| 12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382138313841385138613871388138913901391139213931394139513961397139813991400140114021403140414051406140714081409141014111412141314141415141614171418141914201421142214231424142514261427142814291430143114321433143414351436143714381439144014411442144314441445144614471448144914501451145214531454145514561457145814591460146114621463146414651466146714681469147014711472147314741475147614771478147914801481148214831484148514861487148814891490149114921493149414951496149714981499150015011502150315041505150615071508150915101511151215131514151515161517151815191520152115221523152415251526152715281529153015311532153315341535153615371538153915401541154215431544154515461547154815491550155115521553155415551556155715581559156015611562156315641565156615671568156915701571157215731574157515761577157815791580158115821583158415851586158715881589159015911592159315941595159615971598159916001601160216031604160516061607160816091610161116121613161416151616161716181619162016211622162316241625162616271628162916301631163216331634163516361637163816391640164116421643164416451646164716481649165016511652165316541655165616571658165916601661166216631664166516661667166816691670167116721673167416751676167716781679168016811682168316841685168616871688168916901691169216931694169516961697169816991700170117021703170417051706170717081709171017111712171317141715171617171718171917201721172217231724172517261727172817291730173117321733173417351736173717381739174017411742174317441745174617471748174917501751175217531754175517561757175817591760176117621763176417651766176717681769177017711772177317741775177617771778177917801781178217831784178517861787178817891790179117921793179417951796179717981799180018011802180318041805180618071808180918101811181218131814181518161817181818191820182118221823182418251826182718281829183018311832183318341835183618371838183918401841184218431844184518461847184818491850185118521853185418551856185718581859186018611862186318641865186618671868186918701871187218731874187518761877187818791880188118821883188418851886188718881889189018911892189318941895189618971898189919001901190219031904190519061907190819091910191119121913191419151916191719181919192019211922192319241925192619271928192919301931193219331934193519361937193819391940194119421943194419451946194719481949195019511952195319541955195619571958195919601961196219631964196519661967196819691970197119721973197419751976197719781979198019811982198319841985198619871988198919901991199219931994199519961997199819992000200120022003200420052006200720082009201020112012201320142015201620172018201920202021202220232024202520262027202820292030203120322033203420352036203720382039204020412042204320442045204620472048204920502051205220532054205520562057205820592060206120622063206420652066206720682069207020712072207320742075207620772078207920802081208220832084208520862087208820892090209120922093209420952096209720982099210021012102210321042105210621072108210921102111211221132114211521162117211821192120212121222123212421252126212721282129213021312132213321342135213621372138213921402141214221432144214521462147214821492150215121522153215421552156215721582159216021612162216321642165216621672168216921702171217221732174217521762177217821792180218121822183218421852186218721882189219021912192219321942195219621972198219922002201220222032204220522062207220822092210221122122213221422152216221722182219222022212222222322242225222622272228222922302231223222332234223522362237223822392240224122422243224422452246224722482249225022512252225322542255225622572258225922602261226222632264226522662267226822692270227122722273227422752276227722782279228022812282228322842285228622872288228922902291229222932294229522962297229822992300230123022303230423052306230723082309231023112312231323142315231623172318231923202321232223232324232523262327232823292330233123322333233423352336233723382339234023412342234323442345234623472348234923502351235223532354235523562357235823592360236123622363236423652366236723682369237023712372237323742375237623772378237923802381238223832384238523862387238823892390239123922393239423952396239723982399240024012402240324042405240624072408240924102411241224132414241524162417241824192420242124222423242424252426242724282429243024312432243324342435243624372438243924402441244224432444244524462447244824492450245124522453245424552456245724582459246024612462246324642465246624672468246924702471247224732474247524762477247824792480248124822483248424852486248724882489249024912492249324942495249624972498249925002501250225032504250525062507250825092510251125122513251425152516251725182519252025212522252325242525252625272528252925302531253225332534253525362537253825392540254125422543254425452546254725482549255025512552255325542555255625572558255925602561256225632564256525662567256825692570257125722573257425752576257725782579258025812582258325842585258625872588258925902591259225932594259525962597259825992600260126022603260426052606260726082609261026112612261326142615261626172618261926202621262226232624262526262627262826292630263126322633263426352636263726382639264026412642264326442645264626472648264926502651265226532654265526562657265826592660266126622663266426652666266726682669267026712672267326742675267626772678267926802681268226832684268526862687268826892690269126922693269426952696269726982699270027012702270327042705270627072708270927102711271227132714271527162717271827192720272127222723272427252726272727282729273027312732273327342735273627372738273927402741274227432744274527462747274827492750275127522753275427552756275727582759276027612762276327642765276627672768276927702771277227732774277527762777277827792780278127822783278427852786278727882789279027912792279327942795279627972798279928002801280228032804280528062807280828092810281128122813281428152816281728182819282028212822282328242825282628272828282928302831283228332834283528362837283828392840284128422843284428452846284728482849285028512852285328542855285628572858285928602861286228632864286528662867286828692870287128722873287428752876287728782879288028812882288328842885288628872888288928902891289228932894289528962897289828992900290129022903290429052906290729082909291029112912291329142915291629172918291929202921292229232924292529262927292829292930293129322933293429352936293729382939294029412942294329442945294629472948294929502951295229532954295529562957295829592960296129622963296429652966296729682969297029712972297329742975297629772978297929802981298229832984298529862987298829892990299129922993299429952996299729982999300030013002300330043005300630073008300930103011301230133014301530163017301830193020302130223023302430253026302730283029303030313032303330343035303630373038303930403041304230433044304530463047304830493050305130523053305430553056305730583059306030613062306330643065306630673068306930703071307230733074307530763077307830793080308130823083308430853086308730883089309030913092309330943095309630973098309931003101310231033104310531063107310831093110311131123113311431153116311731183119312031213122312331243125312631273128312931303131313231333134313531363137313831393140314131423143314431453146314731483149315031513152315331543155315631573158315931603161316231633164316531663167316831693170317131723173317431753176317731783179318031813182318331843185318631873188318931903191319231933194319531963197319831993200320132023203320432053206320732083209321032113212321332143215321632173218321932203221322232233224322532263227322832293230323132323233323432353236323732383239324032413242324332443245324632473248324932503251325232533254325532563257325832593260326132623263326432653266326732683269327032713272327332743275327632773278327932803281328232833284328532863287328832893290329132923293329432953296329732983299330033013302330333043305330633073308330933103311331233133314331533163317331833193320332133223323332433253326332733283329333033313332333333343335333633373338333933403341334233433344334533463347334833493350335133523353335433553356335733583359336033613362336333643365336633673368336933703371337233733374337533763377337833793380338133823383338433853386338733883389339033913392339333943395339633973398339934003401340234033404340534063407340834093410341134123413341434153416341734183419342034213422342334243425342634273428342934303431343234333434343534363437343834393440344134423443344434453446344734483449345034513452345334543455345634573458345934603461346234633464346534663467346834693470347134723473347434753476347734783479348034813482348334843485348634873488348934903491349234933494349534963497349834993500350135023503350435053506350735083509351035113512351335143515351635173518351935203521352235233524352535263527352835293530353135323533353435353536353735383539354035413542354335443545354635473548354935503551355235533554355535563557355835593560356135623563356435653566356735683569357035713572357335743575357635773578357935803581358235833584358535863587358835893590359135923593359435953596359735983599360036013602360336043605360636073608360936103611361236133614361536163617361836193620362136223623362436253626362736283629363036313632363336343635363636373638363936403641364236433644364536463647364836493650365136523653365436553656365736583659366036613662366336643665366636673668366936703671367236733674367536763677367836793680368136823683368436853686368736883689369036913692369336943695369636973698369937003701370237033704370537063707370837093710371137123713371437153716371737183719372037213722372337243725372637273728372937303731373237333734373537363737373837393740374137423743374437453746374737483749375037513752375337543755375637573758375937603761376237633764376537663767376837693770377137723773377437753776377737783779378037813782378337843785378637873788378937903791379237933794379537963797379837993800380138023803380438053806380738083809381038113812381338143815381638173818381938203821382238233824382538263827382838293830383138323833383438353836383738383839384038413842384338443845384638473848384938503851385238533854385538563857385838593860386138623863386438653866386738683869387038713872387338743875387638773878387938803881388238833884388538863887388838893890389138923893389438953896389738983899390039013902390339043905390639073908390939103911391239133914391539163917391839193920392139223923392439253926392739283929393039313932393339343935393639373938393939403941394239433944394539463947394839493950395139523953395439553956395739583959396039613962396339643965396639673968396939703971397239733974397539763977397839793980398139823983398439853986398739883989399039913992399339943995399639973998399940004001400240034004400540064007400840094010401140124013401440154016401740184019402040214022402340244025402640274028402940304031403240334034403540364037403840394040404140424043404440454046404740484049405040514052405340544055405640574058405940604061406240634064406540664067406840694070407140724073407440754076407740784079408040814082408340844085408640874088408940904091409240934094409540964097409840994100410141024103410441054106410741084109411041114112411341144115411641174118411941204121412241234124412541264127412841294130413141324133413441354136413741384139414041414142414341444145414641474148414941504151415241534154415541564157415841594160416141624163416441654166416741684169417041714172417341744175417641774178417941804181418241834184418541864187418841894190419141924193419441954196419741984199420042014202420342044205420642074208420942104211421242134214421542164217421842194220422142224223422442254226422742284229423042314232423342344235423642374238423942404241424242434244424542464247424842494250425142524253425442554256425742584259426042614262426342644265426642674268426942704271427242734274427542764277427842794280428142824283428442854286428742884289429042914292429342944295429642974298429943004301430243034304430543064307430843094310431143124313431443154316431743184319432043214322432343244325432643274328432943304331433243334334433543364337433843394340434143424343434443454346434743484349435043514352435343544355435643574358435943604361436243634364436543664367436843694370437143724373437443754376437743784379438043814382438343844385438643874388438943904391439243934394439543964397439843994400440144024403440444054406440744084409441044114412441344144415441644174418441944204421442244234424442544264427442844294430443144324433443444354436443744384439444044414442444344444445444644474448444944504451445244534454445544564457445844594460446144624463446444654466446744684469447044714472447344744475447644774478447944804481448244834484448544864487448844894490449144924493449444954496449744984499450045014502450345044505450645074508450945104511451245134514451545164517451845194520452145224523452445254526452745284529453045314532453345344535453645374538453945404541454245434544454545464547454845494550455145524553455445554556455745584559456045614562456345644565456645674568456945704571457245734574457545764577457845794580458145824583458445854586458745884589459045914592459345944595459645974598459946004601460246034604460546064607460846094610461146124613461446154616461746184619462046214622462346244625462646274628462946304631463246334634463546364637463846394640464146424643464446454646464746484649465046514652465346544655465646574658465946604661466246634664466546664667466846694670467146724673467446754676467746784679468046814682468346844685468646874688468946904691469246934694469546964697469846994700470147024703470447054706470747084709471047114712471347144715471647174718471947204721472247234724472547264727472847294730473147324733473447354736473747384739474047414742474347444745474647474748474947504751475247534754475547564757475847594760476147624763476447654766476747684769477047714772477347744775477647774778477947804781478247834784478547864787478847894790479147924793479447954796479747984799480048014802480348044805480648074808480948104811481248134814481548164817481848194820482148224823482448254826482748284829483048314832483348344835483648374838483948404841484248434844484548464847484848494850485148524853485448554856485748584859486048614862486348644865486648674868486948704871487248734874487548764877487848794880488148824883488448854886488748884889489048914892489348944895489648974898489949004901490249034904490549064907490849094910491149124913491449154916491749184919492049214922492349244925492649274928492949304931493249334934493549364937493849394940494149424943494449454946494749484949495049514952495349544955495649574958495949604961496249634964496549664967496849694970497149724973497449754976497749784979498049814982498349844985498649874988498949904991499249934994499549964997499849995000500150025003500450055006500750085009501050115012501350145015501650175018501950205021502250235024502550265027502850295030503150325033503450355036503750385039504050415042504350445045504650475048504950505051505250535054505550565057505850595060506150625063506450655066506750685069507050715072507350745075507650775078507950805081508250835084508550865087508850895090509150925093509450955096509750985099510051015102510351045105510651075108510951105111511251135114511551165117511851195120512151225123512451255126512751285129513051315132513351345135513651375138513951405141514251435144514551465147514851495150515151525153515451555156515751585159516051615162516351645165516651675168516951705171517251735174517551765177517851795180518151825183518451855186518751885189519051915192519351945195519651975198519952005201520252035204520552065207520852095210521152125213521452155216521752185219522052215222522352245225522652275228522952305231523252335234523552365237523852395240524152425243524452455246524752485249525052515252525352545255525652575258525952605261526252635264526552665267526852695270527152725273527452755276527752785279528052815282528352845285528652875288528952905291529252935294529552965297529852995300530153025303530453055306530753085309531053115312531353145315531653175318531953205321532253235324532553265327532853295330533153325333533453355336533753385339534053415342534353445345534653475348534953505351535253535354535553565357535853595360536153625363536453655366536753685369537053715372537353745375537653775378537953805381538253835384538553865387538853895390539153925393539453955396539753985399540054015402540354045405540654075408540954105411541254135414541554165417541854195420542154225423542454255426542754285429543054315432543354345435543654375438543954405441544254435444544554465447544854495450545154525453545454555456545754585459546054615462546354645465546654675468546954705471547254735474547554765477547854795480548154825483548454855486548754885489549054915492549354945495549654975498549955005501550255035504550555065507550855095510551155125513551455155516551755185519552055215522552355245525552655275528552955305531553255335534553555365537553855395540554155425543554455455546554755485549555055515552555355545555555655575558555955605561556255635564556555665567556855695570557155725573557455755576557755785579558055815582558355845585558655875588558955905591559255935594559555965597559855995600560156025603560456055606560756085609561056115612561356145615561656175618561956205621562256235624562556265627562856295630563156325633563456355636563756385639564056415642564356445645564656475648564956505651565256535654565556565657565856595660566156625663566456655666566756685669567056715672567356745675567656775678567956805681568256835684568556865687568856895690569156925693569456955696569756985699570057015702570357045705570657075708570957105711571257135714571557165717571857195720572157225723572457255726572757285729573057315732573357345735573657375738573957405741574257435744574557465747574857495750575157525753575457555756575757585759576057615762576357645765576657675768576957705771577257735774577557765777577857795780578157825783578457855786578757885789579057915792579357945795579657975798579958005801580258035804580558065807580858095810581158125813581458155816581758185819582058215822582358245825582658275828582958305831583258335834583558365837583858395840584158425843584458455846584758485849585058515852585358545855585658575858585958605861586258635864586558665867586858695870587158725873587458755876587758785879588058815882588358845885588658875888588958905891589258935894589558965897589858995900590159025903590459055906590759085909591059115912591359145915591659175918591959205921592259235924592559265927592859295930593159325933593459355936593759385939594059415942594359445945594659475948594959505951595259535954595559565957595859595960596159625963596459655966596759685969597059715972597359745975597659775978597959805981598259835984598559865987598859895990599159925993599459955996599759985999600060016002600360046005600660076008600960106011601260136014601560166017601860196020602160226023602460256026602760286029603060316032603360346035603660376038603960406041604260436044604560466047604860496050605160526053605460556056605760586059606060616062606360646065606660676068606960706071607260736074607560766077607860796080608160826083608460856086608760886089609060916092609360946095609660976098609961006101610261036104610561066107610861096110611161126113611461156116611761186119612061216122612361246125612661276128612961306131613261336134613561366137613861396140614161426143614461456146614761486149615061516152615361546155615661576158615961606161616261636164616561666167616861696170617161726173617461756176617761786179618061816182618361846185618661876188618961906191619261936194619561966197619861996200620162026203620462056206620762086209621062116212621362146215621662176218621962206221622262236224622562266227622862296230623162326233623462356236623762386239624062416242624362446245624662476248624962506251625262536254625562566257625862596260626162626263626462656266626762686269627062716272627362746275627662776278627962806281628262836284628562866287628862896290629162926293629462956296629762986299630063016302630363046305630663076308630963106311631263136314631563166317631863196320632163226323632463256326632763286329633063316332633363346335633663376338633963406341634263436344634563466347634863496350635163526353635463556356635763586359636063616362636363646365636663676368636963706371637263736374637563766377637863796380638163826383638463856386638763886389639063916392639363946395639663976398639964006401640264036404640564066407640864096410641164126413641464156416641764186419642064216422642364246425642664276428642964306431643264336434643564366437643864396440644164426443644464456446644764486449645064516452645364546455645664576458645964606461646264636464646564666467646864696470647164726473647464756476647764786479648064816482648364846485648664876488648964906491649264936494649564966497649864996500650165026503650465056506650765086509651065116512651365146515651665176518651965206521652265236524652565266527652865296530653165326533653465356536653765386539654065416542654365446545654665476548654965506551655265536554655565566557655865596560656165626563656465656566656765686569657065716572657365746575657665776578657965806581658265836584658565866587658865896590659165926593659465956596659765986599660066016602660366046605660666076608660966106611661266136614661566166617661866196620662166226623662466256626662766286629663066316632663366346635663666376638663966406641664266436644664566466647664866496650665166526653665466556656665766586659666066616662666366646665666666676668666966706671667266736674667566766677667866796680668166826683668466856686668766886689669066916692669366946695669666976698669967006701670267036704670567066707670867096710671167126713671467156716671767186719672067216722672367246725672667276728672967306731673267336734673567366737673867396740674167426743674467456746674767486749675067516752675367546755675667576758675967606761676267636764676567666767676867696770677167726773677467756776677767786779678067816782678367846785678667876788678967906791679267936794679567966797679867996800680168026803680468056806680768086809681068116812681368146815681668176818681968206821682268236824682568266827682868296830683168326833683468356836683768386839684068416842684368446845684668476848684968506851685268536854685568566857685868596860686168626863686468656866686768686869687068716872687368746875687668776878687968806881688268836884688568866887688868896890689168926893689468956896689768986899690069016902690369046905690669076908690969106911691269136914691569166917691869196920692169226923692469256926692769286929693069316932693369346935693669376938693969406941694269436944694569466947694869496950695169526953695469556956695769586959696069616962696369646965696669676968696969706971697269736974697569766977697869796980698169826983698469856986698769886989699069916992699369946995699669976998699970007001700270037004700570067007700870097010701170127013701470157016701770187019702070217022702370247025702670277028702970307031703270337034703570367037703870397040704170427043704470457046704770487049705070517052705370547055705670577058705970607061706270637064706570667067706870697070707170727073707470757076707770787079708070817082708370847085708670877088708970907091709270937094709570967097709870997100710171027103710471057106710771087109711071117112711371147115711671177118711971207121712271237124712571267127712871297130713171327133713471357136713771387139714071417142714371447145714671477148714971507151715271537154715571567157715871597160716171627163716471657166716771687169717071717172717371747175717671777178717971807181718271837184718571867187718871897190719171927193719471957196719771987199720072017202720372047205720672077208720972107211721272137214721572167217721872197220722172227223722472257226722772287229723072317232723372347235723672377238723972407241724272437244724572467247724872497250725172527253725472557256725772587259726072617262726372647265726672677268726972707271727272737274727572767277727872797280728172827283728472857286728772887289729072917292729372947295729672977298729973007301730273037304730573067307730873097310731173127313731473157316731773187319732073217322732373247325732673277328732973307331733273337334733573367337733873397340734173427343734473457346734773487349735073517352735373547355735673577358735973607361736273637364736573667367736873697370737173727373737473757376737773787379738073817382738373847385738673877388738973907391739273937394739573967397739873997400740174027403740474057406740774087409741074117412741374147415741674177418741974207421742274237424742574267427742874297430743174327433743474357436743774387439744074417442744374447445744674477448744974507451745274537454745574567457745874597460746174627463746474657466746774687469747074717472747374747475747674777478747974807481748274837484748574867487748874897490749174927493749474957496749774987499750075017502750375047505750675077508750975107511751275137514751575167517751875197520752175227523752475257526752775287529753075317532753375347535753675377538753975407541754275437544754575467547754875497550755175527553755475557556755775587559756075617562756375647565756675677568756975707571757275737574757575767577757875797580758175827583758475857586758775887589759075917592759375947595759675977598759976007601760276037604760576067607760876097610761176127613761476157616761776187619762076217622762376247625762676277628762976307631763276337634763576367637763876397640764176427643764476457646764776487649765076517652765376547655765676577658765976607661766276637664766576667667766876697670767176727673767476757676767776787679768076817682768376847685768676877688768976907691769276937694769576967697769876997700770177027703770477057706770777087709771077117712771377147715771677177718771977207721772277237724772577267727772877297730773177327733773477357736773777387739774077417742774377447745774677477748774977507751775277537754775577567757775877597760776177627763776477657766776777687769777077717772777377747775777677777778777977807781778277837784778577867787778877897790779177927793779477957796779777987799780078017802780378047805780678077808780978107811781278137814781578167817781878197820782178227823782478257826782778287829783078317832783378347835783678377838783978407841784278437844784578467847784878497850785178527853785478557856785778587859786078617862786378647865786678677868786978707871787278737874787578767877787878797880788178827883788478857886788778887889789078917892789378947895789678977898789979007901790279037904790579067907790879097910791179127913791479157916791779187919792079217922792379247925792679277928792979307931793279337934793579367937793879397940794179427943794479457946794779487949795079517952795379547955795679577958795979607961796279637964796579667967796879697970797179727973797479757976797779787979798079817982798379847985798679877988798979907991799279937994799579967997799879998000800180028003800480058006800780088009801080118012801380148015801680178018801980208021802280238024802580268027802880298030803180328033803480358036803780388039804080418042804380448045804680478048804980508051805280538054805580568057805880598060806180628063806480658066806780688069807080718072807380748075807680778078807980808081808280838084808580868087808880898090809180928093809480958096809780988099810081018102810381048105810681078108810981108111811281138114811581168117811881198120812181228123812481258126812781288129813081318132813381348135813681378138813981408141814281438144814581468147814881498150815181528153815481558156815781588159816081618162816381648165816681678168816981708171817281738174817581768177817881798180818181828183818481858186818781888189819081918192819381948195819681978198819982008201820282038204820582068207820882098210821182128213821482158216821782188219822082218222822382248225822682278228822982308231823282338234823582368237823882398240824182428243824482458246824782488249825082518252825382548255825682578258825982608261826282638264826582668267826882698270827182728273827482758276827782788279828082818282828382848285828682878288828982908291829282938294829582968297829882998300830183028303830483058306830783088309831083118312831383148315831683178318831983208321832283238324832583268327832883298330833183328333833483358336833783388339834083418342834383448345834683478348834983508351835283538354835583568357835883598360836183628363836483658366836783688369837083718372837383748375837683778378837983808381838283838384838583868387838883898390839183928393839483958396839783988399840084018402840384048405840684078408840984108411841284138414841584168417841884198420842184228423842484258426842784288429843084318432843384348435843684378438843984408441844284438444844584468447844884498450845184528453845484558456845784588459846084618462846384648465846684678468846984708471847284738474847584768477847884798480848184828483848484858486848784888489849084918492849384948495849684978498849985008501850285038504850585068507850885098510851185128513851485158516851785188519852085218522852385248525852685278528852985308531853285338534853585368537853885398540854185428543854485458546854785488549855085518552855385548555855685578558855985608561856285638564856585668567856885698570857185728573857485758576857785788579858085818582858385848585858685878588858985908591859285938594859585968597859885998600860186028603860486058606860786088609861086118612861386148615861686178618861986208621862286238624862586268627862886298630863186328633863486358636863786388639864086418642864386448645864686478648864986508651865286538654865586568657865886598660866186628663866486658666866786688669867086718672867386748675867686778678867986808681868286838684868586868687868886898690869186928693869486958696869786988699870087018702870387048705870687078708870987108711871287138714871587168717871887198720872187228723872487258726872787288729873087318732873387348735873687378738873987408741874287438744874587468747874887498750875187528753875487558756875787588759876087618762876387648765876687678768876987708771877287738774877587768777877887798780878187828783878487858786878787888789879087918792879387948795879687978798879988008801880288038804880588068807880888098810881188128813881488158816881788188819882088218822882388248825882688278828882988308831883288338834883588368837883888398840884188428843884488458846884788488849885088518852885388548855885688578858885988608861886288638864886588668867886888698870887188728873887488758876887788788879888088818882888388848885888688878888888988908891889288938894889588968897889888998900890189028903890489058906890789088909891089118912891389148915891689178918891989208921892289238924892589268927892889298930893189328933893489358936893789388939894089418942894389448945894689478948894989508951895289538954895589568957895889598960896189628963896489658966896789688969897089718972897389748975897689778978897989808981898289838984898589868987898889898990899189928993899489958996899789988999900090019002900390049005900690079008900990109011901290139014901590169017901890199020902190229023902490259026902790289029903090319032903390349035903690379038903990409041904290439044904590469047904890499050905190529053905490559056905790589059906090619062906390649065906690679068906990709071907290739074907590769077907890799080908190829083908490859086908790889089909090919092909390949095909690979098909991009101910291039104910591069107910891099110911191129113911491159116911791189119912091219122912391249125912691279128912991309131913291339134913591369137913891399140914191429143914491459146914791489149915091519152915391549155915691579158915991609161916291639164916591669167916891699170917191729173917491759176917791789179918091819182918391849185918691879188918991909191919291939194919591969197919891999200920192029203920492059206920792089209921092119212921392149215921692179218921992209221922292239224922592269227922892299230923192329233923492359236923792389239924092419242924392449245924692479248924992509251925292539254925592569257925892599260926192629263926492659266926792689269927092719272927392749275927692779278927992809281928292839284928592869287928892899290929192929293929492959296929792989299930093019302930393049305930693079308930993109311931293139314931593169317931893199320932193229323932493259326932793289329933093319332933393349335933693379338933993409341934293439344934593469347934893499350935193529353935493559356935793589359936093619362936393649365936693679368936993709371937293739374937593769377937893799380938193829383938493859386938793889389939093919392939393949395939693979398939994009401940294039404940594069407940894099410941194129413941494159416941794189419942094219422942394249425942694279428942994309431943294339434943594369437943894399440944194429443944494459446944794489449945094519452945394549455945694579458945994609461946294639464946594669467946894699470947194729473947494759476947794789479948094819482948394849485948694879488948994909491949294939494949594969497949894999500950195029503950495059506950795089509951095119512951395149515951695179518951995209521952295239524952595269527952895299530953195329533953495359536953795389539954095419542954395449545954695479548954995509551955295539554955595569557955895599560956195629563956495659566956795689569957095719572957395749575957695779578957995809581958295839584958595869587958895899590959195929593959495959596959795989599960096019602960396049605960696079608960996109611961296139614961596169617961896199620962196229623962496259626962796289629963096319632963396349635963696379638963996409641964296439644964596469647964896499650965196529653965496559656965796589659966096619662966396649665966696679668966996709671967296739674967596769677967896799680968196829683968496859686968796889689969096919692969396949695969696979698969997009701970297039704970597069707970897099710971197129713971497159716971797189719972097219722972397249725972697279728972997309731973297339734973597369737973897399740974197429743974497459746974797489749975097519752975397549755975697579758975997609761976297639764976597669767976897699770977197729773977497759776977797789779978097819782978397849785978697879788978997909791979297939794979597969797979897999800980198029803980498059806980798089809981098119812981398149815981698179818981998209821982298239824982598269827982898299830983198329833983498359836983798389839984098419842984398449845984698479848984998509851985298539854985598569857985898599860986198629863986498659866986798689869987098719872987398749875987698779878987998809881988298839884988598869887988898899890989198929893989498959896989798989899990099019902990399049905990699079908990999109911991299139914991599169917991899199920992199229923992499259926992799289929993099319932993399349935993699379938993999409941994299439944994599469947994899499950995199529953995499559956995799589959996099619962996399649965996699679968996999709971997299739974997599769977997899799980998199829983998499859986998799889989999099919992999399949995999699979998999910000100011000210003100041000510006100071000810009100101001110012100131001410015100161001710018100191002010021100221002310024100251002610027100281002910030100311003210033100341003510036100371003810039100401004110042100431004410045100461004710048100491005010051100521005310054100551005610057100581005910060100611006210063100641006510066100671006810069100701007110072100731007410075100761007710078100791008010081100821008310084100851008610087100881008910090100911009210093100941009510096100971009810099101001010110102101031010410105101061010710108101091011010111101121011310114101151011610117101181011910120101211012210123101241012510126101271012810129101301013110132101331013410135101361013710138101391014010141101421014310144101451014610147101481014910150101511015210153101541015510156101571015810159101601016110162101631016410165101661016710168101691017010171101721017310174101751017610177101781017910180101811018210183101841018510186101871018810189101901019110192101931019410195101961019710198101991020010201102021020310204102051020610207102081020910210102111021210213102141021510216102171021810219102201022110222102231022410225102261022710228102291023010231102321023310234102351023610237102381023910240102411024210243102441024510246102471024810249102501025110252102531025410255102561025710258102591026010261102621026310264102651026610267102681026910270102711027210273102741027510276102771027810279102801028110282102831028410285102861028710288102891029010291102921029310294102951029610297102981029910300103011030210303103041030510306103071030810309103101031110312103131031410315103161031710318103191032010321103221032310324103251032610327103281032910330103311033210333103341033510336103371033810339103401034110342103431034410345103461034710348103491035010351103521035310354103551035610357103581035910360103611036210363103641036510366103671036810369103701037110372103731037410375103761037710378103791038010381103821038310384103851038610387103881038910390103911039210393103941039510396103971039810399104001040110402104031040410405104061040710408104091041010411104121041310414104151041610417104181041910420104211042210423104241042510426104271042810429104301043110432104331043410435104361043710438104391044010441104421044310444104451044610447104481044910450104511045210453104541045510456104571045810459104601046110462104631046410465104661046710468104691047010471104721047310474104751047610477104781047910480104811048210483104841048510486104871048810489104901049110492104931049410495104961049710498104991050010501105021050310504105051050610507105081050910510105111051210513105141051510516105171051810519105201052110522105231052410525105261052710528105291053010531105321053310534105351053610537105381053910540105411054210543105441054510546105471054810549105501055110552105531055410555105561055710558105591056010561105621056310564105651056610567105681056910570105711057210573105741057510576105771057810579105801058110582105831058410585105861058710588105891059010591105921059310594105951059610597105981059910600106011060210603106041060510606106071060810609106101061110612106131061410615106161061710618106191062010621106221062310624106251062610627106281062910630106311063210633106341063510636106371063810639106401064110642106431064410645106461064710648106491065010651106521065310654106551065610657106581065910660106611066210663106641066510666106671066810669106701067110672106731067410675106761067710678106791068010681106821068310684106851068610687106881068910690106911069210693106941069510696106971069810699107001070110702107031070410705107061070710708107091071010711107121071310714107151071610717107181071910720107211072210723107241072510726107271072810729107301073110732107331073410735107361073710738107391074010741107421074310744107451074610747107481074910750107511075210753107541075510756107571075810759107601076110762107631076410765107661076710768107691077010771107721077310774107751077610777107781077910780107811078210783107841078510786107871078810789107901079110792107931079410795107961079710798107991080010801108021080310804108051080610807108081080910810108111081210813108141081510816108171081810819108201082110822108231082410825108261082710828108291083010831108321083310834108351083610837108381083910840108411084210843108441084510846108471084810849108501085110852108531085410855108561085710858108591086010861108621086310864108651086610867108681086910870108711087210873108741087510876108771087810879108801088110882108831088410885108861088710888108891089010891108921089310894108951089610897108981089910900109011090210903109041090510906109071090810909109101091110912109131091410915109161091710918109191092010921109221092310924109251092610927109281092910930109311093210933109341093510936109371093810939109401094110942109431094410945109461094710948109491095010951109521095310954109551095610957109581095910960109611096210963109641096510966109671096810969109701097110972109731097410975109761097710978109791098010981109821098310984109851098610987109881098910990109911099210993109941099510996109971099810999110001100111002110031100411005110061100711008110091101011011110121101311014110151101611017110181101911020110211102211023110241102511026110271102811029110301103111032110331103411035110361103711038110391104011041110421104311044110451104611047110481104911050110511105211053110541105511056110571105811059110601106111062110631106411065110661106711068110691107011071110721107311074110751107611077110781107911080110811108211083110841108511086110871108811089110901109111092110931109411095110961109711098110991110011101111021110311104111051110611107111081110911110111111111211113111141111511116111171111811119111201112111122111231112411125111261112711128111291113011131111321113311134111351113611137111381113911140111411114211143111441114511146111471114811149111501115111152111531115411155111561115711158111591116011161111621116311164111651116611167111681116911170111711117211173111741117511176111771117811179111801118111182111831118411185111861118711188111891119011191111921119311194111951119611197111981119911200112011120211203112041120511206112071120811209112101121111212112131121411215112161121711218112191122011221112221122311224112251122611227112281122911230112311123211233112341123511236112371123811239112401124111242112431124411245112461124711248112491125011251112521125311254112551125611257112581125911260112611126211263112641126511266112671126811269112701127111272112731127411275112761127711278112791128011281112821128311284112851128611287112881128911290112911129211293112941129511296112971129811299113001130111302113031130411305113061130711308113091131011311113121131311314113151131611317113181131911320113211132211323113241132511326113271132811329113301133111332113331133411335113361133711338113391134011341113421134311344113451134611347113481134911350113511135211353113541135511356113571135811359113601136111362113631136411365113661136711368113691137011371113721137311374113751137611377113781137911380113811138211383113841138511386113871138811389113901139111392113931139411395113961139711398113991140011401114021140311404114051140611407114081140911410114111141211413114141141511416114171141811419114201142111422114231142411425114261142711428114291143011431114321143311434114351143611437114381143911440114411144211443114441144511446114471144811449114501145111452114531145411455114561145711458114591146011461114621146311464114651146611467114681146911470114711147211473114741147511476114771147811479114801148111482114831148411485114861148711488114891149011491114921149311494114951149611497114981149911500115011150211503115041150511506115071150811509115101151111512115131151411515115161151711518115191152011521115221152311524115251152611527115281152911530115311153211533115341153511536115371153811539115401154111542115431154411545115461154711548115491155011551115521155311554115551155611557115581155911560115611156211563115641156511566115671156811569115701157111572115731157411575115761157711578115791158011581115821158311584115851158611587115881158911590115911159211593115941159511596115971159811599116001160111602116031160411605116061160711608116091161011611116121161311614116151161611617116181161911620116211162211623116241162511626116271162811629116301163111632116331163411635116361163711638116391164011641116421164311644116451164611647116481164911650116511165211653116541165511656116571165811659116601166111662116631166411665116661166711668116691167011671116721167311674116751167611677116781167911680116811168211683116841168511686116871168811689116901169111692116931169411695116961169711698116991170011701117021170311704117051170611707117081170911710117111171211713117141171511716117171171811719117201172111722117231172411725117261172711728117291173011731117321173311734117351173611737117381173911740117411174211743117441174511746117471174811749117501175111752117531175411755117561175711758117591176011761117621176311764117651176611767117681176911770117711177211773117741177511776117771177811779117801178111782117831178411785117861178711788117891179011791117921179311794117951179611797117981179911800118011180211803118041180511806118071180811809118101181111812118131181411815118161181711818118191182011821118221182311824118251182611827118281182911830118311183211833118341183511836118371183811839118401184111842118431184411845118461184711848118491185011851118521185311854118551185611857118581185911860118611186211863118641186511866118671186811869118701187111872118731187411875118761187711878118791188011881118821188311884118851188611887118881188911890118911189211893118941189511896118971189811899119001190111902119031190411905119061190711908119091191011911119121191311914119151191611917119181191911920119211192211923119241192511926119271192811929119301193111932119331193411935119361193711938119391194011941119421194311944119451194611947119481194911950119511195211953119541195511956119571195811959119601196111962119631196411965119661196711968119691197011971119721197311974119751197611977119781197911980119811198211983119841198511986119871198811989119901199111992119931199411995119961199711998119991200012001120021200312004120051200612007120081200912010120111201212013120141201512016120171201812019120201202112022120231202412025120261202712028120291203012031120321203312034120351203612037120381203912040120411204212043120441204512046120471204812049120501205112052120531205412055120561205712058120591206012061120621206312064120651206612067120681206912070120711207212073120741207512076120771207812079120801208112082120831208412085120861208712088120891209012091120921209312094120951209612097120981209912100121011210212103121041210512106121071210812109121101211112112121131211412115121161211712118121191212012121121221212312124121251212612127121281212912130121311213212133121341213512136121371213812139121401214112142121431214412145121461214712148121491215012151121521215312154121551215612157121581215912160121611216212163121641216512166121671216812169121701217112172121731217412175121761217712178121791218012181121821218312184121851218612187121881218912190121911219212193121941219512196121971219812199122001220112202122031220412205122061220712208122091221012211122121221312214122151221612217122181221912220122211222212223122241222512226122271222812229122301223112232122331223412235122361223712238122391224012241122421224312244122451224612247122481224912250122511225212253122541225512256122571225812259122601226112262122631226412265122661226712268122691227012271122721227312274122751227612277122781227912280122811228212283122841228512286122871228812289122901229112292122931229412295122961229712298122991230012301123021230312304123051230612307123081230912310123111231212313123141231512316123171231812319123201232112322123231232412325123261232712328123291233012331123321233312334123351233612337123381233912340123411234212343123441234512346123471234812349123501235112352123531235412355123561235712358123591236012361123621236312364123651236612367123681236912370123711237212373123741237512376123771237812379123801238112382123831238412385123861238712388123891239012391123921239312394123951239612397123981239912400124011240212403124041240512406124071240812409124101241112412124131241412415124161241712418124191242012421124221242312424124251242612427124281242912430124311243212433124341243512436124371243812439124401244112442124431244412445124461244712448124491245012451124521245312454124551245612457124581245912460124611246212463124641246512466124671246812469124701247112472124731247412475124761247712478124791248012481124821248312484124851248612487124881248912490124911249212493124941249512496124971249812499125001250112502125031250412505125061250712508125091251012511125121251312514125151251612517125181251912520125211252212523125241252512526125271252812529125301253112532125331253412535125361253712538125391254012541125421254312544125451254612547125481254912550125511255212553125541255512556125571255812559125601256112562125631256412565125661256712568125691257012571125721257312574125751257612577125781257912580125811258212583125841258512586125871258812589125901259112592125931259412595125961259712598125991260012601126021260312604126051260612607126081260912610126111261212613126141261512616126171261812619126201262112622126231262412625126261262712628126291263012631126321263312634126351263612637126381263912640126411264212643126441264512646126471264812649126501265112652126531265412655126561265712658126591266012661126621266312664126651266612667126681266912670126711267212673126741267512676126771267812679126801268112682126831268412685126861268712688126891269012691126921269312694126951269612697126981269912700127011270212703127041270512706127071270812709127101271112712127131271412715127161271712718127191272012721127221272312724127251272612727127281272912730127311273212733127341273512736127371273812739127401274112742127431274412745127461274712748127491275012751127521275312754127551275612757127581275912760127611276212763127641276512766127671276812769127701277112772127731277412775127761277712778127791278012781127821278312784127851278612787127881278912790127911279212793127941279512796127971279812799128001280112802128031280412805128061280712808128091281012811128121281312814128151281612817128181281912820128211282212823128241282512826128271282812829128301283112832128331283412835128361283712838128391284012841128421284312844128451284612847128481284912850128511285212853128541285512856128571285812859128601286112862128631286412865128661286712868128691287012871128721287312874128751287612877128781287912880128811288212883128841288512886128871288812889128901289112892128931289412895128961289712898128991290012901129021290312904129051290612907129081290912910129111291212913129141291512916129171291812919129201292112922129231292412925129261292712928129291293012931129321293312934129351293612937129381293912940129411294212943129441294512946129471294812949129501295112952129531295412955129561295712958129591296012961129621296312964129651296612967129681296912970129711297212973129741297512976129771297812979129801298112982129831298412985129861298712988129891299012991129921299312994129951299612997129981299913000130011300213003130041300513006130071300813009130101301113012130131301413015130161301713018130191302013021130221302313024130251302613027130281302913030130311303213033130341303513036130371303813039130401304113042130431304413045130461304713048130491305013051130521305313054130551305613057130581305913060130611306213063130641306513066130671306813069130701307113072130731307413075130761307713078130791308013081130821308313084130851308613087130881308913090130911309213093130941309513096130971309813099131001310113102131031310413105131061310713108131091311013111131121311313114131151311613117131181311913120131211312213123131241312513126131271312813129131301313113132131331313413135131361313713138131391314013141131421314313144131451314613147131481314913150131511315213153131541315513156131571315813159131601316113162131631316413165131661316713168131691317013171131721317313174131751317613177131781317913180131811318213183131841318513186131871318813189131901319113192131931319413195131961319713198131991320013201132021320313204132051320613207132081320913210132111321213213132141321513216132171321813219132201322113222132231322413225132261322713228132291323013231132321323313234132351323613237132381323913240132411324213243132441324513246132471324813249132501325113252132531325413255132561325713258132591326013261132621326313264132651326613267132681326913270132711327213273132741327513276132771327813279132801328113282132831328413285132861328713288132891329013291132921329313294132951329613297132981329913300133011330213303133041330513306133071330813309133101331113312133131331413315133161331713318133191332013321133221332313324133251332613327133281332913330133311333213333133341333513336133371333813339133401334113342133431334413345133461334713348133491335013351133521335313354133551335613357133581335913360133611336213363133641336513366133671336813369133701337113372133731337413375133761337713378133791338013381133821338313384133851338613387133881338913390133911339213393133941339513396133971339813399134001340113402134031340413405134061340713408134091341013411134121341313414134151341613417134181341913420134211342213423134241342513426134271342813429134301343113432134331343413435134361343713438134391344013441134421344313444134451344613447134481344913450134511345213453134541345513456134571345813459134601346113462134631346413465134661346713468134691347013471134721347313474134751347613477134781347913480134811348213483134841348513486134871348813489134901349113492134931349413495134961349713498134991350013501135021350313504135051350613507135081350913510135111351213513135141351513516135171351813519135201352113522135231352413525135261352713528135291353013531135321353313534135351353613537135381353913540135411354213543135441354513546135471354813549135501355113552135531355413555135561355713558135591356013561135621356313564135651356613567135681356913570135711357213573135741357513576135771357813579135801358113582135831358413585135861358713588135891359013591135921359313594135951359613597135981359913600136011360213603136041360513606136071360813609136101361113612136131361413615136161361713618136191362013621136221362313624136251362613627136281362913630136311363213633136341363513636136371363813639136401364113642136431364413645136461364713648136491365013651136521365313654136551365613657136581365913660136611366213663136641366513666136671366813669136701367113672136731367413675136761367713678136791368013681136821368313684136851368613687136881368913690136911369213693136941369513696136971369813699137001370113702137031370413705137061370713708137091371013711137121371313714137151371613717137181371913720137211372213723137241372513726137271372813729137301373113732137331373413735137361373713738137391374013741137421374313744137451374613747137481374913750137511375213753137541375513756137571375813759137601376113762137631376413765137661376713768137691377013771137721377313774137751377613777137781377913780137811378213783137841378513786137871378813789137901379113792137931379413795137961379713798137991380013801138021380313804138051380613807138081380913810138111381213813138141381513816138171381813819138201382113822138231382413825138261382713828138291383013831138321383313834138351383613837138381383913840138411384213843138441384513846138471384813849138501385113852138531385413855138561385713858138591386013861138621386313864138651386613867138681386913870138711387213873138741387513876138771387813879138801388113882138831388413885138861388713888138891389013891138921389313894138951389613897138981389913900139011390213903139041390513906139071390813909139101391113912139131391413915139161391713918139191392013921139221392313924139251392613927139281392913930139311393213933139341393513936139371393813939139401394113942139431394413945139461394713948139491395013951139521395313954139551395613957139581395913960139611396213963139641396513966139671396813969139701397113972139731397413975139761397713978139791398013981139821398313984139851398613987139881398913990139911399213993139941399513996139971399813999140001400114002140031400414005140061400714008140091401014011140121401314014140151401614017140181401914020140211402214023140241402514026140271402814029140301403114032140331403414035140361403714038140391404014041140421404314044140451404614047140481404914050140511405214053140541405514056140571405814059140601406114062140631406414065140661406714068140691407014071140721407314074140751407614077140781407914080140811408214083140841408514086140871408814089140901409114092140931409414095140961409714098140991410014101141021410314104141051410614107141081410914110141111411214113141141411514116141171411814119141201412114122141231412414125141261412714128141291413014131141321413314134141351413614137141381413914140141411414214143141441414514146141471414814149141501415114152141531415414155141561415714158141591416014161141621416314164141651416614167141681416914170141711417214173141741417514176141771417814179141801418114182141831418414185141861418714188141891419014191141921419314194141951419614197141981419914200142011420214203142041420514206142071420814209142101421114212142131421414215142161421714218142191422014221142221422314224142251422614227142281422914230142311423214233142341423514236142371423814239142401424114242142431424414245142461424714248142491425014251142521425314254142551425614257142581425914260142611426214263142641426514266142671426814269142701427114272142731427414275142761427714278142791428014281142821428314284142851428614287142881428914290142911429214293142941429514296142971429814299143001430114302143031430414305143061430714308143091431014311143121431314314143151431614317143181431914320143211432214323143241432514326143271432814329143301433114332143331433414335143361433714338143391434014341143421434314344143451434614347143481434914350143511435214353143541435514356143571435814359143601436114362143631436414365143661436714368143691437014371143721437314374143751437614377143781437914380143811438214383143841438514386143871438814389143901439114392143931439414395143961439714398143991440014401144021440314404144051440614407144081440914410144111441214413144141441514416144171441814419144201442114422144231442414425144261442714428144291443014431144321443314434144351443614437144381443914440144411444214443144441444514446144471444814449144501445114452144531445414455144561445714458144591446014461144621446314464144651446614467144681446914470144711447214473144741447514476144771447814479144801448114482144831448414485144861448714488144891449014491144921449314494144951449614497144981449914500145011450214503145041450514506145071450814509145101451114512145131451414515145161451714518145191452014521145221452314524145251452614527145281452914530145311453214533145341453514536145371453814539145401454114542145431454414545145461454714548145491455014551145521455314554145551455614557145581455914560145611456214563145641456514566145671456814569145701457114572145731457414575145761457714578145791458014581145821458314584145851458614587145881458914590145911459214593145941459514596145971459814599146001460114602146031460414605146061460714608146091461014611146121461314614146151461614617146181461914620146211462214623146241462514626146271462814629146301463114632146331463414635146361463714638146391464014641146421464314644146451464614647146481464914650146511465214653146541465514656146571465814659146601466114662146631466414665146661466714668146691467014671146721467314674146751467614677146781467914680146811468214683146841468514686146871468814689146901469114692146931469414695146961469714698146991470014701147021470314704147051470614707147081470914710147111471214713147141471514716147171471814719147201472114722147231472414725147261472714728147291473014731147321473314734147351473614737147381473914740147411474214743147441474514746147471474814749147501475114752147531475414755147561475714758147591476014761147621476314764147651476614767147681476914770147711477214773147741477514776147771477814779147801478114782147831478414785147861478714788147891479014791147921479314794147951479614797147981479914800148011480214803148041480514806148071480814809148101481114812148131481414815148161481714818148191482014821148221482314824148251482614827148281482914830148311483214833148341483514836148371483814839148401484114842148431484414845148461484714848148491485014851148521485314854148551485614857148581485914860148611486214863148641486514866148671486814869148701487114872148731487414875148761487714878148791488014881148821488314884148851488614887148881488914890148911489214893148941489514896148971489814899149001490114902149031490414905149061490714908149091491014911149121491314914149151491614917149181491914920149211492214923149241492514926149271492814929149301493114932149331493414935149361493714938149391494014941149421494314944149451494614947149481494914950149511495214953149541495514956149571495814959149601496114962149631496414965149661496714968149691497014971149721497314974149751497614977149781497914980149811498214983149841498514986149871498814989149901499114992149931499414995149961499714998149991500015001150021500315004150051500615007150081500915010150111501215013150141501515016150171501815019150201502115022150231502415025150261502715028150291503015031150321503315034150351503615037150381503915040150411504215043150441504515046150471504815049150501505115052150531505415055150561505715058150591506015061150621506315064150651506615067150681506915070150711507215073150741507515076150771507815079150801508115082150831508415085150861508715088150891509015091150921509315094150951509615097150981509915100151011510215103151041510515106151071510815109151101511115112151131511415115151161511715118151191512015121151221512315124151251512615127151281512915130151311513215133151341513515136151371513815139151401514115142151431514415145151461514715148151491515015151151521515315154151551515615157151581515915160151611516215163151641516515166151671516815169151701517115172151731517415175151761517715178151791518015181151821518315184151851518615187151881518915190151911519215193151941519515196151971519815199152001520115202152031520415205152061520715208152091521015211152121521315214152151521615217152181521915220152211522215223152241522515226152271522815229152301523115232152331523415235152361523715238152391524015241152421524315244152451524615247152481524915250152511525215253152541525515256152571525815259152601526115262152631526415265152661526715268152691527015271152721527315274152751527615277152781527915280152811528215283152841528515286152871528815289152901529115292152931529415295152961529715298152991530015301153021530315304153051530615307153081530915310153111531215313153141531515316153171531815319153201532115322153231532415325153261532715328153291533015331153321533315334153351533615337153381533915340153411534215343153441534515346153471534815349153501535115352153531535415355153561535715358153591536015361153621536315364153651536615367153681536915370153711537215373153741537515376153771537815379153801538115382153831538415385153861538715388153891539015391153921539315394153951539615397153981539915400154011540215403154041540515406154071540815409154101541115412154131541415415154161541715418154191542015421154221542315424154251542615427154281542915430154311543215433154341543515436154371543815439154401544115442154431544415445154461544715448154491545015451154521545315454154551545615457154581545915460154611546215463154641546515466154671546815469154701547115472154731547415475154761547715478154791548015481154821548315484154851548615487154881548915490154911549215493154941549515496154971549815499155001550115502155031550415505155061550715508155091551015511155121551315514155151551615517155181551915520155211552215523155241552515526155271552815529155301553115532155331553415535155361553715538155391554015541155421554315544155451554615547155481554915550155511555215553155541555515556155571555815559155601556115562155631556415565155661556715568155691557015571155721557315574155751557615577155781557915580155811558215583155841558515586155871558815589155901559115592155931559415595155961559715598155991560015601156021560315604156051560615607156081560915610156111561215613156141561515616156171561815619156201562115622156231562415625156261562715628156291563015631156321563315634156351563615637156381563915640156411564215643156441564515646156471564815649156501565115652156531565415655156561565715658156591566015661156621566315664156651566615667156681566915670156711567215673156741567515676156771567815679156801568115682156831568415685156861568715688156891569015691156921569315694156951569615697156981569915700157011570215703157041570515706157071570815709157101571115712157131571415715157161571715718157191572015721157221572315724157251572615727157281572915730157311573215733157341573515736157371573815739157401574115742157431574415745157461574715748157491575015751157521575315754157551575615757157581575915760157611576215763157641576515766157671576815769157701577115772157731577415775157761577715778157791578015781157821578315784157851578615787157881578915790157911579215793157941579515796157971579815799158001580115802158031580415805158061580715808158091581015811158121581315814158151581615817158181581915820158211582215823158241582515826158271582815829158301583115832158331583415835158361583715838158391584015841158421584315844158451584615847158481584915850158511585215853158541585515856158571585815859158601586115862158631586415865158661586715868158691587015871158721587315874158751587615877158781587915880158811588215883158841588515886158871588815889158901589115892158931589415895158961589715898158991590015901159021590315904159051590615907159081590915910159111591215913159141591515916159171591815919159201592115922159231592415925159261592715928159291593015931159321593315934159351593615937159381593915940159411594215943159441594515946159471594815949159501595115952159531595415955159561595715958159591596015961159621596315964159651596615967159681596915970159711597215973159741597515976159771597815979159801598115982159831598415985159861598715988159891599015991159921599315994159951599615997159981599916000160011600216003160041600516006160071600816009160101601116012160131601416015160161601716018160191602016021160221602316024160251602616027160281602916030160311603216033160341603516036160371603816039160401604116042160431604416045160461604716048160491605016051160521605316054160551605616057160581605916060160611606216063160641606516066160671606816069160701607116072160731607416075160761607716078160791608016081160821608316084160851608616087160881608916090160911609216093160941609516096160971609816099161001610116102161031610416105161061610716108161091611016111161121611316114161151611616117161181611916120161211612216123161241612516126161271612816129161301613116132161331613416135161361613716138161391614016141161421614316144161451614616147161481614916150161511615216153161541615516156161571615816159161601616116162161631616416165161661616716168161691617016171161721617316174161751617616177161781617916180161811618216183161841618516186161871618816189161901619116192161931619416195161961619716198161991620016201162021620316204162051620616207162081620916210162111621216213162141621516216162171621816219162201622116222162231622416225162261622716228162291623016231162321623316234162351623616237162381623916240162411624216243162441624516246162471624816249162501625116252162531625416255162561625716258162591626016261162621626316264162651626616267162681626916270162711627216273162741627516276162771627816279162801628116282162831628416285162861628716288162891629016291162921629316294162951629616297162981629916300163011630216303163041630516306163071630816309163101631116312163131631416315163161631716318163191632016321163221632316324163251632616327163281632916330163311633216333163341633516336163371633816339163401634116342163431634416345163461634716348163491635016351163521635316354163551635616357163581635916360163611636216363163641636516366163671636816369163701637116372163731637416375163761637716378163791638016381163821638316384163851638616387163881638916390163911639216393163941639516396163971639816399164001640116402164031640416405164061640716408164091641016411164121641316414164151641616417164181641916420164211642216423164241642516426164271642816429164301643116432164331643416435164361643716438164391644016441164421644316444164451644616447164481644916450164511645216453164541645516456164571645816459164601646116462164631646416465164661646716468164691647016471164721647316474164751647616477164781647916480164811648216483164841648516486164871648816489164901649116492164931649416495164961649716498164991650016501165021650316504165051650616507165081650916510165111651216513165141651516516165171651816519165201652116522165231652416525165261652716528165291653016531165321653316534165351653616537165381653916540165411654216543165441654516546165471654816549165501655116552165531655416555165561655716558165591656016561165621656316564165651656616567165681656916570165711657216573165741657516576165771657816579165801658116582165831658416585165861658716588165891659016591165921659316594165951659616597165981659916600166011660216603166041660516606166071660816609166101661116612166131661416615166161661716618166191662016621166221662316624166251662616627166281662916630166311663216633166341663516636166371663816639166401664116642166431664416645166461664716648166491665016651166521665316654166551665616657166581665916660166611666216663166641666516666166671666816669166701667116672166731667416675166761667716678166791668016681166821668316684166851668616687166881668916690166911669216693166941669516696166971669816699167001670116702167031670416705167061670716708167091671016711167121671316714167151671616717167181671916720167211672216723167241672516726167271672816729167301673116732167331673416735167361673716738167391674016741167421674316744167451674616747167481674916750167511675216753167541675516756167571675816759167601676116762167631676416765167661676716768167691677016771167721677316774167751677616777167781677916780167811678216783167841678516786167871678816789167901679116792167931679416795167961679716798167991680016801168021680316804168051680616807168081680916810168111681216813168141681516816168171681816819168201682116822168231682416825168261682716828168291683016831168321683316834168351683616837168381683916840168411684216843168441684516846168471684816849168501685116852168531685416855168561685716858168591686016861168621686316864168651686616867168681686916870168711687216873168741687516876168771687816879168801688116882168831688416885168861688716888168891689016891168921689316894168951689616897168981689916900169011690216903169041690516906169071690816909169101691116912169131691416915169161691716918169191692016921169221692316924169251692616927169281692916930169311693216933169341693516936169371693816939169401694116942169431694416945169461694716948169491695016951169521695316954169551695616957169581695916960169611696216963169641696516966169671696816969169701697116972169731697416975169761697716978169791698016981169821698316984169851698616987169881698916990169911699216993169941699516996169971699816999170001700117002170031700417005170061700717008170091701017011170121701317014170151701617017170181701917020170211702217023170241702517026170271702817029170301703117032170331703417035170361703717038170391704017041170421704317044170451704617047170481704917050170511705217053170541705517056170571705817059170601706117062170631706417065170661706717068170691707017071170721707317074170751707617077170781707917080170811708217083170841708517086170871708817089170901709117092170931709417095170961709717098170991710017101171021710317104171051710617107171081710917110171111711217113171141711517116171171711817119171201712117122171231712417125171261712717128171291713017131171321713317134171351713617137171381713917140171411714217143171441714517146171471714817149171501715117152171531715417155171561715717158171591716017161171621716317164171651716617167171681716917170171711717217173171741717517176171771717817179171801718117182171831718417185171861718717188171891719017191171921719317194171951719617197171981719917200172011720217203172041720517206172071720817209172101721117212172131721417215172161721717218172191722017221172221722317224172251722617227172281722917230172311723217233172341723517236172371723817239172401724117242172431724417245172461724717248172491725017251172521725317254172551725617257172581725917260172611726217263172641726517266172671726817269172701727117272172731727417275172761727717278172791728017281172821728317284172851728617287172881728917290172911729217293172941729517296172971729817299173001730117302173031730417305173061730717308173091731017311173121731317314173151731617317173181731917320173211732217323173241732517326173271732817329173301733117332173331733417335173361733717338173391734017341173421734317344173451734617347173481734917350173511735217353173541735517356173571735817359173601736117362173631736417365173661736717368173691737017371173721737317374173751737617377173781737917380173811738217383173841738517386173871738817389173901739117392173931739417395173961739717398173991740017401174021740317404174051740617407174081740917410174111741217413174141741517416174171741817419174201742117422174231742417425174261742717428174291743017431174321743317434174351743617437174381743917440174411744217443174441744517446174471744817449174501745117452174531745417455174561745717458174591746017461174621746317464174651746617467174681746917470174711747217473174741747517476174771747817479174801748117482174831748417485174861748717488174891749017491174921749317494174951749617497174981749917500175011750217503175041750517506175071750817509175101751117512175131751417515175161751717518175191752017521175221752317524175251752617527175281752917530175311753217533175341753517536175371753817539175401754117542175431754417545175461754717548175491755017551175521755317554175551755617557175581755917560175611756217563175641756517566175671756817569175701757117572175731757417575175761757717578175791758017581175821758317584175851758617587175881758917590175911759217593175941759517596175971759817599176001760117602176031760417605176061760717608176091761017611176121761317614176151761617617176181761917620176211762217623176241762517626176271762817629176301763117632176331763417635176361763717638176391764017641176421764317644176451764617647176481764917650176511765217653176541765517656176571765817659176601766117662176631766417665176661766717668176691767017671176721767317674176751767617677176781767917680176811768217683176841768517686176871768817689176901769117692176931769417695176961769717698176991770017701177021770317704177051770617707177081770917710177111771217713177141771517716177171771817719177201772117722177231772417725177261772717728177291773017731177321773317734177351773617737177381773917740177411774217743177441774517746177471774817749177501775117752177531775417755177561775717758177591776017761177621776317764177651776617767177681776917770177711777217773177741777517776177771777817779177801778117782177831778417785177861778717788177891779017791177921779317794177951779617797177981779917800178011780217803178041780517806178071780817809178101781117812178131781417815178161781717818178191782017821178221782317824178251782617827178281782917830178311783217833178341783517836178371783817839178401784117842178431784417845178461784717848178491785017851178521785317854178551785617857178581785917860178611786217863178641786517866178671786817869178701787117872178731787417875178761787717878178791788017881178821788317884178851788617887178881788917890178911789217893178941789517896178971789817899179001790117902179031790417905179061790717908179091791017911179121791317914179151791617917179181791917920179211792217923179241792517926179271792817929179301793117932179331793417935179361793717938179391794017941179421794317944179451794617947179481794917950179511795217953179541795517956179571795817959179601796117962179631796417965179661796717968179691797017971179721797317974179751797617977179781797917980179811798217983179841798517986179871798817989179901799117992179931799417995179961799717998179991800018001180021800318004180051800618007180081800918010180111801218013180141801518016180171801818019180201802118022180231802418025180261802718028180291803018031180321803318034180351803618037180381803918040180411804218043180441804518046180471804818049180501805118052180531805418055180561805718058180591806018061180621806318064180651806618067180681806918070180711807218073180741807518076180771807818079180801808118082180831808418085180861808718088180891809018091180921809318094180951809618097180981809918100181011810218103181041810518106181071810818109181101811118112181131811418115181161811718118181191812018121181221812318124181251812618127181281812918130181311813218133181341813518136181371813818139181401814118142181431814418145181461814718148181491815018151181521815318154181551815618157181581815918160181611816218163181641816518166181671816818169181701817118172181731817418175181761817718178181791818018181181821818318184181851818618187181881818918190181911819218193181941819518196181971819818199182001820118202182031820418205182061820718208182091821018211182121821318214182151821618217182181821918220182211822218223182241822518226182271822818229182301823118232182331823418235182361823718238182391824018241182421824318244182451824618247182481824918250182511825218253182541825518256182571825818259182601826118262182631826418265182661826718268182691827018271182721827318274182751827618277182781827918280182811828218283182841828518286182871828818289182901829118292182931829418295182961829718298182991830018301183021830318304183051830618307183081830918310183111831218313183141831518316183171831818319183201832118322183231832418325183261832718328183291833018331183321833318334183351833618337183381833918340183411834218343183441834518346183471834818349183501835118352183531835418355183561835718358183591836018361183621836318364183651836618367183681836918370183711837218373183741837518376183771837818379183801838118382183831838418385183861838718388183891839018391183921839318394183951839618397183981839918400184011840218403184041840518406184071840818409184101841118412184131841418415184161841718418184191842018421184221842318424184251842618427184281842918430184311843218433184341843518436184371843818439184401844118442184431844418445184461844718448184491845018451184521845318454184551845618457184581845918460184611846218463184641846518466184671846818469184701847118472184731847418475184761847718478184791848018481184821848318484184851848618487184881848918490184911849218493184941849518496184971849818499185001850118502185031850418505185061850718508185091851018511185121851318514185151851618517185181851918520185211852218523185241852518526185271852818529185301853118532185331853418535185361853718538185391854018541185421854318544185451854618547185481854918550185511855218553185541855518556185571855818559185601856118562185631856418565185661856718568185691857018571185721857318574185751857618577185781857918580185811858218583185841858518586185871858818589185901859118592185931859418595185961859718598185991860018601186021860318604186051860618607186081860918610186111861218613186141861518616186171861818619186201862118622186231862418625186261862718628186291863018631186321863318634186351863618637186381863918640186411864218643186441864518646186471864818649186501865118652186531865418655186561865718658186591866018661186621866318664186651866618667186681866918670186711867218673186741867518676186771867818679186801868118682186831868418685186861868718688186891869018691186921869318694186951869618697186981869918700187011870218703187041870518706187071870818709187101871118712187131871418715187161871718718187191872018721187221872318724187251872618727187281872918730187311873218733187341873518736187371873818739187401874118742187431874418745187461874718748187491875018751187521875318754187551875618757187581875918760187611876218763187641876518766187671876818769187701877118772187731877418775187761877718778187791878018781187821878318784187851878618787187881878918790187911879218793187941879518796187971879818799188001880118802188031880418805188061880718808188091881018811188121881318814188151881618817188181881918820188211882218823188241882518826188271882818829188301883118832188331883418835188361883718838188391884018841188421884318844188451884618847188481884918850188511885218853188541885518856188571885818859188601886118862188631886418865188661886718868188691887018871188721887318874188751887618877188781887918880188811888218883188841888518886188871888818889188901889118892188931889418895188961889718898188991890018901189021890318904189051890618907189081890918910189111891218913189141891518916189171891818919189201892118922189231892418925189261892718928189291893018931189321893318934189351893618937189381893918940189411894218943189441894518946189471894818949189501895118952189531895418955189561895718958189591896018961189621896318964189651896618967189681896918970189711897218973189741897518976189771897818979189801898118982189831898418985189861898718988189891899018991189921899318994189951899618997189981899919000190011900219003190041900519006190071900819009190101901119012190131901419015190161901719018190191902019021190221902319024190251902619027190281902919030190311903219033190341903519036190371903819039190401904119042190431904419045190461904719048190491905019051190521905319054190551905619057190581905919060190611906219063190641906519066190671906819069190701907119072190731907419075190761907719078190791908019081190821908319084190851908619087190881908919090190911909219093190941909519096190971909819099191001910119102191031910419105191061910719108191091911019111191121911319114191151911619117191181911919120191211912219123191241912519126191271912819129191301913119132191331913419135191361913719138191391914019141191421914319144191451914619147191481914919150191511915219153191541915519156191571915819159191601916119162191631916419165191661916719168191691917019171191721917319174191751917619177191781917919180191811918219183191841918519186191871918819189191901919119192191931919419195191961919719198191991920019201192021920319204192051920619207192081920919210192111921219213192141921519216192171921819219192201922119222192231922419225192261922719228192291923019231192321923319234192351923619237192381923919240192411924219243192441924519246192471924819249192501925119252192531925419255192561925719258192591926019261192621926319264192651926619267192681926919270192711927219273192741927519276192771927819279192801928119282192831928419285192861928719288192891929019291192921929319294192951929619297192981929919300193011930219303193041930519306193071930819309193101931119312193131931419315193161931719318193191932019321193221932319324193251932619327193281932919330193311933219333193341933519336193371933819339193401934119342193431934419345193461934719348193491935019351193521935319354193551935619357193581935919360193611936219363193641936519366193671936819369193701937119372193731937419375193761937719378193791938019381193821938319384193851938619387193881938919390193911939219393193941939519396193971939819399194001940119402194031940419405194061940719408194091941019411194121941319414194151941619417194181941919420194211942219423194241942519426194271942819429194301943119432194331943419435194361943719438194391944019441194421944319444194451944619447194481944919450194511945219453194541945519456194571945819459194601946119462194631946419465194661946719468194691947019471194721947319474194751947619477194781947919480194811948219483194841948519486194871948819489194901949119492194931949419495194961949719498194991950019501195021950319504195051950619507195081950919510195111951219513195141951519516195171951819519195201952119522195231952419525195261952719528195291953019531195321953319534195351953619537195381953919540195411954219543195441954519546195471954819549195501955119552195531955419555195561955719558195591956019561195621956319564195651956619567195681956919570195711957219573195741957519576195771957819579195801958119582195831958419585195861958719588195891959019591195921959319594195951959619597195981959919600196011960219603196041960519606196071960819609196101961119612196131961419615196161961719618196191962019621196221962319624196251962619627196281962919630196311963219633196341963519636196371963819639196401964119642196431964419645196461964719648196491965019651196521965319654196551965619657196581965919660196611966219663196641966519666196671966819669196701967119672196731967419675196761967719678196791968019681196821968319684196851968619687196881968919690196911969219693196941969519696196971969819699197001970119702197031970419705197061970719708197091971019711197121971319714197151971619717197181971919720197211972219723197241972519726197271972819729197301973119732197331973419735197361973719738197391974019741197421974319744197451974619747197481974919750197511975219753197541975519756197571975819759197601976119762197631976419765197661976719768197691977019771197721977319774197751977619777197781977919780197811978219783197841978519786197871978819789197901979119792197931979419795197961979719798197991980019801198021980319804198051980619807198081980919810198111981219813198141981519816198171981819819198201982119822198231982419825198261982719828198291983019831198321983319834198351983619837198381983919840198411984219843198441984519846198471984819849198501985119852198531985419855198561985719858198591986019861198621986319864198651986619867198681986919870198711987219873198741987519876198771987819879198801988119882198831988419885198861988719888198891989019891198921989319894198951989619897198981989919900199011990219903199041990519906199071990819909199101991119912199131991419915199161991719918199191992019921199221992319924199251992619927199281992919930199311993219933199341993519936199371993819939199401994119942199431994419945199461994719948199491995019951199521995319954199551995619957199581995919960199611996219963199641996519966199671996819969199701997119972199731997419975199761997719978199791998019981199821998319984199851998619987199881998919990199911999219993199941999519996199971999819999200002000120002200032000420005200062000720008200092001020011200122001320014200152001620017200182001920020200212002220023200242002520026200272002820029200302003120032200332003420035200362003720038200392004020041200422004320044200452004620047200482004920050200512005220053200542005520056200572005820059200602006120062200632006420065200662006720068200692007020071200722007320074200752007620077200782007920080200812008220083200842008520086200872008820089200902009120092200932009420095200962009720098200992010020101201022010320104201052010620107201082010920110201112011220113201142011520116201172011820119201202012120122201232012420125201262012720128201292013020131201322013320134201352013620137201382013920140201412014220143201442014520146201472014820149201502015120152201532015420155201562015720158201592016020161201622016320164201652016620167201682016920170201712017220173201742017520176201772017820179201802018120182201832018420185201862018720188201892019020191201922019320194201952019620197201982019920200202012020220203202042020520206202072020820209202102021120212202132021420215202162021720218202192022020221202222022320224202252022620227202282022920230202312023220233202342023520236202372023820239202402024120242202432024420245202462024720248202492025020251202522025320254202552025620257202582025920260202612026220263202642026520266202672026820269202702027120272202732027420275202762027720278202792028020281202822028320284202852028620287202882028920290202912029220293202942029520296202972029820299203002030120302203032030420305203062030720308203092031020311203122031320314203152031620317203182031920320203212032220323203242032520326203272032820329203302033120332203332033420335203362033720338203392034020341203422034320344203452034620347203482034920350203512035220353203542035520356203572035820359203602036120362203632036420365203662036720368203692037020371203722037320374203752037620377203782037920380203812038220383203842038520386203872038820389203902039120392203932039420395203962039720398203992040020401204022040320404204052040620407204082040920410204112041220413204142041520416204172041820419204202042120422204232042420425204262042720428204292043020431204322043320434204352043620437204382043920440204412044220443204442044520446204472044820449204502045120452204532045420455204562045720458204592046020461204622046320464204652046620467204682046920470204712047220473204742047520476204772047820479204802048120482204832048420485204862048720488204892049020491204922049320494204952049620497204982049920500205012050220503205042050520506205072050820509205102051120512205132051420515205162051720518205192052020521205222052320524205252052620527205282052920530205312053220533205342053520536205372053820539205402054120542205432054420545205462054720548205492055020551205522055320554205552055620557205582055920560205612056220563205642056520566205672056820569205702057120572205732057420575205762057720578205792058020581205822058320584205852058620587205882058920590205912059220593205942059520596205972059820599206002060120602206032060420605206062060720608206092061020611206122061320614206152061620617206182061920620206212062220623206242062520626206272062820629206302063120632206332063420635206362063720638206392064020641206422064320644206452064620647206482064920650206512065220653206542065520656206572065820659206602066120662206632066420665206662066720668206692067020671206722067320674206752067620677206782067920680206812068220683206842068520686206872068820689206902069120692206932069420695206962069720698206992070020701207022070320704207052070620707207082070920710207112071220713207142071520716207172071820719207202072120722207232072420725207262072720728207292073020731207322073320734207352073620737207382073920740207412074220743207442074520746207472074820749207502075120752207532075420755207562075720758207592076020761207622076320764207652076620767207682076920770207712077220773207742077520776207772077820779207802078120782207832078420785207862078720788207892079020791207922079320794207952079620797207982079920800208012080220803208042080520806208072080820809208102081120812208132081420815208162081720818208192082020821208222082320824208252082620827208282082920830208312083220833208342083520836208372083820839208402084120842208432084420845208462084720848208492085020851208522085320854208552085620857208582085920860208612086220863208642086520866208672086820869208702087120872208732087420875208762087720878208792088020881208822088320884208852088620887208882088920890208912089220893208942089520896208972089820899209002090120902209032090420905209062090720908209092091020911209122091320914209152091620917209182091920920209212092220923209242092520926209272092820929209302093120932209332093420935209362093720938209392094020941209422094320944209452094620947209482094920950209512095220953209542095520956209572095820959209602096120962209632096420965209662096720968209692097020971209722097320974209752097620977209782097920980209812098220983209842098520986209872098820989209902099120992209932099420995209962099720998209992100021001210022100321004210052100621007210082100921010210112101221013210142101521016210172101821019210202102121022210232102421025210262102721028210292103021031210322103321034210352103621037210382103921040210412104221043210442104521046210472104821049210502105121052210532105421055210562105721058210592106021061210622106321064210652106621067210682106921070210712107221073210742107521076210772107821079210802108121082210832108421085210862108721088210892109021091210922109321094210952109621097210982109921100211012110221103211042110521106211072110821109211102111121112211132111421115211162111721118211192112021121211222112321124211252112621127211282112921130211312113221133211342113521136211372113821139211402114121142211432114421145211462114721148211492115021151211522115321154211552115621157211582115921160211612116221163211642116521166211672116821169211702117121172211732117421175211762117721178211792118021181211822118321184211852118621187211882118921190211912119221193211942119521196211972119821199212002120121202212032120421205212062120721208212092121021211212122121321214212152121621217212182121921220212212122221223212242122521226212272122821229212302123121232212332123421235212362123721238212392124021241212422124321244212452124621247212482124921250212512125221253212542125521256212572125821259212602126121262212632126421265212662126721268212692127021271212722127321274212752127621277212782127921280212812128221283212842128521286212872128821289212902129121292212932129421295212962129721298212992130021301213022130321304213052130621307213082130921310213112131221313213142131521316213172131821319213202132121322213232132421325213262132721328213292133021331213322133321334213352133621337213382133921340213412134221343213442134521346213472134821349213502135121352213532135421355213562135721358213592136021361213622136321364213652136621367213682136921370213712137221373213742137521376213772137821379213802138121382213832138421385213862138721388213892139021391213922139321394213952139621397213982139921400214012140221403214042140521406214072140821409214102141121412214132141421415214162141721418214192142021421214222142321424214252142621427214282142921430214312143221433214342143521436214372143821439214402144121442214432144421445214462144721448214492145021451214522145321454214552145621457214582145921460214612146221463214642146521466214672146821469214702147121472214732147421475214762147721478214792148021481214822148321484214852148621487214882148921490214912149221493214942149521496214972149821499215002150121502215032150421505215062150721508215092151021511215122151321514215152151621517215182151921520215212152221523215242152521526215272152821529215302153121532215332153421535215362153721538215392154021541215422154321544215452154621547215482154921550215512155221553215542155521556215572155821559215602156121562215632156421565215662156721568215692157021571215722157321574215752157621577215782157921580215812158221583215842158521586215872158821589215902159121592215932159421595215962159721598215992160021601216022160321604216052160621607216082160921610216112161221613216142161521616216172161821619216202162121622216232162421625216262162721628216292163021631216322163321634216352163621637216382163921640216412164221643216442164521646216472164821649216502165121652216532165421655216562165721658216592166021661216622166321664216652166621667216682166921670216712167221673216742167521676216772167821679216802168121682216832168421685216862168721688216892169021691216922169321694216952169621697216982169921700217012170221703217042170521706217072170821709217102171121712217132171421715217162171721718217192172021721217222172321724217252172621727217282172921730217312173221733217342173521736217372173821739217402174121742217432174421745217462174721748217492175021751217522175321754217552175621757217582175921760217612176221763217642176521766217672176821769217702177121772217732177421775217762177721778217792178021781217822178321784217852178621787217882178921790217912179221793217942179521796217972179821799218002180121802218032180421805218062180721808218092181021811218122181321814218152181621817218182181921820218212182221823218242182521826218272182821829218302183121832218332183421835218362183721838218392184021841218422184321844218452184621847218482184921850218512185221853218542185521856218572185821859218602186121862218632186421865218662186721868218692187021871218722187321874218752187621877218782187921880218812188221883218842188521886218872188821889218902189121892218932189421895218962189721898218992190021901219022190321904219052190621907219082190921910219112191221913219142191521916219172191821919219202192121922219232192421925219262192721928219292193021931219322193321934219352193621937219382193921940219412194221943219442194521946219472194821949219502195121952219532195421955219562195721958219592196021961219622196321964219652196621967219682196921970219712197221973219742197521976219772197821979219802198121982219832198421985219862198721988219892199021991219922199321994219952199621997219982199922000220012200222003220042200522006220072200822009220102201122012220132201422015220162201722018220192202022021220222202322024220252202622027220282202922030220312203222033220342203522036220372203822039220402204122042220432204422045220462204722048220492205022051220522205322054220552205622057220582205922060220612206222063220642206522066220672206822069220702207122072220732207422075220762207722078220792208022081220822208322084220852208622087220882208922090220912209222093220942209522096220972209822099221002210122102221032210422105221062210722108221092211022111221122211322114221152211622117221182211922120221212212222123221242212522126221272212822129221302213122132221332213422135221362213722138221392214022141221422214322144221452214622147221482214922150221512215222153221542215522156221572215822159221602216122162221632216422165221662216722168221692217022171221722217322174221752217622177221782217922180221812218222183221842218522186221872218822189221902219122192221932219422195221962219722198221992220022201222022220322204222052220622207222082220922210222112221222213222142221522216222172221822219222202222122222222232222422225222262222722228222292223022231222322223322234222352223622237222382223922240222412224222243222442224522246222472224822249222502225122252222532225422255222562225722258222592226022261222622226322264222652226622267222682226922270222712227222273222742227522276222772227822279222802228122282222832228422285222862228722288222892229022291222922229322294222952229622297222982229922300223012230222303223042230522306223072230822309223102231122312223132231422315223162231722318223192232022321223222232322324223252232622327223282232922330223312233222333223342233522336223372233822339223402234122342223432234422345223462234722348223492235022351223522235322354223552235622357223582235922360223612236222363223642236522366223672236822369223702237122372223732237422375223762237722378223792238022381223822238322384223852238622387223882238922390223912239222393223942239522396223972239822399224002240122402224032240422405224062240722408224092241022411224122241322414224152241622417224182241922420224212242222423224242242522426224272242822429224302243122432224332243422435224362243722438224392244022441224422244322444224452244622447224482244922450224512245222453224542245522456224572245822459224602246122462224632246422465224662246722468224692247022471224722247322474224752247622477224782247922480224812248222483224842248522486224872248822489224902249122492224932249422495224962249722498224992250022501225022250322504225052250622507225082250922510225112251222513225142251522516225172251822519225202252122522225232252422525225262252722528225292253022531225322253322534225352253622537225382253922540225412254222543225442254522546225472254822549225502255122552225532255422555225562255722558225592256022561225622256322564225652256622567225682256922570225712257222573225742257522576225772257822579225802258122582225832258422585225862258722588225892259022591225922259322594225952259622597225982259922600226012260222603226042260522606226072260822609226102261122612226132261422615226162261722618226192262022621226222262322624226252262622627226282262922630226312263222633226342263522636226372263822639226402264122642226432264422645226462264722648226492265022651226522265322654226552265622657226582265922660226612266222663226642266522666226672266822669226702267122672226732267422675226762267722678226792268022681226822268322684226852268622687226882268922690226912269222693226942269522696226972269822699227002270122702227032270422705227062270722708227092271022711227122271322714227152271622717227182271922720227212272222723227242272522726227272272822729227302273122732227332273422735227362273722738227392274022741227422274322744227452274622747227482274922750227512275222753227542275522756227572275822759227602276122762227632276422765227662276722768227692277022771227722277322774227752277622777227782277922780227812278222783227842278522786227872278822789227902279122792227932279422795227962279722798227992280022801228022280322804228052280622807228082280922810228112281222813228142281522816228172281822819228202282122822228232282422825228262282722828228292283022831228322283322834228352283622837228382283922840228412284222843228442284522846228472284822849228502285122852228532285422855228562285722858228592286022861228622286322864228652286622867228682286922870228712287222873228742287522876228772287822879228802288122882228832288422885228862288722888228892289022891228922289322894228952289622897228982289922900229012290222903229042290522906229072290822909229102291122912229132291422915229162291722918229192292022921229222292322924229252292622927229282292922930229312293222933229342293522936229372293822939229402294122942229432294422945229462294722948229492295022951229522295322954229552295622957229582295922960229612296222963229642296522966229672296822969229702297122972229732297422975229762297722978229792298022981229822298322984229852298622987229882298922990229912299222993229942299522996229972299822999230002300123002230032300423005230062300723008230092301023011230122301323014230152301623017230182301923020230212302223023230242302523026230272302823029230302303123032230332303423035230362303723038230392304023041230422304323044230452304623047230482304923050230512305223053230542305523056230572305823059230602306123062230632306423065230662306723068230692307023071230722307323074230752307623077230782307923080230812308223083230842308523086230872308823089230902309123092230932309423095230962309723098230992310023101231022310323104231052310623107231082310923110231112311223113231142311523116231172311823119231202312123122231232312423125231262312723128231292313023131231322313323134231352313623137231382313923140231412314223143231442314523146231472314823149231502315123152231532315423155231562315723158231592316023161231622316323164231652316623167231682316923170231712317223173231742317523176231772317823179231802318123182231832318423185231862318723188231892319023191231922319323194231952319623197231982319923200232012320223203232042320523206232072320823209232102321123212232132321423215232162321723218232192322023221232222322323224232252322623227232282322923230232312323223233232342323523236232372323823239232402324123242232432324423245232462324723248232492325023251232522325323254232552325623257232582325923260232612326223263232642326523266232672326823269232702327123272232732327423275232762327723278232792328023281232822328323284232852328623287232882328923290232912329223293232942329523296232972329823299233002330123302233032330423305233062330723308233092331023311233122331323314233152331623317233182331923320233212332223323233242332523326233272332823329233302333123332233332333423335233362333723338233392334023341233422334323344233452334623347233482334923350233512335223353233542335523356233572335823359233602336123362233632336423365233662336723368233692337023371233722337323374233752337623377233782337923380233812338223383233842338523386233872338823389233902339123392233932339423395233962339723398233992340023401234022340323404234052340623407234082340923410234112341223413234142341523416234172341823419234202342123422234232342423425234262342723428234292343023431234322343323434234352343623437234382343923440234412344223443234442344523446234472344823449234502345123452234532345423455234562345723458234592346023461234622346323464234652346623467234682346923470234712347223473234742347523476234772347823479234802348123482234832348423485234862348723488234892349023491234922349323494234952349623497234982349923500235012350223503235042350523506235072350823509235102351123512235132351423515235162351723518235192352023521235222352323524235252352623527235282352923530235312353223533235342353523536235372353823539235402354123542235432354423545235462354723548235492355023551235522355323554235552355623557235582355923560235612356223563235642356523566235672356823569235702357123572235732357423575235762357723578235792358023581235822358323584235852358623587235882358923590235912359223593235942359523596235972359823599236002360123602236032360423605236062360723608236092361023611236122361323614236152361623617236182361923620236212362223623236242362523626236272362823629236302363123632236332363423635236362363723638236392364023641236422364323644236452364623647236482364923650236512365223653236542365523656236572365823659236602366123662236632366423665236662366723668236692367023671236722367323674236752367623677236782367923680236812368223683236842368523686236872368823689236902369123692236932369423695236962369723698236992370023701237022370323704237052370623707237082370923710237112371223713237142371523716237172371823719237202372123722237232372423725237262372723728237292373023731237322373323734237352373623737237382373923740237412374223743237442374523746237472374823749237502375123752237532375423755237562375723758237592376023761237622376323764237652376623767237682376923770237712377223773237742377523776237772377823779237802378123782237832378423785237862378723788237892379023791237922379323794237952379623797237982379923800238012380223803238042380523806238072380823809238102381123812238132381423815238162381723818238192382023821238222382323824238252382623827238282382923830238312383223833238342383523836238372383823839238402384123842238432384423845238462384723848238492385023851238522385323854238552385623857238582385923860238612386223863238642386523866238672386823869238702387123872238732387423875238762387723878238792388023881238822388323884238852388623887238882388923890238912389223893238942389523896238972389823899239002390123902239032390423905239062390723908239092391023911239122391323914239152391623917239182391923920239212392223923239242392523926239272392823929239302393123932239332393423935239362393723938239392394023941239422394323944239452394623947239482394923950239512395223953239542395523956239572395823959239602396123962239632396423965239662396723968239692397023971239722397323974239752397623977239782397923980239812398223983239842398523986239872398823989239902399123992239932399423995239962399723998239992400024001240022400324004240052400624007240082400924010240112401224013240142401524016240172401824019240202402124022240232402424025240262402724028240292403024031240322403324034240352403624037240382403924040240412404224043240442404524046240472404824049240502405124052240532405424055240562405724058240592406024061240622406324064240652406624067240682406924070240712407224073240742407524076240772407824079240802408124082240832408424085240862408724088240892409024091240922409324094240952409624097240982409924100241012410224103241042410524106241072410824109241102411124112241132411424115241162411724118241192412024121241222412324124241252412624127241282412924130241312413224133241342413524136241372413824139241402414124142241432414424145241462414724148241492415024151241522415324154241552415624157241582415924160241612416224163241642416524166241672416824169241702417124172241732417424175241762417724178241792418024181241822418324184241852418624187241882418924190241912419224193241942419524196241972419824199242002420124202242032420424205242062420724208242092421024211242122421324214242152421624217242182421924220242212422224223242242422524226242272422824229242302423124232242332423424235242362423724238242392424024241242422424324244242452424624247242482424924250242512425224253242542425524256242572425824259242602426124262242632426424265242662426724268242692427024271242722427324274242752427624277242782427924280242812428224283242842428524286242872428824289242902429124292242932429424295242962429724298242992430024301243022430324304243052430624307243082430924310243112431224313243142431524316243172431824319243202432124322243232432424325243262432724328243292433024331243322433324334243352433624337243382433924340243412434224343243442434524346243472434824349243502435124352243532435424355243562435724358243592436024361243622436324364243652436624367243682436924370243712437224373243742437524376243772437824379243802438124382243832438424385243862438724388243892439024391243922439324394243952439624397243982439924400244012440224403244042440524406244072440824409244102441124412244132441424415244162441724418244192442024421244222442324424244252442624427244282442924430244312443224433244342443524436244372443824439244402444124442244432444424445244462444724448244492445024451244522445324454244552445624457244582445924460244612446224463244642446524466244672446824469244702447124472244732447424475244762447724478244792448024481244822448324484244852448624487244882448924490244912449224493244942449524496244972449824499245002450124502245032450424505245062450724508245092451024511245122451324514245152451624517245182451924520245212452224523245242452524526245272452824529245302453124532245332453424535245362453724538245392454024541245422454324544245452454624547245482454924550245512455224553245542455524556245572455824559245602456124562245632456424565245662456724568245692457024571245722457324574245752457624577245782457924580245812458224583245842458524586245872458824589245902459124592245932459424595245962459724598245992460024601246022460324604246052460624607246082460924610246112461224613246142461524616246172461824619246202462124622246232462424625246262462724628246292463024631246322463324634246352463624637246382463924640246412464224643246442464524646246472464824649246502465124652246532465424655246562465724658246592466024661246622466324664246652466624667246682466924670246712467224673246742467524676246772467824679246802468124682246832468424685246862468724688246892469024691246922469324694246952469624697246982469924700247012470224703247042470524706247072470824709247102471124712247132471424715247162471724718247192472024721247222472324724247252472624727247282472924730247312473224733247342473524736247372473824739247402474124742247432474424745247462474724748247492475024751247522475324754247552475624757247582475924760247612476224763247642476524766247672476824769247702477124772247732477424775247762477724778247792478024781247822478324784247852478624787247882478924790247912479224793247942479524796247972479824799248002480124802248032480424805248062480724808248092481024811248122481324814248152481624817248182481924820248212482224823248242482524826248272482824829248302483124832248332483424835248362483724838248392484024841248422484324844248452484624847248482484924850248512485224853248542485524856248572485824859248602486124862248632486424865248662486724868248692487024871248722487324874248752487624877248782487924880248812488224883248842488524886248872488824889248902489124892248932489424895248962489724898248992490024901249022490324904249052490624907249082490924910249112491224913249142491524916249172491824919249202492124922249232492424925249262492724928249292493024931249322493324934249352493624937249382493924940249412494224943249442494524946249472494824949249502495124952249532495424955249562495724958249592496024961249622496324964249652496624967249682496924970249712497224973249742497524976249772497824979249802498124982249832498424985249862498724988249892499024991249922499324994249952499624997249982499925000250012500225003250042500525006250072500825009250102501125012250132501425015250162501725018250192502025021250222502325024250252502625027250282502925030250312503225033250342503525036250372503825039250402504125042250432504425045250462504725048250492505025051250522505325054250552505625057250582505925060250612506225063250642506525066250672506825069250702507125072250732507425075250762507725078250792508025081250822508325084250852508625087250882508925090250912509225093250942509525096250972509825099251002510125102251032510425105251062510725108251092511025111251122511325114251152511625117251182511925120251212512225123251242512525126251272512825129251302513125132251332513425135251362513725138251392514025141251422514325144251452514625147251482514925150251512515225153251542515525156251572515825159251602516125162251632516425165251662516725168251692517025171251722517325174251752517625177251782517925180251812518225183251842518525186251872518825189251902519125192251932519425195251962519725198251992520025201252022520325204252052520625207252082520925210252112521225213252142521525216252172521825219252202522125222252232522425225252262522725228252292523025231252322523325234252352523625237252382523925240252412524225243252442524525246252472524825249252502525125252252532525425255252562525725258252592526025261252622526325264252652526625267252682526925270252712527225273252742527525276252772527825279252802528125282252832528425285252862528725288252892529025291252922529325294252952529625297252982529925300253012530225303253042530525306253072530825309253102531125312253132531425315253162531725318253192532025321253222532325324253252532625327253282532925330253312533225333253342533525336253372533825339253402534125342253432534425345253462534725348253492535025351253522535325354253552535625357253582535925360253612536225363253642536525366253672536825369253702537125372253732537425375253762537725378253792538025381253822538325384253852538625387253882538925390253912539225393253942539525396253972539825399254002540125402254032540425405254062540725408254092541025411254122541325414254152541625417254182541925420254212542225423254242542525426254272542825429254302543125432254332543425435254362543725438254392544025441254422544325444254452544625447254482544925450254512545225453254542545525456254572545825459254602546125462254632546425465254662546725468254692547025471254722547325474254752547625477254782547925480254812548225483254842548525486254872548825489254902549125492254932549425495254962549725498254992550025501255022550325504255052550625507255082550925510255112551225513255142551525516255172551825519255202552125522255232552425525255262552725528255292553025531255322553325534255352553625537255382553925540255412554225543255442554525546255472554825549255502555125552255532555425555255562555725558255592556025561255622556325564255652556625567255682556925570255712557225573255742557525576255772557825579255802558125582255832558425585255862558725588255892559025591255922559325594255952559625597255982559925600256012560225603256042560525606256072560825609256102561125612256132561425615256162561725618256192562025621256222562325624256252562625627256282562925630256312563225633256342563525636256372563825639256402564125642256432564425645256462564725648256492565025651256522565325654256552565625657256582565925660256612566225663256642566525666256672566825669256702567125672256732567425675256762567725678256792568025681256822568325684256852568625687256882568925690256912569225693256942569525696256972569825699257002570125702257032570425705257062570725708257092571025711257122571325714257152571625717257182571925720257212572225723257242572525726257272572825729257302573125732257332573425735257362573725738257392574025741257422574325744257452574625747257482574925750257512575225753257542575525756257572575825759257602576125762257632576425765257662576725768257692577025771257722577325774257752577625777257782577925780257812578225783257842578525786257872578825789257902579125792257932579425795257962579725798257992580025801258022580325804258052580625807258082580925810258112581225813258142581525816258172581825819258202582125822258232582425825258262582725828258292583025831258322583325834258352583625837258382583925840258412584225843258442584525846258472584825849258502585125852258532585425855258562585725858258592586025861258622586325864258652586625867258682586925870258712587225873258742587525876258772587825879258802588125882258832588425885258862588725888258892589025891258922589325894258952589625897258982589925900259012590225903259042590525906259072590825909259102591125912259132591425915259162591725918259192592025921259222592325924259252592625927259282592925930259312593225933259342593525936259372593825939259402594125942259432594425945259462594725948259492595025951259522595325954259552595625957259582595925960259612596225963259642596525966259672596825969259702597125972259732597425975259762597725978259792598025981259822598325984259852598625987259882598925990259912599225993259942599525996259972599825999260002600126002260032600426005260062600726008260092601026011260122601326014260152601626017260182601926020260212602226023260242602526026260272602826029260302603126032260332603426035260362603726038260392604026041260422604326044260452604626047260482604926050260512605226053260542605526056260572605826059260602606126062260632606426065260662606726068260692607026071260722607326074260752607626077260782607926080260812608226083260842608526086260872608826089260902609126092260932609426095260962609726098260992610026101261022610326104261052610626107261082610926110261112611226113261142611526116261172611826119261202612126122261232612426125261262612726128261292613026131261322613326134261352613626137261382613926140261412614226143261442614526146261472614826149261502615126152261532615426155261562615726158261592616026161261622616326164261652616626167261682616926170261712617226173261742617526176261772617826179261802618126182261832618426185261862618726188261892619026191261922619326194261952619626197261982619926200262012620226203262042620526206262072620826209262102621126212262132621426215262162621726218262192622026221262222622326224262252622626227262282622926230262312623226233262342623526236262372623826239262402624126242262432624426245262462624726248262492625026251262522625326254262552625626257262582625926260262612626226263262642626526266262672626826269262702627126272262732627426275262762627726278262792628026281262822628326284262852628626287262882628926290262912629226293262942629526296262972629826299263002630126302263032630426305263062630726308263092631026311263122631326314263152631626317263182631926320263212632226323263242632526326263272632826329263302633126332263332633426335263362633726338263392634026341263422634326344263452634626347263482634926350263512635226353263542635526356263572635826359263602636126362263632636426365263662636726368263692637026371263722637326374263752637626377263782637926380263812638226383263842638526386263872638826389263902639126392263932639426395263962639726398263992640026401264022640326404264052640626407264082640926410264112641226413264142641526416264172641826419264202642126422264232642426425264262642726428264292643026431264322643326434264352643626437264382643926440264412644226443264442644526446264472644826449264502645126452264532645426455264562645726458264592646026461264622646326464264652646626467264682646926470264712647226473264742647526476264772647826479264802648126482264832648426485264862648726488264892649026491264922649326494264952649626497264982649926500265012650226503265042650526506265072650826509265102651126512265132651426515265162651726518265192652026521265222652326524265252652626527265282652926530265312653226533265342653526536265372653826539265402654126542265432654426545265462654726548265492655026551265522655326554265552655626557265582655926560265612656226563265642656526566265672656826569265702657126572265732657426575265762657726578265792658026581265822658326584265852658626587265882658926590265912659226593265942659526596265972659826599266002660126602266032660426605266062660726608266092661026611266122661326614266152661626617266182661926620266212662226623266242662526626266272662826629266302663126632266332663426635266362663726638266392664026641266422664326644266452664626647266482664926650266512665226653266542665526656266572665826659266602666126662266632666426665266662666726668266692667026671266722667326674266752667626677266782667926680266812668226683266842668526686266872668826689266902669126692266932669426695266962669726698266992670026701267022670326704267052670626707267082670926710267112671226713267142671526716267172671826719267202672126722267232672426725267262672726728267292673026731267322673326734267352673626737267382673926740267412674226743267442674526746267472674826749267502675126752267532675426755267562675726758267592676026761267622676326764267652676626767267682676926770267712677226773267742677526776267772677826779267802678126782267832678426785267862678726788267892679026791267922679326794267952679626797267982679926800268012680226803268042680526806268072680826809268102681126812268132681426815268162681726818268192682026821268222682326824268252682626827268282682926830268312683226833268342683526836268372683826839268402684126842268432684426845268462684726848268492685026851268522685326854268552685626857268582685926860268612686226863268642686526866268672686826869268702687126872268732687426875268762687726878268792688026881268822688326884268852688626887268882688926890268912689226893268942689526896268972689826899269002690126902269032690426905269062690726908269092691026911269122691326914269152691626917269182691926920269212692226923269242692526926269272692826929269302693126932269332693426935269362693726938269392694026941269422694326944269452694626947269482694926950269512695226953269542695526956269572695826959269602696126962269632696426965269662696726968269692697026971269722697326974269752697626977269782697926980269812698226983269842698526986269872698826989269902699126992269932699426995269962699726998269992700027001270022700327004270052700627007270082700927010270112701227013270142701527016270172701827019270202702127022270232702427025270262702727028270292703027031270322703327034270352703627037270382703927040270412704227043270442704527046270472704827049270502705127052270532705427055270562705727058270592706027061270622706327064270652706627067270682706927070270712707227073270742707527076270772707827079270802708127082270832708427085270862708727088270892709027091270922709327094270952709627097270982709927100271012710227103271042710527106271072710827109271102711127112271132711427115271162711727118271192712027121271222712327124271252712627127271282712927130271312713227133271342713527136271372713827139271402714127142271432714427145271462714727148271492715027151271522715327154271552715627157271582715927160271612716227163271642716527166271672716827169271702717127172271732717427175271762717727178271792718027181271822718327184271852718627187271882718927190271912719227193271942719527196271972719827199272002720127202272032720427205272062720727208272092721027211272122721327214272152721627217272182721927220272212722227223272242722527226272272722827229272302723127232272332723427235272362723727238272392724027241272422724327244272452724627247272482724927250272512725227253272542725527256272572725827259272602726127262272632726427265272662726727268272692727027271272722727327274272752727627277272782727927280272812728227283272842728527286272872728827289272902729127292272932729427295272962729727298272992730027301273022730327304273052730627307273082730927310273112731227313273142731527316273172731827319273202732127322273232732427325273262732727328273292733027331273322733327334273352733627337273382733927340273412734227343273442734527346273472734827349273502735127352273532735427355273562735727358273592736027361273622736327364273652736627367273682736927370273712737227373273742737527376273772737827379273802738127382273832738427385273862738727388273892739027391273922739327394273952739627397273982739927400274012740227403274042740527406274072740827409274102741127412274132741427415274162741727418274192742027421274222742327424274252742627427274282742927430274312743227433274342743527436274372743827439274402744127442274432744427445274462744727448274492745027451274522745327454274552745627457274582745927460274612746227463274642746527466274672746827469274702747127472274732747427475274762747727478274792748027481274822748327484274852748627487274882748927490274912749227493274942749527496274972749827499275002750127502275032750427505275062750727508275092751027511275122751327514275152751627517275182751927520275212752227523275242752527526275272752827529275302753127532275332753427535275362753727538275392754027541275422754327544275452754627547275482754927550275512755227553275542755527556275572755827559275602756127562275632756427565275662756727568275692757027571275722757327574275752757627577275782757927580275812758227583275842758527586275872758827589275902759127592275932759427595275962759727598275992760027601276022760327604276052760627607276082760927610276112761227613276142761527616276172761827619276202762127622276232762427625276262762727628276292763027631276322763327634276352763627637276382763927640276412764227643276442764527646276472764827649276502765127652276532765427655276562765727658276592766027661276622766327664276652766627667276682766927670276712767227673276742767527676276772767827679276802768127682276832768427685276862768727688276892769027691276922769327694276952769627697276982769927700277012770227703277042770527706277072770827709277102771127712277132771427715277162771727718277192772027721277222772327724277252772627727277282772927730277312773227733277342773527736277372773827739277402774127742277432774427745277462774727748277492775027751277522775327754277552775627757277582775927760277612776227763277642776527766277672776827769277702777127772277732777427775277762777727778277792778027781277822778327784277852778627787277882778927790277912779227793277942779527796277972779827799278002780127802278032780427805278062780727808278092781027811278122781327814278152781627817278182781927820278212782227823278242782527826278272782827829278302783127832278332783427835278362783727838278392784027841278422784327844278452784627847278482784927850278512785227853278542785527856278572785827859278602786127862278632786427865278662786727868278692787027871278722787327874278752787627877278782787927880278812788227883278842788527886278872788827889278902789127892278932789427895278962789727898278992790027901279022790327904279052790627907279082790927910279112791227913279142791527916279172791827919279202792127922279232792427925279262792727928279292793027931279322793327934279352793627937279382793927940279412794227943279442794527946279472794827949279502795127952279532795427955279562795727958279592796027961279622796327964279652796627967279682796927970279712797227973279742797527976279772797827979279802798127982279832798427985279862798727988279892799027991279922799327994279952799627997279982799928000280012800228003280042800528006280072800828009280102801128012280132801428015280162801728018280192802028021280222802328024280252802628027280282802928030280312803228033280342803528036280372803828039280402804128042280432804428045280462804728048280492805028051280522805328054280552805628057280582805928060280612806228063280642806528066280672806828069280702807128072280732807428075280762807728078280792808028081280822808328084280852808628087280882808928090280912809228093280942809528096280972809828099281002810128102281032810428105281062810728108281092811028111281122811328114281152811628117281182811928120281212812228123281242812528126281272812828129281302813128132281332813428135281362813728138281392814028141281422814328144281452814628147281482814928150281512815228153281542815528156281572815828159281602816128162281632816428165281662816728168281692817028171281722817328174281752817628177281782817928180281812818228183281842818528186281872818828189281902819128192281932819428195281962819728198281992820028201282022820328204282052820628207282082820928210282112821228213282142821528216282172821828219282202822128222282232822428225282262822728228282292823028231282322823328234282352823628237282382823928240282412824228243282442824528246282472824828249282502825128252282532825428255282562825728258282592826028261282622826328264282652826628267282682826928270282712827228273282742827528276282772827828279282802828128282282832828428285282862828728288282892829028291282922829328294282952829628297282982829928300283012830228303283042830528306283072830828309283102831128312283132831428315283162831728318283192832028321283222832328324283252832628327283282832928330283312833228333283342833528336283372833828339283402834128342283432834428345283462834728348283492835028351283522835328354283552835628357283582835928360283612836228363283642836528366283672836828369283702837128372283732837428375283762837728378283792838028381283822838328384283852838628387283882838928390283912839228393283942839528396283972839828399284002840128402284032840428405284062840728408284092841028411284122841328414284152841628417284182841928420284212842228423284242842528426284272842828429284302843128432284332843428435284362843728438284392844028441284422844328444284452844628447284482844928450284512845228453284542845528456284572845828459284602846128462284632846428465284662846728468284692847028471284722847328474284752847628477284782847928480284812848228483284842848528486284872848828489284902849128492284932849428495284962849728498284992850028501285022850328504285052850628507285082850928510285112851228513285142851528516285172851828519285202852128522285232852428525285262852728528285292853028531285322853328534285352853628537285382853928540285412854228543285442854528546285472854828549285502855128552285532855428555285562855728558285592856028561285622856328564285652856628567285682856928570285712857228573285742857528576285772857828579285802858128582285832858428585285862858728588285892859028591285922859328594285952859628597285982859928600286012860228603286042860528606286072860828609286102861128612286132861428615286162861728618286192862028621286222862328624286252862628627286282862928630286312863228633286342863528636286372863828639286402864128642286432864428645286462864728648286492865028651286522865328654286552865628657286582865928660286612866228663286642866528666286672866828669286702867128672286732867428675286762867728678286792868028681286822868328684286852868628687286882868928690286912869228693286942869528696286972869828699287002870128702287032870428705287062870728708287092871028711287122871328714287152871628717287182871928720287212872228723287242872528726287272872828729287302873128732287332873428735287362873728738287392874028741287422874328744287452874628747287482874928750287512875228753287542875528756287572875828759287602876128762287632876428765287662876728768287692877028771287722877328774287752877628777287782877928780287812878228783287842878528786287872878828789287902879128792287932879428795287962879728798287992880028801288022880328804288052880628807288082880928810288112881228813288142881528816288172881828819288202882128822288232882428825288262882728828288292883028831288322883328834288352883628837288382883928840288412884228843288442884528846288472884828849288502885128852288532885428855288562885728858288592886028861288622886328864288652886628867288682886928870288712887228873288742887528876288772887828879288802888128882288832888428885288862888728888288892889028891288922889328894288952889628897288982889928900289012890228903289042890528906289072890828909289102891128912289132891428915289162891728918289192892028921289222892328924289252892628927289282892928930289312893228933289342893528936289372893828939289402894128942289432894428945289462894728948289492895028951289522895328954289552895628957289582895928960289612896228963289642896528966289672896828969289702897128972289732897428975289762897728978289792898028981289822898328984289852898628987289882898928990289912899228993289942899528996289972899828999290002900129002290032900429005290062900729008290092901029011290122901329014290152901629017290182901929020290212902229023290242902529026290272902829029290302903129032290332903429035290362903729038290392904029041290422904329044290452904629047290482904929050290512905229053290542905529056290572905829059290602906129062290632906429065290662906729068290692907029071290722907329074290752907629077290782907929080290812908229083290842908529086290872908829089290902909129092290932909429095290962909729098290992910029101291022910329104291052910629107291082910929110291112911229113291142911529116291172911829119291202912129122291232912429125291262912729128291292913029131291322913329134291352913629137291382913929140291412914229143291442914529146291472914829149291502915129152291532915429155291562915729158291592916029161291622916329164291652916629167291682916929170291712917229173291742917529176291772917829179291802918129182291832918429185291862918729188291892919029191291922919329194291952919629197291982919929200292012920229203292042920529206292072920829209292102921129212292132921429215292162921729218292192922029221292222922329224292252922629227292282922929230292312923229233292342923529236292372923829239292402924129242292432924429245292462924729248292492925029251292522925329254292552925629257292582925929260292612926229263292642926529266292672926829269292702927129272292732927429275292762927729278292792928029281292822928329284292852928629287292882928929290292912929229293292942929529296292972929829299293002930129302293032930429305293062930729308293092931029311293122931329314293152931629317293182931929320293212932229323293242932529326293272932829329293302933129332293332933429335293362933729338293392934029341293422934329344293452934629347293482934929350293512935229353293542935529356293572935829359293602936129362293632936429365293662936729368293692937029371293722937329374293752937629377293782937929380293812938229383293842938529386293872938829389293902939129392293932939429395293962939729398293992940029401294022940329404294052940629407294082940929410294112941229413294142941529416294172941829419294202942129422294232942429425294262942729428294292943029431294322943329434294352943629437294382943929440294412944229443294442944529446294472944829449294502945129452294532945429455294562945729458294592946029461294622946329464294652946629467294682946929470294712947229473294742947529476294772947829479294802948129482294832948429485294862948729488294892949029491294922949329494294952949629497294982949929500295012950229503295042950529506295072950829509295102951129512295132951429515295162951729518295192952029521295222952329524295252952629527295282952929530295312953229533295342953529536295372953829539295402954129542295432954429545295462954729548295492955029551295522955329554295552955629557295582955929560295612956229563295642956529566295672956829569295702957129572295732957429575295762957729578295792958029581295822958329584295852958629587295882958929590295912959229593295942959529596295972959829599296002960129602296032960429605296062960729608296092961029611296122961329614296152961629617296182961929620296212962229623296242962529626296272962829629296302963129632296332963429635296362963729638296392964029641296422964329644296452964629647296482964929650296512965229653296542965529656296572965829659296602966129662296632966429665296662966729668296692967029671296722967329674296752967629677296782967929680296812968229683296842968529686296872968829689296902969129692296932969429695296962969729698296992970029701297022970329704297052970629707297082970929710297112971229713297142971529716297172971829719297202972129722297232972429725297262972729728297292973029731297322973329734297352973629737297382973929740297412974229743297442974529746297472974829749297502975129752297532975429755297562975729758297592976029761297622976329764297652976629767297682976929770297712977229773297742977529776297772977829779297802978129782297832978429785297862978729788297892979029791297922979329794297952979629797297982979929800298012980229803298042980529806298072980829809298102981129812298132981429815298162981729818298192982029821298222982329824298252982629827298282982929830298312983229833298342983529836298372983829839298402984129842298432984429845298462984729848298492985029851298522985329854298552985629857298582985929860298612986229863298642986529866298672986829869298702987129872298732987429875298762987729878298792988029881298822988329884298852988629887298882988929890298912989229893298942989529896298972989829899299002990129902299032990429905299062990729908299092991029911299122991329914299152991629917299182991929920299212992229923299242992529926299272992829929299302993129932299332993429935299362993729938299392994029941299422994329944299452994629947299482994929950299512995229953299542995529956299572995829959299602996129962299632996429965299662996729968299692997029971299722997329974299752997629977299782997929980299812998229983299842998529986299872998829989299902999129992299932999429995299962999729998299993000030001300023000330004300053000630007300083000930010300113001230013300143001530016300173001830019300203002130022300233002430025300263002730028300293003030031300323003330034300353003630037300383003930040300413004230043300443004530046300473004830049300503005130052300533005430055300563005730058300593006030061300623006330064300653006630067300683006930070300713007230073300743007530076300773007830079300803008130082300833008430085300863008730088300893009030091300923009330094300953009630097300983009930100301013010230103301043010530106301073010830109301103011130112301133011430115301163011730118301193012030121301223012330124301253012630127301283012930130301313013230133301343013530136301373013830139301403014130142301433014430145301463014730148301493015030151301523015330154301553015630157301583015930160301613016230163301643016530166301673016830169301703017130172301733017430175301763017730178301793018030181301823018330184301853018630187301883018930190301913019230193301943019530196301973019830199302003020130202302033020430205302063020730208302093021030211302123021330214302153021630217302183021930220302213022230223302243022530226302273022830229302303023130232302333023430235302363023730238302393024030241302423024330244302453024630247302483024930250302513025230253302543025530256302573025830259302603026130262302633026430265302663026730268302693027030271302723027330274302753027630277302783027930280302813028230283302843028530286302873028830289302903029130292302933029430295302963029730298302993030030301303023030330304303053030630307303083030930310303113031230313303143031530316303173031830319303203032130322303233032430325303263032730328303293033030331303323033330334303353033630337303383033930340303413034230343303443034530346303473034830349303503035130352303533035430355303563035730358303593036030361303623036330364303653036630367303683036930370303713037230373303743037530376303773037830379303803038130382303833038430385303863038730388303893039030391303923039330394303953039630397303983039930400304013040230403304043040530406304073040830409304103041130412304133041430415304163041730418304193042030421304223042330424304253042630427304283042930430304313043230433304343043530436304373043830439304403044130442304433044430445304463044730448304493045030451304523045330454304553045630457304583045930460304613046230463304643046530466304673046830469304703047130472304733047430475304763047730478304793048030481304823048330484304853048630487304883048930490304913049230493304943049530496304973049830499305003050130502305033050430505305063050730508305093051030511305123051330514305153051630517305183051930520305213052230523305243052530526305273052830529305303053130532305333053430535305363053730538305393054030541305423054330544305453054630547305483054930550305513055230553305543055530556305573055830559305603056130562305633056430565305663056730568305693057030571305723057330574305753057630577305783057930580305813058230583305843058530586305873058830589305903059130592305933059430595305963059730598305993060030601306023060330604306053060630607306083060930610306113061230613306143061530616306173061830619306203062130622306233062430625306263062730628306293063030631306323063330634306353063630637306383063930640306413064230643306443064530646306473064830649306503065130652306533065430655306563065730658306593066030661306623066330664306653066630667306683066930670306713067230673306743067530676306773067830679306803068130682306833068430685306863068730688306893069030691306923069330694306953069630697306983069930700307013070230703307043070530706307073070830709307103071130712307133071430715307163071730718307193072030721307223072330724307253072630727307283072930730307313073230733307343073530736307373073830739307403074130742307433074430745307463074730748307493075030751307523075330754307553075630757307583075930760307613076230763307643076530766307673076830769307703077130772307733077430775307763077730778307793078030781307823078330784307853078630787307883078930790307913079230793307943079530796307973079830799308003080130802308033080430805308063080730808308093081030811308123081330814308153081630817308183081930820308213082230823308243082530826308273082830829308303083130832308333083430835308363083730838308393084030841308423084330844308453084630847308483084930850308513085230853308543085530856308573085830859308603086130862308633086430865308663086730868308693087030871308723087330874308753087630877308783087930880308813088230883308843088530886308873088830889308903089130892308933089430895308963089730898308993090030901309023090330904309053090630907309083090930910309113091230913309143091530916309173091830919309203092130922309233092430925309263092730928309293093030931309323093330934309353093630937309383093930940309413094230943309443094530946309473094830949309503095130952309533095430955309563095730958309593096030961309623096330964309653096630967309683096930970309713097230973309743097530976309773097830979309803098130982309833098430985309863098730988309893099030991309923099330994309953099630997309983099931000310013100231003310043100531006310073100831009310103101131012310133101431015310163101731018310193102031021310223102331024310253102631027310283102931030310313103231033310343103531036310373103831039310403104131042310433104431045310463104731048310493105031051310523105331054310553105631057310583105931060310613106231063310643106531066310673106831069310703107131072310733107431075310763107731078310793108031081310823108331084310853108631087310883108931090310913109231093310943109531096310973109831099311003110131102311033110431105311063110731108311093111031111311123111331114311153111631117311183111931120311213112231123311243112531126311273112831129311303113131132311333113431135311363113731138311393114031141311423114331144311453114631147311483114931150311513115231153311543115531156311573115831159311603116131162311633116431165311663116731168311693117031171311723117331174311753117631177311783117931180311813118231183311843118531186311873118831189311903119131192311933119431195311963119731198311993120031201312023120331204312053120631207312083120931210312113121231213312143121531216312173121831219312203122131222312233122431225312263122731228312293123031231312323123331234312353123631237312383123931240312413124231243312443124531246312473124831249312503125131252312533125431255312563125731258312593126031261312623126331264312653126631267312683126931270312713127231273312743127531276312773127831279312803128131282312833128431285312863128731288312893129031291312923129331294312953129631297312983129931300313013130231303313043130531306313073130831309313103131131312313133131431315313163131731318313193132031321313223132331324313253132631327313283132931330313313133231333313343133531336313373133831339313403134131342313433134431345313463134731348313493135031351313523135331354313553135631357313583135931360313613136231363313643136531366313673136831369313703137131372313733137431375313763137731378313793138031381313823138331384313853138631387313883138931390313913139231393313943139531396313973139831399314003140131402314033140431405314063140731408314093141031411314123141331414314153141631417314183141931420314213142231423314243142531426314273142831429314303143131432314333143431435314363143731438314393144031441314423144331444314453144631447314483144931450314513145231453314543145531456314573145831459314603146131462314633146431465314663146731468314693147031471314723147331474314753147631477314783147931480314813148231483314843148531486314873148831489314903149131492314933149431495314963149731498314993150031501315023150331504315053150631507315083150931510315113151231513315143151531516315173151831519315203152131522315233152431525315263152731528315293153031531315323153331534315353153631537315383153931540315413154231543315443154531546315473154831549315503155131552315533155431555315563155731558315593156031561315623156331564315653156631567315683156931570315713157231573315743157531576315773157831579315803158131582315833158431585315863158731588315893159031591315923159331594315953159631597315983159931600316013160231603316043160531606316073160831609316103161131612316133161431615316163161731618316193162031621316223162331624316253162631627316283162931630316313163231633316343163531636316373163831639316403164131642316433164431645316463164731648316493165031651316523165331654316553165631657316583165931660316613166231663316643166531666316673166831669316703167131672316733167431675316763167731678316793168031681316823168331684316853168631687316883168931690316913169231693316943169531696316973169831699317003170131702317033170431705317063170731708317093171031711317123171331714317153171631717317183171931720317213172231723317243172531726317273172831729317303173131732317333173431735317363173731738317393174031741317423174331744317453174631747317483174931750317513175231753317543175531756317573175831759317603176131762317633176431765317663176731768317693177031771317723177331774317753177631777317783177931780317813178231783317843178531786317873178831789317903179131792317933179431795317963179731798317993180031801318023180331804318053180631807318083180931810318113181231813318143181531816318173181831819318203182131822318233182431825318263182731828318293183031831318323183331834318353183631837318383183931840318413184231843318443184531846318473184831849318503185131852318533185431855318563185731858318593186031861318623186331864318653186631867318683186931870318713187231873318743187531876318773187831879318803188131882318833188431885318863188731888318893189031891318923189331894318953189631897318983189931900319013190231903319043190531906319073190831909319103191131912319133191431915319163191731918319193192031921319223192331924319253192631927319283192931930319313193231933319343193531936319373193831939319403194131942319433194431945319463194731948319493195031951319523195331954319553195631957319583195931960319613196231963319643196531966319673196831969319703197131972319733197431975319763197731978319793198031981319823198331984319853198631987319883198931990319913199231993319943199531996319973199831999320003200132002320033200432005320063200732008320093201032011320123201332014320153201632017320183201932020320213202232023320243202532026320273202832029320303203132032320333203432035320363203732038320393204032041320423204332044320453204632047320483204932050320513205232053320543205532056320573205832059320603206132062320633206432065320663206732068320693207032071320723207332074320753207632077320783207932080320813208232083320843208532086320873208832089320903209132092320933209432095320963209732098320993210032101321023210332104321053210632107321083210932110321113211232113321143211532116321173211832119321203212132122321233212432125321263212732128321293213032131321323213332134321353213632137321383213932140321413214232143321443214532146321473214832149321503215132152321533215432155321563215732158321593216032161321623216332164321653216632167321683216932170321713217232173321743217532176321773217832179321803218132182321833218432185321863218732188321893219032191321923219332194321953219632197321983219932200322013220232203322043220532206322073220832209322103221132212322133221432215322163221732218322193222032221322223222332224322253222632227322283222932230322313223232233322343223532236322373223832239322403224132242322433224432245322463224732248322493225032251322523225332254322553225632257322583225932260322613226232263322643226532266322673226832269322703227132272322733227432275322763227732278322793228032281322823228332284322853228632287322883228932290322913229232293322943229532296322973229832299323003230132302323033230432305323063230732308323093231032311323123231332314323153231632317323183231932320323213232232323323243232532326323273232832329323303233132332323333233432335323363233732338323393234032341323423234332344323453234632347323483234932350323513235232353323543235532356323573235832359323603236132362323633236432365323663236732368323693237032371323723237332374323753237632377323783237932380323813238232383323843238532386323873238832389323903239132392323933239432395323963239732398323993240032401324023240332404324053240632407324083240932410324113241232413324143241532416324173241832419324203242132422324233242432425324263242732428324293243032431324323243332434324353243632437324383243932440324413244232443324443244532446324473244832449324503245132452324533245432455324563245732458324593246032461324623246332464324653246632467324683246932470324713247232473324743247532476324773247832479324803248132482324833248432485324863248732488324893249032491324923249332494324953249632497324983249932500325013250232503325043250532506325073250832509325103251132512325133251432515325163251732518325193252032521325223252332524325253252632527325283252932530325313253232533325343253532536325373253832539325403254132542325433254432545325463254732548325493255032551325523255332554325553255632557325583255932560325613256232563325643256532566325673256832569325703257132572325733257432575325763257732578325793258032581325823258332584325853258632587325883258932590325913259232593325943259532596325973259832599326003260132602326033260432605326063260732608326093261032611326123261332614326153261632617326183261932620326213262232623326243262532626326273262832629326303263132632326333263432635326363263732638326393264032641326423264332644326453264632647326483264932650326513265232653326543265532656326573265832659326603266132662326633266432665326663266732668326693267032671326723267332674326753267632677326783267932680326813268232683326843268532686326873268832689326903269132692326933269432695326963269732698326993270032701327023270332704327053270632707327083270932710327113271232713327143271532716327173271832719327203272132722327233272432725327263272732728327293273032731327323273332734327353273632737327383273932740327413274232743327443274532746327473274832749327503275132752327533275432755327563275732758327593276032761327623276332764327653276632767327683276932770327713277232773327743277532776327773277832779327803278132782327833278432785327863278732788327893279032791327923279332794327953279632797327983279932800328013280232803328043280532806328073280832809328103281132812328133281432815328163281732818328193282032821328223282332824328253282632827328283282932830328313283232833328343283532836328373283832839328403284132842328433284432845328463284732848328493285032851328523285332854328553285632857328583285932860328613286232863328643286532866328673286832869328703287132872328733287432875328763287732878328793288032881328823288332884328853288632887328883288932890328913289232893328943289532896328973289832899329003290132902329033290432905329063290732908329093291032911329123291332914329153291632917329183291932920329213292232923329243292532926329273292832929329303293132932329333293432935329363293732938329393294032941329423294332944329453294632947329483294932950329513295232953329543295532956329573295832959329603296132962329633296432965329663296732968329693297032971329723297332974329753297632977329783297932980329813298232983329843298532986329873298832989329903299132992329933299432995329963299732998329993300033001330023300333004330053300633007330083300933010330113301233013330143301533016330173301833019330203302133022330233302433025330263302733028330293303033031330323303333034330353303633037330383303933040330413304233043330443304533046330473304833049330503305133052330533305433055330563305733058330593306033061330623306333064330653306633067330683306933070330713307233073330743307533076330773307833079330803308133082330833308433085330863308733088330893309033091330923309333094330953309633097330983309933100331013310233103331043310533106331073310833109331103311133112331133311433115331163311733118331193312033121331223312333124331253312633127331283312933130331313313233133331343313533136331373313833139331403314133142331433314433145331463314733148331493315033151331523315333154331553315633157331583315933160331613316233163331643316533166331673316833169331703317133172331733317433175331763317733178331793318033181331823318333184331853318633187331883318933190331913319233193331943319533196331973319833199332003320133202332033320433205332063320733208332093321033211332123321333214332153321633217332183321933220332213322233223332243322533226332273322833229332303323133232332333323433235332363323733238332393324033241332423324333244332453324633247332483324933250332513325233253332543325533256332573325833259332603326133262332633326433265332663326733268332693327033271332723327333274332753327633277332783327933280332813328233283332843328533286332873328833289332903329133292332933329433295332963329733298332993330033301333023330333304333053330633307333083330933310333113331233313333143331533316333173331833319333203332133322333233332433325333263332733328333293333033331333323333333334333353333633337333383333933340333413334233343333443334533346333473334833349333503335133352333533335433355333563335733358333593336033361333623336333364333653336633367333683336933370333713337233373333743337533376333773337833379333803338133382333833338433385333863338733388333893339033391333923339333394333953339633397333983339933400334013340233403334043340533406334073340833409334103341133412334133341433415334163341733418334193342033421334223342333424334253342633427334283342933430334313343233433334343343533436334373343833439334403344133442334433344433445334463344733448334493345033451334523345333454334553345633457334583345933460334613346233463334643346533466334673346833469334703347133472334733347433475334763347733478334793348033481334823348333484334853348633487334883348933490334913349233493334943349533496334973349833499335003350133502335033350433505335063350733508335093351033511335123351333514335153351633517335183351933520335213352233523335243352533526335273352833529335303353133532335333353433535335363353733538335393354033541335423354333544335453354633547335483354933550335513355233553335543355533556335573355833559335603356133562335633356433565335663356733568335693357033571335723357333574335753357633577335783357933580335813358233583335843358533586335873358833589335903359133592335933359433595335963359733598335993360033601336023360333604336053360633607336083360933610336113361233613336143361533616336173361833619336203362133622336233362433625336263362733628336293363033631336323363333634336353363633637336383363933640336413364233643336443364533646336473364833649336503365133652336533365433655336563365733658336593366033661336623366333664336653366633667336683366933670336713367233673336743367533676336773367833679336803368133682336833368433685336863368733688336893369033691336923369333694336953369633697336983369933700337013370233703337043370533706337073370833709337103371133712337133371433715337163371733718337193372033721337223372333724337253372633727337283372933730337313373233733337343373533736337373373833739337403374133742337433374433745337463374733748337493375033751337523375333754337553375633757337583375933760337613376233763337643376533766337673376833769337703377133772337733377433775337763377733778337793378033781337823378333784337853378633787337883378933790337913379233793337943379533796337973379833799338003380133802338033380433805338063380733808338093381033811338123381333814338153381633817338183381933820338213382233823338243382533826338273382833829338303383133832338333383433835338363383733838338393384033841338423384333844338453384633847338483384933850338513385233853338543385533856338573385833859338603386133862338633386433865338663386733868338693387033871338723387333874338753387633877338783387933880338813388233883338843388533886338873388833889338903389133892338933389433895338963389733898338993390033901339023390333904339053390633907339083390933910339113391233913339143391533916339173391833919339203392133922339233392433925339263392733928339293393033931339323393333934339353393633937339383393933940339413394233943339443394533946339473394833949339503395133952339533395433955339563395733958339593396033961339623396333964339653396633967339683396933970339713397233973339743397533976339773397833979339803398133982339833398433985339863398733988339893399033991339923399333994339953399633997339983399934000340013400234003340043400534006340073400834009340103401134012340133401434015340163401734018340193402034021340223402334024340253402634027340283402934030340313403234033340343403534036340373403834039340403404134042340433404434045340463404734048340493405034051340523405334054340553405634057340583405934060340613406234063340643406534066340673406834069340703407134072340733407434075340763407734078340793408034081340823408334084340853408634087340883408934090340913409234093340943409534096340973409834099341003410134102341033410434105341063410734108341093411034111341123411334114341153411634117341183411934120341213412234123341243412534126341273412834129341303413134132341333413434135341363413734138341393414034141341423414334144341453414634147341483414934150341513415234153341543415534156341573415834159341603416134162341633416434165341663416734168341693417034171341723417334174341753417634177341783417934180341813418234183341843418534186341873418834189341903419134192341933419434195341963419734198341993420034201342023420334204342053420634207342083420934210342113421234213342143421534216342173421834219342203422134222342233422434225342263422734228342293423034231342323423334234342353423634237342383423934240342413424234243342443424534246342473424834249342503425134252342533425434255342563425734258342593426034261342623426334264342653426634267342683426934270342713427234273342743427534276342773427834279342803428134282342833428434285342863428734288342893429034291342923429334294342953429634297342983429934300343013430234303343043430534306343073430834309343103431134312343133431434315343163431734318343193432034321343223432334324343253432634327343283432934330343313433234333343343433534336343373433834339343403434134342343433434434345343463434734348343493435034351343523435334354343553435634357343583435934360343613436234363343643436534366343673436834369343703437134372343733437434375343763437734378343793438034381343823438334384343853438634387343883438934390343913439234393343943439534396343973439834399344003440134402344033440434405344063440734408344093441034411344123441334414344153441634417344183441934420344213442234423344243442534426344273442834429344303443134432344333443434435344363443734438344393444034441344423444334444344453444634447344483444934450344513445234453344543445534456344573445834459344603446134462344633446434465344663446734468344693447034471344723447334474344753447634477344783447934480344813448234483344843448534486344873448834489344903449134492344933449434495344963449734498344993450034501345023450334504345053450634507345083450934510345113451234513345143451534516345173451834519345203452134522345233452434525345263452734528345293453034531345323453334534345353453634537345383453934540345413454234543345443454534546345473454834549345503455134552345533455434555345563455734558345593456034561345623456334564345653456634567345683456934570345713457234573345743457534576345773457834579345803458134582345833458434585345863458734588345893459034591345923459334594345953459634597345983459934600346013460234603346043460534606346073460834609346103461134612346133461434615346163461734618346193462034621346223462334624346253462634627346283462934630346313463234633346343463534636346373463834639346403464134642346433464434645346463464734648346493465034651346523465334654346553465634657346583465934660346613466234663346643466534666346673466834669346703467134672346733467434675346763467734678346793468034681346823468334684346853468634687346883468934690346913469234693346943469534696346973469834699347003470134702347033470434705347063470734708347093471034711347123471334714347153471634717347183471934720347213472234723347243472534726347273472834729347303473134732347333473434735347363473734738347393474034741347423474334744347453474634747347483474934750347513475234753347543475534756347573475834759347603476134762347633476434765347663476734768347693477034771347723477334774347753477634777347783477934780347813478234783347843478534786347873478834789347903479134792347933479434795347963479734798347993480034801348023480334804348053480634807348083480934810348113481234813348143481534816348173481834819348203482134822348233482434825348263482734828348293483034831348323483334834348353483634837348383483934840348413484234843348443484534846348473484834849348503485134852348533485434855348563485734858348593486034861348623486334864348653486634867348683486934870348713487234873348743487534876348773487834879348803488134882348833488434885348863488734888348893489034891348923489334894348953489634897348983489934900349013490234903349043490534906349073490834909349103491134912349133491434915349163491734918349193492034921349223492334924349253492634927349283492934930349313493234933349343493534936349373493834939349403494134942349433494434945349463494734948349493495034951349523495334954349553495634957349583495934960349613496234963349643496534966349673496834969349703497134972349733497434975349763497734978349793498034981349823498334984349853498634987349883498934990349913499234993349943499534996349973499834999350003500135002350033500435005350063500735008350093501035011350123501335014350153501635017350183501935020350213502235023350243502535026350273502835029350303503135032350333503435035350363503735038350393504035041350423504335044350453504635047350483504935050350513505235053350543505535056350573505835059350603506135062350633506435065350663506735068350693507035071350723507335074350753507635077350783507935080350813508235083350843508535086350873508835089350903509135092350933509435095350963509735098350993510035101351023510335104351053510635107351083510935110351113511235113351143511535116351173511835119351203512135122351233512435125351263512735128351293513035131351323513335134351353513635137351383513935140351413514235143351443514535146351473514835149351503515135152351533515435155351563515735158351593516035161351623516335164351653516635167351683516935170351713517235173351743517535176351773517835179351803518135182351833518435185351863518735188351893519035191351923519335194351953519635197351983519935200352013520235203352043520535206352073520835209352103521135212352133521435215352163521735218352193522035221352223522335224352253522635227352283522935230352313523235233352343523535236352373523835239352403524135242352433524435245352463524735248352493525035251352523525335254352553525635257352583525935260352613526235263352643526535266352673526835269352703527135272352733527435275352763527735278352793528035281352823528335284352853528635287352883528935290352913529235293352943529535296352973529835299353003530135302353033530435305353063530735308353093531035311353123531335314353153531635317353183531935320353213532235323353243532535326353273532835329353303533135332353333533435335353363533735338353393534035341353423534335344353453534635347353483534935350353513535235353353543535535356353573535835359353603536135362353633536435365353663536735368353693537035371353723537335374353753537635377353783537935380353813538235383353843538535386353873538835389353903539135392353933539435395353963539735398353993540035401354023540335404354053540635407354083540935410354113541235413354143541535416354173541835419354203542135422354233542435425354263542735428354293543035431354323543335434354353543635437354383543935440354413544235443354443544535446354473544835449354503545135452354533545435455354563545735458354593546035461354623546335464354653546635467354683546935470354713547235473354743547535476354773547835479354803548135482354833548435485354863548735488354893549035491354923549335494354953549635497354983549935500355013550235503355043550535506355073550835509355103551135512355133551435515355163551735518355193552035521355223552335524355253552635527355283552935530355313553235533355343553535536355373553835539355403554135542355433554435545355463554735548355493555035551355523555335554355553555635557355583555935560355613556235563355643556535566355673556835569355703557135572355733557435575355763557735578355793558035581355823558335584355853558635587355883558935590355913559235593355943559535596355973559835599356003560135602356033560435605356063560735608356093561035611356123561335614356153561635617356183561935620356213562235623356243562535626356273562835629356303563135632356333563435635356363563735638356393564035641356423564335644356453564635647356483564935650356513565235653356543565535656356573565835659356603566135662356633566435665356663566735668356693567035671356723567335674356753567635677356783567935680356813568235683356843568535686356873568835689356903569135692356933569435695356963569735698356993570035701357023570335704357053570635707357083570935710357113571235713357143571535716357173571835719357203572135722357233572435725357263572735728357293573035731357323573335734357353573635737357383573935740357413574235743357443574535746357473574835749357503575135752357533575435755357563575735758357593576035761357623576335764357653576635767357683576935770357713577235773357743577535776357773577835779357803578135782357833578435785357863578735788357893579035791357923579335794357953579635797357983579935800358013580235803358043580535806358073580835809358103581135812358133581435815358163581735818358193582035821358223582335824358253582635827358283582935830358313583235833358343583535836358373583835839358403584135842358433584435845358463584735848358493585035851358523585335854358553585635857358583585935860358613586235863358643586535866358673586835869358703587135872358733587435875358763587735878358793588035881358823588335884358853588635887358883588935890358913589235893358943589535896358973589835899359003590135902359033590435905359063590735908359093591035911359123591335914359153591635917359183591935920359213592235923359243592535926359273592835929359303593135932359333593435935359363593735938359393594035941359423594335944359453594635947359483594935950359513595235953359543595535956359573595835959359603596135962359633596435965359663596735968359693597035971359723597335974359753597635977359783597935980359813598235983359843598535986359873598835989359903599135992359933599435995359963599735998359993600036001360023600336004360053600636007360083600936010360113601236013360143601536016360173601836019360203602136022360233602436025360263602736028360293603036031360323603336034360353603636037360383603936040360413604236043360443604536046360473604836049360503605136052360533605436055360563605736058360593606036061360623606336064360653606636067360683606936070360713607236073360743607536076360773607836079360803608136082360833608436085360863608736088360893609036091360923609336094360953609636097360983609936100361013610236103361043610536106361073610836109361103611136112361133611436115361163611736118361193612036121361223612336124361253612636127361283612936130361313613236133361343613536136361373613836139361403614136142361433614436145361463614736148361493615036151361523615336154361553615636157361583615936160361613616236163361643616536166361673616836169361703617136172361733617436175361763617736178361793618036181361823618336184361853618636187361883618936190361913619236193361943619536196361973619836199362003620136202362033620436205362063620736208362093621036211362123621336214362153621636217362183621936220362213622236223362243622536226362273622836229362303623136232362333623436235362363623736238362393624036241362423624336244362453624636247362483624936250362513625236253362543625536256362573625836259362603626136262362633626436265362663626736268362693627036271362723627336274362753627636277362783627936280362813628236283362843628536286362873628836289362903629136292362933629436295362963629736298362993630036301363023630336304363053630636307363083630936310363113631236313363143631536316363173631836319363203632136322363233632436325363263632736328363293633036331363323633336334363353633636337363383633936340363413634236343363443634536346363473634836349363503635136352363533635436355363563635736358363593636036361363623636336364363653636636367363683636936370363713637236373363743637536376363773637836379363803638136382363833638436385363863638736388363893639036391363923639336394363953639636397363983639936400364013640236403364043640536406364073640836409364103641136412364133641436415364163641736418364193642036421364223642336424364253642636427364283642936430364313643236433364343643536436364373643836439364403644136442364433644436445364463644736448364493645036451364523645336454364553645636457364583645936460364613646236463364643646536466364673646836469364703647136472364733647436475364763647736478364793648036481364823648336484364853648636487364883648936490364913649236493364943649536496364973649836499365003650136502365033650436505365063650736508365093651036511365123651336514365153651636517365183651936520365213652236523365243652536526365273652836529365303653136532365333653436535365363653736538365393654036541365423654336544365453654636547365483654936550365513655236553365543655536556365573655836559365603656136562365633656436565365663656736568365693657036571365723657336574365753657636577365783657936580365813658236583365843658536586365873658836589365903659136592365933659436595365963659736598365993660036601366023660336604366053660636607366083660936610366113661236613366143661536616366173661836619366203662136622366233662436625366263662736628366293663036631366323663336634366353663636637366383663936640366413664236643366443664536646366473664836649366503665136652366533665436655366563665736658366593666036661366623666336664366653666636667366683666936670366713667236673366743667536676366773667836679366803668136682366833668436685366863668736688366893669036691366923669336694366953669636697366983669936700367013670236703367043670536706367073670836709367103671136712367133671436715367163671736718367193672036721367223672336724367253672636727367283672936730367313673236733367343673536736367373673836739367403674136742367433674436745367463674736748367493675036751367523675336754367553675636757367583675936760367613676236763367643676536766367673676836769367703677136772367733677436775367763677736778367793678036781367823678336784367853678636787367883678936790367913679236793367943679536796367973679836799368003680136802368033680436805368063680736808368093681036811368123681336814368153681636817368183681936820368213682236823368243682536826368273682836829368303683136832368333683436835368363683736838368393684036841368423684336844368453684636847368483684936850368513685236853368543685536856368573685836859368603686136862368633686436865368663686736868368693687036871368723687336874368753687636877368783687936880368813688236883368843688536886368873688836889368903689136892368933689436895368963689736898368993690036901369023690336904369053690636907369083690936910369113691236913369143691536916369173691836919369203692136922369233692436925369263692736928369293693036931369323693336934369353693636937369383693936940369413694236943369443694536946369473694836949369503695136952369533695436955369563695736958369593696036961369623696336964369653696636967369683696936970369713697236973369743697536976369773697836979369803698136982369833698436985369863698736988369893699036991369923699336994369953699636997369983699937000370013700237003370043700537006370073700837009370103701137012370133701437015370163701737018370193702037021370223702337024370253702637027370283702937030370313703237033370343703537036370373703837039370403704137042370433704437045370463704737048370493705037051370523705337054370553705637057370583705937060370613706237063370643706537066370673706837069370703707137072370733707437075370763707737078370793708037081370823708337084370853708637087370883708937090370913709237093370943709537096370973709837099371003710137102371033710437105371063710737108371093711037111371123711337114371153711637117371183711937120371213712237123371243712537126371273712837129371303713137132371333713437135371363713737138371393714037141371423714337144371453714637147371483714937150371513715237153371543715537156371573715837159371603716137162371633716437165371663716737168371693717037171371723717337174371753717637177371783717937180371813718237183371843718537186371873718837189371903719137192371933719437195371963719737198371993720037201372023720337204372053720637207372083720937210372113721237213372143721537216372173721837219372203722137222372233722437225372263722737228372293723037231372323723337234372353723637237372383723937240372413724237243372443724537246372473724837249372503725137252372533725437255372563725737258372593726037261372623726337264372653726637267372683726937270372713727237273372743727537276372773727837279372803728137282372833728437285372863728737288372893729037291372923729337294372953729637297372983729937300373013730237303373043730537306373073730837309373103731137312373133731437315373163731737318373193732037321373223732337324373253732637327373283732937330373313733237333373343733537336373373733837339373403734137342373433734437345373463734737348373493735037351373523735337354373553735637357373583735937360373613736237363373643736537366373673736837369373703737137372373733737437375373763737737378373793738037381373823738337384373853738637387373883738937390373913739237393373943739537396373973739837399374003740137402374033740437405374063740737408374093741037411374123741337414374153741637417374183741937420374213742237423374243742537426374273742837429374303743137432374333743437435374363743737438374393744037441374423744337444374453744637447374483744937450374513745237453374543745537456374573745837459374603746137462374633746437465374663746737468374693747037471374723747337474374753747637477374783747937480374813748237483374843748537486374873748837489374903749137492374933749437495374963749737498374993750037501375023750337504375053750637507375083750937510375113751237513375143751537516375173751837519375203752137522375233752437525375263752737528375293753037531375323753337534375353753637537375383753937540375413754237543375443754537546375473754837549375503755137552375533755437555375563755737558375593756037561375623756337564375653756637567375683756937570375713757237573375743757537576375773757837579375803758137582375833758437585375863758737588375893759037591375923759337594375953759637597375983759937600376013760237603376043760537606376073760837609376103761137612376133761437615376163761737618376193762037621376223762337624376253762637627376283762937630376313763237633376343763537636376373763837639376403764137642376433764437645376463764737648376493765037651376523765337654376553765637657376583765937660376613766237663376643766537666376673766837669376703767137672376733767437675376763767737678376793768037681376823768337684376853768637687376883768937690376913769237693376943769537696376973769837699377003770137702377033770437705377063770737708377093771037711377123771337714377153771637717377183771937720377213772237723377243772537726377273772837729377303773137732377333773437735377363773737738377393774037741377423774337744377453774637747377483774937750377513775237753377543775537756377573775837759377603776137762377633776437765377663776737768377693777037771377723777337774377753777637777377783777937780377813778237783377843778537786377873778837789377903779137792377933779437795377963779737798377993780037801378023780337804378053780637807378083780937810378113781237813378143781537816378173781837819378203782137822378233782437825378263782737828378293783037831378323783337834378353783637837378383783937840378413784237843378443784537846378473784837849378503785137852378533785437855378563785737858378593786037861378623786337864378653786637867378683786937870378713787237873378743787537876378773787837879378803788137882378833788437885378863788737888378893789037891378923789337894378953789637897378983789937900379013790237903379043790537906379073790837909379103791137912379133791437915379163791737918379193792037921379223792337924379253792637927379283792937930379313793237933379343793537936379373793837939379403794137942379433794437945379463794737948379493795037951379523795337954379553795637957379583795937960379613796237963379643796537966379673796837969379703797137972379733797437975379763797737978379793798037981379823798337984379853798637987379883798937990379913799237993379943799537996379973799837999380003800138002380033800438005380063800738008380093801038011380123801338014380153801638017380183801938020380213802238023380243802538026380273802838029380303803138032380333803438035380363803738038380393804038041380423804338044380453804638047380483804938050380513805238053380543805538056380573805838059380603806138062380633806438065380663806738068380693807038071380723807338074380753807638077380783807938080380813808238083380843808538086380873808838089380903809138092380933809438095380963809738098380993810038101381023810338104381053810638107381083810938110381113811238113381143811538116381173811838119381203812138122381233812438125381263812738128381293813038131381323813338134381353813638137381383813938140381413814238143381443814538146381473814838149381503815138152381533815438155381563815738158381593816038161381623816338164381653816638167381683816938170381713817238173381743817538176381773817838179381803818138182381833818438185381863818738188381893819038191381923819338194381953819638197381983819938200382013820238203382043820538206382073820838209382103821138212382133821438215382163821738218382193822038221382223822338224382253822638227382283822938230382313823238233382343823538236382373823838239382403824138242382433824438245382463824738248382493825038251382523825338254382553825638257382583825938260382613826238263382643826538266382673826838269382703827138272382733827438275382763827738278382793828038281382823828338284382853828638287382883828938290382913829238293382943829538296382973829838299383003830138302383033830438305383063830738308383093831038311383123831338314383153831638317383183831938320383213832238323383243832538326383273832838329383303833138332383333833438335383363833738338383393834038341383423834338344383453834638347383483834938350383513835238353383543835538356383573835838359383603836138362383633836438365383663836738368383693837038371383723837338374383753837638377383783837938380383813838238383383843838538386383873838838389383903839138392383933839438395383963839738398383993840038401384023840338404384053840638407384083840938410384113841238413384143841538416384173841838419384203842138422384233842438425384263842738428384293843038431384323843338434384353843638437384383843938440384413844238443384443844538446384473844838449384503845138452384533845438455384563845738458384593846038461384623846338464384653846638467384683846938470384713847238473384743847538476384773847838479384803848138482384833848438485384863848738488384893849038491384923849338494384953849638497384983849938500385013850238503385043850538506385073850838509385103851138512385133851438515385163851738518385193852038521385223852338524385253852638527385283852938530385313853238533385343853538536385373853838539385403854138542385433854438545385463854738548385493855038551385523855338554385553855638557385583855938560385613856238563385643856538566385673856838569385703857138572385733857438575385763857738578385793858038581385823858338584385853858638587385883858938590385913859238593385943859538596385973859838599386003860138602386033860438605386063860738608386093861038611386123861338614386153861638617386183861938620386213862238623386243862538626386273862838629386303863138632386333863438635386363863738638386393864038641386423864338644386453864638647386483864938650386513865238653386543865538656386573865838659386603866138662386633866438665386663866738668386693867038671386723867338674386753867638677386783867938680386813868238683386843868538686386873868838689386903869138692386933869438695386963869738698386993870038701387023870338704387053870638707387083870938710387113871238713387143871538716387173871838719387203872138722387233872438725387263872738728387293873038731387323873338734387353873638737387383873938740387413874238743387443874538746387473874838749387503875138752387533875438755387563875738758387593876038761387623876338764387653876638767387683876938770387713877238773387743877538776387773877838779387803878138782387833878438785387863878738788387893879038791387923879338794387953879638797387983879938800388013880238803388043880538806388073880838809388103881138812388133881438815388163881738818388193882038821388223882338824388253882638827388283882938830388313883238833388343883538836388373883838839388403884138842388433884438845388463884738848388493885038851388523885338854388553885638857388583885938860388613886238863388643886538866388673886838869388703887138872388733887438875388763887738878388793888038881388823888338884388853888638887388883888938890388913889238893388943889538896388973889838899389003890138902389033890438905389063890738908389093891038911389123891338914389153891638917389183891938920389213892238923389243892538926389273892838929389303893138932389333893438935389363893738938389393894038941389423894338944389453894638947389483894938950389513895238953389543895538956389573895838959389603896138962389633896438965389663896738968389693897038971389723897338974389753897638977389783897938980389813898238983389843898538986389873898838989389903899138992389933899438995389963899738998389993900039001390023900339004390053900639007390083900939010390113901239013390143901539016390173901839019390203902139022390233902439025390263902739028390293903039031390323903339034390353903639037390383903939040390413904239043390443904539046390473904839049390503905139052390533905439055390563905739058390593906039061390623906339064390653906639067390683906939070390713907239073390743907539076390773907839079390803908139082390833908439085390863908739088390893909039091390923909339094390953909639097390983909939100391013910239103391043910539106391073910839109391103911139112391133911439115391163911739118391193912039121391223912339124391253912639127391283912939130391313913239133391343913539136391373913839139391403914139142391433914439145391463914739148391493915039151391523915339154391553915639157391583915939160391613916239163391643916539166391673916839169391703917139172391733917439175391763917739178391793918039181391823918339184391853918639187391883918939190391913919239193391943919539196391973919839199392003920139202392033920439205392063920739208392093921039211392123921339214392153921639217392183921939220392213922239223392243922539226392273922839229392303923139232392333923439235392363923739238392393924039241392423924339244392453924639247392483924939250392513925239253392543925539256392573925839259392603926139262392633926439265392663926739268392693927039271392723927339274392753927639277392783927939280392813928239283392843928539286392873928839289392903929139292392933929439295392963929739298392993930039301393023930339304393053930639307393083930939310393113931239313393143931539316393173931839319393203932139322393233932439325393263932739328393293933039331393323933339334393353933639337393383933939340393413934239343393443934539346393473934839349393503935139352393533935439355393563935739358393593936039361393623936339364393653936639367393683936939370393713937239373393743937539376393773937839379393803938139382393833938439385393863938739388393893939039391393923939339394393953939639397393983939939400394013940239403394043940539406394073940839409394103941139412394133941439415394163941739418394193942039421394223942339424394253942639427394283942939430394313943239433394343943539436394373943839439394403944139442394433944439445394463944739448394493945039451394523945339454394553945639457394583945939460394613946239463394643946539466394673946839469394703947139472394733947439475394763947739478394793948039481394823948339484394853948639487394883948939490394913949239493394943949539496394973949839499395003950139502395033950439505395063950739508395093951039511395123951339514395153951639517395183951939520395213952239523395243952539526395273952839529395303953139532395333953439535395363953739538395393954039541395423954339544395453954639547395483954939550395513955239553395543955539556395573955839559395603956139562395633956439565395663956739568395693957039571395723957339574395753957639577395783957939580395813958239583395843958539586395873958839589395903959139592395933959439595395963959739598395993960039601396023960339604396053960639607396083960939610396113961239613396143961539616396173961839619396203962139622396233962439625396263962739628396293963039631396323963339634396353963639637396383963939640396413964239643396443964539646396473964839649396503965139652396533965439655396563965739658396593966039661396623966339664396653966639667396683966939670396713967239673396743967539676396773967839679396803968139682396833968439685396863968739688396893969039691396923969339694396953969639697396983969939700397013970239703397043970539706397073970839709397103971139712397133971439715397163971739718397193972039721397223972339724397253972639727397283972939730397313973239733397343973539736397373973839739397403974139742397433974439745397463974739748397493975039751397523975339754397553975639757397583975939760397613976239763397643976539766397673976839769397703977139772397733977439775397763977739778397793978039781397823978339784397853978639787397883978939790397913979239793397943979539796397973979839799398003980139802398033980439805398063980739808398093981039811398123981339814398153981639817398183981939820398213982239823398243982539826398273982839829398303983139832398333983439835398363983739838398393984039841398423984339844398453984639847398483984939850398513985239853398543985539856398573985839859398603986139862398633986439865398663986739868398693987039871398723987339874398753987639877398783987939880398813988239883398843988539886398873988839889398903989139892398933989439895398963989739898398993990039901399023990339904399053990639907399083990939910399113991239913399143991539916399173991839919399203992139922399233992439925399263992739928399293993039931399323993339934399353993639937399383993939940 |
- \input texinfo
- @c -*-texinfo-*-
- @c %**start of header
- @setfilename guix.info
- @documentencoding UTF-8
- @settitle GNU Guix Reference Manual
- @c %**end of header
- @include version.texi
- @c Identifier of the OpenPGP key used to sign tarballs and such.
- @set OPENPGP-SIGNING-KEY-ID 27D586A4F8900854329FF09F1260E46482E63562
- @set OPENPGP-SIGNING-KEY-URL https://sv.gnu.org/people/viewgpg.php?user_id=127547
- @c Base URL for downloads.
- @set BASE-URL https://ftp.gnu.org/gnu/guix
- @c The official substitute server used by default.
- @set SUBSTITUTE-SERVER-1 ci.guix.gnu.org
- @set SUBSTITUTE-SERVER-2 bordeaux.guix.gnu.org
- @set SUBSTITUTE-URLS https://@value{SUBSTITUTE-SERVER-1} https://@value{SUBSTITUTE-SERVER-2}
- @copying
- Copyright @copyright{} 2012-2022 Ludovic Courtès@*
- Copyright @copyright{} 2013, 2014, 2016 Andreas Enge@*
- Copyright @copyright{} 2013 Nikita Karetnikov@*
- Copyright @copyright{} 2014, 2015, 2016 Alex Kost@*
- Copyright @copyright{} 2015, 2016 Mathieu Lirzin@*
- Copyright @copyright{} 2014 Pierre-Antoine Rault@*
- Copyright @copyright{} 2015 Taylan Ulrich Bayırlı/Kammer@*
- Copyright @copyright{} 2015, 2016, 2017, 2019, 2020, 2021 Leo Famulari@*
- Copyright @copyright{} 2015, 2016, 2017, 2018, 2019, 2020, 2021 Ricardo Wurmus@*
- Copyright @copyright{} 2016 Ben Woodcroft@*
- Copyright @copyright{} 2016, 2017, 2018, 2021 Chris Marusich@*
- Copyright @copyright{} 2016, 2017, 2018, 2019, 2020, 2021, 2022 Efraim Flashner@*
- Copyright @copyright{} 2016 John Darrington@*
- Copyright @copyright{} 2016, 2017 Nikita Gillmann@*
- Copyright @copyright{} 2016, 2017, 2018, 2019, 2020 Jan Nieuwenhuizen@*
- Copyright @copyright{} 2016, 2017, 2018, 2019, 2020, 2021 Julien Lepiller@*
- Copyright @copyright{} 2016 Alex ter Weele@*
- Copyright @copyright{} 2016, 2017, 2018, 2019, 2020, 2021 Christopher Baines@*
- Copyright @copyright{} 2017, 2018, 2019 Clément Lassieur@*
- Copyright @copyright{} 2017, 2018, 2020, 2021 Mathieu Othacehe@*
- Copyright @copyright{} 2017 Federico Beffa@*
- Copyright @copyright{} 2017, 2018 Carlo Zancanaro@*
- Copyright @copyright{} 2017 Thomas Danckaert@*
- Copyright @copyright{} 2017 humanitiesNerd@*
- Copyright @copyright{} 2017, 2021 Christine Lemmer-Webber@*
- Copyright @copyright{} 2017, 2018, 2019, 2020, 2021, 2022 Marius Bakke@*
- Copyright @copyright{} 2017, 2019, 2020 Hartmut Goebel@*
- Copyright @copyright{} 2017, 2019, 2020, 2021 Maxim Cournoyer@*
- Copyright @copyright{} 2017–2022 Tobias Geerinckx-Rice@*
- Copyright @copyright{} 2017 George Clemmer@*
- Copyright @copyright{} 2017 Andy Wingo@*
- Copyright @copyright{} 2017, 2018, 2019, 2020 Arun Isaac@*
- Copyright @copyright{} 2017 nee@*
- Copyright @copyright{} 2018 Rutger Helling@*
- Copyright @copyright{} 2018, 2021 Oleg Pykhalov@*
- Copyright @copyright{} 2018 Mike Gerwitz@*
- Copyright @copyright{} 2018 Pierre-Antoine Rouby@*
- Copyright @copyright{} 2018, 2019 Gábor Boskovits@*
- Copyright @copyright{} 2018, 2019, 2020 Florian Pelz@*
- Copyright @copyright{} 2018 Laura Lazzati@*
- Copyright @copyright{} 2018 Alex Vong@*
- Copyright @copyright{} 2019 Josh Holland@*
- Copyright @copyright{} 2019, 2020 Diego Nicola Barbato@*
- Copyright @copyright{} 2019 Ivan Petkov@*
- Copyright @copyright{} 2019 Jakob L. Kreuze@*
- Copyright @copyright{} 2019 Kyle Andrews@*
- Copyright @copyright{} 2019 Alex Griffin@*
- Copyright @copyright{} 2019, 2020, 2021, 2022 Guillaume Le Vaillant@*
- Copyright @copyright{} 2020 Liliana Marie Prikler@*
- Copyright @copyright{} 2019, 2020, 2021, 2022 Simon Tournier@*
- Copyright @copyright{} 2020 Wiktor Żelazny@*
- Copyright @copyright{} 2020 Damien Cassou@*
- Copyright @copyright{} 2020 Jakub Kądziołka@*
- Copyright @copyright{} 2020 Jack Hill@*
- Copyright @copyright{} 2020 Naga Malleswari@*
- Copyright @copyright{} 2020, 2021 Brice Waegeneire@*
- Copyright @copyright{} 2020 R Veera Kumar@*
- Copyright @copyright{} 2020, 2021 Pierre Langlois@*
- Copyright @copyright{} 2020 pinoaffe@*
- Copyright @copyright{} 2020 André Batista@*
- Copyright @copyright{} 2020, 2021 Alexandru-Sergiu Marton@*
- Copyright @copyright{} 2020 raingloom@*
- Copyright @copyright{} 2020 Daniel Brooks@*
- Copyright @copyright{} 2020 John Soo@*
- Copyright @copyright{} 2020 Jonathan Brielmaier@*
- Copyright @copyright{} 2020 Edgar Vincent@*
- Copyright @copyright{} 2021 Maxime Devos@*
- Copyright @copyright{} 2021 B. Wilson@*
- Copyright @copyright{} 2021 Xinglu Chen@*
- Copyright @copyright{} 2021 Raghav Gururajan@*
- Copyright @copyright{} 2021 Domagoj Stolfa@*
- Copyright @copyright{} 2021 Hui Lu@*
- Copyright @copyright{} 2021 pukkamustard@*
- Copyright @copyright{} 2021 Alice Brenon@*
- Copyright @copyright{} 2021 Josselin Poiret@*
- Copyright @copyright{} 2021 Andrew Tropin@*
- Copyright @copyright{} 2021 Sarah Morgensen@*
- Copyright @copyright{} 2021 Josselin Poiret@*
- Copyright @copyright{} 2022 Remco van 't Veer@*
- Copyright @copyright{} 2022 Aleksandr Vityazev@*
- Permission is granted to copy, distribute and/or modify this document
- under the terms of the GNU Free Documentation License, Version 1.3 or
- any later version published by the Free Software Foundation; with no
- Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
- copy of the license is included in the section entitled ``GNU Free
- Documentation License''.
- @end copying
- @dircategory System administration
- @direntry
- * Guix: (guix). Manage installed software and system configuration.
- * guix package: (guix)Invoking guix package. Installing, removing, and upgrading packages.
- * guix gc: (guix)Invoking guix gc. Reclaiming unused disk space.
- * guix pull: (guix)Invoking guix pull. Update the list of available packages.
- * guix system: (guix)Invoking guix system. Manage the operating system configuration.
- * guix deploy: (guix)Invoking guix deploy. Manage operating system configurations for remote hosts.
- @end direntry
- @dircategory Software development
- @direntry
- * guix shell: (guix)Invoking guix shell. Creating software environments.
- * guix environment: (guix)Invoking guix environment. Building development environments with Guix.
- * guix build: (guix)Invoking guix build. Building packages.
- * guix pack: (guix)Invoking guix pack. Creating binary bundles.
- @end direntry
- @titlepage
- @title GNU Guix Reference Manual
- @subtitle Using the GNU Guix Functional Package Manager
- @author The GNU Guix Developers
- @page
- @vskip 0pt plus 1filll
- Edition @value{EDITION} @*
- @value{UPDATED} @*
- @insertcopying
- @end titlepage
- @contents
- @c *********************************************************************
- @node Top
- @top GNU Guix
- This document describes GNU Guix version @value{VERSION}, a functional
- package management tool written for the GNU system.
- @c TRANSLATORS: You can replace the following paragraph with information on
- @c how to join your own translation team and how to report issues with the
- @c translation.
- This manual is also available in Simplified Chinese (@pxref{Top,,, guix.zh_CN,
- GNU Guix参考手册}), French (@pxref{Top,,, guix.fr, Manuel de référence de GNU
- Guix}), German (@pxref{Top,,, guix.de, Referenzhandbuch zu GNU Guix}),
- Spanish (@pxref{Top,,, guix.es, Manual de referencia de GNU Guix}), and
- Russian (@pxref{Top,,, guix.ru, Руководство GNU Guix}). If you
- would like to translate it in your native language, consider joining
- @uref{https://translate.fedoraproject.org/projects/guix/documentation-manual,
- Weblate} (@pxref{Translating Guix}).
- @menu
- * Introduction:: What is Guix about?
- * Installation:: Installing Guix.
- * System Installation:: Installing the whole operating system.
- * Getting Started:: Your first steps.
- * Package Management:: Package installation, upgrade, etc.
- * Channels:: Customizing the package collection.
- * Development:: Guix-aided software development.
- * Programming Interface:: Using Guix in Scheme.
- * Utilities:: Package management commands.
- * System Configuration:: Configuring the operating system.
- * Home Configuration:: Configuring the home environment.
- * Documentation:: Browsing software user manuals.
- * Installing Debugging Files:: Feeding the debugger.
- * Using TeX and LaTeX:: Typesetting.
- * Security Updates:: Deploying security fixes quickly.
- * Bootstrapping:: GNU/Linux built from scratch.
- * Porting:: Targeting another platform or kernel.
- * Contributing:: Your help needed!
- * Acknowledgments:: Thanks!
- * GNU Free Documentation License:: The license of this manual.
- * Concept Index:: Concepts.
- * Programming Index:: Data types, functions, and variables.
- @detailmenu
- --- The Detailed Node Listing ---
- Introduction
- * Managing Software the Guix Way:: What's special.
- * GNU Distribution:: The packages and tools.
- Installation
- * Binary Installation:: Getting Guix running in no time!
- * Requirements:: Software needed to build and run Guix.
- * Running the Test Suite:: Testing Guix.
- * Setting Up the Daemon:: Preparing the build daemon's environment.
- * Invoking guix-daemon:: Running the build daemon.
- * Application Setup:: Application-specific setup.
- * Upgrading Guix:: Upgrading Guix and its build daemon.
- Setting Up the Daemon
- * Build Environment Setup:: Preparing the isolated build environment.
- * Daemon Offload Setup:: Offloading builds to remote machines.
- * SELinux Support:: Using an SELinux policy for the daemon.
- System Installation
- * Limitations:: What you can expect.
- * Hardware Considerations:: Supported hardware.
- * USB Stick and DVD Installation:: Preparing the installation medium.
- * Preparing for Installation:: Networking, partitioning, etc.
- * Guided Graphical Installation:: Easy graphical installation.
- * Manual Installation:: Manual installation for wizards.
- * After System Installation:: When installation succeeded.
- * Installing Guix in a VM:: Guix System playground.
- * Building the Installation Image:: How this comes to be.
- Manual Installation
- * Keyboard Layout and Networking and Partitioning:: Initial setup.
- * Proceeding with the Installation:: Installing.
- Package Management
- * Features:: How Guix will make your life brighter.
- * Invoking guix package:: Package installation, removal, etc.
- * Substitutes:: Downloading pre-built binaries.
- * Packages with Multiple Outputs:: Single source package, multiple outputs.
- * Invoking guix gc:: Running the garbage collector.
- * Invoking guix pull:: Fetching the latest Guix and distribution.
- * Invoking guix time-machine:: Running an older revision of Guix.
- * Inferiors:: Interacting with another revision of Guix.
- * Invoking guix describe:: Display information about your Guix revision.
- * Invoking guix archive:: Exporting and importing store files.
- Substitutes
- * Official Substitute Servers:: One particular source of substitutes.
- * Substitute Server Authorization:: How to enable or disable substitutes.
- * Getting Substitutes from Other Servers:: Substitute diversity.
- * Substitute Authentication:: How Guix verifies substitutes.
- * Proxy Settings:: How to get substitutes via proxy.
- * Substitution Failure:: What happens when substitution fails.
- * On Trusting Binaries:: How can you trust that binary blob?
- Channels
- * Specifying Additional Channels:: Extending the package collection.
- * Using a Custom Guix Channel:: Using a customized Guix.
- * Replicating Guix:: Running the @emph{exact same} Guix.
- * Channel Authentication:: How Guix verifies what it fetches.
- * Channels with Substitutes:: Using channels with available substitutes.
- * Creating a Channel:: How to write your custom channel.
- * Package Modules in a Sub-directory:: Specifying the channel's package modules location.
- * Declaring Channel Dependencies:: How to depend on other channels.
- * Specifying Channel Authorizations:: Defining channel authors authorizations.
- * Primary URL:: Distinguishing mirror to original.
- * Writing Channel News:: Communicating information to channel's users.
- Development
- * Invoking guix shell:: Spawning one-off software environments.
- * Invoking guix environment:: Setting up development environments.
- * Invoking guix pack:: Creating software bundles.
- * The GCC toolchain:: Working with languages supported by GCC.
- * Invoking guix git authenticate:: Authenticating Git repositories.
- Programming Interface
- * Package Modules:: Packages from the programmer's viewpoint.
- * Defining Packages:: Defining new packages.
- * Defining Package Variants:: Customizing packages.
- * Build Systems:: Specifying how packages are built.
- * Build Phases:: Phases of the build process of a package.
- * Build Utilities:: Helpers for your package definitions and more.
- * Search Paths:: Declaring search path environment variables.
- * The Store:: Manipulating the package store.
- * Derivations:: Low-level interface to package derivations.
- * The Store Monad:: Purely functional interface to the store.
- * G-Expressions:: Manipulating build expressions.
- * Invoking guix repl:: Programming Guix in Guile.
- Defining Packages
- * package Reference:: The package data type.
- * origin Reference:: The origin data type.
- Utilities
- * Invoking guix build:: Building packages from the command line.
- * Invoking guix edit:: Editing package definitions.
- * Invoking guix download:: Downloading a file and printing its hash.
- * Invoking guix hash:: Computing the cryptographic hash of a file.
- * Invoking guix import:: Importing package definitions.
- * Invoking guix refresh:: Updating package definitions.
- * Invoking guix style:: Styling package definitions.
- * Invoking guix lint:: Finding errors in package definitions.
- * Invoking guix size:: Profiling disk usage.
- * Invoking guix graph:: Visualizing the graph of packages.
- * Invoking guix publish:: Sharing substitutes.
- * Invoking guix challenge:: Challenging substitute servers.
- * Invoking guix copy:: Copying to and from a remote store.
- * Invoking guix container:: Process isolation.
- * Invoking guix weather:: Assessing substitute availability.
- * Invoking guix processes:: Listing client processes.
- Invoking @command{guix build}
- * Common Build Options:: Build options for most commands.
- * Package Transformation Options:: Creating variants of packages.
- * Additional Build Options:: Options specific to 'guix build'.
- * Debugging Build Failures:: Real life packaging experience.
- System Configuration
- * Using the Configuration System:: Customizing your GNU system.
- * operating-system Reference:: Detail of operating-system declarations.
- * File Systems:: Configuring file system mounts.
- * Mapped Devices:: Block device extra processing.
- * Swap Space:: Backing RAM with disk space.
- * User Accounts:: Specifying user accounts.
- * Keyboard Layout:: How the system interprets key strokes.
- * Locales:: Language and cultural convention settings.
- * Services:: Specifying system services.
- * Setuid Programs:: Programs running with root privileges.
- * X.509 Certificates:: Authenticating HTTPS servers.
- * Name Service Switch:: Configuring libc's name service switch.
- * Initial RAM Disk:: Linux-Libre bootstrapping.
- * Bootloader Configuration:: Configuring the boot loader.
- * Invoking guix system:: Instantiating a system configuration.
- * Invoking guix deploy:: Deploying a system configuration to a remote host.
- * Running Guix in a VM:: How to run Guix System in a virtual machine.
- * Defining Services:: Adding new service definitions.
- Home Environment Configuration
- * Invoking guix home:: Instantiating a home environment configuration.
- Services
- * Base Services:: Essential system services.
- * Scheduled Job Execution:: The mcron service.
- * Log Rotation:: The rottlog service.
- * Networking Setup:: Setting up network interfaces.
- * Networking Services:: Firewall, SSH daemon, etc.
- * Unattended Upgrades:: Automated system upgrades.
- * X Window:: Graphical display.
- * Printing Services:: Local and remote printer support.
- * Desktop Services:: D-Bus and desktop services.
- * Sound Services:: ALSA and Pulseaudio services.
- * Database Services:: SQL databases, key-value stores, etc.
- * Mail Services:: IMAP, POP3, SMTP, and all that.
- * Messaging Services:: Messaging services.
- * Telephony Services:: Telephony services.
- * Monitoring Services:: Monitoring services.
- * Kerberos Services:: Kerberos services.
- * LDAP Services:: LDAP services.
- * Web Services:: Web servers.
- * Certificate Services:: TLS certificates via Let's Encrypt.
- * DNS Services:: DNS daemons.
- * VPN Services:: VPN daemons.
- * Network File System:: NFS related services.
- * Continuous Integration:: Cuirass and Laminar services.
- * Power Management Services:: Extending battery life.
- * Audio Services:: The MPD.
- * Virtualization Services:: Virtualization services.
- * Version Control Services:: Providing remote access to Git repositories.
- * Game Services:: Game servers.
- * PAM Mount Service:: Service to mount volumes when logging in.
- * Guix Services:: Services relating specifically to Guix.
- * Linux Services:: Services tied to the Linux kernel.
- * Hurd Services:: Services specific for a Hurd System.
- * Miscellaneous Services:: Other services.
- Defining Services
- * Service Composition:: The model for composing services.
- * Service Types and Services:: Types and services.
- * Service Reference:: API reference.
- * Shepherd Services:: A particular type of service.
- * Complex Configurations:: Defining bindings for complex configurations.
- Installing Debugging Files
- * Separate Debug Info:: Installing 'debug' outputs.
- * Rebuilding Debug Info:: Building missing debug info.
- Bootstrapping
- * Reduced Binary Seed Bootstrap:: A Bootstrap worthy of GNU.
- * Preparing to Use the Bootstrap Binaries:: Building that what matters most.
- @end detailmenu
- @end menu
- @c *********************************************************************
- @node Introduction
- @chapter Introduction
- @cindex purpose
- GNU Guix@footnote{``Guix'' is pronounced like ``geeks'', or ``ɡiːks''
- using the international phonetic alphabet (IPA).} is a package
- management tool for and distribution of the GNU system.
- Guix makes it easy for unprivileged
- users to install, upgrade, or remove software packages, to roll back to a
- previous package set, to build packages from source, and generally
- assists with the creation and maintenance of software environments.
- @cindex Guix System
- @cindex GuixSD, now Guix System
- @cindex Guix System Distribution, now Guix System
- You can install GNU@tie{}Guix on top of an existing GNU/Linux system where it
- complements the available tools without interference (@pxref{Installation}),
- or you can use it as a standalone operating system distribution,
- @dfn{Guix@tie{}System}@footnote{We used to refer to Guix System as ``Guix
- System Distribution'' or ``GuixSD''. We now consider it makes more sense to
- group everything under the ``Guix'' banner since, after all, Guix System is
- readily available through the @command{guix system} command, even if you're
- using a different distro underneath!}. @xref{GNU Distribution}.
- @menu
- * Managing Software the Guix Way:: What's special.
- * GNU Distribution:: The packages and tools.
- @end menu
- @node Managing Software the Guix Way
- @section Managing Software the Guix Way
- @cindex user interfaces
- Guix provides a command-line package management interface
- (@pxref{Package Management}), tools to help with software development
- (@pxref{Development}), command-line utilities for more advanced usage
- (@pxref{Utilities}), as well as Scheme programming interfaces
- (@pxref{Programming Interface}).
- @cindex build daemon
- Its @dfn{build daemon} is responsible for building packages on behalf of
- users (@pxref{Setting Up the Daemon}) and for downloading pre-built
- binaries from authorized sources (@pxref{Substitutes}).
- @cindex extensibility of the distribution
- @cindex customization, of packages
- Guix includes package definitions for many GNU and non-GNU packages, all
- of which @uref{https://www.gnu.org/philosophy/free-sw.html, respect the
- user's computing freedom}. It is @emph{extensible}: users can write
- their own package definitions (@pxref{Defining Packages}) and make them
- available as independent package modules (@pxref{Package Modules}). It
- is also @emph{customizable}: users can @emph{derive} specialized package
- definitions from existing ones, including from the command line
- (@pxref{Package Transformation Options}).
- @cindex functional package management
- @cindex isolation
- Under the hood, Guix implements the @dfn{functional package management}
- discipline pioneered by Nix (@pxref{Acknowledgments}).
- In Guix, the package build and installation process is seen
- as a @emph{function}, in the mathematical sense. That function takes inputs,
- such as build scripts, a compiler, and libraries, and
- returns an installed package. As a pure function, its result depends
- solely on its inputs---for instance, it cannot refer to software or
- scripts that were not explicitly passed as inputs. A build function
- always produces the same result when passed a given set of inputs. It
- cannot alter the environment of the running system in
- any way; for instance, it cannot create, modify, or delete files outside
- of its build and installation directories. This is achieved by running
- build processes in isolated environments (or @dfn{containers}), where only their
- explicit inputs are visible.
- @cindex store
- The result of package build functions is @dfn{cached} in the file
- system, in a special directory called @dfn{the store} (@pxref{The
- Store}). Each package is installed in a directory of its own in the
- store---by default under @file{/gnu/store}. The directory name contains
- a hash of all the inputs used to build that package; thus, changing an
- input yields a different directory name.
- This approach is the foundation for the salient features of Guix: support
- for transactional package upgrade and rollback, per-user installation, and
- garbage collection of packages (@pxref{Features}).
- @node GNU Distribution
- @section GNU Distribution
- @cindex Guix System
- Guix comes with a distribution of the GNU system consisting entirely of
- free software@footnote{The term ``free'' here refers to the
- @url{https://www.gnu.org/philosophy/free-sw.html,freedom provided to
- users of that software}.}. The
- distribution can be installed on its own (@pxref{System Installation}),
- but it is also possible to install Guix as a package manager on top of
- an installed GNU/Linux system (@pxref{Installation}). When we need to
- distinguish between the two, we refer to the standalone distribution as
- Guix@tie{}System.
- The distribution provides core GNU packages such as GNU libc, GCC, and
- Binutils, as well as many GNU and non-GNU applications. The complete
- list of available packages can be browsed
- @url{https://www.gnu.org/software/guix/packages,on-line} or by
- running @command{guix package} (@pxref{Invoking guix package}):
- @example
- guix package --list-available
- @end example
- Our goal is to provide a practical 100% free software distribution of
- Linux-based and other variants of GNU, with a focus on the promotion and
- tight integration of GNU components, and an emphasis on programs and
- tools that help users exert that freedom.
- Packages are currently available on the following platforms:
- @table @code
- @item x86_64-linux
- Intel/AMD @code{x86_64} architecture, Linux-Libre kernel.
- @item i686-linux
- Intel 32-bit architecture (IA32), Linux-Libre kernel.
- @item armhf-linux
- ARMv7-A architecture with hard float, Thumb-2 and NEON,
- using the EABI hard-float application binary interface (ABI),
- and Linux-Libre kernel.
- @item aarch64-linux
- little-endian 64-bit ARMv8-A processors, Linux-Libre kernel.
- @item i586-gnu
- @uref{https://hurd.gnu.org, GNU/Hurd} on the Intel 32-bit architecture
- (IA32).
- This configuration is experimental and under development. The easiest
- way for you to give it a try is by setting up an instance of
- @code{hurd-vm-service-type} on your GNU/Linux machine
- (@pxref{transparent-emulation-qemu, @code{hurd-vm-service-type}}).
- @xref{Contributing}, on how to help!
- @item mips64el-linux (unsupported)
- little-endian 64-bit MIPS processors, specifically the Loongson series,
- n32 ABI, and Linux-Libre kernel. This configuration is no longer fully
- supported; in particular, there is no ongoing work to ensure that this
- architecture still works. Should someone decide they wish to revive this
- architecture then the code is still available.
- @item powerpc-linux (unsupported)
- big-endian 32-bit PowerPC processors, specifically the PowerPC G4 with
- AltiVec support, and Linux-Libre kernel. This configuration is not
- fully supported and there is no ongoing work to ensure this architecture
- works.
- @item powerpc64le-linux
- little-endian 64-bit Power ISA processors, Linux-Libre kernel. This
- includes POWER9 systems such as the
- @uref{https://www.fsf.org/news/talos-ii-mainboard-and-talos-ii-lite-mainboard-now-fsf-certified-to-respect-your-freedom,
- RYF Talos II mainboard}. This platform is available as a "technology
- preview": although it is supported, substitutes are not yet available
- from the build farm (@pxref{Substitutes}), and some packages may fail to
- build (@pxref{Tracking Bugs and Patches}). That said, the Guix
- community is actively working on improving this support, and now is a
- great time to try it and get involved!
- @item riscv64-linux
- little-endian 64-bit RISC-V processors, specifically RV64GC, and
- Linux-Libre kernel. This playform is available as a "technology preview":
- although it is supported, substitutes are not yet available from the
- build farm (@pxref{Substitutes}), and some packages may fail to build
- (@pxref{Tracking Bugs and Patches}). That said, the Guix community is
- actively working on improving this support, and now is a great time to
- try it and get involved!
- @end table
- With Guix@tie{}System, you @emph{declare} all aspects of the operating system
- configuration and Guix takes care of instantiating the configuration in a
- transactional, reproducible, and stateless fashion (@pxref{System
- Configuration}). Guix System uses the Linux-libre kernel, the Shepherd
- initialization system (@pxref{Introduction,,, shepherd, The GNU Shepherd
- Manual}), the well-known GNU utilities and tool chain, as well as the
- graphical environment or system services of your choice.
- Guix System is available on all the above platforms except
- @code{mips64el-linux}, @code{powerpc-linux}, @code{powerpc64le-linux} and
- @code{riscv64-linux}.
- @noindent
- For information on porting to other architectures or kernels,
- @pxref{Porting}.
- Building this distribution is a cooperative effort, and you are invited
- to join! @xref{Contributing}, for information about how you can help.
- @c *********************************************************************
- @node Installation
- @chapter Installation
- @cindex installing Guix
- @quotation Note
- We recommend the use of this
- @uref{https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh,
- shell installer script} to install Guix on top of a running GNU/Linux system,
- thereafter called a @dfn{foreign distro}.@footnote{This section is concerned
- with the installation of the package manager, which can be done on top of a
- running GNU/Linux system. If, instead, you want to install the complete GNU
- operating system, @pxref{System Installation}.} The script automates the
- download, installation, and initial configuration of Guix. It should be run
- as the root user.
- @end quotation
- @cindex foreign distro
- @cindex directories related to foreign distro
- When installed on a foreign distro, GNU@tie{}Guix complements the available
- tools without interference. Its data lives exclusively in two directories,
- usually @file{/gnu/store} and @file{/var/guix}; other files on your system,
- such as @file{/etc}, are left untouched.
- Once installed, Guix can be updated by running @command{guix pull}
- (@pxref{Invoking guix pull}).
- If you prefer to perform the installation steps manually or want to tweak
- them, you may find the following subsections useful. They describe the
- software requirements of Guix, as well as how to install it manually and get
- ready to use it.
- @menu
- * Binary Installation:: Getting Guix running in no time!
- * Requirements:: Software needed to build and run Guix.
- * Running the Test Suite:: Testing Guix.
- * Setting Up the Daemon:: Preparing the build daemon's environment.
- * Invoking guix-daemon:: Running the build daemon.
- * Application Setup:: Application-specific setup.
- * Upgrading Guix:: Upgrading Guix and its build daemon.
- @end menu
- @node Binary Installation
- @section Binary Installation
- @cindex installing Guix from binaries
- @cindex installer script
- This section describes how to install Guix on an arbitrary system from a
- self-contained tarball providing binaries for Guix and for all its
- dependencies. This is often quicker than installing from source, which
- is described in the next sections. The only requirement is to have
- GNU@tie{}tar and Xz.
- @c Note duplicated from the ``Installation'' node.
- @quotation Note
- We recommend the use of this
- @uref{https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh,
- shell installer script}. The script automates the download, installation, and
- initial configuration steps described below. It should be run as the root
- user. As root, you can thus run this:
- @example
- cd /tmp
- wget https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh
- chmod +x guix-install.sh
- ./guix-install.sh
- @end example
- When you're done, @pxref{Application Setup} for extra configuration you
- might need, and @ref{Getting Started} for your first steps!
- @end quotation
- Installing goes along these lines:
- @enumerate
- @item
- @cindex downloading Guix binary
- Download the binary tarball from
- @indicateurl{@value{BASE-URL}/guix-binary-@value{VERSION}.x86_64-linux.tar.xz},
- where @code{x86_64-linux} can be replaced with @code{i686-linux} for an
- @code{i686} (32-bits) machine already running the kernel Linux, and so on
- (@pxref{GNU Distribution}).
- @c The following is somewhat duplicated in ``System Installation''.
- Make sure to download the associated @file{.sig} file and to verify the
- authenticity of the tarball against it, along these lines:
- @example
- $ wget @value{BASE-URL}/guix-binary-@value{VERSION}.x86_64-linux.tar.xz.sig
- $ gpg --verify guix-binary-@value{VERSION}.x86_64-linux.tar.xz.sig
- @end example
- If that command fails because you do not have the required public key,
- then run this command to import it:
- @example
- $ wget '@value{OPENPGP-SIGNING-KEY-URL}' \
- -qO - | gpg --import -
- @end example
- @noindent
- and rerun the @code{gpg --verify} command.
- Take note that a warning like ``This key is not certified with a trusted
- signature!'' is normal.
- @c end authentication part
- @item
- Now, you need to become the @code{root} user. Depending on your distribution,
- you may have to run @code{su -} or @code{sudo -i}. As @code{root}, run:
- @example
- # cd /tmp
- # tar --warning=no-timestamp -xf \
- /path/to/guix-binary-@value{VERSION}.x86_64-linux.tar.xz
- # mv var/guix /var/ && mv gnu /
- @end example
- This creates @file{/gnu/store} (@pxref{The Store}) and @file{/var/guix}.
- The latter contains a ready-to-use profile for @code{root} (see next
- step).
- Do @emph{not} unpack the tarball on a working Guix system since that
- would overwrite its own essential files.
- The @option{--warning=no-timestamp} option makes sure GNU@tie{}tar does
- not emit warnings about ``implausibly old time stamps'' (such
- warnings were triggered by GNU@tie{}tar 1.26 and older; recent
- versions are fine).
- They stem from the fact that all the
- files in the archive have their modification time set to 1 (which
- means January 1st, 1970). This is done on purpose to make sure the
- archive content is independent of its creation time, thus making it
- reproducible.
- @item
- Make the profile available under @file{~root/.config/guix/current}, which is
- where @command{guix pull} will install updates (@pxref{Invoking guix pull}):
- @example
- # mkdir -p ~root/.config/guix
- # ln -sf /var/guix/profiles/per-user/root/current-guix \
- ~root/.config/guix/current
- @end example
- Source @file{etc/profile} to augment @env{PATH} and other relevant
- environment variables:
- @example
- # GUIX_PROFILE="`echo ~root`/.config/guix/current" ; \
- source $GUIX_PROFILE/etc/profile
- @end example
- @item
- Create the group and user accounts for build users as explained below
- (@pxref{Build Environment Setup}).
- @item
- Run the daemon, and set it to automatically start on boot.
- If your host distro uses the systemd init system, this can be achieved
- with these commands:
- @c Versions of systemd that supported symlinked service files are not
- @c yet widely deployed, so we should suggest that users copy the service
- @c files into place.
- @c
- @c See this thread for more information:
- @c https://lists.gnu.org/archive/html/guix-devel/2017-01/msg01199.html
- @example
- # cp ~root/.config/guix/current/lib/systemd/system/gnu-store.mount \
- ~root/.config/guix/current/lib/systemd/system/guix-daemon.service \
- /etc/systemd/system/
- # systemctl enable --now gnu-store.mount guix-daemon
- @end example
- You may also want to arrange for @command{guix gc} to run periodically:
- @example
- # cp ~root/.config/guix/current/lib/systemd/system/guix-gc.service \
- ~root/.config/guix/current/lib/systemd/system/guix-gc.timer \
- /etc/systemd/system/
- # systemctl enable --now guix-gc.timer
- @end example
- You may want to edit @file{guix-gc.service} to adjust the command line
- options to fit your needs (@pxref{Invoking guix gc}).
- If your host distro uses the Upstart init system:
- @example
- # initctl reload-configuration
- # cp ~root/.config/guix/current/lib/upstart/system/guix-daemon.conf \
- /etc/init/
- # start guix-daemon
- @end example
- Otherwise, you can still start the daemon manually with:
- @example
- # ~root/.config/guix/current/bin/guix-daemon \
- --build-users-group=guixbuild
- @end example
- @item
- Make the @command{guix} command available to other users on the machine,
- for instance with:
- @example
- # mkdir -p /usr/local/bin
- # cd /usr/local/bin
- # ln -s /var/guix/profiles/per-user/root/current-guix/bin/guix
- @end example
- It is also a good idea to make the Info version of this manual available
- there:
- @example
- # mkdir -p /usr/local/share/info
- # cd /usr/local/share/info
- # for i in /var/guix/profiles/per-user/root/current-guix/share/info/* ;
- do ln -s $i ; done
- @end example
- That way, assuming @file{/usr/local/share/info} is in the search path,
- running @command{info guix} will open this manual (@pxref{Other Info
- Directories,,, texinfo, GNU Texinfo}, for more details on changing the
- Info search path).
- @item
- @cindex substitutes, authorization thereof
- To use substitutes from @code{@value{SUBSTITUTE-SERVER-1}},
- @code{@value{SUBSTITUTE-SERVER-2}} or a mirror (@pxref{Substitutes}),
- authorize them:
- @example
- # guix archive --authorize < \
- ~root/.config/guix/current/share/guix/@value{SUBSTITUTE-SERVER-1}.pub
- # guix archive --authorize < \
- ~root/.config/guix/current/share/guix/@value{SUBSTITUTE-SERVER-2}.pub
- @end example
- @quotation Note
- If you do not enable substitutes, Guix will end up building
- @emph{everything} from source on your machine, making each installation
- and upgrade very expensive. @xref{On Trusting Binaries}, for a
- discussion of reasons why one might want do disable substitutes.
- @end quotation
- @item
- Each user may need to perform a few additional steps to make their Guix
- environment ready for use, @pxref{Application Setup}.
- @end enumerate
- Voilà, the installation is complete!
- You can confirm that Guix is working by installing a sample package into
- the root profile:
- @example
- # guix install hello
- @end example
- The binary installation tarball can be (re)produced and verified simply
- by running the following command in the Guix source tree:
- @example
- make guix-binary.@var{system}.tar.xz
- @end example
- @noindent
- ...@: which, in turn, runs:
- @example
- guix pack -s @var{system} --localstatedir \
- --profile-name=current-guix guix
- @end example
- @xref{Invoking guix pack}, for more info on this handy tool.
- @node Requirements
- @section Requirements
- This section lists requirements when building Guix from source. The
- build procedure for Guix is the same as for other GNU software, and is
- not covered here. Please see the files @file{README} and @file{INSTALL}
- in the Guix source tree for additional details.
- @cindex official website
- GNU Guix is available for download from its website at
- @url{https://www.gnu.org/software/guix/}.
- GNU Guix depends on the following packages:
- @itemize
- @item @url{https://gnu.org/software/guile/, GNU Guile}, version 3.0.x,
- version 3.0.3 or later;
- @item @url{https://notabug.org/cwebber/guile-gcrypt, Guile-Gcrypt}, version
- 0.1.0 or later;
- @item
- @uref{https://gnutls.org/, GnuTLS}, specifically its Guile bindings
- (@pxref{Guile Preparations, how to install the GnuTLS bindings for
- Guile,, gnutls-guile, GnuTLS-Guile});
- @item
- @uref{https://notabug.org/guile-sqlite3/guile-sqlite3, Guile-SQLite3}, version 0.1.0
- or later;
- @item @uref{https://notabug.org/guile-zlib/guile-zlib, Guile-zlib},
- version 0.1.0 or later;
- @item @uref{https://notabug.org/guile-lzlib/guile-lzlib, Guile-lzlib};
- @item @uref{https://www.nongnu.org/guile-avahi/, Guile-Avahi};
- @item
- @uref{https://gitlab.com/guile-git/guile-git, Guile-Git}, version 0.5.0
- or later;
- @item @uref{https://savannah.nongnu.org/projects/guile-json/, Guile-JSON}
- 4.3.0 or later;
- @item @url{https://www.gnu.org/software/make/, GNU Make}.
- @end itemize
- The following dependencies are optional:
- @itemize
- @item
- @c Note: We need at least 0.13.0 for #:nodelay.
- Support for build offloading (@pxref{Daemon Offload Setup}) and
- @command{guix copy} (@pxref{Invoking guix copy}) depends on
- @uref{https://github.com/artyom-poptsov/guile-ssh, Guile-SSH},
- version 0.13.0 or later.
- @item
- @uref{https://notabug.org/guile-zstd/guile-zstd, Guile-zstd}, for zstd
- compression and decompression in @command{guix publish} and for
- substitutes (@pxref{Invoking guix publish}).
- @item
- @uref{https://ngyro.com/software/guile-semver.html, Guile-Semver} for
- the @code{crate} importer (@pxref{Invoking guix import}).
- @item
- @uref{https://www.nongnu.org/guile-lib/doc/ref/htmlprag/, Guile-Lib} for
- the @code{go} importer (@pxref{Invoking guix import}) and for some of
- the ``updaters'' (@pxref{Invoking guix refresh}).
- @item
- When @url{http://www.bzip.org, libbz2} is available,
- @command{guix-daemon} can use it to compress build logs.
- @end itemize
- Unless @option{--disable-daemon} was passed to @command{configure}, the
- following packages are also needed:
- @itemize
- @item @url{https://gnupg.org/, GNU libgcrypt};
- @item @url{https://sqlite.org, SQLite 3};
- @item @url{https://gcc.gnu.org, GCC's g++}, with support for the
- C++11 standard.
- @end itemize
- @cindex state directory
- When configuring Guix on a system that already has a Guix installation,
- be sure to specify the same state directory as the existing installation
- using the @option{--localstatedir} option of the @command{configure}
- script (@pxref{Directory Variables, @code{localstatedir},, standards,
- GNU Coding Standards}). Usually, this @var{localstatedir} option is
- set to the value @file{/var}. The @command{configure} script protects
- against unintended misconfiguration of @var{localstatedir} so you do not
- inadvertently corrupt your store (@pxref{The Store}).
- @node Running the Test Suite
- @section Running the Test Suite
- @cindex test suite
- After a successful @command{configure} and @code{make} run, it is a good
- idea to run the test suite. It can help catch issues with the setup or
- environment, or bugs in Guix itself---and really, reporting test
- failures is a good way to help improve the software. To run the test
- suite, type:
- @example
- make check
- @end example
- Test cases can run in parallel: you can use the @code{-j} option of
- GNU@tie{}make to speed things up. The first run may take a few minutes
- on a recent machine; subsequent runs will be faster because the store
- that is created for test purposes will already have various things in
- cache.
- It is also possible to run a subset of the tests by defining the
- @code{TESTS} makefile variable as in this example:
- @example
- make check TESTS="tests/store.scm tests/cpio.scm"
- @end example
- By default, tests results are displayed at a file level. In order to
- see the details of every individual test cases, it is possible to define
- the @code{SCM_LOG_DRIVER_FLAGS} makefile variable as in this example:
- @example
- make check TESTS="tests/base64.scm" SCM_LOG_DRIVER_FLAGS="--brief=no"
- @end example
- The underlying SRFI 64 custom Automake test driver used for the 'check'
- test suite (located at @file{build-aux/test-driver.scm}) also allows
- selecting which test cases to run at a finer level, via its
- @option{--select} and @option{--exclude} options. Here's an example, to
- run all the test cases from the @file{tests/packages.scm} test file
- whose names start with ``transaction-upgrade-entry'':
- @example
- export SCM_LOG_DRIVER_FLAGS="--select=^transaction-upgrade-entry"
- make check TESTS="tests/packages.scm"
- @end example
- Those wishing to inspect the results of failed tests directly from the
- command line can add the @option{--errors-only=yes} option to the
- @code{SCM_LOG_DRIVER_FLAGS} makefile variable and set the @code{VERBOSE}
- Automake makefile variable, as in:
- @example
- make check SCM_LOG_DRIVER_FLAGS="--brief=no --errors-only=yes" VERBOSE=1
- @end example
- The @option{--show-duration=yes} option can be used to print the
- duration of the individual test cases, when used in combination with
- @option{--brief=no}:
- @example
- make check SCM_LOG_DRIVER_FLAGS="--brief=no --show-duration=yes"
- @end example
- @xref{Parallel Test Harness,,,automake,GNU Automake} for more
- information about the Automake Parallel Test Harness.
- Upon failure, please email @email{bug-guix@@gnu.org} and attach the
- @file{test-suite.log} file. Please specify the Guix version being used
- as well as version numbers of the dependencies (@pxref{Requirements}) in
- your message.
- Guix also comes with a whole-system test suite that tests complete
- Guix System instances. It can only run on systems where
- Guix is already installed, using:
- @example
- make check-system
- @end example
- @noindent
- or, again, by defining @code{TESTS} to select a subset of tests to run:
- @example
- make check-system TESTS="basic mcron"
- @end example
- These system tests are defined in the @code{(gnu tests @dots{})}
- modules. They work by running the operating systems under test with
- lightweight instrumentation in a virtual machine (VM). They can be
- computationally intensive or rather cheap, depending on whether
- substitutes are available for their dependencies (@pxref{Substitutes}).
- Some of them require a lot of storage space to hold VM images.
- Again in case of test failures, please send @email{bug-guix@@gnu.org}
- all the details.
- @node Setting Up the Daemon
- @section Setting Up the Daemon
- @cindex daemon
- Operations such as building a package or running the garbage collector
- are all performed by a specialized process, the @dfn{build daemon}, on
- behalf of clients. Only the daemon may access the store and its
- associated database. Thus, any operation that manipulates the store
- goes through the daemon. For instance, command-line tools such as
- @command{guix package} and @command{guix build} communicate with the
- daemon (@i{via} remote procedure calls) to instruct it what to do.
- The following sections explain how to prepare the build daemon's
- environment. See also @ref{Substitutes}, for information on how to allow
- the daemon to download pre-built binaries.
- @menu
- * Build Environment Setup:: Preparing the isolated build environment.
- * Daemon Offload Setup:: Offloading builds to remote machines.
- * SELinux Support:: Using an SELinux policy for the daemon.
- @end menu
- @node Build Environment Setup
- @subsection Build Environment Setup
- @cindex build environment
- In a standard multi-user setup, Guix and its daemon---the
- @command{guix-daemon} program---are installed by the system
- administrator; @file{/gnu/store} is owned by @code{root} and
- @command{guix-daemon} runs as @code{root}. Unprivileged users may use
- Guix tools to build packages or otherwise access the store, and the
- daemon will do it on their behalf, ensuring that the store is kept in a
- consistent state, and allowing built packages to be shared among users.
- @cindex build users
- When @command{guix-daemon} runs as @code{root}, you may not want package
- build processes themselves to run as @code{root} too, for obvious
- security reasons. To avoid that, a special pool of @dfn{build users}
- should be created for use by build processes started by the daemon.
- These build users need not have a shell and a home directory: they will
- just be used when the daemon drops @code{root} privileges in build
- processes. Having several such users allows the daemon to launch
- distinct build processes under separate UIDs, which guarantees that they
- do not interfere with each other---an essential feature since builds are
- regarded as pure functions (@pxref{Introduction}).
- On a GNU/Linux system, a build user pool may be created like this (using
- Bash syntax and the @code{shadow} commands):
- @c See https://lists.gnu.org/archive/html/bug-guix/2013-01/msg00239.html
- @c for why `-G' is needed.
- @example
- # groupadd --system guixbuild
- # for i in $(seq -w 1 10);
- do
- useradd -g guixbuild -G guixbuild \
- -d /var/empty -s $(which nologin) \
- -c "Guix build user $i" --system \
- guixbuilder$i;
- done
- @end example
- @noindent
- The number of build users determines how many build jobs may run in
- parallel, as specified by the @option{--max-jobs} option
- (@pxref{Invoking guix-daemon, @option{--max-jobs}}). To use
- @command{guix system vm} and related commands, you may need to add the
- build users to the @code{kvm} group so they can access @file{/dev/kvm},
- using @code{-G guixbuild,kvm} instead of @code{-G guixbuild}
- (@pxref{Invoking guix system}).
- The @code{guix-daemon} program may then be run as @code{root} with the
- following command@footnote{If your machine uses the systemd init system,
- dropping the @file{@var{prefix}/lib/systemd/system/guix-daemon.service}
- file in @file{/etc/systemd/system} will ensure that
- @command{guix-daemon} is automatically started. Similarly, if your
- machine uses the Upstart init system, drop the
- @file{@var{prefix}/lib/upstart/system/guix-daemon.conf}
- file in @file{/etc/init}.}:
- @example
- # guix-daemon --build-users-group=guixbuild
- @end example
- @cindex chroot
- @noindent
- This way, the daemon starts build processes in a chroot, under one of
- the @code{guixbuilder} users. On GNU/Linux, by default, the chroot
- environment contains nothing but:
- @c Keep this list in sync with libstore/build.cc! -----------------------
- @itemize
- @item
- a minimal @code{/dev} directory, created mostly independently from the
- host @code{/dev}@footnote{``Mostly'', because while the set of files
- that appear in the chroot's @code{/dev} is fixed, most of these files
- can only be created if the host has them.};
- @item
- the @code{/proc} directory; it only shows the processes of the container
- since a separate PID name space is used;
- @item
- @file{/etc/passwd} with an entry for the current user and an entry for
- user @file{nobody};
- @item
- @file{/etc/group} with an entry for the user's group;
- @item
- @file{/etc/hosts} with an entry that maps @code{localhost} to
- @code{127.0.0.1};
- @item
- a writable @file{/tmp} directory.
- @end itemize
- The chroot does not contain a @file{/home} directory, and the @env{HOME}
- environment variable is set to the non-existent
- @file{/homeless-shelter}. This helps to highlight inappropriate uses of
- @env{HOME} in the build scripts of packages.
- You can influence the directory where the daemon stores build trees
- @i{via} the @env{TMPDIR} environment variable. However, the build tree
- within the chroot is always called @file{/tmp/guix-build-@var{name}.drv-0},
- where @var{name} is the derivation name---e.g., @code{coreutils-8.24}.
- This way, the value of @env{TMPDIR} does not leak inside build
- environments, which avoids discrepancies in cases where build processes
- capture the name of their build tree.
- @vindex http_proxy
- @vindex https_proxy
- The daemon also honors the @env{http_proxy} and @env{https_proxy}
- environment variables for HTTP and HTTPS downloads it performs, be it
- for fixed-output derivations (@pxref{Derivations}) or for substitutes
- (@pxref{Substitutes}).
- If you are installing Guix as an unprivileged user, it is still possible
- to run @command{guix-daemon} provided you pass @option{--disable-chroot}.
- However, build processes will not be isolated from one another, and not
- from the rest of the system. Thus, build processes may interfere with
- each other, and may access programs, libraries, and other files
- available on the system---making it much harder to view them as
- @emph{pure} functions.
- @node Daemon Offload Setup
- @subsection Using the Offload Facility
- @cindex offloading
- @cindex build hook
- When desired, the build daemon can @dfn{offload} derivation builds to
- other machines running Guix, using the @code{offload} @dfn{build
- hook}@footnote{This feature is available only when
- @uref{https://github.com/artyom-poptsov/guile-ssh, Guile-SSH} is
- present.}. When that feature is enabled, a list of user-specified build
- machines is read from @file{/etc/guix/machines.scm}; every time a build
- is requested, for instance via @code{guix build}, the daemon attempts to
- offload it to one of the machines that satisfy the constraints of the
- derivation, in particular its system types---e.g., @code{x86_64-linux}.
- A single machine can have multiple system types, either because its
- architecture natively supports it, via emulation
- (@pxref{transparent-emulation-qemu, Transparent Emulation with QEMU}),
- or both. Missing prerequisites for the build are
- copied over SSH to the target machine, which then proceeds with the
- build; upon success the output(s) of the build are copied back to the
- initial machine. The offload facility comes with a basic scheduler that
- attempts to select the best machine. The best machine is chosen among
- the available machines based on criteria such as:
- @enumerate
- @item
- The availability of a build slot. A build machine can have as many
- build slots (connections) as the value of the @code{parallel-builds}
- field of its @code{build-machine} object.
- @item
- Its relative speed, as defined via the @code{speed} field of its
- @code{build-machine} object.
- @item
- Its load. The normalized machine load must be lower than a threshold
- value, configurable via the @code{overload-threshold} field of its
- @code{build-machine} object.
- @item
- Disk space availability. More than a 100 MiB must be available.
- @end enumerate
- The @file{/etc/guix/machines.scm} file typically looks like this:
- @lisp
- (list (build-machine
- (name "eightysix.example.org")
- (systems (list "x86_64-linux" "i686-linux"))
- (host-key "ssh-ed25519 AAAAC3Nza@dots{}")
- (user "bob")
- (speed 2.)) ;incredibly fast!
- (build-machine
- (name "armeight.example.org")
- (systems (list "aarch64-linux"))
- (host-key "ssh-rsa AAAAB3Nza@dots{}")
- (user "alice")
- ;; Remember 'guix offload' is spawned by
- ;; 'guix-daemon' as root.
- (private-key "/root/.ssh/identity-for-guix")))
- @end lisp
- @noindent
- In the example above we specify a list of two build machines, one for
- the @code{x86_64} and @code{i686} architectures and one for the
- @code{aarch64} architecture.
- In fact, this file is---not surprisingly!---a Scheme file that is
- evaluated when the @code{offload} hook is started. Its return value
- must be a list of @code{build-machine} objects. While this example
- shows a fixed list of build machines, one could imagine, say, using
- DNS-SD to return a list of potential build machines discovered in the
- local network (@pxref{Introduction, Guile-Avahi,, guile-avahi, Using
- Avahi in Guile Scheme Programs}). The @code{build-machine} data type is
- detailed below.
- @deftp {Data Type} build-machine
- This data type represents build machines to which the daemon may offload
- builds. The important fields are:
- @table @code
- @item name
- The host name of the remote machine.
- @item systems
- The system types the remote machine supports---e.g., @code{(list
- "x86_64-linux" "i686-linux")}.
- @item user
- The user account to use when connecting to the remote machine over SSH.
- Note that the SSH key pair must @emph{not} be passphrase-protected, to
- allow non-interactive logins.
- @item host-key
- This must be the machine's SSH @dfn{public host key} in OpenSSH format.
- This is used to authenticate the machine when we connect to it. It is a
- long string that looks like this:
- @example
- ssh-ed25519 AAAAC3NzaC@dots{}mde+UhL hint@@example.org
- @end example
- If the machine is running the OpenSSH daemon, @command{sshd}, the host
- key can be found in a file such as
- @file{/etc/ssh/ssh_host_ed25519_key.pub}.
- If the machine is running the SSH daemon of GNU@tie{}lsh,
- @command{lshd}, the host key is in @file{/etc/lsh/host-key.pub} or a
- similar file. It can be converted to the OpenSSH format using
- @command{lsh-export-key} (@pxref{Converting keys,,, lsh, LSH Manual}):
- @example
- $ lsh-export-key --openssh < /etc/lsh/host-key.pub
- ssh-rsa AAAAB3NzaC1yc2EAAAAEOp8FoQAAAQEAs1eB46LV@dots{}
- @end example
- @end table
- A number of optional fields may be specified:
- @table @asis
- @item @code{port} (default: @code{22})
- Port number of SSH server on the machine.
- @item @code{private-key} (default: @file{~root/.ssh/id_rsa})
- The SSH private key file to use when connecting to the machine, in
- OpenSSH format. This key must not be protected with a passphrase.
- Note that the default value is the private key @emph{of the root
- account}. Make sure it exists if you use the default.
- @item @code{compression} (default: @code{"zlib@@openssh.com,zlib"})
- @itemx @code{compression-level} (default: @code{3})
- The SSH-level compression methods and compression level requested.
- Note that offloading relies on SSH compression to reduce bandwidth usage
- when transferring files to and from build machines.
- @item @code{daemon-socket} (default: @code{"/var/guix/daemon-socket/socket"})
- File name of the Unix-domain socket @command{guix-daemon} is listening
- to on that machine.
- @item @code{overload-threshold} (default: @code{0.6})
- The load threshold above which a potential offload machine is
- disregarded by the offload scheduler. The value roughly translates to
- the total processor usage of the build machine, ranging from 0.0 (0%) to
- 1.0 (100%). It can also be disabled by setting
- @code{overload-threshold} to @code{#f}.
- @item @code{parallel-builds} (default: @code{1})
- The number of builds that may run in parallel on the machine.
- @item @code{speed} (default: @code{1.0})
- A ``relative speed factor''. The offload scheduler will tend to prefer
- machines with a higher speed factor.
- @item @code{features} (default: @code{'()})
- A list of strings denoting specific features supported by the machine.
- An example is @code{"kvm"} for machines that have the KVM Linux modules
- and corresponding hardware support. Derivations can request features by
- name, and they will be scheduled on matching build machines.
- @end table
- @end deftp
- The @command{guix} command must be in the search path on the build
- machines. You can check whether this is the case by running:
- @example
- ssh build-machine guix repl --version
- @end example
- There is one last thing to do once @file{machines.scm} is in place. As
- explained above, when offloading, files are transferred back and forth
- between the machine stores. For this to work, you first need to
- generate a key pair on each machine to allow the daemon to export signed
- archives of files from the store (@pxref{Invoking guix archive}):
- @example
- # guix archive --generate-key
- @end example
- @noindent
- Each build machine must authorize the key of the master machine so that
- it accepts store items it receives from the master:
- @example
- # guix archive --authorize < master-public-key.txt
- @end example
- @noindent
- Likewise, the master machine must authorize the key of each build machine.
- All the fuss with keys is here to express pairwise mutual trust
- relations between the master and the build machines. Concretely, when
- the master receives files from a build machine (and @i{vice versa}), its
- build daemon can make sure they are genuine, have not been tampered
- with, and that they are signed by an authorized key.
- @cindex offload test
- To test whether your setup is operational, run this command on the
- master node:
- @example
- # guix offload test
- @end example
- This will attempt to connect to each of the build machines specified in
- @file{/etc/guix/machines.scm}, make sure Guix is
- available on each machine, attempt to export to the machine and import
- from it, and report any error in the process.
- If you want to test a different machine file, just specify it on the
- command line:
- @example
- # guix offload test machines-qualif.scm
- @end example
- Last, you can test the subset of the machines whose name matches a
- regular expression like this:
- @example
- # guix offload test machines.scm '\.gnu\.org$'
- @end example
- @cindex offload status
- To display the current load of all build hosts, run this command on the
- main node:
- @example
- # guix offload status
- @end example
- @node SELinux Support
- @subsection SELinux Support
- @cindex SELinux, daemon policy
- @cindex mandatory access control, SELinux
- @cindex security, guix-daemon
- Guix includes an SELinux policy file at @file{etc/guix-daemon.cil} that
- can be installed on a system where SELinux is enabled, in order to label
- Guix files and to specify the expected behavior of the daemon. Since
- Guix System does not provide an SELinux base policy, the daemon policy cannot
- be used on Guix System.
- @subsubsection Installing the SELinux policy
- @cindex SELinux, policy installation
- To install the policy run this command as root:
- @example
- semodule -i etc/guix-daemon.cil
- @end example
- Then relabel the file system with @code{restorecon} or by a different
- mechanism provided by your system.
- Once the policy is installed, the file system has been relabeled, and
- the daemon has been restarted, it should be running in the
- @code{guix_daemon_t} context. You can confirm this with the following
- command:
- @example
- ps -Zax | grep guix-daemon
- @end example
- Monitor the SELinux log files as you run a command like @code{guix build
- hello} to convince yourself that SELinux permits all necessary
- operations.
- @subsubsection Limitations
- @cindex SELinux, limitations
- This policy is not perfect. Here is a list of limitations or quirks
- that should be considered when deploying the provided SELinux policy for
- the Guix daemon.
- @enumerate
- @item
- @code{guix_daemon_socket_t} isn’t actually used. None of the socket
- operations involve contexts that have anything to do with
- @code{guix_daemon_socket_t}. It doesn’t hurt to have this unused label,
- but it would be preferable to define socket rules for only this label.
- @item
- @code{guix gc} cannot access arbitrary links to profiles. By design,
- the file label of the destination of a symlink is independent of the
- file label of the link itself. Although all profiles under
- $localstatedir are labelled, the links to these profiles inherit the
- label of the directory they are in. For links in the user’s home
- directory this will be @code{user_home_t}. But for links from the root
- user’s home directory, or @file{/tmp}, or the HTTP server’s working
- directory, etc, this won’t work. @code{guix gc} would be prevented from
- reading and following these links.
- @item
- The daemon’s feature to listen for TCP connections might no longer work.
- This might require extra rules, because SELinux treats network sockets
- differently from files.
- @item
- Currently all files with a name matching the regular expression
- @code{/gnu/store/.+-(guix-.+|profile)/bin/guix-daemon} are assigned the
- label @code{guix_daemon_exec_t}; this means that @emph{any} file with
- that name in any profile would be permitted to run in the
- @code{guix_daemon_t} domain. This is not ideal. An attacker could
- build a package that provides this executable and convince a user to
- install and run it, which lifts it into the @code{guix_daemon_t} domain.
- At that point SELinux could not prevent it from accessing files that are
- allowed for processes in that domain.
- You will need to relabel the store directory after all upgrades to
- @file{guix-daemon}, such as after running @code{guix pull}. Assuming the
- store is in @file{/gnu}, you can do this with @code{restorecon -vR /gnu},
- or by other means provided by your operating system.
- We could generate a much more restrictive policy at installation time,
- so that only the @emph{exact} file name of the currently installed
- @code{guix-daemon} executable would be labelled with
- @code{guix_daemon_exec_t}, instead of using a broad regular expression.
- The downside is that root would have to install or upgrade the policy at
- installation time whenever the Guix package that provides the
- effectively running @code{guix-daemon} executable is upgraded.
- @end enumerate
- @node Invoking guix-daemon
- @section Invoking @command{guix-daemon}
- The @command{guix-daemon} program implements all the functionality to
- access the store. This includes launching build processes, running the
- garbage collector, querying the availability of a build result, etc. It
- is normally run as @code{root} like this:
- @example
- # guix-daemon --build-users-group=guixbuild
- @end example
- @noindent
- For details on how to set it up, @pxref{Setting Up the Daemon}.
- @cindex chroot
- @cindex container, build environment
- @cindex build environment
- @cindex reproducible builds
- By default, @command{guix-daemon} launches build processes under
- different UIDs, taken from the build group specified with
- @option{--build-users-group}. In addition, each build process is run in a
- chroot environment that only contains the subset of the store that the
- build process depends on, as specified by its derivation
- (@pxref{Programming Interface, derivation}), plus a set of specific
- system directories. By default, the latter contains @file{/dev} and
- @file{/dev/pts}. Furthermore, on GNU/Linux, the build environment is a
- @dfn{container}: in addition to having its own file system tree, it has
- a separate mount name space, its own PID name space, network name space,
- etc. This helps achieve reproducible builds (@pxref{Features}).
- When the daemon performs a build on behalf of the user, it creates a
- build directory under @file{/tmp} or under the directory specified by
- its @env{TMPDIR} environment variable. This directory is shared with
- the container for the duration of the build, though within the container,
- the build tree is always called @file{/tmp/guix-build-@var{name}.drv-0}.
- The build directory is automatically deleted upon completion, unless the
- build failed and the client specified @option{--keep-failed}
- (@pxref{Common Build Options, @option{--keep-failed}}).
- The daemon listens for connections and spawns one sub-process for each session
- started by a client (one of the @command{guix} sub-commands). The
- @command{guix processes} command allows you to get an overview of the activity
- on your system by viewing each of the active sessions and clients.
- @xref{Invoking guix processes}, for more information.
- The following command-line options are supported:
- @table @code
- @item --build-users-group=@var{group}
- Take users from @var{group} to run build processes (@pxref{Setting Up
- the Daemon, build users}).
- @item --no-substitutes
- @cindex substitutes
- Do not use substitutes for build products. That is, always build things
- locally instead of allowing downloads of pre-built binaries
- (@pxref{Substitutes}).
- When the daemon runs with @option{--no-substitutes}, clients can still
- explicitly enable substitution @i{via} the @code{set-build-options}
- remote procedure call (@pxref{The Store}).
- @anchor{daemon-substitute-urls}
- @item --substitute-urls=@var{urls}
- Consider @var{urls} the default whitespace-separated list of substitute
- source URLs. When this option is omitted,
- @indicateurl{@value{SUBSTITUTE-URLS}} is used.
- This means that substitutes may be downloaded from @var{urls}, as long
- as they are signed by a trusted signature (@pxref{Substitutes}).
- @xref{Getting Substitutes from Other Servers}, for more information on
- how to configure the daemon to get substitutes from other servers.
- @cindex offloading
- @item --no-offload
- Do not use offload builds to other machines (@pxref{Daemon Offload
- Setup}). That is, always build things locally instead of offloading
- builds to remote machines.
- @item --cache-failures
- Cache build failures. By default, only successful builds are cached.
- When this option is used, @command{guix gc --list-failures} can be used
- to query the set of store items marked as failed; @command{guix gc
- --clear-failures} removes store items from the set of cached failures.
- @xref{Invoking guix gc}.
- @item --cores=@var{n}
- @itemx -c @var{n}
- Use @var{n} CPU cores to build each derivation; @code{0} means as many
- as available.
- The default value is @code{0}, but it may be overridden by clients, such
- as the @option{--cores} option of @command{guix build} (@pxref{Invoking
- guix build}).
- The effect is to define the @env{NIX_BUILD_CORES} environment variable
- in the build process, which can then use it to exploit internal
- parallelism---for instance, by running @code{make -j$NIX_BUILD_CORES}.
- @item --max-jobs=@var{n}
- @itemx -M @var{n}
- Allow at most @var{n} build jobs in parallel. The default value is
- @code{1}. Setting it to @code{0} means that no builds will be performed
- locally; instead, the daemon will offload builds (@pxref{Daemon Offload
- Setup}), or simply fail.
- @item --max-silent-time=@var{seconds}
- When the build or substitution process remains silent for more than
- @var{seconds}, terminate it and report a build failure.
- The default value is @code{0}, which disables the timeout.
- The value specified here can be overridden by clients (@pxref{Common
- Build Options, @option{--max-silent-time}}).
- @item --timeout=@var{seconds}
- Likewise, when the build or substitution process lasts for more than
- @var{seconds}, terminate it and report a build failure.
- The default value is @code{0}, which disables the timeout.
- The value specified here can be overridden by clients (@pxref{Common
- Build Options, @option{--timeout}}).
- @item --rounds=@var{N}
- Build each derivation @var{n} times in a row, and raise an error if
- consecutive build results are not bit-for-bit identical. Note that this
- setting can be overridden by clients such as @command{guix build}
- (@pxref{Invoking guix build}).
- When used in conjunction with @option{--keep-failed}, the differing
- output is kept in the store, under @file{/gnu/store/@dots{}-check}.
- This makes it easy to look for differences between the two results.
- @item --debug
- Produce debugging output.
- This is useful to debug daemon start-up issues, but then it may be
- overridden by clients, for example the @option{--verbosity} option of
- @command{guix build} (@pxref{Invoking guix build}).
- @item --chroot-directory=@var{dir}
- Add @var{dir} to the build chroot.
- Doing this may change the result of build processes---for instance if
- they use optional dependencies found in @var{dir} when it is available,
- and not otherwise. For that reason, it is not recommended to do so.
- Instead, make sure that each derivation declares all the inputs that it
- needs.
- @item --disable-chroot
- Disable chroot builds.
- Using this option is not recommended since, again, it would allow build
- processes to gain access to undeclared dependencies. It is necessary,
- though, when @command{guix-daemon} is running under an unprivileged user
- account.
- @item --log-compression=@var{type}
- Compress build logs according to @var{type}, one of @code{gzip},
- @code{bzip2}, or @code{none}.
- Unless @option{--lose-logs} is used, all the build logs are kept in the
- @var{localstatedir}. To save space, the daemon automatically compresses
- them with gzip by default.
- @item --discover[=yes|no]
- Whether to discover substitute servers on the local network using mDNS
- and DNS-SD.
- This feature is still experimental. However, here are a few
- considerations.
- @enumerate
- @item
- It might be faster/less expensive than fetching from remote servers;
- @item
- There are no security risks, only genuine substitutes will be used
- (@pxref{Substitute Authentication});
- @item
- An attacker advertising @command{guix publish} on your LAN cannot serve
- you malicious binaries, but they can learn what software you’re
- installing;
- @item
- Servers may serve substitute over HTTP, unencrypted, so anyone on the
- LAN can see what software you’re installing.
- @end enumerate
- It is also possible to enable or disable substitute server discovery at
- run-time by running:
- @example
- herd discover guix-daemon on
- herd discover guix-daemon off
- @end example
- @item --disable-deduplication
- @cindex deduplication
- Disable automatic file ``deduplication'' in the store.
- By default, files added to the store are automatically ``deduplicated'':
- if a newly added file is identical to another one found in the store,
- the daemon makes the new file a hard link to the other file. This can
- noticeably reduce disk usage, at the expense of slightly increased
- input/output load at the end of a build process. This option disables
- this optimization.
- @item --gc-keep-outputs[=yes|no]
- Tell whether the garbage collector (GC) must keep outputs of live
- derivations.
- @cindex GC roots
- @cindex garbage collector roots
- When set to @code{yes}, the GC will keep the outputs of any live
- derivation available in the store---the @file{.drv} files. The default
- is @code{no}, meaning that derivation outputs are kept only if they are
- reachable from a GC root. @xref{Invoking guix gc}, for more on GC
- roots.
- @item --gc-keep-derivations[=yes|no]
- Tell whether the garbage collector (GC) must keep derivations
- corresponding to live outputs.
- When set to @code{yes}, as is the case by default, the GC keeps
- derivations---i.e., @file{.drv} files---as long as at least one of their
- outputs is live. This allows users to keep track of the origins of
- items in their store. Setting it to @code{no} saves a bit of disk
- space.
- In this way, setting @option{--gc-keep-derivations} to @code{yes} causes
- liveness to flow from outputs to derivations, and setting
- @option{--gc-keep-outputs} to @code{yes} causes liveness to flow from
- derivations to outputs. When both are set to @code{yes}, the effect is
- to keep all the build prerequisites (the sources, compiler, libraries,
- and other build-time tools) of live objects in the store, regardless of
- whether these prerequisites are reachable from a GC root. This is
- convenient for developers since it saves rebuilds or downloads.
- @item --impersonate-linux-2.6
- On Linux-based systems, impersonate Linux 2.6. This means that the
- kernel's @command{uname} system call will report 2.6 as the release number.
- This might be helpful to build programs that (usually wrongfully) depend
- on the kernel version number.
- @item --lose-logs
- Do not keep build logs. By default they are kept under
- @file{@var{localstatedir}/guix/log}.
- @item --system=@var{system}
- Assume @var{system} as the current system type. By default it is the
- architecture/kernel pair found at configure time, such as
- @code{x86_64-linux}.
- @item --listen=@var{endpoint}
- Listen for connections on @var{endpoint}. @var{endpoint} is interpreted
- as the file name of a Unix-domain socket if it starts with
- @code{/} (slash sign). Otherwise, @var{endpoint} is interpreted as a
- host name or host name and port to listen to. Here are a few examples:
- @table @code
- @item --listen=/gnu/var/daemon
- Listen for connections on the @file{/gnu/var/daemon} Unix-domain socket,
- creating it if needed.
- @item --listen=localhost
- @cindex daemon, remote access
- @cindex remote access to the daemon
- @cindex daemon, cluster setup
- @cindex clusters, daemon setup
- Listen for TCP connections on the network interface corresponding to
- @code{localhost}, on port 44146.
- @item --listen=128.0.0.42:1234
- Listen for TCP connections on the network interface corresponding to
- @code{128.0.0.42}, on port 1234.
- @end table
- This option can be repeated multiple times, in which case
- @command{guix-daemon} accepts connections on all the specified
- endpoints. Users can tell client commands what endpoint to connect to
- by setting the @env{GUIX_DAEMON_SOCKET} environment variable
- (@pxref{The Store, @env{GUIX_DAEMON_SOCKET}}).
- @quotation Note
- The daemon protocol is @emph{unauthenticated and unencrypted}. Using
- @option{--listen=@var{host}} is suitable on local networks, such as
- clusters, where only trusted nodes may connect to the build daemon. In
- other cases where remote access to the daemon is needed, we recommend
- using Unix-domain sockets along with SSH.
- @end quotation
- When @option{--listen} is omitted, @command{guix-daemon} listens for
- connections on the Unix-domain socket located at
- @file{@var{localstatedir}/guix/daemon-socket/socket}.
- @end table
- @node Application Setup
- @section Application Setup
- @cindex foreign distro
- When using Guix on top of GNU/Linux distribution other than Guix System---a
- so-called @dfn{foreign distro}---a few additional steps are needed to
- get everything in place. Here are some of them.
- @subsection Locales
- @anchor{locales-and-locpath}
- @cindex locales, when not on Guix System
- @vindex LOCPATH
- @vindex GUIX_LOCPATH
- Packages installed @i{via} Guix will not use the locale data of the
- host system. Instead, you must first install one of the locale packages
- available with Guix and then define the @env{GUIX_LOCPATH} environment
- variable:
- @example
- $ guix install glibc-locales
- $ export GUIX_LOCPATH=$HOME/.guix-profile/lib/locale
- @end example
- Note that the @code{glibc-locales} package contains data for all the
- locales supported by the GNU@tie{}libc and weighs in at around
- 930@tie{}MiB@footnote{The size of the @code{glibc-locales} package is
- reduced down to about 213@tie{}MiB with store deduplication and further
- down to about 67@tie{}MiB when using a zstd-compressed Btrfs file
- system.}. If you only need a few locales, you can define your custom
- locales package via the @code{make-glibc-utf8-locales} procedure from
- the @code{(gnu packages base)} module. The following example defines a
- package containing the various Canadian UTF-8 locales known to the
- GNU@tie{}libc, that weighs around 14@tie{}MiB:
- @lisp
- (use-modules (gnu packages base))
- (define my-glibc-locales
- (make-glibc-utf8-locales
- glibc
- #:locales (list "en_CA" "fr_CA" "ik_CA" "iu_CA" "shs_CA")
- #:name "glibc-canadian-utf8-locales"))
- @end lisp
- The @env{GUIX_LOCPATH} variable plays a role similar to @env{LOCPATH}
- (@pxref{Locale Names, @env{LOCPATH},, libc, The GNU C Library Reference
- Manual}). There are two important differences though:
- @enumerate
- @item
- @env{GUIX_LOCPATH} is honored only by the libc in Guix, and not by the libc
- provided by foreign distros. Thus, using @env{GUIX_LOCPATH} allows you
- to make sure the programs of the foreign distro will not end up loading
- incompatible locale data.
- @item
- libc suffixes each entry of @env{GUIX_LOCPATH} with @code{/X.Y}, where
- @code{X.Y} is the libc version---e.g., @code{2.22}. This means that,
- should your Guix profile contain a mixture of programs linked against
- different libc version, each libc version will only try to load locale
- data in the right format.
- @end enumerate
- This is important because the locale data format used by different libc
- versions may be incompatible.
- @subsection Name Service Switch
- @cindex name service switch, glibc
- @cindex NSS (name service switch), glibc
- @cindex nscd (name service caching daemon)
- @cindex name service caching daemon (nscd)
- When using Guix on a foreign distro, we @emph{strongly recommend} that
- the system run the GNU C library's @dfn{name service cache daemon},
- @command{nscd}, which should be listening on the
- @file{/var/run/nscd/socket} socket. Failing to do that, applications
- installed with Guix may fail to look up host names or user accounts, or
- may even crash. The next paragraphs explain why.
- @cindex @file{nsswitch.conf}
- The GNU C library implements a @dfn{name service switch} (NSS), which is
- an extensible mechanism for ``name lookups'' in general: host name
- resolution, user accounts, and more (@pxref{Name Service Switch,,, libc,
- The GNU C Library Reference Manual}).
- @cindex Network information service (NIS)
- @cindex NIS (Network information service)
- Being extensible, the NSS supports @dfn{plugins}, which provide new name
- lookup implementations: for example, the @code{nss-mdns} plugin allow
- resolution of @code{.local} host names, the @code{nis} plugin allows
- user account lookup using the Network information service (NIS), and so
- on. These extra ``lookup services'' are configured system-wide in
- @file{/etc/nsswitch.conf}, and all the programs running on the system
- honor those settings (@pxref{NSS Configuration File,,, libc, The GNU C
- Reference Manual}).
- When they perform a name lookup---for instance by calling the
- @code{getaddrinfo} function in C---applications first try to connect to
- the nscd; on success, nscd performs name lookups on their behalf. If
- the nscd is not running, then they perform the name lookup by
- themselves, by loading the name lookup services into their own address
- space and running it. These name lookup services---the
- @file{libnss_*.so} files---are @code{dlopen}'d, but they may come from
- the host system's C library, rather than from the C library the
- application is linked against (the C library coming from Guix).
- And this is where the problem is: if your application is linked against
- Guix's C library (say, glibc 2.24) and tries to load NSS plugins from
- another C library (say, @code{libnss_mdns.so} for glibc 2.22), it will
- likely crash or have its name lookups fail unexpectedly.
- Running @command{nscd} on the system, among other advantages, eliminates
- this binary incompatibility problem because those @code{libnss_*.so}
- files are loaded in the @command{nscd} process, not in applications
- themselves.
- @subsection X11 Fonts
- @cindex fonts
- The majority of graphical applications use Fontconfig to locate and load
- fonts and perform X11-client-side rendering. The @code{fontconfig}
- package in Guix looks for fonts in @file{$HOME/.guix-profile} by
- default. Thus, to allow graphical applications installed with Guix to
- display fonts, you have to install fonts with Guix as well. Essential
- font packages include @code{font-ghostscript}, @code{font-dejavu}, and
- @code{font-gnu-freefont}.
- @cindex @code{fc-cache}
- @cindex font cache
- Once you have installed or removed fonts, or when you notice an
- application that does not find fonts, you may need to install Fontconfig
- and to force an update of its font cache by running:
- @example
- guix install fontconfig
- fc-cache -rv
- @end example
- To display text written in Chinese languages, Japanese, or Korean in
- graphical applications, consider installing
- @code{font-adobe-source-han-sans} or @code{font-wqy-zenhei}. The former
- has multiple outputs, one per language family (@pxref{Packages with
- Multiple Outputs}). For instance, the following command installs fonts
- for Chinese languages:
- @example
- guix install font-adobe-source-han-sans:cn
- @end example
- @cindex @code{xterm}
- Older programs such as @command{xterm} do not use Fontconfig and instead
- rely on server-side font rendering. Such programs require to specify a
- full name of a font using XLFD (X Logical Font Description), like this:
- @example
- -*-dejavu sans-medium-r-normal-*-*-100-*-*-*-*-*-1
- @end example
- To be able to use such full names for the TrueType fonts installed in
- your Guix profile, you need to extend the font path of the X server:
- @c Note: 'xset' does not accept symlinks so the trick below arranges to
- @c get at the real directory. See <https://bugs.gnu.org/30655>.
- @example
- xset +fp $(dirname $(readlink -f ~/.guix-profile/share/fonts/truetype/fonts.dir))
- @end example
- @cindex @code{xlsfonts}
- After that, you can run @code{xlsfonts} (from @code{xlsfonts} package)
- to make sure your TrueType fonts are listed there.
- @subsection X.509 Certificates
- @cindex @code{nss-certs}
- The @code{nss-certs} package provides X.509 certificates, which allow
- programs to authenticate Web servers accessed over HTTPS.
- When using Guix on a foreign distro, you can install this package and
- define the relevant environment variables so that packages know where to
- look for certificates. @xref{X.509 Certificates}, for detailed
- information.
- @subsection Emacs Packages
- @cindex @code{emacs}
- When you install Emacs packages with Guix, the Elisp files are placed
- under the @file{share/emacs/site-lisp/} directory of the profile in
- which they are installed. The Elisp libraries are made available to
- Emacs through the @env{EMACSLOADPATH} environment variable, which is
- set when installing Emacs itself.
- Additionally, autoload definitions are automatically evaluated at the
- initialization of Emacs, by the Guix-specific
- @code{guix-emacs-autoload-packages} procedure. If, for some reason, you
- want to avoid auto-loading the Emacs packages installed with Guix, you
- can do so by running Emacs with the @option{--no-site-file} option
- (@pxref{Init File,,, emacs, The GNU Emacs Manual}).
- @node Upgrading Guix
- @section Upgrading Guix
- @cindex Upgrading Guix, on a foreign distro
- To upgrade Guix, run:
- @example
- guix pull
- @end example
- @xref{Invoking guix pull}, for more information.
- @cindex upgrading Guix for the root user, on a foreign distro
- @cindex upgrading the Guix daemon, on a foreign distro
- @cindex @command{guix pull} for the root user, on a foreign distro
- On a foreign distro, you can upgrade the build daemon by running:
- @example
- sudo -i guix pull
- @end example
- @noindent
- followed by (assuming your distro uses the systemd service management
- tool):
- @example
- systemctl restart guix-daemon.service
- @end example
- On Guix System, upgrading the daemon is achieved by reconfiguring the
- system (@pxref{Invoking guix system, @code{guix system reconfigure}}).
- @c TODO What else?
- @c *********************************************************************
- @node System Installation
- @chapter System Installation
- @cindex installing Guix System
- @cindex Guix System, installation
- This section explains how to install Guix System
- on a machine. Guix, as a package manager, can
- also be installed on top of a running GNU/Linux system,
- @pxref{Installation}.
- @ifinfo
- @quotation Note
- @c This paragraph is for people reading this from tty2 of the
- @c installation image.
- You are reading this documentation with an Info reader. For details on
- how to use it, hit the @key{RET} key (``return'' or ``enter'') on the
- link that follows: @pxref{Top, Info reader,, info-stnd, Stand-alone GNU
- Info}. Hit @kbd{l} afterwards to come back here.
- Alternatively, run @command{info info} in another tty to keep the manual
- available.
- @end quotation
- @end ifinfo
- @menu
- * Limitations:: What you can expect.
- * Hardware Considerations:: Supported hardware.
- * USB Stick and DVD Installation:: Preparing the installation medium.
- * Preparing for Installation:: Networking, partitioning, etc.
- * Guided Graphical Installation:: Easy graphical installation.
- * Manual Installation:: Manual installation for wizards.
- * After System Installation:: When installation succeeded.
- * Installing Guix in a VM:: Guix System playground.
- * Building the Installation Image:: How this comes to be.
- @end menu
- @node Limitations
- @section Limitations
- We consider Guix System to be ready for a wide range of ``desktop'' and server
- use cases. The reliability guarantees it provides---transactional upgrades
- and rollbacks, reproducibility---make it a solid foundation.
- Nevertheless, before you proceed with the installation, be aware of the
- following noteworthy limitations applicable to version @value{VERSION}:
- @itemize
- @item
- More and more system services are provided (@pxref{Services}), but some
- may be missing.
- @item
- GNOME, Xfce, LXDE, and Enlightenment are available (@pxref{Desktop Services}),
- as well as a number of X11 window managers. However, KDE is currently
- missing.
- @end itemize
- More than a disclaimer, this is an invitation to report issues (and success
- stories!), and to join us in improving it. @xref{Contributing}, for more
- info.
- @node Hardware Considerations
- @section Hardware Considerations
- @cindex hardware support on Guix System
- GNU@tie{}Guix focuses on respecting the user's computing freedom. It
- builds around the kernel Linux-libre, which means that only hardware for
- which free software drivers and firmware exist is supported. Nowadays,
- a wide range of off-the-shelf hardware is supported on
- GNU/Linux-libre---from keyboards to graphics cards to scanners and
- Ethernet controllers. Unfortunately, there are still areas where
- hardware vendors deny users control over their own computing, and such
- hardware is not supported on Guix System.
- @cindex WiFi, hardware support
- One of the main areas where free drivers or firmware are lacking is WiFi
- devices. WiFi devices known to work include those using Atheros chips
- (AR9271 and AR7010), which corresponds to the @code{ath9k} Linux-libre
- driver, and those using Broadcom/AirForce chips (BCM43xx with
- Wireless-Core Revision 5), which corresponds to the @code{b43-open}
- Linux-libre driver. Free firmware exists for both and is available
- out-of-the-box on Guix System, as part of @code{%base-firmware}
- (@pxref{operating-system Reference, @code{firmware}}).
- @cindex RYF, Respects Your Freedom
- The @uref{https://www.fsf.org/, Free Software Foundation} runs
- @uref{https://www.fsf.org/ryf, @dfn{Respects Your Freedom}} (RYF), a
- certification program for hardware products that respect your freedom
- and your privacy and ensure that you have control over your device. We
- encourage you to check the list of RYF-certified devices.
- Another useful resource is the @uref{https://www.h-node.org/, H-Node}
- web site. It contains a catalog of hardware devices with information
- about their support in GNU/Linux.
- @node USB Stick and DVD Installation
- @section USB Stick and DVD Installation
- An ISO-9660 installation image that can be written to a USB stick or
- burnt to a DVD can be downloaded from
- @indicateurl{@value{BASE-URL}/guix-system-install-@value{VERSION}.x86_64-linux.iso},
- where you can replace @code{x86_64-linux} with one of:
- @table @code
- @item x86_64-linux
- for a GNU/Linux system on Intel/AMD-compatible 64-bit CPUs;
- @item i686-linux
- for a 32-bit GNU/Linux system on Intel-compatible CPUs.
- @end table
- @c start duplication of authentication part from ``Binary Installation''
- Make sure to download the associated @file{.sig} file and to verify the
- authenticity of the image against it, along these lines:
- @example
- $ wget @value{BASE-URL}/guix-system-install-@value{VERSION}.x86_64-linux.iso.sig
- $ gpg --verify guix-system-install-@value{VERSION}.x86_64-linux.iso.sig
- @end example
- If that command fails because you do not have the required public key,
- then run this command to import it:
- @example
- $ wget @value{OPENPGP-SIGNING-KEY-URL} \
- -qO - | gpg --import -
- @end example
- @noindent
- and rerun the @code{gpg --verify} command.
- Take note that a warning like ``This key is not certified with a trusted
- signature!'' is normal.
- @c end duplication
- This image contains the tools necessary for an installation.
- It is meant to be copied @emph{as is} to a large-enough USB stick or DVD.
- @unnumberedsubsec Copying to a USB Stick
- Insert a USB stick of 1@tie{}GiB or more into your machine, and determine
- its device name. Assuming that the USB stick is known as @file{/dev/sdX},
- copy the image with:
- @example
- dd if=guix-system-install-@value{VERSION}.x86_64-linux.iso of=/dev/sdX status=progress
- sync
- @end example
- Access to @file{/dev/sdX} usually requires root privileges.
- @unnumberedsubsec Burning on a DVD
- Insert a blank DVD into your machine, and determine
- its device name. Assuming that the DVD drive is known as @file{/dev/srX},
- copy the image with:
- @example
- growisofs -dvd-compat -Z /dev/srX=guix-system-install-@value{VERSION}.x86_64-linux.iso
- @end example
- Access to @file{/dev/srX} usually requires root privileges.
- @unnumberedsubsec Booting
- Once this is done, you should be able to reboot the system and boot from
- the USB stick or DVD@. The latter usually requires you to get in the
- BIOS or UEFI boot menu, where you can choose to boot from the USB stick.
- In order to boot from Libreboot, switch to the command mode by pressing
- the @kbd{c} key and type @command{search_grub usb}.
- @xref{Installing Guix in a VM}, if, instead, you would like to install
- Guix System in a virtual machine (VM).
- @node Preparing for Installation
- @section Preparing for Installation
- Once you have booted, you can use the guided graphical installer, which makes
- it easy to get started (@pxref{Guided Graphical Installation}). Alternatively,
- if you are already familiar with GNU/Linux and if you want more control than
- what the graphical installer provides, you can choose the ``manual''
- installation process (@pxref{Manual Installation}).
- The graphical installer is available on TTY1. You can obtain root shells on
- TTYs 3 to 6 by hitting @kbd{ctrl-alt-f3}, @kbd{ctrl-alt-f4}, etc. TTY2 shows
- this documentation and you can reach it with @kbd{ctrl-alt-f2}. Documentation
- is browsable using the Info reader commands (@pxref{Top,,, info-stnd,
- Stand-alone GNU Info}). The installation system runs the GPM mouse daemon,
- which allows you to select text with the left mouse button and to paste it
- with the middle button.
- @quotation Note
- Installation requires access to the Internet so that any missing
- dependencies of your system configuration can be downloaded. See the
- ``Networking'' section below.
- @end quotation
- @node Guided Graphical Installation
- @section Guided Graphical Installation
- The graphical installer is a text-based user interface. It will guide you,
- with dialog boxes, through the steps needed to install GNU@tie{}Guix System.
- The first dialog boxes allow you to set up the system as you use it during the
- installation: you can choose the language, keyboard layout, and set up
- networking, which will be used during the installation. The image below shows
- the networking dialog.
- @image{images/installer-network,5in,, networking setup with the graphical installer}
- Later steps allow you to partition your hard disk, as shown in the image
- below, to choose whether or not to use encrypted file systems, to enter the
- host name and root password, and to create an additional account, among other
- things.
- @image{images/installer-partitions,5in,, partitioning with the graphical installer}
- Note that, at any time, the installer allows you to exit the current
- installation step and resume at a previous step, as show in the image below.
- @image{images/installer-resume,5in,, resuming the installation process}
- Once you're done, the installer produces an operating system configuration and
- displays it (@pxref{Using the Configuration System}). At that point you can
- hit ``OK'' and installation will proceed. On success, you can reboot into the
- new system and enjoy. @xref{After System Installation}, for what's next!
- @node Manual Installation
- @section Manual Installation
- This section describes how you would ``manually'' install GNU@tie{}Guix System
- on your machine. This option requires familiarity with GNU/Linux, with the
- shell, and with common administration tools. If you think this is not for
- you, consider using the guided graphical installer (@pxref{Guided Graphical
- Installation}).
- The installation system provides root shells on TTYs 3 to 6; press
- @kbd{ctrl-alt-f3}, @kbd{ctrl-alt-f4}, and so on to reach them. It includes
- many common tools needed to install the system. But it is also a full-blown
- Guix System, which means that you can install additional packages, should you
- need it, using @command{guix package} (@pxref{Invoking guix package}).
- @menu
- * Keyboard Layout and Networking and Partitioning:: Initial setup.
- * Proceeding with the Installation:: Installing.
- @end menu
- @node Keyboard Layout and Networking and Partitioning
- @subsection Keyboard Layout, Networking, and Partitioning
- Before you can install the system, you may want to adjust the keyboard layout,
- set up networking, and partition your target hard disk. This section will
- guide you through this.
- @subsubsection Keyboard Layout
- @cindex keyboard layout
- The installation image uses the US qwerty keyboard layout. If you want
- to change it, you can use the @command{loadkeys} command. For example,
- the following command selects the Dvorak keyboard layout:
- @example
- loadkeys dvorak
- @end example
- See the files under @file{/run/current-system/profile/share/keymaps} for
- a list of available keyboard layouts. Run @command{man loadkeys} for
- more information.
- @subsubsection Networking
- Run the following command to see what your network interfaces are called:
- @example
- ifconfig -a
- @end example
- @noindent
- @dots{} or, using the GNU/Linux-specific @command{ip} command:
- @example
- ip address
- @end example
- @c https://cgit.freedesktop.org/systemd/systemd/tree/src/udev/udev-builtin-net_id.c#n20
- Wired interfaces have a name starting with @samp{e}; for example, the
- interface corresponding to the first on-board Ethernet controller is
- called @samp{eno1}. Wireless interfaces have a name starting with
- @samp{w}, like @samp{w1p2s0}.
- @table @asis
- @item Wired connection
- To configure a wired network run the following command, substituting
- @var{interface} with the name of the wired interface you want to use.
- @example
- ifconfig @var{interface} up
- @end example
- @noindent
- @dots{} or, using the GNU/Linux-specific @command{ip} command:
- @example
- ip link set @var{interface} up
- @end example
- @item Wireless connection
- @cindex wireless
- @cindex WiFi
- To configure wireless networking, you can create a configuration file
- for the @command{wpa_supplicant} configuration tool (its location is not
- important) using one of the available text editors such as
- @command{nano}:
- @example
- nano wpa_supplicant.conf
- @end example
- As an example, the following stanza can go to this file and will work
- for many wireless networks, provided you give the actual SSID and
- passphrase for the network you are connecting to:
- @example
- network=@{
- ssid="@var{my-ssid}"
- key_mgmt=WPA-PSK
- psk="the network's secret passphrase"
- @}
- @end example
- Start the wireless service and run it in the background with the
- following command (substitute @var{interface} with the name of the
- network interface you want to use):
- @example
- wpa_supplicant -c wpa_supplicant.conf -i @var{interface} -B
- @end example
- Run @command{man wpa_supplicant} for more information.
- @end table
- @cindex DHCP
- At this point, you need to acquire an IP address. On a network where IP
- addresses are automatically assigned @i{via} DHCP, you can run:
- @example
- dhclient -v @var{interface}
- @end example
- Try to ping a server to see if networking is up and running:
- @example
- ping -c 3 gnu.org
- @end example
- Setting up network access is almost always a requirement because the
- image does not contain all the software and tools that may be needed.
- @cindex proxy, during system installation
- If you need HTTP and HTTPS access to go through a proxy, run the
- following command:
- @example
- herd set-http-proxy guix-daemon @var{URL}
- @end example
- @noindent
- where @var{URL} is the proxy URL, for example
- @code{http://example.org:8118}.
- @cindex installing over SSH
- If you want to, you can continue the installation remotely by starting
- an SSH server:
- @example
- herd start ssh-daemon
- @end example
- Make sure to either set a password with @command{passwd}, or configure
- OpenSSH public key authentication before logging in.
- @subsubsection Disk Partitioning
- Unless this has already been done, the next step is to partition, and
- then format the target partition(s).
- The installation image includes several partitioning tools, including
- Parted (@pxref{Overview,,, parted, GNU Parted User Manual}),
- @command{fdisk}, and @command{cfdisk}. Run it and set up your disk with
- the partition layout you want:
- @example
- cfdisk
- @end example
- If your disk uses the GUID Partition Table (GPT) format and you plan to
- install BIOS-based GRUB (which is the default), make sure a BIOS Boot
- Partition is available (@pxref{BIOS installation,,, grub, GNU GRUB
- manual}).
- @cindex EFI, installation
- @cindex UEFI, installation
- @cindex ESP, EFI system partition
- If you instead wish to use EFI-based GRUB, a FAT32 @dfn{EFI System Partition}
- (ESP) is required. This partition can be mounted at @file{/boot/efi} for
- instance and must have the @code{esp} flag set. E.g., for @command{parted}:
- @example
- parted /dev/sda set 1 esp on
- @end example
- @quotation Note
- @vindex grub-bootloader
- @vindex grub-efi-bootloader
- Unsure whether to use EFI- or BIOS-based GRUB? If the directory
- @file{/sys/firmware/efi} exists in the installation image, then you should
- probably perform an EFI installation, using @code{grub-efi-bootloader}.
- Otherwise you should use the BIOS-based GRUB, known as
- @code{grub-bootloader}. @xref{Bootloader Configuration}, for more info on
- bootloaders.
- @end quotation
- Once you are done partitioning the target hard disk drive, you have to
- create a file system on the relevant partition(s)@footnote{Currently
- Guix System only supports ext4, btrfs, JFS, F2FS, and XFS file systems. In
- particular, code that reads file system UUIDs and labels only works for these
- file system types.}. For the ESP, if you have one and assuming it is
- @file{/dev/sda1}, run:
- @example
- mkfs.fat -F32 /dev/sda1
- @end example
- For the root file system, ext4 is the most widely used format. Other
- file systems, such as Btrfs, support compression, which is reported to
- nicely complement file deduplication that the daemon performs
- independently of the file system (@pxref{Invoking guix-daemon,
- deduplication}).
- Preferably, assign file systems a label so that you can easily and
- reliably refer to them in @code{file-system} declarations (@pxref{File
- Systems}). This is typically done using the @code{-L} option of
- @command{mkfs.ext4} and related commands. So, assuming the target root
- partition lives at @file{/dev/sda2}, a file system with the label
- @code{my-root} can be created with:
- @example
- mkfs.ext4 -L my-root /dev/sda2
- @end example
- @cindex encrypted disk
- If you are instead planning to encrypt the root partition, you can use
- the Cryptsetup/LUKS utilities to do that (see @inlinefmtifelse{html,
- @uref{https://linux.die.net/man/8/cryptsetup, @code{man cryptsetup}},
- @code{man cryptsetup}} for more information).
- @quotation Warning
- Note that GRUB can unlock LUKS2 devices since version 2.06, but only
- supports the PBKDF2 key derivation function, which is not the default
- for @command{cryptsetup luksFormat}. You can check which key derivation
- function is being used by a device by running @command{cryptsetup
- luksDump @var{device}}, and looking for the PBKDF field of your
- keyslots.
- @end quotation
- Assuming you want to store the root partition on @file{/dev/sda2}, the
- command sequence to format it as a LUKS2 partition would be along these
- lines:
- @example
- cryptsetup luksFormat --type luks2 --pbkdf pbkdf2 /dev/sda2
- cryptsetup open /dev/sda2 my-partition
- mkfs.ext4 -L my-root /dev/mapper/my-partition
- @end example
- Once that is done, mount the target file system under @file{/mnt}
- with a command like (again, assuming @code{my-root} is the label of the
- root file system):
- @example
- mount LABEL=my-root /mnt
- @end example
- Also mount any other file systems you would like to use on the target
- system relative to this path. If you have opted for @file{/boot/efi} as an
- EFI mount point for example, mount it at @file{/mnt/boot/efi} now so it is
- found by @code{guix system init} afterwards.
- Finally, if you plan to use one or more swap partitions (@pxref{Swap
- Space}), make sure to initialize them with @command{mkswap}. Assuming
- you have one swap partition on @file{/dev/sda3}, you would run:
- @example
- mkswap /dev/sda3
- swapon /dev/sda3
- @end example
- Alternatively, you may use a swap file. For example, assuming that in
- the new system you want to use the file @file{/swapfile} as a swap file,
- you would run@footnote{This example will work for many types of file
- systems (e.g., ext4). However, for copy-on-write file systems (e.g.,
- btrfs), the required steps may be different. For details, see the
- manual pages for @command{mkswap} and @command{swapon}.}:
- @example
- # This is 10 GiB of swap space. Adjust "count" to change the size.
- dd if=/dev/zero of=/mnt/swapfile bs=1MiB count=10240
- # For security, make the file readable and writable only by root.
- chmod 600 /mnt/swapfile
- mkswap /mnt/swapfile
- swapon /mnt/swapfile
- @end example
- Note that if you have encrypted the root partition and created a swap
- file in its file system as described above, then the encryption also
- protects the swap file, just like any other file in that file system.
- @node Proceeding with the Installation
- @subsection Proceeding with the Installation
- With the target partitions ready and the target root mounted on
- @file{/mnt}, we're ready to go. First, run:
- @example
- herd start cow-store /mnt
- @end example
- This makes @file{/gnu/store} copy-on-write, such that packages added to it
- during the installation phase are written to the target disk on @file{/mnt}
- rather than kept in memory. This is necessary because the first phase of
- the @command{guix system init} command (see below) entails downloads or
- builds to @file{/gnu/store} which, initially, is an in-memory file system.
- Next, you have to edit a file and
- provide the declaration of the operating system to be installed. To
- that end, the installation system comes with three text editors. We
- recommend GNU nano (@pxref{Top,,, nano, GNU nano Manual}), which
- supports syntax highlighting and parentheses matching; other editors
- include mg (an Emacs clone), and
- nvi (a clone of the original BSD @command{vi} editor).
- We strongly recommend storing that file on the target root file system, say,
- as @file{/mnt/etc/config.scm}. Failing to do that, you will have lost your
- configuration file once you have rebooted into the newly-installed system.
- @xref{Using the Configuration System}, for an overview of the
- configuration file. The example configurations discussed in that
- section are available under @file{/etc/configuration} in the
- installation image. Thus, to get started with a system configuration
- providing a graphical display server (a ``desktop'' system), you can run
- something along these lines:
- @example
- # mkdir /mnt/etc
- # cp /etc/configuration/desktop.scm /mnt/etc/config.scm
- # nano /mnt/etc/config.scm
- @end example
- You should pay attention to what your configuration file contains, and
- in particular:
- @itemize
- @item
- Make sure the @code{bootloader-configuration} form refers to the targets
- you want to install GRUB on. It should mention @code{grub-bootloader}
- if you are installing GRUB in the legacy way, or
- @code{grub-efi-bootloader} for newer UEFI systems. For legacy systems,
- the @code{targets} field contain the names of the devices, like
- @code{(list "/dev/sda")}; for UEFI systems it names the paths to mounted
- EFI partitions, like @code{(list "/boot/efi")}; do make sure the paths
- are currently mounted and a @code{file-system} entry is specified in
- your configuration.
- @item
- Be sure that your file system labels match the value of their respective
- @code{device} fields in your @code{file-system} configuration, assuming
- your @code{file-system} configuration uses the @code{file-system-label}
- procedure in its @code{device} field.
- @item
- If there are encrypted or RAID partitions, make sure to add a
- @code{mapped-devices} field to describe them (@pxref{Mapped Devices}).
- @end itemize
- Once you are done preparing the configuration file, the new system must
- be initialized (remember that the target root file system is mounted
- under @file{/mnt}):
- @example
- guix system init /mnt/etc/config.scm /mnt
- @end example
- @noindent
- This copies all the necessary files and installs GRUB on
- @file{/dev/sdX}, unless you pass the @option{--no-bootloader} option. For
- more information, @pxref{Invoking guix system}. This command may trigger
- downloads or builds of missing packages, which can take some time.
- Once that command has completed---and hopefully succeeded!---you can run
- @command{reboot} and boot into the new system. The @code{root} password
- in the new system is initially empty; other users' passwords need to be
- initialized by running the @command{passwd} command as @code{root},
- unless your configuration specifies otherwise
- (@pxref{user-account-password, user account passwords}).
- @xref{After System Installation}, for what's next!
- @node After System Installation
- @section After System Installation
- Success, you've now booted into Guix System! From then on, you can update the
- system whenever you want by running, say:
- @example
- guix pull
- sudo guix system reconfigure /etc/config.scm
- @end example
- @noindent
- This builds a new system generation with the latest packages and services
- (@pxref{Invoking guix system}). We recommend doing that regularly so that
- your system includes the latest security updates (@pxref{Security Updates}).
- @c See <https://lists.gnu.org/archive/html/guix-devel/2019-01/msg00268.html>.
- @quotation Note
- @cindex sudo vs. @command{guix pull}
- Note that @command{sudo guix} runs your user's @command{guix} command and
- @emph{not} root's, because @command{sudo} leaves @env{PATH} unchanged. To
- explicitly run root's @command{guix}, type @command{sudo -i guix @dots{}}.
- The difference matters here, because @command{guix pull} updates
- the @command{guix} command and package definitions only for the user it is run
- as. This means that if you choose to use @command{guix system reconfigure} in
- root's login shell, you'll need to @command{guix pull} separately.
- @end quotation
- Now, @pxref{Getting Started}, and
- join us on @code{#guix} on the Libera Chat IRC network or on
- @email{guix-devel@@gnu.org} to share your experience!
- @node Installing Guix in a VM
- @section Installing Guix in a Virtual Machine
- @cindex virtual machine, Guix System installation
- @cindex virtual private server (VPS)
- @cindex VPS (virtual private server)
- If you'd like to install Guix System in a virtual machine (VM) or on a
- virtual private server (VPS) rather than on your beloved machine, this
- section is for you.
- To boot a @uref{https://qemu.org/,QEMU} VM for installing Guix System in a
- disk image, follow these steps:
- @enumerate
- @item
- First, retrieve and decompress the Guix system installation image as
- described previously (@pxref{USB Stick and DVD Installation}).
- @item
- Create a disk image that will hold the installed system. To make a
- qcow2-formatted disk image, use the @command{qemu-img} command:
- @example
- qemu-img create -f qcow2 guix-system.img 50G
- @end example
- The resulting file will be much smaller than 50 GB (typically less than
- 1 MB), but it will grow as the virtualized storage device is filled up.
- @item
- Boot the USB installation image in an VM:
- @example
- qemu-system-x86_64 -m 1024 -smp 1 -enable-kvm \
- -nic user,model=virtio-net-pci -boot menu=on,order=d \
- -drive file=guix-system.img \
- -drive media=cdrom,file=guix-system-install-@value{VERSION}.@var{system}.iso
- @end example
- @code{-enable-kvm} is optional, but significantly improves performance,
- @pxref{Running Guix in a VM}.
- @item
- You're now root in the VM, proceed with the installation process.
- @xref{Preparing for Installation}, and follow the instructions.
- @end enumerate
- Once installation is complete, you can boot the system that's on your
- @file{guix-system.img} image. @xref{Running Guix in a VM}, for how to do
- that.
- @node Building the Installation Image
- @section Building the Installation Image
- @cindex installation image
- The installation image described above was built using the @command{guix
- system} command, specifically:
- @example
- guix system image -t iso9660 gnu/system/install.scm
- @end example
- Have a look at @file{gnu/system/install.scm} in the source tree,
- and see also @ref{Invoking guix system} for more information
- about the installation image.
- @section Building the Installation Image for ARM Boards
- Many ARM boards require a specific variant of the
- @uref{https://www.denx.de/wiki/U-Boot/, U-Boot} bootloader.
- If you build a disk image and the bootloader is not available otherwise
- (on another boot drive etc), it's advisable to build an image that
- includes the bootloader, specifically:
- @example
- guix system image --system=armhf-linux -e '((@@ (gnu system install) os-with-u-boot) (@@ (gnu system install) installation-os) "A20-OLinuXino-Lime2")'
- @end example
- @code{A20-OLinuXino-Lime2} is the name of the board. If you specify an invalid
- board, a list of possible boards will be printed.
- @c *********************************************************************
- @node Getting Started
- @chapter Getting Started
- Presumably, you've reached this section because either you have
- installed Guix on top of another distribution (@pxref{Installation}), or
- you've installed the standalone Guix System (@pxref{System
- Installation}). It's time for you to get started using Guix and this
- section aims to help you do that and give you a feel of what it's like.
- Guix is about installing software, so probably the first thing you'll
- want to do is to actually look for software. Let's say you're looking
- for a text editor, you can run:
- @example
- guix search text editor
- @end example
- This command shows you a number of matching @dfn{packages}, each time
- showing the package's name, version, a description, and additional info.
- Once you've found out the one you want to use, let's say Emacs (ah ha!),
- you can go ahead and install it (run this command as a regular user,
- @emph{no need for root privileges}!):
- @example
- guix install emacs
- @end example
- @cindex profile
- You've installed your first package, congrats! The package is now
- visible in your default @dfn{profile}, @file{$HOME/.guix-profile}---a
- profile is a directory containing installed packages.
- In the process, you've
- probably noticed that Guix downloaded pre-built binaries; or, if you
- explicitly chose to @emph{not} use pre-built binaries, then probably
- Guix is still building software (@pxref{Substitutes}, for more info).
- Unless you're using Guix System, the @command{guix install} command must
- have printed this hint:
- @example
- hint: Consider setting the necessary environment variables by running:
- GUIX_PROFILE="$HOME/.guix-profile"
- . "$GUIX_PROFILE/etc/profile"
- Alternately, see `guix package --search-paths -p "$HOME/.guix-profile"'.
- @end example
- Indeed, you must now tell your shell where @command{emacs} and other
- programs installed with Guix are to be found. Pasting the two lines
- above will do just that: it will add
- @code{$HOME/.guix-profile/bin}---which is where the installed package
- is---to the @code{PATH} environment variable. You can paste these two
- lines in your shell so they take effect right away, but more importantly
- you should add them to @file{~/.bash_profile} (or equivalent file if you
- do not use Bash) so that environment variables are set next time you
- spawn a shell. You only need to do this once and other search paths
- environment variables will be taken care of similarly---e.g., if you
- eventually install @code{python} and Python libraries,
- @env{GUIX_PYTHONPATH} will be defined.
- You can go on installing packages at your will. To list installed
- packages, run:
- @example
- guix package --list-installed
- @end example
- To remove a package, you would unsurprisingly run @command{guix remove}.
- A distinguishing feature is the ability to @dfn{roll back} any operation
- you made---installation, removal, upgrade---by simply typing:
- @example
- guix package --roll-back
- @end example
- This is because each operation is in fact a @dfn{transaction} that
- creates a new @dfn{generation}. These generations and the difference
- between them can be displayed by running:
- @example
- guix package --list-generations
- @end example
- Now you know the basics of package management!
- @quotation Going further
- @xref{Package Management}, for more about package management. You may
- like @dfn{declarative} package management with @command{guix package
- --manifest}, managing separate @dfn{profiles} with @option{--profile},
- deleting old generations, collecting garbage, and other nifty features
- that will come in handy as you become more familiar with Guix. If you
- are a developer, @pxref{Development} for additional tools. And if
- you're curious, @pxref{Features}, to peek under the hood.
- @end quotation
- Once you've installed a set of packages, you will want to periodically
- @emph{upgrade} them to the latest and greatest version. To do that, you
- will first pull the latest revision of Guix and its package collection:
- @example
- guix pull
- @end example
- The end result is a new @command{guix} command, under
- @file{~/.config/guix/current/bin}. Unless you're on Guix System, the
- first time you run @command{guix pull}, be sure to follow the hint that
- the command prints and, similar to what we saw above, paste these two
- lines in your terminal and @file{.bash_profile}:
- @example
- GUIX_PROFILE="$HOME/.config/guix/current"
- . "$GUIX_PROFILE/etc/profile"
- @end example
- @noindent
- You must also instruct your shell to point to this new @command{guix}:
- @example
- hash guix
- @end example
- At this point, you're running a brand new Guix. You can thus go ahead
- and actually upgrade all the packages you previously installed:
- @example
- guix upgrade
- @end example
- As you run this command, you will see that binaries are downloaded (or
- perhaps some packages are built), and eventually you end up with the
- upgraded packages. Should one of these upgraded packages not be to your
- liking, remember you can always roll back!
- You can display the exact revision of Guix you're currently using by
- running:
- @example
- guix describe
- @end example
- The information it displays is @emph{all it takes to reproduce the exact
- same Guix}, be it at a different point in time or on a different
- machine.
- @quotation Going further
- @xref{Invoking guix pull}, for more information. @xref{Channels}, on
- how to specify additional @dfn{channels} to pull packages from, how to
- replicate Guix, and more. You may also find @command{time-machine}
- handy (@pxref{Invoking guix time-machine}).
- @end quotation
- If you installed Guix System, one of the first things you'll want to do
- is to upgrade your system. Once you've run @command{guix pull} to get
- the latest Guix, you can upgrade the system like this:
- @example
- sudo guix system reconfigure /etc/config.scm
- @end example
- Upon completion, the system runs the latest versions of its software
- packages. When you eventually reboot, you'll notice a sub-menu in the
- bootloader that reads ``Old system generations'': it's what allows you
- to boot @emph{an older generation of your system}, should the latest
- generation be ``broken'' or otherwise unsatisfying. Just like for
- packages, you can always @emph{roll back} to a previous generation
- @emph{of the whole system}:
- @example
- sudo guix system roll-back
- @end example
- There are many things you'll probably want to tweak on your system:
- adding new user accounts, adding new system services, fiddling with the
- configuration of those services, etc. The system configuration is
- @emph{entirely} described in the @file{/etc/config.scm} file.
- @xref{Using the Configuration System}, to learn how to change it.
- Now you know enough to get started!
- @quotation Resources
- The rest of this manual provides a reference for all things Guix. Here
- are some additional resources you may find useful:
- @itemize
- @item
- @xref{Top,,, guix-cookbook, The GNU Guix Cookbook}, for a list of
- ``how-to'' style of recipes for a variety of applications.
- @item
- The @uref{https://guix.gnu.org/guix-refcard.pdf, GNU Guix Reference
- Card} lists in two pages most of the commands and options you'll ever
- need.
- @item
- The web site contains @uref{https://guix.gnu.org/en/videos/,
- instructional videos} covering topics such as everyday use of Guix, how
- to get help, and how to become a contributor.
- @item
- @xref{Documentation}, to learn how to access documentation on your
- computer.
- @end itemize
- We hope you will enjoy Guix as much as the community enjoys building it!
- @end quotation
- @c *********************************************************************
- @node Package Management
- @chapter Package Management
- @cindex packages
- The purpose of GNU Guix is to allow users to easily install, upgrade, and
- remove software packages, without having to know about their build
- procedures or dependencies. Guix also goes beyond this obvious set of
- features.
- This chapter describes the main features of Guix, as well as the
- package management tools it provides. Along with the command-line
- interface described below (@pxref{Invoking guix package, @code{guix
- package}}), you may also use the Emacs-Guix interface (@pxref{Top,,,
- emacs-guix, The Emacs-Guix Reference Manual}), after installing
- @code{emacs-guix} package (run @kbd{M-x guix-help} command to start
- with it):
- @example
- guix install emacs-guix
- @end example
- @menu
- * Features:: How Guix will make your life brighter.
- * Invoking guix package:: Package installation, removal, etc.
- * Substitutes:: Downloading pre-built binaries.
- * Packages with Multiple Outputs:: Single source package, multiple outputs.
- * Invoking guix gc:: Running the garbage collector.
- * Invoking guix pull:: Fetching the latest Guix and distribution.
- * Invoking guix time-machine:: Running an older revision of Guix.
- * Inferiors:: Interacting with another revision of Guix.
- * Invoking guix describe:: Display information about your Guix revision.
- * Invoking guix archive:: Exporting and importing store files.
- @end menu
- @node Features
- @section Features
- Here we assume you've already made your first steps with Guix
- (@pxref{Getting Started}) and would like to get an overview about what's
- going on under the hood.
- When using Guix, each package ends up in the @dfn{package store}, in its
- own directory---something that resembles
- @file{/gnu/store/xxx-package-1.2}, where @code{xxx} is a base32 string.
- Instead of referring to these directories, users have their own
- @dfn{profile}, which points to the packages that they actually want to
- use. These profiles are stored within each user's home directory, at
- @code{$HOME/.guix-profile}.
- For example, @code{alice} installs GCC 4.7.2. As a result,
- @file{/home/alice/.guix-profile/bin/gcc} points to
- @file{/gnu/store/@dots{}-gcc-4.7.2/bin/gcc}. Now, on the same machine,
- @code{bob} had already installed GCC 4.8.0. The profile of @code{bob}
- simply continues to point to
- @file{/gnu/store/@dots{}-gcc-4.8.0/bin/gcc}---i.e., both versions of GCC
- coexist on the same system without any interference.
- The @command{guix package} command is the central tool to manage
- packages (@pxref{Invoking guix package}). It operates on the per-user
- profiles, and can be used @emph{with normal user privileges}.
- @cindex transactions
- The command provides the obvious install, remove, and upgrade
- operations. Each invocation is actually a @emph{transaction}: either
- the specified operation succeeds, or nothing happens. Thus, if the
- @command{guix package} process is terminated during the transaction,
- or if a power outage occurs during the transaction, then the user's
- profile remains in its previous state, and remains usable.
- In addition, any package transaction may be @emph{rolled back}. So, if,
- for example, an upgrade installs a new version of a package that turns
- out to have a serious bug, users may roll back to the previous instance
- of their profile, which was known to work well. Similarly, the global
- system configuration on Guix is subject to
- transactional upgrades and roll-back
- (@pxref{Using the Configuration System}).
- All packages in the package store may be @emph{garbage-collected}.
- Guix can determine which packages are still referenced by user
- profiles, and remove those that are provably no longer referenced
- (@pxref{Invoking guix gc}). Users may also explicitly remove old
- generations of their profile so that the packages they refer to can be
- collected.
- @cindex reproducibility
- @cindex reproducible builds
- Guix takes a @dfn{purely functional} approach to package
- management, as described in the introduction (@pxref{Introduction}).
- Each @file{/gnu/store} package directory name contains a hash of all the
- inputs that were used to build that package---compiler, libraries, build
- scripts, etc. This direct correspondence allows users to make sure a
- given package installation matches the current state of their
- distribution. It also helps maximize @dfn{build reproducibility}:
- thanks to the isolated build environments that are used, a given build
- is likely to yield bit-identical files when performed on different
- machines (@pxref{Invoking guix-daemon, container}).
- @cindex substitutes
- This foundation allows Guix to support @dfn{transparent binary/source
- deployment}. When a pre-built binary for a @file{/gnu/store} item is
- available from an external source---a @dfn{substitute}, Guix just
- downloads it and unpacks it;
- otherwise, it builds the package from source, locally
- (@pxref{Substitutes}). Because build results are usually bit-for-bit
- reproducible, users do not have to trust servers that provide
- substitutes: they can force a local build and @emph{challenge} providers
- (@pxref{Invoking guix challenge}).
- Control over the build environment is a feature that is also useful for
- developers. The @command{guix shell} command allows developers of
- a package to quickly set up the right development environment for their
- package, without having to manually install the dependencies of the
- package into their profile (@pxref{Invoking guix shell}).
- @cindex replication, of software environments
- @cindex provenance tracking, of software artifacts
- All of Guix and its package definitions is version-controlled, and
- @command{guix pull} allows you to ``travel in time'' on the history of Guix
- itself (@pxref{Invoking guix pull}). This makes it possible to replicate a
- Guix instance on a different machine or at a later point in time, which in
- turn allows you to @emph{replicate complete software environments}, while
- retaining precise @dfn{provenance tracking} of the software.
- @node Invoking guix package
- @section Invoking @command{guix package}
- @cindex installing packages
- @cindex removing packages
- @cindex package installation
- @cindex package removal
- @cindex profile
- The @command{guix package} command is the tool that allows users to
- install, upgrade, and remove packages, as well as rolling back to
- previous configurations. These operations work on a user
- @dfn{profile}---a directory of installed packages. Each user has a
- default profile in @file{$HOME/.guix-profile}.
- The command operates only on the user's own profile,
- and works with normal user privileges (@pxref{Features}). Its syntax
- is:
- @example
- guix package @var{options}
- @end example
- @cindex transactions
- Primarily, @var{options} specifies the operations to be performed during
- the transaction. Upon completion, a new profile is created, but
- previous @dfn{generations} of the profile remain available, should the user
- want to roll back.
- For example, to remove @code{lua} and install @code{guile} and
- @code{guile-cairo} in a single transaction:
- @example
- guix package -r lua -i guile guile-cairo
- @end example
- @cindex aliases, for @command{guix package}
- For your convenience, we also provide the following aliases:
- @itemize
- @item
- @command{guix search} is an alias for @command{guix package -s},
- @item
- @command{guix install} is an alias for @command{guix package -i},
- @item
- @command{guix remove} is an alias for @command{guix package -r},
- @item
- @command{guix upgrade} is an alias for @command{guix package -u},
- @item
- and @command{guix show} is an alias for @command{guix package --show=}.
- @end itemize
- These aliases are less expressive than @command{guix package} and provide
- fewer options, so in some cases you'll probably want to use @command{guix
- package} directly.
- @command{guix package} also supports a @dfn{declarative approach}
- whereby the user specifies the exact set of packages to be available and
- passes it @i{via} the @option{--manifest} option
- (@pxref{profile-manifest, @option{--manifest}}).
- @cindex profile
- For each user, a symlink to the user's default profile is automatically
- created in @file{$HOME/.guix-profile}. This symlink always points to the
- current generation of the user's default profile. Thus, users can add
- @file{$HOME/.guix-profile/bin} to their @env{PATH} environment
- variable, and so on.
- @cindex search paths
- If you are not using Guix System, consider adding the
- following lines to your @file{~/.bash_profile} (@pxref{Bash Startup
- Files,,, bash, The GNU Bash Reference Manual}) so that newly-spawned
- shells get all the right environment variable definitions:
- @example
- GUIX_PROFILE="$HOME/.guix-profile" ; \
- source "$GUIX_PROFILE/etc/profile"
- @end example
- In a multi-user setup, user profiles are stored in a place registered as
- a @dfn{garbage-collector root}, which @file{$HOME/.guix-profile} points
- to (@pxref{Invoking guix gc}). That directory is normally
- @code{@var{localstatedir}/guix/profiles/per-user/@var{user}}, where
- @var{localstatedir} is the value passed to @code{configure} as
- @option{--localstatedir}, and @var{user} is the user name. The
- @file{per-user} directory is created when @command{guix-daemon} is
- started, and the @var{user} sub-directory is created by @command{guix
- package}.
- The @var{options} can be among the following:
- @table @code
- @item --install=@var{package} @dots{}
- @itemx -i @var{package} @dots{}
- Install the specified @var{package}s.
- Each @var{package} may specify either a simple package name, such as
- @code{guile}, or a package name followed by an at-sign and version number,
- such as @code{guile@@1.8.8} or simply @code{guile@@1.8} (in the latter
- case, the newest version prefixed by @code{1.8} is selected).
- If no version number is specified, the
- newest available version will be selected. In addition, @var{package}
- may contain a colon, followed by the name of one of the outputs of the
- package, as in @code{gcc:doc} or @code{binutils@@2.22:lib}
- (@pxref{Packages with Multiple Outputs}). Packages with a corresponding
- name (and optionally version) are searched for among the GNU
- distribution modules (@pxref{Package Modules}).
- @cindex propagated inputs
- Sometimes packages have @dfn{propagated inputs}: these are dependencies
- that automatically get installed along with the required package
- (@pxref{package-propagated-inputs, @code{propagated-inputs} in
- @code{package} objects}, for information about propagated inputs in
- package definitions).
- @anchor{package-cmd-propagated-inputs}
- An example is the GNU MPC library: its C header files refer to those of
- the GNU MPFR library, which in turn refer to those of the GMP library.
- Thus, when installing MPC, the MPFR and GMP libraries also get installed
- in the profile; removing MPC also removes MPFR and GMP---unless they had
- also been explicitly installed by the user.
- Besides, packages sometimes rely on the definition of environment
- variables for their search paths (see explanation of
- @option{--search-paths} below). Any missing or possibly incorrect
- environment variable definitions are reported here.
- @item --install-from-expression=@var{exp}
- @itemx -e @var{exp}
- Install the package @var{exp} evaluates to.
- @var{exp} must be a Scheme expression that evaluates to a
- @code{<package>} object. This option is notably useful to disambiguate
- between same-named variants of a package, with expressions such as
- @code{(@@ (gnu packages base) guile-final)}.
- Note that this option installs the first output of the specified
- package, which may be insufficient when needing a specific output of a
- multiple-output package.
- @item --install-from-file=@var{file}
- @itemx -f @var{file}
- Install the package that the code within @var{file} evaluates to.
- As an example, @var{file} might contain a definition like this
- (@pxref{Defining Packages}):
- @lisp
- @include package-hello.scm
- @end lisp
- Developers may find it useful to include such a @file{guix.scm} file
- in the root of their project source tree that can be used to test
- development snapshots and create reproducible development environments
- (@pxref{Invoking guix shell}).
- The @var{file} may also contain a JSON representation of one or more
- package definitions. Running @code{guix package -f} on
- @file{hello.json} with the following contents would result in installing
- the package @code{greeter} after building @code{myhello}:
- @example
- @verbatiminclude package-hello.json
- @end example
- @item --remove=@var{package} @dots{}
- @itemx -r @var{package} @dots{}
- Remove the specified @var{package}s.
- As for @option{--install}, each @var{package} may specify a version number
- and/or output name in addition to the package name. For instance,
- @samp{-r glibc:debug} would remove the @code{debug} output of
- @code{glibc}.
- @item --upgrade[=@var{regexp} @dots{}]
- @itemx -u [@var{regexp} @dots{}]
- @cindex upgrading packages
- Upgrade all the installed packages. If one or more @var{regexp}s are
- specified, upgrade only installed packages whose name matches a
- @var{regexp}. Also see the @option{--do-not-upgrade} option below.
- Note that this upgrades package to the latest version of packages found
- in the distribution currently installed. To update your distribution,
- you should regularly run @command{guix pull} (@pxref{Invoking guix
- pull}).
- @cindex package transformations, upgrades
- When upgrading, package transformations that were originally applied
- when creating the profile are automatically re-applied (@pxref{Package
- Transformation Options}). For example, assume you first installed Emacs
- from the tip of its development branch with:
- @example
- guix install emacs-next --with-branch=emacs-next=master
- @end example
- Next time you run @command{guix upgrade}, Guix will again pull the tip
- of the Emacs development branch and build @code{emacs-next} from that
- checkout.
- Note that transformation options such as @option{--with-branch} and
- @option{--with-source} depend on external state; it is up to you to
- ensure that they work as expected. You can also discard a
- transformations that apply to a package by running:
- @example
- guix install @var{package}
- @end example
- @item --do-not-upgrade[=@var{regexp} @dots{}]
- When used together with the @option{--upgrade} option, do @emph{not}
- upgrade any packages whose name matches a @var{regexp}. For example, to
- upgrade all packages in the current profile except those containing the
- substring ``emacs'':
- @example
- $ guix package --upgrade . --do-not-upgrade emacs
- @end example
- @item @anchor{profile-manifest}--manifest=@var{file}
- @itemx -m @var{file}
- @cindex profile declaration
- @cindex profile manifest
- Create a new generation of the profile from the manifest object
- returned by the Scheme code in @var{file}. This option can be repeated
- several times, in which case the manifests are concatenated.
- This allows you to @emph{declare} the profile's contents rather than
- constructing it through a sequence of @option{--install} and similar
- commands. The advantage is that @var{file} can be put under version
- control, copied to different machines to reproduce the same profile, and
- so on.
- @c FIXME: Add reference to (guix profile) documentation when available.
- @var{file} must return a @dfn{manifest} object, which is roughly a list
- of packages:
- @findex packages->manifest
- @lisp
- (use-package-modules guile emacs)
- (packages->manifest
- (list emacs
- guile-2.0
- ;; Use a specific package output.
- (list guile-2.0 "debug")))
- @end lisp
- @findex specifications->manifest
- In this example we have to know which modules define the @code{emacs}
- and @code{guile-2.0} variables to provide the right
- @code{use-package-modules} line, which can be cumbersome. We can
- instead provide regular package specifications and let
- @code{specifications->manifest} look up the corresponding package
- objects, like this:
- @lisp
- (specifications->manifest
- '("emacs" "guile@@2.2" "guile@@2.2:debug"))
- @end lisp
- @findex package->development-manifest
- You might also want to create a manifest for all the dependencies of a
- package, rather than the package itself:
- @lisp
- (package->development-manifest (specification->package "emacs"))
- @end lisp
- The example above gives you all the software required to develop Emacs,
- similar to what @command{guix environment emacs} provides.
- @xref{export-manifest, @option{--export-manifest}}, to learn how to
- obtain a manifest file from an existing profile.
- @item --roll-back
- @cindex rolling back
- @cindex undoing transactions
- @cindex transactions, undoing
- Roll back to the previous @dfn{generation} of the profile---i.e., undo
- the last transaction.
- When combined with options such as @option{--install}, roll back occurs
- before any other actions.
- When rolling back from the first generation that actually contains
- installed packages, the profile is made to point to the @dfn{zeroth
- generation}, which contains no files apart from its own metadata.
- After having rolled back, installing, removing, or upgrading packages
- overwrites previous future generations. Thus, the history of the
- generations in a profile is always linear.
- @item --switch-generation=@var{pattern}
- @itemx -S @var{pattern}
- @cindex generations
- Switch to a particular generation defined by @var{pattern}.
- @var{pattern} may be either a generation number or a number prefixed
- with ``+'' or ``-''. The latter means: move forward/backward by a
- specified number of generations. For example, if you want to return to
- the latest generation after @option{--roll-back}, use
- @option{--switch-generation=+1}.
- The difference between @option{--roll-back} and
- @option{--switch-generation=-1} is that @option{--switch-generation} will
- not make a zeroth generation, so if a specified generation does not
- exist, the current generation will not be changed.
- @item --search-paths[=@var{kind}]
- @cindex search paths
- Report environment variable definitions, in Bash syntax, that may be
- needed in order to use the set of installed packages. These environment
- variables are used to specify @dfn{search paths} for files used by some
- of the installed packages.
- For example, GCC needs the @env{CPATH} and @env{LIBRARY_PATH}
- environment variables to be defined so it can look for headers and
- libraries in the user's profile (@pxref{Environment Variables,,, gcc,
- Using the GNU Compiler Collection (GCC)}). If GCC and, say, the C
- library are installed in the profile, then @option{--search-paths} will
- suggest setting these variables to @file{@var{profile}/include} and
- @file{@var{profile}/lib}, respectively (@pxref{Search Paths}, for info
- on search path specifications associated with packages.)
- The typical use case is to define these environment variables in the
- shell:
- @example
- $ eval `guix package --search-paths`
- @end example
- @var{kind} may be one of @code{exact}, @code{prefix}, or @code{suffix},
- meaning that the returned environment variable definitions will either
- be exact settings, or prefixes or suffixes of the current value of these
- variables. When omitted, @var{kind} defaults to @code{exact}.
- This option can also be used to compute the @emph{combined} search paths
- of several profiles. Consider this example:
- @example
- $ guix package -p foo -i guile
- $ guix package -p bar -i guile-json
- $ guix package -p foo -p bar --search-paths
- @end example
- The last command above reports about the @env{GUILE_LOAD_PATH}
- variable, even though, taken individually, neither @file{foo} nor
- @file{bar} would lead to that recommendation.
- @cindex profile, choosing
- @item --profile=@var{profile}
- @itemx -p @var{profile}
- Use @var{profile} instead of the user's default profile.
- @var{profile} must be the name of a file that will be created upon
- completion. Concretely, @var{profile} will be a mere symbolic link
- (``symlink'') pointing to the actual profile where packages are
- installed:
- @example
- $ guix install hello -p ~/code/my-profile
- @dots{}
- $ ~/code/my-profile/bin/hello
- Hello, world!
- @end example
- All it takes to get rid of the profile is to remove this symlink and its
- siblings that point to specific generations:
- @example
- $ rm ~/code/my-profile ~/code/my-profile-*-link
- @end example
- @item --list-profiles
- List all the user's profiles:
- @example
- $ guix package --list-profiles
- /home/charlie/.guix-profile
- /home/charlie/code/my-profile
- /home/charlie/code/devel-profile
- /home/charlie/tmp/test
- @end example
- When running as root, list all the profiles of all the users.
- @cindex collisions, in a profile
- @cindex colliding packages in profiles
- @cindex profile collisions
- @item --allow-collisions
- Allow colliding packages in the new profile. Use at your own risk!
- By default, @command{guix package} reports as an error @dfn{collisions}
- in the profile. Collisions happen when two or more different versions
- or variants of a given package end up in the profile.
- @item --bootstrap
- Use the bootstrap Guile to build the profile. This option is only
- useful to distribution developers.
- @end table
- In addition to these actions, @command{guix package} supports the
- following options to query the current state of a profile, or the
- availability of packages:
- @table @option
- @item --search=@var{regexp}
- @itemx -s @var{regexp}
- @anchor{guix-search}
- @cindex searching for packages
- List the available packages whose name, synopsis, or description matches
- @var{regexp} (in a case-insensitive fashion), sorted by relevance.
- Print all the metadata of matching packages in
- @code{recutils} format (@pxref{Top, GNU recutils databases,, recutils,
- GNU recutils manual}).
- This allows specific fields to be extracted using the @command{recsel}
- command, for instance:
- @example
- $ guix package -s malloc | recsel -p name,version,relevance
- name: jemalloc
- version: 4.5.0
- relevance: 6
- name: glibc
- version: 2.25
- relevance: 1
- name: libgc
- version: 7.6.0
- relevance: 1
- @end example
- Similarly, to show the name of all the packages available under the
- terms of the GNU@tie{}LGPL version 3:
- @example
- $ guix package -s "" | recsel -p name -e 'license ~ "LGPL 3"'
- name: elfutils
- name: gmp
- @dots{}
- @end example
- It is also possible to refine search results using several @code{-s} flags to
- @command{guix package}, or several arguments to @command{guix search}. For
- example, the following command returns a list of board games (this time using
- the @command{guix search} alias):
- @example
- $ guix search '\<board\>' game | recsel -p name
- name: gnubg
- @dots{}
- @end example
- If we were to omit @code{-s game}, we would also get software packages
- that deal with printed circuit boards; removing the angle brackets
- around @code{board} would further add packages that have to do with
- keyboards.
- And now for a more elaborate example. The following command searches
- for cryptographic libraries, filters out Haskell, Perl, Python, and Ruby
- libraries, and prints the name and synopsis of the matching packages:
- @example
- $ guix search crypto library | \
- recsel -e '! (name ~ "^(ghc|perl|python|ruby)")' -p name,synopsis
- @end example
- @noindent
- @xref{Selection Expressions,,, recutils, GNU recutils manual}, for more
- information on @dfn{selection expressions} for @code{recsel -e}.
- @item --show=@var{package}
- Show details about @var{package}, taken from the list of available packages, in
- @code{recutils} format (@pxref{Top, GNU recutils databases,, recutils, GNU
- recutils manual}).
- @example
- $ guix package --show=guile | recsel -p name,version
- name: guile
- version: 3.0.5
- name: guile
- version: 3.0.2
- name: guile
- version: 2.2.7
- @dots{}
- @end example
- You may also specify the full name of a package to only get details about a
- specific version of it (this time using the @command{guix show} alias):
- @example
- $ guix show guile@@3.0.5 | recsel -p name,version
- name: guile
- version: 3.0.5
- @end example
- @item --list-installed[=@var{regexp}]
- @itemx -I [@var{regexp}]
- List the currently installed packages in the specified profile, with the
- most recently installed packages shown last. When @var{regexp} is
- specified, list only installed packages whose name matches @var{regexp}.
- For each installed package, print the following items, separated by
- tabs: the package name, its version string, the part of the package that
- is installed (for instance, @code{out} for the default output,
- @code{include} for its headers, etc.), and the path of this package in
- the store.
- @item --list-available[=@var{regexp}]
- @itemx -A [@var{regexp}]
- List packages currently available in the distribution for this system
- (@pxref{GNU Distribution}). When @var{regexp} is specified, list only
- available packages whose name matches @var{regexp}.
- For each package, print the following items separated by tabs: its name,
- its version string, the parts of the package (@pxref{Packages with
- Multiple Outputs}), and the source location of its definition.
- @item --list-generations[=@var{pattern}]
- @itemx -l [@var{pattern}]
- @cindex generations
- Return a list of generations along with their creation dates; for each
- generation, show the installed packages, with the most recently
- installed packages shown last. Note that the zeroth generation is never
- shown.
- For each installed package, print the following items, separated by
- tabs: the name of a package, its version string, the part of the package
- that is installed (@pxref{Packages with Multiple Outputs}), and the
- location of this package in the store.
- When @var{pattern} is used, the command returns only matching
- generations. Valid patterns include:
- @itemize
- @item @emph{Integers and comma-separated integers}. Both patterns denote
- generation numbers. For instance, @option{--list-generations=1} returns
- the first one.
- And @option{--list-generations=1,8,2} outputs three generations in the
- specified order. Neither spaces nor trailing commas are allowed.
- @item @emph{Ranges}. @option{--list-generations=2..9} prints the
- specified generations and everything in between. Note that the start of
- a range must be smaller than its end.
- It is also possible to omit the endpoint. For example,
- @option{--list-generations=2..}, returns all generations starting from the
- second one.
- @item @emph{Durations}. You can also get the last @emph{N}@tie{}days, weeks,
- or months by passing an integer along with the first letter of the
- duration. For example, @option{--list-generations=20d} lists generations
- that are up to 20 days old.
- @end itemize
- @item --delete-generations[=@var{pattern}]
- @itemx -d [@var{pattern}]
- When @var{pattern} is omitted, delete all generations except the current
- one.
- This command accepts the same patterns as @option{--list-generations}.
- When @var{pattern} is specified, delete the matching generations. When
- @var{pattern} specifies a duration, generations @emph{older} than the
- specified duration match. For instance, @option{--delete-generations=1m}
- deletes generations that are more than one month old.
- If the current generation matches, it is @emph{not} deleted. Also, the
- zeroth generation is never deleted.
- Note that deleting generations prevents rolling back to them.
- Consequently, this command must be used with care.
- @cindex manifest, exporting
- @anchor{export-manifest}
- @item --export-manifest
- Write to standard output a manifest suitable for @option{--manifest}
- corresponding to the chosen profile(s).
- This option is meant to help you migrate from the ``imperative''
- operating mode---running @command{guix install}, @command{guix upgrade},
- etc.---to the declarative mode that @option{--manifest} offers.
- Be aware that the resulting manifest @emph{approximates} what your
- profile actually contains; for instance, depending on how your profile
- was created, it can refer to packages or package versions that are not
- exactly what you specified.
- Keep in mind that a manifest is purely symbolic: it only contains
- package names and possibly versions, and their meaning varies over time.
- If you wish to ``pin'' channels to the revisions that were used to build
- the profile(s), see @option{--export-channels} below.
- @cindex pinning, channel revisions of a profile
- @item --export-channels
- Write to standard output the list of channels used by the chosen
- profile(s), in a format suitable for @command{guix pull --channels} or
- @command{guix time-machine --channels} (@pxref{Channels}).
- Together with @option{--export-manifest}, this option provides
- information allowing you to replicate the current profile
- (@pxref{Replicating Guix}).
- However, note that the output of this command @emph{approximates} what
- was actually used to build this profile. In particular, a single
- profile might have been built from several different revisions of the
- same channel. In that case, @option{--export-manifest} chooses the last
- one and writes the list of other revisions in a comment. If you really
- need to pick packages from different channel revisions, you can use
- inferiors in your manifest to do so (@pxref{Inferiors}).
- Together with @option{--export-manifest}, this is a good starting point
- if you are willing to migrate from the ``imperative'' model to the fully
- declarative model consisting of a manifest file along with a channels
- file pinning the exact channel revision(s) you want.
- @end table
- Finally, since @command{guix package} may actually start build
- processes, it supports all the common build options (@pxref{Common Build
- Options}). It also supports package transformation options, such as
- @option{--with-source}, and preserves them across upgrades
- (@pxref{Package Transformation Options}).
- @node Substitutes
- @section Substitutes
- @cindex substitutes
- @cindex pre-built binaries
- Guix supports transparent source/binary deployment, which means that it
- can either build things locally, or download pre-built items from a
- server, or both. We call these pre-built items @dfn{substitutes}---they
- are substitutes for local build results. In many cases, downloading a
- substitute is much faster than building things locally.
- Substitutes can be anything resulting from a derivation build
- (@pxref{Derivations}). Of course, in the common case, they are
- pre-built package binaries, but source tarballs, for instance, which
- also result from derivation builds, can be available as substitutes.
- @menu
- * Official Substitute Servers:: One particular source of substitutes.
- * Substitute Server Authorization:: How to enable or disable substitutes.
- * Getting Substitutes from Other Servers:: Substitute diversity.
- * Substitute Authentication:: How Guix verifies substitutes.
- * Proxy Settings:: How to get substitutes via proxy.
- * Substitution Failure:: What happens when substitution fails.
- * On Trusting Binaries:: How can you trust that binary blob?
- @end menu
- @node Official Substitute Servers
- @subsection Official Substitute Servers
- @cindex build farm
- @code{@value{SUBSTITUTE-SERVER-1}} and
- @code{@value{SUBSTITUTE-SERVER-2}} are both front-ends to official build
- farms that build packages from Guix continuously for some architectures,
- and make them available as substitutes. These are the default source of
- substitutes; which can be overridden by passing the
- @option{--substitute-urls} option either to @command{guix-daemon}
- (@pxref{daemon-substitute-urls,, @code{guix-daemon --substitute-urls}})
- or to client tools such as @command{guix package}
- (@pxref{client-substitute-urls,, client @option{--substitute-urls}
- option}).
- Substitute URLs can be either HTTP or HTTPS.
- HTTPS is recommended because communications are encrypted; conversely,
- using HTTP makes all communications visible to an eavesdropper, who
- could use the information gathered to determine, for instance, whether
- your system has unpatched security vulnerabilities.
- Substitutes from the official build farms are enabled by default when
- using Guix System (@pxref{GNU Distribution}). However,
- they are disabled by default when using Guix on a foreign distribution,
- unless you have explicitly enabled them via one of the recommended
- installation steps (@pxref{Installation}). The following paragraphs
- describe how to enable or disable substitutes for the official build
- farm; the same procedure can also be used to enable substitutes for any
- other substitute server.
- @node Substitute Server Authorization
- @subsection Substitute Server Authorization
- @cindex security
- @cindex substitutes, authorization thereof
- @cindex access control list (ACL), for substitutes
- @cindex ACL (access control list), for substitutes
- To allow Guix to download substitutes from @code{@value{SUBSTITUTE-SERVER-1}}, @code{@value{SUBSTITUTE-SERVER-2}} or a mirror, you
- must add the relevant public key to the access control list (ACL) of archive
- imports, using the @command{guix archive} command (@pxref{Invoking guix
- archive}). Doing so implies that you trust the substitute server to not
- be compromised and to serve genuine substitutes.
- @quotation Note
- If you are using Guix System, you can skip this section: Guix System
- authorizes substitutes from @code{@value{SUBSTITUTE-SERVER-1}} and
- @code{@value{SUBSTITUTE-SERVER-2}} by default.
- @end quotation
- The public keys for each of the project maintained substitute servers
- are installed along with Guix, in @code{@var{prefix}/share/guix/}, where
- @var{prefix} is the installation prefix of Guix. If you installed Guix
- from source, make sure you checked the GPG signature of
- @file{guix-@value{VERSION}.tar.gz}, which contains this public key file.
- Then, you can run something like this:
- @example
- # guix archive --authorize < @var{prefix}/share/guix/@value{SUBSTITUTE-SERVER-1}.pub
- # guix archive --authorize < @var{prefix}/share/guix/@value{SUBSTITUTE-SERVER-2}.pub
- @end example
- Once this is in place, the output of a command like @code{guix build}
- should change from something like:
- @example
- $ guix build emacs --dry-run
- The following derivations would be built:
- /gnu/store/yr7bnx8xwcayd6j95r2clmkdl1qh688w-emacs-24.3.drv
- /gnu/store/x8qsh1hlhgjx6cwsjyvybnfv2i37z23w-dbus-1.6.4.tar.gz.drv
- /gnu/store/1ixwp12fl950d15h2cj11c73733jay0z-alsa-lib-1.0.27.1.tar.bz2.drv
- /gnu/store/nlma1pw0p603fpfiqy7kn4zm105r5dmw-util-linux-2.21.drv
- @dots{}
- @end example
- @noindent
- to something like:
- @example
- $ guix build emacs --dry-run
- 112.3 MB would be downloaded:
- /gnu/store/pk3n22lbq6ydamyymqkkz7i69wiwjiwi-emacs-24.3
- /gnu/store/2ygn4ncnhrpr61rssa6z0d9x22si0va3-libjpeg-8d
- /gnu/store/71yz6lgx4dazma9dwn2mcjxaah9w77jq-cairo-1.12.16
- /gnu/store/7zdhgp0n1518lvfn8mb96sxqfmvqrl7v-libxrender-0.9.7
- @dots{}
- @end example
- @noindent
- The text changed from ``The following derivations would be built'' to
- ``112.3 MB would be downloaded''. This indicates that substitutes from
- the configured substitute servers are usable and will be downloaded,
- when possible, for future builds.
- @cindex substitutes, how to disable
- The substitute mechanism can be disabled globally by running
- @code{guix-daemon} with @option{--no-substitutes} (@pxref{Invoking
- guix-daemon}). It can also be disabled temporarily by passing the
- @option{--no-substitutes} option to @command{guix package},
- @command{guix build}, and other command-line tools.
- @node Getting Substitutes from Other Servers
- @subsection Getting Substitutes from Other Servers
- @cindex substitute servers, adding more
- Guix can look up and fetch substitutes from several servers. This is
- useful when you are using packages from additional channels for which
- the official server does not have substitutes but another server
- provides them. Another situation where this is useful is when you would
- prefer to download from your organization's substitute server, resorting
- to the official server only as a fallback or dismissing it altogether.
- You can give Guix a list of substitute server URLs and it will check
- them in the specified order. You also need to explicitly authorize the
- public keys of substitute servers to instruct Guix to accept the
- substitutes they sign.
- On Guix System, this is achieved by modifying the configuration of the
- @code{guix} service. Since the @code{guix} service is part of the
- default lists of services, @code{%base-services} and
- @code{%desktop-services}, you can use @code{modify-services} to change
- its configuration and add the URLs and substitute keys that you want
- (@pxref{Service Reference, @code{modify-services}}).
- As an example, suppose you want to fetch substitutes from
- @code{guix.example.org} and to authorize the signing key of that server,
- in addition to the default @code{@value{SUBSTITUTE-SERVER-1}} and
- @code{@value{SUBSTITUTE-SERVER-2}}. The resulting operating system
- configuration will look something like:
- @lisp
- (operating-system
- ;; @dots{}
- (services
- ;; Assume we're starting from '%desktop-services'. Replace it
- ;; with the list of services you're actually using.
- (modify-services %desktop-services
- (guix-service-type config =>
- (guix-configuration
- (inherit config)
- (substitute-urls
- (append (list "https://guix.example.org")
- %default-substitute-urls))
- (authorized-keys
- (append (list (local-file "./key.pub"))
- %default-authorized-guix-keys)))))))
- @end lisp
- This assumes that the file @file{key.pub} contains the signing key of
- @code{guix.example.org}. With this change in place in your operating
- system configuration file (say @file{/etc/config.scm}), you can
- reconfigure and restart the @code{guix-daemon} service or reboot so the
- changes take effect:
- @example
- $ sudo guix system reconfigure /etc/config.scm
- $ sudo herd restart guix-daemon
- @end example
- If you're running Guix on a ``foreign distro'', you would instead take
- the following steps to get substitutes from additional servers:
- @enumerate
- @item
- Edit the service configuration file for @code{guix-daemon}; when using
- systemd, this is normally
- @file{/etc/systemd/system/guix-daemon.service}. Add the
- @option{--substitute-urls} option on the @command{guix-daemon} command
- line and list the URLs of interest (@pxref{daemon-substitute-urls,
- @code{guix-daemon --substitute-urls}}):
- @example
- @dots{} --substitute-urls='https://guix.example.org @value{SUBSTITUTE-URLS}'
- @end example
- @item
- Restart the daemon. For systemd, it goes like this:
- @example
- systemctl daemon-reload
- systemctl restart guix-daemon.service
- @end example
- @item
- Authorize the key of the new server (@pxref{Invoking guix archive}):
- @example
- guix archive --authorize < key.pub
- @end example
- Again this assumes @file{key.pub} contains the public key that
- @code{guix.example.org} uses to sign substitutes.
- @end enumerate
- Now you're all set! Substitutes will be preferably taken from
- @code{https://guix.example.org}, using
- @code{@value{SUBSTITUTE-SERVER-1}} then
- @code{@value{SUBSTITUTE-SERVER-2}} as fallback options. Of course you
- can list as many substitute servers as you like, with the caveat that
- substitute lookup can be slowed down if too many servers need to be
- contacted.
- Note that there are also situations where one may want to add the URL of
- a substitute server @emph{without} authorizing its key.
- @xref{Substitute Authentication}, to understand this fine point.
- @node Substitute Authentication
- @subsection Substitute Authentication
- @cindex digital signatures
- Guix detects and raises an error when attempting to use a substitute
- that has been tampered with. Likewise, it ignores substitutes that are
- not signed, or that are not signed by one of the keys listed in the ACL.
- There is one exception though: if an unauthorized server provides
- substitutes that are @emph{bit-for-bit identical} to those provided by
- an authorized server, then the unauthorized server becomes eligible for
- downloads. For example, assume we have chosen two substitute servers
- with this option:
- @example
- --substitute-urls="https://a.example.org https://b.example.org"
- @end example
- @noindent
- @cindex reproducible builds
- If the ACL contains only the key for @samp{b.example.org}, and if
- @samp{a.example.org} happens to serve the @emph{exact same} substitutes,
- then Guix will download substitutes from @samp{a.example.org} because it
- comes first in the list and can be considered a mirror of
- @samp{b.example.org}. In practice, independent build machines usually
- produce the same binaries, thanks to bit-reproducible builds (see
- below).
- When using HTTPS, the server's X.509 certificate is @emph{not} validated
- (in other words, the server is not authenticated), contrary to what
- HTTPS clients such as Web browsers usually do. This is because Guix
- authenticates substitute information itself, as explained above, which
- is what we care about (whereas X.509 certificates are about
- authenticating bindings between domain names and public keys).
- @node Proxy Settings
- @subsection Proxy Settings
- @vindex http_proxy
- @vindex https_proxy
- Substitutes are downloaded over HTTP or HTTPS@. The @env{http_proxy} and
- @env{https_proxy} environment variables can be set in the environment of
- @command{guix-daemon} and are honored for downloads of substitutes.
- Note that the value of those environment variables in the environment
- where @command{guix build}, @command{guix package}, and other client
- commands are run has @emph{absolutely no effect}.
- @node Substitution Failure
- @subsection Substitution Failure
- Even when a substitute for a derivation is available, sometimes the
- substitution attempt will fail. This can happen for a variety of
- reasons: the substitute server might be offline, the substitute may
- recently have been deleted, the connection might have been interrupted,
- etc.
- When substitutes are enabled and a substitute for a derivation is
- available, but the substitution attempt fails, Guix will attempt to
- build the derivation locally depending on whether or not
- @option{--fallback} was given (@pxref{fallback-option,, common build
- option @option{--fallback}}). Specifically, if @option{--fallback} was
- omitted, then no local build will be performed, and the derivation is
- considered to have failed. However, if @option{--fallback} was given,
- then Guix will attempt to build the derivation locally, and the success
- or failure of the derivation depends on the success or failure of the
- local build. Note that when substitutes are disabled or no substitute
- is available for the derivation in question, a local build will
- @emph{always} be performed, regardless of whether or not
- @option{--fallback} was given.
- To get an idea of how many substitutes are available right now, you can
- try running the @command{guix weather} command (@pxref{Invoking guix
- weather}). This command provides statistics on the substitutes provided
- by a server.
- @node On Trusting Binaries
- @subsection On Trusting Binaries
- @cindex trust, of pre-built binaries
- Today, each individual's control over their own computing is at the
- mercy of institutions, corporations, and groups with enough power and
- determination to subvert the computing infrastructure and exploit its
- weaknesses. While using substitutes can be convenient, we encourage
- users to also build on their own, or even run their own build farm, such
- that the project run substitute servers are less of an interesting
- target. One way to help is by publishing the software you build using
- @command{guix publish} so that others have one more choice of server to
- download substitutes from (@pxref{Invoking guix publish}).
- Guix has the foundations to maximize build reproducibility
- (@pxref{Features}). In most cases, independent builds of a given
- package or derivation should yield bit-identical results. Thus, through
- a diverse set of independent package builds, we can strengthen the
- integrity of our systems. The @command{guix challenge} command aims to
- help users assess substitute servers, and to assist developers in
- finding out about non-deterministic package builds (@pxref{Invoking guix
- challenge}). Similarly, the @option{--check} option of @command{guix
- build} allows users to check whether previously-installed substitutes
- are genuine by rebuilding them locally (@pxref{build-check,
- @command{guix build --check}}).
- In the future, we want Guix to have support to publish and retrieve
- binaries to/from other users, in a peer-to-peer fashion. If you would
- like to discuss this project, join us on @email{guix-devel@@gnu.org}.
- @node Packages with Multiple Outputs
- @section Packages with Multiple Outputs
- @cindex multiple-output packages
- @cindex package outputs
- @cindex outputs
- Often, packages defined in Guix have a single @dfn{output}---i.e., the
- source package leads to exactly one directory in the store. When running
- @command{guix install glibc}, one installs the default output of the
- GNU libc package; the default output is called @code{out}, but its name
- can be omitted as shown in this command. In this particular case, the
- default output of @code{glibc} contains all the C header files, shared
- libraries, static libraries, Info documentation, and other supporting
- files.
- Sometimes it is more appropriate to separate the various types of files
- produced from a single source package into separate outputs. For
- instance, the GLib C library (used by GTK+ and related packages)
- installs more than 20 MiB of reference documentation as HTML pages.
- To save space for users who do not need it, the documentation goes to a
- separate output, called @code{doc}. To install the main GLib output,
- which contains everything but the documentation, one would run:
- @example
- guix install glib
- @end example
- @cindex documentation
- The command to install its documentation is:
- @example
- guix install glib:doc
- @end example
- Some packages install programs with different ``dependency footprints''.
- For instance, the WordNet package installs both command-line tools and
- graphical user interfaces (GUIs). The former depend solely on the C
- library, whereas the latter depend on Tcl/Tk and the underlying X
- libraries. In this case, we leave the command-line tools in the default
- output, whereas the GUIs are in a separate output. This allows users
- who do not need the GUIs to save space. The @command{guix size} command
- can help find out about such situations (@pxref{Invoking guix size}).
- @command{guix graph} can also be helpful (@pxref{Invoking guix graph}).
- There are several such multiple-output packages in the GNU distribution.
- Other conventional output names include @code{lib} for libraries and
- possibly header files, @code{bin} for stand-alone programs, and
- @code{debug} for debugging information (@pxref{Installing Debugging
- Files}). The outputs of a packages are listed in the third column of
- the output of @command{guix package --list-available} (@pxref{Invoking
- guix package}).
- @node Invoking guix gc
- @section Invoking @command{guix gc}
- @cindex garbage collector
- @cindex disk space
- Packages that are installed, but not used, may be @dfn{garbage-collected}.
- The @command{guix gc} command allows users to explicitly run the garbage
- collector to reclaim space from the @file{/gnu/store} directory. It is
- the @emph{only} way to remove files from @file{/gnu/store}---removing
- files or directories manually may break it beyond repair!
- @cindex GC roots
- @cindex garbage collector roots
- The garbage collector has a set of known @dfn{roots}: any file under
- @file{/gnu/store} reachable from a root is considered @dfn{live} and
- cannot be deleted; any other file is considered @dfn{dead} and may be
- deleted. The set of garbage collector roots (``GC roots'' for short)
- includes default user profiles; by default, the symlinks under
- @file{/var/guix/gcroots} represent these GC roots. New GC roots can be
- added with @command{guix build --root}, for example (@pxref{Invoking
- guix build}). The @command{guix gc --list-roots} command lists them.
- Prior to running @code{guix gc --collect-garbage} to make space, it is
- often useful to remove old generations from user profiles; that way, old
- package builds referenced by those generations can be reclaimed. This
- is achieved by running @code{guix package --delete-generations}
- (@pxref{Invoking guix package}).
- Our recommendation is to run a garbage collection periodically, or when
- you are short on disk space. For instance, to guarantee that at least
- 5@tie{}GB are available on your disk, simply run:
- @example
- guix gc -F 5G
- @end example
- It is perfectly safe to run as a non-interactive periodic job
- (@pxref{Scheduled Job Execution}, for how to set up such a job).
- Running @command{guix gc} with no arguments will collect as
- much garbage as it can, but that is often inconvenient: you may find
- yourself having to rebuild or re-download software that is ``dead'' from
- the GC viewpoint but that is necessary to build other pieces of
- software---e.g., the compiler tool chain.
- The @command{guix gc} command has three modes of operation: it can be
- used to garbage-collect any dead files (the default), to delete specific
- files (the @option{--delete} option), to print garbage-collector
- information, or for more advanced queries. The garbage collection
- options are as follows:
- @table @code
- @item --collect-garbage[=@var{min}]
- @itemx -C [@var{min}]
- Collect garbage---i.e., unreachable @file{/gnu/store} files and
- sub-directories. This is the default operation when no option is
- specified.
- When @var{min} is given, stop once @var{min} bytes have been collected.
- @var{min} may be a number of bytes, or it may include a unit as a
- suffix, such as @code{MiB} for mebibytes and @code{GB} for gigabytes
- (@pxref{Block size, size specifications,, coreutils, GNU Coreutils}).
- When @var{min} is omitted, collect all the garbage.
- @item --free-space=@var{free}
- @itemx -F @var{free}
- Collect garbage until @var{free} space is available under
- @file{/gnu/store}, if possible; @var{free} denotes storage space, such
- as @code{500MiB}, as described above.
- When @var{free} or more is already available in @file{/gnu/store}, do
- nothing and exit immediately.
- @item --delete-generations[=@var{duration}]
- @itemx -d [@var{duration}]
- Before starting the garbage collection process, delete all the generations
- older than @var{duration}, for all the user profiles; when run as root, this
- applies to all the profiles @emph{of all the users}.
- For example, this command deletes all the generations of all your profiles
- that are older than 2 months (except generations that are current), and then
- proceeds to free space until at least 10 GiB are available:
- @example
- guix gc -d 2m -F 10G
- @end example
- @item --delete
- @itemx -D
- Attempt to delete all the store files and directories specified as
- arguments. This fails if some of the files are not in the store, or if
- they are still live.
- @item --list-failures
- List store items corresponding to cached build failures.
- This prints nothing unless the daemon was started with
- @option{--cache-failures} (@pxref{Invoking guix-daemon,
- @option{--cache-failures}}).
- @item --list-roots
- List the GC roots owned by the user; when run as root, list @emph{all} the GC
- roots.
- @item --list-busy
- List store items in use by currently running processes. These store
- items are effectively considered GC roots: they cannot be deleted.
- @item --clear-failures
- Remove the specified store items from the failed-build cache.
- Again, this option only makes sense when the daemon is started with
- @option{--cache-failures}. Otherwise, it does nothing.
- @item --list-dead
- Show the list of dead files and directories still present in the
- store---i.e., files and directories no longer reachable from any root.
- @item --list-live
- Show the list of live store files and directories.
- @end table
- In addition, the references among existing store files can be queried:
- @table @code
- @item --references
- @itemx --referrers
- @cindex package dependencies
- List the references (respectively, the referrers) of store files given
- as arguments.
- @item --requisites
- @itemx -R
- @cindex closure
- List the requisites of the store files passed as arguments. Requisites
- include the store files themselves, their references, and the references
- of these, recursively. In other words, the returned list is the
- @dfn{transitive closure} of the store files.
- @xref{Invoking guix size}, for a tool to profile the size of the closure
- of an element. @xref{Invoking guix graph}, for a tool to visualize
- the graph of references.
- @item --derivers
- @cindex derivation
- Return the derivation(s) leading to the given store items
- (@pxref{Derivations}).
- For example, this command:
- @example
- guix gc --derivers $(guix package -I ^emacs$ | cut -f4)
- @end example
- @noindent
- returns the @file{.drv} file(s) leading to the @code{emacs} package
- installed in your profile.
- Note that there may be zero matching @file{.drv} files, for instance
- because these files have been garbage-collected. There can also be more
- than one matching @file{.drv} due to fixed-output derivations.
- @end table
- Lastly, the following options allow you to check the integrity of the
- store and to control disk usage.
- @table @option
- @item --verify[=@var{options}]
- @cindex integrity, of the store
- @cindex integrity checking
- Verify the integrity of the store.
- By default, make sure that all the store items marked as valid in the
- database of the daemon actually exist in @file{/gnu/store}.
- When provided, @var{options} must be a comma-separated list containing one
- or more of @code{contents} and @code{repair}.
- When passing @option{--verify=contents}, the daemon computes the
- content hash of each store item and compares it against its hash in the
- database. Hash mismatches are reported as data corruptions. Because it
- traverses @emph{all the files in the store}, this command can take a
- long time, especially on systems with a slow disk drive.
- @cindex repairing the store
- @cindex corruption, recovering from
- Using @option{--verify=repair} or @option{--verify=contents,repair}
- causes the daemon to try to repair corrupt store items by fetching
- substitutes for them (@pxref{Substitutes}). Because repairing is not
- atomic, and thus potentially dangerous, it is available only to the
- system administrator. A lightweight alternative, when you know exactly
- which items in the store are corrupt, is @command{guix build --repair}
- (@pxref{Invoking guix build}).
- @item --optimize
- @cindex deduplication
- Optimize the store by hard-linking identical files---this is
- @dfn{deduplication}.
- The daemon performs deduplication after each successful build or archive
- import, unless it was started with @option{--disable-deduplication}
- (@pxref{Invoking guix-daemon, @option{--disable-deduplication}}). Thus,
- this option is primarily useful when the daemon was running with
- @option{--disable-deduplication}.
- @end table
- @node Invoking guix pull
- @section Invoking @command{guix pull}
- @cindex upgrading Guix
- @cindex updating Guix
- @cindex @command{guix pull}
- @cindex pull
- @cindex security, @command{guix pull}
- @cindex authenticity, of code obtained with @command{guix pull}
- Packages are installed or upgraded to the latest version available in
- the distribution currently available on your local machine. To update
- that distribution, along with the Guix tools, you must run @command{guix
- pull}: the command downloads the latest Guix source code and package
- descriptions, and deploys it. Source code is downloaded from a
- @uref{https://git-scm.com, Git} repository, by default the official
- GNU@tie{}Guix repository, though this can be customized. @command{guix
- pull} ensures that the code it downloads is @emph{authentic} by
- verifying that commits are signed by Guix developers.
- Specifically, @command{guix pull} downloads code from the @dfn{channels}
- (@pxref{Channels}) specified by one of the followings, in this order:
- @enumerate
- @item
- the @option{--channels} option;
- @item
- the user's @file{~/.config/guix/channels.scm} file;
- @item
- the system-wide @file{/etc/guix/channels.scm} file;
- @item
- the built-in default channels specified in the @code{%default-channels}
- variable.
- @end enumerate
- On completion, @command{guix package} will use packages and package
- versions from this just-retrieved copy of Guix. Not only that, but all
- the Guix commands and Scheme modules will also be taken from that latest
- version. New @command{guix} sub-commands added by the update also
- become available.
- Any user can update their Guix copy using @command{guix pull}, and the
- effect is limited to the user who ran @command{guix pull}. For
- instance, when user @code{root} runs @command{guix pull}, this has no
- effect on the version of Guix that user @code{alice} sees, and vice
- versa.
- The result of running @command{guix pull} is a @dfn{profile} available
- under @file{~/.config/guix/current} containing the latest Guix. Thus,
- make sure to add it to the beginning of your search path so that you use
- the latest version, and similarly for the Info manual
- (@pxref{Documentation}):
- @example
- export PATH="$HOME/.config/guix/current/bin:$PATH"
- export INFOPATH="$HOME/.config/guix/current/share/info:$INFOPATH"
- @end example
- The @option{--list-generations} or @option{-l} option lists past generations
- produced by @command{guix pull}, along with details about their provenance:
- @example
- $ guix pull -l
- Generation 1 Jun 10 2018 00:18:18
- guix 65956ad
- repository URL: https://git.savannah.gnu.org/git/guix.git
- branch: origin/master
- commit: 65956ad3526ba09e1f7a40722c96c6ef7c0936fe
- Generation 2 Jun 11 2018 11:02:49
- guix e0cc7f6
- repository URL: https://git.savannah.gnu.org/git/guix.git
- branch: origin/master
- commit: e0cc7f669bec22c37481dd03a7941c7d11a64f1d
- Generation 3 Jun 13 2018 23:31:07 (current)
- guix 844cc1c
- repository URL: https://git.savannah.gnu.org/git/guix.git
- branch: origin/master
- commit: 844cc1c8f394f03b404c5bb3aee086922373490c
- @end example
- @xref{Invoking guix describe, @command{guix describe}}, for other ways to
- describe the current status of Guix.
- This @code{~/.config/guix/current} profile works exactly like the profiles
- created by @command{guix package} (@pxref{Invoking guix package}). That
- is, you can list generations, roll back to the previous
- generation---i.e., the previous Guix---and so on:
- @example
- $ guix pull --roll-back
- switched from generation 3 to 2
- $ guix pull --delete-generations=1
- deleting /var/guix/profiles/per-user/charlie/current-guix-1-link
- @end example
- You can also use @command{guix package} (@pxref{Invoking guix package})
- to manage the profile by naming it explicitly:
- @example
- $ guix package -p ~/.config/guix/current --roll-back
- switched from generation 3 to 2
- $ guix package -p ~/.config/guix/current --delete-generations=1
- deleting /var/guix/profiles/per-user/charlie/current-guix-1-link
- @end example
- The @command{guix pull} command is usually invoked with no arguments,
- but it supports the following options:
- @table @code
- @item --url=@var{url}
- @itemx --commit=@var{commit}
- @itemx --branch=@var{branch}
- Download code for the @code{guix} channel from the specified @var{url}, at the
- given @var{commit} (a valid Git commit ID represented as a hexadecimal
- string), or @var{branch}.
- @cindex @file{channels.scm}, configuration file
- @cindex configuration file for channels
- These options are provided for convenience, but you can also specify your
- configuration in the @file{~/.config/guix/channels.scm} file or using the
- @option{--channels} option (see below).
- @item --channels=@var{file}
- @itemx -C @var{file}
- Read the list of channels from @var{file} instead of
- @file{~/.config/guix/channels.scm} or @file{/etc/guix/channels.scm}.
- @var{file} must contain Scheme code that
- evaluates to a list of channel objects. @xref{Channels}, for more
- information.
- @cindex channel news
- @item --news
- @itemx -N
- Display news written by channel authors for their users for changes made
- since the previous generation (@pxref{Channels, Writing Channel News}).
- When @option{--details} is passed, additionally display new and upgraded
- packages.
- You can view that information for previous generations with
- @command{guix pull -l}.
- @item --list-generations[=@var{pattern}]
- @itemx -l [@var{pattern}]
- List all the generations of @file{~/.config/guix/current} or, if @var{pattern}
- is provided, the subset of generations that match @var{pattern}.
- The syntax of @var{pattern} is the same as with @code{guix package
- --list-generations} (@pxref{Invoking guix package}).
- By default, this prints information about the channels used in each
- revision as well as the corresponding news entries. If you pass
- @option{--details}, it will also print the list of packages added and
- upgraded in each generation compared to the previous one.
- @item --details
- Instruct @option{--list-generations} or @option{--news} to display more
- information about the differences between subsequent generations---see
- above.
- @item --roll-back
- @cindex rolling back
- @cindex undoing transactions
- @cindex transactions, undoing
- Roll back to the previous @dfn{generation} of @file{~/.config/guix/current}---i.e.,
- undo the last transaction.
- @item --switch-generation=@var{pattern}
- @itemx -S @var{pattern}
- @cindex generations
- Switch to a particular generation defined by @var{pattern}.
- @var{pattern} may be either a generation number or a number prefixed
- with ``+'' or ``-''. The latter means: move forward/backward by a
- specified number of generations. For example, if you want to return to
- the latest generation after @option{--roll-back}, use
- @option{--switch-generation=+1}.
- @item --delete-generations[=@var{pattern}]
- @itemx -d [@var{pattern}]
- When @var{pattern} is omitted, delete all generations except the current
- one.
- This command accepts the same patterns as @option{--list-generations}.
- When @var{pattern} is specified, delete the matching generations. When
- @var{pattern} specifies a duration, generations @emph{older} than the
- specified duration match. For instance, @option{--delete-generations=1m}
- deletes generations that are more than one month old.
- If the current generation matches, it is @emph{not} deleted.
- Note that deleting generations prevents rolling back to them.
- Consequently, this command must be used with care.
- @xref{Invoking guix describe}, for a way to display information about the
- current generation only.
- @item --profile=@var{profile}
- @itemx -p @var{profile}
- Use @var{profile} instead of @file{~/.config/guix/current}.
- @item --dry-run
- @itemx -n
- Show which channel commit(s) would be used and what would be built or
- substituted but do not actually do it.
- @item --allow-downgrades
- Allow pulling older or unrelated revisions of channels than those
- currently in use.
- @cindex downgrade attacks, protection against
- By default, @command{guix pull} protects against so-called ``downgrade
- attacks'' whereby the Git repository of a channel would be reset to an
- earlier or unrelated revision of itself, potentially leading you to
- install older, known-vulnerable versions of software packages.
- @quotation Note
- Make sure you understand its security implications before using
- @option{--allow-downgrades}.
- @end quotation
- @item --disable-authentication
- Allow pulling channel code without authenticating it.
- @cindex authentication, of channel code
- By default, @command{guix pull} authenticates code downloaded from
- channels by verifying that its commits are signed by authorized
- developers, and raises an error if this is not the case. This option
- instructs it to not perform any such verification.
- @quotation Note
- Make sure you understand its security implications before using
- @option{--disable-authentication}.
- @end quotation
- @item --system=@var{system}
- @itemx -s @var{system}
- Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of
- the system type of the build host.
- @item --bootstrap
- Use the bootstrap Guile to build the latest Guix. This option is only
- useful to Guix developers.
- @end table
- The @dfn{channel} mechanism allows you to instruct @command{guix pull} which
- repository and branch to pull from, as well as @emph{additional} repositories
- containing package modules that should be deployed. @xref{Channels}, for more
- information.
- In addition, @command{guix pull} supports all the common build options
- (@pxref{Common Build Options}).
- @node Invoking guix time-machine
- @section Invoking @command{guix time-machine}
- @cindex @command{guix time-machine}
- @cindex pinning, channels
- @cindex replicating Guix
- @cindex reproducibility, of Guix
- The @command{guix time-machine} command provides access to other
- revisions of Guix, for example to install older versions of packages,
- or to reproduce a computation in an identical environment. The revision
- of Guix to be used is defined by a commit or by a channel
- description file created by @command{guix describe}
- (@pxref{Invoking guix describe}).
- The general syntax is:
- @example
- guix time-machine @var{options}@dots{} -- @var{command} @var {arg}@dots{}
- @end example
- where @var{command} and @var{arg}@dots{} are passed unmodified to the
- @command{guix} command of the specified revision. The @var{options} that define
- this revision are the same as for @command{guix pull} (@pxref{Invoking guix pull}):
- @table @code
- @item --url=@var{url}
- @itemx --commit=@var{commit}
- @itemx --branch=@var{branch}
- Use the @code{guix} channel from the specified @var{url}, at the
- given @var{commit} (a valid Git commit ID represented as a hexadecimal
- string), or @var{branch}.
- @item --channels=@var{file}
- @itemx -C @var{file}
- Read the list of channels from @var{file}. @var{file} must contain
- Scheme code that evaluates to a list of channel objects.
- @xref{Channels} for more information.
- @end table
- As for @command{guix pull}, the absence of any options means that the
- latest commit on the master branch will be used. The command
- @example
- guix time-machine -- build hello
- @end example
- will thus build the package @code{hello} as defined in the master branch,
- which is in general a newer revision of Guix than you have installed.
- Time travel works in both directions!
- Note that @command{guix time-machine} can trigger builds of channels and
- their dependencies, and these are controlled by the standard build
- options (@pxref{Common Build Options}).
- @node Inferiors
- @section Inferiors
- @c TODO: Remove this once we're more confident about API stability.
- @quotation Note
- The functionality described here is a ``technology preview'' as of version
- @value{VERSION}. As such, the interface is subject to change.
- @end quotation
- @cindex inferiors
- @cindex composition of Guix revisions
- Sometimes you might need to mix packages from the revision of Guix you're
- currently running with packages available in a different revision of Guix.
- Guix @dfn{inferiors} allow you to achieve that by composing different Guix
- revisions in arbitrary ways.
- @cindex inferior packages
- Technically, an ``inferior'' is essentially a separate Guix process connected
- to your main Guix process through a REPL (@pxref{Invoking guix repl}). The
- @code{(guix inferior)} module allows you to create inferiors and to
- communicate with them. It also provides a high-level interface to browse and
- manipulate the packages that an inferior provides---@dfn{inferior packages}.
- When combined with channels (@pxref{Channels}), inferiors provide a simple way
- to interact with a separate revision of Guix. For example, let's assume you
- want to install in your profile the current @code{guile} package, along with
- the @code{guile-json} as it existed in an older revision of Guix---perhaps
- because the newer @code{guile-json} has an incompatible API and you want to
- run your code against the old API@. To do that, you could write a manifest for
- use by @code{guix package --manifest} (@pxref{Invoking guix package}); in that
- manifest, you would create an inferior for that old Guix revision you care
- about, and you would look up the @code{guile-json} package in the inferior:
- @lisp
- (use-modules (guix inferior) (guix channels)
- (srfi srfi-1)) ;for 'first'
- (define channels
- ;; This is the old revision from which we want to
- ;; extract guile-json.
- (list (channel
- (name 'guix)
- (url "https://git.savannah.gnu.org/git/guix.git")
- (commit
- "65956ad3526ba09e1f7a40722c96c6ef7c0936fe"))))
- (define inferior
- ;; An inferior representing the above revision.
- (inferior-for-channels channels))
- ;; Now create a manifest with the current "guile" package
- ;; and the old "guile-json" package.
- (packages->manifest
- (list (first (lookup-inferior-packages inferior "guile-json"))
- (specification->package "guile")))
- @end lisp
- On its first run, @command{guix package --manifest} might have to build the
- channel you specified before it can create the inferior; subsequent runs will
- be much faster because the Guix revision will be cached.
- The @code{(guix inferior)} module provides the following procedures to open an
- inferior:
- @deffn {Scheme Procedure} inferior-for-channels @var{channels} @
- [#:cache-directory] [#:ttl]
- Return an inferior for @var{channels}, a list of channels. Use the cache at
- @var{cache-directory}, where entries can be reclaimed after @var{ttl} seconds.
- This procedure opens a new connection to the build daemon.
- As a side effect, this procedure may build or substitute binaries for
- @var{channels}, which can take time.
- @end deffn
- @deffn {Scheme Procedure} open-inferior @var{directory} @
- [#:command "bin/guix"]
- Open the inferior Guix in @var{directory}, running
- @code{@var{directory}/@var{command} repl} or equivalent. Return @code{#f} if
- the inferior could not be launched.
- @end deffn
- @cindex inferior packages
- The procedures listed below allow you to obtain and manipulate inferior
- packages.
- @deffn {Scheme Procedure} inferior-packages @var{inferior}
- Return the list of packages known to @var{inferior}.
- @end deffn
- @deffn {Scheme Procedure} lookup-inferior-packages @var{inferior} @var{name} @
- [@var{version}]
- Return the sorted list of inferior packages matching @var{name} in
- @var{inferior}, with highest version numbers first. If @var{version} is true,
- return only packages with a version number prefixed by @var{version}.
- @end deffn
- @deffn {Scheme Procedure} inferior-package? @var{obj}
- Return true if @var{obj} is an inferior package.
- @end deffn
- @deffn {Scheme Procedure} inferior-package-name @var{package}
- @deffnx {Scheme Procedure} inferior-package-version @var{package}
- @deffnx {Scheme Procedure} inferior-package-synopsis @var{package}
- @deffnx {Scheme Procedure} inferior-package-description @var{package}
- @deffnx {Scheme Procedure} inferior-package-home-page @var{package}
- @deffnx {Scheme Procedure} inferior-package-location @var{package}
- @deffnx {Scheme Procedure} inferior-package-inputs @var{package}
- @deffnx {Scheme Procedure} inferior-package-native-inputs @var{package}
- @deffnx {Scheme Procedure} inferior-package-propagated-inputs @var{package}
- @deffnx {Scheme Procedure} inferior-package-transitive-propagated-inputs @var{package}
- @deffnx {Scheme Procedure} inferior-package-native-search-paths @var{package}
- @deffnx {Scheme Procedure} inferior-package-transitive-native-search-paths @var{package}
- @deffnx {Scheme Procedure} inferior-package-search-paths @var{package}
- These procedures are the counterpart of package record accessors
- (@pxref{package Reference}). Most of them work by querying the inferior
- @var{package} comes from, so the inferior must still be live when you call
- these procedures.
- @end deffn
- Inferior packages can be used transparently like any other package or
- file-like object in G-expressions (@pxref{G-Expressions}). They are also
- transparently handled by the @code{packages->manifest} procedure, which is
- commonly used in manifests (@pxref{Invoking guix package, the
- @option{--manifest} option of @command{guix package}}). Thus you can insert
- an inferior package pretty much anywhere you would insert a regular package:
- in manifests, in the @code{packages} field of your @code{operating-system}
- declaration, and so on.
- @node Invoking guix describe
- @section Invoking @command{guix describe}
- @cindex reproducibility
- @cindex replicating Guix
- Often you may want to answer questions like: ``Which revision of Guix am I
- using?'' or ``Which channels am I using?'' This is useful information in many
- situations: if you want to @emph{replicate} an environment on a different
- machine or user account, if you want to report a bug or to determine what
- change in the channels you are using caused it, or if you want to record your
- system state for reproducibility purposes. The @command{guix describe}
- command answers these questions.
- When run from a @command{guix pull}ed @command{guix}, @command{guix describe}
- displays the channel(s) that it was built from, including their repository URL
- and commit IDs (@pxref{Channels}):
- @example
- $ guix describe
- Generation 10 Sep 03 2018 17:32:44 (current)
- guix e0fa68c
- repository URL: https://git.savannah.gnu.org/git/guix.git
- branch: master
- commit: e0fa68c7718fffd33d81af415279d6ddb518f727
- @end example
- If you're familiar with the Git version control system, this is similar in
- spirit to @command{git describe}; the output is also similar to that of
- @command{guix pull --list-generations}, but limited to the current generation
- (@pxref{Invoking guix pull, the @option{--list-generations} option}). Because
- the Git commit ID shown above unambiguously refers to a snapshot of Guix, this
- information is all it takes to describe the revision of Guix you're using, and
- also to replicate it.
- To make it easier to replicate Guix, @command{guix describe} can also be asked
- to return a list of channels instead of the human-readable description above:
- @example
- $ guix describe -f channels
- (list (channel
- (name 'guix)
- (url "https://git.savannah.gnu.org/git/guix.git")
- (commit
- "e0fa68c7718fffd33d81af415279d6ddb518f727")
- (introduction
- (make-channel-introduction
- "9edb3f66fd807b096b48283debdcddccfea34bad"
- (openpgp-fingerprint
- "BBB0 2DDF 2CEA F6A8 0D1D E643 A2A0 6DF2 A33A 54FA")))))
- @end example
- @noindent
- You can save this to a file and feed it to @command{guix pull -C} on some
- other machine or at a later point in time, which will instantiate @emph{this
- exact Guix revision} (@pxref{Invoking guix pull, the @option{-C} option}).
- From there on, since you're able to deploy the same revision of Guix, you can
- just as well @emph{replicate a complete software environment}. We humbly
- think that this is @emph{awesome}, and we hope you'll like it too!
- The details of the options supported by @command{guix describe} are as
- follows:
- @table @code
- @item --format=@var{format}
- @itemx -f @var{format}
- Produce output in the specified @var{format}, one of:
- @table @code
- @item human
- produce human-readable output;
- @item channels
- produce a list of channel specifications that can be passed to @command{guix
- pull -C} or installed as @file{~/.config/guix/channels.scm} (@pxref{Invoking
- guix pull});
- @item channels-sans-intro
- like @code{channels}, but omit the @code{introduction} field; use it to
- produce a channel specification suitable for Guix version 1.1.0 or
- earlier---the @code{introduction} field has to do with channel
- authentication (@pxref{Channels, Channel Authentication}) and is not
- supported by these older versions;
- @item json
- @cindex JSON
- produce a list of channel specifications in JSON format;
- @item recutils
- produce a list of channel specifications in Recutils format.
- @end table
- @item --list-formats
- Display available formats for @option{--format} option.
- @item --profile=@var{profile}
- @itemx -p @var{profile}
- Display information about @var{profile}.
- @end table
- @node Invoking guix archive
- @section Invoking @command{guix archive}
- @cindex @command{guix archive}
- @cindex archive
- The @command{guix archive} command allows users to @dfn{export} files
- from the store into a single archive, and to later @dfn{import} them on
- a machine that runs Guix.
- In particular, it allows store files to be transferred from one machine
- to the store on another machine.
- @quotation Note
- If you're looking for a way to produce archives in a format suitable for
- tools other than Guix, @pxref{Invoking guix pack}.
- @end quotation
- @cindex exporting store items
- To export store files as an archive to standard output, run:
- @example
- guix archive --export @var{options} @var{specifications}...
- @end example
- @var{specifications} may be either store file names or package
- specifications, as for @command{guix package} (@pxref{Invoking guix
- package}). For instance, the following command creates an archive
- containing the @code{gui} output of the @code{git} package and the main
- output of @code{emacs}:
- @example
- guix archive --export git:gui /gnu/store/...-emacs-24.3 > great.nar
- @end example
- If the specified packages are not built yet, @command{guix archive}
- automatically builds them. The build process may be controlled with the
- common build options (@pxref{Common Build Options}).
- To transfer the @code{emacs} package to a machine connected over SSH,
- one would run:
- @example
- guix archive --export -r emacs | ssh the-machine guix archive --import
- @end example
- @noindent
- Similarly, a complete user profile may be transferred from one machine
- to another like this:
- @example
- guix archive --export -r $(readlink -f ~/.guix-profile) | \
- ssh the-machine guix archive --import
- @end example
- @noindent
- However, note that, in both examples, all of @code{emacs} and the
- profile as well as all of their dependencies are transferred (due to
- @option{-r}), regardless of what is already available in the store on
- the target machine. The @option{--missing} option can help figure out
- which items are missing from the target store. The @command{guix copy}
- command simplifies and optimizes this whole process, so this is probably
- what you should use in this case (@pxref{Invoking guix copy}).
- @cindex nar, archive format
- @cindex normalized archive (nar)
- @cindex nar bundle, archive format
- Each store item is written in the @dfn{normalized archive} or @dfn{nar}
- format (described below), and the output of @command{guix archive
- --export} (and input of @command{guix archive --import}) is a @dfn{nar
- bundle}.
- The nar format is
- comparable in spirit to `tar', but with differences
- that make it more appropriate for our purposes. First, rather than
- recording all Unix metadata for each file, the nar format only mentions
- the file type (regular, directory, or symbolic link); Unix permissions
- and owner/group are dismissed. Second, the order in which directory
- entries are stored always follows the order of file names according to
- the C locale collation order. This makes archive production fully
- deterministic.
- That nar bundle format is essentially the concatenation of zero or more
- nars along with metadata for each store item it contains: its file name,
- references, corresponding derivation, and a digital signature.
- When exporting, the daemon digitally signs the contents of the archive,
- and that digital signature is appended. When importing, the daemon
- verifies the signature and rejects the import in case of an invalid
- signature or if the signing key is not authorized.
- @c FIXME: Add xref to daemon doc about signatures.
- The main options are:
- @table @code
- @item --export
- Export the specified store files or packages (see below). Write the
- resulting archive to the standard output.
- Dependencies are @emph{not} included in the output, unless
- @option{--recursive} is passed.
- @item -r
- @itemx --recursive
- When combined with @option{--export}, this instructs @command{guix archive}
- to include dependencies of the given items in the archive. Thus, the
- resulting archive is self-contained: it contains the closure of the
- exported store items.
- @item --import
- Read an archive from the standard input, and import the files listed
- therein into the store. Abort if the archive has an invalid digital
- signature, or if it is signed by a public key not among the authorized
- keys (see @option{--authorize} below).
- @item --missing
- Read a list of store file names from the standard input, one per line,
- and write on the standard output the subset of these files missing from
- the store.
- @item --generate-key[=@var{parameters}]
- @cindex signing, archives
- Generate a new key pair for the daemon. This is a prerequisite before
- archives can be exported with @option{--export}. This
- operation is usually instantaneous but it can take time if the system's
- entropy pool needs to be refilled. On Guix System,
- @code{guix-service-type} takes care of generating this key pair the
- first boot.
- The generated key pair is typically stored under @file{/etc/guix}, in
- @file{signing-key.pub} (public key) and @file{signing-key.sec} (private
- key, which must be kept secret). When @var{parameters} is omitted,
- an ECDSA key using the Ed25519 curve is generated, or, for Libgcrypt
- versions before 1.6.0, it is a 4096-bit RSA key.
- Alternatively, @var{parameters} can specify
- @code{genkey} parameters suitable for Libgcrypt (@pxref{General
- public-key related Functions, @code{gcry_pk_genkey},, gcrypt, The
- Libgcrypt Reference Manual}).
- @item --authorize
- @cindex authorizing, archives
- Authorize imports signed by the public key passed on standard input.
- The public key must be in ``s-expression advanced format''---i.e., the
- same format as the @file{signing-key.pub} file.
- The list of authorized keys is kept in the human-editable file
- @file{/etc/guix/acl}. The file contains
- @url{https://people.csail.mit.edu/rivest/Sexp.txt, ``advanced-format
- s-expressions''} and is structured as an access-control list in the
- @url{https://theworld.com/~cme/spki.txt, Simple Public-Key Infrastructure
- (SPKI)}.
- @item --extract=@var{directory}
- @itemx -x @var{directory}
- Read a single-item archive as served by substitute servers
- (@pxref{Substitutes}) and extract it to @var{directory}. This is a
- low-level operation needed in only very narrow use cases; see below.
- For example, the following command extracts the substitute for Emacs
- served by @code{@value{SUBSTITUTE-SERVER-1}} to @file{/tmp/emacs}:
- @example
- $ wget -O - \
- https://@value{SUBSTITUTE-SERVER-1}/nar/gzip/@dots{}-emacs-24.5 \
- | gunzip | guix archive -x /tmp/emacs
- @end example
- Single-item archives are different from multiple-item archives produced
- by @command{guix archive --export}; they contain a single store item,
- and they do @emph{not} embed a signature. Thus this operation does
- @emph{no} signature verification and its output should be considered
- unsafe.
- The primary purpose of this operation is to facilitate inspection of
- archive contents coming from possibly untrusted substitute servers
- (@pxref{Invoking guix challenge}).
- @item --list
- @itemx -t
- Read a single-item archive as served by substitute servers
- (@pxref{Substitutes}) and print the list of files it contains, as in
- this example:
- @example
- $ wget -O - \
- https://@value{SUBSTITUTE-SERVER-1}/nar/lzip/@dots{}-emacs-26.3 \
- | lzip -d | guix archive -t
- @end example
- @end table
- @c *********************************************************************
- @node Channels
- @chapter Channels
- @cindex channels
- @cindex @file{channels.scm}, configuration file
- @cindex configuration file for channels
- @cindex @command{guix pull}, configuration file
- @cindex configuration of @command{guix pull}
- Guix and its package collection are updated by running @command{guix pull}
- (@pxref{Invoking guix pull}). By default @command{guix pull} downloads and
- deploys Guix itself from the official GNU@tie{}Guix repository. This can be
- customized by defining @dfn{channels} in the
- @file{~/.config/guix/channels.scm} file. A channel specifies a URL and branch
- of a Git repository to be deployed, and @command{guix pull} can be instructed
- to pull from one or more channels. In other words, channels can be used
- to @emph{customize} and to @emph{extend} Guix, as we will see below.
- Guix is able to take into account security concerns and deal with authenticated
- updates.
- @menu
- * Specifying Additional Channels:: Extending the package collection.
- * Using a Custom Guix Channel:: Using a customized Guix.
- * Replicating Guix:: Running the @emph{exact same} Guix.
- * Channel Authentication:: How Guix verifies what it fetches.
- * Channels with Substitutes:: Using channels with available substitutes.
- * Creating a Channel:: How to write your custom channel.
- * Package Modules in a Sub-directory:: Specifying the channel's package modules location.
- * Declaring Channel Dependencies:: How to depend on other channels.
- * Specifying Channel Authorizations:: Defining channel authors authorizations.
- * Primary URL:: Distinguishing mirror to original.
- * Writing Channel News:: Communicating information to channel's users.
- @end menu
- @node Specifying Additional Channels
- @section Specifying Additional Channels
- @cindex extending the package collection (channels)
- @cindex variant packages (channels)
- You can specify @emph{additional channels} to pull from. To use a channel, write
- @code{~/.config/guix/channels.scm} to instruct @command{guix pull} to pull from it
- @emph{in addition} to the default Guix channel(s):
- @vindex %default-channels
- @lisp
- ;; Add variant packages to those Guix provides.
- (cons (channel
- (name 'variant-packages)
- (url "https://example.org/variant-packages.git"))
- %default-channels)
- @end lisp
- @noindent
- Note that the snippet above is (as always!)@: Scheme code; we use @code{cons} to
- add a channel the list of channels that the variable @code{%default-channels}
- is bound to (@pxref{Pairs, @code{cons} and lists,, guile, GNU Guile Reference
- Manual}). With this file in place, @command{guix pull} builds not only Guix
- but also the package modules from your own repository. The result in
- @file{~/.config/guix/current} is the union of Guix with your own package
- modules:
- @example
- $ guix pull --list-generations
- @dots{}
- Generation 19 Aug 27 2018 16:20:48
- guix d894ab8
- repository URL: https://git.savannah.gnu.org/git/guix.git
- branch: master
- commit: d894ab8e9bfabcefa6c49d9ba2e834dd5a73a300
- variant-packages dd3df5e
- repository URL: https://example.org/variant-packages.git
- branch: master
- commit: dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb
- 11 new packages: variant-gimp, variant-emacs-with-cool-features, @dots{}
- 4 packages upgraded: emacs-racket-mode@@0.0.2-2.1b78827, @dots{}
- @end example
- @noindent
- The output of @command{guix pull} above shows that Generation@tie{}19 includes
- both Guix and packages from the @code{variant-personal-packages} channel. Among
- the new and upgraded packages that are listed, some like @code{variant-gimp} and
- @code{variant-emacs-with-cool-features} might come from
- @code{variant-packages}, while others come from the Guix default channel.
- @node Using a Custom Guix Channel
- @section Using a Custom Guix Channel
- The channel called @code{guix} specifies where Guix itself---its command-line
- tools as well as its package collection---should be downloaded. For instance,
- suppose you want to update from another copy of the Guix repository at
- @code{example.org}, and specifically the @code{super-hacks} branch, you can
- write in @code{~/.config/guix/channels.scm} this specification:
- @lisp
- ;; Tell 'guix pull' to use another repo.
- (list (channel
- (name 'guix)
- (url "https://example.org/another-guix.git")
- (branch "super-hacks")))
- @end lisp
- @noindent
- From there on, @command{guix pull} will fetch code from the @code{super-hacks}
- branch of the repository at @code{example.org}. The authentication concern is
- addressed below ((@pxref{Channel Authentication}).
- @node Replicating Guix
- @section Replicating Guix
- @cindex pinning, channels
- @cindex replicating Guix
- @cindex reproducibility, of Guix
- The @command{guix pull --list-generations} output above shows precisely which
- commits were used to build this instance of Guix. We can thus replicate it,
- say, on another machine, by providing a channel specification in
- @file{~/.config/guix/channels.scm} that is ``pinned'' to these commits:
- @lisp
- ;; Deploy specific commits of my channels of interest.
- (list (channel
- (name 'guix)
- (url "https://git.savannah.gnu.org/git/guix.git")
- (commit "6298c3ffd9654d3231a6f25390b056483e8f407c"))
- (channel
- (name 'variant-packages)
- (url "https://example.org/variant-packages.git")
- (commit "dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb")))
- @end lisp
- The @command{guix describe --format=channels} command can even generate this
- list of channels directly (@pxref{Invoking guix describe}). The resulting
- file can be used with the -C options of @command{guix pull}
- (@pxref{Invoking guix pull}) or @command{guix time-machine}
- (@pxref{Invoking guix time-machine}).
- At this point the two machines run the @emph{exact same Guix}, with access to
- the @emph{exact same packages}. The output of @command{guix build gimp} on
- one machine will be exactly the same, bit for bit, as the output of the same
- command on the other machine. It also means both machines have access to all
- the source code of Guix and, transitively, to all the source code of every
- package it defines.
- This gives you super powers, allowing you to track the provenance of binary
- artifacts with very fine grain, and to reproduce software environments at
- will---some sort of ``meta reproducibility'' capabilities, if you will.
- @xref{Inferiors}, for another way to take advantage of these super powers.
- @node Channel Authentication
- @section Channel Authentication
- @anchor{channel-authentication}
- @cindex authentication, of channel code
- The @command{guix pull} and @command{guix time-machine} commands
- @dfn{authenticate} the code retrieved from channels: they make sure each
- commit that is fetched is signed by an authorized developer. The goal
- is to protect from unauthorized modifications to the channel that would
- lead users to run malicious code.
- As a user, you must provide a @dfn{channel introduction} in your
- channels file so that Guix knows how to authenticate its first commit.
- A channel specification, including its introduction, looks something
- along these lines:
- @lisp
- (channel
- (name 'some-channel)
- (url "https://example.org/some-channel.git")
- (introduction
- (make-channel-introduction
- "6f0d8cc0d88abb59c324b2990bfee2876016bb86"
- (openpgp-fingerprint
- "CABB A931 C0FF EEC6 900D 0CFB 090B 1199 3D9A EBB5"))))
- @end lisp
- The specification above shows the name and URL of the channel. The call
- to @code{make-channel-introduction} above specifies that authentication
- of this channel starts at commit @code{6f0d8cc@dots{}}, which is signed
- by the OpenPGP key with fingerprint @code{CABB A931@dots{}}.
- For the main channel, called @code{guix}, you automatically get that
- information from your Guix installation. For other channels, include
- the channel introduction provided by the channel authors in your
- @file{channels.scm} file. Make sure you retrieve the channel
- introduction from a trusted source since that is the root of your trust.
- If you're curious about the authentication mechanics, read on!
- @node Channels with Substitutes
- @section Channels with Substitutes
- When running @command{guix pull}, Guix will first compile the
- definitions of every available package. This is an expensive operation
- for which substitutes (@pxref{Substitutes}) may be available. The
- following snippet in @file{channels.scm} will ensure that @command{guix
- pull} uses the latest commit with available substitutes for the package
- definitions: this is done by querying the continuous integration
- server at @url{https://ci.guix.gnu.org}.
- @lisp
- (use-modules (guix ci))
- (list (channel-with-substitutes-available
- %default-guix-channel
- "https://ci.guix.gnu.org"))
- @end lisp
- Note that this does not mean that all the packages that you will
- install after running @command{guix pull} will have available
- substitutes. It only ensures that @command{guix pull} will not try to
- compile package definitions. This is particularly useful when using
- machines with limited resources.
- @node Creating a Channel
- @section Creating a Channel
- @cindex personal packages (channels)
- @cindex channels, for personal packages
- Let's say you have a bunch of custom package variants or personal packages
- that you think would make little sense to contribute to the Guix project, but
- would like to have these packages transparently available to you at the
- command line. You would first write modules containing those package
- definitions (@pxref{Package Modules}), maintain them in a Git repository, and
- then you and anyone else can use it as an additional channel to get packages
- from. Neat, no?
- @c What follows stems from discussions at
- @c <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=22629#134> as well as
- @c earlier discussions on guix-devel@gnu.org.
- @quotation Warning
- Before you, dear user, shout---``woow this is @emph{soooo coool}!''---and
- publish your personal channel to the world, we would like to share a few words
- of caution:
- @itemize
- @item
- Before publishing a channel, please consider contributing your package
- definitions to Guix proper (@pxref{Contributing}). Guix as a project is open
- to free software of all sorts, and packages in Guix proper are readily
- available to all Guix users and benefit from the project's quality assurance
- process.
- @item
- When you maintain package definitions outside Guix, we, Guix developers,
- consider that @emph{the compatibility burden is on you}. Remember that
- package modules and package definitions are just Scheme code that uses various
- programming interfaces (APIs). We want to remain free to change these APIs to
- keep improving Guix, possibly in ways that break your channel. We never
- change APIs gratuitously, but we will @emph{not} commit to freezing APIs
- either.
- @item
- Corollary: if you're using an external channel and that channel breaks, please
- @emph{report the issue to the channel authors}, not to the Guix project.
- @end itemize
- You've been warned! Having said this, we believe external channels are a
- practical way to exert your freedom to augment Guix' package collection and to
- share your improvements, which are basic tenets of
- @uref{https://www.gnu.org/philosophy/free-sw.html, free software}. Please
- email us at @email{guix-devel@@gnu.org} if you'd like to discuss this.
- @end quotation
- To create a channel, create a Git repository containing your own package
- modules and make it available. The repository can contain anything, but a
- useful channel will contain Guile modules that export packages. Once you
- start using a channel, Guix will behave as if the root directory of that
- channel's Git repository has been added to the Guile load path (@pxref{Load
- Paths,,, guile, GNU Guile Reference Manual}). For example, if your channel
- contains a file at @file{my-packages/my-tools.scm} that defines a Guile
- module, then the module will be available under the name @code{(my-packages
- my-tools)}, and you will be able to use it like any other module
- (@pxref{Modules,,, guile, GNU Guile Reference Manual}).
- As a channel author, consider bundling authentication material with your
- channel so that users can authenticate it. @xref{Channel
- Authentication}, and @ref{Specifying Channel Authorizations}, for info
- on how to do it.
- @node Package Modules in a Sub-directory
- @section Package Modules in a Sub-directory
- @cindex subdirectory, channels
- As a channel author, you may want to keep your channel modules in a
- sub-directory. If your modules are in the sub-directory @file{guix}, you must
- add a meta-data file @file{.guix-channel} that contains:
- @lisp
- (channel
- (version 0)
- (directory "guix"))
- @end lisp
- @node Declaring Channel Dependencies
- @section Declaring Channel Dependencies
- @cindex dependencies, channels
- @cindex meta-data, channels
- Channel authors may decide to augment a package collection provided by other
- channels. They can declare their channel to be dependent on other channels in
- a meta-data file @file{.guix-channel}, which is to be placed in the root of
- the channel repository.
- The meta-data file should contain a simple S-expression like this:
- @lisp
- (channel
- (version 0)
- (dependencies
- (channel
- (name some-collection)
- (url "https://example.org/first-collection.git")
- ;; The 'introduction' bit below is optional: you would
- ;; provide it for dependencies that can be authenticated.
- (introduction
- (channel-introduction
- (version 0)
- (commit "a8883b58dc82e167c96506cf05095f37c2c2c6cd")
- (signer "CABB A931 C0FF EEC6 900D 0CFB 090B 1199 3D9A EBB5"))))
- (channel
- (name some-other-collection)
- (url "https://example.org/second-collection.git")
- (branch "testing"))))
- @end lisp
- In the above example this channel is declared to depend on two other channels,
- which will both be fetched automatically. The modules provided by the channel
- will be compiled in an environment where the modules of all these declared
- channels are available.
- For the sake of reliability and maintainability, you should avoid dependencies
- on channels that you don't control, and you should aim to keep the number of
- dependencies to a minimum.
- @node Specifying Channel Authorizations
- @section Specifying Channel Authorizations
- @cindex channel authorizations
- @anchor{channel-authorizations}
- As we saw above, Guix ensures the source code it pulls from channels
- comes from authorized developers. As a channel author, you need to
- specify the list of authorized developers in the
- @file{.guix-authorizations} file in the channel's Git repository. The
- authentication rule is simple: each commit must be signed by a key
- listed in the @file{.guix-authorizations} file of its parent
- commit(s)@footnote{Git commits form a @dfn{directed acyclic graph}
- (DAG). Each commit can have zero or more parents; ``regular'' commits
- have one parent and merge commits have two parent commits. Read
- @uref{https://eagain.net/articles/git-for-computer-scientists/, @i{Git
- for Computer Scientists}} for a great overview.} The
- @file{.guix-authorizations} file looks like this:
- @lisp
- ;; Example '.guix-authorizations' file.
- (authorizations
- (version 0) ;current file format version
- (("AD17 A21E F8AE D8F1 CC02 DBD9 F8AE D8F1 765C 61E3"
- (name "alice"))
- ("2A39 3FFF 68F4 EF7A 3D29 12AF 68F4 EF7A 22FB B2D5"
- (name "bob"))
- ("CABB A931 C0FF EEC6 900D 0CFB 090B 1199 3D9A EBB5"
- (name "charlie"))))
- @end lisp
- Each fingerprint is followed by optional key/value pairs, as in the
- example above. Currently these key/value pairs are ignored.
- This authentication rule creates a chicken-and-egg issue: how do we
- authenticate the first commit? Related to that: how do we deal with
- channels whose repository history contains unsigned commits and lack
- @file{.guix-authorizations}? And how do we fork existing channels?
- @cindex channel introduction
- Channel introductions answer these questions by describing the first
- commit of a channel that should be authenticated. The first time a
- channel is fetched with @command{guix pull} or @command{guix
- time-machine}, the command looks up the introductory commit and verifies
- that it is signed by the specified OpenPGP key. From then on, it
- authenticates commits according to the rule above. Authentication fails
- if the target commit is neither a descendant nor an ancestor of the
- introductory commit.
- Additionally, your channel must provide all the OpenPGP keys that were
- ever mentioned in @file{.guix-authorizations}, stored as @file{.key}
- files, which can be either binary or ``ASCII-armored''. By default,
- those @file{.key} files are searched for in the branch named
- @code{keyring} but you can specify a different branch name in
- @code{.guix-channel} like so:
- @lisp
- (channel
- (version 0)
- (keyring-reference "my-keyring-branch"))
- @end lisp
- To summarize, as the author of a channel, there are three things you have
- to do to allow users to authenticate your code:
- @enumerate
- @item
- Export the OpenPGP keys of past and present committers with @command{gpg
- --export} and store them in @file{.key} files, by default in a branch
- named @code{keyring} (we recommend making it an @dfn{orphan branch}).
- @item
- Introduce an initial @file{.guix-authorizations} in the channel's
- repository. Do that in a signed commit (@pxref{Commit Access}, for
- information on how to sign Git commits.)
- @item
- Advertise the channel introduction, for instance on your channel's web
- page. The channel introduction, as we saw above, is the commit/key
- pair---i.e., the commit that introduced @file{.guix-authorizations}, and
- the fingerprint of the OpenPGP used to sign it.
- @end enumerate
- Before pushing to your public Git repository, you can run @command{guix
- git-authenticate} to verify that you did sign all the commits you are
- about to push with an authorized key:
- @example
- guix git authenticate @var{commit} @var{signer}
- @end example
- @noindent
- where @var{commit} and @var{signer} are your channel introduction.
- @xref{Invoking guix git authenticate}, for details.
- Publishing a signed channel requires discipline: any mistake, such as an
- unsigned commit or a commit signed by an unauthorized key, will prevent
- users from pulling from your channel---well, that's the whole point of
- authentication! Pay attention to merges in particular: merge commits
- are considered authentic if and only if they are signed by a key present
- in the @file{.guix-authorizations} file of @emph{both} branches.
- @node Primary URL
- @section Primary URL
- @cindex primary URL, channels
- Channel authors can indicate the primary URL of their channel's Git
- repository in the @file{.guix-channel} file, like so:
- @lisp
- (channel
- (version 0)
- (url "https://example.org/guix.git"))
- @end lisp
- This allows @command{guix pull} to determine whether it is pulling code
- from a mirror of the channel; when that is the case, it warns the user
- that the mirror might be stale and displays the primary URL@. That way,
- users cannot be tricked into fetching code from a stale mirror that does
- not receive security updates.
- This feature only makes sense for authenticated repositories, such as
- the official @code{guix} channel, for which @command{guix pull} ensures
- the code it fetches is authentic.
- @node Writing Channel News
- @section Writing Channel News
- @cindex news, for channels
- Channel authors may occasionally want to communicate to their users
- information about important changes in the channel. You'd send them all
- an email, but that's not convenient.
- Instead, channels can provide a @dfn{news file}; when the channel users
- run @command{guix pull}, that news file is automatically read and
- @command{guix pull --news} can display the announcements that correspond
- to the new commits that have been pulled, if any.
- To do that, channel authors must first declare the name of the news file
- in their @file{.guix-channel} file:
- @lisp
- (channel
- (version 0)
- (news-file "etc/news.txt"))
- @end lisp
- The news file itself, @file{etc/news.txt} in this example, must look
- something like this:
- @lisp
- (channel-news
- (version 0)
- (entry (tag "the-bug-fix")
- (title (en "Fixed terrible bug")
- (fr "Oh la la"))
- (body (en "@@emph@{Good news@}! It's fixed!")
- (eo "Certe ĝi pli bone funkcias nun!")))
- (entry (commit "bdcabe815cd28144a2d2b4bc3c5057b051fa9906")
- (title (en "Added a great package")
- (ca "Què vol dir guix?"))
- (body (en "Don't miss the @@code@{hello@} package!"))))
- @end lisp
- While the news file is using the Scheme syntax, avoid naming it with a
- @file{.scm} extension or else it will get picked up when building the
- channel and yield an error since it is not a valid module.
- Alternatively, you can move the channel module to a subdirectory and
- store the news file in another directory.
- The file consists of a list of @dfn{news entries}. Each entry is
- associated with a commit or tag: it describes changes made in this
- commit, possibly in preceding commits as well. Users see entries only
- the first time they obtain the commit the entry refers to.
- The @code{title} field should be a one-line summary while @code{body}
- can be arbitrarily long, and both can contain Texinfo markup
- (@pxref{Overview,,, texinfo, GNU Texinfo}). Both the title and body are
- a list of language tag/message tuples, which allows @command{guix pull}
- to display news in the language that corresponds to the user's locale.
- If you want to translate news using a gettext-based workflow, you can
- extract translatable strings with @command{xgettext} (@pxref{xgettext
- Invocation,,, gettext, GNU Gettext Utilities}). For example, assuming
- you write news entries in English first, the command below creates a PO
- file containing the strings to translate:
- @example
- xgettext -o news.po -l scheme -ken etc/news.txt
- @end example
- To sum up, yes, you could use your channel as a blog. But beware, this
- is @emph{not quite} what your users might expect.
- @c *********************************************************************
- @node Development
- @chapter Development
- @cindex software development
- If you are a software developer, Guix provides tools that you should find
- helpful---independently of the language you're developing in. This is what
- this chapter is about.
- The @command{guix shell} command provides a convenient way to set up
- one-off software environments, be it for development purposes or to run
- a command without installing it in your profile. The @command{guix
- pack} command allows you to create @dfn{application bundles} that can be
- easily distributed to users who do not run Guix.
- @menu
- * Invoking guix shell:: Spawning one-off software environments.
- * Invoking guix environment:: Setting up development environments.
- * Invoking guix pack:: Creating software bundles.
- * The GCC toolchain:: Working with languages supported by GCC.
- * Invoking guix git authenticate:: Authenticating Git repositories.
- @end menu
- @node Invoking guix shell
- @section Invoking @command{guix shell}
- @cindex reproducible build environments
- @cindex development environments
- @cindex @command{guix environment}
- @cindex environment, package build environment
- The purpose of @command{guix shell} is to make it easy to create one-off
- software environments, without changing one's profile. It is typically
- used to create development environments; it is also a convenient way to
- run applications without ``polluting'' your profile.
- @quotation Note
- The @command{guix shell} command was recently introduced to supersede
- @command{guix environment} (@pxref{Invoking guix environment}). If you
- are familiar with @command{guix environment}, you will notice that it is
- similar but also---we hope!---more convenient.
- @end quotation
- The general syntax is:
- @example
- guix shell [@var{options}] [@var{package}@dots{}]
- @end example
- The following example creates an environment containing Python and NumPy,
- building or downloading any missing package, and runs the
- @command{python3} command in that environment:
- @example
- guix shell python python-numpy -- python3
- @end example
- Development environments can be created as in the example below, which
- spawns an interactive shell containing all the dependencies and
- environment variables needed to work on Inkscape:
- @example
- guix shell --development inkscape
- @end example
- Exiting the shell places the user back in the original environment
- before @command{guix shell} was invoked. The next garbage collection
- (@pxref{Invoking guix gc}) may clean up packages that were installed in
- the environment and that are no longer used outside of it.
- As an added convenience, when running from a directory that contains a
- @file{manifest.scm} or a @file{guix.scm} file (in this order), possibly
- in a parent directory, @command{guix shell} automatically loads the
- file---provided the directory is listed in
- @file{~/.config/guix/shell-authorized-directories}, and only for
- interactive use:
- @example
- guix shell
- @end example
- This provides an easy way to define, share, and enter development
- environments.
- By default, the shell session or command runs in an @emph{augmented}
- environment, where the new packages are added to search path environment
- variables such as @code{PATH}. You can, instead, choose to create an
- @emph{isolated} environment containing nothing but the packages you
- asked for. Passing the @option{--pure} option clears environment
- variable definitions found in the parent environment@footnote{Be sure to
- use the @option{--check} option the first time you use @command{guix
- shell} interactively to make sure the shell does not undo the effect of
- @option{--pure}.}; passing @option{--container} goes one step further by
- spawning a @dfn{container} isolated from the rest of the system:
- @example
- guix shell --container emacs gcc-toolchain
- @end example
- The command above spawns an interactive shell in a container where
- nothing but @code{emacs}, @code{gcc-toolchain}, and their dependencies
- is available. The container lacks network access and shares no files
- other than the current working directory with the surrounding
- environment. This is useful to prevent access to system-wide resources
- such as @file{/usr/bin} on foreign distros.
- This @option{--container} option can also prove useful if you wish to
- run a security-sensitive application, such as a web browser, in an
- isolated environment. For example, the command below launches
- Ungoogled-Chromium in an isolated environment, this time sharing network
- access with the host and preserving its @code{DISPLAY} environment
- variable, but without even sharing the current directory:
- @example
- guix shell --container --network --no-cwd ungoogled-chromium \
- --preserve='^DISPLAY$' -- chromium
- @end example
- @vindex GUIX_ENVIRONMENT
- @command{guix shell} defines the @env{GUIX_ENVIRONMENT}
- variable in the shell it spawns; its value is the file name of the
- profile of this environment. This allows users to, say, define a
- specific prompt for development environments in their @file{.bashrc}
- (@pxref{Bash Startup Files,,, bash, The GNU Bash Reference Manual}):
- @example
- if [ -n "$GUIX_ENVIRONMENT" ]
- then
- export PS1="\u@@\h \w [dev]\$ "
- fi
- @end example
- @noindent
- ...@: or to browse the profile:
- @example
- $ ls "$GUIX_ENVIRONMENT/bin"
- @end example
- The available options are summarized below.
- @table @code
- @item --check
- Set up the environment and check whether the shell would clobber
- environment variables. It's a good idea to use this option the first
- time you run @command{guix shell} for an interactive session to make
- sure your setup is correct.
- For example, if the shell modifies the @env{PATH} environment variable,
- report it since you would get a different environment than what you
- asked for.
- Such problems usually indicate that the shell startup files are
- unexpectedly modifying those environment variables. For example, if you
- are using Bash, make sure that environment variables are set or modified
- in @file{~/.bash_profile} and @emph{not} in @file{~/.bashrc}---the
- former is sourced only by log-in shells. @xref{Bash Startup Files,,,
- bash, The GNU Bash Reference Manual}, for details on Bash start-up
- files.
- @item --development
- @itemx -D
- Cause @command{guix shell} to include in the environment the
- dependencies of the following package rather than the package itself.
- This can be combined with other packages. For instance, the command
- below starts an interactive shell containing the build-time dependencies
- of GNU@tie{}Guile, plus Autoconf, Automake, and Libtool:
- @example
- guix shell -D guile autoconf automake libtool
- @end example
- @item --expression=@var{expr}
- @itemx -e @var{expr}
- Create an environment for the package or list of packages that
- @var{expr} evaluates to.
- For example, running:
- @example
- guix shell -D -e '(@@ (gnu packages maths) petsc-openmpi)'
- @end example
- starts a shell with the environment for this specific variant of the
- PETSc package.
- Running:
- @example
- guix shell -e '(@@ (gnu) %base-packages)'
- @end example
- starts a shell with all the base system packages available.
- The above commands only use the default output of the given packages.
- To select other outputs, two element tuples can be specified:
- @example
- guix shell -e '(list (@@ (gnu packages bash) bash) "include")'
- @end example
- @item --file=@var{file}
- @itemx -f @var{file}
- Create an environment containing the package or list of packages that
- the code within @var{file} evaluates to.
- As an example, @var{file} might contain a definition like this
- (@pxref{Defining Packages}):
- @lisp
- @verbatiminclude environment-gdb.scm
- @end lisp
- With the file above, you can enter a development environment for GDB by
- running:
- @example
- guix shell -D -f gdb-devel.scm
- @end example
- @item --manifest=@var{file}
- @itemx -m @var{file}
- Create an environment for the packages contained in the manifest object
- returned by the Scheme code in @var{file}. This option can be repeated
- several times, in which case the manifests are concatenated.
- This is similar to the same-named option in @command{guix package}
- (@pxref{profile-manifest, @option{--manifest}}) and uses the same
- manifest files.
- See @option{--export-manifest} below on how to obtain a first manifest.
- @cindex manifest, exporting
- @anchor{shell-export-manifest}
- @item --export-manifest
- Write to standard output a manifest suitable for @option{--manifest}
- corresponding to given command-line options.
- This is a way to ``convert'' command-line arguments into a manifest.
- For example, imagine you are tired of typing long lines and would like
- to get a manifest equivalent to this command line:
- @example
- guix shell -D guile git emacs emacs-geiser emacs-geiser-guile
- @end example
- Just add @option{--export-manifest} to the command line above:
- @example
- guix shell --export-manifest \
- -D guile git emacs emacs-geiser emacs-geiser-guile
- @end example
- @noindent
- ... and you get a manifest along these lines:
- @lisp
- (concatenate-manifests
- (list (specifications->manifest
- (list "git"
- "emacs"
- "emacs-geiser"
- "emacs-geiser-guile"))
- (package->development-manifest
- (specification->package "guile"))))
- @end lisp
- You can store it into a file, say @file{manifest.scm}, and from there
- pass it to @command{guix shell} or indeed pretty much any @command{guix}
- command:
- @example
- guix shell -m manifest.scm
- @end example
- Voilà, you've converted a long command line into a manifest! That
- conversion process honors package transformation options (@pxref{Package
- Transformation Options}) so it should be lossless.
- @item --profile=@var{profile}
- @itemx -p @var{profile}
- Create an environment containing the packages installed in @var{profile}.
- Use @command{guix package} (@pxref{Invoking guix package}) to create
- and manage profiles.
- @item --pure
- Unset existing environment variables when building the new environment, except
- those specified with @option{--preserve} (see below). This has the effect of
- creating an environment in which search paths only contain package inputs.
- @item --preserve=@var{regexp}
- @itemx -E @var{regexp}
- When used alongside @option{--pure}, preserve the environment variables
- matching @var{regexp}---in other words, put them on a ``white list'' of
- environment variables that must be preserved. This option can be repeated
- several times.
- @example
- guix shell --pure --preserve=^SLURM openmpi @dots{} \
- -- mpirun @dots{}
- @end example
- This example runs @command{mpirun} in a context where the only environment
- variables defined are @env{PATH}, environment variables whose name starts
- with @samp{SLURM}, as well as the usual ``precious'' variables (@env{HOME},
- @env{USER}, etc.).
- @item --search-paths
- Display the environment variable definitions that make up the
- environment.
- @item --system=@var{system}
- @itemx -s @var{system}
- Attempt to build for @var{system}---e.g., @code{i686-linux}.
- @item --container
- @itemx -C
- @cindex container
- Run @var{command} within an isolated container. The current working
- directory outside the container is mapped inside the container.
- Additionally, unless overridden with @option{--user}, a dummy home
- directory is created that matches the current user's home directory, and
- @file{/etc/passwd} is configured accordingly.
- The spawned process runs as the current user outside the container. Inside
- the container, it has the same UID and GID as the current user, unless
- @option{--user} is passed (see below).
- @item --network
- @itemx -N
- For containers, share the network namespace with the host system.
- Containers created without this flag only have access to the loopback
- device.
- @item --link-profile
- @itemx -P
- For containers, link the environment profile to @file{~/.guix-profile}
- within the container and set @code{GUIX_ENVIRONMENT} to that.
- This is equivalent to making @file{~/.guix-profile} a symlink to the
- actual profile within the container.
- Linking will fail and abort the environment if the directory already
- exists, which will certainly be the case if @command{guix shell}
- was invoked in the user's home directory.
- Certain packages are configured to look in @file{~/.guix-profile} for
- configuration files and data;@footnote{For example, the
- @code{fontconfig} package inspects @file{~/.guix-profile/share/fonts}
- for additional fonts.} @option{--link-profile} allows these programs to
- behave as expected within the environment.
- @item --user=@var{user}
- @itemx -u @var{user}
- For containers, use the username @var{user} in place of the current
- user. The generated @file{/etc/passwd} entry within the container will
- contain the name @var{user}, the home directory will be
- @file{/home/@var{user}}, and no user GECOS data will be copied. Furthermore,
- the UID and GID inside the container are 1000. @var{user}
- need not exist on the system.
- Additionally, any shared or exposed path (see @option{--share} and
- @option{--expose} respectively) whose target is within the current user's
- home directory will be remapped relative to @file{/home/USER}; this
- includes the automatic mapping of the current working directory.
- @example
- # will expose paths as /home/foo/wd, /home/foo/test, and /home/foo/target
- cd $HOME/wd
- guix shell --container --user=foo \
- --expose=$HOME/test \
- --expose=/tmp/target=$HOME/target
- @end example
- While this will limit the leaking of user identity through home paths
- and each of the user fields, this is only one useful component of a
- broader privacy/anonymity solution---not one in and of itself.
- @item --no-cwd
- For containers, the default behavior is to share the current working
- directory with the isolated container and immediately change to that
- directory within the container. If this is undesirable,
- @option{--no-cwd} will cause the current working directory to @emph{not}
- be automatically shared and will change to the user's home directory
- within the container instead. See also @option{--user}.
- @item --expose=@var{source}[=@var{target}]
- @itemx --share=@var{source}[=@var{target}]
- For containers, @option{--expose} (resp. @option{--share}) exposes the
- file system @var{source} from the host system as the read-only
- (resp. writable) file system @var{target} within the container. If
- @var{target} is not specified, @var{source} is used as the target mount
- point in the container.
- The example below spawns a Guile REPL in a container in which the user's
- home directory is accessible read-only via the @file{/exchange}
- directory:
- @example
- guix shell --container --expose=$HOME=/exchange guile -- guile
- @end example
- @item --rebuild-cache
- @cindex caching, of profiles
- @cindex caching, in @command{guix shell}
- In most cases, @command{guix shell} caches the environment so that
- subsequent uses are instantaneous. Least-recently used cache entries
- are periodically removed. The cache is also invalidated, when using
- @option{--file} or @option{--manifest}, anytime the corresponding file
- is modified.
- The @option{--rebuild-cache} forces the cached environment to be
- refreshed. This is useful when using @option{--file} or
- @option{--manifest} and the @command{guix.scm} or @command{manifest.scm}
- file has external dependencies, or if its behavior depends, say, on
- environment variables.
- @item --root=@var{file}
- @itemx -r @var{file}
- @cindex persistent environment
- @cindex garbage collector root, for environments
- Make @var{file} a symlink to the profile for this environment, and
- register it as a garbage collector root.
- This is useful if you want to protect your environment from garbage
- collection, to make it ``persistent''.
- When this option is omitted, @command{guix shell} caches profiles so
- that subsequent uses of the same environment are instantaneous---this is
- comparable to using @option{--root} except that @command{guix shell}
- takes care of periodically removing the least-recently used garbage
- collector roots.
- In some cases, @command{guix shell} does not cache profiles---e.g., if
- transformation options such as @option{--with-latest} are used. In
- those cases, the environment is protected from garbage collection only
- for the duration of the @command{guix shell} session. This means that
- next time you recreate the same environment, you could have to rebuild
- or re-download packages.
- @xref{Invoking guix gc}, for more on GC roots.
- @end table
- @command{guix shell} also supports all of the common build options that
- @command{guix build} supports (@pxref{Common Build Options}) as well as
- package transformation options (@pxref{Package Transformation Options}).
- @node Invoking guix environment
- @section Invoking @command{guix environment}
- The purpose of @command{guix environment} is to assist in creating
- development environments.
- @quotation Deprecation warning
- The @command{guix environment} command is deprecated in favor of
- @command{guix shell}, which performs similar functions but is more
- convenient to use. @xref{Invoking guix shell}.
- Being deprecated, @command{guix environment} is slated for eventual
- removal, but the Guix project is committed to keeping it until May 1st,
- 2023. Please get in touch with us at @email{guix-devel@@gnu.org} if you
- would like to discuss it.
- @end quotation
- The general syntax is:
- @example
- guix environment @var{options} @var{package}@dots{}
- @end example
- The following example spawns a new shell set up for the development of
- GNU@tie{}Guile:
- @example
- guix environment guile
- @end example
- If the needed dependencies are not built yet, @command{guix environment}
- automatically builds them. The environment of the new shell is an
- augmented version of the environment that @command{guix environment} was
- run in. It contains the necessary search paths for building the given
- package added to the existing environment variables. To create
- a ``pure'' environment, in which the original environment variables have
- been unset, use the @option{--pure} option@footnote{Users sometimes
- wrongfully augment environment variables such as @env{PATH} in their
- @file{~/.bashrc} file. As a consequence, when @command{guix
- environment} launches it, Bash may read @file{~/.bashrc}, thereby
- introducing ``impurities'' in these environment variables. It is an
- error to define such environment variables in @file{.bashrc}; instead,
- they should be defined in @file{.bash_profile}, which is sourced only by
- log-in shells. @xref{Bash Startup Files,,, bash, The GNU Bash Reference
- Manual}, for details on Bash start-up files.}.
- Exiting from a Guix environment is the same as exiting from the shell,
- and will place the user back in the old environment before @command{guix
- environment} was invoked. The next garbage collection (@pxref{Invoking
- guix gc}) will clean up packages that were installed from within the
- environment and are no longer used outside of it.
- @vindex GUIX_ENVIRONMENT
- @command{guix environment} defines the @env{GUIX_ENVIRONMENT}
- variable in the shell it spawns; its value is the file name of the
- profile of this environment. This allows users to, say, define a
- specific prompt for development environments in their @file{.bashrc}
- (@pxref{Bash Startup Files,,, bash, The GNU Bash Reference Manual}):
- @example
- if [ -n "$GUIX_ENVIRONMENT" ]
- then
- export PS1="\u@@\h \w [dev]\$ "
- fi
- @end example
- @noindent
- ...@: or to browse the profile:
- @example
- $ ls "$GUIX_ENVIRONMENT/bin"
- @end example
- Additionally, more than one package may be specified, in which case the
- union of the inputs for the given packages are used. For example, the
- command below spawns a shell where all of the dependencies of both Guile
- and Emacs are available:
- @example
- guix environment guile emacs
- @end example
- Sometimes an interactive shell session is not desired. An arbitrary
- command may be invoked by placing the @code{--} token to separate the
- command from the rest of the arguments:
- @example
- guix environment guile -- make -j4
- @end example
- In other situations, it is more convenient to specify the list of
- packages needed in the environment. For example, the following command
- runs @command{python} from an environment containing Python@tie{}3 and
- NumPy:
- @example
- guix environment --ad-hoc python-numpy python -- python3
- @end example
- Furthermore, one might want the dependencies of a package and also some
- additional packages that are not build-time or runtime dependencies, but
- are useful when developing nonetheless. Because of this, the
- @option{--ad-hoc} flag is positional. Packages appearing before
- @option{--ad-hoc} are interpreted as packages whose dependencies will be
- added to the environment. Packages appearing after are interpreted as
- packages that will be added to the environment directly. For example,
- the following command creates a Guix development environment that
- additionally includes Git and strace:
- @example
- guix environment --pure guix --ad-hoc git strace
- @end example
- @cindex container
- Sometimes it is desirable to isolate the environment as much as
- possible, for maximal purity and reproducibility. In particular, when
- using Guix on a host distro that is not Guix System, it is desirable to
- prevent access to @file{/usr/bin} and other system-wide resources from
- the development environment. For example, the following command spawns
- a Guile REPL in a ``container'' where only the store and the current
- working directory are mounted:
- @example
- guix environment --ad-hoc --container guile -- guile
- @end example
- @quotation Note
- The @option{--container} option requires Linux-libre 3.19 or newer.
- @end quotation
- @cindex certificates
- Another typical use case for containers is to run security-sensitive
- applications such as a web browser. To run Eolie, we must expose and
- share some files and directories; we include @code{nss-certs} and expose
- @file{/etc/ssl/certs/} for HTTPS authentication; finally we preserve the
- @env{DISPLAY} environment variable since containerized graphical
- applications won't display without it.
- @example
- guix environment --preserve='^DISPLAY$' --container --network \
- --expose=/etc/machine-id \
- --expose=/etc/ssl/certs/ \
- --share=$HOME/.local/share/eolie/=$HOME/.local/share/eolie/ \
- --ad-hoc eolie nss-certs dbus -- eolie
- @end example
- The available options are summarized below.
- @table @code
- @item --check
- Set up the environment and check whether the shell would clobber
- environment variables. @xref{Invoking guix shell, @option{--check}},
- for more info.
- @item --root=@var{file}
- @itemx -r @var{file}
- @cindex persistent environment
- @cindex garbage collector root, for environments
- Make @var{file} a symlink to the profile for this environment, and
- register it as a garbage collector root.
- This is useful if you want to protect your environment from garbage
- collection, to make it ``persistent''.
- When this option is omitted, the environment is protected from garbage
- collection only for the duration of the @command{guix environment}
- session. This means that next time you recreate the same environment,
- you could have to rebuild or re-download packages. @xref{Invoking guix
- gc}, for more on GC roots.
- @item --expression=@var{expr}
- @itemx -e @var{expr}
- Create an environment for the package or list of packages that
- @var{expr} evaluates to.
- For example, running:
- @example
- guix environment -e '(@@ (gnu packages maths) petsc-openmpi)'
- @end example
- starts a shell with the environment for this specific variant of the
- PETSc package.
- Running:
- @example
- guix environment --ad-hoc -e '(@@ (gnu) %base-packages)'
- @end example
- starts a shell with all the base system packages available.
- The above commands only use the default output of the given packages.
- To select other outputs, two element tuples can be specified:
- @example
- guix environment --ad-hoc -e '(list (@@ (gnu packages bash) bash) "include")'
- @end example
- @item --load=@var{file}
- @itemx -l @var{file}
- Create an environment for the package or list of packages that the code
- within @var{file} evaluates to.
- As an example, @var{file} might contain a definition like this
- (@pxref{Defining Packages}):
- @lisp
- @verbatiminclude environment-gdb.scm
- @end lisp
- @item --manifest=@var{file}
- @itemx -m @var{file}
- Create an environment for the packages contained in the manifest object
- returned by the Scheme code in @var{file}. This option can be repeated
- several times, in which case the manifests are concatenated.
- This is similar to the same-named option in @command{guix package}
- (@pxref{profile-manifest, @option{--manifest}}) and uses the same
- manifest files.
- @xref{shell-export-manifest, @command{guix shell --export-manifest}},
- for information on how to ``convert'' command-line options into a
- manifest.
- @item --ad-hoc
- Include all specified packages in the resulting environment, as if an
- @i{ad hoc} package were defined with them as inputs. This option is
- useful for quickly creating an environment without having to write a
- package expression to contain the desired inputs.
- For instance, the command:
- @example
- guix environment --ad-hoc guile guile-sdl -- guile
- @end example
- runs @command{guile} in an environment where Guile and Guile-SDL are
- available.
- Note that this example implicitly asks for the default output of
- @code{guile} and @code{guile-sdl}, but it is possible to ask for a
- specific output---e.g., @code{glib:bin} asks for the @code{bin} output
- of @code{glib} (@pxref{Packages with Multiple Outputs}).
- This option may be composed with the default behavior of @command{guix
- environment}. Packages appearing before @option{--ad-hoc} are
- interpreted as packages whose dependencies will be added to the
- environment, the default behavior. Packages appearing after are
- interpreted as packages that will be added to the environment directly.
- @item --profile=@var{profile}
- @itemx -p @var{profile}
- Create an environment containing the packages installed in @var{profile}.
- Use @command{guix package} (@pxref{Invoking guix package}) to create
- and manage profiles.
- @item --pure
- Unset existing environment variables when building the new environment, except
- those specified with @option{--preserve} (see below). This has the effect of
- creating an environment in which search paths only contain package inputs.
- @item --preserve=@var{regexp}
- @itemx -E @var{regexp}
- When used alongside @option{--pure}, preserve the environment variables
- matching @var{regexp}---in other words, put them on a ``white list'' of
- environment variables that must be preserved. This option can be repeated
- several times.
- @example
- guix environment --pure --preserve=^SLURM --ad-hoc openmpi @dots{} \
- -- mpirun @dots{}
- @end example
- This example runs @command{mpirun} in a context where the only environment
- variables defined are @env{PATH}, environment variables whose name starts
- with @samp{SLURM}, as well as the usual ``precious'' variables (@env{HOME},
- @env{USER}, etc.).
- @item --search-paths
- Display the environment variable definitions that make up the
- environment.
- @item --system=@var{system}
- @itemx -s @var{system}
- Attempt to build for @var{system}---e.g., @code{i686-linux}.
- @item --container
- @itemx -C
- @cindex container
- Run @var{command} within an isolated container. The current working
- directory outside the container is mapped inside the container.
- Additionally, unless overridden with @option{--user}, a dummy home
- directory is created that matches the current user's home directory, and
- @file{/etc/passwd} is configured accordingly.
- The spawned process runs as the current user outside the container. Inside
- the container, it has the same UID and GID as the current user, unless
- @option{--user} is passed (see below).
- @item --network
- @itemx -N
- For containers, share the network namespace with the host system.
- Containers created without this flag only have access to the loopback
- device.
- @item --link-profile
- @itemx -P
- For containers, link the environment profile to @file{~/.guix-profile}
- within the container and set @code{GUIX_ENVIRONMENT} to that.
- This is equivalent to making @file{~/.guix-profile} a symlink to the
- actual profile within the container.
- Linking will fail and abort the environment if the directory already
- exists, which will certainly be the case if @command{guix environment}
- was invoked in the user's home directory.
- Certain packages are configured to look in @file{~/.guix-profile} for
- configuration files and data;@footnote{For example, the
- @code{fontconfig} package inspects @file{~/.guix-profile/share/fonts}
- for additional fonts.} @option{--link-profile} allows these programs to
- behave as expected within the environment.
- @item --user=@var{user}
- @itemx -u @var{user}
- For containers, use the username @var{user} in place of the current
- user. The generated @file{/etc/passwd} entry within the container will
- contain the name @var{user}, the home directory will be
- @file{/home/@var{user}}, and no user GECOS data will be copied. Furthermore,
- the UID and GID inside the container are 1000. @var{user}
- need not exist on the system.
- Additionally, any shared or exposed path (see @option{--share} and
- @option{--expose} respectively) whose target is within the current user's
- home directory will be remapped relative to @file{/home/USER}; this
- includes the automatic mapping of the current working directory.
- @example
- # will expose paths as /home/foo/wd, /home/foo/test, and /home/foo/target
- cd $HOME/wd
- guix environment --container --user=foo \
- --expose=$HOME/test \
- --expose=/tmp/target=$HOME/target
- @end example
- While this will limit the leaking of user identity through home paths
- and each of the user fields, this is only one useful component of a
- broader privacy/anonymity solution---not one in and of itself.
- @item --no-cwd
- For containers, the default behavior is to share the current working
- directory with the isolated container and immediately change to that
- directory within the container. If this is undesirable,
- @option{--no-cwd} will cause the current working directory to @emph{not}
- be automatically shared and will change to the user's home directory
- within the container instead. See also @option{--user}.
- @item --expose=@var{source}[=@var{target}]
- @itemx --share=@var{source}[=@var{target}]
- For containers, @option{--expose} (resp. @option{--share}) exposes the
- file system @var{source} from the host system as the read-only
- (resp. writable) file system @var{target} within the container. If
- @var{target} is not specified, @var{source} is used as the target mount
- point in the container.
- The example below spawns a Guile REPL in a container in which the user's
- home directory is accessible read-only via the @file{/exchange}
- directory:
- @example
- guix environment --container --expose=$HOME=/exchange --ad-hoc guile -- guile
- @end example
- @end table
- @command{guix environment}
- also supports all of the common build options that @command{guix
- build} supports (@pxref{Common Build Options}) as well as package
- transformation options (@pxref{Package Transformation Options}).
- @node Invoking guix pack
- @section Invoking @command{guix pack}
- Occasionally you want to pass software to people who are not (yet!)
- lucky enough to be using Guix. You'd tell them to run @command{guix
- package -i @var{something}}, but that's not possible in this case. This
- is where @command{guix pack} comes in.
- @quotation Note
- If you are looking for ways to exchange binaries among machines that
- already run Guix, @pxref{Invoking guix copy}, @ref{Invoking guix
- publish}, and @ref{Invoking guix archive}.
- @end quotation
- @cindex pack
- @cindex bundle
- @cindex application bundle
- @cindex software bundle
- The @command{guix pack} command creates a shrink-wrapped @dfn{pack} or
- @dfn{software bundle}: it creates a tarball or some other archive
- containing the binaries of the software you're interested in, and all
- its dependencies. The resulting archive can be used on any machine that
- does not have Guix, and people can run the exact same binaries as those
- you have with Guix. The pack itself is created in a bit-reproducible
- fashion, so anyone can verify that it really contains the build results
- that you pretend to be shipping.
- For example, to create a bundle containing Guile, Emacs, Geiser, and all
- their dependencies, you can run:
- @example
- $ guix pack guile emacs emacs-geiser
- @dots{}
- /gnu/store/@dots{}-pack.tar.gz
- @end example
- The result here is a tarball containing a @file{/gnu/store} directory
- with all the relevant packages. The resulting tarball contains a
- @dfn{profile} with the three packages of interest; the profile is the
- same as would be created by @command{guix package -i}. It is this
- mechanism that is used to create Guix's own standalone binary tarball
- (@pxref{Binary Installation}).
- Users of this pack would have to run
- @file{/gnu/store/@dots{}-profile/bin/guile} to run Guile, which you may
- find inconvenient. To work around it, you can create, say, a
- @file{/opt/gnu/bin} symlink to the profile:
- @example
- guix pack -S /opt/gnu/bin=bin guile emacs emacs-geiser
- @end example
- @noindent
- That way, users can happily type @file{/opt/gnu/bin/guile} and enjoy.
- @cindex relocatable binaries, with @command{guix pack}
- What if the recipient of your pack does not have root privileges on
- their machine, and thus cannot unpack it in the root file system? In
- that case, you will want to use the @option{--relocatable} option (see
- below). This option produces @dfn{relocatable binaries}, meaning they
- they can be placed anywhere in the file system hierarchy: in the example
- above, users can unpack your tarball in their home directory and
- directly run @file{./opt/gnu/bin/guile}.
- @cindex Docker, build an image with guix pack
- Alternatively, you can produce a pack in the Docker image format using
- the following command:
- @example
- guix pack -f docker -S /bin=bin guile guile-readline
- @end example
- @noindent
- The result is a tarball that can be passed to the @command{docker load}
- command, followed by @code{docker run}:
- @example
- docker load < @var{file}
- docker run -ti guile-guile-readline /bin/guile
- @end example
- @noindent
- where @var{file} is the image returned by @var{guix pack}, and
- @code{guile-guile-readline} is its ``image tag''. See the
- @uref{https://docs.docker.com/engine/reference/commandline/load/, Docker
- documentation} for more information.
- @cindex Singularity, build an image with guix pack
- @cindex SquashFS, build an image with guix pack
- Yet another option is to produce a SquashFS image with the following
- command:
- @example
- guix pack -f squashfs bash guile emacs emacs-geiser
- @end example
- @noindent
- The result is a SquashFS file system image that can either be mounted or
- directly be used as a file system container image with the
- @uref{https://www.sylabs.io/docs/, Singularity container execution
- environment}, using commands like @command{singularity shell} or
- @command{singularity exec}.
- Several command-line options allow you to customize your pack:
- @table @code
- @item --format=@var{format}
- @itemx -f @var{format}
- Produce a pack in the given @var{format}.
- The available formats are:
- @table @code
- @item tarball
- This is the default format. It produces a tarball containing all the
- specified binaries and symlinks.
- @item docker
- This produces a tarball that follows the
- @uref{https://github.com/docker/docker/blob/master/image/spec/v1.2.md,
- Docker Image Specification}. The ``repository name'' as it appears in
- the output of the @command{docker images} command is computed from
- package names passed on the command line or in the manifest file.
- @item squashfs
- This produces a SquashFS image containing all the specified binaries and
- symlinks, as well as empty mount points for virtual file systems like
- procfs.
- @quotation Note
- Singularity @emph{requires} you to provide @file{/bin/sh} in the image.
- For that reason, @command{guix pack -f squashfs} always implies @code{-S
- /bin=bin}. Thus, your @command{guix pack} invocation must always start
- with something like:
- @example
- guix pack -f squashfs bash @dots{}
- @end example
- If you forget the @code{bash} (or similar) package, @command{singularity
- run} and @command{singularity exec} will fail with an unhelpful ``no
- such file or directory'' message.
- @end quotation
- @item deb
- This produces a Debian archive (a package with the @samp{.deb} file
- extension) containing all the specified binaries and symbolic links,
- that can be installed on top of any dpkg-based GNU(/Linux) distribution.
- Advanced options can be revealed via the @option{--help-deb-format}
- option. They allow embedding control files for more fine-grained
- control, such as activating specific triggers or providing a maintainer
- configure script to run arbitrary setup code upon installation.
- @example
- guix pack -f deb -C xz -S /usr/bin/hello=bin/hello hello
- @end example
- @quotation Note
- Because archives produced with @command{guix pack} contain a collection
- of store items and because each @command{dpkg} package must not have
- conflicting files, in practice that means you likely won't be able to
- install more than one such archive on a given system.
- @end quotation
- @quotation Warning
- @command{dpkg} will assume ownership of any files contained in the pack
- that it does @emph{not} know about. It is unwise to install
- Guix-produced @samp{.deb} files on a system where @file{/gnu/store} is
- shared by other software, such as a Guix installation or other, non-deb
- packs.
- @end quotation
- @end table
- @cindex relocatable binaries
- @item --relocatable
- @itemx -R
- Produce @dfn{relocatable binaries}---i.e., binaries that can be placed
- anywhere in the file system hierarchy and run from there.
- When this option is passed once, the resulting binaries require support for
- @dfn{user namespaces} in the kernel Linux; when passed
- @emph{twice}@footnote{Here's a trick to memorize it: @code{-RR}, which adds
- PRoot support, can be thought of as the abbreviation of ``Really
- Relocatable''. Neat, isn't it?}, relocatable binaries fall to back to
- other techniques if user namespaces are unavailable, and essentially
- work anywhere---see below for the implications.
- For example, if you create a pack containing Bash with:
- @example
- guix pack -RR -S /mybin=bin bash
- @end example
- @noindent
- ...@: you can copy that pack to a machine that lacks Guix, and from your
- home directory as a normal user, run:
- @example
- tar xf pack.tar.gz
- ./mybin/sh
- @end example
- @noindent
- In that shell, if you type @code{ls /gnu/store}, you'll notice that
- @file{/gnu/store} shows up and contains all the dependencies of
- @code{bash}, even though the machine actually lacks @file{/gnu/store}
- altogether! That is probably the simplest way to deploy Guix-built
- software on a non-Guix machine.
- @quotation Note
- By default, relocatable binaries rely on the @dfn{user namespace} feature of
- the kernel Linux, which allows unprivileged users to mount or change root.
- Old versions of Linux did not support it, and some GNU/Linux distributions
- turn it off.
- To produce relocatable binaries that work even in the absence of user
- namespaces, pass @option{--relocatable} or @option{-R} @emph{twice}. In that
- case, binaries will try user namespace support and fall back to another
- @dfn{execution engine} if user namespaces are not supported. The
- following execution engines are supported:
- @table @code
- @item default
- Try user namespaces and fall back to PRoot if user namespaces are not
- supported (see below).
- @item performance
- Try user namespaces and fall back to Fakechroot if user namespaces are
- not supported (see below).
- @item userns
- Run the program through user namespaces and abort if they are not
- supported.
- @item proot
- Run through PRoot. The @uref{https://proot-me.github.io/, PRoot} program
- provides the necessary
- support for file system virtualization. It achieves that by using the
- @code{ptrace} system call on the running program. This approach has the
- advantage to work without requiring special kernel support, but it incurs
- run-time overhead every time a system call is made.
- @item fakechroot
- Run through Fakechroot. @uref{https://github.com/dex4er/fakechroot/,
- Fakechroot} virtualizes file system accesses by intercepting calls to C
- library functions such as @code{open}, @code{stat}, @code{exec}, and so
- on. Unlike PRoot, it incurs very little overhead. However, it does not
- always work: for example, some file system accesses made from within the
- C library are not intercepted, and file system accesses made @i{via}
- direct syscalls are not intercepted either, leading to erratic behavior.
- @end table
- @vindex GUIX_EXECUTION_ENGINE
- When running a wrapped program, you can explicitly request one of the
- execution engines listed above by setting the
- @env{GUIX_EXECUTION_ENGINE} environment variable accordingly.
- @end quotation
- @cindex entry point, for Docker images
- @item --entry-point=@var{command}
- Use @var{command} as the @dfn{entry point} of the resulting pack, if the pack
- format supports it---currently @code{docker} and @code{squashfs} (Singularity)
- support it. @var{command} must be relative to the profile contained in the
- pack.
- The entry point specifies the command that tools like @code{docker run} or
- @code{singularity run} automatically start by default. For example, you can
- do:
- @example
- guix pack -f docker --entry-point=bin/guile guile
- @end example
- The resulting pack can easily be loaded and @code{docker run} with no extra
- arguments will spawn @code{bin/guile}:
- @example
- docker load -i pack.tar.gz
- docker run @var{image-id}
- @end example
- @item --expression=@var{expr}
- @itemx -e @var{expr}
- Consider the package @var{expr} evaluates to.
- This has the same purpose as the same-named option in @command{guix
- build} (@pxref{Additional Build Options, @option{--expression} in
- @command{guix build}}).
- @item --manifest=@var{file}
- @itemx -m @var{file}
- Use the packages contained in the manifest object returned by the Scheme
- code in @var{file}. This option can be repeated several times, in which
- case the manifests are concatenated.
- This has a similar purpose as the same-named option in @command{guix
- package} (@pxref{profile-manifest, @option{--manifest}}) and uses the
- same manifest files. It allows you to define a collection of packages
- once and use it both for creating profiles and for creating archives
- for use on machines that do not have Guix installed. Note that you can
- specify @emph{either} a manifest file @emph{or} a list of packages,
- but not both.
- @xref{shell-export-manifest, @command{guix shell --export-manifest}},
- for information on how to ``convert'' command-line options into a
- manifest.
- @item --system=@var{system}
- @itemx -s @var{system}
- Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of
- the system type of the build host.
- @item --target=@var{triplet}
- @cindex cross-compilation
- Cross-build for @var{triplet}, which must be a valid GNU triplet, such
- as @code{"aarch64-linux-gnu"} (@pxref{Specifying target triplets, GNU
- configuration triplets,, autoconf, Autoconf}).
- @item --compression=@var{tool}
- @itemx -C @var{tool}
- Compress the resulting tarball using @var{tool}---one of @code{gzip},
- @code{zstd}, @code{bzip2}, @code{xz}, @code{lzip}, or @code{none} for no
- compression.
- @item --symlink=@var{spec}
- @itemx -S @var{spec}
- Add the symlinks specified by @var{spec} to the pack. This option can
- appear several times.
- @var{spec} has the form @code{@var{source}=@var{target}}, where
- @var{source} is the symlink that will be created and @var{target} is the
- symlink target.
- For instance, @code{-S /opt/gnu/bin=bin} creates a @file{/opt/gnu/bin}
- symlink pointing to the @file{bin} sub-directory of the profile.
- @item --save-provenance
- Save provenance information for the packages passed on the command line.
- Provenance information includes the URL and commit of the channels in use
- (@pxref{Channels}).
- Provenance information is saved in the
- @file{/gnu/store/@dots{}-profile/manifest} file in the pack, along with the
- usual package metadata---the name and version of each package, their
- propagated inputs, and so on. It is useful information to the recipient of
- the pack, who then knows how the pack was (supposedly) obtained.
- This option is not enabled by default because, like timestamps, provenance
- information contributes nothing to the build process. In other words, there
- is an infinity of channel URLs and commit IDs that can lead to the same pack.
- Recording such ``silent'' metadata in the output thus potentially breaks the
- source-to-binary bitwise reproducibility property.
- @item --root=@var{file}
- @itemx -r @var{file}
- @cindex garbage collector root, for packs
- Make @var{file} a symlink to the resulting pack, and register it as a garbage
- collector root.
- @item --localstatedir
- @itemx --profile-name=@var{name}
- Include the ``local state directory'', @file{/var/guix}, in the resulting
- pack, and notably the @file{/var/guix/profiles/per-user/root/@var{name}}
- profile---by default @var{name} is @code{guix-profile}, which corresponds to
- @file{~root/.guix-profile}.
- @file{/var/guix} contains the store database (@pxref{The Store}) as well
- as garbage-collector roots (@pxref{Invoking guix gc}). Providing it in
- the pack means that the store is ``complete'' and manageable by Guix;
- not providing it pack means that the store is ``dead'': items cannot be
- added to it or removed from it after extraction of the pack.
- One use case for this is the Guix self-contained binary tarball
- (@pxref{Binary Installation}).
- @item --derivation
- @itemx -d
- Print the name of the derivation that builds the pack.
- @item --bootstrap
- Use the bootstrap binaries to build the pack. This option is only
- useful to Guix developers.
- @end table
- In addition, @command{guix pack} supports all the common build options
- (@pxref{Common Build Options}) and all the package transformation
- options (@pxref{Package Transformation Options}).
- @node The GCC toolchain
- @section The GCC toolchain
- @cindex GCC
- @cindex ld-wrapper
- @cindex linker wrapper
- @cindex toolchain, for C development
- @cindex toolchain, for Fortran development
- If you need a complete toolchain for compiling and linking C or C++
- source code, use the @code{gcc-toolchain} package. This package
- provides a complete GCC toolchain for C/C++ development, including GCC
- itself, the GNU C Library (headers and binaries, plus debugging symbols
- in the @code{debug} output), Binutils, and a linker wrapper.
- The wrapper's purpose is to inspect the @code{-L} and @code{-l} switches
- passed to the linker, add corresponding @code{-rpath} arguments, and
- invoke the actual linker with this new set of arguments. You can instruct the
- wrapper to refuse to link against libraries not in the store by setting the
- @env{GUIX_LD_WRAPPER_ALLOW_IMPURITIES} environment variable to @code{no}.
- The package @code{gfortran-toolchain} provides a complete GCC toolchain
- for Fortran development. For other languages, please use
- @samp{guix search gcc toolchain} (@pxref{guix-search,, Invoking guix package}).
- @node Invoking guix git authenticate
- @section Invoking @command{guix git authenticate}
- The @command{guix git authenticate} command authenticates a Git checkout
- following the same rule as for channels (@pxref{channel-authentication,
- channel authentication}). That is, starting from a given commit, it
- ensures that all subsequent commits are signed by an OpenPGP key whose
- fingerprint appears in the @file{.guix-authorizations} file of its
- parent commit(s).
- You will find this command useful if you maintain a channel. But in
- fact, this authentication mechanism is useful in a broader context, so
- you might want to use it for Git repositories that have nothing to do
- with Guix.
- The general syntax is:
- @example
- guix git authenticate @var{commit} @var{signer} [@var{options}@dots{}]
- @end example
- By default, this command authenticates the Git checkout in the current
- directory; it outputs nothing and exits with exit code zero on success
- and non-zero on failure. @var{commit} above denotes the first commit
- where authentication takes place, and @var{signer} is the OpenPGP
- fingerprint of public key used to sign @var{commit}. Together, they
- form a ``channel introduction'' (@pxref{channel-authentication, channel
- introduction}). The options below allow you to fine-tune the process.
- @table @code
- @item --repository=@var{directory}
- @itemx -r @var{directory}
- Open the Git repository in @var{directory} instead of the current
- directory.
- @item --keyring=@var{reference}
- @itemx -k @var{reference}
- Load OpenPGP keyring from @var{reference}, the reference of a branch
- such as @code{origin/keyring} or @code{my-keyring}. The branch must
- contain OpenPGP public keys in @file{.key} files, either in binary form
- or ``ASCII-armored''. By default the keyring is loaded from the branch
- named @code{keyring}.
- @item --stats
- Display commit signing statistics upon completion.
- @item --cache-key=@var{key}
- Previously-authenticated commits are cached in a file under
- @file{~/.cache/guix/authentication}. This option forces the cache to be
- stored in file @var{key} in that directory.
- @item --historical-authorizations=@var{file}
- By default, any commit whose parent commit(s) lack the
- @file{.guix-authorizations} file is considered inauthentic. In
- contrast, this option considers the authorizations in @var{file} for any
- commit that lacks @file{.guix-authorizations}. The format of @var{file}
- is the same as that of @file{.guix-authorizations}
- (@pxref{channel-authorizations, @file{.guix-authorizations} format}).
- @end table
- @c *********************************************************************
- @node Programming Interface
- @chapter Programming Interface
- GNU Guix provides several Scheme programming interfaces (APIs) to
- define, build, and query packages. The first interface allows users to
- write high-level package definitions. These definitions refer to
- familiar packaging concepts, such as the name and version of a package,
- its build system, and its dependencies. These definitions can then be
- turned into concrete build actions.
- Build actions are performed by the Guix daemon, on behalf of users. In a
- standard setup, the daemon has write access to the store---the
- @file{/gnu/store} directory---whereas users do not. The recommended
- setup also has the daemon perform builds in chroots, under specific
- build users, to minimize interference with the rest of the system.
- @cindex derivation
- Lower-level APIs are available to interact with the daemon and the
- store. To instruct the daemon to perform a build action, users actually
- provide it with a @dfn{derivation}. A derivation is a low-level
- representation of the build actions to be taken, and the environment in
- which they should occur---derivations are to package definitions what
- assembly is to C programs. The term ``derivation'' comes from the fact
- that build results @emph{derive} from them.
- This chapter describes all these APIs in turn, starting from high-level
- package definitions.
- @menu
- * Package Modules:: Packages from the programmer's viewpoint.
- * Defining Packages:: Defining new packages.
- * Defining Package Variants:: Customizing packages.
- * Build Systems:: Specifying how packages are built.
- * Build Phases:: Phases of the build process of a package.
- * Build Utilities:: Helpers for your package definitions and more.
- * Search Paths:: Declaring search path environment variables.
- * The Store:: Manipulating the package store.
- * Derivations:: Low-level interface to package derivations.
- * The Store Monad:: Purely functional interface to the store.
- * G-Expressions:: Manipulating build expressions.
- * Invoking guix repl:: Programming Guix in Guile
- @end menu
- @node Package Modules
- @section Package Modules
- From a programming viewpoint, the package definitions of the
- GNU distribution are provided by Guile modules in the @code{(gnu packages
- @dots{})} name space@footnote{Note that packages under the @code{(gnu
- packages @dots{})} module name space are not necessarily ``GNU
- packages''. This module naming scheme follows the usual Guile module
- naming convention: @code{gnu} means that these modules are distributed
- as part of the GNU system, and @code{packages} identifies modules that
- define packages.} (@pxref{Modules, Guile modules,, guile, GNU Guile
- Reference Manual}). For instance, the @code{(gnu packages emacs)}
- module exports a variable named @code{emacs}, which is bound to a
- @code{<package>} object (@pxref{Defining Packages}).
- The @code{(gnu packages @dots{})} module name space is
- automatically scanned for packages by the command-line tools. For
- instance, when running @code{guix install emacs}, all the @code{(gnu
- packages @dots{})} modules are scanned until one that exports a package
- object whose name is @code{emacs} is found. This package search
- facility is implemented in the @code{(gnu packages)} module.
- @cindex customization, of packages
- @cindex package module search path
- Users can store package definitions in modules with different
- names---e.g., @code{(my-packages emacs)}@footnote{Note that the file
- name and module name must match. For instance, the @code{(my-packages
- emacs)} module must be stored in a @file{my-packages/emacs.scm} file
- relative to the load path specified with @option{--load-path} or
- @env{GUIX_PACKAGE_PATH}. @xref{Modules and the File System,,,
- guile, GNU Guile Reference Manual}, for details.}. There are two ways to make
- these package definitions visible to the user interfaces:
- @enumerate
- @item
- By adding the directory containing your package modules to the search path
- with the @code{-L} flag of @command{guix package} and other commands
- (@pxref{Common Build Options}), or by setting the @env{GUIX_PACKAGE_PATH}
- environment variable described below.
- @item
- By defining a @dfn{channel} and configuring @command{guix pull} so that it
- pulls from it. A channel is essentially a Git repository containing package
- modules. @xref{Channels}, for more information on how to define and use
- channels.
- @end enumerate
- @env{GUIX_PACKAGE_PATH} works similarly to other search path variables:
- @defvr {Environment Variable} GUIX_PACKAGE_PATH
- This is a colon-separated list of directories to search for additional
- package modules. Directories listed in this variable take precedence
- over the own modules of the distribution.
- @end defvr
- The distribution is fully @dfn{bootstrapped} and @dfn{self-contained}:
- each package is built based solely on other packages in the
- distribution. The root of this dependency graph is a small set of
- @dfn{bootstrap binaries}, provided by the @code{(gnu packages
- bootstrap)} module. For more information on bootstrapping,
- @pxref{Bootstrapping}.
- @node Defining Packages
- @section Defining Packages
- The high-level interface to package definitions is implemented in the
- @code{(guix packages)} and @code{(guix build-system)} modules. As an
- example, the package definition, or @dfn{recipe}, for the GNU Hello
- package looks like this:
- @lisp
- (define-module (gnu packages hello)
- #:use-module (guix packages)
- #:use-module (guix download)
- #:use-module (guix build-system gnu)
- #:use-module (guix licenses)
- #:use-module (gnu packages gawk))
- (define-public hello
- (package
- (name "hello")
- (version "2.10")
- (source (origin
- (method url-fetch)
- (uri (string-append "mirror://gnu/hello/hello-" version
- ".tar.gz"))
- (sha256
- (base32
- "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i"))))
- (build-system gnu-build-system)
- (arguments '(#:configure-flags '("--enable-silent-rules")))
- (inputs (list gawk))
- (synopsis "Hello, GNU world: An example GNU package")
- (description "Guess what GNU Hello prints!")
- (home-page "https://www.gnu.org/software/hello/")
- (license gpl3+)))
- @end lisp
- @noindent
- Without being a Scheme expert, the reader may have guessed the meaning
- of the various fields here. This expression binds the variable
- @code{hello} to a @code{<package>} object, which is essentially a record
- (@pxref{SRFI-9, Scheme records,, guile, GNU Guile Reference Manual}).
- This package object can be inspected using procedures found in the
- @code{(guix packages)} module; for instance, @code{(package-name hello)}
- returns---surprise!---@code{"hello"}.
- With luck, you may be able to import part or all of the definition of
- the package you are interested in from another repository, using the
- @code{guix import} command (@pxref{Invoking guix import}).
- In the example above, @code{hello} is defined in a module of its own,
- @code{(gnu packages hello)}. Technically, this is not strictly
- necessary, but it is convenient to do so: all the packages defined in
- modules under @code{(gnu packages @dots{})} are automatically known to
- the command-line tools (@pxref{Package Modules}).
- There are a few points worth noting in the above package definition:
- @itemize
- @item
- The @code{source} field of the package is an @code{<origin>} object
- (@pxref{origin Reference}, for the complete reference).
- Here, the @code{url-fetch} method from @code{(guix download)} is used,
- meaning that the source is a file to be downloaded over FTP or HTTP.
- The @code{mirror://gnu} prefix instructs @code{url-fetch} to use one of
- the GNU mirrors defined in @code{(guix download)}.
- The @code{sha256} field specifies the expected SHA256 hash of the file
- being downloaded. It is mandatory, and allows Guix to check the
- integrity of the file. The @code{(base32 @dots{})} form introduces the
- base32 representation of the hash. You can obtain this information with
- @code{guix download} (@pxref{Invoking guix download}) and @code{guix
- hash} (@pxref{Invoking guix hash}).
- @cindex patches
- When needed, the @code{origin} form can also have a @code{patches} field
- listing patches to be applied, and a @code{snippet} field giving a
- Scheme expression to modify the source code.
- @item
- @cindex GNU Build System
- The @code{build-system} field specifies the procedure to build the
- package (@pxref{Build Systems}). Here, @code{gnu-build-system}
- represents the familiar GNU Build System, where packages may be
- configured, built, and installed with the usual @code{./configure &&
- make && make check && make install} command sequence.
- When you start packaging non-trivial software, you may need tools to
- manipulate those build phases, manipulate files, and so on. @xref{Build
- Utilities}, for more on this.
- @item
- The @code{arguments} field specifies options for the build system
- (@pxref{Build Systems}). Here it is interpreted by
- @code{gnu-build-system} as a request run @file{configure} with the
- @option{--enable-silent-rules} flag.
- @cindex quote
- @cindex quoting
- @findex '
- @findex quote
- @cindex backquote (quasiquote)
- @findex `
- @findex quasiquote
- @cindex comma (unquote)
- @findex ,
- @findex unquote
- What about these quote (@code{'}) characters? They are Scheme syntax to
- introduce a literal list; @code{'} is synonymous with @code{quote}.
- Sometimes you'll also see @code{`} (a backquote, synonymous with
- @code{quasiquote}) and @code{,} (a comma, synonymous with @code{unquote}).
- @xref{Expression Syntax, quoting,, guile, GNU Guile Reference Manual},
- for details. Here the value of the @code{arguments} field is a list of
- arguments passed to the build system down the road, as with @code{apply}
- (@pxref{Fly Evaluation, @code{apply},, guile, GNU Guile Reference
- Manual}).
- The hash-colon (@code{#:}) sequence defines a Scheme @dfn{keyword}
- (@pxref{Keywords,,, guile, GNU Guile Reference Manual}), and
- @code{#:configure-flags} is a keyword used to pass a keyword argument
- to the build system (@pxref{Coding With Keywords,,, guile, GNU Guile
- Reference Manual}).
- @item
- The @code{inputs} field specifies inputs to the build process---i.e.,
- build-time or run-time dependencies of the package. Here, we add
- an input, a reference to the @code{gawk}
- variable; @code{gawk} is itself bound to a @code{<package>} object.
- Note that GCC, Coreutils, Bash, and other essential tools do not need to
- be specified as inputs here. Instead, @code{gnu-build-system} takes care
- of ensuring that they are present (@pxref{Build Systems}).
- However, any other dependencies need to be specified in the
- @code{inputs} field. Any dependency not specified here will simply be
- unavailable to the build process, possibly leading to a build failure.
- @end itemize
- @xref{package Reference}, for a full description of possible fields.
- Once a package definition is in place, the
- package may actually be built using the @code{guix build} command-line
- tool (@pxref{Invoking guix build}), troubleshooting any build failures
- you encounter (@pxref{Debugging Build Failures}). You can easily jump back to the
- package definition using the @command{guix edit} command
- (@pxref{Invoking guix edit}).
- @xref{Packaging Guidelines}, for
- more information on how to test package definitions, and
- @ref{Invoking guix lint}, for information on how to check a definition
- for style conformance.
- @vindex GUIX_PACKAGE_PATH
- Lastly, @pxref{Channels}, for information
- on how to extend the distribution by adding your own package definitions
- in a ``channel''.
- Finally, updating the package definition to a new upstream version
- can be partly automated by the @command{guix refresh} command
- (@pxref{Invoking guix refresh}).
- Behind the scenes, a derivation corresponding to the @code{<package>}
- object is first computed by the @code{package-derivation} procedure.
- That derivation is stored in a @file{.drv} file under @file{/gnu/store}.
- The build actions it prescribes may then be realized by using the
- @code{build-derivations} procedure (@pxref{The Store}).
- @deffn {Scheme Procedure} package-derivation @var{store} @var{package} [@var{system}]
- Return the @code{<derivation>} object of @var{package} for @var{system}
- (@pxref{Derivations}).
- @var{package} must be a valid @code{<package>} object, and @var{system}
- must be a string denoting the target system type---e.g.,
- @code{"x86_64-linux"} for an x86_64 Linux-based GNU system. @var{store}
- must be a connection to the daemon, which operates on the store
- (@pxref{The Store}).
- @end deffn
- @noindent
- @cindex cross-compilation
- Similarly, it is possible to compute a derivation that cross-builds a
- package for some other system:
- @deffn {Scheme Procedure} package-cross-derivation @var{store} @
- @var{package} @var{target} [@var{system}]
- Return the @code{<derivation>} object of @var{package} cross-built from
- @var{system} to @var{target}.
- @var{target} must be a valid GNU triplet denoting the target hardware
- and operating system, such as @code{"aarch64-linux-gnu"}
- (@pxref{Specifying Target Triplets,,, autoconf, Autoconf}).
- @end deffn
- Once you have package definitions, you can easily define @emph{variants}
- of those packages. @xref{Defining Package Variants}, for more on that.
- @menu
- * package Reference:: The package data type.
- * origin Reference:: The origin data type.
- @end menu
- @node package Reference
- @subsection @code{package} Reference
- This section summarizes all the options available in @code{package}
- declarations (@pxref{Defining Packages}).
- @deftp {Data Type} package
- This is the data type representing a package recipe.
- @table @asis
- @item @code{name}
- The name of the package, as a string.
- @item @code{version}
- The version of the package, as a string. @xref{Version Numbers}, for
- guidelines.
- @item @code{source}
- An object telling how the source code for the package should be
- acquired. Most of the time, this is an @code{origin} object, which
- denotes a file fetched from the Internet (@pxref{origin Reference}). It
- can also be any other ``file-like'' object such as a @code{local-file},
- which denotes a file from the local file system (@pxref{G-Expressions,
- @code{local-file}}).
- @item @code{build-system}
- The build system that should be used to build the package (@pxref{Build
- Systems}).
- @item @code{arguments} (default: @code{'()})
- The arguments that should be passed to the build system. This is a
- list, typically containing sequential keyword-value pairs.
- @item @code{inputs} (default: @code{'()})
- @itemx @code{native-inputs} (default: @code{'()})
- @itemx @code{propagated-inputs} (default: @code{'()})
- @cindex inputs, of packages
- These fields list dependencies of the package. Each element of these
- lists is either a package, origin, or other ``file-like object''
- (@pxref{G-Expressions}); to specify the output of that file-like object
- that should be used, pass a two-element list where the second element is
- the output (@pxref{Packages with Multiple Outputs}, for more on package
- outputs). For example, the list below specifies three inputs:
- @lisp
- (list libffi libunistring
- `(,glib "bin")) ;the "bin" output of GLib
- @end lisp
- In the example above, the @code{"out"} output of @code{libffi} and
- @code{libunistring} is used.
- @quotation Compatibility Note
- Until version 1.3.0, input lists were a list of tuples,
- where each tuple has a label for the input (a string) as its
- first element, a package, origin, or derivation as its second element,
- and optionally the name of the output thereof that should be used, which
- defaults to @code{"out"}. For example, the list below is equivalent to
- the one above, but using the @dfn{old input style}:
- @lisp
- ;; Old input style (deprecated).
- `(("libffi" ,libffi)
- ("libunistring" ,libunistring)
- ("glib:bin" ,glib "bin")) ;the "bin" output of GLib
- @end lisp
- This style is now deprecated; it is still supported but support will be
- removed in a future version. It should not be used for new package
- definitions. @xref{Invoking guix style}, on how to migrate to the new
- style.
- @end quotation
- @cindex cross compilation, package dependencies
- The distinction between @code{native-inputs} and @code{inputs} is
- necessary when considering cross-compilation. When cross-compiling,
- dependencies listed in @code{inputs} are built for the @emph{target}
- architecture; conversely, dependencies listed in @code{native-inputs}
- are built for the architecture of the @emph{build} machine.
- @code{native-inputs} is typically used to list tools needed at
- build time, but not at run time, such as Autoconf, Automake, pkg-config,
- Gettext, or Bison. @command{guix lint} can report likely mistakes in
- this area (@pxref{Invoking guix lint}).
- @anchor{package-propagated-inputs}
- Lastly, @code{propagated-inputs} is similar to @code{inputs}, but the
- specified packages will be automatically installed to profiles
- (@pxref{Features, the role of profiles in Guix}) alongside the package
- they belong to (@pxref{package-cmd-propagated-inputs, @command{guix
- package}}, for information on how @command{guix package} deals with
- propagated inputs).
- For example this is necessary when packaging a C/C++ library that needs
- headers of another library to compile, or when a pkg-config file refers
- to another one @i{via} its @code{Requires} field.
- Another example where @code{propagated-inputs} is useful is for languages
- that lack a facility to record the run-time search path akin to the
- @code{RUNPATH} of ELF files; this includes Guile, Python, Perl, and
- more. When packaging libraries written in those languages, ensure they
- can find library code they depend on at run time by listing run-time
- dependencies in @code{propagated-inputs} rather than @code{inputs}.
- @item @code{outputs} (default: @code{'("out")})
- The list of output names of the package. @xref{Packages with Multiple
- Outputs}, for typical uses of additional outputs.
- @item @code{native-search-paths} (default: @code{'()})
- @itemx @code{search-paths} (default: @code{'()})
- A list of @code{search-path-specification} objects describing
- search-path environment variables honored by the package. @xref{Search
- Paths}, for more on search path specifications.
- As for inputs, the distinction between @code{native-search-paths} and
- @code{search-paths} only matters when cross-compiling. In a
- cross-compilation context, @code{native-search-paths} applies
- exclusively to native inputs whereas @code{search-paths} applies only to
- host inputs.
- Packages such as cross-compilers care about target inputs---for
- instance, our (modified) GCC cross-compiler has
- @env{CROSS_C_INCLUDE_PATH} in @code{search-paths}, which allows it to
- pick @file{.h} files for the target system and @emph{not} those of
- native inputs. For the majority of packages though, only
- @code{native-search-paths} makes sense.
- @item @code{replacement} (default: @code{#f})
- This must be either @code{#f} or a package object that will be used as a
- @dfn{replacement} for this package. @xref{Security Updates, grafts},
- for details.
- @item @code{synopsis}
- A one-line description of the package.
- @item @code{description}
- A more elaborate description of the package, as a string in Texinfo
- syntax.
- @item @code{license}
- @cindex license, of packages
- The license of the package; a value from @code{(guix licenses)},
- or a list of such values.
- @item @code{home-page}
- The URL to the home-page of the package, as a string.
- @item @code{supported-systems} (default: @code{%supported-systems})
- The list of systems supported by the package, as strings of the form
- @code{architecture-kernel}, for example @code{"x86_64-linux"}.
- @item @code{location} (default: source location of the @code{package} form)
- The source location of the package. It is useful to override this when
- inheriting from another package, in which case this field is not
- automatically corrected.
- @end table
- @end deftp
- @deffn {Scheme Syntax} this-package
- When used in the @emph{lexical scope} of a package field definition, this
- identifier resolves to the package being defined.
- The example below shows how to add a package as a native input of itself when
- cross-compiling:
- @lisp
- (package
- (name "guile")
- ;; ...
- ;; When cross-compiled, Guile, for example, depends on
- ;; a native version of itself. Add it here.
- (native-inputs (if (%current-target-system)
- (list this-package)
- '())))
- @end lisp
- It is an error to refer to @code{this-package} outside a package definition.
- @end deffn
- The following helper procedures are provided to help deal with package
- inputs.
- @deffn {Scheme Procedure} lookup-package-input @var{package} @var{name}
- @deffnx {Scheme Procedure} lookup-package-native-input @var{package} @var{name}
- @deffnx {Scheme Procedure} lookup-package-propagated-input @var{package} @var{name}
- @deffnx {Scheme Procedure} lookup-package-direct-input @var{package} @var{name}
- Look up @var{name} among @var{package}'s inputs (or native, propagated,
- or direct inputs). Return it if found, @code{#f} otherwise.
- @var{name} is the name of a package depended on. Here's how you might
- use it:
- @lisp
- (use-modules (guix packages) (gnu packages base))
- (lookup-package-direct-input coreutils "gmp")
- @result{} #<package gmp@@6.2.1 @dots{}>
- @end lisp
- In this example we obtain the @code{gmp} package that is among the
- direct inputs of @code{coreutils}.
- @end deffn
- @cindex development inputs, of a package
- @cindex implicit inputs, of a package
- Sometimes you will want to obtain the list of inputs needed to
- @emph{develop} a package---all the inputs that are visible when the
- package is compiled. This is what the @code{package-development-inputs}
- procedure returns.
- @deffn {Scheme Procedure} package-development-inputs @var{package} @
- [@var{system}] [#:target #f]
- Return the list of inputs required by @var{package} for development
- purposes on @var{system}. When @var{target} is true, return the inputs
- needed to cross-compile @var{package} from @var{system} to
- @var{triplet}, where @var{triplet} is a triplet such as
- @code{"aarch64-linux-gnu"}.
- Note that the result includes both explicit inputs and implicit
- inputs---inputs automatically added by the build system (@pxref{Build
- Systems}). Let us take the @code{hello} package to illustrate that:
- @lisp
- (use-modules (gnu packages base) (guix packages))
- hello
- @result{} #<package hello@@2.10 gnu/packages/base.scm:79 7f585d4f6790>
- (package-direct-inputs hello)
- @result{} ()
- (package-development-inputs hello)
- @result{} (("source" @dots{}) ("tar" #<package tar@@1.32 @dots{}>) @dots{})
- @end lisp
- In this example, @code{package-direct-inputs} returns the empty list,
- because @code{hello} has zero explicit dependencies. Conversely,
- @code{package-development-inputs} includes inputs implicitly added by
- @code{gnu-build-system} that are required to build @code{hello}: tar,
- gzip, GCC, libc, Bash, and more. To visualize it, @command{guix graph
- hello} would show you explicit inputs, whereas @command{guix graph -t
- bag hello} would include implicit inputs (@pxref{Invoking guix graph}).
- @end deffn
- Because packages are regular Scheme objects that capture a complete
- dependency graph and associated build procedures, it is often useful to
- write procedures that take a package and return a modified version
- thereof according to some parameters. Below are a few examples.
- @cindex tool chain, choosing a package's tool chain
- @deffn {Scheme Procedure} package-with-c-toolchain @var{package} @var{toolchain}
- Return a variant of @var{package} that uses @var{toolchain} instead of
- the default GNU C/C++ toolchain. @var{toolchain} must be a list of
- inputs (label/package tuples) providing equivalent functionality, such
- as the @code{gcc-toolchain} package.
- The example below returns a variant of the @code{hello} package built
- with GCC@tie{}10.x and the rest of the GNU tool chain (Binutils and the
- GNU C Library) instead of the default tool chain:
- @lisp
- (let ((toolchain (specification->package "gcc-toolchain@@10")))
- (package-with-c-toolchain hello `(("toolchain" ,toolchain))))
- @end lisp
- The build tool chain is part of the @dfn{implicit inputs} of
- packages---it's usually not listed as part of the various ``inputs''
- fields and is instead pulled in by the build system. Consequently, this
- procedure works by changing the build system of @var{package} so that it
- pulls in @var{toolchain} instead of the defaults. @ref{Build Systems},
- for more on build systems.
- @end deffn
- @node origin Reference
- @subsection @code{origin} Reference
- This section documents @dfn{origins}. An @code{origin} declaration
- specifies data that must be ``produced''---downloaded, usually---and
- whose content hash is known in advance. Origins are primarily used to
- represent the source code of packages (@pxref{Defining Packages}). For
- that reason, the @code{origin} form allows you to declare patches to
- apply to the original source code as well as code snippets to modify it.
- @deftp {Data Type} origin
- This is the data type representing a source code origin.
- @table @asis
- @item @code{uri}
- An object containing the URI of the source. The object type depends on
- the @code{method} (see below). For example, when using the
- @var{url-fetch} method of @code{(guix download)}, the valid @code{uri}
- values are: a URL represented as a string, or a list thereof.
- @cindex fixed-output derivations, for download
- @item @code{method}
- A monadic procedure that handles the given URI@. The procedure must
- accept at least three arguments: the value of the @code{uri} field and
- the hash algorithm and hash value specified by the @code{hash} field.
- It must return a store item or a derivation in the store monad
- (@pxref{The Store Monad}); most methods return a fixed-output derivation
- (@pxref{Derivations}).
- Commonly used methods include @code{url-fetch}, which fetches data from
- a URL, and @code{git-fetch}, which fetches data from a Git repository
- (see below).
- @item @code{sha256}
- A bytevector containing the SHA-256 hash of the source. This is
- equivalent to providing a @code{content-hash} SHA256 object in the
- @code{hash} field described below.
- @item @code{hash}
- The @code{content-hash} object of the source---see below for how to use
- @code{content-hash}.
- You can obtain this information using @code{guix download}
- (@pxref{Invoking guix download}) or @code{guix hash} (@pxref{Invoking
- guix hash}).
- @item @code{file-name} (default: @code{#f})
- The file name under which the source code should be saved. When this is
- @code{#f}, a sensible default value will be used in most cases. In case
- the source is fetched from a URL, the file name from the URL will be
- used. For version control checkouts, it is recommended to provide the
- file name explicitly because the default is not very descriptive.
- @item @code{patches} (default: @code{'()})
- A list of file names, origins, or file-like objects (@pxref{G-Expressions,
- file-like objects}) pointing to patches to be applied to the source.
- This list of patches must be unconditional. In particular, it cannot
- depend on the value of @code{%current-system} or
- @code{%current-target-system}.
- @item @code{snippet} (default: @code{#f})
- A G-expression (@pxref{G-Expressions}) or S-expression that will be run
- in the source directory. This is a convenient way to modify the source,
- sometimes more convenient than a patch.
- @item @code{patch-flags} (default: @code{'("-p1")})
- A list of command-line flags that should be passed to the @code{patch}
- command.
- @item @code{patch-inputs} (default: @code{#f})
- Input packages or derivations to the patching process. When this is
- @code{#f}, the usual set of inputs necessary for patching are provided,
- such as GNU@tie{}Patch.
- @item @code{modules} (default: @code{'()})
- A list of Guile modules that should be loaded during the patching
- process and while running the code in the @code{snippet} field.
- @item @code{patch-guile} (default: @code{#f})
- The Guile package that should be used in the patching process. When
- this is @code{#f}, a sensible default is used.
- @end table
- @end deftp
- @deftp {Data Type} content-hash @var{value} [@var{algorithm}]
- Construct a content hash object for the given @var{algorithm}, and with
- @var{value} as its hash value. When @var{algorithm} is omitted, assume
- it is @code{sha256}.
- @var{value} can be a literal string, in which case it is base32-decoded,
- or it can be a bytevector.
- The following forms are all equivalent:
- @lisp
- (content-hash "05zxkyz9bv3j9h0xyid1rhvh3klhsmrpkf3bcs6frvlgyr2gwilj")
- (content-hash "05zxkyz9bv3j9h0xyid1rhvh3klhsmrpkf3bcs6frvlgyr2gwilj"
- sha256)
- (content-hash (base32
- "05zxkyz9bv3j9h0xyid1rhvh3klhsmrpkf3bcs6frvlgyr2gwilj"))
- (content-hash (base64 "kkb+RPaP7uyMZmu4eXPVkM4BN8yhRd8BTHLslb6f/Rc=")
- sha256)
- @end lisp
- Technically, @code{content-hash} is currently implemented as a macro.
- It performs sanity checks at macro-expansion time, when possible, such
- as ensuring that @var{value} has the right size for @var{algorithm}.
- @end deftp
- As we have seen above, how exactly the data an origin refers to is
- retrieved is determined by its @code{method} field. The @code{(guix
- download)} module provides the most common method, @code{url-fetch},
- described below.
- @deffn {Scheme Procedure} url-fetch @var{url} @var{hash-algo} @var{hash} @
- [name] [#:executable? #f]
- Return a fixed-output derivation that fetches data from @var{url} (a
- string, or a list of strings denoting alternate URLs), which is expected
- to have hash @var{hash} of type @var{hash-algo} (a symbol). By default,
- the file name is the base name of URL; optionally, @var{name} can
- specify a different file name. When @var{executable?} is true, make the
- downloaded file executable.
- When one of the URL starts with @code{mirror://}, then its host part is
- interpreted as the name of a mirror scheme, taken from @file{%mirror-file}.
- Alternatively, when URL starts with @code{file://}, return the
- corresponding file name in the store.
- @end deffn
- Likewise, the @code{(guix git-download)} module defines the
- @code{git-fetch} origin method, which fetches data from a Git version
- control repository, and the @code{git-reference} data type to describe
- the repository and revision to fetch.
- @deffn {Scheme Procedure} git-fetch @var{ref} @var{hash-algo} @var{hash}
- Return a fixed-output derivation that fetches @var{ref}, a
- @code{<git-reference>} object. The output is expected to have recursive
- hash @var{hash} of type @var{hash-algo} (a symbol). Use @var{name} as
- the file name, or a generic name if @code{#f}.
- @end deffn
- @deftp {Data Type} git-reference
- This data type represents a Git reference for @code{git-fetch} to
- retrieve.
- @table @asis
- @item @code{url}
- The URL of the Git repository to clone.
- @item @code{commit}
- This string denotes either the commit to fetch (a hexadecimal string),
- or the tag to fetch. You can also use a ``short'' commit ID or a
- @command{git describe} style identifier such as
- @code{v1.0.1-10-g58d7909c97}.
- @item @code{recursive?} (default: @code{#f})
- This Boolean indicates whether to recursively fetch Git sub-modules.
- @end table
- The example below denotes the @code{v2.10} tag of the GNU@tie{}Hello
- repository:
- @lisp
- (git-reference
- (url "https://git.savannah.gnu.org/git/hello.git")
- (commit "v2.10"))
- @end lisp
- This is equivalent to the reference below, which explicitly names the
- commit:
- @lisp
- (git-reference
- (url "https://git.savannah.gnu.org/git/hello.git")
- (commit "dc7dc56a00e48fe6f231a58f6537139fe2908fb9"))
- @end lisp
- @end deftp
- For Mercurial repositories, the module @code{(guix hg-download)} defines
- the @code{hg-fetch} origin method and @code{hg-reference} data type for
- support of the Mercurial version control system.
- @deffn {Scheme Procedure} hg-fetch @var{ref} @var{hash-algo} @var{hash} @
- [name]
- Return a fixed-output derivation that fetches @var{ref}, a
- @code{<hg-reference>} object. The output is expected to have recursive
- hash @var{hash} of type @var{hash-algo} (a symbol). Use @var{name} as
- the file name, or a generic name if @code{#false}.
- @end deffn
- @node Defining Package Variants
- @section Defining Package Variants
- @cindex customizing packages
- @cindex variants, of packages
- One of the nice things with Guix is that, given a package definition,
- you can easily @emph{derive} variants of that package---for a different
- upstream version, with different dependencies, different compilation
- options, and so on. Some of these custom packages can be defined
- straight from the command line (@pxref{Package Transformation Options}).
- This section describes how to define package variants in code. This can
- be useful in ``manifests'' (@pxref{profile-manifest,
- @option{--manifest}}) and in your own package collection
- (@pxref{Creating a Channel}), among others!
- @cindex inherit, for package definitions
- As discussed earlier, packages are first-class objects in the Scheme
- language. The @code{(guix packages)} module provides the @code{package}
- construct to define new package objects (@pxref{package Reference}).
- The easiest way to define a package variant is using the @code{inherit}
- keyword together with @code{package}. This allows you to inherit from a
- package definition while overriding the fields you want.
- For example, given the @code{hello} variable, which contains a
- definition for the current version of GNU@tie{}Hello, here's how you
- would define a variant for version 2.2 (released in 2006, it's
- vintage!):
- @lisp
- (use-modules (gnu packages base)) ;for 'hello'
- (define hello-2.2
- (package
- (inherit hello)
- (version "2.2")
- (source (origin
- (method url-fetch)
- (uri (string-append "mirror://gnu/hello/hello-" version
- ".tar.gz"))
- (sha256
- (base32
- "0lappv4slgb5spyqbh6yl5r013zv72yqg2pcl30mginf3wdqd8k9"))))))
- @end lisp
- The example above corresponds to what the @option{--with-source} package
- transformation option does. Essentially @code{hello-2.2} preserves all
- the fields of @code{hello}, except @code{version} and @code{source},
- which it overrides. Note that the original @code{hello} variable is
- still there, in the @code{(gnu packages base)} module, unchanged. When
- you define a custom package like this, you are really @emph{adding} a
- new package definition; the original one remains available.
- You can just as well define variants with a different set of
- dependencies than the original package. For example, the default
- @code{gdb} package depends on @code{guile}, but since that is an
- optional dependency, you can define a variant that removes that
- dependency like so:
- @lisp
- (use-modules (gnu packages gdb)) ;for 'gdb'
- (define gdb-sans-guile
- (package
- (inherit gdb)
- (inputs (modify-inputs (package-inputs gdb)
- (delete "guile")))))
- @end lisp
- The @code{modify-inputs} form above removes the @code{"guile"} package
- from the @code{inputs} field of @code{gdb}. The @code{modify-inputs}
- macro is a helper that can prove useful anytime you want to remove, add,
- or replace package inputs.
- @deffn {Scheme Syntax} modify-inputs @var{inputs} @var{clauses}
- Modify the given package inputs, as returned by @code{package-inputs} & co.,
- according to the given clauses. Each clause must have one of the
- following forms:
- @table @code
- @item (delete @var{name}@dots{})
- Delete from the inputs packages with the given @var{name}s (strings).
- @item (append @var{package}@dots{})
- Add @var{package}s to the end of the input list.
- @item (prepend @var{package}@dots{})
- Add @var{package}s to the front of the input list.
- @end table
- The example below removes the GMP and ACL inputs of Coreutils and adds
- libcap to the back of the input list:
- @lisp
- (modify-inputs (package-inputs coreutils)
- (delete "gmp" "acl")
- (append libcap))
- @end lisp
- The example below replaces the @code{guile} package from the inputs of
- @code{guile-redis} with @code{guile-2.2}:
- @lisp
- (modify-inputs (package-inputs guile-redis)
- (replace "guile" guile-2.2))
- @end lisp
- The last type of clause is @code{prepend}, to add inputs to the front of
- the list.
- @end deffn
- In some cases, you may find it useful to write functions
- (``procedures'', in Scheme parlance) that return a package based on some
- parameters. For example, consider the @code{luasocket} library for the
- Lua programming language. We want to create @code{luasocket} packages
- for major versions of Lua. One way to do that is to define a procedure
- that takes a Lua package and returns a @code{luasocket} package that
- depends on it:
- @lisp
- (define (make-lua-socket name lua)
- ;; Return a luasocket package built with LUA.
- (package
- (name name)
- (version "3.0")
- ;; several fields omitted
- (inputs (list lua))
- (synopsis "Socket library for Lua")))
- (define-public lua5.1-socket
- (make-lua-socket "lua5.1-socket" lua-5.1))
- (define-public lua5.2-socket
- (make-lua-socket "lua5.2-socket" lua-5.2))
- @end lisp
- Here we have defined packages @code{lua5.1-socket} and
- @code{lua5.2-socket} by calling @code{make-lua-socket} with different
- arguments. @xref{Procedures,,, guile, GNU Guile Reference Manual}, for
- more info on procedures. Having top-level public definitions for these
- two packages means that they can be referred to from the command line
- (@pxref{Package Modules}).
- @cindex package transformations
- These are pretty simple package variants. As a convenience, the
- @code{(guix transformations)} module provides a high-level interface
- that directly maps to the more sophisticated package transformation
- options (@pxref{Package Transformation Options}):
- @deffn {Scheme Procedure} options->transformation @var{opts}
- Return a procedure that, when passed an object to build (package,
- derivation, etc.), applies the transformations specified by @var{opts} and returns
- the resulting objects. @var{opts} must be a list of symbol/string pairs such as:
- @lisp
- ((with-branch . "guile-gcrypt=master")
- (without-tests . "libgcrypt"))
- @end lisp
- Each symbol names a transformation and the corresponding string is an argument
- to that transformation.
- @end deffn
- For instance, a manifest equivalent to this command:
- @example
- guix build guix \
- --with-branch=guile-gcrypt=master \
- --with-debug-info=zlib
- @end example
- @noindent
- ... would look like this:
- @lisp
- (use-modules (guix transformations))
- (define transform
- ;; The package transformation procedure.
- (options->transformation
- '((with-branch . "guile-gcrypt=master")
- (with-debug-info . "zlib"))))
- (packages->manifest
- (list (transform (specification->package "guix"))))
- @end lisp
- @cindex input rewriting
- @cindex dependency graph rewriting
- The @code{options->transformation} procedure is convenient, but it's
- perhaps also not as flexible as you may like. How is it implemented?
- The astute reader probably noticed that most package transformation
- options go beyond the superficial changes shown in the first examples of
- this section: they involve @dfn{input rewriting}, whereby the dependency
- graph of a package is rewritten by replacing specific inputs by others.
- Dependency graph rewriting, for the purposes of swapping packages in the
- graph, is what the @code{package-input-rewriting} procedure in
- @code{(guix packages)} implements.
- @deffn {Scheme Procedure} package-input-rewriting @var{replacements} @
- [@var{rewrite-name}] [#:deep? #t]
- Return a procedure that, when passed a package, replaces its direct and
- indirect dependencies, including implicit inputs when @var{deep?} is
- true, according to @var{replacements}. @var{replacements} is a list of
- package pairs; the first element of each pair is the package to replace,
- and the second one is the replacement.
- Optionally, @var{rewrite-name} is a one-argument procedure that takes
- the name of a package and returns its new name after rewrite.
- @end deffn
- @noindent
- Consider this example:
- @lisp
- (define libressl-instead-of-openssl
- ;; This is a procedure to replace OPENSSL by LIBRESSL,
- ;; recursively.
- (package-input-rewriting `((,openssl . ,libressl))))
- (define git-with-libressl
- (libressl-instead-of-openssl git))
- @end lisp
- @noindent
- Here we first define a rewriting procedure that replaces @var{openssl}
- with @var{libressl}. Then we use it to define a @dfn{variant} of the
- @var{git} package that uses @var{libressl} instead of @var{openssl}.
- This is exactly what the @option{--with-input} command-line option does
- (@pxref{Package Transformation Options, @option{--with-input}}).
- The following variant of @code{package-input-rewriting} can match packages to
- be replaced by name rather than by identity.
- @deffn {Scheme Procedure} package-input-rewriting/spec @var{replacements} [#:deep? #t]
- Return a procedure that, given a package, applies the given
- @var{replacements} to all the package graph, including implicit inputs
- unless @var{deep?} is false. @var{replacements} is a list of
- spec/procedures pair; each spec is a package specification such as
- @code{"gcc"} or @code{"guile@@2"}, and each procedure takes a matching
- package and returns a replacement for that package.
- @end deffn
- The example above could be rewritten this way:
- @lisp
- (define libressl-instead-of-openssl
- ;; Replace all the packages called "openssl" with LibreSSL.
- (package-input-rewriting/spec `(("openssl" . ,(const libressl)))))
- @end lisp
- The key difference here is that, this time, packages are matched by spec and
- not by identity. In other words, any package in the graph that is called
- @code{openssl} will be replaced.
- A more generic procedure to rewrite a package dependency graph is
- @code{package-mapping}: it supports arbitrary changes to nodes in the
- graph.
- @deffn {Scheme Procedure} package-mapping @var{proc} [@var{cut?}] [#:deep? #f]
- Return a procedure that, given a package, applies @var{proc} to all the packages
- depended on and returns the resulting package. The procedure stops recursion
- when @var{cut?} returns true for a given package. When @var{deep?} is true, @var{proc} is
- applied to implicit inputs as well.
- @end deffn
- @node Build Systems
- @section Build Systems
- @cindex build system
- Each package definition specifies a @dfn{build system} and arguments for
- that build system (@pxref{Defining Packages}). This @code{build-system}
- field represents the build procedure of the package, as well as implicit
- dependencies of that build procedure.
- Build systems are @code{<build-system>} objects. The interface to
- create and manipulate them is provided by the @code{(guix build-system)}
- module, and actual build systems are exported by specific modules.
- @cindex bag (low-level package representation)
- Under the hood, build systems first compile package objects to
- @dfn{bags}. A @dfn{bag} is like a package, but with less
- ornamentation---in other words, a bag is a lower-level representation of
- a package, which includes all the inputs of that package, including some
- that were implicitly added by the build system. This intermediate
- representation is then compiled to a derivation (@pxref{Derivations}).
- The @code{package-with-c-toolchain} is an example of a way to change the
- implicit inputs that a package's build system pulls in (@pxref{package
- Reference, @code{package-with-c-toolchain}}).
- Build systems accept an optional list of @dfn{arguments}. In package
- definitions, these are passed @i{via} the @code{arguments} field
- (@pxref{Defining Packages}). They are typically keyword arguments
- (@pxref{Optional Arguments, keyword arguments in Guile,, guile, GNU
- Guile Reference Manual}). The value of these arguments is usually
- evaluated in the @dfn{build stratum}---i.e., by a Guile process launched
- by the daemon (@pxref{Derivations}).
- The main build system is @code{gnu-build-system}, which implements the
- standard build procedure for GNU and many other packages. It
- is provided by the @code{(guix build-system gnu)} module.
- @defvr {Scheme Variable} gnu-build-system
- @code{gnu-build-system} represents the GNU Build System, and variants
- thereof (@pxref{Configuration, configuration and makefile conventions,,
- standards, GNU Coding Standards}).
- @cindex build phases
- In a nutshell, packages using it are configured, built, and installed with
- the usual @code{./configure && make && make check && make install}
- command sequence. In practice, a few additional steps are often needed.
- All these steps are split up in separate @dfn{phases}.
- @xref{Build Phases}, for more info on build phases and ways to customize
- them.
- In addition, this build system ensures that the ``standard'' environment
- for GNU packages is available. This includes tools such as GCC, libc,
- Coreutils, Bash, Make, Diffutils, grep, and sed (see the @code{(guix
- build-system gnu)} module for a complete list). We call these the
- @dfn{implicit inputs} of a package, because package definitions do not
- have to mention them.
- This build system supports a number of keyword arguments, which can be
- passed @i{via} the @code{arguments} field of a package. Here are some
- of the main parameters:
- @table @code
- @item #:phases
- This argument specifies build-side code that evaluates to an alist of
- build phases. @xref{Build Phases}, for more information.
- @item #:configure-flags
- This is a list of flags (strings) passed to the @command{configure}
- script. @xref{Defining Packages}, for an example.
- @item #:make-flags
- This list of strings contains flags passed as arguments to
- @command{make} invocations in the @code{build}, @code{check}, and
- @code{install} phases.
- @item #:out-of-source?
- This Boolean, @code{#f} by default, indicates whether to run builds in a
- build directory separate from the source tree.
- When it is true, the @code{configure} phase creates a separate build
- directory, changes to that directory, and runs the @code{configure}
- script from there. This is useful for packages that require it, such as
- @code{glibc}.
- @item #:tests?
- This Boolean, @code{#t} by default, indicates whether the @code{check}
- phase should run the package's test suite.
- @item #:test-target
- This string, @code{"check"} by default, gives the name of the makefile
- target used by the @code{check} phase.
- @item #:parallel-build?
- @itemx #:parallel-tests?
- These Boolean values specify whether to build, respectively run the test
- suite, in parallel, with the @code{-j} flag of @command{make}. When
- they are true, @code{make} is passed @code{-j@var{n}}, where @var{n} is
- the number specified as the @option{--cores} option of
- @command{guix-daemon} or that of the @command{guix} client command
- (@pxref{Common Build Options, @option{--cores}}).
- @cindex RUNPATH, validation
- @item #:validate-runpath?
- This Boolean, @code{#t} by default, determines whether to ``validate''
- the @code{RUNPATH} of ELF binaries (@code{.so} shared libraries as well
- as executables) previously installed by the @code{install} phase.
- This validation step consists in making sure that all the shared
- libraries needed by an ELF binary, which are listed as
- @code{DT_NEEDED} entries in its @code{PT_DYNAMIC} segment, appear in the
- @code{DT_RUNPATH} entry of that binary. In other words, it ensures that
- running or using those binaries will not result in a ``file not found''
- error at run time. @xref{Options, @option{-rpath},, ld, The GNU
- Linker}, for more information on @code{RUNPATH}.
- @item #:substitutable?
- This Boolean, @code{#t} by default, tells whether the package outputs
- should be substitutable---i.e., whether users should be able to obtain
- substitutes for them instead of building locally (@pxref{Substitutes}).
- @item #:allowed-references
- @itemx #:disallowed-references
- When true, these arguments must be a list of dependencies that must not
- appear among the references of the build results. If, upon build
- completion, some of these references are retained, the build process
- fails.
- This is useful to ensure that a package does not erroneously keep a
- reference to some of it build-time inputs, in cases where doing so
- would, for example, unnecessarily increase its size (@pxref{Invoking
- guix size}).
- @end table
- Most other build systems support these keyword arguments.
- @end defvr
- Other @code{<build-system>} objects are defined to support other
- conventions and tools used by free software packages. They inherit most
- of @code{gnu-build-system}, and differ mainly in the set of inputs
- implicitly added to the build process, and in the list of phases
- executed. Some of these build systems are listed below.
- @defvr {Scheme Variable} ant-build-system
- This variable is exported by @code{(guix build-system ant)}. It
- implements the build procedure for Java packages that can be built with
- @url{https://ant.apache.org/, Ant build tool}.
- It adds both @code{ant} and the @dfn{Java Development Kit} (JDK) as
- provided by the @code{icedtea} package to the set of inputs. Different
- packages can be specified with the @code{#:ant} and @code{#:jdk}
- parameters, respectively.
- When the original package does not provide a suitable Ant build file,
- the parameter @code{#:jar-name} can be used to generate a minimal Ant
- build file @file{build.xml} with tasks to build the specified jar
- archive. In this case the parameter @code{#:source-dir} can be used to
- specify the source sub-directory, defaulting to ``src''.
- The @code{#:main-class} parameter can be used with the minimal ant
- buildfile to specify the main class of the resulting jar. This makes the
- jar file executable. The @code{#:test-include} parameter can be used to
- specify the list of junit tests to run. It defaults to
- @code{(list "**/*Test.java")}. The @code{#:test-exclude} can be used to
- disable some tests. It defaults to @code{(list "**/Abstract*.java")},
- because abstract classes cannot be run as tests.
- The parameter @code{#:build-target} can be used to specify the Ant task
- that should be run during the @code{build} phase. By default the
- ``jar'' task will be run.
- @end defvr
- @defvr {Scheme Variable} android-ndk-build-system
- @cindex Android distribution
- @cindex Android NDK build system
- This variable is exported by @code{(guix build-system android-ndk)}. It
- implements a build procedure for Android NDK (native development kit)
- packages using a Guix-specific build process.
- The build system assumes that packages install their public interface
- (header) files to the subdirectory @file{include} of the @code{out} output and
- their libraries to the subdirectory @file{lib} the @code{out} output.
- It's also assumed that the union of all the dependencies of a package
- has no conflicting files.
- For the time being, cross-compilation is not supported - so right now
- the libraries and header files are assumed to be host tools.
- @end defvr
- @defvr {Scheme Variable} asdf-build-system/source
- @defvrx {Scheme Variable} asdf-build-system/sbcl
- @defvrx {Scheme Variable} asdf-build-system/ecl
- These variables, exported by @code{(guix build-system asdf)}, implement
- build procedures for Common Lisp packages using
- @url{https://common-lisp.net/project/asdf/, ``ASDF''}. ASDF is a system
- definition facility for Common Lisp programs and libraries.
- The @code{asdf-build-system/source} system installs the packages in
- source form, and can be loaded using any common lisp implementation, via
- ASDF@. The others, such as @code{asdf-build-system/sbcl}, install binary
- systems in the format which a particular implementation understands.
- These build systems can also be used to produce executable programs, or
- lisp images which contain a set of packages pre-loaded.
- The build system uses naming conventions. For binary packages, the
- package name should be prefixed with the lisp implementation, such as
- @code{sbcl-} for @code{asdf-build-system/sbcl}.
- Additionally, the corresponding source package should be labeled using
- the same convention as python packages (see @ref{Python Modules}), using
- the @code{cl-} prefix.
- In order to create executable programs and images, the build-side
- procedures @code{build-program} and @code{build-image} can be used.
- They should be called in a build phase after the
- @code{create-asdf-configuration} phase, so that the system which was
- just built can be used within the resulting image. @code{build-program}
- requires a list of Common Lisp expressions to be passed as the
- @code{#:entry-program} argument.
- By default, all the @file{.asd} files present in the sources are read to
- find system definitions. The @code{#:asd-files} parameter can be used
- to specify the list of @file{.asd} files to read. Furthermore, if the
- package defines a system for its tests in a separate file, it will be
- loaded before the tests are run if it is specified by the
- @code{#:test-asd-file} parameter. If it is not set, the files
- @code{<system>-tests.asd}, @code{<system>-test.asd}, @code{tests.asd},
- and @code{test.asd} will be tried if they exist.
- If for some reason the package must be named in a different way than the
- naming conventions suggest, or if several systems must be compiled, the
- @code{#:asd-systems} parameter can be used to specify the list of system
- names.
- @end defvr
- @defvr {Scheme Variable} cargo-build-system
- @cindex Rust programming language
- @cindex Cargo (Rust build system)
- This variable is exported by @code{(guix build-system cargo)}. It
- supports builds of packages using Cargo, the build tool of the
- @uref{https://www.rust-lang.org, Rust programming language}.
- It adds @code{rustc} and @code{cargo} to the set of inputs.
- A different Rust package can be specified with the @code{#:rust} parameter.
- Regular cargo dependencies should be added to the package definition similarly
- to other packages; those needed only at build time to native-inputs, others to
- inputs. If you need to add source-only crates then you should add them to via
- the @code{#:cargo-inputs} parameter as a list of name and spec pairs, where the
- spec can be a package or a source definition. Note that the spec must
- evaluate to a path to a gzipped tarball which includes a @code{Cargo.toml}
- file at its root, or it will be ignored. Similarly, cargo dev-dependencies
- should be added to the package definition via the
- @code{#:cargo-development-inputs} parameter.
- In its @code{configure} phase, this build system will make any source inputs
- specified in the @code{#:cargo-inputs} and @code{#:cargo-development-inputs}
- parameters available to cargo. It will also remove an included
- @code{Cargo.lock} file to be recreated by @code{cargo} during the
- @code{build} phase. The @code{package} phase will run @code{cargo package}
- to create a source crate for future use. The @code{install} phase installs
- the binaries defined by the crate. Unless @code{install-source? #f} is
- defined it will also install a source crate repository of itself and unpacked
- sources, to ease in future hacking on rust packages.
- @end defvr
- @defvr {Scheme Variable} chicken-build-system
- This variable is exported by @code{(guix build-system chicken)}. It
- builds @uref{https://call-cc.org/, CHICKEN Scheme} modules, also called
- ``eggs'' or ``extensions''. CHICKEN generates C source code, which then
- gets compiled by a C compiler, in this case GCC.
- This build system adds @code{chicken} to the package inputs, as well as
- the packages of @code{gnu-build-system}.
- The build system can't (yet) deduce the egg's name automatically, so just like
- with @code{go-build-system} and its @code{#:import-path}, you should define
- @code{#:egg-name} in the package's @code{arguments} field.
- For example, if you are packaging the @code{srfi-1} egg:
- @lisp
- (arguments '(#:egg-name "srfi-1"))
- @end lisp
- Egg dependencies must be defined in @code{propagated-inputs}, not @code{inputs}
- because CHICKEN doesn't embed absolute references in compiled eggs.
- Test dependencies should go to @code{native-inputs}, as usual.
- @end defvr
- @defvr {Scheme Variable} copy-build-system
- This variable is exported by @code{(guix build-system copy)}. It
- supports builds of simple packages that don't require much compiling,
- mostly just moving files around.
- It adds much of the @code{gnu-build-system} packages to the set of
- inputs. Because of this, the @code{copy-build-system} does not require
- all the boilerplate code often needed for the
- @code{trivial-build-system}.
- To further simplify the file installation process, an
- @code{#:install-plan} argument is exposed to let the packager specify
- which files go where. The install plan is a list of @code{(@var{source}
- @var{target} [@var{filters}])}. @var{filters} are optional.
- @itemize
- @item When @var{source} matches a file or directory without trailing slash, install it to @var{target}.
- @itemize
- @item If @var{target} has a trailing slash, install @var{source} basename beneath @var{target}.
- @item Otherwise install @var{source} as @var{target}.
- @end itemize
- @item When @var{source} is a directory with a trailing slash, or when @var{filters} are used,
- the trailing slash of @var{target} is implied with the same meaning
- as above.
- @itemize
- @item Without @var{filters}, install the full @var{source} @emph{content} to @var{target}.
- @item With @var{filters} among @code{#:include}, @code{#:include-regexp}, @code{#:exclude},
- @code{#:exclude-regexp}, only select files are installed depending on
- the filters. Each filters is specified by a list of strings.
- @itemize
- @item With @code{#:include}, install all the files which the path suffix matches
- at least one of the elements in the given list.
- @item With @code{#:include-regexp}, install all the files which the
- subpaths match at least one of the regular expressions in the given
- list.
- @item The @code{#:exclude} and @code{#:exclude-regexp} filters
- are the complement of their inclusion counterpart. Without @code{#:include} flags,
- install all files but those matching the exclusion filters.
- If both inclusions and exclusions are specified, the exclusions are done
- on top of the inclusions.
- @end itemize
- @end itemize
- In all cases, the paths relative to @var{source} are preserved within
- @var{target}.
- @end itemize
- Examples:
- @itemize
- @item @code{("foo/bar" "share/my-app/")}: Install @file{bar} to @file{share/my-app/bar}.
- @item @code{("foo/bar" "share/my-app/baz")}: Install @file{bar} to @file{share/my-app/baz}.
- @item @code{("foo/" "share/my-app")}: Install the content of @file{foo} inside @file{share/my-app},
- e.g., install @file{foo/sub/file} to @file{share/my-app/sub/file}.
- @item @code{("foo/" "share/my-app" #:include ("sub/file"))}: Install only @file{foo/sub/file} to
- @file{share/my-app/sub/file}.
- @item @code{("foo/sub" "share/my-app" #:include ("file"))}: Install @file{foo/sub/file} to
- @file{share/my-app/file}.
- @end itemize
- @end defvr
- @cindex Clojure (programming language)
- @cindex simple Clojure build system
- @defvr {Scheme Variable} clojure-build-system
- This variable is exported by @code{(guix build-system clojure)}. It implements
- a simple build procedure for @uref{https://clojure.org/, Clojure} packages
- using plain old @code{compile} in Clojure. Cross-compilation is not supported
- yet.
- It adds @code{clojure}, @code{icedtea} and @code{zip} to the set of inputs.
- Different packages can be specified with the @code{#:clojure}, @code{#:jdk} and
- @code{#:zip} parameters, respectively.
- A list of source directories, test directories and jar names can be specified
- with the @code{#:source-dirs}, @code{#:test-dirs} and @code{#:jar-names}
- parameters, respectively. Compile directory and main class can be specified
- with the @code{#:compile-dir} and @code{#:main-class} parameters, respectively.
- Other parameters are documented below.
- This build system is an extension of @code{ant-build-system}, but with the
- following phases changed:
- @table @code
- @item build
- This phase calls @code{compile} in Clojure to compile source files and runs
- @command{jar} to create jars from both source files and compiled files
- according to the include list and exclude list specified in
- @code{#:aot-include} and @code{#:aot-exclude}, respectively. The exclude list
- has priority over the include list. These lists consist of symbols
- representing Clojure libraries or the special keyword @code{#:all} representing
- all Clojure libraries found under the source directories. The parameter
- @code{#:omit-source?} decides if source should be included into the jars.
- @item check
- This phase runs tests according to the include list and exclude list specified
- in @code{#:test-include} and @code{#:test-exclude}, respectively. Their
- meanings are analogous to that of @code{#:aot-include} and
- @code{#:aot-exclude}, except that the special keyword @code{#:all} now
- stands for all Clojure libraries found under the test directories. The
- parameter @code{#:tests?} decides if tests should be run.
- @item install
- This phase installs all jars built previously.
- @end table
- Apart from the above, this build system also contains an additional phase:
- @table @code
- @item install-doc
- This phase installs all top-level files with base name matching
- @code{%doc-regex}. A different regex can be specified with the
- @code{#:doc-regex} parameter. All files (recursively) inside the documentation
- directories specified in @code{#:doc-dirs} are installed as well.
- @end table
- @end defvr
- @defvr {Scheme Variable} cmake-build-system
- This variable is exported by @code{(guix build-system cmake)}. It
- implements the build procedure for packages using the
- @url{https://www.cmake.org, CMake build tool}.
- It automatically adds the @code{cmake} package to the set of inputs.
- Which package is used can be specified with the @code{#:cmake}
- parameter.
- The @code{#:configure-flags} parameter is taken as a list of flags
- passed to the @command{cmake} command. The @code{#:build-type}
- parameter specifies in abstract terms the flags passed to the compiler;
- it defaults to @code{"RelWithDebInfo"} (short for ``release mode with
- debugging information''), which roughly means that code is compiled with
- @code{-O2 -g}, as is the case for Autoconf-based packages by default.
- @end defvr
- @defvr {Scheme Variable} dune-build-system
- This variable is exported by @code{(guix build-system dune)}. It
- supports builds of packages using @uref{https://dune.build/, Dune}, a build
- tool for the OCaml programming language. It is implemented as an extension
- of the @code{ocaml-build-system} which is described below. As such, the
- @code{#:ocaml} and @code{#:findlib} parameters can be passed to this build
- system.
- It automatically adds the @code{dune} package to the set of inputs.
- Which package is used can be specified with the @code{#:dune}
- parameter.
- There is no @code{configure} phase because dune packages typically don't
- need to be configured. The @code{#:build-flags} parameter is taken as a
- list of flags passed to the @code{dune} command during the build.
- The @code{#:jbuild?} parameter can be passed to use the @code{jbuild}
- command instead of the more recent @code{dune} command while building
- a package. Its default value is @code{#f}.
- The @code{#:package} parameter can be passed to specify a package name, which
- is useful when a package contains multiple packages and you want to build
- only one of them. This is equivalent to passing the @code{-p} argument to
- @code{dune}.
- @end defvr
- @defvr {Scheme Variable} go-build-system
- This variable is exported by @code{(guix build-system go)}. It
- implements a build procedure for Go packages using the standard
- @url{https://golang.org/cmd/go/#hdr-Compile_packages_and_dependencies,
- Go build mechanisms}.
- The user is expected to provide a value for the key @code{#:import-path}
- and, in some cases, @code{#:unpack-path}. The
- @url{https://golang.org/doc/code.html#ImportPaths, import path}
- corresponds to the file system path expected by the package's build
- scripts and any referring packages, and provides a unique way to
- refer to a Go package. It is typically based on a combination of the
- package source code's remote URI and file system hierarchy structure. In
- some cases, you will need to unpack the package's source code to a
- different directory structure than the one indicated by the import path,
- and @code{#:unpack-path} should be used in such cases.
- Packages that provide Go libraries should install their source code into
- the built output. The key @code{#:install-source?}, which defaults to
- @code{#t}, controls whether or not the source code is installed. It can
- be set to @code{#f} for packages that only provide executable files.
- Packages can be cross-built, and if a specific architecture or operating
- system is desired then the keywords @code{#:goarch} and @code{#:goos}
- can be used to force the package to be built for that architecture and
- operating system. The combinations known to Go can be found
- @url{"https://golang.org/doc/install/source#environment", in their
- documentation}.
- @end defvr
- @defvr {Scheme Variable} glib-or-gtk-build-system
- This variable is exported by @code{(guix build-system glib-or-gtk)}. It
- is intended for use with packages making use of GLib or GTK+.
- This build system adds the following two phases to the ones defined by
- @code{gnu-build-system}:
- @table @code
- @item glib-or-gtk-wrap
- The phase @code{glib-or-gtk-wrap} ensures that programs in
- @file{bin/} are able to find GLib ``schemas'' and
- @uref{https://developer.gnome.org/gtk3/stable/gtk-running.html, GTK+
- modules}. This is achieved by wrapping the programs in launch scripts
- that appropriately set the @env{XDG_DATA_DIRS} and @env{GTK_PATH}
- environment variables.
- It is possible to exclude specific package outputs from that wrapping
- process by listing their names in the
- @code{#:glib-or-gtk-wrap-excluded-outputs} parameter. This is useful
- when an output is known not to contain any GLib or GTK+ binaries, and
- where wrapping would gratuitously add a dependency of that output on
- GLib and GTK+.
- @item glib-or-gtk-compile-schemas
- The phase @code{glib-or-gtk-compile-schemas} makes sure that all
- @uref{https://developer.gnome.org/gio/stable/glib-compile-schemas.html,
- GSettings schemas} of GLib are compiled. Compilation is performed by the
- @command{glib-compile-schemas} program. It is provided by the package
- @code{glib:bin} which is automatically imported by the build system.
- The @code{glib} package providing @command{glib-compile-schemas} can be
- specified with the @code{#:glib} parameter.
- @end table
- Both phases are executed after the @code{install} phase.
- @end defvr
- @defvr {Scheme Variable} guile-build-system
- This build system is for Guile packages that consist exclusively of Scheme
- code and that are so lean that they don't even have a makefile, let alone a
- @file{configure} script. It compiles Scheme code using @command{guild
- compile} (@pxref{Compilation,,, guile, GNU Guile Reference Manual}) and
- installs the @file{.scm} and @file{.go} files in the right place. It also
- installs documentation.
- This build system supports cross-compilation by using the
- @option{--target} option of @samp{guild compile}.
- Packages built with @code{guile-build-system} must provide a Guile package in
- their @code{native-inputs} field.
- @end defvr
- @defvr {Scheme Variable} julia-build-system
- This variable is exported by @code{(guix build-system julia)}. It
- implements the build procedure used by @uref{https://julialang.org/,
- julia} packages, which essentially is similar to running @samp{julia -e
- 'using Pkg; Pkg.add(package)'} in an environment where
- @env{JULIA_LOAD_PATH} contains the paths to all Julia package inputs.
- Tests are run by calling @code{/test/runtests.jl}.
- The Julia package name and uuid is read from the file
- @file{Project.toml}. These values can be overridden by passing the
- argument @code{#:julia-package-name} (which must be correctly
- capitalized) or @code{#:julia-package-uuid}.
- Julia packages usually manage their binary dependencies via
- @code{JLLWrappers.jl}, a Julia package that creates a module (named
- after the wrapped library followed by @code{_jll.jl}.
- To add the binary path @code{_jll.jl} packages, you need to patch the
- files under @file{src/wrappers/}, replacing the call to the macro
- @code{JLLWrappers.@@generate_wrapper_header}, adding as a second
- argument containing the store path the binary.
- As an example, in the MbedTLS Julia package, we add a build phase
- (@pxref{Build Phases}) to insert the absolute file name of the wrapped
- MbedTLS package:
- @lisp
- (add-after 'unpack 'override-binary-path
- (lambda* (#:key inputs #:allow-other-keys)
- (for-each (lambda (wrapper)
- (substitute* wrapper
- (("generate_wrapper_header.*")
- (string-append
- "generate_wrapper_header(\"MbedTLS\", \""
- (assoc-ref inputs "mbedtls-apache") "\")\n"))))
- ;; There's a Julia file for each platform, override them all.
- (find-files "src/wrappers/" "\\.jl$"))))
- @end lisp
- Some older packages that aren't using @file{Project.toml} yet, will
- require this file to be created, too. It is internally done if the
- arguments @code{#:julia-package-name} and @code{#:julia-package-uuid}
- are provided.
- @end defvr
- @defvr {Scheme Variable} maven-build-system
- This variable is exported by @code{(guix build-system maven)}. It implements
- a build procedure for @uref{https://maven.apache.org, Maven} packages. Maven
- is a dependency and lifecycle management tool for Java. A user of Maven
- specifies dependencies and plugins in a @file{pom.xml} file that Maven reads.
- When Maven does not have one of the dependencies or plugins in its repository,
- it will download them and use them to build the package.
- The maven build system ensures that maven will not try to download any
- dependency by running in offline mode. Maven will fail if a dependency is
- missing. Before running Maven, the @file{pom.xml} (and subprojects) are
- modified to specify the version of dependencies and plugins that match the
- versions available in the guix build environment. Dependencies and plugins
- must be installed in the fake maven repository at @file{lib/m2}, and are
- symlinked into a proper repository before maven is run. Maven is instructed
- to use that repository for the build and installs built artifacts there.
- Changed files are copied to the @file{lib/m2} directory of the package output.
- You can specify a @file{pom.xml} file with the @code{#:pom-file} argument,
- or let the build system use the default @file{pom.xml} file in the sources.
- In case you need to specify a dependency's version manually, you can use the
- @code{#:local-packages} argument. It takes an association list where the key
- is the groupId of the package and its value is an association list where the
- key is the artifactId of the package and its value is the version you want to
- override in the @file{pom.xml}.
- Some packages use dependencies or plugins that are not useful at runtime nor
- at build time in Guix. You can alter the @file{pom.xml} file to remove them
- using the @code{#:exclude} argument. Its value is an association list where
- the key is the groupId of the plugin or dependency you want to remove, and
- the value is a list of artifactId you want to remove.
- You can override the default @code{jdk} and @code{maven} packages with the
- corresponding argument, @code{#:jdk} and @code{#:maven}.
- The @code{#:maven-plugins} argument is a list of maven plugins used during
- the build, with the same format as the @code{inputs} fields of the package
- declaration. Its default value is @code{(default-maven-plugins)} which is
- also exported.
- @end defvr
- @defvr {Scheme Variable} minetest-mod-build-system
- This variable is exported by @code{(guix build-system minetest)}. It
- implements a build procedure for @uref{https://www.minetest.net, Minetest}
- mods, which consists of copying Lua code, images and other resources to
- the location Minetest searches for mods. The build system also minimises
- PNG images and verifies that Minetest can load the mod without errors.
- @end defvr
- @defvr {Scheme Variable} minify-build-system
- This variable is exported by @code{(guix build-system minify)}. It
- implements a minification procedure for simple JavaScript packages.
- It adds @code{uglify-js} to the set of inputs and uses it to compress
- all JavaScript files in the @file{src} directory. A different minifier
- package can be specified with the @code{#:uglify-js} parameter, but it
- is expected that the package writes the minified code to the standard
- output.
- When the input JavaScript files are not all located in the @file{src}
- directory, the parameter @code{#:javascript-files} can be used to
- specify a list of file names to feed to the minifier.
- @end defvr
- @defvr {Scheme Variable} ocaml-build-system
- This variable is exported by @code{(guix build-system ocaml)}. It implements
- a build procedure for @uref{https://ocaml.org, OCaml} packages, which consists
- of choosing the correct set of commands to run for each package. OCaml
- packages can expect many different commands to be run. This build system will
- try some of them.
- When the package has a @file{setup.ml} file present at the top-level, it will
- run @code{ocaml setup.ml -configure}, @code{ocaml setup.ml -build} and
- @code{ocaml setup.ml -install}. The build system will assume that this file
- was generated by @uref{http://oasis.forge.ocamlcore.org/, OASIS} and will take
- care of setting the prefix and enabling tests if they are not disabled. You
- can pass configure and build flags with the @code{#:configure-flags} and
- @code{#:build-flags}. The @code{#:test-flags} key can be passed to change the
- set of flags used to enable tests. The @code{#:use-make?} key can be used to
- bypass this system in the build and install phases.
- When the package has a @file{configure} file, it is assumed that it is a
- hand-made configure script that requires a different argument format than
- in the @code{gnu-build-system}. You can add more flags with the
- @code{#:configure-flags} key.
- When the package has a @file{Makefile} file (or @code{#:use-make?} is
- @code{#t}), it will be used and more flags can be passed to the build and
- install phases with the @code{#:make-flags} key.
- Finally, some packages do not have these files and use a somewhat standard
- location for its build system. In that case, the build system will run
- @code{ocaml pkg/pkg.ml} or @code{ocaml pkg/build.ml} and take care of
- providing the path to the required findlib module. Additional flags can
- be passed via the @code{#:build-flags} key. Install is taken care of by
- @command{opam-installer}. In this case, the @code{opam} package must
- be added to the @code{native-inputs} field of the package definition.
- Note that most OCaml packages assume they will be installed in the same
- directory as OCaml, which is not what we want in guix. In particular, they
- will install @file{.so} files in their module's directory, which is usually
- fine because it is in the OCaml compiler directory. In guix though, these
- libraries cannot be found and we use @env{CAML_LD_LIBRARY_PATH}. This
- variable points to @file{lib/ocaml/site-lib/stubslibs} and this is where
- @file{.so} libraries should be installed.
- @end defvr
- @defvr {Scheme Variable} python-build-system
- This variable is exported by @code{(guix build-system python)}. It
- implements the more or less standard build procedure used by Python
- packages, which consists in running @code{python setup.py build} and
- then @code{python setup.py install --prefix=/gnu/store/@dots{}}.
- For packages that install stand-alone Python programs under @code{bin/},
- it takes care of wrapping these programs so that their
- @env{GUIX_PYTHONPATH} environment variable points to all the Python
- libraries they depend on.
- Which Python package is used to perform the build can be specified with
- the @code{#:python} parameter. This is a useful way to force a package
- to be built for a specific version of the Python interpreter, which
- might be necessary if the package is only compatible with a single
- interpreter version.
- By default guix calls @code{setup.py} under control of
- @code{setuptools}, much like @command{pip} does. Some packages are not
- compatible with setuptools (and pip), thus you can disable this by
- setting the @code{#:use-setuptools?} parameter to @code{#f}.
- If a @code{"python"} output is available, the package is installed into it
- instead of the default @code{"out"} output. This is useful for packages that
- include a Python package as only a part of the software, and thus want to
- combine the phases of @code{python-build-system} with another build system.
- Python bindings are a common usecase.
- @end defvr
- @defvr {Scheme Variable} perl-build-system
- This variable is exported by @code{(guix build-system perl)}. It
- implements the standard build procedure for Perl packages, which either
- consists in running @code{perl Build.PL --prefix=/gnu/store/@dots{}},
- followed by @code{Build} and @code{Build install}; or in running
- @code{perl Makefile.PL PREFIX=/gnu/store/@dots{}}, followed by
- @code{make} and @code{make install}, depending on which of
- @code{Build.PL} or @code{Makefile.PL} is present in the package
- distribution. Preference is given to the former if both @code{Build.PL}
- and @code{Makefile.PL} exist in the package distribution. This
- preference can be reversed by specifying @code{#t} for the
- @code{#:make-maker?} parameter.
- The initial @code{perl Makefile.PL} or @code{perl Build.PL} invocation
- passes flags specified by the @code{#:make-maker-flags} or
- @code{#:module-build-flags} parameter, respectively.
- Which Perl package is used can be specified with @code{#:perl}.
- @end defvr
- @defvr {Scheme Variable} renpy-build-system
- This variable is exported by @code{(guix build-system renpy)}. It implements
- the more or less standard build procedure used by Ren'py games, which consists
- of loading @code{#:game} once, thereby creating bytecode for it.
- It further creates a wrapper script in @code{bin/} and a desktop entry in
- @code{share/applications}, both of which can be used to launch the game.
- Which Ren'py package is used can be specified with @code{#:renpy}.
- Games can also be installed in outputs other than ``out'' by using
- @code{#:output}.
- @end defvr
- @defvr {Scheme Variable} qt-build-system
- This variable is exported by @code{(guix build-system qt)}. It
- is intended for use with applications using Qt or KDE.
- This build system adds the following two phases to the ones defined by
- @code{cmake-build-system}:
- @table @code
- @item check-setup
- The phase @code{check-setup} prepares the environment for running
- the checks as commonly used by Qt test programs.
- For now this only sets some environment variables:
- @code{QT_QPA_PLATFORM=offscreen},
- @code{DBUS_FATAL_WARNINGS=0} and
- @code{CTEST_OUTPUT_ON_FAILURE=1}.
- This phase is added before the @code{check} phase.
- It's a separate phase to ease adjusting if necessary.
- @item qt-wrap
- The phase @code{qt-wrap}
- searches for Qt5 plugin paths, QML paths and some XDG in the inputs
- and output. In case some path is found, all programs in the output's
- @file{bin/}, @file{sbin/}, @file{libexec/} and @file{lib/libexec/} directories
- are wrapped in scripts defining the necessary environment variables.
- It is possible to exclude specific package outputs from that wrapping process
- by listing their names in the @code{#:qt-wrap-excluded-outputs} parameter.
- This is useful when an output is known not to contain any Qt binaries, and
- where wrapping would gratuitously add a dependency of that output on Qt, KDE,
- or such.
- This phase is added after the @code{install} phase.
- @end table
- @end defvr
- @defvr {Scheme Variable} r-build-system
- This variable is exported by @code{(guix build-system r)}. It
- implements the build procedure used by @uref{https://r-project.org, R}
- packages, which essentially is little more than running @samp{R CMD
- INSTALL --library=/gnu/store/@dots{}} in an environment where
- @env{R_LIBS_SITE} contains the paths to all R package inputs. Tests are
- run after installation using the R function
- @code{tools::testInstalledPackage}.
- @end defvr
- @defvr {Scheme Variable} rakudo-build-system
- This variable is exported by @code{(guix build-system rakudo)}. It
- implements the build procedure used by @uref{https://rakudo.org/,
- Rakudo} for @uref{https://perl6.org/, Perl6} packages. It installs the
- package to @code{/gnu/store/@dots{}/NAME-VERSION/share/perl6} and
- installs the binaries, library files and the resources, as well as wrap
- the files under the @code{bin/} directory. Tests can be skipped by
- passing @code{#f} to the @code{tests?} parameter.
- Which rakudo package is used can be specified with @code{rakudo}.
- Which perl6-tap-harness package used for the tests can be specified with
- @code{#:prove6} or removed by passing @code{#f} to the
- @code{with-prove6?} parameter.
- Which perl6-zef package used for tests and installing can be specified
- with @code{#:zef} or removed by passing @code{#f} to the
- @code{with-zef?} parameter.
- @end defvr
- @defvr {Scheme Variable} texlive-build-system
- This variable is exported by @code{(guix build-system texlive)}. It is
- used to build TeX packages in batch mode with a specified engine. The
- build system sets the @env{TEXINPUTS} variable to find all TeX source
- files in the inputs.
- By default it runs @code{luatex} on all files ending on @code{ins}. A
- different engine and format can be specified with the
- @code{#:tex-format} argument. Different build targets can be specified
- with the @code{#:build-targets} argument, which expects a list of file
- names. The build system adds only @code{texlive-bin} and
- @code{texlive-latex-base} (both from @code{(gnu packages tex}) to the
- inputs. Both can be overridden with the arguments @code{#:texlive-bin}
- and @code{#:texlive-latex-base}, respectively.
- The @code{#:tex-directory} parameter tells the build system where to
- install the built files under the texmf tree.
- @end defvr
- @defvr {Scheme Variable} ruby-build-system
- This variable is exported by @code{(guix build-system ruby)}. It
- implements the RubyGems build procedure used by Ruby packages, which
- involves running @code{gem build} followed by @code{gem install}.
- The @code{source} field of a package that uses this build system
- typically references a gem archive, since this is the format that Ruby
- developers use when releasing their software. The build system unpacks
- the gem archive, potentially patches the source, runs the test suite,
- repackages the gem, and installs it. Additionally, directories and
- tarballs may be referenced to allow building unreleased gems from Git or
- a traditional source release tarball.
- Which Ruby package is used can be specified with the @code{#:ruby}
- parameter. A list of additional flags to be passed to the @command{gem}
- command can be specified with the @code{#:gem-flags} parameter.
- @end defvr
- @defvr {Scheme Variable} waf-build-system
- This variable is exported by @code{(guix build-system waf)}. It
- implements a build procedure around the @code{waf} script. The common
- phases---@code{configure}, @code{build}, and @code{install}---are
- implemented by passing their names as arguments to the @code{waf}
- script.
- The @code{waf} script is executed by the Python interpreter. Which
- Python package is used to run the script can be specified with the
- @code{#:python} parameter.
- @end defvr
- @defvr {Scheme Variable} scons-build-system
- This variable is exported by @code{(guix build-system scons)}. It
- implements the build procedure used by the SCons software construction
- tool. This build system runs @code{scons} to build the package,
- @code{scons test} to run tests, and then @code{scons install} to install
- the package.
- Additional flags to be passed to @code{scons} can be specified with the
- @code{#:scons-flags} parameter. The default build and install targets
- can be overridden with @code{#:build-targets} and
- @code{#:install-targets} respectively. The version of Python used to
- run SCons can be specified by selecting the appropriate SCons package
- with the @code{#:scons} parameter.
- @end defvr
- @defvr {Scheme Variable} haskell-build-system
- This variable is exported by @code{(guix build-system haskell)}. It
- implements the Cabal build procedure used by Haskell packages, which
- involves running @code{runhaskell Setup.hs configure
- --prefix=/gnu/store/@dots{}} and @code{runhaskell Setup.hs build}.
- Instead of installing the package by running @code{runhaskell Setup.hs
- install}, to avoid trying to register libraries in the read-only
- compiler store directory, the build system uses @code{runhaskell
- Setup.hs copy}, followed by @code{runhaskell Setup.hs register}. In
- addition, the build system generates the package documentation by
- running @code{runhaskell Setup.hs haddock}, unless @code{#:haddock? #f}
- is passed. Optional Haddock parameters can be passed with the help of
- the @code{#:haddock-flags} parameter. If the file @code{Setup.hs} is
- not found, the build system looks for @code{Setup.lhs} instead.
- Which Haskell compiler is used can be specified with the @code{#:haskell}
- parameter which defaults to @code{ghc}.
- @end defvr
- @defvr {Scheme Variable} dub-build-system
- This variable is exported by @code{(guix build-system dub)}. It
- implements the Dub build procedure used by D packages, which
- involves running @code{dub build} and @code{dub run}.
- Installation is done by copying the files manually.
- Which D compiler is used can be specified with the @code{#:ldc}
- parameter which defaults to @code{ldc}.
- @end defvr
- @anchor{emacs-build-system}
- @defvr {Scheme Variable} emacs-build-system
- This variable is exported by @code{(guix build-system emacs)}. It
- implements an installation procedure similar to the packaging system
- of Emacs itself (@pxref{Packages,,, emacs, The GNU Emacs Manual}).
- It first creates the @code{@code{package}-autoloads.el} file, then it
- byte compiles all Emacs Lisp files. Differently from the Emacs
- packaging system, the Info documentation files are moved to the standard
- documentation directory and the @file{dir} file is deleted. The Elisp
- package files are installed directly under @file{share/emacs/site-lisp}.
- @end defvr
- @defvr {Scheme Variable} font-build-system
- This variable is exported by @code{(guix build-system font)}. It
- implements an installation procedure for font packages where upstream
- provides pre-compiled TrueType, OpenType, etc.@: font files that merely
- need to be copied into place. It copies font files to standard
- locations in the output directory.
- @end defvr
- @defvr {Scheme Variable} meson-build-system
- This variable is exported by @code{(guix build-system meson)}. It
- implements the build procedure for packages that use
- @url{https://mesonbuild.com, Meson} as their build system.
- It adds both Meson and @uref{https://ninja-build.org/, Ninja} to the set
- of inputs, and they can be changed with the parameters @code{#:meson}
- and @code{#:ninja} if needed.
- This build system is an extension of @code{gnu-build-system}, but with the
- following phases changed to some specific for Meson:
- @table @code
- @item configure
- The phase runs @code{meson} with the flags specified in
- @code{#:configure-flags}. The flag @option{--buildtype} is always set to
- @code{debugoptimized} unless something else is specified in
- @code{#:build-type}.
- @item build
- The phase runs @code{ninja} to build the package in parallel by default, but
- this can be changed with @code{#:parallel-build?}.
- @item check
- The phase runs @samp{meson test} with a base set of options that cannot
- be overridden. This base set of options can be extended via the
- @code{#:test-options} argument, for example to select or skip a specific
- test suite.
- @item install
- The phase runs @code{ninja install} and can not be changed.
- @end table
- Apart from that, the build system also adds the following phases:
- @table @code
- @item fix-runpath
- This phase ensures that all binaries can find the libraries they need.
- It searches for required libraries in subdirectories of the package
- being built, and adds those to @code{RUNPATH} where needed. It also
- removes references to libraries left over from the build phase by
- @code{meson}, such as test dependencies, that aren't actually required
- for the program to run.
- @item glib-or-gtk-wrap
- This phase is the phase provided by @code{glib-or-gtk-build-system}, and it
- is not enabled by default. It can be enabled with @code{#:glib-or-gtk?}.
- @item glib-or-gtk-compile-schemas
- This phase is the phase provided by @code{glib-or-gtk-build-system}, and it
- is not enabled by default. It can be enabled with @code{#:glib-or-gtk?}.
- @end table
- @end defvr
- @defvr {Scheme Variable} linux-module-build-system
- @code{linux-module-build-system} allows building Linux kernel modules.
- @cindex build phases
- This build system is an extension of @code{gnu-build-system}, but with the
- following phases changed:
- @table @code
- @item configure
- This phase configures the environment so that the Linux kernel's Makefile
- can be used to build the external kernel module.
- @item build
- This phase uses the Linux kernel's Makefile in order to build the external
- kernel module.
- @item install
- This phase uses the Linux kernel's Makefile in order to install the external
- kernel module.
- @end table
- It is possible and useful to specify the Linux kernel to use for building
- the module (in the @code{arguments} form of a package using the
- @code{linux-module-build-system}, use the key @code{#:linux} to specify it).
- @end defvr
- @defvr {Scheme Variable} node-build-system
- This variable is exported by @code{(guix build-system node)}. It
- implements the build procedure used by @uref{https://nodejs.org,
- Node.js}, which implements an approximation of the @code{npm install}
- command, followed by an @code{npm test} command.
- Which Node.js package is used to interpret the @code{npm} commands can
- be specified with the @code{#:node} parameter which defaults to
- @code{node}.
- @end defvr
- Lastly, for packages that do not need anything as sophisticated, a
- ``trivial'' build system is provided. It is trivial in the sense that
- it provides basically no support: it does not pull any implicit inputs,
- and does not have a notion of build phases.
- @defvr {Scheme Variable} trivial-build-system
- This variable is exported by @code{(guix build-system trivial)}.
- This build system requires a @code{#:builder} argument. This argument
- must be a Scheme expression that builds the package output(s)---as
- with @code{build-expression->derivation} (@pxref{Derivations,
- @code{build-expression->derivation}}).
- @end defvr
- @node Build Phases
- @section Build Phases
- @cindex build phases, for packages
- Almost all package build systems implement a notion @dfn{build phases}:
- a sequence of actions that the build system executes, when you build the
- package, leading to the installed byproducts in the store. A notable
- exception is the ``bare-bones'' @code{trivial-build-system}
- (@pxref{Build Systems}).
- As discussed in the previous section, those build systems provide a
- standard list of phases. For @code{gnu-build-system}, the main build
- phases are the following:
- @table @code
- @item set-paths
- Define search path environment variables for all the input packages,
- including @env{PATH} (@pxref{Search Paths}).
- @item unpack
- Unpack the source tarball, and change the current directory to the
- extracted source tree. If the source is actually a directory, copy it
- to the build tree, and enter that directory.
- @item patch-source-shebangs
- Patch shebangs encountered in source files so they refer to the right
- store file names. For instance, this changes @code{#!/bin/sh} to
- @code{#!/gnu/store/@dots{}-bash-4.3/bin/sh}.
- @item configure
- Run the @file{configure} script with a number of default options, such
- as @option{--prefix=/gnu/store/@dots{}}, as well as the options specified
- by the @code{#:configure-flags} argument.
- @item build
- Run @code{make} with the list of flags specified with
- @code{#:make-flags}. If the @code{#:parallel-build?} argument is true
- (the default), build with @code{make -j}.
- @item check
- Run @code{make check}, or some other target specified with
- @code{#:test-target}, unless @code{#:tests? #f} is passed. If the
- @code{#:parallel-tests?} argument is true (the default), run @code{make
- check -j}.
- @item install
- Run @code{make install} with the flags listed in @code{#:make-flags}.
- @item patch-shebangs
- Patch shebangs on the installed executable files.
- @item strip
- Strip debugging symbols from ELF files (unless @code{#:strip-binaries?}
- is false), copying them to the @code{debug} output when available
- (@pxref{Installing Debugging Files}).
- @end table
- Other build systems have similar phases, with some variations. For
- example, @code{cmake-build-system} has same-named phases but its
- @code{configure} phases runs @code{cmake} instead of @code{./configure}.
- Others, such as @code{python-build-system}, have a wholly different list
- of standard phases. All this code runs on the @dfn{build side}: it is
- evaluated when you actually build the package, in a dedicated build
- process spawned by the build daemon (@pxref{Invoking guix-daemon}).
- Build phases are represented as association lists or ``alists''
- (@pxref{Association Lists,,, guile, GNU Guile Reference Manual}) where
- each key is a symbol for the name of the phase and the associated value
- is a procedure that accepts an arbitrary number of arguments. By
- convention, those procedures receive information about the build in the
- form of @dfn{keyword parameters}, which they can use or ignore.
- @vindex %standard-phases
- For example, here is how @code{(guix build gnu-build-system)} defines
- @code{%standard-phases}, the variable holding its alist of build
- phases@footnote{We present a simplified view of those build phases, but
- do take a look at @code{(guix build gnu-build-system)} to see all the
- details!}:
- @lisp
- ;; The build phases of 'gnu-build-system'.
- (define* (unpack #:key source #:allow-other-keys)
- ;; Extract the source tarball.
- (invoke "tar" "xvf" source))
- (define* (configure #:key outputs #:allow-other-keys)
- ;; Run the 'configure' script. Install to output "out".
- (let ((out (assoc-ref outputs "out")))
- (invoke "./configure"
- (string-append "--prefix=" out))))
- (define* (build #:allow-other-keys)
- ;; Compile.
- (invoke "make"))
- (define* (check #:key (test-target "check") (tests? #true)
- #:allow-other-keys)
- ;; Run the test suite.
- (if tests?
- (invoke "make" test-target)
- (display "test suite not run\n")))
- (define* (install #:allow-other-keys)
- ;; Install files to the prefix 'configure' specified.
- (invoke "make" "install"))
- (define %standard-phases
- ;; The list of standard phases (quite a few are omitted
- ;; for brevity). Each element is a symbol/procedure pair.
- (list (cons 'unpack unpack)
- (cons 'configure configure)
- (cons 'build build)
- (cons 'check check)
- (cons 'install install)))
- @end lisp
- This shows how @code{%standard-phases} is defined as a list of
- symbol/procedure pairs (@pxref{Pairs,,, guile, GNU Guile Reference
- Manual}). The first pair associates the @code{unpack} procedure with
- the @code{unpack} symbol---a name; the second pair defines the
- @code{configure} phase similarly, and so on. When building a package
- that uses @code{gnu-build-system} with its default list of phases, those
- phases are executed sequentially. You can see the name of each phase
- started and completed in the build log of packages that you build.
- Let's now look at the procedures themselves. Each one is defined with
- @code{define*}: @code{#:key} lists keyword parameters the procedure
- accepts, possibly with a default value, and @code{#:allow-other-keys}
- specifies that other keyword parameters are ignored (@pxref{Optional
- Arguments,,, guile, GNU Guile Reference Manual}).
- The @code{unpack} procedure honors the @code{source} parameter, which
- the build system uses to pass the file name of the source tarball (or
- version control checkout), and it ignores other parameters. The
- @code{configure} phase only cares about the @code{outputs} parameter, an
- alist mapping package output names to their store file name
- (@pxref{Packages with Multiple Outputs}). It extracts the file name of
- for @code{out}, the default output, and passes it to
- @command{./configure} as the installation prefix, meaning that
- @command{make install} will eventually copy all the files in that
- directory (@pxref{Configuration, configuration and makefile
- conventions,, standards, GNU Coding Standards}). @code{build} and
- @code{install} ignore all their arguments. @code{check} honors the
- @code{test-target} argument, which specifies the name of the Makefile
- target to run tests; it prints a message and skips tests when
- @code{tests?} is false.
- @cindex build phases, customizing
- The list of phases used for a particular package can be changed with the
- @code{#:phases} parameter of the build system. Changing the set of
- build phases boils down to building a new alist of phases based on the
- @code{%standard-phases} alist described above. This can be done with
- standard alist procedures such as @code{alist-delete} (@pxref{SRFI-1
- Association Lists,,, guile, GNU Guile Reference Manual}); however, it is
- more convenient to do so with @code{modify-phases} (@pxref{Build
- Utilities, @code{modify-phases}}).
- Here is an example of a package definition that removes the
- @code{configure} phase of @code{%standard-phases} and inserts a new
- phase before the @code{build} phase, called
- @code{set-prefix-in-makefile}:
- @lisp
- (define-public example
- (package
- (name "example")
- ;; other fields omitted
- (build-system gnu-build-system)
- (arguments
- '(#:phases (modify-phases %standard-phases
- (delete 'configure)
- (add-before 'build 'set-prefix-in-makefile
- (lambda* (#:key outputs #:allow-other-keys)
- ;; Modify the makefile so that its
- ;; 'PREFIX' variable points to "out".
- (let ((out (assoc-ref outputs "out")))
- (substitute* "Makefile"
- (("PREFIX =.*")
- (string-append "PREFIX = "
- out "\n")))
- #true))))))))
- @end lisp
- The new phase that is inserted is written as an anonymous procedure,
- introduced with @code{lambda*}; it honors the @code{outputs} parameter
- we have seen before. @xref{Build Utilities}, for more about the helpers
- used by this phase, and for more examples of @code{modify-phases}.
- @cindex code staging
- @cindex staging, of code
- Keep in mind that build phases are code evaluated at the time the
- package is actually built. This explains why the whole
- @code{modify-phases} expression above is quoted (it comes after the
- @code{'} or apostrophe): it is @dfn{staged} for later execution.
- @xref{G-Expressions}, for an explanation of code staging and the
- @dfn{code strata} involved.
- @node Build Utilities
- @section Build Utilities
- As soon as you start writing non-trivial package definitions
- (@pxref{Defining Packages}) or other build actions
- (@pxref{G-Expressions}), you will likely start looking for helpers for
- ``shell-like'' actions---creating directories, copying and deleting
- files recursively, manipulating build phases, and so on. The
- @code{(guix build utils)} module provides such utility procedures.
- Most build systems load @code{(guix build utils)} (@pxref{Build
- Systems}). Thus, when writing custom build phases for your package
- definitions, you can usually assume those procedures are in scope.
- When writing G-expressions, you can import @code{(guix build utils)} on
- the ``build side'' using @code{with-imported-modules} and then put it in
- scope with the @code{use-modules} form (@pxref{Using Guile Modules,,,
- guile, GNU Guile Reference Manual}):
- @lisp
- (with-imported-modules '((guix build utils)) ;import it
- (computed-file "empty-tree"
- #~(begin
- ;; Put it in scope.
- (use-modules (guix build utils))
- ;; Happily use its 'mkdir-p' procedure.
- (mkdir-p (string-append #$output "/a/b/c")))))
- @end lisp
- The remainder of this section is the reference for most of the utility
- procedures provided by @code{(guix build utils)}.
- @c TODO Document what's missing.
- @subsection Dealing with Store File Names
- This section documents procedures that deal with store file names.
- @deffn {Scheme Procedure} %store-directory
- Return the directory name of the store.
- @end deffn
- @deffn {Scheme Procedure} store-file-name? @var{file}
- Return true if @var{file} is in the store.
- @end deffn
- @deffn {Scheme Procedure} strip-store-file-name @var{file}
- Strip the @file{/gnu/store} and hash from @var{file}, a store file name.
- The result is typically a @code{"@var{package}-@var{version}"} string.
- @end deffn
- @deffn {Scheme Procedure} package-name->name+version @var{name}
- Given @var{name}, a package name like @code{"foo-0.9.1b"}, return two
- values: @code{"foo"} and @code{"0.9.1b"}. When the version part is
- unavailable, @var{name} and @code{#f} are returned. The first hyphen
- followed by a digit is considered to introduce the version part.
- @end deffn
- @subsection File Types
- The procedures below deal with files and file types.
- @deffn {Scheme Procedure} directory-exists? @var{dir}
- Return @code{#t} if @var{dir} exists and is a directory.
- @end deffn
- @deffn {Scheme Procedure} executable-file? @var{file}
- Return @code{#t} if @var{file} exists and is executable.
- @end deffn
- @deffn {Scheme Procedure} symbolic-link? @var{file}
- Return @code{#t} if @var{file} is a symbolic link (aka. a ``symlink'').
- @end deffn
- @deffn {Scheme Procedure} elf-file? @var{file}
- @deffnx {Scheme Procedure} ar-file? @var{file}
- @deffnx {Scheme Procedure} gzip-file? @var{file}
- Return @code{#t} if @var{file} is, respectively, an ELF file, an
- @code{ar} archive (such as a @file{.a} static library), or a gzip file.
- @end deffn
- @deffn {Scheme Procedure} reset-gzip-timestamp @var{file} [#:keep-mtime? #t]
- If @var{file} is a gzip file, reset its embedded timestamp (as with
- @command{gzip --no-name}) and return true. Otherwise return @code{#f}.
- When @var{keep-mtime?} is true, preserve @var{file}'s modification time.
- @end deffn
- @subsection File Manipulation
- The following procedures and macros help create, modify, and delete
- files. They provide functionality comparable to common shell utilities
- such as @command{mkdir -p}, @command{cp -r}, @command{rm -r}, and
- @command{sed}. They complement Guile's extensive, but low-level, file
- system interface (@pxref{POSIX,,, guile, GNU Guile Reference Manual}).
- @deffn {Scheme Syntax} with-directory-excursion @var{directory} @var{body}@dots{}
- Run @var{body} with @var{directory} as the process's current directory.
- Essentially, this macro changes the current directory to @var{directory}
- before evaluating @var{body}, using @code{chdir} (@pxref{Processes,,,
- guile, GNU Guile Reference Manual}). It changes back to the initial
- directory when the dynamic extent of @var{body} is left, be it @i{via}
- normal procedure return or @i{via} a non-local exit such as an
- exception.
- @end deffn
- @deffn {Scheme Procedure} mkdir-p @var{dir}
- Create directory @var{dir} and all its ancestors.
- @end deffn
- @deffn {Scheme Procedure} install-file @var{file} @var{directory}
- Create @var{directory} if it does not exist and copy @var{file} in there
- under the same name.
- @end deffn
- @deffn {Scheme Procedure} make-file-writable @var{file}
- Make @var{file} writable for its owner.
- @end deffn
- @deffn {Scheme Procedure} copy-recursively @var{source} @var{destination} @
- [#:log (current-output-port)] [#:follow-symlinks? #f] @
- [#:copy-file copy-file] [#:keep-mtime? #f] [#:keep-permissions? #t]
- Copy @var{source} directory to @var{destination}. Follow symlinks if
- @var{follow-symlinks?} is true; otherwise, just preserve them. Call
- @var{copy-file} to copy regular files. When @var{keep-mtime?} is true,
- keep the modification time of the files in @var{source} on those of
- @var{destination}. When @var{keep-permissions?} is true, preserve file
- permissions. Write verbose output to the @var{log} port.
- @end deffn
- @deffn {Scheme Procedure} delete-file-recursively @var{dir} @
- [#:follow-mounts? #f]
- Delete @var{dir} recursively, like @command{rm -rf}, without following
- symlinks. Don't follow mount points either, unless @var{follow-mounts?}
- is true. Report but ignore errors.
- @end deffn
- @deffn {Scheme Syntax} substitute* @var{file} @
- ((@var{regexp} @var{match-var}@dots{}) @var{body}@dots{}) @dots{}
- Substitute @var{regexp} in @var{file} by the string returned by
- @var{body}. @var{body} is evaluated with each @var{match-var} bound to
- the corresponding positional regexp sub-expression. For example:
- @lisp
- (substitute* file
- (("hello")
- "good morning\n")
- (("foo([a-z]+)bar(.*)$" all letters end)
- (string-append "baz" letters end)))
- @end lisp
- Here, anytime a line of @var{file} contains @code{hello}, it is replaced
- by @code{good morning}. Anytime a line of @var{file} matches the second
- regexp, @code{all} is bound to the complete match, @code{letters} is bound
- to the first sub-expression, and @code{end} is bound to the last one.
- When one of the @var{match-var} is @code{_}, no variable is bound to the
- corresponding match substring.
- Alternatively, @var{file} may be a list of file names, in which case
- they are all subject to the substitutions.
- Be careful about using @code{$} to match the end of a line; by itself it
- won't match the terminating newline of a line.
- @end deffn
- @subsection File Search
- @cindex file, searching
- This section documents procedures to search and filter files.
- @deffn {Scheme Procedure} file-name-predicate @var{regexp}
- Return a predicate that returns true when passed a file name whose base
- name matches @var{regexp}.
- @end deffn
- @deffn {Scheme Procedure} find-files @var{dir} [@var{pred}] @
- [#:stat lstat] [#:directories? #f] [#:fail-on-error? #f]
- Return the lexicographically sorted list of files under @var{dir} for
- which @var{pred} returns true. @var{pred} is passed two arguments: the
- absolute file name, and its stat buffer; the default predicate always
- returns true. @var{pred} can also be a regular expression, in which
- case it is equivalent to @code{(file-name-predicate @var{pred})}.
- @var{stat} is used to obtain file information; using @code{lstat} means
- that symlinks are not followed. If @var{directories?} is true, then
- directories will also be included. If @var{fail-on-error?} is true,
- raise an exception upon error.
- @end deffn
- Here are a few examples where we assume that the current directory is
- the root of the Guix source tree:
- @lisp
- ;; List all the regular files in the current directory.
- (find-files ".")
- @result{} ("./.dir-locals.el" "./.gitignore" @dots{})
- ;; List all the .scm files under gnu/services.
- (find-files "gnu/services" "\\.scm$")
- @result{} ("gnu/services/admin.scm" "gnu/services/audio.scm" @dots{})
- ;; List ar files in the current directory.
- (find-files "." (lambda (file stat) (ar-file? file)))
- @result{} ("./libformat.a" "./libstore.a" @dots{})
- @end lisp
- @deffn {Scheme Procedure} which @var{program}
- Return the complete file name for @var{program} as found in
- @code{$PATH}, or @code{#f} if @var{program} could not be found.
- @end deffn
- @deffn {Scheme Procedure} search-input-file @var{inputs} @var{name}
- @deffnx {Scheme Procedure} search-input-directory @var{inputs} @var{name}
- Return the complete file name for @var{name} as found in @var{inputs};
- @code{search-input-file} searches for a regular file and
- @code{search-input-directory} searches for a directory. If @var{name}
- could not be found, an exception is raised.
- Here, @var{inputs} must be an association list like @code{inputs} and
- @code{native-inputs} as available to build phases (@pxref{Build
- Phases}).
- @end deffn
- Here is a (simplified) example of how @code{search-input-file} is used
- in a build phase of the @code{wireguard-tools} package:
- @lisp
- (add-after 'install 'wrap-wg-quick
- (lambda* (#:key inputs outputs #:allow-other-keys)
- (let ((coreutils (string-append (assoc-ref inputs "coreutils")
- "/bin")))
- (wrap-program (search-input-file outputs "bin/wg-quick")
- #:sh (search-input-file inputs "bin/bash")
- `("PATH" ":" prefix ,(list coreutils))))))
- @end lisp
- @subsection Program Invocation
- @cindex program invocation, from Scheme
- @cindex invoking programs, from Scheme
- You'll find handy procedures to spawn processes in this module,
- essentially convenient wrappers around Guile's @code{system*}
- (@pxref{Processes, @code{system*},, guile, GNU Guile Reference Manual}).
- @deffn {Scheme Procedure} invoke @var{program} @var{args}@dots{}
- Invoke @var{program} with the given @var{args}. Raise an
- @code{&invoke-error} exception if the exit code is non-zero; otherwise
- return @code{#t}.
- The advantage compared to @code{system*} is that you do not need to
- check the return value. This reduces boilerplate in shell-script-like
- snippets for instance in package build phases.
- @end deffn
- @deffn {Scheme Procedure} invoke-error? @var{c}
- Return true if @var{c} is an @code{&invoke-error} condition.
- @end deffn
- @deffn {Scheme Procedure} invoke-error-program @var{c}
- @deffnx {Scheme Procedure} invoke-error-arguments @var{c}
- @deffnx {Scheme Procedure} invoke-error-exit-status @var{c}
- @deffnx {Scheme Procedure} invoke-error-term-signal @var{c}
- @deffnx {Scheme Procedure} invoke-error-stop-signal @var{c}
- Access specific fields of @var{c}, an @code{&invoke-error} condition.
- @end deffn
- @deffn {Scheme Procedure} report-invoke-error @var{c} [@var{port}]
- Report to @var{port} (by default the current error port) about @var{c},
- an @code{&invoke-error} condition, in a human-friendly way.
- Typical usage would look like this:
- @lisp
- (use-modules (srfi srfi-34) ;for 'guard'
- (guix build utils))
- (guard (c ((invoke-error? c)
- (report-invoke-error c)))
- (invoke "date" "--imaginary-option"))
- @print{} command "date" "--imaginary-option" failed with status 1
- @end lisp
- @end deffn
- @deffn {Scheme Procedure} invoke/quiet @var{program} @var{args}@dots{}
- Invoke @var{program} with @var{args} and capture @var{program}'s
- standard output and standard error. If @var{program} succeeds, print
- nothing and return the unspecified value; otherwise, raise a
- @code{&message} error condition that includes the status code and the
- output of @var{program}.
- Here's an example:
- @lisp
- (use-modules (srfi srfi-34) ;for 'guard'
- (srfi srfi-35) ;for 'message-condition?'
- (guix build utils))
- (guard (c ((message-condition? c)
- (display (condition-message c))))
- (invoke/quiet "date") ;all is fine
- (invoke/quiet "date" "--imaginary-option"))
- @print{} 'date --imaginary-option' exited with status 1; output follows:
- date: unrecognized option '--imaginary-option'
- Try 'date --help' for more information.
- @end lisp
- @end deffn
- @subsection Build Phases
- @cindex build phases
- The @code{(guix build utils)} also contains tools to manipulate build
- phases as used by build systems (@pxref{Build Systems}). Build phases
- are represented as association lists or ``alists'' (@pxref{Association
- Lists,,, guile, GNU Guile Reference Manual}) where each key is a symbol
- naming the phase and the associated value is a procedure (@pxref{Build
- Phases}).
- Guile core and the @code{(srfi srfi-1)} module both provide tools to
- manipulate alists. The @code{(guix build utils)} module complements
- those with tools written with build phases in mind.
- @cindex build phases, modifying
- @deffn {Scheme Syntax} modify-phases @var{phases} @var{clause}@dots{}
- Modify @var{phases} sequentially as per each @var{clause}, which may
- have one of the following forms:
- @lisp
- (delete @var{old-phase-name})
- (replace @var{old-phase-name} @var{new-phase})
- (add-before @var{old-phase-name} @var{new-phase-name} @var{new-phase})
- (add-after @var{old-phase-name} @var{new-phase-name} @var{new-phase})
- @end lisp
- Where every @var{phase-name} above is an expression evaluating to a
- symbol, and @var{new-phase} an expression evaluating to a procedure.
- @end deffn
- The example below is taken from the definition of the @code{grep}
- package. It adds a phase to run after the @code{install} phase, called
- @code{fix-egrep-and-fgrep}. That phase is a procedure (@code{lambda*}
- is for anonymous procedures) that takes a @code{#:outputs} keyword
- argument and ignores extra keyword arguments (@pxref{Optional
- Arguments,,, guile, GNU Guile Reference Manual}, for more on
- @code{lambda*} and optional and keyword arguments.) The phase uses
- @code{substitute*} to modify the installed @file{egrep} and @file{fgrep}
- scripts so that they refer to @code{grep} by its absolute file name:
- @lisp
- (modify-phases %standard-phases
- (add-after 'install 'fix-egrep-and-fgrep
- ;; Patch 'egrep' and 'fgrep' to execute 'grep' via its
- ;; absolute file name instead of searching for it in $PATH.
- (lambda* (#:key outputs #:allow-other-keys)
- (let* ((out (assoc-ref outputs "out"))
- (bin (string-append out "/bin")))
- (substitute* (list (string-append bin "/egrep")
- (string-append bin "/fgrep"))
- (("^exec grep")
- (string-append "exec " bin "/grep")))))))
- @end lisp
- In the example below, phases are modified in two ways: the standard
- @code{configure} phase is deleted, presumably because the package does
- not have a @file{configure} script or anything similar, and the default
- @code{install} phase is replaced by one that manually copies the
- executable files to be installed:
- @lisp
- (modify-phases %standard-phases
- (delete 'configure) ;no 'configure' script
- (replace 'install
- (lambda* (#:key outputs #:allow-other-keys)
- ;; The package's Makefile doesn't provide an "install"
- ;; rule so do it by ourselves.
- (let ((bin (string-append (assoc-ref outputs "out")
- "/bin")))
- (install-file "footswitch" bin)
- (install-file "scythe" bin)))))
- @end lisp
- @c TODO: Add more examples.
- @subsection Wrappers
- @cindex program wrappers
- @cindex wrapping programs
- It is not unusual for a command to require certain environment variables
- to be set for proper functioning, typically search paths (@pxref{Search
- Paths}). Failing to do that, the command might fail to find files or
- other commands it relies on, or it might pick the ``wrong''
- ones---depending on the environment in which it runs. Examples include:
- @itemize
- @item
- a shell script that assumes all the commands it uses are in @env{PATH};
- @item
- a Guile program that assumes all its modules are in @env{GUILE_LOAD_PATH}
- and @env{GUILE_LOAD_COMPILED_PATH};
- @item
- a Qt application that expects to find certain plugins in
- @env{QT_PLUGIN_PATH}.
- @end itemize
- For a package writer, the goal is to make sure commands always work the
- same rather than depend on some external settings. One way to achieve
- that is to @dfn{wrap} commands in a thin script that sets those
- environment variables, thereby ensuring that those run-time dependencies
- are always found. The wrapper would be used to set @env{PATH},
- @env{GUILE_LOAD_PATH}, or @env{QT_PLUGIN_PATH} in the examples above.
- To ease that task, the @code{(guix build utils)} module provides a
- couple of helpers to wrap commands.
- @deffn {Scheme Procedure} wrap-program @var{program} @
- [#:sh @var{sh}] [#:rest @var{variables}]
- Make a wrapper for @var{program}. @var{variables} should look like this:
- @lisp
- '(@var{variable} @var{delimiter} @var{position} @var{list-of-directories})
- @end lisp
- where @var{delimiter} is optional. @code{:} will be used if
- @var{delimiter} is not given.
- For example, this call:
- @lisp
- (wrap-program "foo"
- '("PATH" ":" = ("/gnu/.../bar/bin"))
- '("CERT_PATH" suffix ("/gnu/.../baz/certs"
- "/qux/certs")))
- @end lisp
- will copy @file{foo} to @file{.foo-real} and create the file @file{foo}
- with the following contents:
- @example
- #!location/of/bin/bash
- export PATH="/gnu/.../bar/bin"
- export CERT_PATH="$CERT_PATH$@{CERT_PATH:+:@}/gnu/.../baz/certs:/qux/certs"
- exec -a $0 location/of/.foo-real "$@@"
- @end example
- If @var{program} has previously been wrapped by @code{wrap-program}, the
- wrapper is extended with definitions for @var{variables}. If it is not,
- @var{sh} will be used as the interpreter.
- @end deffn
- @deffn {Scheme Procedure} wrap-script @var{program} @
- [#:guile @var{guile}] [#:rest @var{variables}]
- Wrap the script @var{program} such that @var{variables} are set first.
- The format of @var{variables} is the same as in the @code{wrap-program}
- procedure. This procedure differs from @code{wrap-program} in that it
- does not create a separate shell script. Instead, @var{program} is
- modified directly by prepending a Guile script, which is interpreted as
- a comment in the script's language.
- Special encoding comments as supported by Python are recreated on the
- second line.
- Note that this procedure can only be used once per file as Guile scripts are
- not supported.
- @end deffn
- @node Search Paths
- @section Search Paths
- @cindex search path
- Many programs and libraries look for input data in a @dfn{search path},
- a list of directories: shells like Bash look for executables in the
- command search path, a C compiler looks for @file{.h} files in its
- header search path, the Python interpreter looks for @file{.py}
- files in its search path, the spell checker has a search path for
- dictionaries, and so on.
- Search paths can usually be defined or overridden @i{via} environment
- variables (@pxref{Environment Variables,,, libc, The GNU C Library
- Reference Manual}). For example, the search paths mentioned above can
- be changed by defining the @env{PATH}, @env{C_INCLUDE_PATH},
- @env{PYTHONPATH} (or @env{GUIX_PYTHONPATH}), and @env{DICPATH}
- environment variables---you know, all these something-PATH variables
- that you need to get right or things ``won't be found''.
- You may have noticed from the command line that Guix ``knows'' which
- search path environment variables should be defined, and how. When you
- install packages in your default profile, the file
- @file{~/.guix-profile/etc/profile} is created, which you can ``source''
- from the shell to set those variables. Likewise, if you ask
- @command{guix shell} to create an environment containing Python and
- NumPy, a Python library, and if you pass it the @option{--search-paths}
- option, it will tell you about @env{PATH} and @env{GUIX_PYTHONPATH}
- (@pxref{Invoking guix shell}):
- @example
- $ guix shell python python-numpy --pure --search-paths
- export PATH="/gnu/store/@dots{}-profile/bin"
- export GUIX_PYTHONPATH="/gnu/store/@dots{}-profile/lib/python3.9/site-packages"
- @end example
- When you omit @option{--search-paths}, it defines these environment
- variables right away, such that Python can readily find NumPy:
- @example
- $ guix shell python python-numpy -- python3
- Python 3.9.6 (default, Jan 1 1970, 00:00:01)
- [GCC 10.3.0] on linux
- Type "help", "copyright", "credits" or "license" for more information.
- >>> import numpy
- >>> numpy.version.version
- '1.20.3'
- @end example
- For this to work, the definition of the @code{python} package
- @emph{declares} the search path it cares about and its associated
- environment variable, @env{GUIX_PYTHONPATH}. It looks like this:
- @lisp
- (package
- (name "python")
- (version "3.9.9")
- ;; some fields omitted...
- (native-search-paths
- (list (search-path-specification
- (variable "GUIX_PYTHONPATH")
- (files (list "lib/python/3.9/site-packages"))))))
- @end lisp
- What this @code{native-search-paths} field says is that, when the
- @code{python} package is used, the @env{GUIX_PYTHONPATH} environment
- variable must be defined to include all the
- @file{lib/python/3.9/site-packages} sub-directories encountered in its
- environment. (The @code{native-} bit means that, if we are in a
- cross-compilation environment, only native inputs may be added to the
- search path; @pxref{package Reference, @code{search-paths}}.)
- In the NumPy example above, the profile where
- @code{python} appears contains exactly one such sub-directory, and
- @env{GUIX_PYTHONPATH} is set to that. When there are several
- @file{lib/python/3.9/site-packages}---this is the case in package build
- environments---they are all added to @env{GUIX_PYTHONPATH}, separated by
- colons (@code{:}).
- @quotation Note
- Notice that @env{GUIX_PYTHONPATH} is specified as part of the definition
- of the @code{python} package, and @emph{not} as part of that of
- @code{python-numpy}. This is because this environment variable
- ``belongs'' to Python, not NumPy: Python actually reads the value of
- that variable and honors it.
- Corollary: if you create a profile that does not contain @code{python},
- @code{GUIX_PYTHONPATH} will @emph{not} be defined, even if it contains
- packages that provide @file{.py} files:
- @example
- $ guix shell python-numpy --search-paths --pure
- export PATH="/gnu/store/@dots{}-profile/bin"
- @end example
- This makes a lot of sense if we look at this profile in isolation: no
- software in this profile would read @env{GUIX_PYTHONPATH}.
- @end quotation
- Of course, there are many variations on that theme: some packages honor
- more than one search path, some use separators other than colon, some
- accumulate several directories in their search path, and so on. A more
- complex example is the search path of libxml2: the value of the
- @env{XML_CATALOG_FILES} environment variable is space-separated, it must
- contain a list of @file{catalog.xml} files (not directories), which are
- to be found in @file{xml} sub-directories---nothing less. The search
- path specification looks like this:
- @lisp
- (package
- (name "libxml2")
- ;; some fields omitted
- (native-search-paths
- (list (search-path-specification
- (variable "XML_CATALOG_FILES")
- (separator " ")
- (files '("xml"))
- (file-pattern "^catalog\\.xml$")
- (file-type 'regular)))))
- @end lisp
- Worry not, search path specifications are usually not this tricky.
- The @code{(guix search-paths)} module defines the data type of search
- path specifications and a number of helper procedures. Below is the
- reference of search path specifications.
- @deftp {Data Type} search-path-specification
- The data type for search path specifications.
- @table @asis
- @item @code{variable}
- The name of the environment variable for this search path (a string).
- @item @code{files}
- The list of sub-directories (strings) that should be added to the search
- path.
- @item @code{separator} (default: @code{":"})
- The string used to separate search path components.
- As a special case, a @code{separator} value of @code{#f} specifies a
- ``single-component search path''---in other words, a search path that
- cannot contain more than one element. This is useful in some cases,
- such as the @code{SSL_CERT_DIR} variable (honored by OpenSSL, cURL, and
- a few other packages) or the @code{ASPELL_DICT_DIR} variable (honored by
- the GNU Aspell spell checker), both of which must point to a single
- directory.
- @item @code{file-type} (default: @code{'directory})
- The type of file being matched---@code{'directory} or @code{'regular},
- though it can be any symbol returned by @code{stat:type} (@pxref{File
- System, @code{stat},, guile, GNU Guile Reference Manual}).
- In the libxml2 example above, we would match regular files; in the
- Python example, we would match directories.
- @item @code{file-pattern} (default: @code{#f})
- This must be either @code{#f} or a regular expression specifying
- files to be matched @emph{within} the sub-directories specified by the
- @code{files} field.
- Again, the libxml2 example shows a situation where this is needed.
- @end table
- @end deftp
- How do you turn search path specifications on one hand and a bunch of
- directories on the other hand in a set of environment variable
- definitions? That's the job of @code{evaluate-search-paths}.
- @deffn {Scheme Procedure} evaluate-search-paths @var{search-paths} @
- @var{directories} [@var{getenv}]
- Evaluate @var{search-paths}, a list of search-path specifications, for
- @var{directories}, a list of directory names, and return a list of
- specification/value pairs. Use @var{getenv} to determine the current
- settings and report only settings not already effective.
- @end deffn
- The @code{(guix profiles)} provides a higher-level helper procedure,
- @code{load-profile}, that sets the environment variables of a profile.
- @node The Store
- @section The Store
- @cindex store
- @cindex store items
- @cindex store paths
- Conceptually, the @dfn{store} is the place where derivations that have
- been built successfully are stored---by default, @file{/gnu/store}.
- Sub-directories in the store are referred to as @dfn{store items} or
- sometimes @dfn{store paths}. The store has an associated database that
- contains information such as the store paths referred to by each store
- path, and the list of @emph{valid} store items---results of successful
- builds. This database resides in @file{@var{localstatedir}/guix/db},
- where @var{localstatedir} is the state directory specified @i{via}
- @option{--localstatedir} at configure time, usually @file{/var}.
- The store is @emph{always} accessed by the daemon on behalf of its clients
- (@pxref{Invoking guix-daemon}). To manipulate the store, clients
- connect to the daemon over a Unix-domain socket, send requests to it,
- and read the result---these are remote procedure calls, or RPCs.
- @quotation Note
- Users must @emph{never} modify files under @file{/gnu/store} directly.
- This would lead to inconsistencies and break the immutability
- assumptions of Guix's functional model (@pxref{Introduction}).
- @xref{Invoking guix gc, @command{guix gc --verify}}, for information on
- how to check the integrity of the store and attempt recovery from
- accidental modifications.
- @end quotation
- The @code{(guix store)} module provides procedures to connect to the
- daemon, and to perform RPCs. These are described below. By default,
- @code{open-connection}, and thus all the @command{guix} commands,
- connect to the local daemon or to the URI specified by the
- @env{GUIX_DAEMON_SOCKET} environment variable.
- @defvr {Environment Variable} GUIX_DAEMON_SOCKET
- When set, the value of this variable should be a file name or a URI
- designating the daemon endpoint. When it is a file name, it denotes a
- Unix-domain socket to connect to. In addition to file names, the
- supported URI schemes are:
- @table @code
- @item file
- @itemx unix
- These are for Unix-domain sockets.
- @code{file:///var/guix/daemon-socket/socket} is equivalent to
- @file{/var/guix/daemon-socket/socket}.
- @item guix
- @cindex daemon, remote access
- @cindex remote access to the daemon
- @cindex daemon, cluster setup
- @cindex clusters, daemon setup
- These URIs denote connections over TCP/IP, without encryption nor
- authentication of the remote host. The URI must specify the host name
- and optionally a port number (by default port 44146 is used):
- @example
- guix://master.guix.example.org:1234
- @end example
- This setup is suitable on local networks, such as clusters, where only
- trusted nodes may connect to the build daemon at
- @code{master.guix.example.org}.
- The @option{--listen} option of @command{guix-daemon} can be used to
- instruct it to listen for TCP connections (@pxref{Invoking guix-daemon,
- @option{--listen}}).
- @item ssh
- @cindex SSH access to build daemons
- These URIs allow you to connect to a remote daemon over SSH@. This
- feature requires Guile-SSH (@pxref{Requirements}) and a working
- @command{guile} binary in @env{PATH} on the destination machine. It
- supports public key and GSSAPI authentication. A typical URL might look
- like this:
- @example
- ssh://charlie@@guix.example.org:22
- @end example
- As for @command{guix copy}, the usual OpenSSH client configuration files
- are honored (@pxref{Invoking guix copy}).
- @end table
- Additional URI schemes may be supported in the future.
- @c XXX: Remove this note when the protocol incurs fewer round trips
- @c and when (guix derivations) no longer relies on file system access.
- @quotation Note
- The ability to connect to remote build daemons is considered
- experimental as of @value{VERSION}. Please get in touch with us to
- share any problems or suggestions you may have (@pxref{Contributing}).
- @end quotation
- @end defvr
- @deffn {Scheme Procedure} open-connection [@var{uri}] [#:reserve-space? #t]
- Connect to the daemon over the Unix-domain socket at @var{uri} (a string). When
- @var{reserve-space?} is true, instruct it to reserve a little bit of
- extra space on the file system so that the garbage collector can still
- operate should the disk become full. Return a server object.
- @var{file} defaults to @code{%default-socket-path}, which is the normal
- location given the options that were passed to @command{configure}.
- @end deffn
- @deffn {Scheme Procedure} close-connection @var{server}
- Close the connection to @var{server}.
- @end deffn
- @defvr {Scheme Variable} current-build-output-port
- This variable is bound to a SRFI-39 parameter, which refers to the port
- where build and error logs sent by the daemon should be written.
- @end defvr
- Procedures that make RPCs all take a server object as their first
- argument.
- @deffn {Scheme Procedure} valid-path? @var{server} @var{path}
- @cindex invalid store items
- Return @code{#t} when @var{path} designates a valid store item and
- @code{#f} otherwise (an invalid item may exist on disk but still be
- invalid, for instance because it is the result of an aborted or failed
- build).
- A @code{&store-protocol-error} condition is raised if @var{path} is not
- prefixed by the store directory (@file{/gnu/store}).
- @end deffn
- @deffn {Scheme Procedure} add-text-to-store @var{server} @var{name} @var{text} [@var{references}]
- Add @var{text} under file @var{name} in the store, and return its store
- path. @var{references} is the list of store paths referred to by the
- resulting store path.
- @end deffn
- @deffn {Scheme Procedure} build-derivations @var{store} @var{derivations} @
- [@var{mode}]
- Build @var{derivations}, a list of @code{<derivation>} objects, @file{.drv}
- file names, or derivation/output pairs, using the specified
- @var{mode}---@code{(build-mode normal)} by default.
- @end deffn
- Note that the @code{(guix monads)} module provides a monad as well as
- monadic versions of the above procedures, with the goal of making it
- more convenient to work with code that accesses the store (@pxref{The
- Store Monad}).
- @c FIXME
- @i{This section is currently incomplete.}
- @node Derivations
- @section Derivations
- @cindex derivations
- Low-level build actions and the environment in which they are performed
- are represented by @dfn{derivations}. A derivation contains the
- following pieces of information:
- @itemize
- @item
- The outputs of the derivation---derivations produce at least one file or
- directory in the store, but may produce more.
- @item
- @cindex build-time dependencies
- @cindex dependencies, build-time
- The inputs of the derivations---i.e., its build-time dependencies---which may
- be other derivations or plain files in the store (patches, build scripts,
- etc.).
- @item
- The system type targeted by the derivation---e.g., @code{x86_64-linux}.
- @item
- The file name of a build script in the store, along with the arguments
- to be passed.
- @item
- A list of environment variables to be defined.
- @end itemize
- @cindex derivation path
- Derivations allow clients of the daemon to communicate build actions to
- the store. They exist in two forms: as an in-memory representation,
- both on the client- and daemon-side, and as files in the store whose
- name end in @file{.drv}---these files are referred to as @dfn{derivation
- paths}. Derivations paths can be passed to the @code{build-derivations}
- procedure to perform the build actions they prescribe (@pxref{The
- Store}).
- @cindex fixed-output derivations
- Operations such as file downloads and version-control checkouts for
- which the expected content hash is known in advance are modeled as
- @dfn{fixed-output derivations}. Unlike regular derivations, the outputs
- of a fixed-output derivation are independent of its inputs---e.g., a
- source code download produces the same result regardless of the download
- method and tools being used.
- @cindex references
- @cindex run-time dependencies
- @cindex dependencies, run-time
- The outputs of derivations---i.e., the build results---have a set of
- @dfn{references}, as reported by the @code{references} RPC or the
- @command{guix gc --references} command (@pxref{Invoking guix gc}). References
- are the set of run-time dependencies of the build results. References are a
- subset of the inputs of the derivation; this subset is automatically computed
- by the build daemon by scanning all the files in the outputs.
- The @code{(guix derivations)} module provides a representation of
- derivations as Scheme objects, along with procedures to create and
- otherwise manipulate derivations. The lowest-level primitive to create
- a derivation is the @code{derivation} procedure:
- @deffn {Scheme Procedure} derivation @var{store} @var{name} @var{builder} @
- @var{args} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @
- [#:recursive? #f] [#:inputs '()] [#:env-vars '()] @
- [#:system (%current-system)] [#:references-graphs #f] @
- [#:allowed-references #f] [#:disallowed-references #f] @
- [#:leaked-env-vars #f] [#:local-build? #f] @
- [#:substitutable? #t] [#:properties '()]
- Build a derivation with the given arguments, and return the resulting
- @code{<derivation>} object.
- When @var{hash} and @var{hash-algo} are given, a
- @dfn{fixed-output derivation} is created---i.e., one whose result is
- known in advance, such as a file download. If, in addition,
- @var{recursive?} is true, then that fixed output may be an executable
- file or a directory and @var{hash} must be the hash of an archive
- containing this output.
- When @var{references-graphs} is true, it must be a list of file
- name/store path pairs. In that case, the reference graph of each store
- path is exported in the build environment in the corresponding file, in
- a simple text format.
- When @var{allowed-references} is true, it must be a list of store items
- or outputs that the derivation's output may refer to. Likewise,
- @var{disallowed-references}, if true, must be a list of things the
- outputs may @emph{not} refer to.
- When @var{leaked-env-vars} is true, it must be a list of strings
- denoting environment variables that are allowed to ``leak'' from the
- daemon's environment to the build environment. This is only applicable
- to fixed-output derivations---i.e., when @var{hash} is true. The main
- use is to allow variables such as @code{http_proxy} to be passed to
- derivations that download files.
- When @var{local-build?} is true, declare that the derivation is not a
- good candidate for offloading and should rather be built locally
- (@pxref{Daemon Offload Setup}). This is the case for small derivations
- where the costs of data transfers would outweigh the benefits.
- When @var{substitutable?} is false, declare that substitutes of the
- derivation's output should not be used (@pxref{Substitutes}). This is
- useful, for instance, when building packages that capture details of the
- host CPU instruction set.
- @var{properties} must be an association list describing ``properties'' of the
- derivation. It is kept as-is, uninterpreted, in the derivation.
- @end deffn
- @noindent
- Here's an example with a shell script as its builder, assuming
- @var{store} is an open connection to the daemon, and @var{bash} points
- to a Bash executable in the store:
- @lisp
- (use-modules (guix utils)
- (guix store)
- (guix derivations))
- (let ((builder ; add the Bash script to the store
- (add-text-to-store store "my-builder.sh"
- "echo hello world > $out\n" '())))
- (derivation store "foo"
- bash `("-e" ,builder)
- #:inputs `((,bash) (,builder))
- #:env-vars '(("HOME" . "/homeless"))))
- @result{} #<derivation /gnu/store/@dots{}-foo.drv => /gnu/store/@dots{}-foo>
- @end lisp
- As can be guessed, this primitive is cumbersome to use directly. A
- better approach is to write build scripts in Scheme, of course! The
- best course of action for that is to write the build code as a
- ``G-expression'', and to pass it to @code{gexp->derivation}. For more
- information, @pxref{G-Expressions}.
- Once upon a time, @code{gexp->derivation} did not exist and constructing
- derivations with build code written in Scheme was achieved with
- @code{build-expression->derivation}, documented below. This procedure
- is now deprecated in favor of the much nicer @code{gexp->derivation}.
- @deffn {Scheme Procedure} build-expression->derivation @var{store} @
- @var{name} @var{exp} @
- [#:system (%current-system)] [#:inputs '()] @
- [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @
- [#:recursive? #f] [#:env-vars '()] [#:modules '()] @
- [#:references-graphs #f] [#:allowed-references #f] @
- [#:disallowed-references #f] @
- [#:local-build? #f] [#:substitutable? #t] [#:guile-for-build #f]
- Return a derivation that executes Scheme expression @var{exp} as a
- builder for derivation @var{name}. @var{inputs} must be a list of
- @code{(name drv-path sub-drv)} tuples; when @var{sub-drv} is omitted,
- @code{"out"} is assumed. @var{modules} is a list of names of Guile
- modules from the current search path to be copied in the store,
- compiled, and made available in the load path during the execution of
- @var{exp}---e.g., @code{((guix build utils) (guix build
- gnu-build-system))}.
- @var{exp} is evaluated in an environment where @code{%outputs} is bound
- to a list of output/path pairs, and where @code{%build-inputs} is bound
- to a list of string/output-path pairs made from @var{inputs}.
- Optionally, @var{env-vars} is a list of string pairs specifying the name
- and value of environment variables visible to the builder. The builder
- terminates by passing the result of @var{exp} to @code{exit}; thus, when
- @var{exp} returns @code{#f}, the build is considered to have failed.
- @var{exp} is built using @var{guile-for-build} (a derivation). When
- @var{guile-for-build} is omitted or is @code{#f}, the value of the
- @code{%guile-for-build} fluid is used instead.
- See the @code{derivation} procedure for the meaning of
- @var{references-graphs}, @var{allowed-references},
- @var{disallowed-references}, @var{local-build?}, and
- @var{substitutable?}.
- @end deffn
- @noindent
- Here's an example of a single-output derivation that creates a directory
- containing one file:
- @lisp
- (let ((builder '(let ((out (assoc-ref %outputs "out")))
- (mkdir out) ; create /gnu/store/@dots{}-goo
- (call-with-output-file (string-append out "/test")
- (lambda (p)
- (display '(hello guix) p))))))
- (build-expression->derivation store "goo" builder))
- @result{} #<derivation /gnu/store/@dots{}-goo.drv => @dots{}>
- @end lisp
- @node The Store Monad
- @section The Store Monad
- @cindex monad
- The procedures that operate on the store described in the previous
- sections all take an open connection to the build daemon as their first
- argument. Although the underlying model is functional, they either have
- side effects or depend on the current state of the store.
- The former is inconvenient: the connection to the build daemon has to be
- carried around in all those functions, making it impossible to compose
- functions that do not take that parameter with functions that do. The
- latter can be problematic: since store operations have side effects
- and/or depend on external state, they have to be properly sequenced.
- @cindex monadic values
- @cindex monadic functions
- This is where the @code{(guix monads)} module comes in. This module
- provides a framework for working with @dfn{monads}, and a particularly
- useful monad for our uses, the @dfn{store monad}. Monads are a
- construct that allows two things: associating ``context'' with values
- (in our case, the context is the store), and building sequences of
- computations (here computations include accesses to the store). Values
- in a monad---values that carry this additional context---are called
- @dfn{monadic values}; procedures that return such values are called
- @dfn{monadic procedures}.
- Consider this ``normal'' procedure:
- @lisp
- (define (sh-symlink store)
- ;; Return a derivation that symlinks the 'bash' executable.
- (let* ((drv (package-derivation store bash))
- (out (derivation->output-path drv))
- (sh (string-append out "/bin/bash")))
- (build-expression->derivation store "sh"
- `(symlink ,sh %output))))
- @end lisp
- Using @code{(guix monads)} and @code{(guix gexp)}, it may be rewritten
- as a monadic function:
- @lisp
- (define (sh-symlink)
- ;; Same, but return a monadic value.
- (mlet %store-monad ((drv (package->derivation bash)))
- (gexp->derivation "sh"
- #~(symlink (string-append #$drv "/bin/bash")
- #$output))))
- @end lisp
- There are several things to note in the second version: the @code{store}
- parameter is now implicit and is ``threaded'' in the calls to the
- @code{package->derivation} and @code{gexp->derivation} monadic
- procedures, and the monadic value returned by @code{package->derivation}
- is @dfn{bound} using @code{mlet} instead of plain @code{let}.
- As it turns out, the call to @code{package->derivation} can even be
- omitted since it will take place implicitly, as we will see later
- (@pxref{G-Expressions}):
- @lisp
- (define (sh-symlink)
- (gexp->derivation "sh"
- #~(symlink (string-append #$bash "/bin/bash")
- #$output)))
- @end lisp
- @c See
- @c <https://syntaxexclamation.wordpress.com/2014/06/26/escaping-continuations/>
- @c for the funny quote.
- Calling the monadic @code{sh-symlink} has no effect. As someone once
- said, ``you exit a monad like you exit a building on fire: by running''.
- So, to exit the monad and get the desired effect, one must use
- @code{run-with-store}:
- @lisp
- (run-with-store (open-connection) (sh-symlink))
- @result{} /gnu/store/...-sh-symlink
- @end lisp
- Note that the @code{(guix monad-repl)} module extends the Guile REPL with
- new ``meta-commands'' to make it easier to deal with monadic procedures:
- @code{run-in-store}, and @code{enter-store-monad}. The former is used
- to ``run'' a single monadic value through the store:
- @example
- scheme@@(guile-user)> ,run-in-store (package->derivation hello)
- $1 = #<derivation /gnu/store/@dots{}-hello-2.9.drv => @dots{}>
- @end example
- The latter enters a recursive REPL, where all the return values are
- automatically run through the store:
- @example
- scheme@@(guile-user)> ,enter-store-monad
- store-monad@@(guile-user) [1]> (package->derivation hello)
- $2 = #<derivation /gnu/store/@dots{}-hello-2.9.drv => @dots{}>
- store-monad@@(guile-user) [1]> (text-file "foo" "Hello!")
- $3 = "/gnu/store/@dots{}-foo"
- store-monad@@(guile-user) [1]> ,q
- scheme@@(guile-user)>
- @end example
- @noindent
- Note that non-monadic values cannot be returned in the
- @code{store-monad} REPL.
- The main syntactic forms to deal with monads in general are provided by
- the @code{(guix monads)} module and are described below.
- @deffn {Scheme Syntax} with-monad @var{monad} @var{body} ...
- Evaluate any @code{>>=} or @code{return} forms in @var{body} as being
- in @var{monad}.
- @end deffn
- @deffn {Scheme Syntax} return @var{val}
- Return a monadic value that encapsulates @var{val}.
- @end deffn
- @deffn {Scheme Syntax} >>= @var{mval} @var{mproc} ...
- @dfn{Bind} monadic value @var{mval}, passing its ``contents'' to monadic
- procedures @var{mproc}@dots{}@footnote{This operation is commonly
- referred to as ``bind'', but that name denotes an unrelated procedure in
- Guile. Thus we use this somewhat cryptic symbol inherited from the
- Haskell language.}. There can be one @var{mproc} or several of them, as
- in this example:
- @lisp
- (run-with-state
- (with-monad %state-monad
- (>>= (return 1)
- (lambda (x) (return (+ 1 x)))
- (lambda (x) (return (* 2 x)))))
- 'some-state)
- @result{} 4
- @result{} some-state
- @end lisp
- @end deffn
- @deffn {Scheme Syntax} mlet @var{monad} ((@var{var} @var{mval}) ...) @
- @var{body} ...
- @deffnx {Scheme Syntax} mlet* @var{monad} ((@var{var} @var{mval}) ...) @
- @var{body} ...
- Bind the variables @var{var} to the monadic values @var{mval} in
- @var{body}, which is a sequence of expressions. As with the bind
- operator, this can be thought of as ``unpacking'' the raw, non-monadic
- value ``contained'' in @var{mval} and making @var{var} refer to that
- raw, non-monadic value within the scope of the @var{body}. The form
- (@var{var} -> @var{val}) binds @var{var} to the ``normal'' value
- @var{val}, as per @code{let}. The binding operations occur in sequence
- from left to right. The last expression of @var{body} must be a monadic
- expression, and its result will become the result of the @code{mlet} or
- @code{mlet*} when run in the @var{monad}.
- @code{mlet*} is to @code{mlet} what @code{let*} is to @code{let}
- (@pxref{Local Bindings,,, guile, GNU Guile Reference Manual}).
- @end deffn
- @deffn {Scheme System} mbegin @var{monad} @var{mexp} ...
- Bind @var{mexp} and the following monadic expressions in sequence,
- returning the result of the last expression. Every expression in the
- sequence must be a monadic expression.
- This is akin to @code{mlet}, except that the return values of the
- monadic expressions are ignored. In that sense, it is analogous to
- @code{begin}, but applied to monadic expressions.
- @end deffn
- @deffn {Scheme System} mwhen @var{condition} @var{mexp0} @var{mexp*} ...
- When @var{condition} is true, evaluate the sequence of monadic
- expressions @var{mexp0}..@var{mexp*} as in an @code{mbegin}. When
- @var{condition} is false, return @code{*unspecified*} in the current
- monad. Every expression in the sequence must be a monadic expression.
- @end deffn
- @deffn {Scheme System} munless @var{condition} @var{mexp0} @var{mexp*} ...
- When @var{condition} is false, evaluate the sequence of monadic
- expressions @var{mexp0}..@var{mexp*} as in an @code{mbegin}. When
- @var{condition} is true, return @code{*unspecified*} in the current
- monad. Every expression in the sequence must be a monadic expression.
- @end deffn
- @cindex state monad
- The @code{(guix monads)} module provides the @dfn{state monad}, which
- allows an additional value---the state---to be @emph{threaded} through
- monadic procedure calls.
- @defvr {Scheme Variable} %state-monad
- The state monad. Procedures in the state monad can access and change
- the state that is threaded.
- Consider the example below. The @code{square} procedure returns a value
- in the state monad. It returns the square of its argument, but also
- increments the current state value:
- @lisp
- (define (square x)
- (mlet %state-monad ((count (current-state)))
- (mbegin %state-monad
- (set-current-state (+ 1 count))
- (return (* x x)))))
- (run-with-state (sequence %state-monad (map square (iota 3))) 0)
- @result{} (0 1 4)
- @result{} 3
- @end lisp
- When ``run'' through @code{%state-monad}, we obtain that additional state
- value, which is the number of @code{square} calls.
- @end defvr
- @deffn {Monadic Procedure} current-state
- Return the current state as a monadic value.
- @end deffn
- @deffn {Monadic Procedure} set-current-state @var{value}
- Set the current state to @var{value} and return the previous state as a
- monadic value.
- @end deffn
- @deffn {Monadic Procedure} state-push @var{value}
- Push @var{value} to the current state, which is assumed to be a list,
- and return the previous state as a monadic value.
- @end deffn
- @deffn {Monadic Procedure} state-pop
- Pop a value from the current state and return it as a monadic value.
- The state is assumed to be a list.
- @end deffn
- @deffn {Scheme Procedure} run-with-state @var{mval} [@var{state}]
- Run monadic value @var{mval} starting with @var{state} as the initial
- state. Return two values: the resulting value, and the resulting state.
- @end deffn
- The main interface to the store monad, provided by the @code{(guix
- store)} module, is as follows.
- @defvr {Scheme Variable} %store-monad
- The store monad---an alias for @code{%state-monad}.
- Values in the store monad encapsulate accesses to the store. When its
- effect is needed, a value of the store monad must be ``evaluated'' by
- passing it to the @code{run-with-store} procedure (see below).
- @end defvr
- @deffn {Scheme Procedure} run-with-store @var{store} @var{mval} [#:guile-for-build] [#:system (%current-system)]
- Run @var{mval}, a monadic value in the store monad, in @var{store}, an
- open store connection.
- @end deffn
- @deffn {Monadic Procedure} text-file @var{name} @var{text} [@var{references}]
- Return as a monadic value the absolute file name in the store of the file
- containing @var{text}, a string. @var{references} is a list of store items that the
- resulting text file refers to; it defaults to the empty list.
- @end deffn
- @deffn {Monadic Procedure} binary-file @var{name} @var{data} [@var{references}]
- Return as a monadic value the absolute file name in the store of the file
- containing @var{data}, a bytevector. @var{references} is a list of store
- items that the resulting binary file refers to; it defaults to the empty list.
- @end deffn
- @deffn {Monadic Procedure} interned-file @var{file} [@var{name}] @
- [#:recursive? #t] [#:select? (const #t)]
- Return the name of @var{file} once interned in the store. Use
- @var{name} as its store name, or the basename of @var{file} if
- @var{name} is omitted.
- When @var{recursive?} is true, the contents of @var{file} are added
- recursively; if @var{file} designates a flat file and @var{recursive?}
- is true, its contents are added, and its permission bits are kept.
- When @var{recursive?} is true, call @code{(@var{select?} @var{file}
- @var{stat})} for each directory entry, where @var{file} is the entry's
- absolute file name and @var{stat} is the result of @code{lstat}; exclude
- entries for which @var{select?} does not return true.
- The example below adds a file to the store, under two different names:
- @lisp
- (run-with-store (open-connection)
- (mlet %store-monad ((a (interned-file "README"))
- (b (interned-file "README" "LEGU-MIN")))
- (return (list a b))))
- @result{} ("/gnu/store/rwm@dots{}-README" "/gnu/store/44i@dots{}-LEGU-MIN")
- @end lisp
- @end deffn
- The @code{(guix packages)} module exports the following package-related
- monadic procedures:
- @deffn {Monadic Procedure} package-file @var{package} [@var{file}] @
- [#:system (%current-system)] [#:target #f] @
- [#:output "out"]
- Return as a monadic
- value in the absolute file name of @var{file} within the @var{output}
- directory of @var{package}. When @var{file} is omitted, return the name
- of the @var{output} directory of @var{package}. When @var{target} is
- true, use it as a cross-compilation target triplet.
- Note that this procedure does @emph{not} build @var{package}. Thus, the
- result might or might not designate an existing file. We recommend not
- using this procedure unless you know what you are doing.
- @end deffn
- @deffn {Monadic Procedure} package->derivation @var{package} [@var{system}]
- @deffnx {Monadic Procedure} package->cross-derivation @var{package} @
- @var{target} [@var{system}]
- Monadic version of @code{package-derivation} and
- @code{package-cross-derivation} (@pxref{Defining Packages}).
- @end deffn
- @node G-Expressions
- @section G-Expressions
- @cindex G-expression
- @cindex build code quoting
- So we have ``derivations'', which represent a sequence of build actions
- to be performed to produce an item in the store (@pxref{Derivations}).
- These build actions are performed when asking the daemon to actually
- build the derivations; they are run by the daemon in a container
- (@pxref{Invoking guix-daemon}).
- @cindex code staging
- @cindex staging, of code
- @cindex strata of code
- It should come as no surprise that we like to write these build actions
- in Scheme. When we do that, we end up with two @dfn{strata} of Scheme
- code@footnote{The term @dfn{stratum} in this context was coined by
- Manuel Serrano et al.@: in the context of their work on Hop. Oleg
- Kiselyov, who has written insightful
- @url{http://okmij.org/ftp/meta-programming/#meta-scheme, essays and code
- on this topic}, refers to this kind of code generation as
- @dfn{staging}.}: the ``host code''---code that defines packages, talks
- to the daemon, etc.---and the ``build code''---code that actually
- performs build actions, such as making directories, invoking
- @command{make}, and so on (@pxref{Build Phases}).
- To describe a derivation and its build actions, one typically needs to
- embed build code inside host code. It boils down to manipulating build
- code as data, and the homoiconicity of Scheme---code has a direct
- representation as data---comes in handy for that. But we need more than
- the normal @code{quasiquote} mechanism in Scheme to construct build
- expressions.
- The @code{(guix gexp)} module implements @dfn{G-expressions}, a form of
- S-expressions adapted to build expressions. G-expressions, or
- @dfn{gexps}, consist essentially of three syntactic forms: @code{gexp},
- @code{ungexp}, and @code{ungexp-splicing} (or simply: @code{#~},
- @code{#$}, and @code{#$@@}), which are comparable to
- @code{quasiquote}, @code{unquote}, and @code{unquote-splicing},
- respectively (@pxref{Expression Syntax, @code{quasiquote},, guile,
- GNU Guile Reference Manual}). However, there are major differences:
- @itemize
- @item
- Gexps are meant to be written to a file and run or manipulated by other
- processes.
- @item
- When a high-level object such as a package or derivation is unquoted
- inside a gexp, the result is as if its output file name had been
- introduced.
- @item
- Gexps carry information about the packages or derivations they refer to,
- and these dependencies are automatically added as inputs to the build
- processes that use them.
- @end itemize
- @cindex lowering, of high-level objects in gexps
- This mechanism is not limited to package and derivation
- objects: @dfn{compilers} able to ``lower'' other high-level objects to
- derivations or files in the store can be defined,
- such that these objects can also be inserted
- into gexps. For example, a useful type of high-level objects that can be
- inserted in a gexp is ``file-like objects'', which make it easy to
- add files to the store and to refer to them in
- derivations and such (see @code{local-file} and @code{plain-file}
- below).
- To illustrate the idea, here is an example of a gexp:
- @lisp
- (define build-exp
- #~(begin
- (mkdir #$output)
- (chdir #$output)
- (symlink (string-append #$coreutils "/bin/ls")
- "list-files")))
- @end lisp
- This gexp can be passed to @code{gexp->derivation}; we obtain a
- derivation that builds a directory containing exactly one symlink to
- @file{/gnu/store/@dots{}-coreutils-8.22/bin/ls}:
- @lisp
- (gexp->derivation "the-thing" build-exp)
- @end lisp
- As one would expect, the @code{"/gnu/store/@dots{}-coreutils-8.22"} string is
- substituted to the reference to the @var{coreutils} package in the
- actual build code, and @var{coreutils} is automatically made an input to
- the derivation. Likewise, @code{#$output} (equivalent to @code{(ungexp
- output)}) is replaced by a string containing the directory name of the
- output of the derivation.
- @cindex cross compilation
- In a cross-compilation context, it is useful to distinguish between
- references to the @emph{native} build of a package---that can run on the
- host---versus references to cross builds of a package. To that end, the
- @code{#+} plays the same role as @code{#$}, but is a reference to a
- native package build:
- @lisp
- (gexp->derivation "vi"
- #~(begin
- (mkdir #$output)
- (mkdir (string-append #$output "/bin"))
- (system* (string-append #+coreutils "/bin/ln")
- "-s"
- (string-append #$emacs "/bin/emacs")
- (string-append #$output "/bin/vi")))
- #:target "aarch64-linux-gnu")
- @end lisp
- @noindent
- In the example above, the native build of @var{coreutils} is used, so
- that @command{ln} can actually run on the host; but then the
- cross-compiled build of @var{emacs} is referenced.
- @cindex imported modules, for gexps
- @findex with-imported-modules
- Another gexp feature is @dfn{imported modules}: sometimes you want to be
- able to use certain Guile modules from the ``host environment'' in the
- gexp, so those modules should be imported in the ``build environment''.
- The @code{with-imported-modules} form allows you to express that:
- @lisp
- (let ((build (with-imported-modules '((guix build utils))
- #~(begin
- (use-modules (guix build utils))
- (mkdir-p (string-append #$output "/bin"))))))
- (gexp->derivation "empty-dir"
- #~(begin
- #$build
- (display "success!\n")
- #t)))
- @end lisp
- @noindent
- In this example, the @code{(guix build utils)} module is automatically
- pulled into the isolated build environment of our gexp, such that
- @code{(use-modules (guix build utils))} works as expected.
- @cindex module closure
- @findex source-module-closure
- Usually you want the @emph{closure} of the module to be imported---i.e.,
- the module itself and all the modules it depends on---rather than just
- the module; failing to do that, attempts to use the module will fail
- because of missing dependent modules. The @code{source-module-closure}
- procedure computes the closure of a module by looking at its source file
- headers, which comes in handy in this case:
- @lisp
- (use-modules (guix modules)) ;for 'source-module-closure'
- (with-imported-modules (source-module-closure
- '((guix build utils)
- (gnu build image)))
- (gexp->derivation "something-with-vms"
- #~(begin
- (use-modules (guix build utils)
- (gnu build image))
- @dots{})))
- @end lisp
- @cindex extensions, for gexps
- @findex with-extensions
- In the same vein, sometimes you want to import not just pure-Scheme
- modules, but also ``extensions'' such as Guile bindings to C libraries
- or other ``full-blown'' packages. Say you need the @code{guile-json}
- package available on the build side, here's how you would do it:
- @lisp
- (use-modules (gnu packages guile)) ;for 'guile-json'
- (with-extensions (list guile-json)
- (gexp->derivation "something-with-json"
- #~(begin
- (use-modules (json))
- @dots{})))
- @end lisp
- The syntactic form to construct gexps is summarized below.
- @deffn {Scheme Syntax} #~@var{exp}
- @deffnx {Scheme Syntax} (gexp @var{exp})
- Return a G-expression containing @var{exp}. @var{exp} may contain one
- or more of the following forms:
- @table @code
- @item #$@var{obj}
- @itemx (ungexp @var{obj})
- Introduce a reference to @var{obj}. @var{obj} may have one of the
- supported types, for example a package or a
- derivation, in which case the @code{ungexp} form is replaced by its
- output file name---e.g., @code{"/gnu/store/@dots{}-coreutils-8.22}.
- If @var{obj} is a list, it is traversed and references to supported
- objects are substituted similarly.
- If @var{obj} is another gexp, its contents are inserted and its
- dependencies are added to those of the containing gexp.
- If @var{obj} is another kind of object, it is inserted as is.
- @item #$@var{obj}:@var{output}
- @itemx (ungexp @var{obj} @var{output})
- This is like the form above, but referring explicitly to the
- @var{output} of @var{obj}---this is useful when @var{obj} produces
- multiple outputs (@pxref{Packages with Multiple Outputs}).
- @item #+@var{obj}
- @itemx #+@var{obj}:output
- @itemx (ungexp-native @var{obj})
- @itemx (ungexp-native @var{obj} @var{output})
- Same as @code{ungexp}, but produces a reference to the @emph{native}
- build of @var{obj} when used in a cross compilation context.
- @item #$output[:@var{output}]
- @itemx (ungexp output [@var{output}])
- Insert a reference to derivation output @var{output}, or to the main
- output when @var{output} is omitted.
- This only makes sense for gexps passed to @code{gexp->derivation}.
- @item #$@@@var{lst}
- @itemx (ungexp-splicing @var{lst})
- Like the above, but splices the contents of @var{lst} inside the
- containing list.
- @item #+@@@var{lst}
- @itemx (ungexp-native-splicing @var{lst})
- Like the above, but refers to native builds of the objects listed in
- @var{lst}.
- @end table
- G-expressions created by @code{gexp} or @code{#~} are run-time objects
- of the @code{gexp?} type (see below).
- @end deffn
- @deffn {Scheme Syntax} with-imported-modules @var{modules} @var{body}@dots{}
- Mark the gexps defined in @var{body}@dots{} as requiring @var{modules}
- in their execution environment.
- Each item in @var{modules} can be the name of a module, such as
- @code{(guix build utils)}, or it can be a module name, followed by an
- arrow, followed by a file-like object:
- @lisp
- `((guix build utils)
- (guix gcrypt)
- ((guix config) => ,(scheme-file "config.scm"
- #~(define-module @dots{}))))
- @end lisp
- @noindent
- In the example above, the first two modules are taken from the search
- path, and the last one is created from the given file-like object.
- This form has @emph{lexical} scope: it has an effect on the gexps
- directly defined in @var{body}@dots{}, but not on those defined, say, in
- procedures called from @var{body}@dots{}.
- @end deffn
- @deffn {Scheme Syntax} with-extensions @var{extensions} @var{body}@dots{}
- Mark the gexps defined in @var{body}@dots{} as requiring
- @var{extensions} in their build and execution environment.
- @var{extensions} is typically a list of package objects such as those
- defined in the @code{(gnu packages guile)} module.
- Concretely, the packages listed in @var{extensions} are added to the
- load path while compiling imported modules in @var{body}@dots{}; they
- are also added to the load path of the gexp returned by
- @var{body}@dots{}.
- @end deffn
- @deffn {Scheme Procedure} gexp? @var{obj}
- Return @code{#t} if @var{obj} is a G-expression.
- @end deffn
- G-expressions are meant to be written to disk, either as code building
- some derivation, or as plain files in the store. The monadic procedures
- below allow you to do that (@pxref{The Store Monad}, for more
- information about monads).
- @deffn {Monadic Procedure} gexp->derivation @var{name} @var{exp} @
- [#:system (%current-system)] [#:target #f] [#:graft? #t] @
- [#:hash #f] [#:hash-algo #f] @
- [#:recursive? #f] [#:env-vars '()] [#:modules '()] @
- [#:module-path @code{%load-path}] @
- [#:effective-version "2.2"] @
- [#:references-graphs #f] [#:allowed-references #f] @
- [#:disallowed-references #f] @
- [#:leaked-env-vars #f] @
- [#:script-name (string-append @var{name} "-builder")] @
- [#:deprecation-warnings #f] @
- [#:local-build? #f] [#:substitutable? #t] @
- [#:properties '()] [#:guile-for-build #f]
- Return a derivation @var{name} that runs @var{exp} (a gexp) with
- @var{guile-for-build} (a derivation) on @var{system}; @var{exp} is
- stored in a file called @var{script-name}. When @var{target} is true,
- it is used as the cross-compilation target triplet for packages referred
- to by @var{exp}.
- @var{modules} is deprecated in favor of @code{with-imported-modules}.
- Its meaning is to
- make @var{modules} available in the evaluation context of @var{exp};
- @var{modules} is a list of names of Guile modules searched in
- @var{module-path} to be copied in the store, compiled, and made available in
- the load path during the execution of @var{exp}---e.g., @code{((guix
- build utils) (guix build gnu-build-system))}.
- @var{effective-version} determines the string to use when adding extensions of
- @var{exp} (see @code{with-extensions}) to the search path---e.g., @code{"2.2"}.
- @var{graft?} determines whether packages referred to by @var{exp} should be grafted when
- applicable.
- When @var{references-graphs} is true, it must be a list of tuples of one of the
- following forms:
- @example
- (@var{file-name} @var{package})
- (@var{file-name} @var{package} @var{output})
- (@var{file-name} @var{derivation})
- (@var{file-name} @var{derivation} @var{output})
- (@var{file-name} @var{store-item})
- @end example
- The right-hand-side of each element of @var{references-graphs} is automatically made
- an input of the build process of @var{exp}. In the build environment, each
- @var{file-name} contains the reference graph of the corresponding item, in a simple
- text format.
- @var{allowed-references} must be either @code{#f} or a list of output names and packages.
- In the latter case, the list denotes store items that the result is allowed to
- refer to. Any reference to another store item will lead to a build error.
- Similarly for @var{disallowed-references}, which can list items that must not be
- referenced by the outputs.
- @var{deprecation-warnings} determines whether to show deprecation warnings while
- compiling modules. It can be @code{#f}, @code{#t}, or @code{'detailed}.
- The other arguments are as for @code{derivation} (@pxref{Derivations}).
- @end deffn
- @cindex file-like objects
- The @code{local-file}, @code{plain-file}, @code{computed-file},
- @code{program-file}, and @code{scheme-file} procedures below return
- @dfn{file-like objects}. That is, when unquoted in a G-expression,
- these objects lead to a file in the store. Consider this G-expression:
- @lisp
- #~(system* #$(file-append glibc "/sbin/nscd") "-f"
- #$(local-file "/tmp/my-nscd.conf"))
- @end lisp
- The effect here is to ``intern'' @file{/tmp/my-nscd.conf} by copying it
- to the store. Once expanded, for instance @i{via}
- @code{gexp->derivation}, the G-expression refers to that copy under
- @file{/gnu/store}; thus, modifying or removing the file in @file{/tmp}
- does not have any effect on what the G-expression does.
- @code{plain-file} can be used similarly; it differs in that the file
- content is directly passed as a string.
- @deffn {Scheme Procedure} local-file @var{file} [@var{name}] @
- [#:recursive? #f] [#:select? (const #t)]
- Return an object representing local file @var{file} to add to the store;
- this object can be used in a gexp. If @var{file} is a literal string
- denoting a relative file name, it is looked up relative to the source
- file where it appears; if @var{file} is not a literal string, it is
- looked up relative to the current working directory at run time.
- @var{file} will be added to the store under @var{name}--by default the
- base name of @var{file}.
- When @var{recursive?} is true, the contents of @var{file} are added recursively; if @var{file}
- designates a flat file and @var{recursive?} is true, its contents are added, and its
- permission bits are kept.
- When @var{recursive?} is true, call @code{(@var{select?} @var{file}
- @var{stat})} for each directory entry, where @var{file} is the entry's
- absolute file name and @var{stat} is the result of @code{lstat}; exclude
- entries for which @var{select?} does not return true.
- This is the declarative counterpart of the @code{interned-file} monadic
- procedure (@pxref{The Store Monad, @code{interned-file}}).
- @end deffn
- @deffn {Scheme Procedure} plain-file @var{name} @var{content}
- Return an object representing a text file called @var{name} with the given
- @var{content} (a string or a bytevector) to be added to the store.
- This is the declarative counterpart of @code{text-file}.
- @end deffn
- @deffn {Scheme Procedure} computed-file @var{name} @var{gexp} @
- [#:local-build? #t]
- [#:options '()]
- Return an object representing the store item @var{name}, a file or
- directory computed by @var{gexp}. When @var{local-build?} is true (the
- default), the derivation is built locally. @var{options} is a list of
- additional arguments to pass to @code{gexp->derivation}.
- This is the declarative counterpart of @code{gexp->derivation}.
- @end deffn
- @deffn {Monadic Procedure} gexp->script @var{name} @var{exp} @
- [#:guile (default-guile)] [#:module-path %load-path] @
- [#:system (%current-system)] [#:target #f]
- Return an executable script @var{name} that runs @var{exp} using
- @var{guile}, with @var{exp}'s imported modules in its search path.
- Look up @var{exp}'s modules in @var{module-path}.
- The example below builds a script that simply invokes the @command{ls}
- command:
- @lisp
- (use-modules (guix gexp) (gnu packages base))
- (gexp->script "list-files"
- #~(execl #$(file-append coreutils "/bin/ls")
- "ls"))
- @end lisp
- When ``running'' it through the store (@pxref{The Store Monad,
- @code{run-with-store}}), we obtain a derivation that produces an
- executable file @file{/gnu/store/@dots{}-list-files} along these lines:
- @example
- #!/gnu/store/@dots{}-guile-2.0.11/bin/guile -ds
- !#
- (execl "/gnu/store/@dots{}-coreutils-8.22"/bin/ls" "ls")
- @end example
- @end deffn
- @deffn {Scheme Procedure} program-file @var{name} @var{exp} @
- [#:guile #f] [#:module-path %load-path]
- Return an object representing the executable store item @var{name} that
- runs @var{gexp}. @var{guile} is the Guile package used to execute that
- script. Imported modules of @var{gexp} are looked up in @var{module-path}.
- This is the declarative counterpart of @code{gexp->script}.
- @end deffn
- @deffn {Monadic Procedure} gexp->file @var{name} @var{exp} @
- [#:set-load-path? #t] [#:module-path %load-path] @
- [#:splice? #f] @
- [#:guile (default-guile)]
- Return a derivation that builds a file @var{name} containing @var{exp}.
- When @var{splice?} is true, @var{exp} is considered to be a list of
- expressions that will be spliced in the resulting file.
- When @var{set-load-path?} is true, emit code in the resulting file to
- set @code{%load-path} and @code{%load-compiled-path} to honor
- @var{exp}'s imported modules. Look up @var{exp}'s modules in
- @var{module-path}.
- The resulting file holds references to all the dependencies of @var{exp}
- or a subset thereof.
- @end deffn
- @deffn {Scheme Procedure} scheme-file @var{name} @var{exp} @
- [#:splice? #f] [#:set-load-path? #t]
- Return an object representing the Scheme file @var{name} that contains
- @var{exp}.
- This is the declarative counterpart of @code{gexp->file}.
- @end deffn
- @deffn {Monadic Procedure} text-file* @var{name} @var{text} @dots{}
- Return as a monadic value a derivation that builds a text file
- containing all of @var{text}. @var{text} may list, in addition to
- strings, objects of any type that can be used in a gexp: packages,
- derivations, local file objects, etc. The resulting store file holds
- references to all these.
- This variant should be preferred over @code{text-file} anytime the file
- to create will reference items from the store. This is typically the
- case when building a configuration file that embeds store file names,
- like this:
- @lisp
- (define (profile.sh)
- ;; Return the name of a shell script in the store that
- ;; initializes the 'PATH' environment variable.
- (text-file* "profile.sh"
- "export PATH=" coreutils "/bin:"
- grep "/bin:" sed "/bin\n"))
- @end lisp
- In this example, the resulting @file{/gnu/store/@dots{}-profile.sh} file
- will reference @var{coreutils}, @var{grep}, and @var{sed}, thereby
- preventing them from being garbage-collected during its lifetime.
- @end deffn
- @deffn {Scheme Procedure} mixed-text-file @var{name} @var{text} @dots{}
- Return an object representing store file @var{name} containing
- @var{text}. @var{text} is a sequence of strings and file-like objects,
- as in:
- @lisp
- (mixed-text-file "profile"
- "export PATH=" coreutils "/bin:" grep "/bin")
- @end lisp
- This is the declarative counterpart of @code{text-file*}.
- @end deffn
- @deffn {Scheme Procedure} file-union @var{name} @var{files}
- Return a @code{<computed-file>} that builds a directory containing all of @var{files}.
- Each item in @var{files} must be a two-element list where the first element is the
- file name to use in the new directory, and the second element is a gexp
- denoting the target file. Here's an example:
- @lisp
- (file-union "etc"
- `(("hosts" ,(plain-file "hosts"
- "127.0.0.1 localhost"))
- ("bashrc" ,(plain-file "bashrc"
- "alias ls='ls --color=auto'"))))
- @end lisp
- This yields an @code{etc} directory containing these two files.
- @end deffn
- @deffn {Scheme Procedure} directory-union @var{name} @var{things}
- Return a directory that is the union of @var{things}, where @var{things} is a list of
- file-like objects denoting directories. For example:
- @lisp
- (directory-union "guile+emacs" (list guile emacs))
- @end lisp
- yields a directory that is the union of the @code{guile} and @code{emacs} packages.
- @end deffn
- @deffn {Scheme Procedure} file-append @var{obj} @var{suffix} @dots{}
- Return a file-like object that expands to the concatenation of @var{obj}
- and @var{suffix}, where @var{obj} is a lowerable object and each
- @var{suffix} is a string.
- As an example, consider this gexp:
- @lisp
- (gexp->script "run-uname"
- #~(system* #$(file-append coreutils
- "/bin/uname")))
- @end lisp
- The same effect could be achieved with:
- @lisp
- (gexp->script "run-uname"
- #~(system* (string-append #$coreutils
- "/bin/uname")))
- @end lisp
- There is one difference though: in the @code{file-append} case, the
- resulting script contains the absolute file name as a string, whereas in
- the second case, the resulting script contains a @code{(string-append
- @dots{})} expression to construct the file name @emph{at run time}.
- @end deffn
- @deffn {Scheme Syntax} let-system @var{system} @var{body}@dots{}
- @deffnx {Scheme Syntax} let-system (@var{system} @var{target}) @var{body}@dots{}
- Bind @var{system} to the currently targeted system---e.g.,
- @code{"x86_64-linux"}---within @var{body}.
- In the second case, additionally bind @var{target} to the current
- cross-compilation target---a GNU triplet such as
- @code{"arm-linux-gnueabihf"}---or @code{#f} if we are not
- cross-compiling.
- @code{let-system} is useful in the occasional case where the object
- spliced into the gexp depends on the target system, as in this example:
- @lisp
- #~(system*
- #+(let-system system
- (cond ((string-prefix? "armhf-" system)
- (file-append qemu "/bin/qemu-system-arm"))
- ((string-prefix? "x86_64-" system)
- (file-append qemu "/bin/qemu-system-x86_64"))
- (else
- (error "dunno!"))))
- "-net" "user" #$image)
- @end lisp
- @end deffn
- @deffn {Scheme Syntax} with-parameters ((@var{parameter} @var{value}) @dots{}) @var{exp}
- This macro is similar to the @code{parameterize} form for
- dynamically-bound @dfn{parameters} (@pxref{Parameters,,, guile, GNU
- Guile Reference Manual}). The key difference is that it takes effect
- when the file-like object returned by @var{exp} is lowered to a
- derivation or store item.
- A typical use of @code{with-parameters} is to force the system in effect
- for a given object:
- @lisp
- (with-parameters ((%current-system "i686-linux"))
- coreutils)
- @end lisp
- The example above returns an object that corresponds to the i686 build
- of Coreutils, regardless of the current value of @code{%current-system}.
- @end deffn
- Of course, in addition to gexps embedded in ``host'' code, there are
- also modules containing build tools. To make it clear that they are
- meant to be used in the build stratum, these modules are kept in the
- @code{(guix build @dots{})} name space.
- @cindex lowering, of high-level objects in gexps
- Internally, high-level objects are @dfn{lowered}, using their compiler,
- to either derivations or store items. For instance, lowering a package
- yields a derivation, and lowering a @code{plain-file} yields a store
- item. This is achieved using the @code{lower-object} monadic procedure.
- @deffn {Monadic Procedure} lower-object @var{obj} [@var{system}] @
- [#:target #f]
- Return as a value in @code{%store-monad} the derivation or store item
- corresponding to @var{obj} for @var{system}, cross-compiling for
- @var{target} if @var{target} is true. @var{obj} must be an object that
- has an associated gexp compiler, such as a @code{<package>}.
- @end deffn
- @deffn {Procedure} gexp->approximate-sexp @var{gexp}
- Sometimes, it may be useful to convert a G-exp into a S-exp. For
- example, some linters (@pxref{Invoking guix lint}) peek into the build
- phases of a package to detect potential problems. This conversion can
- be achieved with this procedure. However, some information can be lost
- in the process. More specifically, lowerable objects will be silently
- replaced with some arbitrary object -- currently the list
- @code{(*approximate*)}, but this may change.
- @end deffn
- @node Invoking guix repl
- @section Invoking @command{guix repl}
- @cindex REPL, read-eval-print loop, script
- The @command{guix repl} command makes it easier to program Guix in Guile
- by launching a Guile @dfn{read-eval-print loop} (REPL) for interactive
- programming (@pxref{Using Guile Interactively,,, guile,
- GNU Guile Reference Manual}), or by running Guile scripts
- (@pxref{Running Guile Scripts,,, guile,
- GNU Guile Reference Manual}).
- Compared to just launching the @command{guile}
- command, @command{guix repl} guarantees that all the Guix modules and all its
- dependencies are available in the search path.
- The general syntax is:
- @example
- guix repl @var{options} [@var{file} @var{args}]
- @end example
- When a @var{file} argument is provided, @var{file} is
- executed as a Guile scripts:
- @example
- guix repl my-script.scm
- @end example
- To pass arguments to the script, use @code{--} to prevent them from
- being interpreted as arguments to @command{guix repl} itself:
- @example
- guix repl -- my-script.scm --input=foo.txt
- @end example
- To make a script executable directly from the shell, using the guix
- executable that is on the user's search path, add the following two
- lines at the top of the script:
- @example
- @code{#!/usr/bin/env -S guix repl --}
- @code{!#}
- @end example
- Without a file name argument, a Guile REPL is started:
- @example
- $ guix repl
- scheme@@(guile-user)> ,use (gnu packages base)
- scheme@@(guile-user)> coreutils
- $1 = #<package coreutils@@8.29 gnu/packages/base.scm:327 3e28300>
- @end example
- @cindex inferiors
- In addition, @command{guix repl} implements a simple machine-readable REPL
- protocol for use by @code{(guix inferior)}, a facility to interact with
- @dfn{inferiors}, separate processes running a potentially different revision
- of Guix.
- The available options are as follows:
- @table @code
- @item --type=@var{type}
- @itemx -t @var{type}
- Start a REPL of the given @var{TYPE}, which can be one of the following:
- @table @code
- @item guile
- This is default, and it spawns a standard full-featured Guile REPL.
- @item machine
- Spawn a REPL that uses the machine-readable protocol. This is the protocol
- that the @code{(guix inferior)} module speaks.
- @end table
- @item --listen=@var{endpoint}
- By default, @command{guix repl} reads from standard input and writes to
- standard output. When this option is passed, it will instead listen for
- connections on @var{endpoint}. Here are examples of valid options:
- @table @code
- @item --listen=tcp:37146
- Accept connections on localhost on port 37146.
- @item --listen=unix:/tmp/socket
- Accept connections on the Unix-domain socket @file{/tmp/socket}.
- @end table
- @item --load-path=@var{directory}
- @itemx -L @var{directory}
- Add @var{directory} to the front of the package module search path
- (@pxref{Package Modules}).
- This allows users to define their own packages and make them visible to
- the script or REPL.
- @item -q
- Inhibit loading of the @file{~/.guile} file. By default, that
- configuration file is loaded when spawning a @code{guile} REPL.
- @end table
- @c *********************************************************************
- @node Utilities
- @chapter Utilities
- This section describes Guix command-line utilities. Some of them are
- primarily targeted at developers and users who write new package
- definitions, while others are more generally useful. They complement
- the Scheme programming interface of Guix in a convenient way.
- @menu
- * Invoking guix build:: Building packages from the command line.
- * Invoking guix edit:: Editing package definitions.
- * Invoking guix download:: Downloading a file and printing its hash.
- * Invoking guix hash:: Computing the cryptographic hash of a file.
- * Invoking guix import:: Importing package definitions.
- * Invoking guix refresh:: Updating package definitions.
- * Invoking guix style:: Styling package definitions.
- * Invoking guix lint:: Finding errors in package definitions.
- * Invoking guix size:: Profiling disk usage.
- * Invoking guix graph:: Visualizing the graph of packages.
- * Invoking guix publish:: Sharing substitutes.
- * Invoking guix challenge:: Challenging substitute servers.
- * Invoking guix copy:: Copying to and from a remote store.
- * Invoking guix container:: Process isolation.
- * Invoking guix weather:: Assessing substitute availability.
- * Invoking guix processes:: Listing client processes.
- @end menu
- @node Invoking guix build
- @section Invoking @command{guix build}
- @cindex package building
- @cindex @command{guix build}
- The @command{guix build} command builds packages or derivations and
- their dependencies, and prints the resulting store paths. Note that it
- does not modify the user's profile---this is the job of the
- @command{guix package} command (@pxref{Invoking guix package}). Thus,
- it is mainly useful for distribution developers.
- The general syntax is:
- @example
- guix build @var{options} @var{package-or-derivation}@dots{}
- @end example
- As an example, the following command builds the latest versions of Emacs
- and of Guile, displays their build logs, and finally displays the
- resulting directories:
- @example
- guix build emacs guile
- @end example
- Similarly, the following command builds all the available packages:
- @example
- guix build --quiet --keep-going \
- $(guix package -A | awk '@{ print $1 "@@" $2 @}')
- @end example
- @var{package-or-derivation} may be either the name of a package found in
- the software distribution such as @code{coreutils} or
- @code{coreutils@@8.20}, or a derivation such as
- @file{/gnu/store/@dots{}-coreutils-8.19.drv}. In the former case, a
- package with the corresponding name (and optionally version) is searched
- for among the GNU distribution modules (@pxref{Package Modules}).
- Alternatively, the @option{--expression} option may be used to specify a
- Scheme expression that evaluates to a package; this is useful when
- disambiguating among several same-named packages or package variants is
- needed.
- There may be zero or more @var{options}. The available options are
- described in the subsections below.
- @menu
- * Common Build Options:: Build options for most commands.
- * Package Transformation Options:: Creating variants of packages.
- * Additional Build Options:: Options specific to 'guix build'.
- * Debugging Build Failures:: Real life packaging experience.
- @end menu
- @node Common Build Options
- @subsection Common Build Options
- A number of options that control the build process are common to
- @command{guix build} and other commands that can spawn builds, such as
- @command{guix package} or @command{guix archive}. These are the
- following:
- @table @code
- @item --load-path=@var{directory}
- @itemx -L @var{directory}
- Add @var{directory} to the front of the package module search path
- (@pxref{Package Modules}).
- This allows users to define their own packages and make them visible to
- the command-line tools.
- @item --keep-failed
- @itemx -K
- Keep the build tree of failed builds. Thus, if a build fails, its build
- tree is kept under @file{/tmp}, in a directory whose name is shown at
- the end of the build log. This is useful when debugging build issues.
- @xref{Debugging Build Failures}, for tips and tricks on how to debug
- build issues.
- This option implies @option{--no-offload}, and it has no effect when
- connecting to a remote daemon with a @code{guix://} URI (@pxref{The
- Store, the @env{GUIX_DAEMON_SOCKET} variable}).
- @item --keep-going
- @itemx -k
- Keep going when some of the derivations fail to build; return only once
- all the builds have either completed or failed.
- The default behavior is to stop as soon as one of the specified
- derivations has failed.
- @item --dry-run
- @itemx -n
- Do not build the derivations.
- @anchor{fallback-option}
- @item --fallback
- When substituting a pre-built binary fails, fall back to building
- packages locally (@pxref{Substitution Failure}).
- @item --substitute-urls=@var{urls}
- @anchor{client-substitute-urls}
- Consider @var{urls} the whitespace-separated list of substitute source
- URLs, overriding the default list of URLs of @command{guix-daemon}
- (@pxref{daemon-substitute-urls,, @command{guix-daemon} URLs}).
- This means that substitutes may be downloaded from @var{urls}, provided
- they are signed by a key authorized by the system administrator
- (@pxref{Substitutes}).
- When @var{urls} is the empty string, substitutes are effectively
- disabled.
- @item --no-substitutes
- Do not use substitutes for build products. That is, always build things
- locally instead of allowing downloads of pre-built binaries
- (@pxref{Substitutes}).
- @item --no-grafts
- Do not ``graft'' packages. In practice, this means that package updates
- available as grafts are not applied. @xref{Security Updates}, for more
- information on grafts.
- @item --rounds=@var{n}
- Build each derivation @var{n} times in a row, and raise an error if
- consecutive build results are not bit-for-bit identical.
- This is a useful way to detect non-deterministic builds processes.
- Non-deterministic build processes are a problem because they make it
- practically impossible for users to @emph{verify} whether third-party
- binaries are genuine. @xref{Invoking guix challenge}, for more.
- When used in conjunction with @option{--keep-failed}, the differing
- output is kept in the store, under @file{/gnu/store/@dots{}-check}.
- This makes it easy to look for differences between the two results.
- @item --no-offload
- Do not use offload builds to other machines (@pxref{Daemon Offload
- Setup}). That is, always build things locally instead of offloading
- builds to remote machines.
- @item --max-silent-time=@var{seconds}
- When the build or substitution process remains silent for more than
- @var{seconds}, terminate it and report a build failure.
- By default, the daemon's setting is honored (@pxref{Invoking
- guix-daemon, @option{--max-silent-time}}).
- @item --timeout=@var{seconds}
- Likewise, when the build or substitution process lasts for more than
- @var{seconds}, terminate it and report a build failure.
- By default, the daemon's setting is honored (@pxref{Invoking
- guix-daemon, @option{--timeout}}).
- @c Note: This option is actually not part of %standard-build-options but
- @c most programs honor it.
- @cindex verbosity, of the command-line tools
- @cindex build logs, verbosity
- @item -v @var{level}
- @itemx --verbosity=@var{level}
- Use the given verbosity @var{level}, an integer. Choosing 0 means that
- no output is produced, 1 is for quiet output; 2 is similar to 1 but it
- additionally displays download URLs; 3 shows all the build log output on
- standard error.
- @item --cores=@var{n}
- @itemx -c @var{n}
- Allow the use of up to @var{n} CPU cores for the build. The special
- value @code{0} means to use as many CPU cores as available.
- @item --max-jobs=@var{n}
- @itemx -M @var{n}
- Allow at most @var{n} build jobs in parallel. @xref{Invoking
- guix-daemon, @option{--max-jobs}}, for details about this option and the
- equivalent @command{guix-daemon} option.
- @item --debug=@var{level}
- Produce debugging output coming from the build daemon. @var{level} must be an
- integer between 0 and 5; higher means more verbose output. Setting a level of
- 4 or more may be helpful when debugging setup issues with the build daemon.
- @end table
- Behind the scenes, @command{guix build} is essentially an interface to
- the @code{package-derivation} procedure of the @code{(guix packages)}
- module, and to the @code{build-derivations} procedure of the @code{(guix
- derivations)} module.
- In addition to options explicitly passed on the command line,
- @command{guix build} and other @command{guix} commands that support
- building honor the @env{GUIX_BUILD_OPTIONS} environment variable.
- @defvr {Environment Variable} GUIX_BUILD_OPTIONS
- Users can define this variable to a list of command line options that
- will automatically be used by @command{guix build} and other
- @command{guix} commands that can perform builds, as in the example
- below:
- @example
- $ export GUIX_BUILD_OPTIONS="--no-substitutes -c 2 -L /foo/bar"
- @end example
- These options are parsed independently, and the result is appended to
- the parsed command-line options.
- @end defvr
- @node Package Transformation Options
- @subsection Package Transformation Options
- @cindex package variants
- Another set of command-line options supported by @command{guix build}
- and also @command{guix package} are @dfn{package transformation
- options}. These are options that make it possible to define @dfn{package
- variants}---for instance, packages built from different source code.
- This is a convenient way to create customized packages on the fly
- without having to type in the definitions of package variants
- (@pxref{Defining Packages}).
- Package transformation options are preserved across upgrades:
- @command{guix upgrade} attempts to apply transformation options
- initially used when creating the profile to the upgraded packages.
- The available options are listed below. Most commands support them and
- also support a @option{--help-transform} option that lists all the
- available options and a synopsis (these options are not shown in the
- @option{--help} output for brevity).
- @table @code
- @cindex performance, tuning code
- @cindex optimization, of package code
- @cindex tuning, of package code
- @cindex SIMD support
- @cindex tunable packages
- @cindex package multi-versioning
- @item --tune[=@var{cpu}]
- Use versions of the packages marked as ``tunable'' optimized for
- @var{cpu}. When @var{cpu} is @code{native}, or when it is omitted, tune
- for the CPU on which the @command{guix} command is running.
- Valid @var{cpu} names are those recognized by the underlying compiler,
- by default the GNU Compiler Collection. On x86_64 processors, this
- includes CPU names such as @code{nehalem}, @code{haswell}, and
- @code{skylake} (@pxref{x86 Options, @code{-march},, gcc, Using the GNU
- Compiler Collection (GCC)}).
- As new generations of CPUs come out, they augment the standard
- instruction set architecture (ISA) with additional instructions, in
- particular instructions for single-instruction/multiple-data (SIMD)
- parallel processing. For example, while Core2 and Skylake CPUs both
- implement the x86_64 ISA, only the latter supports AVX2 SIMD
- instructions.
- The primary gain one can expect from @option{--tune} is for programs
- that can make use of those SIMD capabilities @emph{and} that do not
- already have a mechanism to select the right optimized code at run time.
- Packages that have the @code{tunable?} property set are considered
- @dfn{tunable packages} by the @option{--tune} option; a package
- definition with the property set looks like this:
- @lisp
- (package
- (name "hello-simd")
- ;; ...
- ;; This package may benefit from SIMD extensions so
- ;; mark it as "tunable".
- (properties '((tunable? . #t))))
- @end lisp
- Other packages are not considered tunable. This allows Guix to use
- generic binaries in the cases where tuning for a specific CPU is
- unlikely to provide any gain.
- Tuned packages are built with @code{-march=@var{CPU}}; under the hood,
- the @option{-march} option is passed to the actual wrapper by a compiler
- wrapper. Since the build machine may not be able to run code for the
- target CPU micro-architecture, the test suite is not run when building a
- tuned package.
- To reduce rebuilds to the minimum, tuned packages are @emph{grafted}
- onto packages that depend on them (@pxref{Security Updates, grafts}).
- Thus, using @option{--no-grafts} cancels the effect of @option{--tune}.
- We call this technique @dfn{package multi-versioning}: several variants
- of tunable packages may be built, one for each CPU variant. It is the
- coarse-grain counterpart of @dfn{function multi-versioning} as
- implemented by the GNU tool chain (@pxref{Function Multiversioning,,,
- gcc, Using the GNU Compiler Collection (GCC)}).
- @item --with-source=@var{source}
- @itemx --with-source=@var{package}=@var{source}
- @itemx --with-source=@var{package}@@@var{version}=@var{source}
- Use @var{source} as the source of @var{package}, and @var{version} as
- its version number.
- @var{source} must be a file name or a URL, as for @command{guix
- download} (@pxref{Invoking guix download}).
- When @var{package} is omitted,
- it is taken to be the package name specified on the
- command line that matches the base of @var{source}---e.g.,
- if @var{source} is @code{/src/guile-2.0.10.tar.gz}, the corresponding
- package is @code{guile}.
- Likewise, when @var{version} is omitted, the version string is inferred from
- @var{source}; in the previous example, it is @code{2.0.10}.
- This option allows users to try out versions of packages other than the
- one provided by the distribution. The example below downloads
- @file{ed-1.7.tar.gz} from a GNU mirror and uses that as the source for
- the @code{ed} package:
- @example
- guix build ed --with-source=mirror://gnu/ed/ed-1.7.tar.gz
- @end example
- As a developer, @option{--with-source} makes it easy to test release
- candidates:
- @example
- guix build guile --with-source=../guile-2.0.9.219-e1bb7.tar.xz
- @end example
- @dots{} or to build from a checkout in a pristine environment:
- @example
- $ git clone git://git.sv.gnu.org/guix.git
- $ guix build guix --with-source=guix@@1.0=./guix
- @end example
- @item --with-input=@var{package}=@var{replacement}
- Replace dependency on @var{package} by a dependency on
- @var{replacement}. @var{package} must be a package name, and
- @var{replacement} must be a package specification such as @code{guile}
- or @code{guile@@1.8}.
- For instance, the following command builds Guix, but replaces its
- dependency on the current stable version of Guile with a dependency on
- the legacy version of Guile, @code{guile@@2.0}:
- @example
- guix build --with-input=guile=guile@@2.0 guix
- @end example
- This is a recursive, deep replacement. So in this example, both
- @code{guix} and its dependency @code{guile-json} (which also depends on
- @code{guile}) get rebuilt against @code{guile@@2.0}.
- This is implemented using the @code{package-input-rewriting} Scheme
- procedure (@pxref{Defining Packages, @code{package-input-rewriting}}).
- @item --with-graft=@var{package}=@var{replacement}
- This is similar to @option{--with-input} but with an important difference:
- instead of rebuilding the whole dependency chain, @var{replacement} is
- built and then @dfn{grafted} onto the binaries that were initially
- referring to @var{package}. @xref{Security Updates}, for more
- information on grafts.
- For example, the command below grafts version 3.5.4 of GnuTLS onto Wget
- and all its dependencies, replacing references to the version of GnuTLS
- they currently refer to:
- @example
- guix build --with-graft=gnutls=gnutls@@3.5.4 wget
- @end example
- This has the advantage of being much faster than rebuilding everything.
- But there is a caveat: it works if and only if @var{package} and
- @var{replacement} are strictly compatible---for example, if they provide
- a library, the application binary interface (ABI) of those libraries
- must be compatible. If @var{replacement} is somehow incompatible with
- @var{package}, then the resulting package may be unusable. Use with
- care!
- @cindex debugging info, rebuilding
- @item --with-debug-info=@var{package}
- Build @var{package} in a way that preserves its debugging info and graft
- it onto packages that depend on it. This is useful if @var{package}
- does not already provide debugging info as a @code{debug} output
- (@pxref{Installing Debugging Files}).
- For example, suppose you're experiencing a crash in Inkscape and would
- like to see what's up in GLib, a library deep down in Inkscape's
- dependency graph. GLib lacks a @code{debug} output, so debugging is
- tough. Fortunately, you rebuild GLib with debugging info and tack it on
- Inkscape:
- @example
- guix install inkscape --with-debug-info=glib
- @end example
- Only GLib needs to be recompiled so this takes a reasonable amount of
- time. @xref{Installing Debugging Files}, for more info.
- @quotation Note
- Under the hood, this option works by passing the @samp{#:strip-binaries?
- #f} to the build system of the package of interest (@pxref{Build
- Systems}). Most build systems support that option but some do not. In
- that case, an error is raised.
- Likewise, if a C/C++ package is built without @code{-g} (which is rarely
- the case), debugging info will remain unavailable even when
- @code{#:strip-binaries?} is false.
- @end quotation
- @cindex tool chain, changing the build tool chain of a package
- @item --with-c-toolchain=@var{package}=@var{toolchain}
- This option changes the compilation of @var{package} and everything that
- depends on it so that they get built with @var{toolchain} instead of the
- default GNU tool chain for C/C++.
- Consider this example:
- @example
- guix build octave-cli \
- --with-c-toolchain=fftw=gcc-toolchain@@10 \
- --with-c-toolchain=fftwf=gcc-toolchain@@10
- @end example
- The command above builds a variant of the @code{fftw} and @code{fftwf}
- packages using version 10 of @code{gcc-toolchain} instead of the default
- tool chain, and then builds a variant of the GNU@tie{}Octave
- command-line interface using them. GNU@tie{}Octave itself is also built
- with @code{gcc-toolchain@@10}.
- This other example builds the Hardware Locality (@code{hwloc}) library
- and its dependents up to @code{intel-mpi-benchmarks} with the Clang C
- compiler:
- @example
- guix build --with-c-toolchain=hwloc=clang-toolchain \
- intel-mpi-benchmarks
- @end example
- @quotation Note
- There can be application binary interface (ABI) incompatibilities among
- tool chains. This is particularly true of the C++ standard library and
- run-time support libraries such as that of OpenMP@. By rebuilding all
- dependents with the same tool chain, @option{--with-c-toolchain} minimizes
- the risks of incompatibility but cannot entirely eliminate them. Choose
- @var{package} wisely.
- @end quotation
- @item --with-git-url=@var{package}=@var{url}
- @cindex Git, using the latest commit
- @cindex latest commit, building
- Build @var{package} from the latest commit of the @code{master} branch of the
- Git repository at @var{url}. Git sub-modules of the repository are fetched,
- recursively.
- For example, the following command builds the NumPy Python library against the
- latest commit of the master branch of Python itself:
- @example
- guix build python-numpy \
- --with-git-url=python=https://github.com/python/cpython
- @end example
- This option can also be combined with @option{--with-branch} or
- @option{--with-commit} (see below).
- @cindex continuous integration
- Obviously, since it uses the latest commit of the given branch, the result of
- such a command varies over time. Nevertheless it is a convenient way to
- rebuild entire software stacks against the latest commit of one or more
- packages. This is particularly useful in the context of continuous
- integration (CI).
- Checkouts are kept in a cache under @file{~/.cache/guix/checkouts} to speed up
- consecutive accesses to the same repository. You may want to clean it up once
- in a while to save disk space.
- @item --with-branch=@var{package}=@var{branch}
- Build @var{package} from the latest commit of @var{branch}. If the
- @code{source} field of @var{package} is an origin with the @code{git-fetch}
- method (@pxref{origin Reference}) or a @code{git-checkout} object, the
- repository URL is taken from that @code{source}. Otherwise you have to use
- @option{--with-git-url} to specify the URL of the Git repository.
- For instance, the following command builds @code{guile-sqlite3} from the
- latest commit of its @code{master} branch, and then builds @code{guix} (which
- depends on it) and @code{cuirass} (which depends on @code{guix}) against this
- specific @code{guile-sqlite3} build:
- @example
- guix build --with-branch=guile-sqlite3=master cuirass
- @end example
- @item --with-commit=@var{package}=@var{commit}
- This is similar to @option{--with-branch}, except that it builds from
- @var{commit} rather than the tip of a branch. @var{commit} must be a valid
- Git commit SHA1 identifier, a tag, or a @command{git describe} style
- identifier such as @code{1.0-3-gabc123}.
- @item --with-patch=@var{package}=@var{file}
- Add @var{file} to the list of patches applied to @var{package}, where
- @var{package} is a spec such as @code{python@@3.8} or @code{glibc}.
- @var{file} must contain a patch; it is applied with the flags specified
- in the @code{origin} of @var{package} (@pxref{origin Reference}), which
- by default includes @code{-p1} (@pxref{patch Directories,,, diffutils,
- Comparing and Merging Files}).
- As an example, the command below rebuilds Coreutils with the GNU C
- Library (glibc) patched with the given patch:
- @example
- guix build coreutils --with-patch=glibc=./glibc-frob.patch
- @end example
- In this example, glibc itself as well as everything that leads to
- Coreutils in the dependency graph is rebuilt.
- @cindex upstream, latest version
- @item --with-latest=@var{package}
- So you like living on the bleeding edge? This option is for you! It
- replaces occurrences of @var{package} in the dependency graph with its
- latest upstream version, as reported by @command{guix refresh}
- (@pxref{Invoking guix refresh}).
- It does so by determining the latest upstream release of @var{package}
- (if possible), downloading it, and authenticating it @emph{if} it comes
- with an OpenPGP signature.
- As an example, the command below builds Guix against the latest version
- of Guile-JSON:
- @example
- guix build guix --with-latest=guile-json
- @end example
- There are limitations. First, in cases where the tool cannot or does
- not know how to authenticate source code, you are at risk of running
- malicious code; a warning is emitted in this case. Second, this option
- simply changes the source used in the existing package definitions,
- which is not always sufficient: there might be additional dependencies
- that need to be added, patches to apply, and more generally the quality
- assurance work that Guix developers normally do will be missing.
- You've been warned! In all the other cases, it's a snappy way to stay
- on top. We encourage you to submit patches updating the actual package
- definitions once you have successfully tested an upgrade
- (@pxref{Contributing}).
- @cindex test suite, skipping
- @item --without-tests=@var{package}
- Build @var{package} without running its tests. This can be useful in
- situations where you want to skip the lengthy test suite of a
- intermediate package, or if a package's test suite fails in a
- non-deterministic fashion. It should be used with care because running
- the test suite is a good way to ensure a package is working as intended.
- Turning off tests leads to a different store item. Consequently, when
- using this option, anything that depends on @var{package} must be
- rebuilt, as in this example:
- @example
- guix install --without-tests=python python-notebook
- @end example
- The command above installs @code{python-notebook} on top of
- @code{python} built without running its test suite. To do so, it also
- rebuilds everything that depends on @code{python}, including
- @code{python-notebook} itself.
- Internally, @option{--without-tests} relies on changing the
- @code{#:tests?} option of a package's @code{check} phase (@pxref{Build
- Systems}). Note that some packages use a customized @code{check} phase
- that does not respect a @code{#:tests? #f} setting. Therefore,
- @option{--without-tests} has no effect on these packages.
- @end table
- Wondering how to achieve the same effect using Scheme code, for example
- in your manifest, or how to write your own package transformation?
- @xref{Defining Package Variants}, for an overview of the programming
- interfaces available.
- @node Additional Build Options
- @subsection Additional Build Options
- The command-line options presented below are specific to @command{guix
- build}.
- @table @code
- @item --quiet
- @itemx -q
- Build quietly, without displaying the build log; this is equivalent to
- @option{--verbosity=0}. Upon completion, the build log is kept in @file{/var}
- (or similar) and can always be retrieved using the @option{--log-file} option.
- @item --file=@var{file}
- @itemx -f @var{file}
- Build the package, derivation, or other file-like object that the code within
- @var{file} evaluates to (@pxref{G-Expressions, file-like objects}).
- As an example, @var{file} might contain a package definition like this
- (@pxref{Defining Packages}):
- @lisp
- @include package-hello.scm
- @end lisp
- The @var{file} may also contain a JSON representation of one or more
- package definitions. Running @code{guix build -f} on @file{hello.json}
- with the following contents would result in building the packages
- @code{myhello} and @code{greeter}:
- @example
- @verbatiminclude package-hello.json
- @end example
- @item --manifest=@var{manifest}
- @itemx -m @var{manifest}
- Build all packages listed in the given @var{manifest}
- (@pxref{profile-manifest, @option{--manifest}}).
- @item --expression=@var{expr}
- @itemx -e @var{expr}
- Build the package or derivation @var{expr} evaluates to.
- For example, @var{expr} may be @code{(@@ (gnu packages guile)
- guile-1.8)}, which unambiguously designates this specific variant of
- version 1.8 of Guile.
- Alternatively, @var{expr} may be a G-expression, in which case it is used
- as a build program passed to @code{gexp->derivation}
- (@pxref{G-Expressions}).
- Lastly, @var{expr} may refer to a zero-argument monadic procedure
- (@pxref{The Store Monad}). The procedure must return a derivation as a
- monadic value, which is then passed through @code{run-with-store}.
- @item --source
- @itemx -S
- Build the source derivations of the packages, rather than the packages
- themselves.
- For instance, @code{guix build -S gcc} returns something like
- @file{/gnu/store/@dots{}-gcc-4.7.2.tar.bz2}, which is the GCC
- source tarball.
- The returned source tarball is the result of applying any patches and
- code snippets specified in the package @code{origin} (@pxref{Defining
- Packages}).
- @cindex source, verification
- As with other derivations, the result of building a source derivation
- can be verified using the @option{--check} option (@pxref{build-check}).
- This is useful to validate that a (potentially already built or
- substituted, thus cached) package source matches against its declared
- hash.
- Note that @command{guix build -S} compiles the sources only of the
- specified packages. They do not include the sources of statically
- linked dependencies and by themselves are insufficient for reproducing
- the packages.
- @item --sources
- Fetch and return the source of @var{package-or-derivation} and all their
- dependencies, recursively. This is a handy way to obtain a local copy
- of all the source code needed to build @var{packages}, allowing you to
- eventually build them even without network access. It is an extension
- of the @option{--source} option and can accept one of the following
- optional argument values:
- @table @code
- @item package
- This value causes the @option{--sources} option to behave in the same way
- as the @option{--source} option.
- @item all
- Build the source derivations of all packages, including any source that
- might be listed as @code{inputs}. This is the default value.
- @example
- $ guix build --sources tzdata
- The following derivations will be built:
- /gnu/store/@dots{}-tzdata2015b.tar.gz.drv
- /gnu/store/@dots{}-tzcode2015b.tar.gz.drv
- @end example
- @item transitive
- Build the source derivations of all packages, as well of all transitive
- inputs to the packages. This can be used e.g.@: to
- prefetch package source for later offline building.
- @example
- $ guix build --sources=transitive tzdata
- The following derivations will be built:
- /gnu/store/@dots{}-tzcode2015b.tar.gz.drv
- /gnu/store/@dots{}-findutils-4.4.2.tar.xz.drv
- /gnu/store/@dots{}-grep-2.21.tar.xz.drv
- /gnu/store/@dots{}-coreutils-8.23.tar.xz.drv
- /gnu/store/@dots{}-make-4.1.tar.xz.drv
- /gnu/store/@dots{}-bash-4.3.tar.xz.drv
- @dots{}
- @end example
- @end table
- @item --system=@var{system}
- @itemx -s @var{system}
- Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of
- the system type of the build host. The @command{guix build} command allows
- you to repeat this option several times, in which case it builds for all the
- specified systems; other commands ignore extraneous @option{-s} options.
- @quotation Note
- The @option{--system} flag is for @emph{native} compilation and must not
- be confused with cross-compilation. See @option{--target} below for
- information on cross-compilation.
- @end quotation
- An example use of this is on Linux-based systems, which can emulate
- different personalities. For instance, passing
- @option{--system=i686-linux} on an @code{x86_64-linux} system or
- @option{--system=armhf-linux} on an @code{aarch64-linux} system allows
- you to build packages in a complete 32-bit environment.
- @quotation Note
- Building for an @code{armhf-linux} system is unconditionally enabled on
- @code{aarch64-linux} machines, although certain aarch64 chipsets do not
- allow for this functionality, notably the ThunderX.
- @end quotation
- Similarly, when transparent emulation with QEMU and @code{binfmt_misc}
- is enabled (@pxref{Virtualization Services,
- @code{qemu-binfmt-service-type}}), you can build for any system for
- which a QEMU @code{binfmt_misc} handler is installed.
- Builds for a system other than that of the machine you are using can
- also be offloaded to a remote machine of the right architecture.
- @xref{Daemon Offload Setup}, for more information on offloading.
- @item --target=@var{triplet}
- @cindex cross-compilation
- Cross-build for @var{triplet}, which must be a valid GNU triplet, such
- as @code{"aarch64-linux-gnu"} (@pxref{Specifying Target Triplets, GNU
- configuration triplets,, autoconf, Autoconf}).
- @anchor{build-check}
- @item --check
- @cindex determinism, checking
- @cindex reproducibility, checking
- Rebuild @var{package-or-derivation}, which are already available in the
- store, and raise an error if the build results are not bit-for-bit
- identical.
- This mechanism allows you to check whether previously installed
- substitutes are genuine (@pxref{Substitutes}), or whether the build result
- of a package is deterministic. @xref{Invoking guix challenge}, for more
- background information and tools.
- When used in conjunction with @option{--keep-failed}, the differing
- output is kept in the store, under @file{/gnu/store/@dots{}-check}.
- This makes it easy to look for differences between the two results.
- @item --repair
- @cindex repairing store items
- @cindex corruption, recovering from
- Attempt to repair the specified store items, if they are corrupt, by
- re-downloading or rebuilding them.
- This operation is not atomic and thus restricted to @code{root}.
- @item --derivations
- @itemx -d
- Return the derivation paths, not the output paths, of the given
- packages.
- @item --root=@var{file}
- @itemx -r @var{file}
- @cindex GC roots, adding
- @cindex garbage collector roots, adding
- Make @var{file} a symlink to the result, and register it as a garbage
- collector root.
- Consequently, the results of this @command{guix build} invocation are
- protected from garbage collection until @var{file} is removed. When
- that option is omitted, build results are eligible for garbage
- collection as soon as the build completes. @xref{Invoking guix gc}, for
- more on GC roots.
- @item --log-file
- @cindex build logs, access
- Return the build log file names or URLs for the given
- @var{package-or-derivation}, or raise an error if build logs are
- missing.
- This works regardless of how packages or derivations are specified. For
- instance, the following invocations are equivalent:
- @example
- guix build --log-file $(guix build -d guile)
- guix build --log-file $(guix build guile)
- guix build --log-file guile
- guix build --log-file -e '(@@ (gnu packages guile) guile-2.0)'
- @end example
- If a log is unavailable locally, and unless @option{--no-substitutes} is
- passed, the command looks for a corresponding log on one of the
- substitute servers (as specified with @option{--substitute-urls}).
- So for instance, imagine you want to see the build log of GDB on MIPS,
- but you are actually on an @code{x86_64} machine:
- @example
- $ guix build --log-file gdb -s aarch64-linux
- https://@value{SUBSTITUTE-SERVER-1}/log/@dots{}-gdb-7.10
- @end example
- You can freely access a huge library of build logs!
- @end table
- @node Debugging Build Failures
- @subsection Debugging Build Failures
- @cindex build failures, debugging
- When defining a new package (@pxref{Defining Packages}), you will
- probably find yourself spending some time debugging and tweaking the
- build until it succeeds. To do that, you need to operate the build
- commands yourself in an environment as close as possible to the one the
- build daemon uses.
- To that end, the first thing to do is to use the @option{--keep-failed}
- or @option{-K} option of @command{guix build}, which will keep the
- failed build tree in @file{/tmp} or whatever directory you specified as
- @env{TMPDIR} (@pxref{Common Build Options, @option{--keep-failed}}).
- From there on, you can @command{cd} to the failed build tree and source
- the @file{environment-variables} file, which contains all the
- environment variable definitions that were in place when the build
- failed. So let's say you're debugging a build failure in package
- @code{foo}; a typical session would look like this:
- @example
- $ guix build foo -K
- @dots{} @i{build fails}
- $ cd /tmp/guix-build-foo.drv-0
- $ source ./environment-variables
- $ cd foo-1.2
- @end example
- Now, you can invoke commands as if you were the daemon (almost) and
- troubleshoot your build process.
- Sometimes it happens that, for example, a package's tests pass when you
- run them manually but they fail when the daemon runs them. This can
- happen because the daemon runs builds in containers where, unlike in our
- environment above, network access is missing, @file{/bin/sh} does not
- exist, etc. (@pxref{Build Environment Setup}).
- In such cases, you may need to run inspect the build process from within
- a container similar to the one the build daemon creates:
- @example
- $ guix build -K foo
- @dots{}
- $ cd /tmp/guix-build-foo.drv-0
- $ guix shell --no-grafts -C -D foo strace gdb
- [env]# source ./environment-variables
- [env]# cd foo-1.2
- @end example
- Here, @command{guix shell -C} creates a container and spawns a new
- shell in it (@pxref{Invoking guix shell}). The @command{strace gdb}
- part adds the @command{strace} and @command{gdb} commands to
- the container, which you may find handy while debugging. The
- @option{--no-grafts} option makes sure we get the exact same
- environment, with ungrafted packages (@pxref{Security Updates}, for more
- info on grafts).
- To get closer to a container like that used by the build daemon, we can
- remove @file{/bin/sh}:
- @example
- [env]# rm /bin/sh
- @end example
- (Don't worry, this is harmless: this is all happening in the throw-away
- container created by @command{guix shell}.)
- The @command{strace} command is probably not in the search path, but we
- can run:
- @example
- [env]# $GUIX_ENVIRONMENT/bin/strace -f -o log make check
- @end example
- In this way, not only you will have reproduced the environment variables
- the daemon uses, you will also be running the build process in a container
- similar to the one the daemon uses.
- @node Invoking guix edit
- @section Invoking @command{guix edit}
- @cindex @command{guix edit}
- @cindex package definition, editing
- So many packages, so many source files! The @command{guix edit} command
- facilitates the life of users and packagers by pointing their editor at
- the source file containing the definition of the specified packages.
- For instance:
- @example
- guix edit gcc@@4.9 vim
- @end example
- @noindent
- launches the program specified in the @env{VISUAL} or in the
- @env{EDITOR} environment variable to view the recipe of GCC@tie{}4.9.3
- and that of Vim.
- If you are using a Guix Git checkout (@pxref{Building from Git}), or
- have created your own packages on @env{GUIX_PACKAGE_PATH}
- (@pxref{Package Modules}), you will be able to edit the package
- recipes. In other cases, you will be able to examine the read-only recipes
- for packages currently in the store.
- Instead of @env{GUIX_PACKAGE_PATH}, the command-line option
- @option{--load-path=@var{directory}} (or in short @option{-L
- @var{directory}}) allows you to add @var{directory} to the front of the
- package module search path and so make your own packages visible.
- @node Invoking guix download
- @section Invoking @command{guix download}
- @cindex @command{guix download}
- @cindex downloading package sources
- When writing a package definition, developers typically need to download
- a source tarball, compute its SHA256 hash, and write that
- hash in the package definition (@pxref{Defining Packages}). The
- @command{guix download} tool helps with this task: it downloads a file
- from the given URI, adds it to the store, and prints both its file name
- in the store and its SHA256 hash.
- The fact that the downloaded file is added to the store saves bandwidth:
- when the developer eventually tries to build the newly defined package
- with @command{guix build}, the source tarball will not have to be
- downloaded again because it is already in the store. It is also a
- convenient way to temporarily stash files, which may be deleted
- eventually (@pxref{Invoking guix gc}).
- The @command{guix download} command supports the same URIs as used in
- package definitions. In particular, it supports @code{mirror://} URIs.
- @code{https} URIs (HTTP over TLS) are supported @emph{provided} the
- Guile bindings for GnuTLS are available in the user's environment; when
- they are not available, an error is raised. @xref{Guile Preparations,
- how to install the GnuTLS bindings for Guile,, gnutls-guile,
- GnuTLS-Guile}, for more information.
- @command{guix download} verifies HTTPS server certificates by loading
- the certificates of X.509 authorities from the directory pointed to by
- the @env{SSL_CERT_DIR} environment variable (@pxref{X.509
- Certificates}), unless @option{--no-check-certificate} is used.
- The following options are available:
- @table @code
- @item --hash=@var{algorithm}
- @itemx -H @var{algorithm}
- Compute a hash using the specified @var{algorithm}. @xref{Invoking guix
- hash}, for more information.
- @item --format=@var{fmt}
- @itemx -f @var{fmt}
- Write the hash in the format specified by @var{fmt}. For more
- information on the valid values for @var{fmt}, @pxref{Invoking guix hash}.
- @item --no-check-certificate
- Do not validate the X.509 certificates of HTTPS servers.
- When using this option, you have @emph{absolutely no guarantee} that you
- are communicating with the authentic server responsible for the given
- URL, which makes you vulnerable to ``man-in-the-middle'' attacks.
- @item --output=@var{file}
- @itemx -o @var{file}
- Save the downloaded file to @var{file} instead of adding it to the
- store.
- @end table
- @node Invoking guix hash
- @section Invoking @command{guix hash}
- @cindex @command{guix hash}
- The @command{guix hash} command computes the hash of a file.
- It is primarily a convenience tool for anyone contributing to the
- distribution: it computes the cryptographic hash of one or more files, which can be
- used in the definition of a package (@pxref{Defining Packages}).
- The general syntax is:
- @example
- guix hash @var{option} @var{file} ...
- @end example
- When @var{file} is @code{-} (a hyphen), @command{guix hash} computes the
- hash of data read from standard input. @command{guix hash} has the
- following options:
- @table @code
- @item --hash=@var{algorithm}
- @itemx -H @var{algorithm}
- Compute a hash using the specified @var{algorithm}, @code{sha256} by
- default.
- @var{algorithm} must be the name of a cryptographic hash algorithm
- supported by Libgcrypt @i{via} Guile-Gcrypt---e.g., @code{sha512} or
- @code{sha3-256} (@pxref{Hash Functions,,, guile-gcrypt, Guile-Gcrypt
- Reference Manual}).
- @item --format=@var{fmt}
- @itemx -f @var{fmt}
- Write the hash in the format specified by @var{fmt}.
- Supported formats: @code{base64}, @code{nix-base32}, @code{base32}, @code{base16}
- (@code{hex} and @code{hexadecimal} can be used as well).
- If the @option{--format} option is not specified, @command{guix hash}
- will output the hash in @code{nix-base32}. This representation is used
- in the definitions of packages.
- @item --recursive
- @itemx -r
- The @option{--recursive} option is deprecated in favor of
- @option{--serializer=nar} (see below); @option{-r} remains accepted as a
- convenient shorthand.
- @item --serializer=@var{type}
- @itemx -S @var{type}
- Compute the hash on @var{file} using @var{type} serialization.
- @var{type} may be one of the following:
- @table @code
- @item none
- This is the default: it computes the hash of a file's contents.
- @item nar
- Compute the hash of a ``normalized archive'' (or ``nar'') containing
- @var{file}, including its children if it is a directory. Some of the
- metadata of @var{file} is part of the archive; for instance, when
- @var{file} is a regular file, the hash is different depending on whether
- @var{file} is executable or not. Metadata such as time stamps have no
- impact on the hash (@pxref{Invoking guix archive}, for more info on the
- nar format).
- @c FIXME: Replace xref above with xref to an ``Archive'' section when
- @c it exists.
- @item git
- Compute the hash of the file or directory as a Git ``tree'', following
- the same method as the Git version control system.
- @end table
- @item --exclude-vcs
- @itemx -x
- When combined with @option{--recursive}, exclude version control system
- directories (@file{.bzr}, @file{.git}, @file{.hg}, etc.).
- @vindex git-fetch
- As an example, here is how you would compute the hash of a Git checkout,
- which is useful when using the @code{git-fetch} method (@pxref{origin
- Reference}):
- @example
- $ git clone http://example.org/foo.git
- $ cd foo
- $ guix hash -x --serializer=nar .
- @end example
- @end table
- @node Invoking guix import
- @section Invoking @command{guix import}
- @cindex importing packages
- @cindex package import
- @cindex package conversion
- @cindex Invoking @command{guix import}
- The @command{guix import} command is useful for people who would like to
- add a package to the distribution with as little work as
- possible---a legitimate demand. The command knows of a few
- repositories from which it can ``import'' package metadata. The result
- is a package definition, or a template thereof, in the format we know
- (@pxref{Defining Packages}).
- The general syntax is:
- @example
- guix import @var{importer} @var{options}@dots{}
- @end example
- @var{importer} specifies the source from which to import package
- metadata, and @var{options} specifies a package identifier and other
- options specific to @var{importer}.
- Some of the importers rely on the ability to run the @command{gpgv} command.
- For these, GnuPG must be installed and in @code{$PATH}; run @code{guix install
- gnupg} if needed.
- Currently, the available ``importers'' are:
- @table @code
- @item gnu
- Import metadata for the given GNU package. This provides a template
- for the latest version of that GNU package, including the hash of its
- source tarball, and its canonical synopsis and description.
- Additional information such as the package dependencies and its
- license needs to be figured out manually.
- For example, the following command returns a package definition for
- GNU@tie{}Hello:
- @example
- guix import gnu hello
- @end example
- Specific command-line options are:
- @table @code
- @item --key-download=@var{policy}
- As for @command{guix refresh}, specify the policy to handle missing
- OpenPGP keys when verifying the package signature. @xref{Invoking guix
- refresh, @option{--key-download}}.
- @end table
- @item pypi
- @cindex pypi
- Import metadata from the @uref{https://pypi.python.org/, Python Package
- Index}. Information is taken from the JSON-formatted description
- available at @code{pypi.python.org} and usually includes all the relevant
- information, including package dependencies. For maximum efficiency, it
- is recommended to install the @command{unzip} utility, so that the
- importer can unzip Python wheels and gather data from them.
- The command below imports metadata for the latest version of the
- @code{itsdangerous} Python package:
- @example
- guix import pypi itsdangerous
- @end example
- You can also ask for a specific version:
- @example
- guix import pypi itsdangerous@@1.1.0
- @end example
- @table @code
- @item --recursive
- @itemx -r
- Traverse the dependency graph of the given upstream package recursively
- and generate package expressions for all those packages that are not yet
- in Guix.
- @end table
- @item gem
- @cindex gem
- Import metadata from @uref{https://rubygems.org/, RubyGems}. Information
- is taken from the JSON-formatted description available at
- @code{rubygems.org} and includes most relevant information, including
- runtime dependencies. There are some caveats, however. The metadata
- doesn't distinguish between synopses and descriptions, so the same string
- is used for both fields. Additionally, the details of non-Ruby
- dependencies required to build native extensions is unavailable and left
- as an exercise to the packager.
- The command below imports metadata for the @code{rails} Ruby package:
- @example
- guix import gem rails
- @end example
- @table @code
- @item --recursive
- @itemx -r
- Traverse the dependency graph of the given upstream package recursively
- and generate package expressions for all those packages that are not yet
- in Guix.
- @end table
- @item minetest
- @cindex minetest
- @cindex ContentDB
- Import metadata from @uref{https://content.minetest.net, ContentDB}.
- Information is taken from the JSON-formatted metadata provided through
- @uref{https://content.minetest.net/help/api/, ContentDB's API} and
- includes most relevant information, including dependencies. There are
- some caveats, however. The license information is often incomplete.
- The commit hash is sometimes missing. The descriptions are in the
- Markdown format, but Guix uses Texinfo instead. Texture packs and
- subgames are unsupported.
- The command below imports metadata for the Mesecons mod by Jeija:
- @example
- guix import minetest Jeija/mesecons
- @end example
- The author name can also be left out:
- @example
- guix import minetest mesecons
- @end example
- @table @code
- @item --recursive
- @itemx -r
- Traverse the dependency graph of the given upstream package recursively
- and generate package expressions for all those packages that are not yet
- in Guix.
- @end table
- @item cpan
- @cindex CPAN
- Import metadata from @uref{https://www.metacpan.org/, MetaCPAN}.
- Information is taken from the JSON-formatted metadata provided through
- @uref{https://fastapi.metacpan.org/, MetaCPAN's API} and includes most
- relevant information, such as module dependencies. License information
- should be checked closely. If Perl is available in the store, then the
- @code{corelist} utility will be used to filter core modules out of the
- list of dependencies.
- The command command below imports metadata for the Acme::Boolean Perl
- module:
- @example
- guix import cpan Acme::Boolean
- @end example
- @item cran
- @cindex CRAN
- @cindex Bioconductor
- Import metadata from @uref{https://cran.r-project.org/, CRAN}, the
- central repository for the @uref{https://r-project.org, GNU@tie{}R
- statistical and graphical environment}.
- Information is extracted from the @file{DESCRIPTION} file of the package.
- The command command below imports metadata for the Cairo R package:
- @example
- guix import cran Cairo
- @end example
- You can also ask for a specific version:
- @example
- guix import cran rasterVis@@0.50.3
- @end example
- When @option{--recursive} is added, the importer will traverse the
- dependency graph of the given upstream package recursively and generate
- package expressions for all those packages that are not yet in Guix.
- When @option{--style=specification} is added, the importer will generate
- package definitions whose inputs are package specifications instead of
- references to package variables. This is useful when generated package
- definitions are to be appended to existing user modules, as the list of
- used package modules need not be changed. The default is
- @option{--style=variable}.
- When @option{--archive=bioconductor} is added, metadata is imported from
- @uref{https://www.bioconductor.org/, Bioconductor}, a repository of R
- packages for the analysis and comprehension of high-throughput
- genomic data in bioinformatics.
- Information is extracted from the @file{DESCRIPTION} file contained in the
- package archive.
- The command below imports metadata for the GenomicRanges R package:
- @example
- guix import cran --archive=bioconductor GenomicRanges
- @end example
- Finally, you can also import R packages that have not yet been published on
- CRAN or Bioconductor as long as they are in a git repository. Use
- @option{--archive=git} followed by the URL of the git repository:
- @example
- guix import cran --archive=git https://github.com/immunogenomics/harmony
- @end example
- @item texlive
- @cindex TeX Live
- @cindex CTAN
- Import TeX package information from the TeX Live package database for
- TeX packages that are part of the @uref{https://www.tug.org/texlive/,
- TeX Live distribution}.
- Information about the package is obtained from the TeX Live package
- database, a plain text file that is included in the @code{texlive-bin}
- package. The source code is downloaded from possibly multiple locations
- in the SVN repository of the Tex Live project.
- The command command below imports metadata for the @code{fontspec}
- TeX package:
- @example
- guix import texlive fontspec
- @end example
- @item json
- @cindex JSON, import
- Import package metadata from a local JSON file. Consider the following
- example package definition in JSON format:
- @example
- @{
- "name": "hello",
- "version": "2.10",
- "source": "mirror://gnu/hello/hello-2.10.tar.gz",
- "build-system": "gnu",
- "home-page": "https://www.gnu.org/software/hello/",
- "synopsis": "Hello, GNU world: An example GNU package",
- "description": "GNU Hello prints a greeting.",
- "license": "GPL-3.0+",
- "native-inputs": ["gettext"]
- @}
- @end example
- The field names are the same as for the @code{<package>} record
- (@xref{Defining Packages}). References to other packages are provided
- as JSON lists of quoted package specification strings such as
- @code{guile} or @code{guile@@2.0}.
- The importer also supports a more explicit source definition using the
- common fields for @code{<origin>} records:
- @example
- @{
- @dots{}
- "source": @{
- "method": "url-fetch",
- "uri": "mirror://gnu/hello/hello-2.10.tar.gz",
- "sha256": @{
- "base32": "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i"
- @}
- @}
- @dots{}
- @}
- @end example
- The command below reads metadata from the JSON file @code{hello.json}
- and outputs a package expression:
- @example
- guix import json hello.json
- @end example
- @item hackage
- @cindex hackage
- Import metadata from the Haskell community's central package archive
- @uref{https://hackage.haskell.org/, Hackage}. Information is taken from
- Cabal files and includes all the relevant information, including package
- dependencies.
- Specific command-line options are:
- @table @code
- @item --stdin
- @itemx -s
- Read a Cabal file from standard input.
- @item --no-test-dependencies
- @itemx -t
- Do not include dependencies required only by the test suites.
- @item --cabal-environment=@var{alist}
- @itemx -e @var{alist}
- @var{alist} is a Scheme alist defining the environment in which the
- Cabal conditionals are evaluated. The accepted keys are: @code{os},
- @code{arch}, @code{impl} and a string representing the name of a flag.
- The value associated with a flag has to be either the symbol
- @code{true} or @code{false}. The value associated with other keys
- has to conform to the Cabal file format definition. The default value
- associated with the keys @code{os}, @code{arch} and @code{impl} is
- @samp{linux}, @samp{x86_64} and @samp{ghc}, respectively.
- @item --recursive
- @itemx -r
- Traverse the dependency graph of the given upstream package recursively
- and generate package expressions for all those packages that are not yet
- in Guix.
- @end table
- The command below imports metadata for the latest version of the
- HTTP Haskell package without including test dependencies and
- specifying the value of the flag @samp{network-uri} as @code{false}:
- @example
- guix import hackage -t -e "'((\"network-uri\" . false))" HTTP
- @end example
- A specific package version may optionally be specified by following the
- package name by an at-sign and a version number as in the following example:
- @example
- guix import hackage mtl@@2.1.3.1
- @end example
- @item stackage
- @cindex stackage
- The @code{stackage} importer is a wrapper around the @code{hackage} one.
- It takes a package name, looks up the package version included in a
- long-term support (LTS) @uref{https://www.stackage.org, Stackage}
- release and uses the @code{hackage} importer to retrieve its metadata.
- Note that it is up to you to select an LTS release compatible with the
- GHC compiler used by Guix.
- Specific command-line options are:
- @table @code
- @item --no-test-dependencies
- @itemx -t
- Do not include dependencies required only by the test suites.
- @item --lts-version=@var{version}
- @itemx -l @var{version}
- @var{version} is the desired LTS release version. If omitted the latest
- release is used.
- @item --recursive
- @itemx -r
- Traverse the dependency graph of the given upstream package recursively
- and generate package expressions for all those packages that are not yet
- in Guix.
- @end table
- The command below imports metadata for the HTTP Haskell package
- included in the LTS Stackage release version 7.18:
- @example
- guix import stackage --lts-version=7.18 HTTP
- @end example
- @item elpa
- @cindex elpa
- Import metadata from an Emacs Lisp Package Archive (ELPA) package
- repository (@pxref{Packages,,, emacs, The GNU Emacs Manual}).
- Specific command-line options are:
- @table @code
- @item --archive=@var{repo}
- @itemx -a @var{repo}
- @var{repo} identifies the archive repository from which to retrieve the
- information. Currently the supported repositories and their identifiers
- are:
- @itemize -
- @item
- @uref{https://elpa.gnu.org/packages, GNU}, selected by the @code{gnu}
- identifier. This is the default.
- Packages from @code{elpa.gnu.org} are signed with one of the keys
- contained in the GnuPG keyring at
- @file{share/emacs/25.1/etc/package-keyring.gpg} (or similar) in the
- @code{emacs} package (@pxref{Package Installation, ELPA package
- signatures,, emacs, The GNU Emacs Manual}).
- @item
- @uref{https://elpa.nongnu.org/nongnu/, NonGNU}, selected by the
- @code{nongnu} identifier.
- @item
- @uref{https://stable.melpa.org/packages, MELPA-Stable}, selected by the
- @code{melpa-stable} identifier.
- @item
- @uref{https://melpa.org/packages, MELPA}, selected by the @code{melpa}
- identifier.
- @end itemize
- @item --recursive
- @itemx -r
- Traverse the dependency graph of the given upstream package recursively
- and generate package expressions for all those packages that are not yet
- in Guix.
- @end table
- @item crate
- @cindex crate
- Import metadata from the crates.io Rust package repository
- @uref{https://crates.io, crates.io}, as in this example:
- @example
- guix import crate blake2-rfc
- @end example
- The crate importer also allows you to specify a version string:
- @example
- guix import crate constant-time-eq@@0.1.0
- @end example
- Additional options include:
- @table @code
- @item --recursive
- @itemx -r
- Traverse the dependency graph of the given upstream package recursively
- and generate package expressions for all those packages that are not yet
- in Guix.
- @end table
- @item opam
- @cindex OPAM
- @cindex OCaml
- Import metadata from the @uref{https://opam.ocaml.org/, OPAM} package
- repository used by the OCaml community.
- Additional options include:
- @table @code
- @item --recursive
- @itemx -r
- Traverse the dependency graph of the given upstream package recursively
- and generate package expressions for all those packages that are not yet
- in Guix.
- @item --repo
- By default, packages are searched in the official OPAM repository. This
- option, which can be used more than once, lets you add other repositories
- which will be searched for packages. It accepts as valid arguments:
- @itemize
- @item the name of a known repository - can be one of @code{opam},
- @code{coq} (equivalent to @code{coq-released}),
- @code{coq-core-dev}, @code{coq-extra-dev} or @code{grew}.
- @item the URL of a repository as expected by the
- @code{opam repository add} command (for instance, the URL equivalent
- of the above @code{opam} name would be
- @uref{https://opam.ocaml.org}).
- @item the path to a local copy of a repository (a directory containing a
- @file{packages/} sub-directory).
- @end itemize
- Repositories are assumed to be passed to this option by order of
- preference. The additional repositories will not replace the default
- @code{opam} repository, which is always kept as a fallback.
- Also, please note that versions are not compared across repositories.
- The first repository (from left to right) that has at least one version
- of a given package will prevail over any others, and the version
- imported will be the latest one found @emph{in this repository only}.
- @end table
- @item go
- @cindex go
- Import metadata for a Go module using
- @uref{https://proxy.golang.org, proxy.golang.org}.
- @example
- guix import go gopkg.in/yaml.v2
- @end example
- It is possible to use a package specification with a @code{@@VERSION}
- suffix to import a specific version.
- Additional options include:
- @table @code
- @item --recursive
- @itemx -r
- Traverse the dependency graph of the given upstream package recursively
- and generate package expressions for all those packages that are not yet
- in Guix.
- @item --pin-versions
- When using this option, the importer preserves the exact versions of the
- Go modules dependencies instead of using their latest available
- versions. This can be useful when attempting to import packages that
- recursively depend on former versions of themselves to build. When
- using this mode, the symbol of the package is made by appending the
- version to its name, so that multiple versions of the same package can
- coexist.
- @end table
- @item egg
- @cindex egg
- Import metadata for @uref{https://wiki.call-cc.org/eggs, CHICKEN eggs}.
- The information is taken from @file{PACKAGE.egg} files found in the
- @uref{git://code.call-cc.org/eggs-5-all, eggs-5-all} Git
- repository. However, it does not provide all the information that we
- need, there is no ``description'' field, and the licenses used are not
- always precise (BSD is often used instead of BSD-N).
- @example
- guix import egg sourcehut
- @end example
- You can also ask for a specific version:
- @example
- guix import egg arrays@@1.0
- @end example
- Additional options include:
- @table @code
- @item --recursive
- @itemx -r
- Traverse the dependency graph of the given upstream package recursively
- and generate package expressions for all those packages that are not yet
- in Guix.
- @end table
- @end table
- The structure of the @command{guix import} code is modular. It would be
- useful to have more importers for other package formats, and your help
- is welcome here (@pxref{Contributing}).
- @node Invoking guix refresh
- @section Invoking @command{guix refresh}
- @cindex @command {guix refresh}
- The primary audience of the @command{guix refresh} command is packagers.
- As a user, you may be interested in the @option{--with-latest} option,
- which can bring you package update superpowers built upon @command{guix
- refresh} (@pxref{Package Transformation Options,
- @option{--with-latest}}). By default, @command{guix refresh} reports
- any packages provided by the distribution that are outdated compared to
- the latest upstream version, like this:
- @example
- $ guix refresh
- gnu/packages/gettext.scm:29:13: gettext would be upgraded from 0.18.1.1 to 0.18.2.1
- gnu/packages/glib.scm:77:12: glib would be upgraded from 2.34.3 to 2.37.0
- @end example
- Alternatively, one can specify packages to consider, in which case a
- warning is emitted for packages that lack an updater:
- @example
- $ guix refresh coreutils guile guile-ssh
- gnu/packages/ssh.scm:205:2: warning: no updater for guile-ssh
- gnu/packages/guile.scm:136:12: guile would be upgraded from 2.0.12 to 2.0.13
- @end example
- @command{guix refresh} browses the upstream repository of each package and determines
- the highest version number of the releases therein. The command
- knows how to update specific types of packages: GNU packages, ELPA
- packages, etc.---see the documentation for @option{--type} below. There
- are many packages, though, for which it lacks a method to determine
- whether a new upstream release is available. However, the mechanism is
- extensible, so feel free to get in touch with us to add a new method!
- @table @code
- @item --recursive
- Consider the packages specified, and all the packages upon which they depend.
- @example
- $ guix refresh --recursive coreutils
- gnu/packages/acl.scm:40:13: acl would be upgraded from 2.2.53 to 2.3.1
- gnu/packages/m4.scm:30:12: 1.4.18 is already the latest version of m4
- gnu/packages/xml.scm:68:2: warning: no updater for expat
- gnu/packages/multiprecision.scm:40:12: 6.1.2 is already the latest version of gmp
- @dots{}
- @end example
- @end table
- Sometimes the upstream name differs from the package name used in Guix,
- and @command{guix refresh} needs a little help. Most updaters honor the
- @code{upstream-name} property in package definitions, which can be used
- to that effect:
- @lisp
- (define-public network-manager
- (package
- (name "network-manager")
- ;; @dots{}
- (properties '((upstream-name . "NetworkManager")))))
- @end lisp
- When passed @option{--update}, it modifies distribution source files to
- update the version numbers and source tarball hashes of those package
- recipes (@pxref{Defining Packages}). This is achieved by downloading
- each package's latest source tarball and its associated OpenPGP
- signature, authenticating the downloaded tarball against its signature
- using @command{gpgv}, and finally computing its hash---note that GnuPG must be
- installed and in @code{$PATH}; run @code{guix install gnupg} if needed.
- When the public
- key used to sign the tarball is missing from the user's keyring, an
- attempt is made to automatically retrieve it from a public key server;
- when this is successful, the key is added to the user's keyring; otherwise,
- @command{guix refresh} reports an error.
- The following options are supported:
- @table @code
- @item --expression=@var{expr}
- @itemx -e @var{expr}
- Consider the package @var{expr} evaluates to.
- This is useful to precisely refer to a package, as in this example:
- @example
- guix refresh -l -e '(@@@@ (gnu packages commencement) glibc-final)'
- @end example
- This command lists the dependents of the ``final'' libc (essentially all
- the packages).
- @item --update
- @itemx -u
- Update distribution source files (package recipes) in place. This is
- usually run from a checkout of the Guix source tree (@pxref{Running
- Guix Before It Is Installed}):
- @example
- $ ./pre-inst-env guix refresh -s non-core -u
- @end example
- @xref{Defining Packages}, for more information on package definitions.
- @item --select=[@var{subset}]
- @itemx -s @var{subset}
- Select all the packages in @var{subset}, one of @code{core} or
- @code{non-core}.
- The @code{core} subset refers to all the packages at the core of the
- distribution---i.e., packages that are used to build ``everything
- else''. This includes GCC, libc, Binutils, Bash, etc. Usually,
- changing one of these packages in the distribution entails a rebuild of
- all the others. Thus, such updates are an inconvenience to users in
- terms of build time or bandwidth used to achieve the upgrade.
- The @code{non-core} subset refers to the remaining packages. It is
- typically useful in cases where an update of the core packages would be
- inconvenient.
- @item --manifest=@var{file}
- @itemx -m @var{file}
- Select all the packages from the manifest in @var{file}. This is useful to
- check if any packages of the user manifest can be updated.
- @item --type=@var{updater}
- @itemx -t @var{updater}
- Select only packages handled by @var{updater} (may be a comma-separated
- list of updaters). Currently, @var{updater} may be one of:
- @table @code
- @item gnu
- the updater for GNU packages;
- @item savannah
- the updater for packages hosted at @uref{https://savannah.gnu.org, Savannah};
- @item sourceforge
- the updater for packages hosted at @uref{https://sourceforge.net, SourceForge};
- @item gnome
- the updater for GNOME packages;
- @item kde
- the updater for KDE packages;
- @item xorg
- the updater for X.org packages;
- @item kernel.org
- the updater for packages hosted on kernel.org;
- @item egg
- the updater for @uref{https://wiki.call-cc.org/eggs/, Egg} packages;
- @item elpa
- the updater for @uref{https://elpa.gnu.org/, ELPA} packages;
- @item cran
- the updater for @uref{https://cran.r-project.org/, CRAN} packages;
- @item bioconductor
- the updater for @uref{https://www.bioconductor.org/, Bioconductor} R packages;
- @item cpan
- the updater for @uref{https://www.cpan.org/, CPAN} packages;
- @item pypi
- the updater for @uref{https://pypi.python.org, PyPI} packages.
- @item gem
- the updater for @uref{https://rubygems.org, RubyGems} packages.
- @item github
- the updater for @uref{https://github.com, GitHub} packages.
- @item hackage
- the updater for @uref{https://hackage.haskell.org, Hackage} packages.
- @item stackage
- the updater for @uref{https://www.stackage.org, Stackage} packages.
- @item crate
- the updater for @uref{https://crates.io, Crates} packages.
- @item launchpad
- the updater for @uref{https://launchpad.net, Launchpad} packages.
- @item generic-html
- a generic updater that crawls the HTML page where the source tarball of
- the package is hosted, when applicable.
- @item generic-git
- a generic updater for packages hosted on Git repositories. It tries to
- be smart about parsing Git tag names, but if it is not able to parse the
- tag name and compare tags correctly, users can define the following
- properties for a package.
- @itemize
- @item @code{release-tag-prefix}: a regular expression for matching a prefix of
- the tag name.
- @item @code{release-tag-suffix}: a regular expression for matching a suffix of
- the tag name.
- @item @code{release-tag-version-delimiter}: a string used as the delimiter in
- the tag name for separating the numbers of the version.
- @item @code{accept-pre-releases}: by default, the updater will ignore
- pre-releases; to make it also look for pre-releases, set the this
- property to @code{#t}.
- @end itemize
- @lisp
- (package
- (name "foo")
- ;; ...
- (properties
- '((release-tag-prefix . "^release0-")
- (release-tag-suffix . "[a-z]?$")
- (release-tag-version-delimiter . ":"))))
- @end lisp
- @end table
- For instance, the following command only checks for updates of Emacs
- packages hosted at @code{elpa.gnu.org} and for updates of CRAN packages:
- @example
- $ guix refresh --type=elpa,cran
- gnu/packages/statistics.scm:819:13: r-testthat would be upgraded from 0.10.0 to 0.11.0
- gnu/packages/emacs.scm:856:13: emacs-auctex would be upgraded from 11.88.6 to 11.88.9
- @end example
- @item --list-updaters
- @itemx -L
- List available updaters and exit (see @option{--type} above).
- For each updater, display the fraction of packages it covers; at the
- end, display the fraction of packages covered by all these updaters.
- @end table
- In addition, @command{guix refresh} can be passed one or more package
- names, as in this example:
- @example
- $ ./pre-inst-env guix refresh -u emacs idutils gcc@@4.8
- @end example
- @noindent
- The command above specifically updates the @code{emacs} and
- @code{idutils} packages. The @option{--select} option would have no
- effect in this case. You might also want to update definitions that
- correspond to the packages installed in your profile:
- @example
- $ ./pre-inst-env guix refresh -u \
- $(guix package --list-installed | cut -f1)
- @end example
- When considering whether to upgrade a package, it is sometimes
- convenient to know which packages would be affected by the upgrade and
- should be checked for compatibility. For this the following option may
- be used when passing @command{guix refresh} one or more package names:
- @table @code
- @item --list-dependent
- @itemx -l
- List top-level dependent packages that would need to be rebuilt as a
- result of upgrading one or more packages.
- @xref{Invoking guix graph, the @code{reverse-package} type of
- @command{guix graph}}, for information on how to visualize the list of
- dependents of a package.
- @end table
- Be aware that the @option{--list-dependent} option only
- @emph{approximates} the rebuilds that would be required as a result of
- an upgrade. More rebuilds might be required under some circumstances.
- @example
- $ guix refresh --list-dependent flex
- Building the following 120 packages would ensure 213 dependent packages are rebuilt:
- hop@@2.4.0 emacs-geiser@@0.13 notmuch@@0.18 mu@@0.9.9.5 cflow@@1.4 idutils@@4.6 @dots{}
- @end example
- The command above lists a set of packages that could be built to check
- for compatibility with an upgraded @code{flex} package.
- @table @code
- @item --list-transitive
- List all the packages which one or more packages depend upon.
- @example
- $ guix refresh --list-transitive flex
- flex@@2.6.4 depends on the following 25 packages: perl@@5.28.0 help2man@@1.47.6
- bison@@3.0.5 indent@@2.2.10 tar@@1.30 gzip@@1.9 bzip2@@1.0.6 xz@@5.2.4 file@@5.33 @dots{}
- @end example
- @end table
- The command above lists a set of packages which, when changed, would cause
- @code{flex} to be rebuilt.
- The following options can be used to customize GnuPG operation:
- @table @code
- @item --gpg=@var{command}
- Use @var{command} as the GnuPG 2.x command. @var{command} is searched
- for in @code{$PATH}.
- @item --keyring=@var{file}
- Use @var{file} as the keyring for upstream keys. @var{file} must be in the
- @dfn{keybox format}. Keybox files usually have a name ending in @file{.kbx}
- and the GNU@tie{}Privacy Guard (GPG) can manipulate these files
- (@pxref{kbxutil, @command{kbxutil},, gnupg, Using the GNU Privacy Guard}, for
- information on a tool to manipulate keybox files).
- When this option is omitted, @command{guix refresh} uses
- @file{~/.config/guix/upstream/trustedkeys.kbx} as the keyring for upstream
- signing keys. OpenPGP signatures are checked against keys from this keyring;
- missing keys are downloaded to this keyring as well (see
- @option{--key-download} below).
- You can export keys from your default GPG keyring into a keybox file using
- commands like this one:
- @example
- gpg --export rms@@gnu.org | kbxutil --import-openpgp >> mykeyring.kbx
- @end example
- Likewise, you can fetch keys to a specific keybox file like this:
- @example
- gpg --no-default-keyring --keyring mykeyring.kbx \
- --recv-keys @value{OPENPGP-SIGNING-KEY-ID}
- @end example
- @xref{GPG Configuration Options, @option{--keyring},, gnupg, Using the GNU
- Privacy Guard}, for more information on GPG's @option{--keyring} option.
- @item --key-download=@var{policy}
- Handle missing OpenPGP keys according to @var{policy}, which may be one
- of:
- @table @code
- @item always
- Always download missing OpenPGP keys from the key server, and add them
- to the user's GnuPG keyring.
- @item never
- Never try to download missing OpenPGP keys. Instead just bail out.
- @item interactive
- When a package signed with an unknown OpenPGP key is encountered, ask
- the user whether to download it or not. This is the default behavior.
- @end table
- @item --key-server=@var{host}
- Use @var{host} as the OpenPGP key server when importing a public key.
- @item --load-path=@var{directory}
- Add @var{directory} to the front of the package module search path
- (@pxref{Package Modules}).
- This allows users to define their own packages and make them visible to
- the command-line tools.
- @end table
- The @code{github} updater uses the
- @uref{https://developer.github.com/v3/, GitHub API} to query for new
- releases. When used repeatedly e.g.@: when refreshing all packages,
- GitHub will eventually refuse to answer any further API requests. By
- default 60 API requests per hour are allowed, and a full refresh on all
- GitHub packages in Guix requires more than this. Authentication with
- GitHub through the use of an API token alleviates these limits. To use
- an API token, set the environment variable @env{GUIX_GITHUB_TOKEN} to a
- token procured from @uref{https://github.com/settings/tokens} or
- otherwise.
- @node Invoking guix style
- @section Invoking @command{guix style}
- The @command{guix style} command helps packagers style their package
- definitions according to the latest fashionable trends. The command
- currently provides the following styling rules:
- @itemize
- @item
- formatting package definitions according to the project's conventions
- (@pxref{Formatting Code});
- @item
- rewriting package inputs to the ``new style'', as explained below.
- @end itemize
- The way package inputs are written is going through a transition
- (@pxref{package Reference}, for more on package inputs). Until version
- 1.3.0, package inputs were written using the ``old style'', where each
- input was given an explicit label, most of the time the package name:
- @lisp
- (package
- ;; @dots{}
- ;; The "old style" (deprecated).
- (inputs `(("libunistring" ,libunistring)
- ("libffi" ,libffi))))
- @end lisp
- Today, the old style is deprecated and the preferred style looks like
- this:
- @lisp
- (package
- ;; @dots{}
- ;; The "new style".
- (inputs (list libunistring libffi)))
- @end lisp
- Likewise, uses of @code{alist-delete} and friends to manipulate inputs
- is now deprecated in favor of @code{modify-inputs} (@pxref{Defining
- Package Variants}, for more info on @code{modify-inputs}).
- In the vast majority of cases, this is a purely mechanical change on the
- surface syntax that does not even incur a package rebuild. Running
- @command{guix style -S inputs} can do that for you, whether you're working on
- packages in Guix proper or in an external channel.
- The general syntax is:
- @example
- guix style [@var{options}] @var{package}@dots{}
- @end example
- This causes @command{guix style} to analyze and rewrite the definition
- of @var{package}@dots{} or, when @var{package} is omitted, of @emph{all}
- the packages. The @option{--styling} or @option{-S} option allows you
- to select the style rule, the default rule being @code{format}---see
- below.
- The available options are listed below.
- @table @code
- @item --dry-run
- @itemx -n
- Show source file locations that would be edited but do not modify them.
- @item --styling=@var{rule}
- @itemx -S @var{rule}
- Apply @var{rule}, one of the following styling rules:
- @table @code
- @item format
- Format the given package definition(s)---this is the default styling
- rule. For example, a packager running Guix on a checkout
- (@pxref{Running Guix Before It Is Installed}) might want to reformat the
- definition of the Coreutils package like so:
- @example
- ./pre-inst-env guix style coreutils
- @end example
- @item inputs
- Rewrite package inputs to the ``new style'', as described above. This
- is how you would rewrite inputs of package @code{whatnot} in your own
- channel:
- @example
- guix style -L ~/my/channel -S inputs whatnot
- @end example
- Rewriting is done in a conservative way: preserving comments and bailing
- out if it cannot make sense of the code that appears in an inputs field.
- The @option{--input-simplification} option described below provides
- fine-grain control over when inputs should be simplified.
- @end table
- @item --load-path=@var{directory}
- @itemx -L @var{directory}
- Add @var{directory} to the front of the package module search path
- (@pxref{Package Modules}).
- @item --expression=@var{expr}
- @itemx -e @var{expr}
- Style the package @var{expr} evaluates to.
- For example, running:
- @example
- guix style -e '(@@ (gnu packages gcc) gcc-5)'
- @end example
- styles the @code{gcc-5} package definition.
- @item --input-simplification=@var{policy}
- When using the @code{inputs} styling rule, with @samp{-S inputs}, this
- option specifies the package input simplification policy for cases where
- an input label does not match the corresponding package name.
- @var{policy} may be one of the following:
- @table @code
- @item silent
- Simplify inputs only when the change is ``silent'', meaning that the
- package does not need to be rebuilt (its derivation is unchanged).
- @item safe
- Simplify inputs only when that is ``safe'' to do: the package might need
- to be rebuilt, but the change is known to have no observable effect.
- @item always
- Simplify inputs even when input labels do not match package names, and
- even if that might have an observable effect.
- @end table
- The default is @code{silent}, meaning that input simplifications do not
- trigger any package rebuild.
- @end table
- @node Invoking guix lint
- @section Invoking @command{guix lint}
- @cindex @command{guix lint}
- @cindex package, checking for errors
- The @command{guix lint} command is meant to help package developers avoid
- common errors and use a consistent style. It runs a number of checks on
- a given set of packages in order to find common mistakes in their
- definitions. Available @dfn{checkers} include (see
- @option{--list-checkers} for a complete list):
- @table @code
- @item synopsis
- @itemx description
- Validate certain typographical and stylistic rules about package
- descriptions and synopses.
- @item inputs-should-be-native
- Identify inputs that should most likely be native inputs.
- @item source
- @itemx home-page
- @itemx mirror-url
- @itemx github-url
- @itemx source-file-name
- Probe @code{home-page} and @code{source} URLs and report those that are
- invalid. Suggest a @code{mirror://} URL when applicable. If the
- @code{source} URL redirects to a GitHub URL, recommend usage of the GitHub
- URL@. Check that the source file name is meaningful, e.g.@: is not just a
- version number or ``git-checkout'', without a declared @code{file-name}
- (@pxref{origin Reference}).
- @item source-unstable-tarball
- Parse the @code{source} URL to determine if a tarball from GitHub is
- autogenerated or if it is a release tarball. Unfortunately GitHub's
- autogenerated tarballs are sometimes regenerated.
- @item derivation
- Check that the derivation of the given packages can be successfully
- computed for all the supported systems (@pxref{Derivations}).
- @item profile-collisions
- Check whether installing the given packages in a profile would lead to
- collisions. Collisions occur when several packages with the same name
- but a different version or a different store file name are propagated.
- @xref{package Reference, @code{propagated-inputs}}, for more information
- on propagated inputs.
- @item archival
- @cindex Software Heritage, source code archive
- @cindex archival of source code, Software Heritage
- Checks whether the package's source code is archived at
- @uref{https://www.softwareheritage.org, Software Heritage}.
- When the source code that is not archived comes from a version-control system
- (VCS)---e.g., it's obtained with @code{git-fetch}, send Software Heritage a
- ``save'' request so that it eventually archives it. This ensures that the
- source will remain available in the long term, and that Guix can fall back to
- Software Heritage should the source code disappear from its original host.
- The status of recent ``save'' requests can be
- @uref{https://archive.softwareheritage.org/save/#requests, viewed on-line}.
- When source code is a tarball obtained with @code{url-fetch}, simply print a
- message when it is not archived. As of this writing, Software Heritage does
- not allow requests to save arbitrary tarballs; we are working on ways to
- ensure that non-VCS source code is also archived.
- Software Heritage
- @uref{https://archive.softwareheritage.org/api/#rate-limiting, limits the
- request rate per IP address}. When the limit is reached, @command{guix lint}
- prints a message and the @code{archival} checker stops doing anything until
- that limit has been reset.
- @item cve
- @cindex security vulnerabilities
- @cindex CVE, Common Vulnerabilities and Exposures
- Report known vulnerabilities found in the Common Vulnerabilities and
- Exposures (CVE) databases of the current and past year
- @uref{https://nvd.nist.gov/vuln/data-feeds, published by the US
- NIST}.
- To view information about a particular vulnerability, visit pages such as:
- @itemize
- @item
- @indicateurl{https://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-YYYY-ABCD}
- @item
- @indicateurl{https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-YYYY-ABCD}
- @end itemize
- @noindent
- where @code{CVE-YYYY-ABCD} is the CVE identifier---e.g.,
- @code{CVE-2015-7554}.
- Package developers can specify in package recipes the
- @uref{https://nvd.nist.gov/products/cpe,Common Platform Enumeration (CPE)}
- name and version of the package when they differ from the name or version
- that Guix uses, as in this example:
- @lisp
- (package
- (name "grub")
- ;; @dots{}
- ;; CPE calls this package "grub2".
- (properties '((cpe-name . "grub2")
- (cpe-version . "2.3"))))
- @end lisp
- @c See <https://www.openwall.com/lists/oss-security/2017/03/15/3>.
- Some entries in the CVE database do not specify which version of a
- package they apply to, and would thus ``stick around'' forever. Package
- developers who found CVE alerts and verified they can be ignored can
- declare them as in this example:
- @lisp
- (package
- (name "t1lib")
- ;; @dots{}
- ;; These CVEs no longer apply and can be safely ignored.
- (properties `((lint-hidden-cve . ("CVE-2011-0433"
- "CVE-2011-1553"
- "CVE-2011-1554"
- "CVE-2011-5244")))))
- @end lisp
- @item formatting
- Warn about obvious source code formatting issues: trailing white space,
- use of tabulations, etc.
- @item input-labels
- Report old-style input labels that do not match the name of the
- corresponding package. This aims to help migrate from the ``old input
- style''. @xref{package Reference}, for more information on package
- inputs and input styles. @xref{Invoking guix style}, on how to migrate
- to the new style.
- @end table
- The general syntax is:
- @example
- guix lint @var{options} @var{package}@dots{}
- @end example
- If no package is given on the command line, then all packages are checked.
- The @var{options} may be zero or more of the following:
- @table @code
- @item --list-checkers
- @itemx -l
- List and describe all the available checkers that will be run on packages
- and exit.
- @item --checkers
- @itemx -c
- Only enable the checkers specified in a comma-separated list using the
- names returned by @option{--list-checkers}.
- @item --exclude
- @itemx -x
- Only disable the checkers specified in a comma-separated list using the
- names returned by @option{--list-checkers}.
- @item --no-network
- @itemx -n
- Only enable the checkers that do not depend on Internet access.
- @item --load-path=@var{directory}
- @itemx -L @var{directory}
- Add @var{directory} to the front of the package module search path
- (@pxref{Package Modules}).
- This allows users to define their own packages and make them visible to
- the command-line tools.
- @end table
- @node Invoking guix size
- @section Invoking @command{guix size}
- @cindex size
- @cindex package size
- @cindex closure
- @cindex @command{guix size}
- The @command{guix size} command helps package developers profile the
- disk usage of packages. It is easy to overlook the impact of an
- additional dependency added to a package, or the impact of using a
- single output for a package that could easily be split (@pxref{Packages
- with Multiple Outputs}). Such are the typical issues that
- @command{guix size} can highlight.
- The command can be passed one or more package specifications
- such as @code{gcc@@4.8}
- or @code{guile:debug}, or a file name in the store. Consider this
- example:
- @example
- $ guix size coreutils
- store item total self
- /gnu/store/@dots{}-gcc-5.5.0-lib 60.4 30.1 38.1%
- /gnu/store/@dots{}-glibc-2.27 30.3 28.8 36.6%
- /gnu/store/@dots{}-coreutils-8.28 78.9 15.0 19.0%
- /gnu/store/@dots{}-gmp-6.1.2 63.1 2.7 3.4%
- /gnu/store/@dots{}-bash-static-4.4.12 1.5 1.5 1.9%
- /gnu/store/@dots{}-acl-2.2.52 61.1 0.4 0.5%
- /gnu/store/@dots{}-attr-2.4.47 60.6 0.2 0.3%
- /gnu/store/@dots{}-libcap-2.25 60.5 0.2 0.2%
- total: 78.9 MiB
- @end example
- @cindex closure
- The store items listed here constitute the @dfn{transitive closure} of
- Coreutils---i.e., Coreutils and all its dependencies, recursively---as
- would be returned by:
- @example
- $ guix gc -R /gnu/store/@dots{}-coreutils-8.23
- @end example
- Here the output shows three columns next to store items. The first column,
- labeled ``total'', shows the size in mebibytes (MiB) of the closure of
- the store item---that is, its own size plus the size of all its
- dependencies. The next column, labeled ``self'', shows the size of the
- item itself. The last column shows the ratio of the size of the item
- itself to the space occupied by all the items listed here.
- In this example, we see that the closure of Coreutils weighs in at
- 79@tie{}MiB, most of which is taken by libc and GCC's run-time support
- libraries. (That libc and GCC's libraries represent a large fraction of
- the closure is not a problem @i{per se} because they are always available
- on the system anyway.)
- Since the command also accepts store file names, assessing the size of
- a build result is straightforward:
- @example
- guix size $(guix system build config.scm)
- @end example
- When the package(s) passed to @command{guix size} are available in the
- store@footnote{More precisely, @command{guix size} looks for the
- @emph{ungrafted} variant of the given package(s), as returned by
- @code{guix build @var{package} --no-grafts}. @xref{Security Updates},
- for information on grafts.}, @command{guix size} queries the daemon to determine its
- dependencies, and measures its size in the store, similar to @command{du
- -ms --apparent-size} (@pxref{du invocation,,, coreutils, GNU
- Coreutils}).
- When the given packages are @emph{not} in the store, @command{guix size}
- reports information based on the available substitutes
- (@pxref{Substitutes}). This makes it possible it to profile disk usage of
- store items that are not even on disk, only available remotely.
- You can also specify several package names:
- @example
- $ guix size coreutils grep sed bash
- store item total self
- /gnu/store/@dots{}-coreutils-8.24 77.8 13.8 13.4%
- /gnu/store/@dots{}-grep-2.22 73.1 0.8 0.8%
- /gnu/store/@dots{}-bash-4.3.42 72.3 4.7 4.6%
- /gnu/store/@dots{}-readline-6.3 67.6 1.2 1.2%
- @dots{}
- total: 102.3 MiB
- @end example
- @noindent
- In this example we see that the combination of the four packages takes
- 102.3@tie{}MiB in total, which is much less than the sum of each closure
- since they have a lot of dependencies in common.
- When looking at the profile returned by @command{guix size}, you may
- find yourself wondering why a given package shows up in the profile at
- all. To understand it, you can use @command{guix graph --path -t
- references} to display the shortest path between the two packages
- (@pxref{Invoking guix graph}).
- The available options are:
- @table @option
- @item --substitute-urls=@var{urls}
- Use substitute information from @var{urls}.
- @xref{client-substitute-urls, the same option for @code{guix build}}.
- @item --sort=@var{key}
- Sort lines according to @var{key}, one of the following options:
- @table @code
- @item self
- the size of each item (the default);
- @item closure
- the total size of the item's closure.
- @end table
- @item --map-file=@var{file}
- Write a graphical map of disk usage in PNG format to @var{file}.
- For the example above, the map looks like this:
- @image{images/coreutils-size-map,5in,, map of Coreutils disk usage
- produced by @command{guix size}}
- This option requires that
- @uref{https://wingolog.org/software/guile-charting/, Guile-Charting} be
- installed and visible in Guile's module search path. When that is not
- the case, @command{guix size} fails as it tries to load it.
- @item --system=@var{system}
- @itemx -s @var{system}
- Consider packages for @var{system}---e.g., @code{x86_64-linux}.
- @item --load-path=@var{directory}
- @itemx -L @var{directory}
- Add @var{directory} to the front of the package module search path
- (@pxref{Package Modules}).
- This allows users to define their own packages and make them visible to
- the command-line tools.
- @end table
- @node Invoking guix graph
- @section Invoking @command{guix graph}
- @cindex DAG
- @cindex @command{guix graph}
- @cindex package dependencies
- Packages and their dependencies form a @dfn{graph}, specifically a
- directed acyclic graph (DAG). It can quickly become difficult to have a
- mental model of the package DAG, so the @command{guix graph} command
- provides a visual representation of the DAG@. By default,
- @command{guix graph} emits a DAG representation in the input format of
- @uref{https://www.graphviz.org/, Graphviz}, so its output can be passed
- directly to the @command{dot} command of Graphviz. It can also emit an
- HTML page with embedded JavaScript code to display a ``chord diagram''
- in a Web browser, using the @uref{https://d3js.org/, d3.js} library, or
- emit Cypher queries to construct a graph in a graph database supporting
- the @uref{https://www.opencypher.org/, openCypher} query language. With
- @option{--path}, it simply displays the shortest path between two
- packages. The general syntax is:
- @example
- guix graph @var{options} @var{package}@dots{}
- @end example
- For example, the following command generates a PDF file representing the
- package DAG for the GNU@tie{}Core Utilities, showing its build-time
- dependencies:
- @example
- guix graph coreutils | dot -Tpdf > dag.pdf
- @end example
- The output looks like this:
- @image{images/coreutils-graph,2in,,Dependency graph of the GNU Coreutils}
- Nice little graph, no?
- You may find it more pleasant to navigate the graph interactively with
- @command{xdot} (from the @code{xdot} package):
- @example
- guix graph coreutils | xdot -
- @end example
- But there is more than one graph! The one above is concise: it is the
- graph of package objects, omitting implicit inputs such as GCC, libc,
- grep, etc. It is often useful to have such a concise graph, but
- sometimes one may want to see more details. @command{guix graph} supports
- several types of graphs, allowing you to choose the level of detail:
- @table @code
- @item package
- This is the default type used in the example above. It shows the DAG of
- package objects, excluding implicit dependencies. It is concise, but
- filters out many details.
- @item reverse-package
- This shows the @emph{reverse} DAG of packages. For example:
- @example
- guix graph --type=reverse-package ocaml
- @end example
- ...@: yields the graph of packages that @emph{explicitly} depend on OCaml (if
- you are also interested in cases where OCaml is an implicit dependency, see
- @code{reverse-bag} below).
- Note that for core packages this can yield huge graphs. If all you want
- is to know the number of packages that depend on a given package, use
- @command{guix refresh --list-dependent} (@pxref{Invoking guix refresh,
- @option{--list-dependent}}).
- @item bag-emerged
- This is the package DAG, @emph{including} implicit inputs.
- For instance, the following command:
- @example
- guix graph --type=bag-emerged coreutils
- @end example
- ...@: yields this bigger graph:
- @image{images/coreutils-bag-graph,,5in,Detailed dependency graph of the GNU Coreutils}
- At the bottom of the graph, we see all the implicit inputs of
- @var{gnu-build-system} (@pxref{Build Systems, @code{gnu-build-system}}).
- Now, note that the dependencies of these implicit inputs---that is, the
- @dfn{bootstrap dependencies} (@pxref{Bootstrapping})---are not shown
- here, for conciseness.
- @item bag
- Similar to @code{bag-emerged}, but this time including all the bootstrap
- dependencies.
- @item bag-with-origins
- Similar to @code{bag}, but also showing origins and their dependencies.
- @item reverse-bag
- This shows the @emph{reverse} DAG of packages. Unlike @code{reverse-package},
- it also takes implicit dependencies into account. For example:
- @example
- guix graph -t reverse-bag dune
- @end example
- @noindent
- ...@: yields the graph of all packages that depend on Dune, directly or
- indirectly. Since Dune is an @emph{implicit} dependency of many packages
- @i{via} @code{dune-build-system}, this shows a large number of packages,
- whereas @code{reverse-package} would show very few if any.
- @item derivation
- This is the most detailed representation: It shows the DAG of
- derivations (@pxref{Derivations}) and plain store items. Compared to
- the above representation, many additional nodes are visible, including
- build scripts, patches, Guile modules, etc.
- For this type of graph, it is also possible to pass a @file{.drv} file
- name instead of a package name, as in:
- @example
- guix graph -t derivation $(guix system build -d my-config.scm)
- @end example
- @item module
- This is the graph of @dfn{package modules} (@pxref{Package Modules}).
- For example, the following command shows the graph for the package
- module that defines the @code{guile} package:
- @example
- guix graph -t module guile | xdot -
- @end example
- @end table
- All the types above correspond to @emph{build-time dependencies}. The
- following graph type represents the @emph{run-time dependencies}:
- @table @code
- @item references
- This is the graph of @dfn{references} of a package output, as returned
- by @command{guix gc --references} (@pxref{Invoking guix gc}).
- If the given package output is not available in the store, @command{guix
- graph} attempts to obtain dependency information from substitutes.
- Here you can also pass a store file name instead of a package name. For
- example, the command below produces the reference graph of your profile
- (which can be big!):
- @example
- guix graph -t references $(readlink -f ~/.guix-profile)
- @end example
- @item referrers
- This is the graph of the @dfn{referrers} of a store item, as returned by
- @command{guix gc --referrers} (@pxref{Invoking guix gc}).
- This relies exclusively on local information from your store. For
- instance, let us suppose that the current Inkscape is available in 10
- profiles on your machine; @command{guix graph -t referrers inkscape}
- will show a graph rooted at Inkscape and with those 10 profiles linked
- to it.
- It can help determine what is preventing a store item from being garbage
- collected.
- @end table
- @cindex shortest path, between packages
- Often, the graph of the package you are interested in does not fit on
- your screen, and anyway all you want to know is @emph{why} that package
- actually depends on some seemingly unrelated package. The
- @option{--path} option instructs @command{guix graph} to display the
- shortest path between two packages (or derivations, or store items,
- etc.):
- @example
- $ guix graph --path emacs libunistring
- emacs@@26.3
- mailutils@@3.9
- libunistring@@0.9.10
- $ guix graph --path -t derivation emacs libunistring
- /gnu/store/@dots{}-emacs-26.3.drv
- /gnu/store/@dots{}-mailutils-3.9.drv
- /gnu/store/@dots{}-libunistring-0.9.10.drv
- $ guix graph --path -t references emacs libunistring
- /gnu/store/@dots{}-emacs-26.3
- /gnu/store/@dots{}-libidn2-2.2.0
- /gnu/store/@dots{}-libunistring-0.9.10
- @end example
- Sometimes you still want to visualize the graph but would like to trim
- it so it can actually be displayed. One way to do it is via the
- @option{--max-depth} (or @option{-M}) option, which lets you specify the
- maximum depth of the graph. In the example below, we visualize only
- @code{libreoffice} and the nodes whose distance to @code{libreoffice} is
- at most 2:
- @example
- guix graph -M 2 libreoffice | xdot -f fdp -
- @end example
- Mind you, that's still a big ball of spaghetti, but at least
- @command{dot} can render it quickly and it can be browsed somewhat.
- The available options are the following:
- @table @option
- @item --type=@var{type}
- @itemx -t @var{type}
- Produce a graph output of @var{type}, where @var{type} must be one of
- the values listed above.
- @item --list-types
- List the supported graph types.
- @item --backend=@var{backend}
- @itemx -b @var{backend}
- Produce a graph using the selected @var{backend}.
- @item --list-backends
- List the supported graph backends.
- Currently, the available backends are Graphviz and d3.js.
- @item --path
- Display the shortest path between two nodes of the type specified by
- @option{--type}. The example below shows the shortest path between
- @code{libreoffice} and @code{llvm} according to the references of
- @code{libreoffice}:
- @example
- $ guix graph --path -t references libreoffice llvm
- /gnu/store/@dots{}-libreoffice-6.4.2.2
- /gnu/store/@dots{}-libepoxy-1.5.4
- /gnu/store/@dots{}-mesa-19.3.4
- /gnu/store/@dots{}-llvm-9.0.1
- @end example
- @item --expression=@var{expr}
- @itemx -e @var{expr}
- Consider the package @var{expr} evaluates to.
- This is useful to precisely refer to a package, as in this example:
- @example
- guix graph -e '(@@@@ (gnu packages commencement) gnu-make-final)'
- @end example
- @item --system=@var{system}
- @itemx -s @var{system}
- Display the graph for @var{system}---e.g., @code{i686-linux}.
- The package dependency graph is largely architecture-independent, but there
- are some architecture-dependent bits that this option allows you to visualize.
- @item --load-path=@var{directory}
- @itemx -L @var{directory}
- Add @var{directory} to the front of the package module search path
- (@pxref{Package Modules}).
- This allows users to define their own packages and make them visible to
- the command-line tools.
- @end table
- On top of that, @command{guix graph} supports all the usual package
- transformation options (@pxref{Package Transformation Options}). This
- makes it easy to view the effect of a graph-rewriting transformation
- such as @option{--with-input}. For example, the command below outputs
- the graph of @code{git} once @code{openssl} has been replaced by
- @code{libressl} everywhere in the graph:
- @example
- guix graph git --with-input=openssl=libressl
- @end example
- So many possibilities, so much fun!
- @node Invoking guix publish
- @section Invoking @command{guix publish}
- @cindex @command{guix publish}
- The purpose of @command{guix publish} is to enable users to easily share
- their store with others, who can then use it as a substitute server
- (@pxref{Substitutes}).
- When @command{guix publish} runs, it spawns an HTTP server which allows
- anyone with network access to obtain substitutes from it. This means
- that any machine running Guix can also act as if it were a build farm,
- since the HTTP interface is compatible with Cuirass, the software behind
- the @code{@value{SUBSTITUTE-SERVER-1}} build farm.
- For security, each substitute is signed, allowing recipients to check
- their authenticity and integrity (@pxref{Substitutes}). Because
- @command{guix publish} uses the signing key of the system, which is only
- readable by the system administrator, it must be started as root; the
- @option{--user} option makes it drop root privileges early on.
- The signing key pair must be generated before @command{guix publish} is
- launched, using @command{guix archive --generate-key} (@pxref{Invoking
- guix archive}).
- When the @option{--advertise} option is passed, the server advertises
- its availability on the local network using multicast DNS (mDNS) and DNS
- service discovery (DNS-SD), currently @i{via} Guile-Avahi (@pxref{Top,,,
- guile-avahi, Using Avahi in Guile Scheme Programs}).
- The general syntax is:
- @example
- guix publish @var{options}@dots{}
- @end example
- Running @command{guix publish} without any additional arguments will
- spawn an HTTP server on port 8080:
- @example
- guix publish
- @end example
- Once a publishing server has been authorized, the daemon may download
- substitutes from it. @xref{Getting Substitutes from Other Servers}.
- By default, @command{guix publish} compresses archives on the fly as it
- serves them. This ``on-the-fly'' mode is convenient in that it requires
- no setup and is immediately available. However, when serving lots of
- clients, we recommend using the @option{--cache} option, which enables
- caching of the archives before they are sent to clients---see below for
- details. The @command{guix weather} command provides a handy way to
- check what a server provides (@pxref{Invoking guix weather}).
- As a bonus, @command{guix publish} also serves as a content-addressed
- mirror for source files referenced in @code{origin} records
- (@pxref{origin Reference}). For instance, assuming @command{guix
- publish} is running on @code{example.org}, the following URL returns the
- raw @file{hello-2.10.tar.gz} file with the given SHA256 hash
- (represented in @code{nix-base32} format, @pxref{Invoking guix hash}):
- @example
- http://example.org/file/hello-2.10.tar.gz/sha256/0ssi1@dots{}ndq1i
- @end example
- Obviously, these URLs only work for files that are in the store; in
- other cases, they return 404 (``Not Found'').
- @cindex build logs, publication
- Build logs are available from @code{/log} URLs like:
- @example
- http://example.org/log/gwspk@dots{}-guile-2.2.3
- @end example
- @noindent
- When @command{guix-daemon} is configured to save compressed build logs,
- as is the case by default (@pxref{Invoking guix-daemon}), @code{/log}
- URLs return the compressed log as-is, with an appropriate
- @code{Content-Type} and/or @code{Content-Encoding} header. We recommend
- running @command{guix-daemon} with @option{--log-compression=gzip} since
- Web browsers can automatically decompress it, which is not the case with
- Bzip2 compression.
- The following options are available:
- @table @code
- @item --port=@var{port}
- @itemx -p @var{port}
- Listen for HTTP requests on @var{port}.
- @item --listen=@var{host}
- Listen on the network interface for @var{host}. The default is to
- accept connections from any interface.
- @item --user=@var{user}
- @itemx -u @var{user}
- Change privileges to @var{user} as soon as possible---i.e., once the
- server socket is open and the signing key has been read.
- @item --compression[=@var{method}[:@var{level}]]
- @itemx -C [@var{method}[:@var{level}]]
- Compress data using the given @var{method} and @var{level}. @var{method} is
- one of @code{lzip}, @code{zstd}, and @code{gzip}; when @var{method} is
- omitted, @code{gzip} is used.
- When @var{level} is zero, disable compression. The range 1 to 9 corresponds
- to different compression levels: 1 is the fastest, and 9 is the best
- (CPU-intensive). The default is 3.
- Usually, @code{lzip} compresses noticeably better than @code{gzip} for a
- small increase in CPU usage; see
- @uref{https://nongnu.org/lzip/lzip_benchmark.html,benchmarks on the lzip
- Web page}. However, @code{lzip} achieves low decompression throughput
- (on the order of 50@tie{}MiB/s on modern hardware), which can be a
- bottleneck for someone who downloads over a fast network connection.
- The compression ratio of @code{zstd} is between that of @code{lzip} and
- that of @code{gzip}; its main advantage is a
- @uref{https://facebook.github.io/zstd/,high decompression speed}.
- Unless @option{--cache} is used, compression occurs on the fly and
- the compressed streams are not
- cached. Thus, to reduce load on the machine that runs @command{guix
- publish}, it may be a good idea to choose a low compression level, to
- run @command{guix publish} behind a caching proxy, or to use
- @option{--cache}. Using @option{--cache} has the advantage that it
- allows @command{guix publish} to add @code{Content-Length} HTTP header
- to its responses.
- This option can be repeated, in which case every substitute gets compressed
- using all the selected methods, and all of them are advertised. This is
- useful when users may not support all the compression methods: they can select
- the one they support.
- @item --cache=@var{directory}
- @itemx -c @var{directory}
- Cache archives and meta-data (@code{.narinfo} URLs) to @var{directory}
- and only serve archives that are in cache.
- When this option is omitted, archives and meta-data are created
- on-the-fly. This can reduce the available bandwidth, especially when
- compression is enabled, since this may become CPU-bound. Another
- drawback of the default mode is that the length of archives is not known
- in advance, so @command{guix publish} does not add a
- @code{Content-Length} HTTP header to its responses, which in turn
- prevents clients from knowing the amount of data being downloaded.
- Conversely, when @option{--cache} is used, the first request for a store
- item (@i{via} a @code{.narinfo} URL) triggers a
- background process to @dfn{bake} the archive---computing its
- @code{.narinfo} and compressing the archive, if needed. Once the
- archive is cached in @var{directory}, subsequent requests succeed and
- are served directly from the cache, which guarantees that clients get
- the best possible bandwidth.
- That first @code{.narinfo} request nonetheless returns 200, provided the
- requested store item is ``small enough'', below the cache bypass
- threshold---see @option{--cache-bypass-threshold} below. That way,
- clients do not have to wait until the archive is baked. For larger
- store items, the first @code{.narinfo} request returns 404, meaning that
- clients have to wait until the archive is baked.
- The ``baking'' process is performed by worker threads. By default, one
- thread per CPU core is created, but this can be customized. See
- @option{--workers} below.
- When @option{--ttl} is used, cached entries are automatically deleted
- when they have expired.
- @item --workers=@var{N}
- When @option{--cache} is used, request the allocation of @var{N} worker
- threads to ``bake'' archives.
- @item --ttl=@var{ttl}
- Produce @code{Cache-Control} HTTP headers that advertise a time-to-live
- (TTL) of @var{ttl}. @var{ttl} must denote a duration: @code{5d} means 5
- days, @code{1m} means 1 month, and so on.
- This allows the user's Guix to keep substitute information in cache for
- @var{ttl}. However, note that @code{guix publish} does not itself
- guarantee that the store items it provides will indeed remain available
- for as long as @var{ttl}.
- Additionally, when @option{--cache} is used, cached entries that have
- not been accessed for @var{ttl} and that no longer have a corresponding
- item in the store, may be deleted.
- @item --negative-ttl=@var{ttl}
- Similarly produce @code{Cache-Control} HTTP headers to advertise the
- time-to-live (TTL) of @emph{negative} lookups---missing store items, for
- which the HTTP 404 code is returned. By default, no negative TTL is
- advertised.
- This parameter can help adjust server load and substitute latency by
- instructing cooperating clients to be more or less patient when a store
- item is missing.
- @item --cache-bypass-threshold=@var{size}
- When used in conjunction with @option{--cache}, store items smaller than
- @var{size} are immediately available, even when they are not yet in
- cache. @var{size} is a size in bytes, or it can be suffixed by @code{M}
- for megabytes and so on. The default is @code{10M}.
- ``Cache bypass'' allows you to reduce the publication delay for clients
- at the expense of possibly additional I/O and CPU use on the server
- side: depending on the client access patterns, those store items can end
- up being baked several times until a copy is available in cache.
- Increasing the threshold may be useful for sites that have few users, or
- to guarantee that users get substitutes even for store items that are
- not popular.
- @item --nar-path=@var{path}
- Use @var{path} as the prefix for the URLs of ``nar'' files
- (@pxref{Invoking guix archive, normalized archives}).
- By default, nars are served at a URL such as
- @code{/nar/gzip/@dots{}-coreutils-8.25}. This option allows you to
- change the @code{/nar} part to @var{path}.
- @item --public-key=@var{file}
- @itemx --private-key=@var{file}
- Use the specific @var{file}s as the public/private key pair used to sign
- the store items being published.
- The files must correspond to the same key pair (the private key is used
- for signing and the public key is merely advertised in the signature
- metadata). They must contain keys in the canonical s-expression format
- as produced by @command{guix archive --generate-key} (@pxref{Invoking
- guix archive}). By default, @file{/etc/guix/signing-key.pub} and
- @file{/etc/guix/signing-key.sec} are used.
- @item --repl[=@var{port}]
- @itemx -r [@var{port}]
- Spawn a Guile REPL server (@pxref{REPL Servers,,, guile, GNU Guile
- Reference Manual}) on @var{port} (37146 by default). This is used
- primarily for debugging a running @command{guix publish} server.
- @end table
- Enabling @command{guix publish} on Guix System is a one-liner: just
- instantiate a @code{guix-publish-service-type} service in the @code{services} field
- of the @code{operating-system} declaration (@pxref{guix-publish-service-type,
- @code{guix-publish-service-type}}).
- If you are instead running Guix on a ``foreign distro'', follow these
- instructions:
- @itemize
- @item
- If your host distro uses the systemd init system:
- @example
- # ln -s ~root/.guix-profile/lib/systemd/system/guix-publish.service \
- /etc/systemd/system/
- # systemctl start guix-publish && systemctl enable guix-publish
- @end example
- @item
- If your host distro uses the Upstart init system:
- @example
- # ln -s ~root/.guix-profile/lib/upstart/system/guix-publish.conf /etc/init/
- # start guix-publish
- @end example
- @item
- Otherwise, proceed similarly with your distro's init system.
- @end itemize
- @node Invoking guix challenge
- @section Invoking @command{guix challenge}
- @cindex reproducible builds
- @cindex verifiable builds
- @cindex @command{guix challenge}
- @cindex challenge
- Do the binaries provided by this server really correspond to the source
- code it claims to build? Is a package build process deterministic?
- These are the questions the @command{guix challenge} command attempts to
- answer.
- The former is obviously an important question: Before using a substitute
- server (@pxref{Substitutes}), one had better @emph{verify} that it
- provides the right binaries, and thus @emph{challenge} it. The latter
- is what enables the former: If package builds are deterministic, then
- independent builds of the package should yield the exact same result,
- bit for bit; if a server provides a binary different from the one
- obtained locally, it may be either corrupt or malicious.
- We know that the hash that shows up in @file{/gnu/store} file names is
- the hash of all the inputs of the process that built the file or
- directory---compilers, libraries, build scripts,
- etc. (@pxref{Introduction}). Assuming deterministic build processes,
- one store file name should map to exactly one build output.
- @command{guix challenge} checks whether there is, indeed, a single
- mapping by comparing the build outputs of several independent builds of
- any given store item.
- The command output looks like this:
- @smallexample
- $ guix challenge --substitute-urls="https://@value{SUBSTITUTE-SERVER-1} https://guix.example.org"
- updating list of substitutes from 'https://@value{SUBSTITUTE-SERVER-1}'... 100.0%
- updating list of substitutes from 'https://guix.example.org'... 100.0%
- /gnu/store/@dots{}-openssl-1.0.2d contents differ:
- local hash: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q
- https://@value{SUBSTITUTE-SERVER-1}/nar/@dots{}-openssl-1.0.2d: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q
- https://guix.example.org/nar/@dots{}-openssl-1.0.2d: 1zy4fmaaqcnjrzzajkdn3f5gmjk754b43qkq47llbyak9z0qjyim
- differing files:
- /lib/libcrypto.so.1.1
- /lib/libssl.so.1.1
- /gnu/store/@dots{}-git-2.5.0 contents differ:
- local hash: 00p3bmryhjxrhpn2gxs2fy0a15lnip05l97205pgbk5ra395hyha
- https://@value{SUBSTITUTE-SERVER-1}/nar/@dots{}-git-2.5.0: 069nb85bv4d4a6slrwjdy8v1cn4cwspm3kdbmyb81d6zckj3nq9f
- https://guix.example.org/nar/@dots{}-git-2.5.0: 0mdqa9w1p6cmli6976v4wi0sw9r4p5prkj7lzfd1877wk11c9c73
- differing file:
- /libexec/git-core/git-fsck
- /gnu/store/@dots{}-pius-2.1.1 contents differ:
- local hash: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax
- https://@value{SUBSTITUTE-SERVER-1}/nar/@dots{}-pius-2.1.1: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax
- https://guix.example.org/nar/@dots{}-pius-2.1.1: 1cy25x1a4fzq5rk0pmvc8xhwyffnqz95h2bpvqsz2mpvlbccy0gs
- differing file:
- /share/man/man1/pius.1.gz
- @dots{}
- 6,406 store items were analyzed:
- - 4,749 (74.1%) were identical
- - 525 (8.2%) differed
- - 1,132 (17.7%) were inconclusive
- @end smallexample
- @noindent
- In this example, @command{guix challenge} first scans the store to
- determine the set of locally-built derivations---as opposed to store
- items that were downloaded from a substitute server---and then queries
- all the substitute servers. It then reports those store items for which
- the servers obtained a result different from the local build.
- @cindex non-determinism, in package builds
- As an example, @code{guix.example.org} always gets a different answer.
- Conversely, @code{@value{SUBSTITUTE-SERVER-1}} agrees with local builds, except in the
- case of Git. This might indicate that the build process of Git is
- non-deterministic, meaning that its output varies as a function of
- various things that Guix does not fully control, in spite of building
- packages in isolated environments (@pxref{Features}). Most common
- sources of non-determinism include the addition of timestamps in build
- results, the inclusion of random numbers, and directory listings sorted
- by inode number. See @uref{https://reproducible-builds.org/docs/}, for
- more information.
- To find out what is wrong with this Git binary, the easiest approach is
- to run:
- @example
- guix challenge git \
- --diff=diffoscope \
- --substitute-urls="https://@value{SUBSTITUTE-SERVER-1} https://guix.example.org"
- @end example
- This automatically invokes @command{diffoscope}, which displays detailed
- information about files that differ.
- Alternatively, we can do something along these lines (@pxref{Invoking guix
- archive}):
- @example
- $ wget -q -O - https://@value{SUBSTITUTE-SERVER-1}/nar/lzip/@dots{}-git-2.5.0 \
- | lzip -d | guix archive -x /tmp/git
- $ diff -ur --no-dereference /gnu/store/@dots{}-git.2.5.0 /tmp/git
- @end example
- This command shows the difference between the files resulting from the
- local build, and the files resulting from the build on
- @code{@value{SUBSTITUTE-SERVER-1}} (@pxref{Overview, Comparing and Merging Files,,
- diffutils, Comparing and Merging Files}). The @command{diff} command
- works great for text files. When binary files differ, a better option
- is @uref{https://diffoscope.org/, Diffoscope}, a tool that helps
- visualize differences for all kinds of files.
- Once you have done that work, you can tell whether the differences are due
- to a non-deterministic build process or to a malicious server. We try
- hard to remove sources of non-determinism in packages to make it easier
- to verify substitutes, but of course, this is a process that
- involves not just Guix, but a large part of the free software community.
- In the meantime, @command{guix challenge} is one tool to help address
- the problem.
- If you are writing packages for Guix, you are encouraged to check
- whether @code{@value{SUBSTITUTE-SERVER-1}} and other substitute servers obtain the
- same build result as you did with:
- @example
- $ guix challenge @var{package}
- @end example
- @noindent
- where @var{package} is a package specification such as
- @code{guile@@2.0} or @code{glibc:debug}.
- The general syntax is:
- @example
- guix challenge @var{options} [@var{packages}@dots{}]
- @end example
- When a difference is found between the hash of a locally-built item and
- that of a server-provided substitute, or among substitutes provided by
- different servers, the command displays it as in the example above and
- its exit code is 2 (other non-zero exit codes denote other kinds of
- errors).
- The one option that matters is:
- @table @code
- @item --substitute-urls=@var{urls}
- Consider @var{urls} the whitespace-separated list of substitute source
- URLs to compare to.
- @item --diff=@var{mode}
- Upon mismatches, show differences according to @var{mode}, one of:
- @table @asis
- @item @code{simple} (the default)
- Show the list of files that differ.
- @item @code{diffoscope}
- @itemx @var{command}
- Invoke @uref{https://diffoscope.org/, Diffoscope}, passing it
- two directories whose contents do not match.
- When @var{command} is an absolute file name, run @var{command} instead
- of Diffoscope.
- @item @code{none}
- Do not show further details about the differences.
- @end table
- Thus, unless @option{--diff=none} is passed, @command{guix challenge}
- downloads the store items from the given substitute servers so that it
- can compare them.
- @item --verbose
- @itemx -v
- Show details about matches (identical contents) in addition to
- information about mismatches.
- @end table
- @node Invoking guix copy
- @section Invoking @command{guix copy}
- @cindex copy, of store items, over SSH
- @cindex SSH, copy of store items
- @cindex sharing store items across machines
- @cindex transferring store items across machines
- The @command{guix copy} command copies items from the store of one
- machine to that of another machine over a secure shell (SSH)
- connection@footnote{This command is available only when Guile-SSH was
- found. @xref{Requirements}, for details.}. For example, the following
- command copies the @code{coreutils} package, the user's profile, and all
- their dependencies over to @var{host}, logged in as @var{user}:
- @example
- guix copy --to=@var{user}@@@var{host} \
- coreutils $(readlink -f ~/.guix-profile)
- @end example
- If some of the items to be copied are already present on @var{host},
- they are not actually sent.
- The command below retrieves @code{libreoffice} and @code{gimp} from
- @var{host}, assuming they are available there:
- @example
- guix copy --from=@var{host} libreoffice gimp
- @end example
- The SSH connection is established using the Guile-SSH client, which is
- compatible with OpenSSH: it honors @file{~/.ssh/known_hosts} and
- @file{~/.ssh/config}, and uses the SSH agent for authentication.
- The key used to sign items that are sent must be accepted by the remote
- machine. Likewise, the key used by the remote machine to sign items you
- are retrieving must be in @file{/etc/guix/acl} so it is accepted by your
- own daemon. @xref{Invoking guix archive}, for more information about
- store item authentication.
- The general syntax is:
- @example
- guix copy [--to=@var{spec}|--from=@var{spec}] @var{items}@dots{}
- @end example
- You must always specify one of the following options:
- @table @code
- @item --to=@var{spec}
- @itemx --from=@var{spec}
- Specify the host to send to or receive from. @var{spec} must be an SSH
- spec such as @code{example.org}, @code{charlie@@example.org}, or
- @code{charlie@@example.org:2222}.
- @end table
- The @var{items} can be either package names, such as @code{gimp}, or
- store items, such as @file{/gnu/store/@dots{}-idutils-4.6}.
- When specifying the name of a package to send, it is first built if
- needed, unless @option{--dry-run} was specified. Common build options
- are supported (@pxref{Common Build Options}).
- @node Invoking guix container
- @section Invoking @command{guix container}
- @cindex container
- @cindex @command{guix container}
- @quotation Note
- As of version @value{VERSION}, this tool is experimental. The interface
- is subject to radical change in the future.
- @end quotation
- The purpose of @command{guix container} is to manipulate processes
- running within an isolated environment, commonly known as a
- ``container'', typically created by the @command{guix shell}
- (@pxref{Invoking guix shell}) and @command{guix system container}
- (@pxref{Invoking guix system}) commands.
- The general syntax is:
- @example
- guix container @var{action} @var{options}@dots{}
- @end example
- @var{action} specifies the operation to perform with a container, and
- @var{options} specifies the context-specific arguments for the action.
- The following actions are available:
- @table @code
- @item exec
- Execute a command within the context of a running container.
- The syntax is:
- @example
- guix container exec @var{pid} @var{program} @var{arguments}@dots{}
- @end example
- @var{pid} specifies the process ID of the running container.
- @var{program} specifies an executable file name within the root file
- system of the container. @var{arguments} are the additional options that
- will be passed to @var{program}.
- The following command launches an interactive login shell inside a
- Guix system container, started by @command{guix system container}, and whose
- process ID is 9001:
- @example
- guix container exec 9001 /run/current-system/profile/bin/bash --login
- @end example
- Note that the @var{pid} cannot be the parent process of a container. It
- must be PID 1 of the container or one of its child processes.
- @end table
- @node Invoking guix weather
- @section Invoking @command{guix weather}
- Occasionally you're grumpy because substitutes are lacking and you end
- up building packages by yourself (@pxref{Substitutes}). The
- @command{guix weather} command reports on substitute availability on the
- specified servers so you can have an idea of whether you'll be grumpy
- today. It can sometimes be useful info as a user, but it is primarily
- useful to people running @command{guix publish} (@pxref{Invoking guix
- publish}).
- @cindex statistics, for substitutes
- @cindex availability of substitutes
- @cindex substitute availability
- @cindex weather, substitute availability
- Here's a sample run:
- @example
- $ guix weather --substitute-urls=https://guix.example.org
- computing 5,872 package derivations for x86_64-linux...
- looking for 6,128 store items on https://guix.example.org..
- updating list of substitutes from 'https://guix.example.org'... 100.0%
- https://guix.example.org
- 43.4% substitutes available (2,658 out of 6,128)
- 7,032.5 MiB of nars (compressed)
- 19,824.2 MiB on disk (uncompressed)
- 0.030 seconds per request (182.9 seconds in total)
- 33.5 requests per second
- 9.8% (342 out of 3,470) of the missing items are queued
- 867 queued builds
- x86_64-linux: 518 (59.7%)
- i686-linux: 221 (25.5%)
- aarch64-linux: 128 (14.8%)
- build rate: 23.41 builds per hour
- x86_64-linux: 11.16 builds per hour
- i686-linux: 6.03 builds per hour
- aarch64-linux: 6.41 builds per hour
- @end example
- @cindex continuous integration, statistics
- As you can see, it reports the fraction of all the packages for which
- substitutes are available on the server---regardless of whether
- substitutes are enabled, and regardless of whether this server's signing
- key is authorized. It also reports the size of the compressed archives
- (``nars'') provided by the server, the size the corresponding store
- items occupy in the store (assuming deduplication is turned off), and
- the server's throughput. The second part gives continuous integration
- (CI) statistics, if the server supports it. In addition, using the
- @option{--coverage} option, @command{guix weather} can list ``important''
- package substitutes missing on the server (see below).
- To achieve that, @command{guix weather} queries over HTTP(S) meta-data
- (@dfn{narinfos}) for all the relevant store items. Like @command{guix
- challenge}, it ignores signatures on those substitutes, which is
- innocuous since the command only gathers statistics and cannot install
- those substitutes.
- The general syntax is:
- @example
- guix weather @var{options}@dots{} [@var{packages}@dots{}]
- @end example
- When @var{packages} is omitted, @command{guix weather} checks the availability
- of substitutes for @emph{all} the packages, or for those specified with
- @option{--manifest}; otherwise it only considers the specified packages. It
- is also possible to query specific system types with @option{--system}.
- @command{guix weather} exits with a non-zero code when the fraction of
- available substitutes is below 100%.
- The available options are listed below.
- @table @code
- @item --substitute-urls=@var{urls}
- @var{urls} is the space-separated list of substitute server URLs to
- query. When this option is omitted, the default set of substitute
- servers is queried.
- @item --system=@var{system}
- @itemx -s @var{system}
- Query substitutes for @var{system}---e.g., @code{aarch64-linux}. This
- option can be repeated, in which case @command{guix weather} will query
- substitutes for several system types.
- @item --manifest=@var{file}
- Instead of querying substitutes for all the packages, only ask for those
- specified in @var{file}. @var{file} must contain a @dfn{manifest}, as
- with the @code{-m} option of @command{guix package} (@pxref{Invoking
- guix package}).
- This option can be repeated several times, in which case the manifests
- are concatenated.
- @item --coverage[=@var{count}]
- @itemx -c [@var{count}]
- Report on substitute coverage for packages: list packages with at least
- @var{count} dependents (zero by default) for which substitutes are
- unavailable. Dependent packages themselves are not listed: if @var{b} depends
- on @var{a} and @var{a} has no substitutes, only @var{a} is listed, even though
- @var{b} usually lacks substitutes as well. The result looks like this:
- @example
- $ guix weather --substitute-urls=@value{SUBSTITUTE-URLS} -c 10
- computing 8,983 package derivations for x86_64-linux...
- looking for 9,343 store items on @value{SUBSTITUTE-URLS}...
- updating substitutes from '@value{SUBSTITUTE-URLS}'... 100.0%
- @value{SUBSTITUTE-URLS}
- 64.7% substitutes available (6,047 out of 9,343)
- @dots{}
- 2502 packages are missing from '@value{SUBSTITUTE-URLS}' for 'x86_64-linux', among which:
- 58 kcoreaddons@@5.49.0 /gnu/store/@dots{}-kcoreaddons-5.49.0
- 46 qgpgme@@1.11.1 /gnu/store/@dots{}-qgpgme-1.11.1
- 37 perl-http-cookiejar@@0.008 /gnu/store/@dots{}-perl-http-cookiejar-0.008
- @dots{}
- @end example
- What this example shows is that @code{kcoreaddons} and presumably the 58
- packages that depend on it have no substitutes at
- @code{@value{SUBSTITUTE-SERVER-1}}; likewise for @code{qgpgme} and the 46
- packages that depend on it.
- If you are a Guix developer, or if you are taking care of this build farm,
- you'll probably want to have a closer look at these packages: they may simply
- fail to build.
- @item --display-missing
- Display the list of store items for which substitutes are missing.
- @end table
- @node Invoking guix processes
- @section Invoking @command{guix processes}
- The @command{guix processes} command can be useful to developers and system
- administrators, especially on multi-user machines and on build farms: it lists
- the current sessions (connections to the daemon), as well as information about
- the processes involved@footnote{Remote sessions, when @command{guix-daemon} is
- started with @option{--listen} specifying a TCP endpoint, are @emph{not}
- listed.}. Here's an example of the information it returns:
- @example
- $ sudo guix processes
- SessionPID: 19002
- ClientPID: 19090
- ClientCommand: guix shell python
- SessionPID: 19402
- ClientPID: 19367
- ClientCommand: guix publish -u guix-publish -p 3000 -C 9 @dots{}
- SessionPID: 19444
- ClientPID: 19419
- ClientCommand: cuirass --cache-directory /var/cache/cuirass @dots{}
- LockHeld: /gnu/store/@dots{}-perl-ipc-cmd-0.96.lock
- LockHeld: /gnu/store/@dots{}-python-six-bootstrap-1.11.0.lock
- LockHeld: /gnu/store/@dots{}-libjpeg-turbo-2.0.0.lock
- ChildPID: 20495
- ChildCommand: guix offload x86_64-linux 7200 1 28800
- ChildPID: 27733
- ChildCommand: guix offload x86_64-linux 7200 1 28800
- ChildPID: 27793
- ChildCommand: guix offload x86_64-linux 7200 1 28800
- @end example
- In this example we see that @command{guix-daemon} has three clients:
- @command{guix environment}, @command{guix publish}, and the Cuirass continuous
- integration tool; their process identifier (PID) is given by the
- @code{ClientPID} field. The @code{SessionPID} field gives the PID of the
- @command{guix-daemon} sub-process of this particular session.
- The @code{LockHeld} fields show which store items are currently locked
- by this session, which corresponds to store items being built or
- substituted (the @code{LockHeld} field is not displayed when
- @command{guix processes} is not running as root). Last, by looking at
- the @code{ChildPID} and @code{ChildCommand} fields, we understand that
- these three builds are being offloaded (@pxref{Daemon Offload Setup}).
- The output is in Recutils format so we can use the handy @command{recsel}
- command to select sessions of interest (@pxref{Selection Expressions,,,
- recutils, GNU recutils manual}). As an example, the command shows the command
- line and PID of the client that triggered the build of a Perl package:
- @example
- $ sudo guix processes | \
- recsel -p ClientPID,ClientCommand -e 'LockHeld ~ "perl"'
- ClientPID: 19419
- ClientCommand: cuirass --cache-directory /var/cache/cuirass @dots{}
- @end example
- Additional options are listed below.
- @table @code
- @item --format=@var{format}
- @itemx -f @var{format}
- Produce output in the specified @var{format}, one of:
- @table @code
- @item recutils
- The default option. It outputs a set of Session recutils records
- that include each @code{ChildProcess} as a field.
- @item normalized
- Normalize the output records into record sets (@pxref{Record Sets,,,
- recutils, GNU recutils manual}). Normalizing into record sets allows
- joins across record types. The example below lists the PID of each
- @code{ChildProcess} and the associated PID for @code{Session} that
- spawned the @code{ChildProcess} where the @code{Session} was started
- using @command{guix build}.
- @example
- $ guix processes --format=normalized | \
- recsel \
- -j Session \
- -t ChildProcess \
- -p Session.PID,PID \
- -e 'Session.ClientCommand ~ "guix build"'
- PID: 4435
- Session_PID: 4278
- PID: 4554
- Session_PID: 4278
- PID: 4646
- Session_PID: 4278
- @end example
- @end table
- @end table
- @node System Configuration
- @chapter System Configuration
- @cindex system configuration
- Guix System supports a consistent whole-system configuration
- mechanism. By that we mean that all aspects of the global system
- configuration---such as the available system services, timezone and
- locale settings, user accounts---are declared in a single place. Such
- a @dfn{system configuration} can be @dfn{instantiated}---i.e., effected.
- One of the advantages of putting all the system configuration under the
- control of Guix is that it supports transactional system upgrades, and
- makes it possible to roll back to a previous system instantiation,
- should something go wrong with the new one (@pxref{Features}). Another
- advantage is that it makes it easy to replicate the exact same configuration
- across different machines, or at different points in time, without
- having to resort to additional administration tools layered on top of
- the own tools of the system.
- @c Yes, we're talking of Puppet, Chef, & co. here. ↑
- This section describes this mechanism. First we focus on the system
- administrator's viewpoint---explaining how the system is configured and
- instantiated. Then we show how this mechanism can be extended, for
- instance to support new system services.
- @menu
- * Using the Configuration System:: Customizing your GNU system.
- * operating-system Reference:: Detail of operating-system declarations.
- * File Systems:: Configuring file system mounts.
- * Mapped Devices:: Block device extra processing.
- * Swap Space:: Backing RAM with disk space.
- * User Accounts:: Specifying user accounts.
- * Keyboard Layout:: How the system interprets key strokes.
- * Locales:: Language and cultural convention settings.
- * Services:: Specifying system services.
- * Setuid Programs:: Programs running with root privileges.
- * X.509 Certificates:: Authenticating HTTPS servers.
- * Name Service Switch:: Configuring libc's name service switch.
- * Initial RAM Disk:: Linux-Libre bootstrapping.
- * Bootloader Configuration:: Configuring the boot loader.
- * Invoking guix system:: Instantiating a system configuration.
- * Invoking guix deploy:: Deploying a system configuration to a remote host.
- * Running Guix in a VM:: How to run Guix System in a virtual machine.
- * Defining Services:: Adding new service definitions.
- @end menu
- @node Using the Configuration System
- @section Using the Configuration System
- The operating system is configured by providing an
- @code{operating-system} declaration in a file that can then be passed to
- the @command{guix system} command (@pxref{Invoking guix system}). A
- simple setup, with the default system services, the default Linux-Libre
- kernel, initial RAM disk, and boot loader looks like this:
- @findex operating-system
- @lisp
- @include os-config-bare-bones.texi
- @end lisp
- This example should be self-describing. Some of the fields defined
- above, such as @code{host-name} and @code{bootloader}, are mandatory.
- Others, such as @code{packages} and @code{services}, can be omitted, in
- which case they get a default value.
- Below we discuss the effect of some of the most important fields
- (@pxref{operating-system Reference}, for details about all the available
- fields), and how to @dfn{instantiate} the operating system using
- @command{guix system}.
- @unnumberedsubsec Bootloader
- @cindex legacy boot, on Intel machines
- @cindex BIOS boot, on Intel machines
- @cindex UEFI boot
- @cindex EFI boot
- The @code{bootloader} field describes the method that will be used to boot
- your system. Machines based on Intel processors can boot in ``legacy'' BIOS
- mode, as in the example above. However, more recent machines rely instead on
- the @dfn{Unified Extensible Firmware Interface} (UEFI) to boot. In that case,
- the @code{bootloader} field should contain something along these lines:
- @lisp
- (bootloader-configuration
- (bootloader grub-efi-bootloader)
- (targets '("/boot/efi")))
- @end lisp
- @xref{Bootloader Configuration}, for more information on the available
- configuration options.
- @unnumberedsubsec Globally-Visible Packages
- @vindex %base-packages
- The @code{packages} field lists packages that will be globally visible
- on the system, for all user accounts---i.e., in every user's @env{PATH}
- environment variable---in addition to the per-user profiles
- (@pxref{Invoking guix package}). The @code{%base-packages} variable
- provides all the tools one would expect for basic user and administrator
- tasks---including the GNU Core Utilities, the GNU Networking Utilities,
- the @command{mg} lightweight text editor, @command{find}, @command{grep},
- etc. The example above adds GNU@tie{}Screen to those,
- taken from the @code{(gnu packages screen)}
- module (@pxref{Package Modules}). The
- @code{(list package output)} syntax can be used to add a specific output
- of a package:
- @lisp
- (use-modules (gnu packages))
- (use-modules (gnu packages dns))
- (operating-system
- ;; ...
- (packages (cons (list isc-bind "utils")
- %base-packages)))
- @end lisp
- @findex specification->package
- Referring to packages by variable name, like @code{isc-bind} above, has
- the advantage of being unambiguous; it also allows typos and such to be
- diagnosed right away as ``unbound variables''. The downside is that one
- needs to know which module defines which package, and to augment the
- @code{use-package-modules} line accordingly. To avoid that, one can use
- the @code{specification->package} procedure of the @code{(gnu packages)}
- module, which returns the best package for a given name or name and
- version:
- @lisp
- (use-modules (gnu packages))
- (operating-system
- ;; ...
- (packages (append (map specification->package
- '("tcpdump" "htop" "gnupg@@2.0"))
- %base-packages)))
- @end lisp
- @unnumberedsubsec System Services
- @cindex services
- @vindex %base-services
- The @code{services} field lists @dfn{system services} to be made
- available when the system starts (@pxref{Services}).
- The @code{operating-system} declaration above specifies that, in
- addition to the basic services, we want the OpenSSH secure shell
- daemon listening on port 2222 (@pxref{Networking Services,
- @code{openssh-service-type}}). Under the hood,
- @code{openssh-service-type} arranges so that @command{sshd} is started with the
- right command-line options, possibly with supporting configuration files
- generated as needed (@pxref{Defining Services}).
- @cindex customization, of services
- @findex modify-services
- Occasionally, instead of using the base services as is, you will want to
- customize them. To do this, use @code{modify-services} (@pxref{Service
- Reference, @code{modify-services}}) to modify the list.
- @anchor{auto-login to TTY} For example, suppose you want to modify
- @code{guix-daemon} and Mingetty (the console log-in) in the
- @code{%base-services} list (@pxref{Base Services,
- @code{%base-services}}). To do that, you can write the following in
- your operating system declaration:
- @lisp
- (define %my-services
- ;; My very own list of services.
- (modify-services %base-services
- (guix-service-type config =>
- (guix-configuration
- (inherit config)
- ;; Fetch substitutes from example.org.
- (substitute-urls
- (list "https://example.org/guix"
- "https://ci.guix.gnu.org"))))
- (mingetty-service-type config =>
- (mingetty-configuration
- (inherit config)
- ;; Automatically log in as "guest".
- (auto-login "guest")))))
- (operating-system
- ;; @dots{}
- (services %my-services))
- @end lisp
- This changes the configuration---i.e., the service parameters---of the
- @code{guix-service-type} instance, and that of all the
- @code{mingetty-service-type} instances in the @code{%base-services} list
- (@pxref{Auto-Login to a Specific TTY, see the cookbook for how to
- auto-login one user to a specific TTY,, guix-cookbook, GNU Guix Cookbook})).
- Observe how this is accomplished: first, we arrange for the original
- configuration to be bound to the identifier @code{config} in the
- @var{body}, and then we write the @var{body} so that it evaluates to the
- desired configuration. In particular, notice how we use @code{inherit}
- to create a new configuration which has the same values as the old
- configuration, but with a few modifications.
- @cindex encrypted disk
- The configuration for a typical ``desktop'' usage, with an encrypted
- root partition, a swap file on the root partition, the X11 display
- server, GNOME and Xfce (users can choose which of these desktop
- environments to use at the log-in screen by pressing @kbd{F1}), network
- management, power management, and more, would look like this:
- @lisp
- @include os-config-desktop.texi
- @end lisp
- A graphical system with a choice of lightweight window managers
- instead of full-blown desktop environments would look like this:
- @lisp
- @include os-config-lightweight-desktop.texi
- @end lisp
- This example refers to the @file{/boot/efi} file system by its UUID,
- @code{1234-ABCD}. Replace this UUID with the right UUID on your system,
- as returned by the @command{blkid} command.
- @xref{Desktop Services}, for the exact list of services provided by
- @code{%desktop-services}. @xref{X.509 Certificates}, for background
- information about the @code{nss-certs} package that is used here.
- Again, @code{%desktop-services} is just a list of service objects. If
- you want to remove services from there, you can do so using the
- procedures for list filtering (@pxref{SRFI-1 Filtering and
- Partitioning,,, guile, GNU Guile Reference Manual}). For instance, the
- following expression returns a list that contains all the services in
- @code{%desktop-services} minus the Avahi service:
- @lisp
- (remove (lambda (service)
- (eq? (service-kind service) avahi-service-type))
- %desktop-services)
- @end lisp
- Alternatively, the @code{modify-services} macro can be used:
- @lisp
- (modify-services %desktop-services
- (delete avahi-service-type))
- @end lisp
- @unnumberedsubsec Instantiating the System
- Assuming the @code{operating-system} declaration
- is stored in the @file{my-system-config.scm}
- file, the @command{guix system reconfigure my-system-config.scm} command
- instantiates that configuration, and makes it the default GRUB boot
- entry (@pxref{Invoking guix system}).
- The normal way to change the system configuration is by updating this
- file and re-running @command{guix system reconfigure}. One should never
- have to touch files in @file{/etc} or to run commands that modify the
- system state such as @command{useradd} or @command{grub-install}. In
- fact, you must avoid that since that would not only void your warranty
- but also prevent you from rolling back to previous versions of your
- system, should you ever need to.
- @cindex roll-back, of the operating system
- Speaking of roll-back, each time you run @command{guix system
- reconfigure}, a new @dfn{generation} of the system is created---without
- modifying or deleting previous generations. Old system generations get
- an entry in the bootloader boot menu, allowing you to boot them in case
- something went wrong with the latest generation. Reassuring, no? The
- @command{guix system list-generations} command lists the system
- generations available on disk. It is also possible to roll back the
- system via the commands @command{guix system roll-back} and
- @command{guix system switch-generation}.
- Although the @command{guix system reconfigure} command will not modify
- previous generations, you must take care when the current generation is not
- the latest (e.g., after invoking @command{guix system roll-back}), since
- the operation might overwrite a later generation (@pxref{Invoking guix
- system}).
- @unnumberedsubsec The Programming Interface
- At the Scheme level, the bulk of an @code{operating-system} declaration
- is instantiated with the following monadic procedure (@pxref{The Store
- Monad}):
- @deffn {Monadic Procedure} operating-system-derivation os
- Return a derivation that builds @var{os}, an @code{operating-system}
- object (@pxref{Derivations}).
- The output of the derivation is a single directory that refers to all
- the packages, configuration files, and other supporting files needed to
- instantiate @var{os}.
- @end deffn
- This procedure is provided by the @code{(gnu system)} module. Along
- with @code{(gnu services)} (@pxref{Services}), this module contains the
- guts of Guix System. Make sure to visit it!
- @node operating-system Reference
- @section @code{operating-system} Reference
- This section summarizes all the options available in
- @code{operating-system} declarations (@pxref{Using the Configuration
- System}).
- @deftp {Data Type} operating-system
- This is the data type representing an operating system configuration.
- By that, we mean all the global system configuration, not per-user
- configuration (@pxref{Using the Configuration System}).
- @table @asis
- @item @code{kernel} (default: @code{linux-libre})
- The package object of the operating system kernel to
- use@footnote{Currently only the Linux-libre kernel is fully supported.
- Using GNU@tie{}mach with the GNU@tie{}Hurd is experimental and only
- available when building a virtual machine disk image.}.
- @cindex hurd
- @item @code{hurd} (default: @code{#f})
- The package object of the Hurd to be started by the kernel. When this
- field is set, produce a GNU/Hurd operating system. In that case,
- @code{kernel} must also be set to the @code{gnumach} package---the
- microkernel the Hurd runs on.
- @quotation Warning
- This feature is experimental and only supported for disk images.
- @end quotation
- @item @code{kernel-loadable-modules} (default: '())
- A list of objects (usually packages) to collect loadable kernel modules
- from--e.g. @code{(list ddcci-driver-linux)}.
- @item @code{kernel-arguments} (default: @code{%default-kernel-arguments})
- List of strings or gexps representing additional arguments to pass on
- the command-line of the kernel---e.g., @code{("console=ttyS0")}.
- @item @code{bootloader}
- The system bootloader configuration object. @xref{Bootloader Configuration}.
- @item @code{label}
- This is the label (a string) as it appears in the bootloader's menu entry.
- The default label includes the kernel name and version.
- @item @code{keyboard-layout} (default: @code{#f})
- This field specifies the keyboard layout to use in the console. It can be
- either @code{#f}, in which case the default keyboard layout is used (usually
- US English), or a @code{<keyboard-layout>} record. @xref{Keyboard Layout},
- for more information.
- This keyboard layout is in effect as soon as the kernel has booted. For
- instance, it is the keyboard layout in effect when you type a passphrase if
- your root file system is on a @code{luks-device-mapping} mapped device
- (@pxref{Mapped Devices}).
- @quotation Note
- This does @emph{not} specify the keyboard layout used by the bootloader, nor
- that used by the graphical display server. @xref{Bootloader Configuration},
- for information on how to specify the bootloader's keyboard layout. @xref{X
- Window}, for information on how to specify the keyboard layout used by the X
- Window System.
- @end quotation
- @item @code{initrd-modules} (default: @code{%base-initrd-modules})
- @cindex initrd
- @cindex initial RAM disk
- The list of Linux kernel modules that need to be available in the
- initial RAM disk. @xref{Initial RAM Disk}.
- @item @code{initrd} (default: @code{base-initrd})
- A procedure that returns an initial RAM disk for the Linux
- kernel. This field is provided to support low-level customization and
- should rarely be needed for casual use. @xref{Initial RAM Disk}.
- @item @code{firmware} (default: @code{%base-firmware})
- @cindex firmware
- List of firmware packages loadable by the operating system kernel.
- The default includes firmware needed for Atheros- and Broadcom-based
- WiFi devices (Linux-libre modules @code{ath9k} and @code{b43-open},
- respectively). @xref{Hardware Considerations}, for more info on
- supported hardware.
- @item @code{host-name}
- The host name.
- @item @code{hosts-file}
- @cindex hosts file
- A file-like object (@pxref{G-Expressions, file-like objects}) for use as
- @file{/etc/hosts} (@pxref{Host Names,,, libc, The GNU C Library
- Reference Manual}). The default is a file with entries for
- @code{localhost} and @var{host-name}.
- @item @code{mapped-devices} (default: @code{'()})
- A list of mapped devices. @xref{Mapped Devices}.
- @item @code{file-systems}
- A list of file systems. @xref{File Systems}.
- @item @code{swap-devices} (default: @code{'()})
- @cindex swap devices
- A list of swap spaces. @xref{Swap Space}.
- @item @code{users} (default: @code{%base-user-accounts})
- @itemx @code{groups} (default: @code{%base-groups})
- List of user accounts and groups. @xref{User Accounts}.
- If the @code{users} list lacks a user account with UID@tie{}0, a
- ``root'' account with UID@tie{}0 is automatically added.
- @item @code{skeletons} (default: @code{(default-skeletons)})
- A list of target file name/file-like object tuples (@pxref{G-Expressions,
- file-like objects}). These are the skeleton files that will be added to
- the home directory of newly-created user accounts.
- For instance, a valid value may look like this:
- @lisp
- `((".bashrc" ,(plain-file "bashrc" "echo Hello\n"))
- (".guile" ,(plain-file "guile"
- "(use-modules (ice-9 readline))
- (activate-readline)")))
- @end lisp
- @item @code{issue} (default: @code{%default-issue})
- A string denoting the contents of the @file{/etc/issue} file, which is
- displayed when users log in on a text console.
- @item @code{packages} (default: @code{%base-packages})
- A list of packages to be installed in the global profile, which is accessible
- at @file{/run/current-system/profile}. Each element is either a package
- variable or a package/output tuple. Here's a simple example of both:
- @lisp
- (cons* git ; the default "out" output
- (list git "send-email") ; another output of git
- %base-packages) ; the default set
- @end lisp
- The default set includes core utilities and it is good practice to
- install non-core utilities in user profiles (@pxref{Invoking guix
- package}).
- @item @code{timezone}
- A timezone identifying string---e.g., @code{"Europe/Paris"}.
- You can run the @command{tzselect} command to find out which timezone
- string corresponds to your region. Choosing an invalid timezone name
- causes @command{guix system} to fail.
- @item @code{locale} (default: @code{"en_US.utf8"})
- The name of the default locale (@pxref{Locale Names,,, libc, The GNU C
- Library Reference Manual}). @xref{Locales}, for more information.
- @item @code{locale-definitions} (default: @code{%default-locale-definitions})
- The list of locale definitions to be compiled and that may be used at
- run time. @xref{Locales}.
- @item @code{locale-libcs} (default: @code{(list @var{glibc})})
- The list of GNU@tie{}libc packages whose locale data and tools are used
- to build the locale definitions. @xref{Locales}, for compatibility
- considerations that justify this option.
- @item @code{name-service-switch} (default: @code{%default-nss})
- Configuration of the libc name service switch (NSS)---a
- @code{<name-service-switch>} object. @xref{Name Service Switch}, for
- details.
- @item @code{services} (default: @code{%base-services})
- A list of service objects denoting system services. @xref{Services}.
- @cindex essential services
- @item @code{essential-services} (default: ...)
- The list of ``essential services''---i.e., things like instances of
- @code{system-service-type} and @code{host-name-service-type} (@pxref{Service
- Reference}), which are derived from the operating system definition itself.
- As a user you should @emph{never} need to touch this field.
- @item @code{pam-services} (default: @code{(base-pam-services)})
- @cindex PAM
- @cindex pluggable authentication modules
- Linux @dfn{pluggable authentication module} (PAM) services.
- @c FIXME: Add xref to PAM services section.
- @item @code{setuid-programs} (default: @code{%setuid-programs})
- List of @code{<setuid-program>}. @xref{Setuid Programs}, for more
- information.
- @item @code{sudoers-file} (default: @code{%sudoers-specification})
- @cindex sudoers file
- The contents of the @file{/etc/sudoers} file as a file-like object
- (@pxref{G-Expressions, @code{local-file} and @code{plain-file}}).
- This file specifies which users can use the @command{sudo} command, what
- they are allowed to do, and what privileges they may gain. The default
- is that only @code{root} and members of the @code{wheel} group may use
- @code{sudo}.
- @end table
- @deffn {Scheme Syntax} this-operating-system
- When used in the @emph{lexical scope} of an operating system field definition,
- this identifier resolves to the operating system being defined.
- The example below shows how to refer to the operating system being defined in
- the definition of the @code{label} field:
- @lisp
- (use-modules (gnu) (guix))
- (operating-system
- ;; ...
- (label (package-full-name
- (operating-system-kernel this-operating-system))))
- @end lisp
- It is an error to refer to @code{this-operating-system} outside an operating
- system definition.
- @end deffn
- @end deftp
- @node File Systems
- @section File Systems
- The list of file systems to be mounted is specified in the
- @code{file-systems} field of the operating system declaration
- (@pxref{Using the Configuration System}). Each file system is declared
- using the @code{file-system} form, like this:
- @lisp
- (file-system
- (mount-point "/home")
- (device "/dev/sda3")
- (type "ext4"))
- @end lisp
- As usual, some of the fields are mandatory---those shown in the example
- above---while others can be omitted. These are described below.
- @deftp {Data Type} file-system
- Objects of this type represent file systems to be mounted. They
- contain the following members:
- @table @asis
- @item @code{type}
- This is a string specifying the type of the file system---e.g.,
- @code{"ext4"}.
- @item @code{mount-point}
- This designates the place where the file system is to be mounted.
- @item @code{device}
- This names the ``source'' of the file system. It can be one of three
- things: a file system label, a file system UUID, or the name of a
- @file{/dev} node. Labels and UUIDs offer a way to refer to file
- systems without having to hard-code their actual device
- name@footnote{Note that, while it is tempting to use
- @file{/dev/disk/by-uuid} and similar device names to achieve the same
- result, this is not recommended: These special device nodes are created
- by the udev daemon and may be unavailable at the time the device is
- mounted.}.
- @findex file-system-label
- File system labels are created using the @code{file-system-label}
- procedure, UUIDs are created using @code{uuid}, and @file{/dev} node are
- plain strings. Here's an example of a file system referred to by its
- label, as shown by the @command{e2label} command:
- @lisp
- (file-system
- (mount-point "/home")
- (type "ext4")
- (device (file-system-label "my-home")))
- @end lisp
- @findex uuid
- UUIDs are converted from their string representation (as shown by the
- @command{tune2fs -l} command) using the @code{uuid} form@footnote{The
- @code{uuid} form expects 16-byte UUIDs as defined in
- @uref{https://tools.ietf.org/html/rfc4122, RFC@tie{}4122}. This is the
- form of UUID used by the ext2 family of file systems and others, but it
- is different from ``UUIDs'' found in FAT file systems, for instance.},
- like this:
- @lisp
- (file-system
- (mount-point "/home")
- (type "ext4")
- (device (uuid "4dab5feb-d176-45de-b287-9b0a6e4c01cb")))
- @end lisp
- When the source of a file system is a mapped device (@pxref{Mapped
- Devices}), its @code{device} field @emph{must} refer to the mapped
- device name---e.g., @file{"/dev/mapper/root-partition"}.
- This is required so that
- the system knows that mounting the file system depends on having the
- corresponding device mapping established.
- @item @code{flags} (default: @code{'()})
- This is a list of symbols denoting mount flags. Recognized flags
- include @code{read-only}, @code{bind-mount}, @code{no-dev} (disallow
- access to special files), @code{no-suid} (ignore setuid and setgid
- bits), @code{no-atime} (do not update file access times),
- @code{strict-atime} (update file access time), @code{lazy-time} (only
- update time on the in-memory version of the file inode), and
- @code{no-exec} (disallow program execution).
- @xref{Mount-Unmount-Remount,,, libc, The GNU C Library Reference
- Manual}, for more information on these flags.
- @item @code{options} (default: @code{#f})
- This is either @code{#f}, or a string denoting mount options passed to
- the file system driver. @xref{Mount-Unmount-Remount,,, libc, The GNU C
- Library Reference Manual}, for details and run @command{man 8 mount} for
- options for various file systems. Note that the
- @code{file-system-options->alist} and @code{alist->file-system-options}
- procedures from @code{(gnu system file-systems)} can be used to convert
- file system options given as an association list to the string
- representation, and vice-versa.
- @item @code{mount?} (default: @code{#t})
- This value indicates whether to automatically mount the file system when
- the system is brought up. When set to @code{#f}, the file system gets
- an entry in @file{/etc/fstab} (read by the @command{mount} command) but
- is not automatically mounted.
- @item @code{needed-for-boot?} (default: @code{#f})
- This Boolean value indicates whether the file system is needed when
- booting. If that is true, then the file system is mounted when the
- initial RAM disk (initrd) is loaded. This is always the case, for
- instance, for the root file system.
- @item @code{check?} (default: @code{#t})
- This Boolean indicates whether the file system should be checked for
- errors before being mounted. How and when this happens can be further
- adjusted with the following options.
- @item @code{skip-check-if-clean?} (default: @code{#t})
- When true, this Boolean indicates that a file system check triggered
- by @code{check?} may exit early if the file system is marked as
- ``clean'', meaning that it was previously correctly unmounted and
- should not contain errors.
- Setting this to false will always force a full consistency check when
- @code{check?} is true. This may take a very long time and is not
- recommended on healthy systems---in fact, it may reduce reliability!
- Conversely, some primitive file systems like @code{fat} do not keep
- track of clean shutdowns and will perform a full scan regardless of the
- value of this option.
- @item @code{repair} (default: @code{'preen})
- When @code{check?} finds errors, it can (try to) repair them and
- continue booting. This option controls when and how to do so.
- If false, try not to modify the file system at all. Checking certain
- file systems like @code{jfs} may still write to the device to replay
- the journal. No repairs will be attempted.
- If @code{#t}, try to repair any errors found and assume ``yes'' to
- all questions. This will fix the most errors, but may be risky.
- If @code{'preen}, repair only errors that are safe to fix without
- human interaction. What that means is left up to the developers of
- each file system and may be equivalent to ``none'' or ``all''.
- @item @code{create-mount-point?} (default: @code{#f})
- When true, the mount point is created if it does not exist yet.
- @item @code{mount-may-fail?} (default: @code{#f})
- When true, this indicates that mounting this file system can fail but
- that should not be considered an error. This is useful in unusual
- cases; an example of this is @code{efivarfs}, a file system that can
- only be mounted on EFI/UEFI systems.
- @item @code{dependencies} (default: @code{'()})
- This is a list of @code{<file-system>} or @code{<mapped-device>} objects
- representing file systems that must be mounted or mapped devices that
- must be opened before (and unmounted or closed after) this one.
- As an example, consider a hierarchy of mounts: @file{/sys/fs/cgroup} is
- a dependency of @file{/sys/fs/cgroup/cpu} and
- @file{/sys/fs/cgroup/memory}.
- Another example is a file system that depends on a mapped device, for
- example for an encrypted partition (@pxref{Mapped Devices}).
- @end table
- @end deftp
- @deffn {Scheme Procedure} file-system-label @var{str}
- This procedure returns an opaque file system label from @var{str}, a
- string:
- @lisp
- (file-system-label "home")
- @result{} #<file-system-label "home">
- @end lisp
- File system labels are used to refer to file systems by label rather
- than by device name. See above for examples.
- @end deffn
- The @code{(gnu system file-systems)} exports the following useful
- variables.
- @defvr {Scheme Variable} %base-file-systems
- These are essential file systems that are required on normal systems,
- such as @code{%pseudo-terminal-file-system} and @code{%immutable-store} (see
- below). Operating system declarations should always contain at least
- these.
- @end defvr
- @defvr {Scheme Variable} %pseudo-terminal-file-system
- This is the file system to be mounted as @file{/dev/pts}. It supports
- @dfn{pseudo-terminals} created @i{via} @code{openpty} and similar
- functions (@pxref{Pseudo-Terminals,,, libc, The GNU C Library Reference
- Manual}). Pseudo-terminals are used by terminal emulators such as
- @command{xterm}.
- @end defvr
- @defvr {Scheme Variable} %shared-memory-file-system
- This file system is mounted as @file{/dev/shm} and is used to support
- memory sharing across processes (@pxref{Memory-mapped I/O,
- @code{shm_open},, libc, The GNU C Library Reference Manual}).
- @end defvr
- @defvr {Scheme Variable} %immutable-store
- This file system performs a read-only ``bind mount'' of
- @file{/gnu/store}, making it read-only for all the users including
- @code{root}. This prevents against accidental modification by software
- running as @code{root} or by system administrators.
- The daemon itself is still able to write to the store: it remounts it
- read-write in its own ``name space.''
- @end defvr
- @defvr {Scheme Variable} %binary-format-file-system
- The @code{binfmt_misc} file system, which allows handling of arbitrary
- executable file types to be delegated to user space. This requires the
- @code{binfmt.ko} kernel module to be loaded.
- @end defvr
- @defvr {Scheme Variable} %fuse-control-file-system
- The @code{fusectl} file system, which allows unprivileged users to mount
- and unmount user-space FUSE file systems. This requires the
- @code{fuse.ko} kernel module to be loaded.
- @end defvr
- The @code{(gnu system uuid)} module provides tools to deal with file
- system ``unique identifiers'' (UUIDs).
- @deffn {Scheme Procedure} uuid @var{str} [@var{type}]
- Return an opaque UUID (unique identifier) object of the given @var{type}
- (a symbol) by parsing @var{str} (a string):
- @lisp
- (uuid "4dab5feb-d176-45de-b287-9b0a6e4c01cb")
- @result{} #<<uuid> type: dce bv: @dots{}>
- (uuid "1234-ABCD" 'fat)
- @result{} #<<uuid> type: fat bv: @dots{}>
- @end lisp
- @var{type} may be one of @code{dce}, @code{iso9660}, @code{fat},
- @code{ntfs}, or one of the commonly found synonyms for these.
- UUIDs are another way to unambiguously refer to file systems in
- operating system configuration. See the examples above.
- @end deffn
- @node Btrfs file system
- @subsection Btrfs file system
- The Btrfs has special features, such as subvolumes, that merit being
- explained in more details. The following section attempts to cover
- basic as well as complex uses of a Btrfs file system with the Guix
- System.
- In its simplest usage, a Btrfs file system can be described, for
- example, by:
- @lisp
- (file-system
- (mount-point "/home")
- (type "btrfs")
- (device (file-system-label "my-home")))
- @end lisp
- The example below is more complex, as it makes use of a Btrfs
- subvolume, named @code{rootfs}. The parent Btrfs file system is labeled
- @code{my-btrfs-pool}, and is located on an encrypted device (hence the
- dependency on @code{mapped-devices}):
- @lisp
- (file-system
- (device (file-system-label "my-btrfs-pool"))
- (mount-point "/")
- (type "btrfs")
- (options "subvol=rootfs")
- (dependencies mapped-devices))
- @end lisp
- Some bootloaders, for example GRUB, only mount a Btrfs partition at its
- top level during the early boot, and rely on their configuration to
- refer to the correct subvolume path within that top level. The
- bootloaders operating in this way typically produce their configuration
- on a running system where the Btrfs partitions are already mounted and
- where the subvolume information is readily available. As an example,
- @command{grub-mkconfig}, the configuration generator command shipped
- with GRUB, reads @file{/proc/self/mountinfo} to determine the top-level
- path of a subvolume.
- The Guix System produces a bootloader configuration using the operating
- system configuration as its sole input; it is therefore necessary to
- extract the subvolume name on which @file{/gnu/store} lives (if any)
- from that operating system configuration. To better illustrate,
- consider a subvolume named 'rootfs' which contains the root file system
- data. In such situation, the GRUB bootloader would only see the top
- level of the root Btrfs partition, e.g.:
- @example
- / (top level)
- ├── rootfs (subvolume directory)
- ├── gnu (normal directory)
- ├── store (normal directory)
- [...]
- @end example
- Thus, the subvolume name must be prepended to the @file{/gnu/store} path
- of the kernel, initrd binaries and any other files referred to in the
- GRUB configuration that must be found during the early boot.
- The next example shows a nested hierarchy of subvolumes and
- directories:
- @example
- / (top level)
- ├── rootfs (subvolume)
- ├── gnu (normal directory)
- ├── store (subvolume)
- [...]
- @end example
- This scenario would work without mounting the 'store' subvolume.
- Mounting 'rootfs' is sufficient, since the subvolume name matches its
- intended mount point in the file system hierarchy. Alternatively, the
- 'store' subvolume could be referred to by setting the @code{subvol}
- option to either @code{/rootfs/gnu/store} or @code{rootfs/gnu/store}.
- Finally, a more contrived example of nested subvolumes:
- @example
- / (top level)
- ├── root-snapshots (subvolume)
- ├── root-current (subvolume)
- ├── guix-store (subvolume)
- [...]
- @end example
- Here, the 'guix-store' subvolume doesn't match its intended mount point,
- so it is necessary to mount it. The subvolume must be fully specified,
- by passing its file name to the @code{subvol} option. To illustrate,
- the 'guix-store' subvolume could be mounted on @file{/gnu/store} by using
- a file system declaration such as:
- @lisp
- (file-system
- (device (file-system-label "btrfs-pool-1"))
- (mount-point "/gnu/store")
- (type "btrfs")
- (options "subvol=root-snapshots/root-current/guix-store,\
- compress-force=zstd,space_cache=v2"))
- @end lisp
- @node Mapped Devices
- @section Mapped Devices
- @cindex device mapping
- @cindex mapped devices
- The Linux kernel has a notion of @dfn{device mapping}: a block device,
- such as a hard disk partition, can be @dfn{mapped} into another device,
- usually in @code{/dev/mapper/},
- with additional processing over the data that flows through
- it@footnote{Note that the GNU@tie{}Hurd makes no difference between the
- concept of a ``mapped device'' and that of a file system: both boil down
- to @emph{translating} input/output operations made on a file to
- operations on its backing store. Thus, the Hurd implements mapped
- devices, like file systems, using the generic @dfn{translator} mechanism
- (@pxref{Translators,,, hurd, The GNU Hurd Reference Manual}).}. A
- typical example is encryption device mapping: all writes to the mapped
- device are encrypted, and all reads are deciphered, transparently.
- Guix extends this notion by considering any device or set of devices that
- are @dfn{transformed} in some way to create a new device; for instance,
- RAID devices are obtained by @dfn{assembling} several other devices, such
- as hard disks or partitions, into a new one that behaves as one partition.
- Mapped devices are declared using the @code{mapped-device} form,
- defined as follows; for examples, see below.
- @deftp {Data Type} mapped-device
- Objects of this type represent device mappings that will be made when
- the system boots up.
- @table @code
- @item source
- This is either a string specifying the name of the block device to be mapped,
- such as @code{"/dev/sda3"}, or a list of such strings when several devices
- need to be assembled for creating a new one. In case of LVM this is a
- string specifying name of the volume group to be mapped.
- @item target
- This string specifies the name of the resulting mapped device. For
- kernel mappers such as encrypted devices of type @code{luks-device-mapping},
- specifying @code{"my-partition"} leads to the creation of
- the @code{"/dev/mapper/my-partition"} device.
- For RAID devices of type @code{raid-device-mapping}, the full device name
- such as @code{"/dev/md0"} needs to be given.
- LVM logical volumes of type @code{lvm-device-mapping} need to
- be specified as @code{"VGNAME-LVNAME"}.
- @item targets
- This list of strings specifies names of the resulting mapped devices in case
- there are several. The format is identical to @var{target}.
- @item type
- This must be a @code{mapped-device-kind} object, which specifies how
- @var{source} is mapped to @var{target}.
- @end table
- @end deftp
- @defvr {Scheme Variable} luks-device-mapping
- This defines LUKS block device encryption using the @command{cryptsetup}
- command from the package with the same name. It relies on the
- @code{dm-crypt} Linux kernel module.
- @end defvr
- @defvr {Scheme Variable} raid-device-mapping
- This defines a RAID device, which is assembled using the @code{mdadm}
- command from the package with the same name. It requires a Linux kernel
- module for the appropriate RAID level to be loaded, such as @code{raid456}
- for RAID-4, RAID-5 or RAID-6, or @code{raid10} for RAID-10.
- @end defvr
- @cindex LVM, logical volume manager
- @defvr {Scheme Variable} lvm-device-mapping
- This defines one or more logical volumes for the Linux
- @uref{https://www.sourceware.org/lvm2/, Logical Volume Manager (LVM)}.
- The volume group is activated by the @command{vgchange} command from the
- @code{lvm2} package.
- @end defvr
- @cindex disk encryption
- @cindex LUKS
- The following example specifies a mapping from @file{/dev/sda3} to
- @file{/dev/mapper/home} using LUKS---the
- @url{https://gitlab.com/cryptsetup/cryptsetup,Linux Unified Key Setup}, a
- standard mechanism for disk encryption.
- The @file{/dev/mapper/home}
- device can then be used as the @code{device} of a @code{file-system}
- declaration (@pxref{File Systems}).
- @lisp
- (mapped-device
- (source "/dev/sda3")
- (target "home")
- (type luks-device-mapping))
- @end lisp
- Alternatively, to become independent of device numbering, one may obtain
- the LUKS UUID (@dfn{unique identifier}) of the source device by a
- command like:
- @example
- cryptsetup luksUUID /dev/sda3
- @end example
- and use it as follows:
- @lisp
- (mapped-device
- (source (uuid "cb67fc72-0d54-4c88-9d4b-b225f30b0f44"))
- (target "home")
- (type luks-device-mapping))
- @end lisp
- @cindex swap encryption
- It is also desirable to encrypt swap space, since swap space may contain
- sensitive data. One way to accomplish that is to use a swap file in a
- file system on a device mapped via LUKS encryption. In this way, the
- swap file is encrypted because the entire device is encrypted.
- @xref{Swap Space}, or @xref{Preparing for Installation,,Disk
- Partitioning}, for an example.
- A RAID device formed of the partitions @file{/dev/sda1} and @file{/dev/sdb1}
- may be declared as follows:
- @lisp
- (mapped-device
- (source (list "/dev/sda1" "/dev/sdb1"))
- (target "/dev/md0")
- (type raid-device-mapping))
- @end lisp
- The @file{/dev/md0} device can then be used as the @code{device} of a
- @code{file-system} declaration (@pxref{File Systems}).
- Note that the RAID level need not be given; it is chosen during the
- initial creation and formatting of the RAID device and is determined
- automatically later.
- LVM logical volumes ``alpha'' and ``beta'' from volume group ``vg0'' can
- be declared as follows:
- @lisp
- (mapped-device
- (source "vg0")
- (targets (list "vg0-alpha" "vg0-beta"))
- (type lvm-device-mapping))
- @end lisp
- Devices @file{/dev/mapper/vg0-alpha} and @file{/dev/mapper/vg0-beta} can
- then be used as the @code{device} of a @code{file-system} declaration
- (@pxref{File Systems}).
- @node Swap Space
- @section Swap Space
- @cindex swap space
- Swap space, as it is commonly called, is a disk area specifically
- designated for paging: the process in charge of memory management
- (the Linux kernel or Hurd's default pager) can decide that some memory
- pages stored in RAM which belong to a running program but are unused
- should be stored on disk instead. It unloads those from the RAM,
- freeing up precious fast memory, and writes them to the swap space. If
- the program tries to access that very page, the memory management
- process loads it back into memory for the program to use.
- A common misconception about swap is that it is only useful when small
- amounts of RAM are available to the system. However, it should be noted
- that kernels often use all available RAM for disk access caching to make
- I/O faster, and thus paging out unused portions of program memory will
- expand the RAM available for such caching.
- For a more detailed description of how memory is managed from the
- viewpoint of a monolithic kernel, @xref{Memory
- Concepts,,, libc, The GNU C Library Reference Manual}.
- The Linux kernel has support for swap partitions and swap files: the
- former uses a whole disk partition for paging, whereas the second uses a
- file on a file system for that (the file system driver needs to support
- it). On a comparable setup, both have the same performance, so one
- should consider ease of use when deciding between them. Partitions are
- ``simpler'' and do not need file system support, but need to be
- allocated at disk formatting time (logical volumes notwithstanding),
- whereas files can be allocated and deallocated at any time.
- Note that swap space is not zeroed on shutdown, so sensitive data (such
- as passwords) may linger on it if it was paged out. As such, you should
- consider having your swap reside on an encrypted device (@pxref{Mapped
- Devices}).
- @deftp {Data Type} swap-space
- Objects of this type represent swap spaces. They contain the following
- members:
- @table @asis
- @item @code{target}
- The device or file to use, either a UUID, a @code{file-system-label} or
- a string, as in the definition of a @code{file-system} (@pxref{File
- Systems}).
- @item @code{dependencies} (default: @code{'()})
- A list of @code{file-system} or @code{mapped-device} objects, upon which
- the availability of the space depends. Note that just like for
- @code{file-system} objects, dependencies which are needed for boot and
- mounted in early userspace are not managed by the Shepherd, and so
- automatically filtered out for you.
- @item @code{priority} (default: @code{#f})
- Only supported by the Linux kernel. Either @code{#f} to disable swap
- priority, or an integer between 0 and 32767. The kernel will first use
- swap spaces of higher priority when paging, and use same priority spaces
- on a round-robin basis. The kernel will use swap spaces without a set
- priority after prioritized spaces, and in the order that they appeared in
- (not round-robin).
- @item @code{discard?} (default: @code{#f})
- Only supported by the Linux kernel. When true, the kernel will notify
- the disk controller of discarded pages, for example with the TRIM
- operation on Solid State Drives.
- @end table
- @end deftp
- Here are some examples:
- @lisp
- (swap-space (target (uuid "4dab5feb-d176-45de-b287-9b0a6e4c01cb")))
- @end lisp
- Use the swap partition with the given UUID@. You can learn the UUID of a
- Linux swap partition by running @command{swaplabel @var{device}}, where
- @var{device} is the @file{/dev} file name of that partition.
- @lisp
- (swap-space
- (target (file-system-label "swap"))
- (dependencies mapped-devices))
- @end lisp
- Use the partition with label @code{swap}, which can be found after all
- the @var{mapped-devices} mapped devices have been opened. Again, the
- @command{swaplabel} command allows you to view and change the label of a
- Linux swap partition.
- Here's a more involved example with the corresponding @code{file-systems} part
- of an @code{operating-system} declaration.
- @lisp
- (file-systems
- (list (file-system
- (device (file-system-label "root"))
- (mount-point "/")
- (type "ext4"))
- (file-system
- (device (file-system-label "btrfs"))
- (mount-point "/btrfs")
- (type "btrfs"))))
- (swap-devices
- (list
- (swap-space
- (target "/btrfs/swapfile")
- (dependencies (filter (file-system-mount-point-predicate "/btrfs")
- file-systems)))))
- @end lisp
- Use the file @file{/btrfs/swapfile} as swap space, which depends on the
- file system mounted at @file{/btrfs}. Note how we use Guile's filter to
- select the file system in an elegant fashion!
- @node User Accounts
- @section User Accounts
- @cindex users
- @cindex accounts
- @cindex user accounts
- User accounts and groups are entirely managed through the
- @code{operating-system} declaration. They are specified with the
- @code{user-account} and @code{user-group} forms:
- @lisp
- (user-account
- (name "alice")
- (group "users")
- (supplementary-groups '("wheel" ;allow use of sudo, etc.
- "audio" ;sound card
- "video" ;video devices such as webcams
- "cdrom")) ;the good ol' CD-ROM
- (comment "Bob's sister"))
- @end lisp
- Here's a user account that uses a different shell and a custom home
- directory (the default would be @file{"/home/bob"}):
- @lisp
- (user-account
- (name "bob")
- (group "users")
- (comment "Alice's bro")
- (shell (file-append zsh "/bin/zsh"))
- (home-directory "/home/robert"))
- @end lisp
- When booting or upon completion of @command{guix system reconfigure},
- the system ensures that only the user accounts and groups specified in
- the @code{operating-system} declaration exist, and with the specified
- properties. Thus, account or group creations or modifications made by
- directly invoking commands such as @command{useradd} are lost upon
- reconfiguration or reboot. This ensures that the system remains exactly
- as declared.
- @deftp {Data Type} user-account
- Objects of this type represent user accounts. The following members may
- be specified:
- @table @asis
- @item @code{name}
- The name of the user account.
- @item @code{group}
- @cindex groups
- This is the name (a string) or identifier (a number) of the user group
- this account belongs to.
- @item @code{supplementary-groups} (default: @code{'()})
- Optionally, this can be defined as a list of group names that this
- account belongs to.
- @item @code{uid} (default: @code{#f})
- This is the user ID for this account (a number), or @code{#f}. In the
- latter case, a number is automatically chosen by the system when the
- account is created.
- @item @code{comment} (default: @code{""})
- A comment about the account, such as the account owner's full name.
- Note that, for non-system accounts, users are free to change their real
- name as it appears in @file{/etc/passwd} using the @command{chfn}
- command. When they do, their choice prevails over the system
- administrator's choice; reconfiguring does @emph{not} change their name.
- @item @code{home-directory}
- This is the name of the home directory for the account.
- @item @code{create-home-directory?} (default: @code{#t})
- Indicates whether the home directory of this account should be created
- if it does not exist yet.
- @item @code{shell} (default: Bash)
- This is a G-expression denoting the file name of a program to be used as
- the shell (@pxref{G-Expressions}). For example, you would refer to the
- Bash executable like this:
- @lisp
- (file-append bash "/bin/bash")
- @end lisp
- @noindent
- ... and to the Zsh executable like that:
- @lisp
- (file-append zsh "/bin/zsh")
- @end lisp
- @item @code{system?} (default: @code{#f})
- This Boolean value indicates whether the account is a ``system''
- account. System accounts are sometimes treated specially; for instance,
- graphical login managers do not list them.
- @anchor{user-account-password}
- @cindex password, for user accounts
- @item @code{password} (default: @code{#f})
- You would normally leave this field to @code{#f}, initialize user
- passwords as @code{root} with the @command{passwd} command, and then let
- users change it with @command{passwd}. Passwords set with
- @command{passwd} are of course preserved across reboot and
- reconfiguration.
- If you @emph{do} want to set an initial password for an account, then
- this field must contain the encrypted password, as a string. You can use the
- @code{crypt} procedure for this purpose:
- @lisp
- (user-account
- (name "charlie")
- (group "users")
- ;; Specify a SHA-512-hashed initial password.
- (password (crypt "InitialPassword!" "$6$abc")))
- @end lisp
- @quotation Note
- The hash of this initial password will be available in a file in
- @file{/gnu/store}, readable by all the users, so this method must be used with
- care.
- @end quotation
- @xref{Passphrase Storage,,, libc, The GNU C Library Reference Manual}, for
- more information on password encryption, and @ref{Encryption,,, guile, GNU
- Guile Reference Manual}, for information on Guile's @code{crypt} procedure.
- @end table
- @end deftp
- @cindex groups
- User group declarations are even simpler:
- @lisp
- (user-group (name "students"))
- @end lisp
- @deftp {Data Type} user-group
- This type is for, well, user groups. There are just a few fields:
- @table @asis
- @item @code{name}
- The name of the group.
- @item @code{id} (default: @code{#f})
- The group identifier (a number). If @code{#f}, a new number is
- automatically allocated when the group is created.
- @item @code{system?} (default: @code{#f})
- This Boolean value indicates whether the group is a ``system'' group.
- System groups have low numerical IDs.
- @item @code{password} (default: @code{#f})
- What, user groups can have a password? Well, apparently yes. Unless
- @code{#f}, this field specifies the password of the group.
- @end table
- @end deftp
- For convenience, a variable lists all the basic user groups one may
- expect:
- @defvr {Scheme Variable} %base-groups
- This is the list of basic user groups that users and/or packages expect
- to be present on the system. This includes groups such as ``root'',
- ``wheel'', and ``users'', as well as groups used to control access to
- specific devices such as ``audio'', ``disk'', and ``cdrom''.
- @end defvr
- @defvr {Scheme Variable} %base-user-accounts
- This is the list of basic system accounts that programs may expect to
- find on a GNU/Linux system, such as the ``nobody'' account.
- Note that the ``root'' account is not included here. It is a
- special-case and is automatically added whether or not it is specified.
- @end defvr
- @node Keyboard Layout
- @section Keyboard Layout
- @cindex keyboard layout
- @cindex keymap
- To specify what each key of your keyboard does, you need to tell the operating
- system what @dfn{keyboard layout} you want to use. The default, when nothing
- is specified, is the US English QWERTY layout for 105-key PC keyboards.
- However, German speakers will usually prefer the German QWERTZ layout, French
- speakers will want the AZERTY layout, and so on; hackers might prefer Dvorak
- or bépo, and they might even want to further customize the effect of some of
- the keys. This section explains how to get that done.
- @cindex keyboard layout, definition
- There are three components that will want to know about your keyboard layout:
- @itemize
- @item
- The @emph{bootloader} may want to know what keyboard layout you want to use
- (@pxref{Bootloader Configuration, @code{keyboard-layout}}). This is useful if
- you want, for instance, to make sure that you can type the passphrase of your
- encrypted root partition using the right layout.
- @item
- The @emph{operating system kernel}, Linux, will need that so that the console
- is properly configured (@pxref{operating-system Reference,
- @code{keyboard-layout}}).
- @item
- The @emph{graphical display server}, usually Xorg, also has its own idea of
- the keyboard layout (@pxref{X Window, @code{keyboard-layout}}).
- @end itemize
- Guix allows you to configure all three separately but, fortunately, it allows
- you to share the same keyboard layout for all three components.
- @cindex XKB, keyboard layouts
- Keyboard layouts are represented by records created by the
- @code{keyboard-layout} procedure of @code{(gnu system keyboard)}. Following
- the X Keyboard extension (XKB), each layout has four attributes: a name (often
- a language code such as ``fi'' for Finnish or ``jp'' for Japanese), an
- optional variant name, an optional keyboard model name, and a possibly empty
- list of additional options. In most cases the layout name is all you care
- about.
- @deffn {Scheme Procedure} keyboard-layout @var{name} [@var{variant}] @
- [#:model] [#:options '()]
- Return a new keyboard layout with the given @var{name} and @var{variant}.
- @var{name} must be a string such as @code{"fr"}; @var{variant} must be a
- string such as @code{"bepo"} or @code{"nodeadkeys"}. See the
- @code{xkeyboard-config} package for valid options.
- @end deffn
- Here are a few examples:
- @lisp
- ;; The German QWERTZ layout. Here we assume a standard
- ;; "pc105" keyboard model.
- (keyboard-layout "de")
- ;; The bépo variant of the French layout.
- (keyboard-layout "fr" "bepo")
- ;; The Catalan layout.
- (keyboard-layout "es" "cat")
- ;; Arabic layout with "Alt-Shift" to switch to US layout.
- (keyboard-layout "ar,us" #:options '("grp:alt_shift_toggle"))
- ;; The Latin American Spanish layout. In addition, the
- ;; "Caps Lock" key is used as an additional "Ctrl" key,
- ;; and the "Menu" key is used as a "Compose" key to enter
- ;; accented letters.
- (keyboard-layout "latam"
- #:options '("ctrl:nocaps" "compose:menu"))
- ;; The Russian layout for a ThinkPad keyboard.
- (keyboard-layout "ru" #:model "thinkpad")
- ;; The "US international" layout, which is the US layout plus
- ;; dead keys to enter accented characters. This is for an
- ;; Apple MacBook keyboard.
- (keyboard-layout "us" "intl" #:model "macbook78")
- @end lisp
- See the @file{share/X11/xkb} directory of the @code{xkeyboard-config} package
- for a complete list of supported layouts, variants, and models.
- @cindex keyboard layout, configuration
- Let's say you want your system to use the Turkish keyboard layout throughout
- your system---bootloader, console, and Xorg. Here's what your system
- configuration would look like:
- @findex set-xorg-configuration
- @lisp
- ;; Using the Turkish layout for the bootloader, the console,
- ;; and for Xorg.
- (operating-system
- ;; ...
- (keyboard-layout (keyboard-layout "tr")) ;for the console
- (bootloader (bootloader-configuration
- (bootloader grub-efi-bootloader)
- (targets '("/boot/efi"))
- (keyboard-layout keyboard-layout))) ;for GRUB
- (services (cons (set-xorg-configuration
- (xorg-configuration ;for Xorg
- (keyboard-layout keyboard-layout)))
- %desktop-services)))
- @end lisp
- In the example above, for GRUB and for Xorg, we just refer to the
- @code{keyboard-layout} field defined above, but we could just as well refer to
- a different layout. The @code{set-xorg-configuration} procedure communicates
- the desired Xorg configuration to the graphical log-in manager, by default
- GDM.
- We've discussed how to specify the @emph{default} keyboard layout of your
- system when it starts, but you can also adjust it at run time:
- @itemize
- @item
- If you're using GNOME, its settings panel has a ``Region & Language'' entry
- where you can select one or more keyboard layouts.
- @item
- Under Xorg, the @command{setxkbmap} command (from the same-named package)
- allows you to change the current layout. For example, this is how you would
- change the layout to US Dvorak:
- @example
- setxkbmap us dvorak
- @end example
- @item
- The @code{loadkeys} command changes the keyboard layout in effect in the Linux
- console. However, note that @code{loadkeys} does @emph{not} use the XKB
- keyboard layout categorization described above. The command below loads the
- French bépo layout:
- @example
- loadkeys fr-bepo
- @end example
- @end itemize
- @node Locales
- @section Locales
- @cindex locale
- A @dfn{locale} defines cultural conventions for a particular language
- and region of the world (@pxref{Locales,,, libc, The GNU C Library
- Reference Manual}). Each locale has a name that typically has the form
- @code{@var{language}_@var{territory}.@var{codeset}}---e.g.,
- @code{fr_LU.utf8} designates the locale for the French language, with
- cultural conventions from Luxembourg, and using the UTF-8 encoding.
- @cindex locale definition
- Usually, you will want to specify the default locale for the machine
- using the @code{locale} field of the @code{operating-system} declaration
- (@pxref{operating-system Reference, @code{locale}}).
- The selected locale is automatically added to the @dfn{locale
- definitions} known to the system if needed, with its codeset inferred
- from its name---e.g., @code{bo_CN.utf8} will be assumed to use the
- @code{UTF-8} codeset. Additional locale definitions can be specified in
- the @code{locale-definitions} slot of @code{operating-system}---this is
- useful, for instance, if the codeset could not be inferred from the
- locale name. The default set of locale definitions includes some widely
- used locales, but not all the available locales, in order to save space.
- For instance, to add the North Frisian locale for Germany, the value of
- that field may be:
- @lisp
- (cons (locale-definition
- (name "fy_DE.utf8") (source "fy_DE"))
- %default-locale-definitions)
- @end lisp
- Likewise, to save space, one might want @code{locale-definitions} to
- list only the locales that are actually used, as in:
- @lisp
- (list (locale-definition
- (name "ja_JP.eucjp") (source "ja_JP")
- (charset "EUC-JP")))
- @end lisp
- @vindex LOCPATH
- The compiled locale definitions are available at
- @file{/run/current-system/locale/X.Y}, where @code{X.Y} is the libc
- version, which is the default location where the GNU@tie{}libc provided
- by Guix looks for locale data. This can be overridden using the
- @env{LOCPATH} environment variable (@pxref{locales-and-locpath,
- @env{LOCPATH} and locale packages}).
- The @code{locale-definition} form is provided by the @code{(gnu system
- locale)} module. Details are given below.
- @deftp {Data Type} locale-definition
- This is the data type of a locale definition.
- @table @asis
- @item @code{name}
- The name of the locale. @xref{Locale Names,,, libc, The GNU C Library
- Reference Manual}, for more information on locale names.
- @item @code{source}
- The name of the source for that locale. This is typically the
- @code{@var{language}_@var{territory}} part of the locale name.
- @item @code{charset} (default: @code{"UTF-8"})
- The ``character set'' or ``code set'' for that locale,
- @uref{https://www.iana.org/assignments/character-sets, as defined by
- IANA}.
- @end table
- @end deftp
- @defvr {Scheme Variable} %default-locale-definitions
- A list of commonly used UTF-8 locales, used as the default
- value of the @code{locale-definitions} field of @code{operating-system}
- declarations.
- @cindex locale name
- @cindex normalized codeset in locale names
- These locale definitions use the @dfn{normalized codeset} for the part
- that follows the dot in the name (@pxref{Using gettextized software,
- normalized codeset,, libc, The GNU C Library Reference Manual}). So for
- instance it has @code{uk_UA.utf8} but @emph{not}, say,
- @code{uk_UA.UTF-8}.
- @end defvr
- @subsection Locale Data Compatibility Considerations
- @cindex incompatibility, of locale data
- @code{operating-system} declarations provide a @code{locale-libcs} field
- to specify the GNU@tie{}libc packages that are used to compile locale
- declarations (@pxref{operating-system Reference}). ``Why would I
- care?'', you may ask. Well, it turns out that the binary format of
- locale data is occasionally incompatible from one libc version to
- another.
- @c See <https://sourceware.org/ml/libc-alpha/2015-09/msg00575.html>
- @c and <https://lists.gnu.org/archive/html/guix-devel/2015-08/msg00737.html>.
- For instance, a program linked against libc version 2.21 is unable to
- read locale data produced with libc 2.22; worse, that program
- @emph{aborts} instead of simply ignoring the incompatible locale
- data@footnote{Versions 2.23 and later of GNU@tie{}libc will simply skip
- the incompatible locale data, which is already an improvement.}.
- Similarly, a program linked against libc 2.22 can read most, but not
- all, of the locale data from libc 2.21 (specifically, @env{LC_COLLATE}
- data is incompatible); thus calls to @code{setlocale} may fail, but
- programs will not abort.
- The ``problem'' with Guix is that users have a lot of freedom: They can
- choose whether and when to upgrade software in their profiles, and might
- be using a libc version different from the one the system administrator
- used to build the system-wide locale data.
- Fortunately, unprivileged users can also install their own locale data
- and define @env{GUIX_LOCPATH} accordingly (@pxref{locales-and-locpath,
- @env{GUIX_LOCPATH} and locale packages}).
- Still, it is best if the system-wide locale data at
- @file{/run/current-system/locale} is built for all the libc versions
- actually in use on the system, so that all the programs can access
- it---this is especially crucial on a multi-user system. To do that, the
- administrator can specify several libc packages in the
- @code{locale-libcs} field of @code{operating-system}:
- @lisp
- (use-package-modules base)
- (operating-system
- ;; @dots{}
- (locale-libcs (list glibc-2.21 (canonical-package glibc))))
- @end lisp
- This example would lead to a system containing locale definitions for
- both libc 2.21 and the current version of libc in
- @file{/run/current-system/locale}.
- @node Services
- @section Services
- @cindex system services
- An important part of preparing an @code{operating-system} declaration is
- listing @dfn{system services} and their configuration (@pxref{Using the
- Configuration System}). System services are typically daemons launched
- when the system boots, or other actions needed at that time---e.g.,
- configuring network access.
- Guix has a broad definition of ``service'' (@pxref{Service
- Composition}), but many services are managed by the GNU@tie{}Shepherd
- (@pxref{Shepherd Services}). On a running system, the @command{herd}
- command allows you to list the available services, show their status,
- start and stop them, or do other specific operations (@pxref{Jump
- Start,,, shepherd, The GNU Shepherd Manual}). For example:
- @example
- # herd status
- @end example
- The above command, run as @code{root}, lists the currently defined
- services. The @command{herd doc} command shows a synopsis of the given
- service and its associated actions:
- @example
- # herd doc nscd
- Run libc's name service cache daemon (nscd).
- # herd doc nscd action invalidate
- invalidate: Invalidate the given cache--e.g., 'hosts' for host name lookups.
- @end example
- The @command{start}, @command{stop}, and @command{restart} sub-commands
- have the effect you would expect. For instance, the commands below stop
- the nscd service and restart the Xorg display server:
- @example
- # herd stop nscd
- Service nscd has been stopped.
- # herd restart xorg-server
- Service xorg-server has been stopped.
- Service xorg-server has been started.
- @end example
- The following sections document the available services, starting with
- the core services, that may be used in an @code{operating-system}
- declaration.
- @menu
- * Base Services:: Essential system services.
- * Scheduled Job Execution:: The mcron service.
- * Log Rotation:: The rottlog service.
- * Networking Setup:: Setting up network interfaces.
- * Networking Services:: Firewall, SSH daemon, etc.
- * Unattended Upgrades:: Automated system upgrades.
- * X Window:: Graphical display.
- * Printing Services:: Local and remote printer support.
- * Desktop Services:: D-Bus and desktop services.
- * Sound Services:: ALSA and Pulseaudio services.
- * Database Services:: SQL databases, key-value stores, etc.
- * Mail Services:: IMAP, POP3, SMTP, and all that.
- * Messaging Services:: Messaging services.
- * Telephony Services:: Telephony services.
- * File-Sharing Services:: File-sharing services.
- * Monitoring Services:: Monitoring services.
- * Kerberos Services:: Kerberos services.
- * LDAP Services:: LDAP services.
- * Web Services:: Web servers.
- * Certificate Services:: TLS certificates via Let's Encrypt.
- * DNS Services:: DNS daemons.
- * VPN Services:: VPN daemons.
- * Network File System:: NFS related services.
- * Continuous Integration:: Cuirass and Laminar services.
- * Power Management Services:: Extending battery life.
- * Audio Services:: The MPD.
- * Virtualization Services:: Virtualization services.
- * Version Control Services:: Providing remote access to Git repositories.
- * Game Services:: Game servers.
- * PAM Mount Service:: Service to mount volumes when logging in.
- * Guix Services:: Services relating specifically to Guix.
- * Linux Services:: Services tied to the Linux kernel.
- * Hurd Services:: Services specific for a Hurd System.
- * Miscellaneous Services:: Other services.
- @end menu
- @node Base Services
- @subsection Base Services
- The @code{(gnu services base)} module provides definitions for the basic
- services that one expects from the system. The services exported by
- this module are listed below.
- @defvr {Scheme Variable} %base-services
- This variable contains a list of basic services (@pxref{Service Types
- and Services}, for more information on service objects) one would
- expect from the system: a login service (mingetty) on each tty, syslogd,
- the libc name service cache daemon (nscd), the udev device manager, and
- more.
- This is the default value of the @code{services} field of
- @code{operating-system} declarations. Usually, when customizing a
- system, you will want to append services to @code{%base-services}, like
- this:
- @lisp
- (append (list (service avahi-service-type)
- (service openssh-service-type))
- %base-services)
- @end lisp
- @end defvr
- @defvr {Scheme Variable} special-files-service-type
- This is the service that sets up ``special files'' such as
- @file{/bin/sh}; an instance of it is part of @code{%base-services}.
- The value associated with @code{special-files-service-type} services
- must be a list of tuples where the first element is the ``special file''
- and the second element is its target. By default it is:
- @cindex @file{/bin/sh}
- @cindex @file{sh}, in @file{/bin}
- @lisp
- `(("/bin/sh" ,(file-append bash "/bin/sh")))
- @end lisp
- @cindex @file{/usr/bin/env}
- @cindex @file{env}, in @file{/usr/bin}
- If you want to add, say, @code{/usr/bin/env} to your system, you can
- change it to:
- @lisp
- `(("/bin/sh" ,(file-append bash "/bin/sh"))
- ("/usr/bin/env" ,(file-append coreutils "/bin/env")))
- @end lisp
- Since this is part of @code{%base-services}, you can use
- @code{modify-services} to customize the set of special files
- (@pxref{Service Reference, @code{modify-services}}). But the simple way
- to add a special file is @i{via} the @code{extra-special-file} procedure
- (see below).
- @end defvr
- @deffn {Scheme Procedure} extra-special-file @var{file} @var{target}
- Use @var{target} as the ``special file'' @var{file}.
- For example, adding the following lines to the @code{services} field of
- your operating system declaration leads to a @file{/usr/bin/env}
- symlink:
- @lisp
- (extra-special-file "/usr/bin/env"
- (file-append coreutils "/bin/env"))
- @end lisp
- @end deffn
- @deffn {Scheme Procedure} host-name-service @var{name}
- Return a service that sets the host name to @var{name}.
- @end deffn
- @defvr {Scheme Variable} console-font-service-type
- Install the given fonts on the specified ttys (fonts are per
- virtual console on the kernel Linux). The value of this service is a list of
- tty/font pairs. The font can be the name of a font provided by the @code{kbd}
- package or any valid argument to @command{setfont}, as in this example:
- @lisp
- `(("tty1" . "LatGrkCyr-8x16")
- ("tty2" . ,(file-append
- font-tamzen
- "/share/kbd/consolefonts/TamzenForPowerline10x20.psf"))
- ("tty3" . ,(file-append
- font-terminus
- "/share/consolefonts/ter-132n"))) ; for HDPI
- @end lisp
- @end defvr
- @deffn {Scheme Procedure} login-service @var{config}
- Return a service to run login according to @var{config}, a
- @code{<login-configuration>} object, which specifies the message of the day,
- among other things.
- @end deffn
- @deftp {Data Type} login-configuration
- This is the data type representing the configuration of login.
- @table @asis
- @item @code{motd}
- @cindex message of the day
- A file-like object containing the ``message of the day''.
- @item @code{allow-empty-passwords?} (default: @code{#t})
- Allow empty passwords by default so that first-time users can log in when
- the 'root' account has just been created.
- @end table
- @end deftp
- @deffn {Scheme Procedure} mingetty-service @var{config}
- Return a service to run mingetty according to @var{config}, a
- @code{<mingetty-configuration>} object, which specifies the tty to run, among
- other things.
- @end deffn
- @deftp {Data Type} mingetty-configuration
- This is the data type representing the configuration of Mingetty, which
- provides the default implementation of virtual console log-in.
- @table @asis
- @item @code{tty}
- The name of the console this Mingetty runs on---e.g., @code{"tty1"}.
- @item @code{auto-login} (default: @code{#f})
- When true, this field must be a string denoting the user name under
- which the system automatically logs in. When it is @code{#f}, a
- user name and password must be entered to log in.
- @item @code{login-program} (default: @code{#f})
- This must be either @code{#f}, in which case the default log-in program
- is used (@command{login} from the Shadow tool suite), or a gexp denoting
- the name of the log-in program.
- @item @code{login-pause?} (default: @code{#f})
- When set to @code{#t} in conjunction with @var{auto-login}, the user
- will have to press a key before the log-in shell is launched.
- @item @code{clear-on-logout?} (default: @code{#t})
- When set to @code{#t}, the screen will be cleared after logout.
- @item @code{mingetty} (default: @var{mingetty})
- The Mingetty package to use.
- @end table
- @end deftp
- @deffn {Scheme Procedure} agetty-service @var{config}
- Return a service to run agetty according to @var{config}, an
- @code{<agetty-configuration>} object, which specifies the tty to run,
- among other things.
- @end deffn
- @deftp {Data Type} agetty-configuration
- This is the data type representing the configuration of agetty, which
- implements virtual and serial console log-in. See the @code{agetty(8)}
- man page for more information.
- @table @asis
- @item @code{tty}
- The name of the console this agetty runs on, as a string---e.g.,
- @code{"ttyS0"}. This argument is optional, it will default to
- a reasonable default serial port used by the kernel Linux.
- For this, if there is a value for an option @code{agetty.tty} in the kernel
- command line, agetty will extract the device name of the serial port
- from it and use that.
- If not and if there is a value for an option @code{console} with a tty in
- the Linux command line, agetty will extract the device name of the
- serial port from it and use that.
- In both cases, agetty will leave the other serial device settings
- (baud rate etc.)@: alone---in the hope that Linux pinned them to the
- correct values.
- @item @code{baud-rate} (default: @code{#f})
- A string containing a comma-separated list of one or more baud rates, in
- descending order.
- @item @code{term} (default: @code{#f})
- A string containing the value used for the @env{TERM} environment
- variable.
- @item @code{eight-bits?} (default: @code{#f})
- When @code{#t}, the tty is assumed to be 8-bit clean, and parity detection is
- disabled.
- @item @code{auto-login} (default: @code{#f})
- When passed a login name, as a string, the specified user will be logged
- in automatically without prompting for their login name or password.
- @item @code{no-reset?} (default: @code{#f})
- When @code{#t}, don't reset terminal cflags (control modes).
- @item @code{host} (default: @code{#f})
- This accepts a string containing the ``login_host'', which will be written
- into the @file{/var/run/utmpx} file.
- @item @code{remote?} (default: @code{#f})
- When set to @code{#t} in conjunction with @var{host}, this will add an
- @code{-r} fakehost option to the command line of the login program
- specified in @var{login-program}.
- @item @code{flow-control?} (default: @code{#f})
- When set to @code{#t}, enable hardware (RTS/CTS) flow control.
- @item @code{no-issue?} (default: @code{#f})
- When set to @code{#t}, the contents of the @file{/etc/issue} file will
- not be displayed before presenting the login prompt.
- @item @code{init-string} (default: @code{#f})
- This accepts a string that will be sent to the tty or modem before
- sending anything else. It can be used to initialize a modem.
- @item @code{no-clear?} (default: @code{#f})
- When set to @code{#t}, agetty will not clear the screen before showing
- the login prompt.
- @item @code{login-program} (default: (file-append shadow "/bin/login"))
- This must be either a gexp denoting the name of a log-in program, or
- unset, in which case the default value is the @command{login} from the
- Shadow tool suite.
- @item @code{local-line} (default: @code{#f})
- Control the CLOCAL line flag. This accepts one of three symbols as
- arguments, @code{'auto}, @code{'always}, or @code{'never}. If @code{#f},
- the default value chosen by agetty is @code{'auto}.
- @item @code{extract-baud?} (default: @code{#f})
- When set to @code{#t}, instruct agetty to try to extract the baud rate
- from the status messages produced by certain types of modems.
- @item @code{skip-login?} (default: @code{#f})
- When set to @code{#t}, do not prompt the user for a login name. This
- can be used with @var{login-program} field to use non-standard login
- systems.
- @item @code{no-newline?} (default: @code{#f})
- When set to @code{#t}, do not print a newline before printing the
- @file{/etc/issue} file.
- @c Is this dangerous only when used with login-program, or always?
- @item @code{login-options} (default: @code{#f})
- This option accepts a string containing options that are passed to the
- login program. When used with the @var{login-program}, be aware that a
- malicious user could try to enter a login name containing embedded
- options that could be parsed by the login program.
- @item @code{login-pause} (default: @code{#f})
- When set to @code{#t}, wait for any key before showing the login prompt.
- This can be used in conjunction with @var{auto-login} to save memory by
- lazily spawning shells.
- @item @code{chroot} (default: @code{#f})
- Change root to the specified directory. This option accepts a directory
- path as a string.
- @item @code{hangup?} (default: @code{#f})
- Use the Linux system call @code{vhangup} to do a virtual hangup of the
- specified terminal.
- @item @code{keep-baud?} (default: @code{#f})
- When set to @code{#t}, try to keep the existing baud rate. The baud
- rates from @var{baud-rate} are used when agetty receives a @key{BREAK}
- character.
- @item @code{timeout} (default: @code{#f})
- When set to an integer value, terminate if no user name could be read
- within @var{timeout} seconds.
- @item @code{detect-case?} (default: @code{#f})
- When set to @code{#t}, turn on support for detecting an uppercase-only
- terminal. This setting will detect a login name containing only
- uppercase letters as indicating an uppercase-only terminal and turn on
- some upper-to-lower case conversions. Note that this will not support
- Unicode characters.
- @item @code{wait-cr?} (default: @code{#f})
- When set to @code{#t}, wait for the user or modem to send a
- carriage-return or linefeed character before displaying
- @file{/etc/issue} or login prompt. This is typically used with the
- @var{init-string} option.
- @item @code{no-hints?} (default: @code{#f})
- When set to @code{#t}, do not print hints about Num, Caps, and Scroll
- locks.
- @item @code{no-hostname?} (default: @code{#f})
- By default, the hostname is printed. When this option is set to
- @code{#t}, no hostname will be shown at all.
- @item @code{long-hostname?} (default: @code{#f})
- By default, the hostname is only printed until the first dot. When this
- option is set to @code{#t}, the fully qualified hostname by
- @code{gethostname} or @code{getaddrinfo} is shown.
- @item @code{erase-characters} (default: @code{#f})
- This option accepts a string of additional characters that should be
- interpreted as backspace when the user types their login name.
- @item @code{kill-characters} (default: @code{#f})
- This option accepts a string that should be interpreted to mean ``ignore
- all previous characters'' (also called a ``kill'' character) when the user
- types their login name.
- @item @code{chdir} (default: @code{#f})
- This option accepts, as a string, a directory path that will be changed
- to before login.
- @item @code{delay} (default: @code{#f})
- This options accepts, as an integer, the number of seconds to sleep
- before opening the tty and displaying the login prompt.
- @item @code{nice} (default: @code{#f})
- This option accepts, as an integer, the nice value with which to run the
- @command{login} program.
- @item @code{extra-options} (default: @code{'()})
- This option provides an ``escape hatch'' for the user to provide arbitrary
- command-line arguments to @command{agetty} as a list of strings.
- @item @code{shepherd-requirement} (default: @code{'()})
- The option can be used to provides extra shepherd requirements (for example
- @code{'syslogd}) to the respective @code{'term-}* shepherd service.
- @end table
- @end deftp
- @deffn {Scheme Procedure} kmscon-service-type @var{config}
- Return a service to run @uref{https://www.freedesktop.org/wiki/Software/kmscon,kmscon}
- according to @var{config}, a @code{<kmscon-configuration>} object, which
- specifies the tty to run, among other things.
- @end deffn
- @deftp {Data Type} kmscon-configuration
- This is the data type representing the configuration of Kmscon, which
- implements virtual console log-in.
- @table @asis
- @item @code{virtual-terminal}
- The name of the console this Kmscon runs on---e.g., @code{"tty1"}.
- @item @code{login-program} (default: @code{#~(string-append #$shadow "/bin/login")})
- A gexp denoting the name of the log-in program. The default log-in program is
- @command{login} from the Shadow tool suite.
- @item @code{login-arguments} (default: @code{'("-p")})
- A list of arguments to pass to @command{login}.
- @item @code{auto-login} (default: @code{#f})
- When passed a login name, as a string, the specified user will be logged
- in automatically without prompting for their login name or password.
- @item @code{hardware-acceleration?} (default: #f)
- Whether to use hardware acceleration.
- @item @code{font-engine} (default: @code{"pango"})
- Font engine used in Kmscon.
- @item @code{font-size} (default: @code{12})
- Font size used in Kmscon.
- @item @code{keyboard-layout} (default: @code{#f})
- If this is @code{#f}, Kmscon uses the default keyboard layout---usually US
- English (``qwerty'') for a 105-key PC keyboard.
- Otherwise this must be a @code{keyboard-layout} object specifying the
- keyboard layout. @xref{Keyboard Layout}, for more information on how to
- specify the keyboard layout.
- @item @code{kmscon} (default: @var{kmscon})
- The Kmscon package to use.
- @end table
- @end deftp
- @cindex name service cache daemon
- @cindex nscd
- @deffn {Scheme Procedure} nscd-service [@var{config}] [#:glibc glibc] @
- [#:name-services '()]
- Return a service that runs the libc name service cache daemon (nscd) with the
- given @var{config}---an @code{<nscd-configuration>} object. @xref{Name
- Service Switch}, for an example.
- For convenience, the Shepherd service for nscd provides the following actions:
- @table @code
- @item invalidate
- @cindex cache invalidation, nscd
- @cindex nscd, cache invalidation
- This invalidate the given cache. For instance, running:
- @example
- herd invalidate nscd hosts
- @end example
- @noindent
- invalidates the host name lookup cache of nscd.
- @item statistics
- Running @command{herd statistics nscd} displays information about nscd usage
- and caches.
- @end table
- @end deffn
- @defvr {Scheme Variable} %nscd-default-configuration
- This is the default @code{<nscd-configuration>} value (see below) used
- by @code{nscd-service}. It uses the caches defined by
- @code{%nscd-default-caches}; see below.
- @end defvr
- @deftp {Data Type} nscd-configuration
- This is the data type representing the name service cache daemon (nscd)
- configuration.
- @table @asis
- @item @code{name-services} (default: @code{'()})
- List of packages denoting @dfn{name services} that must be visible to
- the nscd---e.g., @code{(list @var{nss-mdns})}.
- @item @code{glibc} (default: @var{glibc})
- Package object denoting the GNU C Library providing the @command{nscd}
- command.
- @item @code{log-file} (default: @code{"/var/log/nscd.log"})
- Name of the nscd log file. This is where debugging output goes when
- @code{debug-level} is strictly positive.
- @item @code{debug-level} (default: @code{0})
- Integer denoting the debugging levels. Higher numbers mean that more
- debugging output is logged.
- @item @code{caches} (default: @code{%nscd-default-caches})
- List of @code{<nscd-cache>} objects denoting things to be cached; see
- below.
- @end table
- @end deftp
- @deftp {Data Type} nscd-cache
- Data type representing a cache database of nscd and its parameters.
- @table @asis
- @item @code{database}
- This is a symbol representing the name of the database to be cached.
- Valid values are @code{passwd}, @code{group}, @code{hosts}, and
- @code{services}, which designate the corresponding NSS database
- (@pxref{NSS Basics,,, libc, The GNU C Library Reference Manual}).
- @item @code{positive-time-to-live}
- @itemx @code{negative-time-to-live} (default: @code{20})
- A number representing the number of seconds during which a positive or
- negative lookup result remains in cache.
- @item @code{check-files?} (default: @code{#t})
- Whether to check for updates of the files corresponding to
- @var{database}.
- For instance, when @var{database} is @code{hosts}, setting this flag
- instructs nscd to check for updates in @file{/etc/hosts} and to take
- them into account.
- @item @code{persistent?} (default: @code{#t})
- Whether the cache should be stored persistently on disk.
- @item @code{shared?} (default: @code{#t})
- Whether the cache should be shared among users.
- @item @code{max-database-size} (default: 32@tie{}MiB)
- Maximum size in bytes of the database cache.
- @c XXX: 'suggested-size' and 'auto-propagate?' seem to be expert
- @c settings, so leave them out.
- @end table
- @end deftp
- @defvr {Scheme Variable} %nscd-default-caches
- List of @code{<nscd-cache>} objects used by default by
- @code{nscd-configuration} (see above).
- It enables persistent and aggressive caching of service and host name
- lookups. The latter provides better host name lookup performance,
- resilience in the face of unreliable name servers, and also better
- privacy---often the result of host name lookups is in local cache, so
- external name servers do not even need to be queried.
- @end defvr
- @anchor{syslog-configuration-type}
- @cindex syslog
- @cindex logging
- @deftp {Data Type} syslog-configuration
- This data type represents the configuration of the syslog daemon.
- @table @asis
- @item @code{syslogd} (default: @code{#~(string-append #$inetutils "/libexec/syslogd")})
- The syslog daemon to use.
- @item @code{config-file} (default: @code{%default-syslog.conf})
- The syslog configuration file to use.
- @end table
- @end deftp
- @anchor{syslog-service}
- @cindex syslog
- @deffn {Scheme Procedure} syslog-service @var{config}
- Return a service that runs a syslog daemon according to @var{config}.
- @xref{syslogd invocation,,, inetutils, GNU Inetutils}, for more
- information on the configuration file syntax.
- @end deffn
- @defvr {Scheme Variable} guix-service-type
- This is the type of the service that runs the build daemon,
- @command{guix-daemon} (@pxref{Invoking guix-daemon}). Its value must be a
- @code{guix-configuration} record as described below.
- @end defvr
- @anchor{guix-configuration-type}
- @deftp {Data Type} guix-configuration
- This data type represents the configuration of the Guix build daemon.
- @xref{Invoking guix-daemon}, for more information.
- @table @asis
- @item @code{guix} (default: @var{guix})
- The Guix package to use.
- @item @code{build-group} (default: @code{"guixbuild"})
- Name of the group for build user accounts.
- @item @code{build-accounts} (default: @code{10})
- Number of build user accounts to create.
- @item @code{authorize-key?} (default: @code{#t})
- @cindex substitutes, authorization thereof
- Whether to authorize the substitute keys listed in
- @code{authorized-keys}---by default that of
- @code{@value{SUBSTITUTE-SERVER-1}} and
- @code{@value{SUBSTITUTE-SERVER-2}}
- (@pxref{Substitutes}).
- When @code{authorize-key?} is true, @file{/etc/guix/acl} cannot be
- changed by invoking @command{guix archive --authorize}. You must
- instead adjust @code{guix-configuration} as you wish and reconfigure the
- system. This ensures that your operating system configuration file is
- self-contained.
- @quotation Note
- When booting or reconfiguring to a system where @code{authorize-key?}
- is true, the existing @file{/etc/guix/acl} file is backed up as
- @file{/etc/guix/acl.bak} if it was determined to be a manually modified
- file. This is to facilitate migration from earlier versions, which
- allowed for in-place modifications to @file{/etc/guix/acl}.
- @end quotation
- @vindex %default-authorized-guix-keys
- @item @code{authorized-keys} (default: @code{%default-authorized-guix-keys})
- The list of authorized key files for archive imports, as a list of
- string-valued gexps (@pxref{Invoking guix archive}). By default, it
- contains that of @code{@value{SUBSTITUTE-SERVER-1}} and
- @code{@value{SUBSTITUTE-SERVER-2}} (@pxref{Substitutes}). See
- @code{substitute-urls} below for an example on how to change it.
- @item @code{use-substitutes?} (default: @code{#t})
- Whether to use substitutes.
- @item @code{substitute-urls} (default: @code{%default-substitute-urls})
- The list of URLs where to look for substitutes by default.
- Suppose you would like to fetch substitutes from @code{guix.example.org}
- in addition to @code{@value{SUBSTITUTE-SERVER-1}}. You will need to do
- two things: (1) add @code{guix.example.org} to @code{substitute-urls},
- and (2) authorize its signing key, having done appropriate checks
- (@pxref{Substitute Server Authorization}). The configuration below does
- exactly that:
- @lisp
- (guix-configuration
- (substitute-urls
- (append (list "https://guix.example.org")
- %default-substitute-urls))
- (authorized-keys
- (append (list (local-file "./guix.example.org-key.pub"))
- %default-authorized-guix-keys)))
- @end lisp
- This example assumes that the file @file{./guix.example.org-key.pub}
- contains the public key that @code{guix.example.org} uses to sign
- substitutes.
- @item @code{generate-substitute-key?} (default: @code{#t})
- Whether to generate a @dfn{substitute key pair} under
- @file{/etc/guix/signing-key.pub} and @file{/etc/guix/signing-key.sec} if
- there is not already one.
- This key pair is used when exporting store items, for instance with
- @command{guix publish} (@pxref{Invoking guix publish}) or @command{guix
- archive} (@pxref{Invoking guix archive}). Generating a key pair takes a
- few seconds when enough entropy is available and is only done once; you
- might want to turn it off for instance in a virtual machine that does
- not need it and where the extra boot time is a problem.
- @item @code{max-silent-time} (default: @code{0})
- @itemx @code{timeout} (default: @code{0})
- The number of seconds of silence and the number of seconds of activity,
- respectively, after which a build process times out. A value of zero
- disables the timeout.
- @item @code{log-compression} (default: @code{'gzip})
- The type of compression used for build logs---one of @code{gzip},
- @code{bzip2}, or @code{none}.
- @item @code{discover?} (default: @code{#f})
- Whether to discover substitute servers on the local network using mDNS
- and DNS-SD.
- @item @code{extra-options} (default: @code{'()})
- List of extra command-line options for @command{guix-daemon}.
- @item @code{log-file} (default: @code{"/var/log/guix-daemon.log"})
- File where @command{guix-daemon}'s standard output and standard error
- are written.
- @cindex HTTP proxy, for @code{guix-daemon}
- @cindex proxy, for @code{guix-daemon} HTTP access
- @item @code{http-proxy} (default: @code{#f})
- The URL of the HTTP and HTTPS proxy used for downloading fixed-output
- derivations and substitutes.
- It is also possible to change the daemon's proxy at run time through the
- @code{set-http-proxy} action, which restarts it:
- @example
- herd set-http-proxy guix-daemon http://localhost:8118
- @end example
- To clear the proxy settings, run:
- @example
- herd set-http-proxy guix-daemon
- @end example
- @item @code{tmpdir} (default: @code{#f})
- A directory path where the @command{guix-daemon} will perform builds.
- @end table
- @end deftp
- @deffn {Scheme Procedure} udev-service [#:udev @var{eudev} #:rules @code{'()}]
- Run @var{udev}, which populates the @file{/dev} directory dynamically.
- udev rules can be provided as a list of files through the @var{rules}
- variable. The procedures @code{udev-rule}, @code{udev-rules-service}
- and @code{file->udev-rule} from @code{(gnu services base)} simplify the
- creation of such rule files.
- The @command{herd rules udev} command, as root, returns the name of the
- directory containing all the active udev rules.
- @end deffn
- @deffn {Scheme Procedure} udev-rule [@var{file-name} @var{contents}]
- Return a udev-rule file named @var{file-name} containing the rules
- defined by the @var{contents} literal.
- In the following example, a rule for a USB device is defined to be
- stored in the file @file{90-usb-thing.rules}. The rule runs a script
- upon detecting a USB device with a given product identifier.
- @lisp
- (define %example-udev-rule
- (udev-rule
- "90-usb-thing.rules"
- (string-append "ACTION==\"add\", SUBSYSTEM==\"usb\", "
- "ATTR@{product@}==\"Example\", "
- "RUN+=\"/path/to/script\"")))
- @end lisp
- @end deffn
- @deffn {Scheme Procedure} udev-rules-service [@var{name} @var{rules}] @
- [#:groups @var{groups}]
- Return a service that extends @code{udev-service-type } with @var{rules}
- and @code{account-service-type} with @var{groups} as system groups.
- This works by creating a singleton service type
- @code{@var{name}-udev-rules}, of which the returned service is an
- instance.
- Here we show how it can be used to extend @code{udev-service-type} with the
- previously defined rule @code{%example-udev-rule}.
- @lisp
- (operating-system
- ;; @dots{}
- (services
- (cons (udev-rules-service 'usb-thing %example-udev-rule)
- %desktop-services)))
- @end lisp
- @end deffn
- @deffn {Scheme Procedure} file->udev-rule [@var{file-name} @var{file}]
- Return a udev file named @var{file-name} containing the rules defined
- within @var{file}, a file-like object.
- The following example showcases how we can use an existing rule file.
- @lisp
- (use-modules (guix download) ;for url-fetch
- (guix packages) ;for origin
- @dots{})
- (define %android-udev-rules
- (file->udev-rule
- "51-android-udev.rules"
- (let ((version "20170910"))
- (origin
- (method url-fetch)
- (uri (string-append "https://raw.githubusercontent.com/M0Rf30/"
- "android-udev-rules/" version "/51-android.rules"))
- (sha256
- (base32 "0lmmagpyb6xsq6zcr2w1cyx9qmjqmajkvrdbhjx32gqf1d9is003"))))))
- @end lisp
- @end deffn
- Additionally, Guix package definitions can be included in @var{rules} in
- order to extend the udev rules with the definitions found under their
- @file{lib/udev/rules.d} sub-directory. In lieu of the previous
- @var{file->udev-rule} example, we could have used the
- @var{android-udev-rules} package which exists in Guix in the @code{(gnu
- packages android)} module.
- The following example shows how to use the @var{android-udev-rules}
- package so that the Android tool @command{adb} can detect devices
- without root privileges. It also details how to create the
- @code{adbusers} group, which is required for the proper functioning of
- the rules defined within the @code{android-udev-rules} package. To
- create such a group, we must define it both as part of the
- @code{supplementary-groups} of our @code{user-account} declaration, as
- well as in the @var{groups} of the @code{udev-rules-service} procedure.
- @lisp
- (use-modules (gnu packages android) ;for android-udev-rules
- (gnu system shadow) ;for user-group
- @dots{})
- (operating-system
- ;; @dots{}
- (users (cons (user-account
- ;; @dots{}
- (supplementary-groups
- '("adbusers" ;for adb
- "wheel" "netdev" "audio" "video")))))
- ;; @dots{}
- (services
- (cons (udev-rules-service 'android android-udev-rules
- #:groups '("adbusers"))
- %desktop-services)))
- @end lisp
- @defvr {Scheme Variable} urandom-seed-service-type
- Save some entropy in @code{%random-seed-file} to seed @file{/dev/urandom}
- when rebooting. It also tries to seed @file{/dev/urandom} from
- @file{/dev/hwrng} while booting, if @file{/dev/hwrng} exists and is
- readable.
- @end defvr
- @defvr {Scheme Variable} %random-seed-file
- This is the name of the file where some random bytes are saved by
- @var{urandom-seed-service} to seed @file{/dev/urandom} when rebooting.
- It defaults to @file{/var/lib/random-seed}.
- @end defvr
- @cindex mouse
- @cindex gpm
- @defvr {Scheme Variable} gpm-service-type
- This is the type of the service that runs GPM, the @dfn{general-purpose
- mouse daemon}, which provides mouse support to the Linux console. GPM
- allows users to use the mouse in the console, notably to select, copy,
- and paste text.
- The value for services of this type must be a @code{gpm-configuration}
- (see below). This service is not part of @code{%base-services}.
- @end defvr
- @deftp {Data Type} gpm-configuration
- Data type representing the configuration of GPM.
- @table @asis
- @item @code{options} (default: @code{%default-gpm-options})
- Command-line options passed to @command{gpm}. The default set of
- options instruct @command{gpm} to listen to mouse events on
- @file{/dev/input/mice}. @xref{Command Line,,, gpm, gpm manual}, for
- more information.
- @item @code{gpm} (default: @code{gpm})
- The GPM package to use.
- @end table
- @end deftp
- @anchor{guix-publish-service-type}
- @deffn {Scheme Variable} guix-publish-service-type
- This is the service type for @command{guix publish} (@pxref{Invoking
- guix publish}). Its value must be a @code{guix-publish-configuration}
- object, as described below.
- This assumes that @file{/etc/guix} already contains a signing key pair as
- created by @command{guix archive --generate-key} (@pxref{Invoking guix
- archive}). If that is not the case, the service will fail to start.
- @end deffn
- @deftp {Data Type} guix-publish-configuration
- Data type representing the configuration of the @code{guix publish}
- service.
- @table @asis
- @item @code{guix} (default: @code{guix})
- The Guix package to use.
- @item @code{port} (default: @code{80})
- The TCP port to listen for connections.
- @item @code{host} (default: @code{"localhost"})
- The host (and thus, network interface) to listen to. Use
- @code{"0.0.0.0"} to listen on all the network interfaces.
- @item @code{advertise?} (default: @code{#f})
- When true, advertise the service on the local network @i{via} the DNS-SD
- protocol, using Avahi.
- This allows neighboring Guix devices with discovery on (see
- @code{guix-configuration} above) to discover this @command{guix publish}
- instance and to automatically download substitutes from it.
- @item @code{compression} (default: @code{'(("gzip" 3) ("zstd" 3))})
- This is a list of compression method/level tuple used when compressing
- substitutes. For example, to compress all substitutes with @emph{both} lzip
- at level 7 and gzip at level 9, write:
- @lisp
- '(("lzip" 7) ("gzip" 9))
- @end lisp
- Level 9 achieves the best compression ratio at the expense of increased CPU
- usage, whereas level 1 achieves fast compression. @xref{Invoking guix
- publish}, for more information on the available compression methods and
- the tradeoffs involved.
- An empty list disables compression altogether.
- @item @code{nar-path} (default: @code{"nar"})
- The URL path at which ``nars'' can be fetched. @xref{Invoking guix
- publish, @option{--nar-path}}, for details.
- @item @code{cache} (default: @code{#f})
- When it is @code{#f}, disable caching and instead generate archives on
- demand. Otherwise, this should be the name of a directory---e.g.,
- @code{"/var/cache/guix/publish"}---where @command{guix publish} caches
- archives and meta-data ready to be sent. @xref{Invoking guix publish,
- @option{--cache}}, for more information on the tradeoffs involved.
- @item @code{workers} (default: @code{#f})
- When it is an integer, this is the number of worker threads used for
- caching; when @code{#f}, the number of processors is used.
- @xref{Invoking guix publish, @option{--workers}}, for more information.
- @item @code{cache-bypass-threshold} (default: 10 MiB)
- When @code{cache} is true, this is the maximum size in bytes of a store
- item for which @command{guix publish} may bypass its cache in case of a
- cache miss. @xref{Invoking guix publish,
- @option{--cache-bypass-threshold}}, for more information.
- @item @code{ttl} (default: @code{#f})
- When it is an integer, this denotes the @dfn{time-to-live} in seconds
- of the published archives. @xref{Invoking guix publish, @option{--ttl}},
- for more information.
- @item @code{negative-ttl} (default: @code{#f})
- When it is an integer, this denotes the @dfn{time-to-live} in
- seconds for the negative lookups. @xref{Invoking guix publish,
- @option{--negative-ttl}}, for more information.
- @end table
- @end deftp
- @anchor{rngd-service}
- @deffn {Scheme Procedure} rngd-service [#:rng-tools @var{rng-tools}] @
- [#:device "/dev/hwrng"]
- Return a service that runs the @command{rngd} program from @var{rng-tools}
- to add @var{device} to the kernel's entropy pool. The service will fail if
- @var{device} does not exist.
- @end deffn
- @anchor{pam-limits-service}
- @cindex session limits
- @cindex ulimit
- @cindex priority
- @cindex realtime
- @cindex jackd
- @cindex nofile
- @cindex open file descriptors
- @deffn {Scheme Procedure} pam-limits-service [#:limits @code{'()}]
- Return a service that installs a configuration file for the
- @uref{http://linux-pam.org/Linux-PAM-html/sag-pam_limits.html,
- @code{pam_limits} module}. The procedure optionally takes a list of
- @code{pam-limits-entry} values, which can be used to specify
- @code{ulimit} limits and @code{nice} priority limits to user sessions.
- The following limits definition sets two hard and soft limits for all
- login sessions of users in the @code{realtime} group:
- @lisp
- (pam-limits-service
- (list
- (pam-limits-entry "@@realtime" 'both 'rtprio 99)
- (pam-limits-entry "@@realtime" 'both 'memlock 'unlimited)))
- @end lisp
- The first entry increases the maximum realtime priority for
- non-privileged processes; the second entry lifts any restriction of the
- maximum address space that can be locked in memory. These settings are
- commonly used for real-time audio systems.
- Another useful example is raising the maximum number of open file
- descriptors that can be used:
- @lisp
- (pam-limits-service
- (list
- (pam-limits-entry "*" 'both 'nofile 100000)))
- @end lisp
- In the above example, the asterisk means the limit should apply to any
- user. It is important to ensure the chosen value doesn't exceed the
- maximum system value visible in the @file{/proc/sys/fs/file-max} file,
- else the users would be prevented from login in. For more information
- about the Pluggable Authentication Module (PAM) limits, refer to the
- @samp{pam_limits} man page from the @code{linux-pam} package.
- @end deffn
- @node Scheduled Job Execution
- @subsection Scheduled Job Execution
- @cindex cron
- @cindex mcron
- @cindex scheduling jobs
- The @code{(gnu services mcron)} module provides an interface to
- GNU@tie{}mcron, a daemon to run jobs at scheduled times (@pxref{Top,,,
- mcron, GNU@tie{}mcron}). GNU@tie{}mcron is similar to the traditional
- Unix @command{cron} daemon; the main difference is that it is
- implemented in Guile Scheme, which provides a lot of flexibility when
- specifying the scheduling of jobs and their actions.
- The example below defines an operating system that runs the
- @command{updatedb} (@pxref{Invoking updatedb,,, find, Finding Files})
- and the @command{guix gc} commands (@pxref{Invoking guix gc}) daily, as
- well as the @command{mkid} command on behalf of an unprivileged user
- (@pxref{mkid invocation,,, idutils, ID Database Utilities}). It uses
- gexps to introduce job definitions that are passed to mcron
- (@pxref{G-Expressions}).
- @lisp
- (use-modules (guix) (gnu) (gnu services mcron))
- (use-package-modules base idutils)
- (define updatedb-job
- ;; Run 'updatedb' at 3AM every day. Here we write the
- ;; job's action as a Scheme procedure.
- #~(job '(next-hour '(3))
- (lambda ()
- (execl (string-append #$findutils "/bin/updatedb")
- "updatedb"
- "--prunepaths=/tmp /var/tmp /gnu/store"))
- "updatedb"))
- (define garbage-collector-job
- ;; Collect garbage 5 minutes after midnight every day.
- ;; The job's action is a shell command.
- #~(job "5 0 * * *" ;Vixie cron syntax
- "guix gc -F 1G"))
- (define idutils-job
- ;; Update the index database as user "charlie" at 12:15PM
- ;; and 19:15PM. This runs from the user's home directory.
- #~(job '(next-minute-from (next-hour '(12 19)) '(15))
- (string-append #$idutils "/bin/mkid src")
- #:user "charlie"))
- (operating-system
- ;; @dots{}
- ;; %BASE-SERVICES already includes an instance of
- ;; 'mcron-service-type', which we extend with additional
- ;; jobs using 'simple-service'.
- (services (cons (simple-service 'my-cron-jobs
- mcron-service-type
- (list garbage-collector-job
- updatedb-job
- idutils-job))
- %base-services)))
- @end lisp
- @quotation Tip
- When providing the action of a job specification as a procedure, you
- should provide an explicit name for the job via the optional 3rd
- argument as done in the @code{updatedb-job} example above. Otherwise,
- the job would appear as ``Lambda function'' in the output of
- @command{herd schedule mcron}, which is not nearly descriptive enough!
- @end quotation
- For more complex jobs defined in Scheme where you need control over the top
- level, for instance to introduce a @code{use-modules} form, you can move your
- code to a separate program using the @code{program-file} procedure of the
- @code{(guix gexp)} module (@pxref{G-Expressions}). The example below
- illustrates that.
- @lisp
- (define %battery-alert-job
- ;; Beep when the battery percentage falls below %MIN-LEVEL.
- #~(job
- '(next-minute (range 0 60 1))
- #$(program-file
- "battery-alert.scm"
- (with-imported-modules (source-module-closure
- '((guix build utils)))
- #~(begin
- (use-modules (guix build utils)
- (ice-9 popen)
- (ice-9 regex)
- (ice-9 textual-ports)
- (srfi srfi-2))
- (define %min-level 20)
- (setenv "LC_ALL" "C") ;ensure English output
- (and-let* ((input-pipe (open-pipe*
- OPEN_READ
- #$(file-append acpi "/bin/acpi")))
- (output (get-string-all input-pipe))
- (m (string-match "Discharging, ([0-9]+)%" output))
- (level (string->number (match:substring m 1)))
- ((< level %min-level)))
- (format #t "warning: Battery level is low (~a%)~%" level)
- (invoke #$(file-append beep "/bin/beep") "-r5")))))))
- @end lisp
- @xref{Guile Syntax, mcron job specifications,, mcron, GNU@tie{}mcron},
- for more information on mcron job specifications. Below is the
- reference of the mcron service.
- On a running system, you can use the @code{schedule} action of the service to
- visualize the mcron jobs that will be executed next:
- @example
- # herd schedule mcron
- @end example
- @noindent
- The example above lists the next five tasks that will be executed, but you can
- also specify the number of tasks to display:
- @example
- # herd schedule mcron 10
- @end example
- @defvr {Scheme Variable} mcron-service-type
- This is the type of the @code{mcron} service, whose value is an
- @code{mcron-configuration} object.
- This service type can be the target of a service extension that provides
- additional job specifications (@pxref{Service Composition}). In other
- words, it is possible to define services that provide additional mcron
- jobs to run.
- @end defvr
- @deftp {Data Type} mcron-configuration
- Data type representing the configuration of mcron.
- @table @asis
- @item @code{mcron} (default: @var{mcron})
- The mcron package to use.
- @item @code{jobs}
- This is a list of gexps (@pxref{G-Expressions}), where each gexp
- corresponds to an mcron job specification (@pxref{Syntax, mcron job
- specifications,, mcron, GNU@tie{}mcron}).
- @end table
- @end deftp
- @node Log Rotation
- @subsection Log Rotation
- @cindex rottlog
- @cindex log rotation
- @cindex logging
- Log files such as those found in @file{/var/log} tend to grow endlessly,
- so it's a good idea to @dfn{rotate} them once in a while---i.e., archive
- their contents in separate files, possibly compressed. The @code{(gnu
- services admin)} module provides an interface to GNU@tie{}Rot[t]log, a
- log rotation tool (@pxref{Top,,, rottlog, GNU Rot[t]log Manual}).
- This service is part of @code{%base-services}, and thus enabled by
- default, with the default settings, for commonly encountered log files.
- The example below shows how to extend it with an additional
- @dfn{rotation}, should you need to do that (usually, services that
- produce log files already take care of that):
- @lisp
- (use-modules (guix) (gnu))
- (use-service-modules admin)
- (define my-log-files
- ;; Log files that I want to rotate.
- '("/var/log/something.log" "/var/log/another.log"))
- (operating-system
- ;; @dots{}
- (services (cons (simple-service 'rotate-my-stuff
- rottlog-service-type
- (list (log-rotation
- (frequency 'daily)
- (files my-log-files))))
- %base-services)))
- @end lisp
- @defvr {Scheme Variable} rottlog-service-type
- This is the type of the Rottlog service, whose value is a
- @code{rottlog-configuration} object.
- Other services can extend this one with new @code{log-rotation} objects
- (see below), thereby augmenting the set of files to be rotated.
- This service type can define mcron jobs (@pxref{Scheduled Job
- Execution}) to run the rottlog service.
- @end defvr
- @deftp {Data Type} rottlog-configuration
- Data type representing the configuration of rottlog.
- @table @asis
- @item @code{rottlog} (default: @code{rottlog})
- The Rottlog package to use.
- @item @code{rc-file} (default: @code{(file-append rottlog "/etc/rc")})
- The Rottlog configuration file to use (@pxref{Mandatory RC Variables,,,
- rottlog, GNU Rot[t]log Manual}).
- @item @code{rotations} (default: @code{%default-rotations})
- A list of @code{log-rotation} objects as defined below.
- @item @code{jobs}
- This is a list of gexps where each gexp corresponds to an mcron job
- specification (@pxref{Scheduled Job Execution}).
- @end table
- @end deftp
- @deftp {Data Type} log-rotation
- Data type representing the rotation of a group of log files.
- Taking an example from the Rottlog manual (@pxref{Period Related File
- Examples,,, rottlog, GNU Rot[t]log Manual}), a log rotation might be
- defined like this:
- @lisp
- (log-rotation
- (frequency 'daily)
- (files '("/var/log/apache/*"))
- (options '("storedir apache-archives"
- "rotate 6"
- "notifempty"
- "nocompress")))
- @end lisp
- The list of fields is as follows:
- @table @asis
- @item @code{frequency} (default: @code{'weekly})
- The log rotation frequency, a symbol.
- @item @code{files}
- The list of files or file glob patterns to rotate.
- @item @code{options} (default: @code{'()})
- The list of rottlog options for this rotation (@pxref{Configuration
- parameters,,, rottlog, GNU Rot[t]lg Manual}).
- @item @code{post-rotate} (default: @code{#f})
- Either @code{#f} or a gexp to execute once the rotation has completed.
- @end table
- @end deftp
- @defvr {Scheme Variable} %default-rotations
- Specifies weekly rotation of @code{%rotated-files} and of
- @file{/var/log/guix-daemon.log}.
- @end defvr
- @defvr {Scheme Variable} %rotated-files
- The list of syslog-controlled files to be rotated. By default it is:
- @code{'("/var/log/messages" "/var/log/secure" "/var/log/debug" \
- "/var/log/maillog")}.
- @end defvr
- Some log files just need to be deleted periodically once they are old,
- without any other criterion and without any archival step. This is the
- case of build logs stored by @command{guix-daemon} under
- @file{/var/log/guix/drvs} (@pxref{Invoking guix-daemon}). The
- @code{log-cleanup} service addresses this use case. For example,
- @code{%base-services} (@pxref{Base Services}) includes the following:
- @lisp
- ;; Periodically delete old build logs.
- (service log-cleanup-service-type
- (log-cleanup-configuration
- (directory "/var/log/guix/drvs")))
- @end lisp
- That ensures build logs do not accumulate endlessly.
- @defvr {Scheme Variable} log-cleanup-service-type
- This is the type of the service to delete old logs. Its value must be a
- @code{log-cleanup-configuration} record as described below.
- @end defvr
- @deftp {Data Type} log-cleanup-configuration
- Data type representing the log cleanup configuration
- @table @asis
- @item @code{directory}
- Name of the directory containing log files.
- @item @code{expiry} (default: @code{(* 6 30 24 3600)})
- Age in seconds after which a file is subject to deletion (six months by
- default).
- @item @code{schedule} (default: @code{"30 12 01,08,15,22 * *"})
- String or gexp denoting the corresponding mcron job schedule
- (@pxref{Scheduled Job Execution}).
- @end table
- @end deftp
- @node Networking Setup
- @subsection Networking Setup
- The @code{(gnu services networking)} module provides services to
- configure network interfaces and set up networking on your machine.
- Those services provide different ways for you to set up your machine: by
- declaring a static network configuration, by running a Dynamic Host
- Configuration Protocol (DHCP) client, or by running daemons such as
- NetworkManager and Connman that automate the whole process,
- automatically adapt to connectivity changes, and provide a high-level
- user interface.
- On a laptop, NetworkManager and Connman are by far the most convenient
- options, which is why the default desktop services include
- NetworkManager (@pxref{Desktop Services, @code{%desktop-services}}).
- For a server, or for a virtual machine or a container, static network
- configuration or a simple DHCP client are often more appropriate.
- This section describes the various network setup services available,
- starting with static network configuration.
- @defvr {Scheme Variable} static-networking-service-type
- This is the type for statically-configured network interfaces. Its
- value must be a list of @code{static-networking} records. Each of them
- declares a set of @dfn{addresses}, @dfn{routes}, and @dfn{links}, as
- show below.
- @cindex network interface controller (NIC)
- @cindex NIC, networking interface controller
- Here is the simplest configuration, with only one network interface
- controller (NIC) and only IPv4 connectivity:
- @lisp
- ;; Static networking for one NIC, IPv4-only.
- (service static-networking-service-type
- (list (static-networking
- (addresses
- (list (network-address
- (device "eno1")
- (value "10.0.2.15/24"))))
- (routes
- (list (network-route
- (destination "default")
- (gateway "10.0.2.2"))))
- (name-servers '("10.0.2.3")))))
- @end lisp
- The snippet above can be added to the @code{services} field of your
- operating system configuration (@pxref{Using the Configuration System}).
- It will configure your machine to have 10.0.2.15 as its IP address, with
- a 24-bit netmask for the local network---meaning that any 10.0.2.@var{x}
- address is on the local area network (LAN). Traffic to addresses
- outside the local network is routed @i{via} 10.0.2.2. Host names are
- resolved by sending domain name system (DNS) queries to 10.0.2.3.
- @end defvr
- @deftp {Data Type} static-networking
- This is the data type representing a static network configuration.
- As an example, here is how you would declare the configuration of a
- machine with a single network interface controller (NIC) available as
- @code{eno1}, and with one IPv4 and one IPv6 address:
- @lisp
- ;; Network configuration for one NIC, IPv4 + IPv6.
- (static-networking
- (addresses (list (network-address
- (device "eno1")
- (value "10.0.2.15/24"))
- (network-address
- (device "eno1")
- (value "2001:123:4567:101::1/64"))))
- (routes (list (network-route
- (destination "default")
- (gateway "10.0.2.2"))
- (network-route
- (destination "default")
- (gateway "2020:321:4567:42::1"))))
- (name-servers '("10.0.2.3")))
- @end lisp
- If you are familiar with the @command{ip} command of the
- @uref{https://wiki.linuxfoundation.org/networking/iproute2,
- @code{iproute2} package} found on Linux-based systems, the declaration
- above is equivalent to typing:
- @example
- ip address add 10.0.2.15/24 dev eno1
- ip address add 2001:123:4567:101::1/64 dev eno1
- ip route add default via inet 10.0.2.2
- ip route add default via inet6 2020:321:4567:42::1
- @end example
- Run @command{man 8 ip} for more info. Venerable GNU/Linux users will
- certainly know how to do it with @command{ifconfig} and @command{route},
- but we'll spare you that.
- The available fields of this data type are as follows:
- @table @asis
- @item @code{addresses}
- @itemx @code{links} (default: @code{'()})
- @itemx @code{routes} (default: @code{'()})
- The list of @code{network-address}, @code{network-link}, and
- @code{network-route} records for this network (see below).
- @item @code{name-servers} (default: @code{'()})
- The list of IP addresses (strings) of domain name servers. These IP
- addresses go to @file{/etc/resolv.conf}.
- @item @code{provision} (default: @code{'(networking)})
- If true, this should be a list of symbols for the Shepherd service
- corresponding to this network configuration.
- @item @code{requirement} (default @code{'()})
- The list of Shepherd services depended on.
- @end table
- @end deftp
- @deftp {Data Type} network-address
- This is the data type representing the IP address of a network
- interface.
- @table @code
- @item device
- The name of the network interface for this address---e.g.,
- @code{"eno1"}.
- @item value
- The actual IP address and network mask, in
- @uref{https://en.wikipedia.org/wiki/CIDR#CIDR_notation, @acronym{CIDR,
- Classless Inter-Domain Routing} notation}, as a string.
- For example, @code{"10.0.2.15/24"} denotes IPv4 address 10.0.2.15 on a
- 24-bit sub-network---all 10.0.2.@var{x} addresses are on the same local
- network.
- @item ipv6?
- Whether @code{value} denotes an IPv6 address. By default this is
- automatically determined.
- @end table
- @end deftp
- @deftp {Data Type} network-route
- This is the data type representing a network route.
- @table @asis
- @item @code{destination}
- The route destination (a string), either an IP address or
- @code{"default"} to denote the default route.
- @item @code{source} (default: @code{#f})
- The route source.
- @item @code{device} (default: @code{#f})
- The device used for this route---e.g., @code{"eno2"}.
- @item @code{ipv6?} (default: auto)
- Whether this is an IPv6 route. By default this is automatically
- determined based on @code{destination} or @code{gateway}.
- @item @code{gateway} (default: @code{#f})
- IP address (a string) through which traffic is routed.
- @end table
- @end deftp
- @deftp {Data Type} network-link
- Data type for a network link (@pxref{Link,,, guile-netlink,
- Guile-Netlink Manual}).
- @table @code
- @item name
- The name of the link---e.g., @code{"v0p0"}.
- @item type
- A symbol denoting the type of the link---e.g., @code{'veth}.
- @item arguments
- List of arguments for this type of link.
- @end table
- @end deftp
- @cindex loopback device
- @defvr {Scheme Variable} %loopback-static-networking
- This is the @code{static-networking} record representing the ``loopback
- device'', @code{lo}, for IP addresses 127.0.0.1 and ::1, and providing
- the @code{loopback} Shepherd service.
- @end defvr
- @cindex networking, with QEMU
- @cindex QEMU, networking
- @defvr {Scheme Variable} %qemu-static-networking
- This is the @code{static-networking} record representing network setup
- when using QEMU's user-mode network stack on @code{eth0} (@pxref{Using
- the user mode network stack,,, QEMU, QEMU Documentation}).
- @end defvr
- @cindex DHCP, networking service
- @defvr {Scheme Variable} dhcp-client-service-type
- This is the type of services that run @var{dhcp}, a Dynamic Host Configuration
- Protocol (DHCP) client, on all the non-loopback network interfaces. Its value
- is the DHCP client package to use, @code{isc-dhcp} by default.
- @end defvr
- @cindex NetworkManager
- @defvr {Scheme Variable} network-manager-service-type
- This is the service type for the
- @uref{https://wiki.gnome.org/Projects/NetworkManager, NetworkManager}
- service. The value for this service type is a
- @code{network-manager-configuration} record.
- This service is part of @code{%desktop-services} (@pxref{Desktop
- Services}).
- @end defvr
- @deftp {Data Type} network-manager-configuration
- Data type representing the configuration of NetworkManager.
- @table @asis
- @item @code{network-manager} (default: @code{network-manager})
- The NetworkManager package to use.
- @item @code{dns} (default: @code{"default"})
- Processing mode for DNS, which affects how NetworkManager uses the
- @code{resolv.conf} configuration file.
- @table @samp
- @item default
- NetworkManager will update @code{resolv.conf} to reflect the nameservers
- provided by currently active connections.
- @item dnsmasq
- NetworkManager will run @code{dnsmasq} as a local caching nameserver, using a
- @dfn{conditional forwarding} configuration if you are connected to a VPN, and
- then update @code{resolv.conf} to point to the local nameserver.
- With this setting, you can share your network connection. For example when
- you want to share your network connection to another laptop @i{via} an
- Ethernet cable, you can open @command{nm-connection-editor} and configure the
- Wired connection's method for IPv4 and IPv6 to be ``Shared to other computers''
- and reestablish the connection (or reboot).
- You can also set up a @dfn{host-to-guest connection} to QEMU VMs
- (@pxref{Installing Guix in a VM}). With a host-to-guest connection, you can
- e.g.@: access a Web server running on the VM (@pxref{Web Services}) from a Web
- browser on your host system, or connect to the VM @i{via} SSH
- (@pxref{Networking Services, @code{openssh-service-type}}). To set up a
- host-to-guest connection, run this command once:
- @example
- nmcli connection add type tun \
- connection.interface-name tap0 \
- tun.mode tap tun.owner $(id -u) \
- ipv4.method shared \
- ipv4.addresses 172.28.112.1/24
- @end example
- Then each time you launch your QEMU VM (@pxref{Running Guix in a VM}), pass
- @option{-nic tap,ifname=tap0,script=no,downscript=no} to
- @command{qemu-system-...}.
- @item none
- NetworkManager will not modify @code{resolv.conf}.
- @end table
- @item @code{vpn-plugins} (default: @code{'()})
- This is the list of available plugins for virtual private networks
- (VPNs). An example of this is the @code{network-manager-openvpn}
- package, which allows NetworkManager to manage VPNs @i{via} OpenVPN.
- @end table
- @end deftp
- @cindex Connman
- @deffn {Scheme Variable} connman-service-type
- This is the service type to run @url{https://01.org/connman,Connman},
- a network connection manager.
- Its value must be an
- @code{connman-configuration} record as in this example:
- @lisp
- (service connman-service-type
- (connman-configuration
- (disable-vpn? #t)))
- @end lisp
- See below for details about @code{connman-configuration}.
- @end deffn
- @deftp {Data Type} connman-configuration
- Data Type representing the configuration of connman.
- @table @asis
- @item @code{connman} (default: @var{connman})
- The connman package to use.
- @item @code{disable-vpn?} (default: @code{#f})
- When true, disable connman's vpn plugin.
- @end table
- @end deftp
- @cindex WPA Supplicant
- @defvr {Scheme Variable} wpa-supplicant-service-type
- This is the service type to run @url{https://w1.fi/wpa_supplicant/,WPA
- supplicant}, an authentication daemon required to authenticate against
- encrypted WiFi or ethernet networks.
- @end defvr
- @deftp {Data Type} wpa-supplicant-configuration
- Data type representing the configuration of WPA Supplicant.
- It takes the following parameters:
- @table @asis
- @item @code{wpa-supplicant} (default: @code{wpa-supplicant})
- The WPA Supplicant package to use.
- @item @code{requirement} (default: @code{'(user-processes loopback syslogd)}
- List of services that should be started before WPA Supplicant starts.
- @item @code{dbus?} (default: @code{#t})
- Whether to listen for requests on D-Bus.
- @item @code{pid-file} (default: @code{"/var/run/wpa_supplicant.pid"})
- Where to store the PID file.
- @item @code{interface} (default: @code{#f})
- If this is set, it must specify the name of a network interface that
- WPA supplicant will control.
- @item @code{config-file} (default: @code{#f})
- Optional configuration file to use.
- @item @code{extra-options} (default: @code{'()})
- List of additional command-line arguments to pass to the daemon.
- @end table
- @end deftp
- @cindex wicd
- @cindex wireless
- @cindex WiFi
- @cindex network management
- @deffn {Scheme Procedure} wicd-service [#:wicd @var{wicd}]
- Return a service that runs @url{https://launchpad.net/wicd,Wicd}, a network
- management daemon that aims to simplify wired and wireless networking.
- This service adds the @var{wicd} package to the global profile, providing
- several commands to interact with the daemon and configure networking:
- @command{wicd-client}, a graphical user interface, and the @command{wicd-cli}
- and @command{wicd-curses} user interfaces.
- @end deffn
- @cindex ModemManager
- Some networking devices such as modems require special care, and this is
- what the services below focus on.
- @defvr {Scheme Variable} modem-manager-service-type
- This is the service type for the
- @uref{https://wiki.gnome.org/Projects/ModemManager, ModemManager}
- service. The value for this service type is a
- @code{modem-manager-configuration} record.
- This service is part of @code{%desktop-services} (@pxref{Desktop
- Services}).
- @end defvr
- @deftp {Data Type} modem-manager-configuration
- Data type representing the configuration of ModemManager.
- @table @asis
- @item @code{modem-manager} (default: @code{modem-manager})
- The ModemManager package to use.
- @end table
- @end deftp
- @cindex USB_ModeSwitch
- @cindex Modeswitching
- @defvr {Scheme Variable} usb-modeswitch-service-type
- This is the service type for the
- @uref{https://www.draisberghof.de/usb_modeswitch/, USB_ModeSwitch}
- service. The value for this service type is
- a @code{usb-modeswitch-configuration} record.
- When plugged in, some USB modems (and other USB devices) initially present
- themselves as a read-only storage medium and not as a modem. They need to be
- @dfn{modeswitched} before they are usable. The USB_ModeSwitch service type
- installs udev rules to automatically modeswitch these devices when they are
- plugged in.
- This service is part of @code{%desktop-services} (@pxref{Desktop
- Services}).
- @end defvr
- @deftp {Data Type} usb-modeswitch-configuration
- Data type representing the configuration of USB_ModeSwitch.
- @table @asis
- @item @code{usb-modeswitch} (default: @code{usb-modeswitch})
- The USB_ModeSwitch package providing the binaries for modeswitching.
- @item @code{usb-modeswitch-data} (default: @code{usb-modeswitch-data})
- The package providing the device data and udev rules file used by
- USB_ModeSwitch.
- @item @code{config-file} (default: @code{#~(string-append #$usb-modeswitch:dispatcher "/etc/usb_modeswitch.conf")})
- Which config file to use for the USB_ModeSwitch dispatcher. By default the
- config file shipped with USB_ModeSwitch is used which disables logging to
- @file{/var/log} among other default settings. If set to @code{#f}, no config
- file is used.
- @end table
- @end deftp
- @node Networking Services
- @subsection Networking Services
- The @code{(gnu services networking)} module discussed in the previous
- section provides services for more advanced setups: providing a DHCP
- service for others to use, filtering packets with iptables or nftables,
- running a WiFi access point with @command{hostapd}, running the
- @command{inetd} ``superdaemon'', and more. This section describes
- those.
- @deffn {Scheme Procedure} dhcpd-service-type
- This type defines a service that runs a DHCP daemon. To create a
- service of this type, you must supply a @code{<dhcpd-configuration>}.
- For example:
- @lisp
- (service dhcpd-service-type
- (dhcpd-configuration
- (config-file (local-file "my-dhcpd.conf"))
- (interfaces '("enp0s25"))))
- @end lisp
- @end deffn
- @deftp {Data Type} dhcpd-configuration
- @table @asis
- @item @code{package} (default: @code{isc-dhcp})
- The package that provides the DHCP daemon. This package is expected to
- provide the daemon at @file{sbin/dhcpd} relative to its output
- directory. The default package is the
- @uref{https://www.isc.org/products/DHCP, ISC's DHCP server}.
- @item @code{config-file} (default: @code{#f})
- The configuration file to use. This is required. It will be passed to
- @code{dhcpd} via its @code{-cf} option. This may be any ``file-like''
- object (@pxref{G-Expressions, file-like objects}). See @code{man
- dhcpd.conf} for details on the configuration file syntax.
- @item @code{version} (default: @code{"4"})
- The DHCP version to use. The ISC DHCP server supports the values ``4'',
- ``6'', and ``4o6''. These correspond to the @code{dhcpd} program
- options @code{-4}, @code{-6}, and @code{-4o6}. See @code{man dhcpd} for
- details.
- @item @code{run-directory} (default: @code{"/run/dhcpd"})
- The run directory to use. At service activation time, this directory
- will be created if it does not exist.
- @item @code{pid-file} (default: @code{"/run/dhcpd/dhcpd.pid"})
- The PID file to use. This corresponds to the @code{-pf} option of
- @code{dhcpd}. See @code{man dhcpd} for details.
- @item @code{interfaces} (default: @code{'()})
- The names of the network interfaces on which dhcpd should listen for
- broadcasts. If this list is not empty, then its elements (which must be
- strings) will be appended to the @code{dhcpd} invocation when starting
- the daemon. It may not be necessary to explicitly specify any
- interfaces here; see @code{man dhcpd} for details.
- @end table
- @end deftp
- @cindex hostapd service, for Wi-Fi access points
- @cindex Wi-Fi access points, hostapd service
- @defvr {Scheme Variable} hostapd-service-type
- This is the service type to run the @uref{https://w1.fi/hostapd/,
- hostapd} daemon to set up WiFi (IEEE 802.11) access points and
- authentication servers. Its associated value must be a
- @code{hostapd-configuration} as shown below:
- @lisp
- ;; Use wlan1 to run the access point for "My Network".
- (service hostapd-service-type
- (hostapd-configuration
- (interface "wlan1")
- (ssid "My Network")
- (channel 12)))
- @end lisp
- @end defvr
- @deftp {Data Type} hostapd-configuration
- This data type represents the configuration of the hostapd service, with
- the following fields:
- @table @asis
- @item @code{package} (default: @code{hostapd})
- The hostapd package to use.
- @item @code{interface} (default: @code{"wlan0"})
- The network interface to run the WiFi access point.
- @item @code{ssid}
- The SSID (@dfn{service set identifier}), a string that identifies this
- network.
- @item @code{broadcast-ssid?} (default: @code{#t})
- Whether to broadcast this SSID.
- @item @code{channel} (default: @code{1})
- The WiFi channel to use.
- @item @code{driver} (default: @code{"nl80211"})
- The driver interface type. @code{"nl80211"} is used with all Linux
- mac80211 drivers. Use @code{"none"} if building hostapd as a standalone
- RADIUS server that does # not control any wireless/wired driver.
- @item @code{extra-settings} (default: @code{""})
- Extra settings to append as-is to the hostapd configuration file. See
- @uref{https://w1.fi/cgit/hostap/plain/hostapd/hostapd.conf} for the
- configuration file reference.
- @end table
- @end deftp
- @defvr {Scheme Variable} simulated-wifi-service-type
- This is the type of a service to simulate WiFi networking, which can be
- useful in virtual machines for testing purposes. The service loads the
- Linux kernel
- @uref{https://www.kernel.org/doc/html/latest/networking/mac80211_hwsim/mac80211_hwsim.html,
- @code{mac80211_hwsim} module} and starts hostapd to create a pseudo WiFi
- network that can be seen on @code{wlan0}, by default.
- The service's value is a @code{hostapd-configuration} record.
- @end defvr
- @cindex iptables
- @defvr {Scheme Variable} iptables-service-type
- This is the service type to set up an iptables configuration. iptables is a
- packet filtering framework supported by the Linux kernel. This service
- supports configuring iptables for both IPv4 and IPv6. A simple example
- configuration rejecting all incoming connections except those to the ssh port
- 22 is shown below.
- @lisp
- (service iptables-service-type
- (iptables-configuration
- (ipv4-rules (plain-file "iptables.rules" "*filter
- :INPUT ACCEPT
- :FORWARD ACCEPT
- :OUTPUT ACCEPT
- -A INPUT -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT
- -A INPUT -p tcp --dport 22 -j ACCEPT
- -A INPUT -j REJECT --reject-with icmp-port-unreachable
- COMMIT
- "))
- (ipv6-rules (plain-file "ip6tables.rules" "*filter
- :INPUT ACCEPT
- :FORWARD ACCEPT
- :OUTPUT ACCEPT
- -A INPUT -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT
- -A INPUT -p tcp --dport 22 -j ACCEPT
- -A INPUT -j REJECT --reject-with icmp6-port-unreachable
- COMMIT
- "))))
- @end lisp
- @end defvr
- @deftp {Data Type} iptables-configuration
- The data type representing the configuration of iptables.
- @table @asis
- @item @code{iptables} (default: @code{iptables})
- The iptables package that provides @code{iptables-restore} and
- @code{ip6tables-restore}.
- @item @code{ipv4-rules} (default: @code{%iptables-accept-all-rules})
- The iptables rules to use. It will be passed to @code{iptables-restore}.
- This may be any ``file-like'' object (@pxref{G-Expressions, file-like
- objects}).
- @item @code{ipv6-rules} (default: @code{%iptables-accept-all-rules})
- The ip6tables rules to use. It will be passed to @code{ip6tables-restore}.
- This may be any ``file-like'' object (@pxref{G-Expressions, file-like
- objects}).
- @end table
- @end deftp
- @cindex nftables
- @defvr {Scheme Variable} nftables-service-type
- This is the service type to set up a nftables configuration. nftables is a
- netfilter project that aims to replace the existing iptables, ip6tables,
- arptables and ebtables framework. It provides a new packet filtering
- framework, a new user-space utility @command{nft}, and a compatibility layer
- for iptables. This service comes with a default ruleset
- @code{%default-nftables-ruleset} that rejecting all incoming connections
- except those to the ssh port 22. To use it, simply write:
- @lisp
- (service nftables-service-type)
- @end lisp
- @end defvr
- @deftp {Data Type} nftables-configuration
- The data type representing the configuration of nftables.
- @table @asis
- @item @code{package} (default: @code{nftables})
- The nftables package that provides @command{nft}.
- @item @code{ruleset} (default: @code{%default-nftables-ruleset})
- The nftables ruleset to use. This may be any ``file-like'' object
- (@pxref{G-Expressions, file-like objects}).
- @end table
- @end deftp
- @cindex NTP (Network Time Protocol), service
- @cindex ntpd, service for the Network Time Protocol daemon
- @cindex real time clock
- @defvr {Scheme Variable} ntp-service-type
- This is the type of the service running the @uref{https://www.ntp.org,
- Network Time Protocol (NTP)} daemon, @command{ntpd}. The daemon will keep the
- system clock synchronized with that of the specified NTP servers.
- The value of this service is an @code{ntpd-configuration} object, as described
- below.
- @end defvr
- @deftp {Data Type} ntp-configuration
- This is the data type for the NTP service configuration.
- @table @asis
- @item @code{servers} (default: @code{%ntp-servers})
- This is the list of servers (@code{<ntp-server>} records) with which
- @command{ntpd} will be synchronized. See the @code{ntp-server} data type
- definition below.
- @item @code{allow-large-adjustment?} (default: @code{#t})
- This determines whether @command{ntpd} is allowed to make an initial
- adjustment of more than 1,000 seconds.
- @item @code{ntp} (default: @code{ntp})
- The NTP package to use.
- @end table
- @end deftp
- @defvr {Scheme Variable} %ntp-servers
- List of host names used as the default NTP servers. These are servers of the
- @uref{https://www.ntppool.org/en/, NTP Pool Project}.
- @end defvr
- @deftp {Data Type} ntp-server
- The data type representing the configuration of a NTP server.
- @table @asis
- @item @code{type} (default: @code{'server})
- The type of the NTP server, given as a symbol. One of @code{'pool},
- @code{'server}, @code{'peer}, @code{'broadcast} or @code{'manycastclient}.
- @item @code{address}
- The address of the server, as a string.
- @item @code{options}
- NTPD options to use with that specific server, given as a list of option names
- and/or of option names and values tuples. The following example define a server
- to use with the options @option{iburst} and @option{prefer}, as well as
- @option{version} 3 and a @option{maxpoll} time of 16 seconds.
- @example
- (ntp-server
- (type 'server)
- (address "some.ntp.server.org")
- (options `(iburst (version 3) (maxpoll 16) prefer))))
- @end example
- @end table
- @end deftp
- @cindex OpenNTPD
- @deffn {Scheme Procedure} openntpd-service-type
- Run the @command{ntpd}, the Network Time Protocol (NTP) daemon, as implemented
- by @uref{http://www.openntpd.org, OpenNTPD}. The daemon will keep the system
- clock synchronized with that of the given servers.
- @lisp
- (service
- openntpd-service-type
- (openntpd-configuration
- (listen-on '("127.0.0.1" "::1"))
- (sensor '("udcf0 correction 70000"))
- (constraint-from '("www.gnu.org"))
- (constraints-from '("https://www.google.com/"))))
- @end lisp
- @end deffn
- @defvr {Scheme Variable} %openntpd-servers
- This variable is a list of the server addresses defined in
- @code{%ntp-servers}.
- @end defvr
- @deftp {Data Type} openntpd-configuration
- @table @asis
- @item @code{openntpd} (default: @code{(file-append openntpd "/sbin/ntpd")})
- The openntpd executable to use.
- @item @code{listen-on} (default: @code{'("127.0.0.1" "::1")})
- A list of local IP addresses or hostnames the ntpd daemon should listen on.
- @item @code{query-from} (default: @code{'()})
- A list of local IP address the ntpd daemon should use for outgoing queries.
- @item @code{sensor} (default: @code{'()})
- Specify a list of timedelta sensor devices ntpd should use. @code{ntpd}
- will listen to each sensor that actually exists and ignore non-existent ones.
- See @uref{https://man.openbsd.org/ntpd.conf, upstream documentation} for more
- information.
- @item @code{server} (default: @code{'()})
- Specify a list of IP addresses or hostnames of NTP servers to synchronize to.
- @item @code{servers} (default: @code{%openntp-servers})
- Specify a list of IP addresses or hostnames of NTP pools to synchronize to.
- @item @code{constraint-from} (default: @code{'()})
- @code{ntpd} can be configured to query the ‘Date’ from trusted HTTPS servers via TLS.
- This time information is not used for precision but acts as an authenticated
- constraint, thereby reducing the impact of unauthenticated NTP
- man-in-the-middle attacks.
- Specify a list of URLs, IP addresses or hostnames of HTTPS servers to provide
- a constraint.
- @item @code{constraints-from} (default: @code{'()})
- As with constraint from, specify a list of URLs, IP addresses or hostnames of
- HTTPS servers to provide a constraint. Should the hostname resolve to multiple
- IP addresses, @code{ntpd} will calculate a median constraint from all of them.
- @end table
- @end deftp
- @cindex inetd
- @deffn {Scheme variable} inetd-service-type
- This service runs the @command{inetd} (@pxref{inetd invocation,,,
- inetutils, GNU Inetutils}) daemon. @command{inetd} listens for
- connections on internet sockets, and lazily starts the specified server
- program when a connection is made on one of these sockets.
- The value of this service is an @code{inetd-configuration} object. The
- following example configures the @command{inetd} daemon to provide the
- built-in @command{echo} service, as well as an smtp service which
- forwards smtp traffic over ssh to a server @code{smtp-server} behind a
- gateway @code{hostname}:
- @lisp
- (service
- inetd-service-type
- (inetd-configuration
- (entries (list
- (inetd-entry
- (name "echo")
- (socket-type 'stream)
- (protocol "tcp")
- (wait? #f)
- (user "root"))
- (inetd-entry
- (node "127.0.0.1")
- (name "smtp")
- (socket-type 'stream)
- (protocol "tcp")
- (wait? #f)
- (user "root")
- (program (file-append openssh "/bin/ssh"))
- (arguments
- '("ssh" "-qT" "-i" "/path/to/ssh_key"
- "-W" "smtp-server:25" "user@@hostname")))))))
- @end lisp
- See below for more details about @code{inetd-configuration}.
- @end deffn
- @deftp {Data Type} inetd-configuration
- Data type representing the configuration of @command{inetd}.
- @table @asis
- @item @code{program} (default: @code{(file-append inetutils "/libexec/inetd")})
- The @command{inetd} executable to use.
- @item @code{entries} (default: @code{'()})
- A list of @command{inetd} service entries. Each entry should be created
- by the @code{inetd-entry} constructor.
- @end table
- @end deftp
- @deftp {Data Type} inetd-entry
- Data type representing an entry in the @command{inetd} configuration.
- Each entry corresponds to a socket where @command{inetd} will listen for
- requests.
- @table @asis
- @item @code{node} (default: @code{#f})
- Optional string, a comma-separated list of local addresses
- @command{inetd} should use when listening for this service.
- @xref{Configuration file,,, inetutils, GNU Inetutils} for a complete
- description of all options.
- @item @code{name}
- A string, the name must correspond to an entry in @code{/etc/services}.
- @item @code{socket-type}
- One of @code{'stream}, @code{'dgram}, @code{'raw}, @code{'rdm} or
- @code{'seqpacket}.
- @item @code{protocol}
- A string, must correspond to an entry in @code{/etc/protocols}.
- @item @code{wait?} (default: @code{#t})
- Whether @command{inetd} should wait for the server to exit before
- listening to new service requests.
- @item @code{user}
- A string containing the user (and, optionally, group) name of the user
- as whom the server should run. The group name can be specified in a
- suffix, separated by a colon or period, i.e.@: @code{"user"},
- @code{"user:group"} or @code{"user.group"}.
- @item @code{program} (default: @code{"internal"})
- The server program which will serve the requests, or @code{"internal"}
- if @command{inetd} should use a built-in service.
- @item @code{arguments} (default: @code{'()})
- A list strings or file-like objects, which are the server program's
- arguments, starting with the zeroth argument, i.e.@: the name of the
- program itself. For @command{inetd}'s internal services, this entry
- must be @code{'()} or @code{'("internal")}.
- @end table
- @xref{Configuration file,,, inetutils, GNU Inetutils} for a more
- detailed discussion of each configuration field.
- @end deftp
- @cindex opendht, distributed hash table network service
- @cindex dhtproxy, for use with jami
- @defvr {Scheme Variable} opendht-service-type
- This is the type of the service running a @uref{https://opendht.net,
- OpenDHT} node, @command{dhtnode}. The daemon can be used to host your
- own proxy service to the distributed hash table (DHT), for example to
- connect to with Jami, among other applications.
- @quotation Important
- When using the OpenDHT proxy server, the IP addresses it ``sees'' from
- the clients should be addresses reachable from other peers. In practice
- this means that a publicly reachable address is best suited for a proxy
- server, outside of your private network. For example, hosting the proxy
- server on a IPv4 private local network and exposing it via port
- forwarding could work for external peers, but peers local to the proxy
- would have their private addresses shared with the external peers,
- leading to connectivity problems.
- @end quotation
- The value of this service is a @code{opendht-configuration} object, as
- described below.
- @end defvr
- @deftp {Data Type} opendht-configuration
- This is the data type for the OpenDHT service configuration.
- @c The fields documentation has been auto-generated using the
- @c configuration->documentation procedure from
- @c (gnu services configuration).
- Available @code{opendht-configuration} fields are:
- @deftypevr {@code{opendht-configuration} parameter} package opendht
- The @code{opendht} package to use.
- @end deftypevr
- @deftypevr {@code{opendht-configuration} parameter} boolean peer-discovery?
- Whether to enable the multicast local peer discovery mechanism.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{opendht-configuration} parameter} boolean enable-logging?
- Whether to enable logging messages to syslog. It is disabled by default
- as it is rather verbose.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{opendht-configuration} parameter} boolean debug?
- Whether to enable debug-level logging messages. This has no effect if
- logging is disabled.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{opendht-configuration} parameter} maybe-string bootstrap-host
- The node host name that is used to make the first connection to the
- network. A specific port value can be provided by appending the
- @code{:PORT} suffix. By default, it uses the Jami bootstrap nodes, but
- any host can be specified here. It's also possible to disable
- bootsrapping by setting this to the @code{'disabled} symbol.
- Defaults to @samp{"bootstrap.jami.net:4222"}.
- @end deftypevr
- @deftypevr {@code{opendht-configuration} parameter} maybe-number port
- The UDP port to bind to. When set to @code{'disabled}, an available
- port is automatically selected.
- Defaults to @samp{4222}.
- @end deftypevr
- @deftypevr {@code{opendht-configuration} parameter} maybe-number proxy-server-port
- Spawn a proxy server listening on the specified port.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{opendht-configuration} parameter} maybe-number proxy-server-port-tls
- Spawn a proxy server listening to TLS connections on the specified port.
- Defaults to @samp{disabled}.
- @end deftypevr
- @end deftp
- @cindex Tor
- @defvr {Scheme Variable} tor-service-type
- This is the type for a service that runs the @uref{https://torproject.org,
- Tor} anonymous networking daemon. The service is configured using a
- @code{<tor-configuration>} record. By default, the Tor daemon runs as the
- @code{tor} unprivileged user, which is a member of the @code{tor} group.
- @end defvr
- @deftp {Data Type} tor-configuration
- @table @asis
- @item @code{tor} (default: @code{tor})
- The package that provides the Tor daemon. This package is expected to provide
- the daemon at @file{bin/tor} relative to its output directory. The default
- package is the @uref{https://www.torproject.org, Tor Project's}
- implementation.
- @item @code{config-file} (default: @code{(plain-file "empty" "")})
- The configuration file to use. It will be appended to a default configuration
- file, and the final configuration file will be passed to @code{tor} via its
- @code{-f} option. This may be any ``file-like'' object (@pxref{G-Expressions,
- file-like objects}). See @code{man tor} for details on the configuration file
- syntax.
- @item @code{hidden-services} (default: @code{'()})
- The list of @code{<hidden-service>} records to use. For any hidden service
- you include in this list, appropriate configuration to enable the hidden
- service will be automatically added to the default configuration file. You
- may conveniently create @code{<hidden-service>} records using the
- @code{tor-hidden-service} procedure described below.
- @item @code{socks-socket-type} (default: @code{'tcp})
- The default socket type that Tor should use for its SOCKS socket. This must
- be either @code{'tcp} or @code{'unix}. If it is @code{'tcp}, then by default
- Tor will listen on TCP port 9050 on the loopback interface (i.e., localhost).
- If it is @code{'unix}, then Tor will listen on the UNIX domain socket
- @file{/var/run/tor/socks-sock}, which will be made writable by members of the
- @code{tor} group.
- If you want to customize the SOCKS socket in more detail, leave
- @code{socks-socket-type} at its default value of @code{'tcp} and use
- @code{config-file} to override the default by providing your own
- @code{SocksPort} option.
- @item @code{control-socket?} (default: @code{#f})
- Whether or not to provide a ``control socket'' by which Tor can be
- controlled to, for instance, dynamically instantiate tor onion services.
- If @code{#t}, Tor will listen for control commands on the UNIX domain socket
- @file{/var/run/tor/control-sock}, which will be made writable by members of the
- @code{tor} group.
- @end table
- @end deftp
- @cindex hidden service
- @deffn {Scheme Procedure} tor-hidden-service @var{name} @var{mapping}
- Define a new Tor @dfn{hidden service} called @var{name} and implementing
- @var{mapping}. @var{mapping} is a list of port/host tuples, such as:
- @example
- '((22 "127.0.0.1:22")
- (80 "127.0.0.1:8080"))
- @end example
- In this example, port 22 of the hidden service is mapped to local port 22, and
- port 80 is mapped to local port 8080.
- This creates a @file{/var/lib/tor/hidden-services/@var{name}} directory, where
- the @file{hostname} file contains the @code{.onion} host name for the hidden
- service.
- See @uref{https://www.torproject.org/docs/tor-hidden-service.html.en, the Tor
- project's documentation} for more information.
- @end deffn
- The @code{(gnu services rsync)} module provides the following services:
- You might want an rsync daemon if you have files that you want available
- so anyone (or just yourself) can download existing files or upload new
- files.
- @deffn {Scheme Variable} rsync-service-type
- This is the service type for the @uref{https://rsync.samba.org, rsync} daemon,
- The value for this service type is a
- @command{rsync-configuration} record as in this example:
- @lisp
- ;; Export two directories over rsync. By default rsync listens on
- ;; all the network interfaces.
- (service rsync-service-type
- (rsync-configuration
- (modules (list (rsync-module
- (name "music")
- (file-name "/srv/zik")
- (read-only? #f))
- (rsync-module
- (name "movies")
- (file-name "/home/charlie/movies"))))))
- @end lisp
- See below for details about @code{rsync-configuration}.
- @end deffn
- @deftp {Data Type} rsync-configuration
- Data type representing the configuration for @code{rsync-service}.
- @table @asis
- @item @code{package} (default: @var{rsync})
- @code{rsync} package to use.
- @item @code{address} (default: @code{#f})
- IP address on which @command{rsync} listens for incoming connections.
- If unspecified, it defaults to listening on all available addresses.
- @item @code{port-number} (default: @code{873})
- TCP port on which @command{rsync} listens for incoming connections. If port
- is less than @code{1024} @command{rsync} needs to be started as the
- @code{root} user and group.
- @item @code{pid-file} (default: @code{"/var/run/rsyncd/rsyncd.pid"})
- Name of the file where @command{rsync} writes its PID.
- @item @code{lock-file} (default: @code{"/var/run/rsyncd/rsyncd.lock"})
- Name of the file where @command{rsync} writes its lock file.
- @item @code{log-file} (default: @code{"/var/log/rsyncd.log"})
- Name of the file where @command{rsync} writes its log file.
- @item @code{user} (default: @code{"root"})
- Owner of the @code{rsync} process.
- @item @code{group} (default: @code{"root"})
- Group of the @code{rsync} process.
- @item @code{uid} (default: @code{"rsyncd"})
- User name or user ID that file transfers to and from that module should take
- place as when the daemon was run as @code{root}.
- @item @code{gid} (default: @code{"rsyncd"})
- Group name or group ID that will be used when accessing the module.
- @item @code{modules} (default: @code{%default-modules})
- List of ``modules''---i.e., directories exported over rsync. Each
- element must be a @code{rsync-module} record, as described below.
- @end table
- @end deftp
- @deftp {Data Type} rsync-module
- This is the data type for rsync ``modules''. A module is a directory
- exported over the rsync protocol. The available fields are as follows:
- @table @asis
- @item @code{name}
- The module name. This is the name that shows up in URLs. For example,
- if the module is called @code{music}, the corresponding URL will be
- @code{rsync://host.example.org/music}.
- @item @code{file-name}
- Name of the directory being exported.
- @item @code{comment} (default: @code{""})
- Comment associated with the module. Client user interfaces may display
- it when they obtain the list of available modules.
- @item @code{read-only?} (default: @code{#t})
- Whether or not client will be able to upload files. If this is false,
- the uploads will be authorized if permissions on the daemon side permit
- it.
- @item @code{chroot?} (default: @code{#t})
- When this is true, the rsync daemon changes root to the module's
- directory before starting file transfers with the client. This improves
- security, but requires rsync to run as root.
- @item @code{timeout} (default: @code{300})
- Idle time in seconds after which the daemon closes a connection with the
- client.
- @end table
- @end deftp
- The @code{(gnu services syncthing)} module provides the following services:
- @cindex syncthing
- You might want a syncthing daemon if you have files between two or more
- computers and want to sync them in real time, safely protected from
- prying eyes.
- @deffn {Scheme Variable} syncthing-service-type
- This is the service type for the @uref{https://syncthing.net/,
- syncthing} daemon, The value for this service type is a
- @command{syncthing-configuration} record as in this example:
- @lisp
- (service syncthing-service-type
- (syncthing-configuration (user "alice")))
- @end lisp
- See below for details about @code{syncthing-configuration}.
- @deftp {Data Type} syncthing-configuration
- Data type representing the configuration for @code{syncthing-service-type}.
- @table @asis
- @item @code{syncthing} (default: @var{syncthing})
- @code{syncthing} package to use.
- @item @code{arguments} (default: @var{'()})
- List of command-line arguments passing to @code{syncthing} binary.
- @item @code{logflags} (default: @var{0})
- Sum of logging flags, see
- @uref{https://docs.syncthing.net/users/syncthing.html#cmdoption-logflags, Syncthing documentation logflags}.
- @item @code{user} (default: @var{#f})
- The user as which the Syncthing service is to be run.
- This assumes that the specified user exists.
- @item @code{group} (default: @var{"users"})
- The group as which the Syncthing service is to be run.
- This assumes that the specified group exists.
- @item @code{home} (default: @var{#f})
- Common configuration and data directory. The default configuration
- directory is @file{$HOME} of the specified Syncthing @code{user}.
- @end table
- @end deftp
- @end deffn
- Furthermore, @code{(gnu services ssh)} provides the following services.
- @cindex SSH
- @cindex SSH server
- @deffn {Scheme Procedure} lsh-service [#:host-key "/etc/lsh/host-key"] @
- [#:daemonic? #t] [#:interfaces '()] [#:port-number 22] @
- [#:allow-empty-passwords? #f] [#:root-login? #f] @
- [#:syslog-output? #t] [#:x11-forwarding? #t] @
- [#:tcp/ip-forwarding? #t] [#:password-authentication? #t] @
- [#:public-key-authentication? #t] [#:initialize? #t]
- Run the @command{lshd} program from @var{lsh} to listen on port @var{port-number}.
- @var{host-key} must designate a file containing the host key, and readable
- only by root.
- When @var{daemonic?} is true, @command{lshd} will detach from the
- controlling terminal and log its output to syslogd, unless one sets
- @var{syslog-output?} to false. Obviously, it also makes lsh-service
- depend on existence of syslogd service. When @var{pid-file?} is true,
- @command{lshd} writes its PID to the file called @var{pid-file}.
- When @var{initialize?} is true, automatically create the seed and host key
- upon service activation if they do not exist yet. This may take long and
- require interaction.
- When @var{initialize?} is false, it is up to the user to initialize the
- randomness generator (@pxref{lsh-make-seed,,, lsh, LSH Manual}), and to create
- a key pair with the private key stored in file @var{host-key} (@pxref{lshd
- basics,,, lsh, LSH Manual}).
- When @var{interfaces} is empty, lshd listens for connections on all the
- network interfaces; otherwise, @var{interfaces} must be a list of host names
- or addresses.
- @var{allow-empty-passwords?} specifies whether to accept log-ins with empty
- passwords, and @var{root-login?} specifies whether to accept log-ins as
- root.
- The other options should be self-descriptive.
- @end deffn
- @cindex SSH
- @cindex SSH server
- @deffn {Scheme Variable} openssh-service-type
- This is the type for the @uref{http://www.openssh.org, OpenSSH} secure
- shell daemon, @command{sshd}. Its value must be an
- @code{openssh-configuration} record as in this example:
- @lisp
- (service openssh-service-type
- (openssh-configuration
- (x11-forwarding? #t)
- (permit-root-login 'prohibit-password)
- (authorized-keys
- `(("alice" ,(local-file "alice.pub"))
- ("bob" ,(local-file "bob.pub"))))))
- @end lisp
- See below for details about @code{openssh-configuration}.
- This service can be extended with extra authorized keys, as in this
- example:
- @lisp
- (service-extension openssh-service-type
- (const `(("charlie"
- ,(local-file "charlie.pub")))))
- @end lisp
- @end deffn
- @deftp {Data Type} openssh-configuration
- This is the configuration record for OpenSSH's @command{sshd}.
- @table @asis
- @item @code{openssh} (default @var{openssh})
- The OpenSSH package to use.
- @item @code{pid-file} (default: @code{"/var/run/sshd.pid"})
- Name of the file where @command{sshd} writes its PID.
- @item @code{port-number} (default: @code{22})
- TCP port on which @command{sshd} listens for incoming connections.
- @item @code{max-connections} (default: @code{200})
- Hard limit on the maximum number of simultaneous client connections,
- enforced by the inetd-style Shepherd service (@pxref{Service De- and
- Constructors, @code{make-inetd-constructor},, shepherd, The GNU Shepherd
- Manual}).
- @item @code{permit-root-login} (default: @code{#f})
- This field determines whether and when to allow logins as root. If
- @code{#f}, root logins are disallowed; if @code{#t}, they are allowed.
- If it's the symbol @code{'prohibit-password}, then root logins are
- permitted but not with password-based authentication.
- @item @code{allow-empty-passwords?} (default: @code{#f})
- When true, users with empty passwords may log in. When false, they may
- not.
- @item @code{password-authentication?} (default: @code{#t})
- When true, users may log in with their password. When false, they have
- other authentication methods.
- @item @code{public-key-authentication?} (default: @code{#t})
- When true, users may log in using public key authentication. When
- false, users have to use other authentication method.
- Authorized public keys are stored in @file{~/.ssh/authorized_keys}.
- This is used only by protocol version 2.
- @item @code{x11-forwarding?} (default: @code{#f})
- When true, forwarding of X11 graphical client connections is
- enabled---in other words, @command{ssh} options @option{-X} and
- @option{-Y} will work.
- @item @code{allow-agent-forwarding?} (default: @code{#t})
- Whether to allow agent forwarding.
- @item @code{allow-tcp-forwarding?} (default: @code{#t})
- Whether to allow TCP forwarding.
- @item @code{gateway-ports?} (default: @code{#f})
- Whether to allow gateway ports.
- @item @code{challenge-response-authentication?} (default: @code{#f})
- Specifies whether challenge response authentication is allowed (e.g.@: via
- PAM).
- @item @code{use-pam?} (default: @code{#t})
- Enables the Pluggable Authentication Module interface. If set to
- @code{#t}, this will enable PAM authentication using
- @code{challenge-response-authentication?} and
- @code{password-authentication?}, in addition to PAM account and session
- module processing for all authentication types.
- Because PAM challenge response authentication usually serves an
- equivalent role to password authentication, you should disable either
- @code{challenge-response-authentication?} or
- @code{password-authentication?}.
- @item @code{print-last-log?} (default: @code{#t})
- Specifies whether @command{sshd} should print the date and time of the
- last user login when a user logs in interactively.
- @item @code{subsystems} (default: @code{'(("sftp" "internal-sftp"))})
- Configures external subsystems (e.g.@: file transfer daemon).
- This is a list of two-element lists, each of which containing the
- subsystem name and a command (with optional arguments) to execute upon
- subsystem request.
- The command @command{internal-sftp} implements an in-process SFTP
- server. Alternatively, one can specify the @command{sftp-server} command:
- @lisp
- (service openssh-service-type
- (openssh-configuration
- (subsystems
- `(("sftp" ,(file-append openssh "/libexec/sftp-server"))))))
- @end lisp
- @item @code{accepted-environment} (default: @code{'()})
- List of strings describing which environment variables may be exported.
- Each string gets on its own line. See the @code{AcceptEnv} option in
- @code{man sshd_config}.
- This example allows ssh-clients to export the @env{COLORTERM} variable.
- It is set by terminal emulators, which support colors. You can use it in
- your shell's resource file to enable colors for the prompt and commands
- if this variable is set.
- @lisp
- (service openssh-service-type
- (openssh-configuration
- (accepted-environment '("COLORTERM"))))
- @end lisp
- @item @code{authorized-keys} (default: @code{'()})
- @cindex authorized keys, SSH
- @cindex SSH authorized keys
- This is the list of authorized keys. Each element of the list is a user
- name followed by one or more file-like objects that represent SSH public
- keys. For example:
- @lisp
- (openssh-configuration
- (authorized-keys
- `(("rekado" ,(local-file "rekado.pub"))
- ("chris" ,(local-file "chris.pub"))
- ("root" ,(local-file "rekado.pub") ,(local-file "chris.pub")))))
- @end lisp
- @noindent
- registers the specified public keys for user accounts @code{rekado},
- @code{chris}, and @code{root}.
- Additional authorized keys can be specified @i{via}
- @code{service-extension}.
- Note that this does @emph{not} interfere with the use of
- @file{~/.ssh/authorized_keys}.
- @item @code{generate-host-keys?} (default: @code{#t})
- Whether to generate host key pairs with @command{ssh-keygen -A} under
- @file{/etc/ssh} if there are none.
- Generating key pairs takes a few seconds when enough entropy is
- available and is only done once. You might want to turn it off for
- instance in a virtual machine that does not need it because host keys
- are provided in some other way, and where the extra boot time is a
- problem.
- @item @code{log-level} (default: @code{'info})
- This is a symbol specifying the logging level: @code{quiet}, @code{fatal},
- @code{error}, @code{info}, @code{verbose}, @code{debug}, etc. See the man
- page for @file{sshd_config} for the full list of level names.
- @item @code{extra-content} (default: @code{""})
- This field can be used to append arbitrary text to the configuration file. It
- is especially useful for elaborate configurations that cannot be expressed
- otherwise. This configuration, for example, would generally disable root
- logins, but permit them from one specific IP address:
- @lisp
- (openssh-configuration
- (extra-content "\
- Match Address 192.168.0.1
- PermitRootLogin yes"))
- @end lisp
- @end table
- @end deftp
- @deffn {Scheme Procedure} dropbear-service [@var{config}]
- Run the @uref{https://matt.ucc.asn.au/dropbear/dropbear.html,Dropbear SSH
- daemon} with the given @var{config}, a @code{<dropbear-configuration>}
- object.
- For example, to specify a Dropbear service listening on port 1234, add
- this call to the operating system's @code{services} field:
- @lisp
- (dropbear-service (dropbear-configuration
- (port-number 1234)))
- @end lisp
- @end deffn
- @deftp {Data Type} dropbear-configuration
- This data type represents the configuration of a Dropbear SSH daemon.
- @table @asis
- @item @code{dropbear} (default: @var{dropbear})
- The Dropbear package to use.
- @item @code{port-number} (default: 22)
- The TCP port where the daemon waits for incoming connections.
- @item @code{syslog-output?} (default: @code{#t})
- Whether to enable syslog output.
- @item @code{pid-file} (default: @code{"/var/run/dropbear.pid"})
- File name of the daemon's PID file.
- @item @code{root-login?} (default: @code{#f})
- Whether to allow @code{root} logins.
- @item @code{allow-empty-passwords?} (default: @code{#f})
- Whether to allow empty passwords.
- @item @code{password-authentication?} (default: @code{#t})
- Whether to enable password-based authentication.
- @end table
- @end deftp
- @cindex AutoSSH
- @deffn {Scheme Variable} autossh-service-type
- This is the type for the @uref{https://www.harding.motd.ca/autossh,
- AutoSSH} program that runs a copy of @command{ssh} and monitors it,
- restarting it as necessary should it die or stop passing traffic.
- AutoSSH can be run manually from the command-line by passing arguments
- to the binary @command{autossh} from the package @code{autossh}, but it
- can also be run as a Guix service. This latter use case is documented
- here.
- AutoSSH can be used to forward local traffic to a remote machine using
- an SSH tunnel, and it respects the @file{~/.ssh/config} of the user it
- is run as.
- For example, to specify a service running autossh as the user
- @code{pino} and forwarding all local connections to port @code{8081} to
- @code{remote:8081} using an SSH tunnel, add this call to the operating
- system's @code{services} field:
- @lisp
- (service autossh-service-type
- (autossh-configuration
- (user "pino")
- (ssh-options (list "-T" "-N" "-L" "8081:localhost:8081" "remote.net"))))
- @end lisp
- @end deffn
- @deftp {Data Type} autossh-configuration
- This data type represents the configuration of an AutoSSH service.
- @table @asis
- @item @code{user} (default @code{"autossh"})
- The user as which the AutoSSH service is to be run.
- This assumes that the specified user exists.
- @item @code{poll} (default @code{600})
- Specifies the connection poll time in seconds.
- @item @code{first-poll} (default @code{#f})
- Specifies how many seconds AutoSSH waits before the first connection
- test. After this first test, polling is resumed at the pace defined in
- @code{poll}. When set to @code{#f}, the first poll is not treated
- specially and will also use the connection poll specified in
- @code{poll}.
- @item @code{gate-time} (default @code{30})
- Specifies how many seconds an SSH connection must be active before it is
- considered successful.
- @item @code{log-level} (default @code{1})
- The log level, corresponding to the levels used by syslog---so @code{0}
- is the most silent while @code{7} is the chattiest.
- @item @code{max-start} (default @code{#f})
- The maximum number of times SSH may be (re)started before AutoSSH exits.
- When set to @code{#f}, no maximum is configured and AutoSSH may restart indefinitely.
- @item @code{message} (default @code{""})
- The message to append to the echo message sent when testing connections.
- @item @code{port} (default @code{"0"})
- The ports used for monitoring the connection. When set to @code{"0"},
- monitoring is disabled. When set to @code{"@var{n}"} where @var{n} is
- a positive integer, ports @var{n} and @var{n}+1 are used for
- monitoring the connection, such that port @var{n} is the base
- monitoring port and @code{n+1} is the echo port. When set to
- @code{"@var{n}:@var{m}"} where @var{n} and @var{m} are positive
- integers, the ports @var{n} and @var{m} are used for monitoring the
- connection, such that port @var{n} is the base monitoring port and
- @var{m} is the echo port.
- @item @code{ssh-options} (default @code{'()})
- The list of command-line arguments to pass to @command{ssh} when it is
- run. Options @option{-f} and @option{-M} are reserved for AutoSSH and
- may cause undefined behaviour.
- @end table
- @end deftp
- @cindex WebSSH
- @deffn {Scheme Variable} webssh-service-type
- This is the type for the @uref{https://webssh.huashengdun.org/, WebSSH}
- program that runs a web SSH client. WebSSH can be run manually from the
- command-line by passing arguments to the binary @command{wssh} from the
- package @code{webssh}, but it can also be run as a Guix service. This
- latter use case is documented here.
- For example, to specify a service running WebSSH on loopback interface
- on port @code{8888} with reject policy with a list of allowed to
- connection hosts, and NGINX as a reverse-proxy to this service listening
- for HTTPS connection, add this call to the operating system's
- @code{services} field:
- @lisp
- (service webssh-service-type
- (webssh-configuration (address "127.0.0.1")
- (port 8888)
- (policy 'reject)
- (known-hosts '("localhost ecdsa-sha2-nistp256 AAAA…"
- "127.0.0.1 ecdsa-sha2-nistp256 AAAA…"))))
- (service nginx-service-type
- (nginx-configuration
- (server-blocks
- (list
- (nginx-server-configuration
- (inherit %webssh-configuration-nginx)
- (server-name '("webssh.example.com"))
- (listen '("443 ssl"))
- (ssl-certificate (letsencrypt-certificate "webssh.example.com"))
- (ssl-certificate-key (letsencrypt-key "webssh.example.com"))
- (locations
- (cons (nginx-location-configuration
- (uri "/.well-known")
- (body '("root /var/www;")))
- (nginx-server-configuration-locations %webssh-configuration-nginx))))))))
- @end lisp
- @end deffn
- @deftp {Data Type} webssh-configuration
- Data type representing the configuration for @code{webssh-service}.
- @table @asis
- @item @code{package} (default: @var{webssh})
- @code{webssh} package to use.
- @item @code{user-name} (default: @var{"webssh"})
- User name or user ID that file transfers to and from that module should take
- place.
- @item @code{group-name} (default: @var{"webssh"})
- Group name or group ID that will be used when accessing the module.
- @item @code{address} (default: @var{#f})
- IP address on which @command{webssh} listens for incoming connections.
- @item @code{port} (default: @var{8888})
- TCP port on which @command{webssh} listens for incoming connections.
- @item @code{policy} (default: @var{#f})
- Connection policy. @var{reject} policy requires to specify @var{known-hosts}.
- @item @code{known-hosts} (default: @var{'()})
- List of hosts which allowed for SSH connection from @command{webssh}.
- @item @code{log-file} (default: @file{"/var/log/webssh.log"})
- Name of the file where @command{webssh} writes its log file.
- @item @code{log-level} (default: @var{#f})
- Logging level.
- @end table
- @end deftp
- @defvr {Scheme Variable} %facebook-host-aliases
- This variable contains a string for use in @file{/etc/hosts}
- (@pxref{Host Names,,, libc, The GNU C Library Reference Manual}). Each
- line contains a entry that maps a known server name of the Facebook
- on-line service---e.g., @code{www.facebook.com}---to the local
- host---@code{127.0.0.1} or its IPv6 equivalent, @code{::1}.
- This variable is typically used in the @code{hosts-file} field of an
- @code{operating-system} declaration (@pxref{operating-system Reference,
- @file{/etc/hosts}}):
- @lisp
- (use-modules (gnu) (guix))
- (operating-system
- (host-name "mymachine")
- ;; ...
- (hosts-file
- ;; Create a /etc/hosts file with aliases for "localhost"
- ;; and "mymachine", as well as for Facebook servers.
- (plain-file "hosts"
- (string-append (local-host-aliases host-name)
- %facebook-host-aliases))))
- @end lisp
- This mechanism can prevent programs running locally, such as Web
- browsers, from accessing Facebook.
- @end defvr
- The @code{(gnu services avahi)} provides the following definition.
- @defvr {Scheme Variable} avahi-service-type
- This is the service that runs @command{avahi-daemon}, a system-wide
- mDNS/DNS-SD responder that allows for service discovery and
- ``zero-configuration'' host name lookups (see @uref{https://avahi.org/}).
- Its value must be an @code{avahi-configuration} record---see below.
- This service extends the name service cache daemon (nscd) so that it can
- resolve @code{.local} host names using
- @uref{https://0pointer.de/lennart/projects/nss-mdns/, nss-mdns}. @xref{Name
- Service Switch}, for information on host name resolution.
- Additionally, add the @var{avahi} package to the system profile so that
- commands such as @command{avahi-browse} are directly usable.
- @end defvr
- @deftp {Data Type} avahi-configuration
- Data type representation the configuration for Avahi.
- @table @asis
- @item @code{host-name} (default: @code{#f})
- If different from @code{#f}, use that as the host name to
- publish for this machine; otherwise, use the machine's actual host name.
- @item @code{publish?} (default: @code{#t})
- When true, allow host names and services to be published (broadcast) over the
- network.
- @item @code{publish-workstation?} (default: @code{#t})
- When true, @command{avahi-daemon} publishes the machine's host name and IP
- address via mDNS on the local network. To view the host names published on
- your local network, you can run:
- @example
- avahi-browse _workstation._tcp
- @end example
- @item @code{wide-area?} (default: @code{#f})
- When true, DNS-SD over unicast DNS is enabled.
- @item @code{ipv4?} (default: @code{#t})
- @itemx @code{ipv6?} (default: @code{#t})
- These fields determine whether to use IPv4/IPv6 sockets.
- @item @code{domains-to-browse} (default: @code{'()})
- This is a list of domains to browse.
- @end table
- @end deftp
- @deffn {Scheme Variable} openvswitch-service-type
- This is the type of the @uref{https://www.openvswitch.org, Open vSwitch}
- service, whose value should be an @code{openvswitch-configuration}
- object.
- @end deffn
- @deftp {Data Type} openvswitch-configuration
- Data type representing the configuration of Open vSwitch, a multilayer
- virtual switch which is designed to enable massive network automation
- through programmatic extension.
- @table @asis
- @item @code{package} (default: @var{openvswitch})
- Package object of the Open vSwitch.
- @end table
- @end deftp
- @defvr {Scheme Variable} pagekite-service-type
- This is the service type for the @uref{https://pagekite.net, PageKite} service,
- a tunneling solution for making localhost servers publicly visible, even from
- behind restrictive firewalls or NAT without forwarded ports. The value for
- this service type is a @code{pagekite-configuration} record.
- Here's an example exposing the local HTTP and SSH daemons:
- @lisp
- (service pagekite-service-type
- (pagekite-configuration
- (kites '("http:@@kitename:localhost:80:@@kitesecret"
- "raw/22:@@kitename:localhost:22:@@kitesecret"))
- (extra-file "/etc/pagekite.rc")))
- @end lisp
- @end defvr
- @deftp {Data Type} pagekite-configuration
- Data type representing the configuration of PageKite.
- @table @asis
- @item @code{package} (default: @var{pagekite})
- Package object of PageKite.
- @item @code{kitename} (default: @code{#f})
- PageKite name for authenticating to the frontend server.
- @item @code{kitesecret} (default: @code{#f})
- Shared secret for authenticating to the frontend server. You should probably
- put this inside @code{extra-file} instead.
- @item @code{frontend} (default: @code{#f})
- Connect to the named PageKite frontend server instead of the
- @uref{https://pagekite.net,,pagekite.net} service.
- @item @code{kites} (default: @code{'("http:@@kitename:localhost:80:@@kitesecret")})
- List of service kites to use. Exposes HTTP on port 80 by default. The format
- is @code{proto:kitename:host:port:secret}.
- @item @code{extra-file} (default: @code{#f})
- Extra configuration file to read, which you are expected to create manually.
- Use this to add additional options and manage shared secrets out-of-band.
- @end table
- @end deftp
- @defvr {Scheme Variable} yggdrasil-service-type
- The service type for connecting to the @uref{https://yggdrasil-network.github.io/,
- Yggdrasil network}, an early-stage implementation of a fully end-to-end
- encrypted IPv6 network.
- @quotation
- Yggdrasil provides name-independent routing with cryptographically generated
- addresses. Static addressing means you can keep the same address as long as
- you want, even if you move to a new location, or generate a new address (by
- generating new keys) whenever you want.
- @uref{https://yggdrasil-network.github.io/2018/07/28/addressing.html}
- @end quotation
- Pass it a value of @code{yggdrasil-configuration} to connect it to public
- peers and/or local peers.
- Here is an example using public peers and a static address. The static
- signing and encryption keys are defined in @file{/etc/yggdrasil-private.conf}
- (the default value for @code{config-file}).
- @lisp
- ;; part of the operating-system declaration
- (service yggdrasil-service-type
- (yggdrasil-configuration
- (autoconf? #f) ;; use only the public peers
- (json-config
- ;; choose one from
- ;; https://github.com/yggdrasil-network/public-peers
- '((peers . #("tcp://1.2.3.4:1337"))))
- ;; /etc/yggdrasil-private.conf is the default value for config-file
- ))
- @end lisp
- @example
- # sample content for /etc/yggdrasil-private.conf
- @{
- # Your public key. Your peers may ask you for this to put
- # into their AllowedPublicKeys configuration.
- PublicKey: 64277...
- # Your private key. DO NOT share this with anyone!
- PrivateKey: 5c750...
- @}
- @end example
- @end defvr
- @deftp {Data Type} yggdrasil-configuration
- Data type representing the configuration of Yggdrasil.
- @table @asis
- @item @code{package} (default: @code{yggdrasil})
- Package object of Yggdrasil.
- @item @code{json-config} (default: @code{'()})
- Contents of @file{/etc/yggdrasil.conf}. Will be merged with
- @file{/etc/yggdrasil-private.conf}. Note that these settings are stored in
- the Guix store, which is readable to all users. @strong{Do not store your
- private keys in it}. See the output of @code{yggdrasil -genconf} for a
- quick overview of valid keys and their default values.
- @item @code{autoconf?} (default: @code{#f})
- Whether to use automatic mode. Enabling it makes Yggdrasil use adynamic IP
- and peer with IPv6 neighbors.
- @item @code{log-level} (default: @code{'info})
- How much detail to include in logs. Use @code{'debug} for more detail.
- @item @code{log-to} (default: @code{'stdout})
- Where to send logs. By default, the service logs standard output to
- @file{/var/log/yggdrasil.log}. The alternative is @code{'syslog}, which
- sends output to the running syslog service.
- @item @code{config-file} (default: @code{"/etc/yggdrasil-private.conf"})
- What HJSON file to load sensitive data from. This is where private keys
- should be stored, which are necessary to specify if you don't want a
- randomized address after each restart. Use @code{#f} to disable. Options
- defined in this file take precedence over @code{json-config}. Use the output
- of @code{yggdrasil -genconf} as a starting point. To configure a static
- address, delete everything except these options:
- @itemize
- @item @code{EncryptionPublicKey}
- @item @code{EncryptionPrivateKey}
- @item @code{SigningPublicKey}
- @item @code{SigningPrivateKey}
- @end itemize
- @end table
- @end deftp
- @cindex IPFS
- @defvr {Scheme Variable} ipfs-service-type
- The service type for connecting to the @uref{https://ipfs.io,IPFS network},
- a global, versioned, peer-to-peer file system. Pass it a
- @code{ipfs-configuration} to change the ports used for the gateway and API.
- Here's an example configuration, using some non-standard ports:
- @lisp
- (service ipfs-service-type
- (ipfs-configuration
- (gateway "/ip4/127.0.0.1/tcp/8880")
- (api "/ip4/127.0.0.1/tcp/8881")))
- @end lisp
- @end defvr
- @deftp {Data Type} ipfs-configuration
- Data type representing the configuration of IPFS.
- @table @asis
- @item @code{package} (default: @code{go-ipfs})
- Package object of IPFS.
- @item @code{gateway} (default: @code{"/ip4/127.0.0.1/tcp/8082"})
- Address of the gateway, in ‘multiaddress’ format.
- @item @code{api} (default: @code{"/ip4/127.0.0.1/tcp/5001"})
- Address of the API endpoint, in ‘multiaddress’ format.
- @end table
- @end deftp
- @cindex keepalived
- @deffn {Scheme Variable} keepalived-service-type
- This is the type for the @uref{https://www.keepalived.org/, Keepalived}
- routing software, @command{keepalived}. Its value must be an
- @code{keepalived-configuration} record as in this example for master
- machine:
- @lisp
- (service keepalived-service-type
- (keepalived-configuration
- (config-file (local-file "keepalived-master.conf"))))
- @end lisp
- where @file{keepalived-master.conf}:
- @example
- vrrp_instance my-group @{
- state MASTER
- interface enp9s0
- virtual_router_id 100
- priority 100
- unicast_peer @{ 10.0.0.2 @}
- virtual_ipaddress @{
- 10.0.0.4/24
- @}
- @}
- @end example
- and for backup machine:
- @lisp
- (service keepalived-service-type
- (keepalived-configuration
- (config-file (local-file "keepalived-backup.conf"))))
- @end lisp
- where @file{keepalived-backup.conf}:
- @example
- vrrp_instance my-group @{
- state BACKUP
- interface enp9s0
- virtual_router_id 100
- priority 99
- unicast_peer @{ 10.0.0.3 @}
- virtual_ipaddress @{
- 10.0.0.4/24
- @}
- @}
- @end example
- @end deffn
- @node Unattended Upgrades
- @subsection Unattended Upgrades
- @cindex unattended upgrades
- @cindex upgrades, unattended
- Guix provides a service to perform @emph{unattended upgrades}:
- periodically, the system automatically reconfigures itself from the
- latest Guix. Guix System has several properties that make unattended
- upgrades safe:
- @itemize
- @item
- upgrades are transactional (either the upgrade succeeds or it fails, but
- you cannot end up with an ``in-between'' system state);
- @item
- the upgrade log is kept---you can view it with @command{guix system
- list-generations}---and you can roll back to any previous generation,
- should the upgraded system fail to behave as intended;
- @item
- channel code is authenticated so you know you can only run genuine code
- (@pxref{Channels});
- @item
- @command{guix system reconfigure} prevents downgrades, which makes it
- immune to @dfn{downgrade attacks}.
- @end itemize
- To set up unattended upgrades, add an instance of
- @code{unattended-upgrade-service-type} like the one below to the list of
- your operating system services:
- @lisp
- (service unattended-upgrade-service-type)
- @end lisp
- The defaults above set up weekly upgrades: every Sunday at midnight.
- You do not need to provide the operating system configuration file: it
- uses @file{/run/current-system/configuration.scm}, which ensures it
- always uses your latest configuration---@pxref{provenance-service-type},
- for more information about this file.
- There are several things that can be configured, in particular the
- periodicity and services (daemons) to be restarted upon completion.
- When the upgrade is successful, the service takes care of deleting
- system generations older that some threshold, as per @command{guix
- system delete-generations}. See the reference below for details.
- To ensure that upgrades are actually happening, you can run
- @command{guix system describe}. To investigate upgrade failures, visit
- the unattended upgrade log file (see below).
- @defvr {Scheme Variable} unattended-upgrade-service-type
- This is the service type for unattended upgrades. It sets up an mcron
- job (@pxref{Scheduled Job Execution}) that runs @command{guix system
- reconfigure} from the latest version of the specified channels.
- Its value must be a @code{unattended-upgrade-configuration} record (see
- below).
- @end defvr
- @deftp {Data Type} unattended-upgrade-configuration
- This data type represents the configuration of the unattended upgrade
- service. The following fields are available:
- @table @asis
- @item @code{schedule} (default: @code{"30 01 * * 0"})
- This is the schedule of upgrades, expressed as a gexp containing an
- mcron job schedule (@pxref{Guile Syntax, mcron job specifications,,
- mcron, GNU@tie{}mcron}).
- @item @code{channels} (default: @code{#~%default-channels})
- This gexp specifies the channels to use for the upgrade
- (@pxref{Channels}). By default, the tip of the official @code{guix}
- channel is used.
- @item @code{operating-system-file} (default: @code{"/run/current-system/configuration.scm"})
- This field specifies the operating system configuration file to use.
- The default is to reuse the config file of the current configuration.
- There are cases, though, where referring to
- @file{/run/current-system/configuration.scm} is not enough, for instance
- because that file refers to extra files (SSH public keys, extra
- configuration files, etc.) @i{via} @code{local-file} and similar
- constructs. For those cases, we recommend something along these lines:
- @lisp
- (unattended-upgrade-configuration
- (operating-system-file
- (file-append (local-file "." "config-dir" #:recursive? #t)
- "/config.scm")))
- @end lisp
- The effect here is to import all of the current directory into the
- store, and to refer to @file{config.scm} within that directory.
- Therefore, uses of @code{local-file} within @file{config.scm} will work
- as expected. @xref{G-Expressions}, for information about
- @code{local-file} and @code{file-append}.
- @item @code{services-to-restart} (default: @code{'(mcron)})
- This field specifies the Shepherd services to restart when the upgrade
- completes.
- Those services are restarted right away upon completion, as with
- @command{herd restart}, which ensures that the latest version is
- running---remember that by default @command{guix system reconfigure}
- only restarts services that are not currently running, which is
- conservative: it minimizes disruption but leaves outdated services
- running.
- Use @command{herd status} to find out candidates for restarting.
- @xref{Services}, for general information about services. Common
- services to restart would include @code{ntpd} and @code{ssh-daemon}.
- By default, the @code{mcron} service is restarted. This ensures that
- the latest version of the unattended upgrade job will be used next time.
- @item @code{system-expiration} (default: @code{(* 3 30 24 3600)})
- This is the expiration time in seconds for system generations. System
- generations older that this amount of time are deleted with
- @command{guix system delete-generations} when an upgrade completes.
- @quotation Note
- The unattended upgrade service does not run the garbage collector. You
- will probably want to set up your own mcron job to run @command{guix gc}
- periodically.
- @end quotation
- @item @code{maximum-duration} (default: @code{3600})
- Maximum duration in seconds for the upgrade; past that time, the upgrade
- aborts.
- This is primarily useful to ensure the upgrade does not end up
- rebuilding or re-downloading ``the world''.
- @item @code{log-file} (default: @code{"/var/log/unattended-upgrade.log"})
- File where unattended upgrades are logged.
- @end table
- @end deftp
- @node X Window
- @subsection X Window
- @cindex X11
- @cindex X Window System
- @cindex login manager
- Support for the X Window graphical display system---specifically
- Xorg---is provided by the @code{(gnu services xorg)} module. Note that
- there is no @code{xorg-service} procedure. Instead, the X server is
- started by the @dfn{login manager}, by default the GNOME Display Manager (GDM).
- @cindex GDM
- @cindex GNOME, login manager
- GDM of course allows users to log in into window managers and desktop
- environments other than GNOME; for those using GNOME, GDM is required for
- features such as automatic screen locking.
- @cindex window manager
- To use X11, you must install at least one @dfn{window manager}---for
- example the @code{windowmaker} or @code{openbox} packages---preferably
- by adding it to the @code{packages} field of your operating system
- definition (@pxref{operating-system Reference, system-wide packages}).
- @anchor{wayland-gdm}
- GDM also supports Wayland: it can itself use Wayland instead of X11 for
- its user interface, and it can also start Wayland sessions. The former is
- required for the latter, to enable, set @code{wayland?} to @code{#t} in
- @code{gdm-configuration}.
- @defvr {Scheme Variable} gdm-service-type
- This is the type for the @uref{https://wiki.gnome.org/Projects/GDM/, GNOME
- Desktop Manager} (GDM), a program that manages graphical display servers and
- handles graphical user logins. Its value must be a @code{gdm-configuration}
- (see below).
- @cindex session types
- GDM looks for @dfn{session types} described by the @file{.desktop} files in
- @file{/run/current-system/profile/share/xsessions} (for X11 sessions) and
- @file{/run/current-system/profile/share/wayland-sessions} (for Wayland
- sessions) and allows users to choose a session from the log-in screen.
- Packages such as @code{gnome}, @code{xfce}, @code{i3} and @code{sway} provide
- @file{.desktop} files; adding them to the system-wide set of packages
- automatically makes them available at the log-in screen.
- In addition, @file{~/.xsession} files are honored. When available,
- @file{~/.xsession} must be an executable that starts a window manager
- and/or other X clients.
- @end defvr
- @deftp {Data Type} gdm-configuration
- @table @asis
- @item @code{auto-login?} (default: @code{#f})
- @itemx @code{default-user} (default: @code{#f})
- When @code{auto-login?} is false, GDM presents a log-in screen.
- When @code{auto-login?} is true, GDM logs in directly as
- @code{default-user}.
- @item @code{debug?} (default: @code{#f})
- When true, GDM writes debug messages to its log.
- @item @code{gnome-shell-assets} (default: ...)
- List of GNOME Shell assets needed by GDM: icon theme, fonts, etc.
- @item @code{xorg-configuration} (default: @code{(xorg-configuration)})
- Configuration of the Xorg graphical server.
- @item @code{xsession} (default: @code{(xinitrc)})
- Script to run before starting a X session.
- @item @code{dbus-daemon} (default: @code{dbus-daemon-wrapper})
- File name of the @code{dbus-daemon} executable.
- @item @code{gdm} (default: @code{gdm})
- The GDM package to use.
- @item @code{wayland?} (default: @code{#f})
- When true, enables Wayland in GDM, necessary to use Wayland sessions.
- @item @code{wayland-session} (default: @code{gdm-wayland-session-wrapper})
- The Wayland session wrapper to use, needed to setup the
- environment.
- @end table
- @end deftp
- @defvr {Scheme Variable} slim-service-type
- This is the type for the SLiM graphical login manager for X11.
- Like GDM, SLiM looks for session types described by @file{.desktop} files and
- allows users to choose a session from the log-in screen using @kbd{F1}. It
- also honors @file{~/.xsession} files.
- Unlike GDM, SLiM does not spawn the user session on a different VT after
- logging in, which means that you can only start one graphical session. If you
- want to be able to run multiple graphical sessions at the same time you have
- to add multiple SLiM services to your system services. The following example
- shows how to replace the default GDM service with two SLiM services on tty7
- and tty8.
- @lisp
- (use-modules (gnu services)
- (gnu services desktop)
- (gnu services xorg))
- (operating-system
- ;; ...
- (services (cons* (service slim-service-type (slim-configuration
- (display ":0")
- (vt "vt7")))
- (service slim-service-type (slim-configuration
- (display ":1")
- (vt "vt8")))
- (modify-services %desktop-services
- (delete gdm-service-type)))))
- @end lisp
- @end defvr
- @deftp {Data Type} slim-configuration
- Data type representing the configuration of @code{slim-service-type}.
- @table @asis
- @item @code{allow-empty-passwords?} (default: @code{#t})
- Whether to allow logins with empty passwords.
- @item @code{gnupg?} (default: @code{#f})
- If enabled, @code{pam-gnupg} will attempt to automatically unlock the
- user's GPG keys with the login password via @code{gpg-agent}. The
- keygrips of all keys to be unlocked should be written to
- @file{~/.pam-gnupg}, and can be queried with @code{gpg -K
- --with-keygrip}. Presetting passphrases must be enabled by adding
- @code{allow-preset-passphrase} in @file{~/.gnupg/gpg-agent.conf}.
- @item @code{auto-login?} (default: @code{#f})
- @itemx @code{default-user} (default: @code{""})
- When @code{auto-login?} is false, SLiM presents a log-in screen.
- When @code{auto-login?} is true, SLiM logs in directly as
- @code{default-user}.
- @item @code{theme} (default: @code{%default-slim-theme})
- @itemx @code{theme-name} (default: @code{%default-slim-theme-name})
- The graphical theme to use and its name.
- @item @code{auto-login-session} (default: @code{#f})
- If true, this must be the name of the executable to start as the default
- session---e.g., @code{(file-append windowmaker "/bin/windowmaker")}.
- If false, a session described by one of the available @file{.desktop}
- files in @code{/run/current-system/profile} and @code{~/.guix-profile}
- will be used.
- @quotation Note
- You must install at least one window manager in the system profile or in
- your user profile. Failing to do that, if @code{auto-login-session} is
- false, you will be unable to log in.
- @end quotation
- @item @code{xorg-configuration} (default @code{(xorg-configuration)})
- Configuration of the Xorg graphical server.
- @item @code{display} (default @code{":0"})
- The display on which to start the Xorg graphical server.
- @item @code{vt} (default @code{"vt7"})
- The VT on which to start the Xorg graphical server.
- @item @code{xauth} (default: @code{xauth})
- The XAuth package to use.
- @item @code{shepherd} (default: @code{shepherd})
- The Shepherd package used when invoking @command{halt} and
- @command{reboot}.
- @item @code{sessreg} (default: @code{sessreg})
- The sessreg package used in order to register the session.
- @item @code{slim} (default: @code{slim})
- The SLiM package to use.
- @end table
- @end deftp
- @defvr {Scheme Variable} %default-theme
- @defvrx {Scheme Variable} %default-theme-name
- The default SLiM theme and its name.
- @end defvr
- @deftp {Data Type} sddm-configuration
- This is the data type representing the SDDM service configuration.
- @table @asis
- @item @code{display-server} (default: "x11")
- Select display server to use for the greeter. Valid values are
- @samp{"x11"} or @samp{"wayland"}.
- @item @code{numlock} (default: "on")
- Valid values are @samp{"on"}, @samp{"off"} or @samp{"none"}.
- @item @code{halt-command} (default @code{#~(string-apppend #$shepherd "/sbin/halt")})
- Command to run when halting.
- @item @code{reboot-command} (default @code{#~(string-append #$shepherd "/sbin/reboot")})
- Command to run when rebooting.
- @item @code{theme} (default "maldives")
- Theme to use. Default themes provided by SDDM are @samp{"elarun"},
- @samp{"maldives"} or @samp{"maya"}.
- @item @code{themes-directory} (default "/run/current-system/profile/share/sddm/themes")
- Directory to look for themes.
- @item @code{faces-directory} (default "/run/current-system/profile/share/sddm/faces")
- Directory to look for faces.
- @item @code{default-path} (default "/run/current-system/profile/bin")
- Default PATH to use.
- @item @code{minimum-uid} (default: 1000)
- Minimum UID displayed in SDDM and allowed for log-in.
- @item @code{maximum-uid} (default: 2000)
- Maximum UID to display in SDDM.
- @item @code{remember-last-user?} (default #t)
- Remember last user.
- @item @code{remember-last-session?} (default #t)
- Remember last session.
- @item @code{hide-users} (default "")
- Usernames to hide from SDDM greeter.
- @item @code{hide-shells} (default @code{#~(string-append #$shadow "/sbin/nologin")})
- Users with shells listed will be hidden from the SDDM greeter.
- @item @code{session-command} (default @code{#~(string-append #$sddm "/share/sddm/scripts/wayland-session")})
- Script to run before starting a wayland session.
- @item @code{sessions-directory} (default "/run/current-system/profile/share/wayland-sessions")
- Directory to look for desktop files starting wayland sessions.
- @item @code{xorg-configuration} (default @code{(xorg-configuration)})
- Configuration of the Xorg graphical server.
- @item @code{xauth-path} (default @code{#~(string-append #$xauth "/bin/xauth")})
- Path to xauth.
- @item @code{xephyr-path} (default @code{#~(string-append #$xorg-server "/bin/Xephyr")})
- Path to Xephyr.
- @item @code{xdisplay-start} (default @code{#~(string-append #$sddm "/share/sddm/scripts/Xsetup")})
- Script to run after starting xorg-server.
- @item @code{xdisplay-stop} (default @code{#~(string-append #$sddm "/share/sddm/scripts/Xstop")})
- Script to run before stopping xorg-server.
- @item @code{xsession-command} (default: @code{xinitrc})
- Script to run before starting a X session.
- @item @code{xsessions-directory} (default: "/run/current-system/profile/share/xsessions")
- Directory to look for desktop files starting X sessions.
- @item @code{minimum-vt} (default: 7)
- Minimum VT to use.
- @item @code{auto-login-user} (default "")
- User to use for auto-login.
- @item @code{auto-login-session} (default "")
- Desktop file to use for auto-login.
- @item @code{relogin?} (default #f)
- Relogin after logout.
- @end table
- @end deftp
- @cindex login manager
- @cindex X11 login
- @defvr {Scheme Variable} sddm-service-type
- This is the type of the service to run the
- @uref{https://github.com/sddm/sddm,SDDM display manager}. Its value
- must be a @code{sddm-configuration} record (see below).
- Here's an example use:
- @lisp
- (service sddm-service-type
- (sddm-configuration
- (auto-login-user "alice")
- (auto-login-session "xfce.desktop")))
- @end lisp
- @end defvr
- @deftp {Data Type} sddm-configuration
- This data type represents the configuration of the SDDM login manager.
- The available fields are:
- @table @asis
- @item @code{sddm} (default: @code{sddm})
- The SDDM package to use.
- @item @code{display-server} (default: @code{"x11"})
- This must be either @code{"x11"} or @code{"wayland"}.
- @c FIXME: Add more fields.
- @item @code{auto-login-user} (default: @code{""})
- If non-empty, this is the user account under which to log in
- automatically.
- @item @code{auto-login-session} (default: @code{""})
- If non-empty, this is the @file{.desktop} file name to use as the
- auto-login session.
- @end table
- @end deftp
- @cindex Xorg, configuration
- @deftp {Data Type} xorg-configuration
- This data type represents the configuration of the Xorg graphical display
- server. Note that there is no Xorg service; instead, the X server is started
- by a ``display manager'' such as GDM, SDDM, and SLiM@. Thus, the configuration
- of these display managers aggregates an @code{xorg-configuration} record.
- @table @asis
- @item @code{modules} (default: @code{%default-xorg-modules})
- This is a list of @dfn{module packages} loaded by the Xorg
- server---e.g., @code{xf86-video-vesa}, @code{xf86-input-keyboard}, and so on.
- @item @code{fonts} (default: @code{%default-xorg-fonts})
- This is a list of font directories to add to the server's @dfn{font path}.
- @item @code{drivers} (default: @code{'()})
- This must be either the empty list, in which case Xorg chooses a graphics
- driver automatically, or a list of driver names that will be tried in this
- order---e.g., @code{("modesetting" "vesa")}.
- @item @code{resolutions} (default: @code{'()})
- When @code{resolutions} is the empty list, Xorg chooses an appropriate screen
- resolution. Otherwise, it must be a list of resolutions---e.g., @code{((1024
- 768) (640 480))}.
- @cindex keyboard layout, for Xorg
- @cindex keymap, for Xorg
- @item @code{keyboard-layout} (default: @code{#f})
- If this is @code{#f}, Xorg uses the default keyboard layout---usually US
- English (``qwerty'') for a 105-key PC keyboard.
- Otherwise this must be a @code{keyboard-layout} object specifying the keyboard
- layout in use when Xorg is running. @xref{Keyboard Layout}, for more
- information on how to specify the keyboard layout.
- @item @code{extra-config} (default: @code{'()})
- This is a list of strings or objects appended to the configuration file. It
- is used to pass extra text to be added verbatim to the configuration file.
- @item @code{server} (default: @code{xorg-server})
- This is the package providing the Xorg server.
- @item @code{server-arguments} (default: @code{%default-xorg-server-arguments})
- This is the list of command-line arguments to pass to the X server. The
- default is @code{-nolisten tcp}.
- @end table
- @end deftp
- @deffn {Scheme Procedure} set-xorg-configuration @var{config} @
- [@var{login-manager-service-type}]
- Tell the log-in manager (of type @var{login-manager-service-type}) to use
- @var{config}, an @code{<xorg-configuration>} record.
- Since the Xorg configuration is embedded in the log-in manager's
- configuration---e.g., @code{gdm-configuration}---this procedure provides a
- shorthand to set the Xorg configuration.
- @end deffn
- @deffn {Scheme Procedure} xorg-start-command [@var{config}]
- Return a @code{startx} script in which the modules, fonts, etc. specified
- in @var{config}, are available. The result should be used in place of
- @code{startx}.
- Usually the X server is started by a login manager.
- @end deffn
- @deffn {Scheme Procedure} screen-locker-service @var{package} [@var{program}]
- Add @var{package}, a package for a screen locker or screen saver whose
- command is @var{program}, to the set of setuid programs and add a PAM entry
- for it. For example:
- @lisp
- (screen-locker-service xlockmore "xlock")
- @end lisp
- makes the good ol' XlockMore usable.
- @end deffn
- @node Printing Services
- @subsection Printing Services
- @cindex printer support with CUPS
- The @code{(gnu services cups)} module provides a Guix service definition
- for the CUPS printing service. To add printer support to a Guix
- system, add a @code{cups-service} to the operating system definition:
- @deffn {Scheme Variable} cups-service-type
- The service type for the CUPS print server. Its value should be a valid
- CUPS configuration (see below). To use the default settings, simply
- write:
- @lisp
- (service cups-service-type)
- @end lisp
- @end deffn
- The CUPS configuration controls the basic things about your CUPS
- installation: what interfaces it listens on, what to do if a print job
- fails, how much logging to do, and so on. To actually add a printer,
- you have to visit the @url{http://localhost:631} URL, or use a tool such
- as GNOME's printer configuration services. By default, configuring a
- CUPS service will generate a self-signed certificate if needed, for
- secure connections to the print server.
- Suppose you want to enable the Web interface of CUPS and also add
- support for Epson printers @i{via} the @code{epson-inkjet-printer-escpr}
- package and for HP printers @i{via} the @code{hplip-minimal} package.
- You can do that directly, like this (you need to use the
- @code{(gnu packages cups)} module):
- @lisp
- (service cups-service-type
- (cups-configuration
- (web-interface? #t)
- (extensions
- (list cups-filters epson-inkjet-printer-escpr hplip-minimal))))
- @end lisp
- Note: If you wish to use the Qt5 based GUI which comes with the hplip
- package then it is suggested that you install the @code{hplip} package,
- either in your OS configuration file or as your user.
- The available configuration parameters follow. Each parameter
- definition is preceded by its type; for example, @samp{string-list foo}
- indicates that the @code{foo} parameter should be specified as a list of
- strings. There is also a way to specify the configuration as a string,
- if you have an old @code{cupsd.conf} file that you want to port over
- from some other system; see the end for more details.
- @c The following documentation was initially generated by
- @c (generate-documentation) in (gnu services cups). Manually maintained
- @c documentation is better, so we shouldn't hesitate to edit below as
- @c needed. However if the change you want to make to this documentation
- @c can be done in an automated way, it's probably easier to change
- @c (generate-documentation) than to make it below and have to deal with
- @c the churn as CUPS updates.
- Available @code{cups-configuration} fields are:
- @deftypevr {@code{cups-configuration} parameter} package cups
- The CUPS package.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} package-list extensions (default: @code{(list brlaser cups-filters epson-inkjet-printer-escpr foomatic-filters hplip-minimal splix)})
- Drivers and other extensions to the CUPS package.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} files-configuration files-configuration
- Configuration of where to write logs, what directories to use for print
- spools, and related privileged configuration parameters.
- Available @code{files-configuration} fields are:
- @deftypevr {@code{files-configuration} parameter} log-location access-log
- Defines the access log filename. Specifying a blank filename disables
- access log generation. The value @code{stderr} causes log entries to be
- sent to the standard error file when the scheduler is running in the
- foreground, or to the system log daemon when run in the background. The
- value @code{syslog} causes log entries to be sent to the system log
- daemon. The server name may be included in filenames using the string
- @code{%s}, as in @code{/var/log/cups/%s-access_log}.
- Defaults to @samp{"/var/log/cups/access_log"}.
- @end deftypevr
- @deftypevr {@code{files-configuration} parameter} file-name cache-dir
- Where CUPS should cache data.
- Defaults to @samp{"/var/cache/cups"}.
- @end deftypevr
- @deftypevr {@code{files-configuration} parameter} string config-file-perm
- Specifies the permissions for all configuration files that the scheduler
- writes.
- Note that the permissions for the printers.conf file are currently
- masked to only allow access from the scheduler user (typically root).
- This is done because printer device URIs sometimes contain sensitive
- authentication information that should not be generally known on the
- system. There is no way to disable this security feature.
- Defaults to @samp{"0640"}.
- @end deftypevr
- @deftypevr {@code{files-configuration} parameter} log-location error-log
- Defines the error log filename. Specifying a blank filename disables
- error log generation. The value @code{stderr} causes log entries to be
- sent to the standard error file when the scheduler is running in the
- foreground, or to the system log daemon when run in the background. The
- value @code{syslog} causes log entries to be sent to the system log
- daemon. The server name may be included in filenames using the string
- @code{%s}, as in @code{/var/log/cups/%s-error_log}.
- Defaults to @samp{"/var/log/cups/error_log"}.
- @end deftypevr
- @deftypevr {@code{files-configuration} parameter} string fatal-errors
- Specifies which errors are fatal, causing the scheduler to exit. The
- kind strings are:
- @table @code
- @item none
- No errors are fatal.
- @item all
- All of the errors below are fatal.
- @item browse
- Browsing initialization errors are fatal, for example failed connections
- to the DNS-SD daemon.
- @item config
- Configuration file syntax errors are fatal.
- @item listen
- Listen or Port errors are fatal, except for IPv6 failures on the
- loopback or @code{any} addresses.
- @item log
- Log file creation or write errors are fatal.
- @item permissions
- Bad startup file permissions are fatal, for example shared TLS
- certificate and key files with world-read permissions.
- @end table
- Defaults to @samp{"all -browse"}.
- @end deftypevr
- @deftypevr {@code{files-configuration} parameter} boolean file-device?
- Specifies whether the file pseudo-device can be used for new printer
- queues. The URI @uref{file:///dev/null} is always allowed.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{files-configuration} parameter} string group
- Specifies the group name or ID that will be used when executing external
- programs.
- Defaults to @samp{"lp"}.
- @end deftypevr
- @deftypevr {@code{files-configuration} parameter} string log-file-group
- Specifies the group name or ID that will be used for log files.
- Defaults to @samp{"lpadmin"}.
- @end deftypevr
- @deftypevr {@code{files-configuration} parameter} string log-file-perm
- Specifies the permissions for all log files that the scheduler writes.
- Defaults to @samp{"0644"}.
- @end deftypevr
- @deftypevr {@code{files-configuration} parameter} log-location page-log
- Defines the page log filename. Specifying a blank filename disables
- page log generation. The value @code{stderr} causes log entries to be
- sent to the standard error file when the scheduler is running in the
- foreground, or to the system log daemon when run in the background. The
- value @code{syslog} causes log entries to be sent to the system log
- daemon. The server name may be included in filenames using the string
- @code{%s}, as in @code{/var/log/cups/%s-page_log}.
- Defaults to @samp{"/var/log/cups/page_log"}.
- @end deftypevr
- @deftypevr {@code{files-configuration} parameter} string remote-root
- Specifies the username that is associated with unauthenticated accesses
- by clients claiming to be the root user. The default is @code{remroot}.
- Defaults to @samp{"remroot"}.
- @end deftypevr
- @deftypevr {@code{files-configuration} parameter} file-name request-root
- Specifies the directory that contains print jobs and other HTTP request
- data.
- Defaults to @samp{"/var/spool/cups"}.
- @end deftypevr
- @deftypevr {@code{files-configuration} parameter} sandboxing sandboxing
- Specifies the level of security sandboxing that is applied to print
- filters, backends, and other child processes of the scheduler; either
- @code{relaxed} or @code{strict}. This directive is currently only
- used/supported on macOS.
- Defaults to @samp{strict}.
- @end deftypevr
- @deftypevr {@code{files-configuration} parameter} file-name server-keychain
- Specifies the location of TLS certificates and private keys. CUPS will
- look for public and private keys in this directory: @file{.crt} files
- for PEM-encoded certificates and corresponding @file{.key} files for
- PEM-encoded private keys.
- Defaults to @samp{"/etc/cups/ssl"}.
- @end deftypevr
- @deftypevr {@code{files-configuration} parameter} file-name server-root
- Specifies the directory containing the server configuration files.
- Defaults to @samp{"/etc/cups"}.
- @end deftypevr
- @deftypevr {@code{files-configuration} parameter} boolean sync-on-close?
- Specifies whether the scheduler calls fsync(2) after writing
- configuration or state files.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{files-configuration} parameter} space-separated-string-list system-group
- Specifies the group(s) to use for @code{@@SYSTEM} group authentication.
- @end deftypevr
- @deftypevr {@code{files-configuration} parameter} file-name temp-dir
- Specifies the directory where temporary files are stored.
- Defaults to @samp{"/var/spool/cups/tmp"}.
- @end deftypevr
- @deftypevr {@code{files-configuration} parameter} string user
- Specifies the user name or ID that is used when running external
- programs.
- Defaults to @samp{"lp"}.
- @end deftypevr
- @deftypevr {@code{files-configuration} parameter} string set-env
- Set the specified environment variable to be passed to child processes.
- Defaults to @samp{"variable value"}.
- @end deftypevr
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} access-log-level access-log-level
- Specifies the logging level for the AccessLog file. The @code{config}
- level logs when printers and classes are added, deleted, or modified and
- when configuration files are accessed or updated. The @code{actions}
- level logs when print jobs are submitted, held, released, modified, or
- canceled, and any of the conditions for @code{config}. The @code{all}
- level logs all requests.
- Defaults to @samp{actions}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} boolean auto-purge-jobs?
- Specifies whether to purge job history data automatically when it is no
- longer required for quotas.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} comma-separated-string-list browse-dns-sd-sub-types
- Specifies a list of DNS-SD sub-types to advertise for each shared printer.
- For example, @samp{"_cups" "_print"} will tell network clients that both
- CUPS sharing and IPP Everywhere are supported.
- Defaults to @samp{"_cups"}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} browse-local-protocols browse-local-protocols
- Specifies which protocols to use for local printer sharing.
- Defaults to @samp{dnssd}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} boolean browse-web-if?
- Specifies whether the CUPS web interface is advertised.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} boolean browsing?
- Specifies whether shared printers are advertised.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} string classification
- Specifies the security classification of the server. Any valid banner
- name can be used, including @samp{"classified"}, @samp{"confidential"},
- @samp{"secret"}, @samp{"topsecret"}, and @samp{"unclassified"}, or the
- banner can be omitted to disable secure printing functions.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} boolean classify-override?
- Specifies whether users may override the classification (cover page) of
- individual print jobs using the @code{job-sheets} option.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} default-auth-type default-auth-type
- Specifies the default type of authentication to use.
- Defaults to @samp{Basic}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} default-encryption default-encryption
- Specifies whether encryption will be used for authenticated requests.
- Defaults to @samp{Required}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} string default-language
- Specifies the default language to use for text and web content.
- Defaults to @samp{"en"}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} string default-paper-size
- Specifies the default paper size for new print queues. @samp{"Auto"}
- uses a locale-specific default, while @samp{"None"} specifies there is
- no default paper size. Specific size names are typically
- @samp{"Letter"} or @samp{"A4"}.
- Defaults to @samp{"Auto"}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} string default-policy
- Specifies the default access policy to use.
- Defaults to @samp{"default"}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} boolean default-shared?
- Specifies whether local printers are shared by default.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} non-negative-integer dirty-clean-interval
- Specifies the delay for updating of configuration and state files, in
- seconds. A value of 0 causes the update to happen as soon as possible,
- typically within a few milliseconds.
- Defaults to @samp{30}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} error-policy error-policy
- Specifies what to do when an error occurs. Possible values are
- @code{abort-job}, which will discard the failed print job;
- @code{retry-job}, which will retry the job at a later time;
- @code{retry-current-job}, which retries the failed job immediately; and
- @code{stop-printer}, which stops the printer.
- Defaults to @samp{stop-printer}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} non-negative-integer filter-limit
- Specifies the maximum cost of filters that are run concurrently, which
- can be used to minimize disk, memory, and CPU resource problems. A
- limit of 0 disables filter limiting. An average print to a
- non-PostScript printer needs a filter limit of about 200. A PostScript
- printer needs about half that (100). Setting the limit below these
- thresholds will effectively limit the scheduler to printing a single job
- at any time.
- Defaults to @samp{0}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} non-negative-integer filter-nice
- Specifies the scheduling priority of filters that are run to print a
- job. The nice value ranges from 0, the highest priority, to 19, the
- lowest priority.
- Defaults to @samp{0}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} host-name-lookups host-name-lookups
- Specifies whether to do reverse lookups on connecting clients. The
- @code{double} setting causes @code{cupsd} to verify that the hostname
- resolved from the address matches one of the addresses returned for that
- hostname. Double lookups also prevent clients with unregistered
- addresses from connecting to your server. Only set this option to
- @code{#t} or @code{double} if absolutely required.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} non-negative-integer job-kill-delay
- Specifies the number of seconds to wait before killing the filters and
- backend associated with a canceled or held job.
- Defaults to @samp{30}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} non-negative-integer job-retry-interval
- Specifies the interval between retries of jobs in seconds. This is
- typically used for fax queues but can also be used with normal print
- queues whose error policy is @code{retry-job} or
- @code{retry-current-job}.
- Defaults to @samp{30}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} non-negative-integer job-retry-limit
- Specifies the number of retries that are done for jobs. This is
- typically used for fax queues but can also be used with normal print
- queues whose error policy is @code{retry-job} or
- @code{retry-current-job}.
- Defaults to @samp{5}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} boolean keep-alive?
- Specifies whether to support HTTP keep-alive connections.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} non-negative-integer limit-request-body
- Specifies the maximum size of print files, IPP requests, and HTML form
- data. A limit of 0 disables the limit check.
- Defaults to @samp{0}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} multiline-string-list listen
- Listens on the specified interfaces for connections. Valid values are
- of the form @var{address}:@var{port}, where @var{address} is either an
- IPv6 address enclosed in brackets, an IPv4 address, or @code{*} to
- indicate all addresses. Values can also be file names of local UNIX
- domain sockets. The Listen directive is similar to the Port directive
- but allows you to restrict access to specific interfaces or networks.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} non-negative-integer listen-back-log
- Specifies the number of pending connections that will be allowed. This
- normally only affects very busy servers that have reached the MaxClients
- limit, but can also be triggered by large numbers of simultaneous
- connections. When the limit is reached, the operating system will
- refuse additional connections until the scheduler can accept the pending
- ones.
- Defaults to @samp{128}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} location-access-control-list location-access-controls
- Specifies a set of additional access controls.
- Available @code{location-access-controls} fields are:
- @deftypevr {@code{location-access-controls} parameter} file-name path
- Specifies the URI path to which the access control applies.
- @end deftypevr
- @deftypevr {@code{location-access-controls} parameter} access-control-list access-controls
- Access controls for all access to this path, in the same format as the
- @code{access-controls} of @code{operation-access-control}.
- Defaults to @samp{()}.
- @end deftypevr
- @deftypevr {@code{location-access-controls} parameter} method-access-control-list method-access-controls
- Access controls for method-specific access to this path.
- Defaults to @samp{()}.
- Available @code{method-access-controls} fields are:
- @deftypevr {@code{method-access-controls} parameter} boolean reverse?
- If @code{#t}, apply access controls to all methods except the listed
- methods. Otherwise apply to only the listed methods.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{method-access-controls} parameter} method-list methods
- Methods to which this access control applies.
- Defaults to @samp{()}.
- @end deftypevr
- @deftypevr {@code{method-access-controls} parameter} access-control-list access-controls
- Access control directives, as a list of strings. Each string should be
- one directive, such as @samp{"Order allow,deny"}.
- Defaults to @samp{()}.
- @end deftypevr
- @end deftypevr
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} non-negative-integer log-debug-history
- Specifies the number of debugging messages that are retained for logging
- if an error occurs in a print job. Debug messages are logged regardless
- of the LogLevel setting.
- Defaults to @samp{100}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} log-level log-level
- Specifies the level of logging for the ErrorLog file. The value
- @code{none} stops all logging while @code{debug2} logs everything.
- Defaults to @samp{info}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} log-time-format log-time-format
- Specifies the format of the date and time in the log files. The value
- @code{standard} logs whole seconds while @code{usecs} logs microseconds.
- Defaults to @samp{standard}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} non-negative-integer max-clients
- Specifies the maximum number of simultaneous clients that are allowed by
- the scheduler.
- Defaults to @samp{100}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} non-negative-integer max-clients-per-host
- Specifies the maximum number of simultaneous clients that are allowed
- from a single address.
- Defaults to @samp{100}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} non-negative-integer max-copies
- Specifies the maximum number of copies that a user can print of each
- job.
- Defaults to @samp{9999}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} non-negative-integer max-hold-time
- Specifies the maximum time a job may remain in the @code{indefinite}
- hold state before it is canceled. A value of 0 disables cancellation of
- held jobs.
- Defaults to @samp{0}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} non-negative-integer max-jobs
- Specifies the maximum number of simultaneous jobs that are allowed. Set
- to 0 to allow an unlimited number of jobs.
- Defaults to @samp{500}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} non-negative-integer max-jobs-per-printer
- Specifies the maximum number of simultaneous jobs that are allowed per
- printer. A value of 0 allows up to MaxJobs jobs per printer.
- Defaults to @samp{0}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} non-negative-integer max-jobs-per-user
- Specifies the maximum number of simultaneous jobs that are allowed per
- user. A value of 0 allows up to MaxJobs jobs per user.
- Defaults to @samp{0}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} non-negative-integer max-job-time
- Specifies the maximum time a job may take to print before it is
- canceled, in seconds. Set to 0 to disable cancellation of ``stuck'' jobs.
- Defaults to @samp{10800}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} non-negative-integer max-log-size
- Specifies the maximum size of the log files before they are rotated, in
- bytes. The value 0 disables log rotation.
- Defaults to @samp{1048576}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} non-negative-integer multiple-operation-timeout
- Specifies the maximum amount of time to allow between files in a
- multiple file print job, in seconds.
- Defaults to @samp{900}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} string page-log-format
- Specifies the format of PageLog lines. Sequences beginning with percent
- (@samp{%}) characters are replaced with the corresponding information,
- while all other characters are copied literally. The following percent
- sequences are recognized:
- @table @samp
- @item %%
- insert a single percent character
- @item %@{name@}
- insert the value of the specified IPP attribute
- @item %C
- insert the number of copies for the current page
- @item %P
- insert the current page number
- @item %T
- insert the current date and time in common log format
- @item %j
- insert the job ID
- @item %p
- insert the printer name
- @item %u
- insert the username
- @end table
- A value of the empty string disables page logging. The string @code{%p
- %u %j %T %P %C %@{job-billing@} %@{job-originating-host-name@}
- %@{job-name@} %@{media@} %@{sides@}} creates a page log with the
- standard items.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} environment-variables environment-variables
- Passes the specified environment variable(s) to child processes; a list
- of strings.
- Defaults to @samp{()}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} policy-configuration-list policies
- Specifies named access control policies.
- Available @code{policy-configuration} fields are:
- @deftypevr {@code{policy-configuration} parameter} string name
- Name of the policy.
- @end deftypevr
- @deftypevr {@code{policy-configuration} parameter} string job-private-access
- Specifies an access list for a job's private values. @code{@@ACL} maps
- to the printer's requesting-user-name-allowed or
- requesting-user-name-denied values. @code{@@OWNER} maps to the job's
- owner. @code{@@SYSTEM} maps to the groups listed for the
- @code{system-group} field of the @code{files-configuration},
- which is reified into the @code{cups-files.conf(5)} file. Other
- possible elements of the access list include specific user names, and
- @code{@@@var{group}} to indicate members of a specific group. The
- access list may also be simply @code{all} or @code{default}.
- Defaults to @samp{"@@OWNER @@SYSTEM"}.
- @end deftypevr
- @deftypevr {@code{policy-configuration} parameter} string job-private-values
- Specifies the list of job values to make private, or @code{all},
- @code{default}, or @code{none}.
- Defaults to @samp{"job-name job-originating-host-name
- job-originating-user-name phone"}.
- @end deftypevr
- @deftypevr {@code{policy-configuration} parameter} string subscription-private-access
- Specifies an access list for a subscription's private values.
- @code{@@ACL} maps to the printer's requesting-user-name-allowed or
- requesting-user-name-denied values. @code{@@OWNER} maps to the job's
- owner. @code{@@SYSTEM} maps to the groups listed for the
- @code{system-group} field of the @code{files-configuration},
- which is reified into the @code{cups-files.conf(5)} file. Other
- possible elements of the access list include specific user names, and
- @code{@@@var{group}} to indicate members of a specific group. The
- access list may also be simply @code{all} or @code{default}.
- Defaults to @samp{"@@OWNER @@SYSTEM"}.
- @end deftypevr
- @deftypevr {@code{policy-configuration} parameter} string subscription-private-values
- Specifies the list of job values to make private, or @code{all},
- @code{default}, or @code{none}.
- Defaults to @samp{"notify-events notify-pull-method notify-recipient-uri
- notify-subscriber-user-name notify-user-data"}.
- @end deftypevr
- @deftypevr {@code{policy-configuration} parameter} operation-access-control-list access-controls
- Access control by IPP operation.
- Defaults to @samp{()}.
- @end deftypevr
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} boolean-or-non-negative-integer preserve-job-files
- Specifies whether job files (documents) are preserved after a job is
- printed. If a numeric value is specified, job files are preserved for
- the indicated number of seconds after printing. Otherwise a boolean
- value applies indefinitely.
- Defaults to @samp{86400}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} boolean-or-non-negative-integer preserve-job-history
- Specifies whether the job history is preserved after a job is printed.
- If a numeric value is specified, the job history is preserved for the
- indicated number of seconds after printing. If @code{#t}, the job
- history is preserved until the MaxJobs limit is reached.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} non-negative-integer reload-timeout
- Specifies the amount of time to wait for job completion before
- restarting the scheduler.
- Defaults to @samp{30}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} string rip-cache
- Specifies the maximum amount of memory to use when converting documents
- into bitmaps for a printer.
- Defaults to @samp{"128m"}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} string server-admin
- Specifies the email address of the server administrator.
- Defaults to @samp{"root@@localhost.localdomain"}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} host-name-list-or-* server-alias
- The ServerAlias directive is used for HTTP Host header validation when
- clients connect to the scheduler from external interfaces. Using the
- special name @code{*} can expose your system to known browser-based DNS
- rebinding attacks, even when accessing sites through a firewall. If the
- auto-discovery of alternate names does not work, we recommend listing
- each alternate name with a ServerAlias directive instead of using
- @code{*}.
- Defaults to @samp{*}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} string server-name
- Specifies the fully-qualified host name of the server.
- Defaults to @samp{"localhost"}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} server-tokens server-tokens
- Specifies what information is included in the Server header of HTTP
- responses. @code{None} disables the Server header. @code{ProductOnly}
- reports @code{CUPS}. @code{Major} reports @code{CUPS 2}. @code{Minor}
- reports @code{CUPS 2.0}. @code{Minimal} reports @code{CUPS 2.0.0}.
- @code{OS} reports @code{CUPS 2.0.0 (@var{uname})} where @var{uname} is
- the output of the @code{uname} command. @code{Full} reports @code{CUPS
- 2.0.0 (@var{uname}) IPP/2.0}.
- Defaults to @samp{Minimal}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} multiline-string-list ssl-listen
- Listens on the specified interfaces for encrypted connections. Valid
- values are of the form @var{address}:@var{port}, where @var{address} is
- either an IPv6 address enclosed in brackets, an IPv4 address, or
- @code{*} to indicate all addresses.
- Defaults to @samp{()}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} ssl-options ssl-options
- Sets encryption options. By default, CUPS only supports encryption
- using TLS v1.0 or higher using known secure cipher suites. Security is
- reduced when @code{Allow} options are used, and enhanced when @code{Deny}
- options are used. The @code{AllowRC4} option enables the 128-bit RC4 cipher
- suites, which are required for some older clients. The @code{AllowSSL3} option
- enables SSL v3.0, which is required for some older clients that do not support
- TLS v1.0. The @code{DenyCBC} option disables all CBC cipher suites. The
- @code{DenyTLS1.0} option disables TLS v1.0 support - this sets the minimum
- protocol version to TLS v1.1.
- Defaults to @samp{()}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} boolean strict-conformance?
- Specifies whether the scheduler requires clients to strictly adhere to
- the IPP specifications.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} non-negative-integer timeout
- Specifies the HTTP request timeout, in seconds.
- Defaults to @samp{900}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} boolean web-interface?
- Specifies whether the web interface is enabled.
- Defaults to @samp{#f}.
- @end deftypevr
- At this point you're probably thinking ``oh dear, Guix manual, I like
- you but you can stop already with the configuration options''. Indeed.
- However, one more point: it could be that you have an existing
- @code{cupsd.conf} that you want to use. In that case, you can pass an
- @code{opaque-cups-configuration} as the configuration of a
- @code{cups-service-type}.
- Available @code{opaque-cups-configuration} fields are:
- @deftypevr {@code{opaque-cups-configuration} parameter} package cups
- The CUPS package.
- @end deftypevr
- @deftypevr {@code{opaque-cups-configuration} parameter} string cupsd.conf
- The contents of the @code{cupsd.conf}, as a string.
- @end deftypevr
- @deftypevr {@code{opaque-cups-configuration} parameter} string cups-files.conf
- The contents of the @code{cups-files.conf} file, as a string.
- @end deftypevr
- For example, if your @code{cupsd.conf} and @code{cups-files.conf} are in
- strings of the same name, you could instantiate a CUPS service like
- this:
- @lisp
- (service cups-service-type
- (opaque-cups-configuration
- (cupsd.conf cupsd.conf)
- (cups-files.conf cups-files.conf)))
- @end lisp
- @node Desktop Services
- @subsection Desktop Services
- The @code{(gnu services desktop)} module provides services that are
- usually useful in the context of a ``desktop'' setup---that is, on a
- machine running a graphical display server, possibly with graphical user
- interfaces, etc. It also defines services that provide specific desktop
- environments like GNOME, Xfce or MATE.
- To simplify things, the module defines a variable containing the set of
- services that users typically expect on a machine with a graphical
- environment and networking:
- @defvr {Scheme Variable} %desktop-services
- This is a list of services that builds upon @code{%base-services} and
- adds or adjusts services for a typical ``desktop'' setup.
- In particular, it adds a graphical login manager (@pxref{X Window,
- @code{gdm-service-type}}), screen lockers, a network management tool
- (@pxref{Networking Services, @code{network-manager-service-type}}) with modem
- support (@pxref{Networking Services, @code{modem-manager-service-type}}),
- energy and color management services, the @code{elogind} login and seat
- manager, the Polkit privilege service, the GeoClue location service, the
- AccountsService daemon that allows authorized users change system passwords,
- an NTP client (@pxref{Networking Services}), the Avahi daemon, and has the
- name service switch service configured to be able to use @code{nss-mdns}
- (@pxref{Name Service Switch, mDNS}).
- @end defvr
- The @code{%desktop-services} variable can be used as the @code{services}
- field of an @code{operating-system} declaration (@pxref{operating-system
- Reference, @code{services}}).
- Additionally, the @code{gnome-desktop-service-type},
- @code{xfce-desktop-service}, @code{mate-desktop-service-type},
- @code{lxqt-desktop-service-type} and @code{enlightenment-desktop-service-type}
- procedures can add GNOME, Xfce, MATE and/or Enlightenment to a system. To
- ``add GNOME'' means that system-level services like the backlight adjustment
- helpers and the power management utilities are added to the system, extending
- @code{polkit} and @code{dbus} appropriately, allowing GNOME to operate with
- elevated privileges on a limited number of special-purpose system interfaces.
- Additionally, adding a service made by @code{gnome-desktop-service-type} adds
- the GNOME metapackage to the system profile. Likewise, adding the Xfce
- service not only adds the @code{xfce} metapackage to the system profile, but
- it also gives the Thunar file manager the ability to open a ``root-mode'' file
- management window, if the user authenticates using the administrator's
- password via the standard polkit graphical interface. To ``add MATE'' means
- that @code{polkit} and @code{dbus} are extended appropriately, allowing MATE
- to operate with elevated privileges on a limited number of special-purpose
- system interfaces. Additionally, adding a service of type
- @code{mate-desktop-service-type} adds the MATE metapackage to the system
- profile. ``Adding Enlightenment'' means that @code{dbus} is extended
- appropriately, and several of Enlightenment's binaries are set as setuid,
- allowing Enlightenment's screen locker and other functionality to work as
- expected.
- The desktop environments in Guix use the Xorg display server by
- default. If you'd like to use the newer display server protocol
- called Wayland, you need to enable Wayland support in GDM
- (@pxref{wayland-gdm}). Another solution is to use the
- @code{sddm-service} instead of GDM as the graphical login manager.
- You should then select the ``GNOME (Wayland)'' session in SDDM@.
- Alternatively you can also try starting GNOME on Wayland manually from a
- TTY with the command ``XDG_SESSION_TYPE=wayland exec dbus-run-session
- gnome-session``. Currently only GNOME has support for Wayland.
- @defvr {Scheme Variable} gnome-desktop-service-type
- This is the type of the service that adds the @uref{https://www.gnome.org,
- GNOME} desktop environment. Its value is a @code{gnome-desktop-configuration}
- object (see below).
- This service adds the @code{gnome} package to the system profile, and extends
- polkit with the actions from @code{gnome-settings-daemon}.
- @end defvr
- @deftp {Data Type} gnome-desktop-configuration
- Configuration record for the GNOME desktop environment.
- @table @asis
- @item @code{gnome} (default: @code{gnome})
- The GNOME package to use.
- @end table
- @end deftp
- @defvr {Scheme Variable} xfce-desktop-service-type
- This is the type of a service to run the @uref{Xfce, https://xfce.org/}
- desktop environment. Its value is an @code{xfce-desktop-configuration} object
- (see below).
- This service adds the @code{xfce} package to the system profile, and
- extends polkit with the ability for @code{thunar} to manipulate the file
- system as root from within a user session, after the user has authenticated
- with the administrator's password.
- Note that @code{xfce4-panel} and its plugin packages should be installed in
- the same profile to ensure compatibility. When using this service, you should
- add extra plugins (@code{xfce4-whiskermenu-plugin},
- @code{xfce4-weather-plugin}, etc.) to the @code{packages} field of your
- @code{operating-system}.
- @end defvr
- @deftp {Data Type} xfce-desktop-configuration
- Configuration record for the Xfce desktop environment.
- @table @asis
- @item @code{xfce} (default: @code{xfce})
- The Xfce package to use.
- @end table
- @end deftp
- @deffn {Scheme Variable} mate-desktop-service-type
- This is the type of the service that runs the @uref{https://mate-desktop.org/,
- MATE desktop environment}. Its value is a @code{mate-desktop-configuration}
- object (see below).
- This service adds the @code{mate} package to the system
- profile, and extends polkit with the actions from
- @code{mate-settings-daemon}.
- @end deffn
- @deftp {Data Type} mate-desktop-configuration
- Configuration record for the MATE desktop environment.
- @table @asis
- @item @code{mate} (default: @code{mate})
- The MATE package to use.
- @end table
- @end deftp
- @deffn {Scheme Variable} lxqt-desktop-service-type
- This is the type of the service that runs the @uref{https://lxqt-project.org,
- LXQt desktop environment}. Its value is a @code{lxqt-desktop-configuration}
- object (see below).
- This service adds the @code{lxqt} package to the system
- profile.
- @end deffn
- @deftp {Data Type} lxqt-desktop-configuration
- Configuration record for the LXQt desktop environment.
- @table @asis
- @item @code{lxqt} (default: @code{lxqt})
- The LXQT package to use.
- @end table
- @end deftp
- @deffn {Scheme Variable} enlightenment-desktop-service-type
- Return a service that adds the @code{enlightenment} package to the system
- profile, and extends dbus with actions from @code{efl}.
- @end deffn
- @deftp {Data Type} enlightenment-desktop-service-configuration
- @table @asis
- @item @code{enlightenment} (default: @code{enlightenment})
- The enlightenment package to use.
- @end table
- @end deftp
- Because the GNOME, Xfce and MATE desktop services pull in so many packages,
- the default @code{%desktop-services} variable doesn't include any of
- them by default. To add GNOME, Xfce or MATE, just @code{cons} them onto
- @code{%desktop-services} in the @code{services} field of your
- @code{operating-system}:
- @lisp
- (use-modules (gnu))
- (use-service-modules desktop)
- (operating-system
- ...
- ;; cons* adds items to the list given as its last argument.
- (services (cons* (service gnome-desktop-service-type)
- (service xfce-desktop-service)
- %desktop-services))
- ...)
- @end lisp
- These desktop environments will then be available as options in the
- graphical login window.
- The actual service definitions included in @code{%desktop-services} and
- provided by @code{(gnu services dbus)} and @code{(gnu services desktop)}
- are described below.
- @deffn {Scheme Procedure} dbus-service [#:dbus @var{dbus}] [#:services '()]
- Return a service that runs the ``system bus'', using @var{dbus}, with
- support for @var{services}.
- @uref{https://dbus.freedesktop.org/, D-Bus} is an inter-process communication
- facility. Its system bus is used to allow system services to communicate
- and to be notified of system-wide events.
- @var{services} must be a list of packages that provide an
- @file{etc/dbus-1/system.d} directory containing additional D-Bus configuration
- and policy files. For example, to allow avahi-daemon to use the system bus,
- @var{services} must be equal to @code{(list avahi)}.
- @end deffn
- @deffn {Scheme Procedure} elogind-service [#:config @var{config}]
- Return a service that runs the @code{elogind} login and
- seat management daemon. @uref{https://github.com/elogind/elogind,
- Elogind} exposes a D-Bus interface that can be used to know which users
- are logged in, know what kind of sessions they have open, suspend the
- system, inhibit system suspend, reboot the system, and other tasks.
- Elogind handles most system-level power events for a computer, for
- example suspending the system when a lid is closed, or shutting it down
- when the power button is pressed.
- The @var{config} keyword argument specifies the configuration for
- elogind, and should be the result of an @code{(elogind-configuration
- (@var{parameter} @var{value})...)} invocation. Available parameters and
- their default values are:
- @table @code
- @item kill-user-processes?
- @code{#f}
- @item kill-only-users
- @code{()}
- @item kill-exclude-users
- @code{("root")}
- @item inhibit-delay-max-seconds
- @code{5}
- @item handle-power-key
- @code{poweroff}
- @item handle-suspend-key
- @code{suspend}
- @item handle-hibernate-key
- @code{hibernate}
- @item handle-lid-switch
- @code{suspend}
- @item handle-lid-switch-docked
- @code{ignore}
- @item handle-lid-switch-external-power
- @code{ignore}
- @item power-key-ignore-inhibited?
- @code{#f}
- @item suspend-key-ignore-inhibited?
- @code{#f}
- @item hibernate-key-ignore-inhibited?
- @code{#f}
- @item lid-switch-ignore-inhibited?
- @code{#t}
- @item holdoff-timeout-seconds
- @code{30}
- @item idle-action
- @code{ignore}
- @item idle-action-seconds
- @code{(* 30 60)}
- @item runtime-directory-size-percent
- @code{10}
- @item runtime-directory-size
- @code{#f}
- @item remove-ipc?
- @code{#t}
- @item suspend-state
- @code{("mem" "standby" "freeze")}
- @item suspend-mode
- @code{()}
- @item hibernate-state
- @code{("disk")}
- @item hibernate-mode
- @code{("platform" "shutdown")}
- @item hybrid-sleep-state
- @code{("disk")}
- @item hybrid-sleep-mode
- @code{("suspend" "platform" "shutdown")}
- @end table
- @end deffn
- @deffn {Scheme Procedure} accountsservice-service @
- [#:accountsservice @var{accountsservice}]
- Return a service that runs AccountsService, a system service that can
- list available accounts, change their passwords, and so on.
- AccountsService integrates with PolicyKit to enable unprivileged users
- to acquire the capability to modify their system configuration.
- @uref{https://www.freedesktop.org/wiki/Software/AccountsService/, the
- accountsservice web site} for more information.
- The @var{accountsservice} keyword argument is the @code{accountsservice}
- package to expose as a service.
- @end deffn
- @deffn {Scheme Procedure} polkit-service @
- [#:polkit @var{polkit}]
- Return a service that runs the
- @uref{https://www.freedesktop.org/wiki/Software/polkit/, Polkit privilege
- management service}, which allows system administrators to grant access to
- privileged operations in a structured way. By querying the Polkit service, a
- privileged system component can know when it should grant additional
- capabilities to ordinary users. For example, an ordinary user can be granted
- the capability to suspend the system if the user is logged in locally.
- @end deffn
- @defvr {Scheme Variable} polkit-wheel-service
- Service that adds the @code{wheel} group as admins to the Polkit
- service. This makes it so that users in the @code{wheel} group are queried
- for their own passwords when performing administrative actions instead of
- @code{root}'s, similar to the behaviour used by @code{sudo}.
- @end defvr
- @defvr {Scheme Variable} upower-service-type
- Service that runs @uref{https://upower.freedesktop.org/, @command{upowerd}}, a
- system-wide monitor for power consumption and battery levels, with the given
- configuration settings.
- It implements the @code{org.freedesktop.UPower} D-Bus interface, and is
- notably used by GNOME.
- @end defvr
- @deftp {Data Type} upower-configuration
- Data type representation the configuration for UPower.
- @table @asis
- @item @code{upower} (default: @var{upower})
- Package to use for @code{upower}.
- @item @code{watts-up-pro?} (default: @code{#f})
- Enable the Watts Up Pro device.
- @item @code{poll-batteries?} (default: @code{#t})
- Enable polling the kernel for battery level changes.
- @item @code{ignore-lid?} (default: @code{#f})
- Ignore the lid state, this can be useful if it's incorrect on a device.
- @item @code{use-percentage-for-policy?} (default: @code{#f})
- Whether battery percentage based policy should be used. The default is to use
- the time left, change to @code{#t} to use the percentage.
- @item @code{percentage-low} (default: @code{10})
- When @code{use-percentage-for-policy?} is @code{#t}, this sets the percentage
- at which the battery is considered low.
- @item @code{percentage-critical} (default: @code{3})
- When @code{use-percentage-for-policy?} is @code{#t}, this sets the percentage
- at which the battery is considered critical.
- @item @code{percentage-action} (default: @code{2})
- When @code{use-percentage-for-policy?} is @code{#t}, this sets the percentage
- at which action will be taken.
- @item @code{time-low} (default: @code{1200})
- When @code{use-time-for-policy?} is @code{#f}, this sets the time remaining in
- seconds at which the battery is considered low.
- @item @code{time-critical} (default: @code{300})
- When @code{use-time-for-policy?} is @code{#f}, this sets the time remaining in
- seconds at which the battery is considered critical.
- @item @code{time-action} (default: @code{120})
- When @code{use-time-for-policy?} is @code{#f}, this sets the time remaining in
- seconds at which action will be taken.
- @item @code{critical-power-action} (default: @code{'hybrid-sleep})
- The action taken when @code{percentage-action} or @code{time-action} is
- reached (depending on the configuration of @code{use-percentage-for-policy?}).
- Possible values are:
- @itemize @bullet
- @item
- @code{'power-off}
- @item
- @code{'hibernate}
- @item
- @code{'hybrid-sleep}.
- @end itemize
- @end table
- @end deftp
- @deffn {Scheme Procedure} udisks-service [#:udisks @var{udisks}]
- Return a service for @uref{https://udisks.freedesktop.org/docs/latest/,
- UDisks}, a @dfn{disk management} daemon that provides user interfaces
- with notifications and ways to mount/unmount disks. Programs that talk
- to UDisks include the @command{udisksctl} command, part of UDisks, and
- GNOME Disks. Note that Udisks relies on the @command{mount} command, so
- it will only be able to use the file-system utilities installed in the
- system profile. For example if you want to be able to mount NTFS
- file-systems in read and write fashion, you'll need to have
- @code{ntfs-3g} installed system-wide.
- @end deffn
- @deffn {Scheme Variable} colord-service-type
- This is the type of the service that runs @command{colord}, a system
- service with a D-Bus
- interface to manage the color profiles of input and output devices such as
- screens and scanners. It is notably used by the GNOME Color Manager graphical
- tool. See @uref{https://www.freedesktop.org/software/colord/, the colord web
- site} for more information.
- @end deffn
- @cindex scanner access
- @defvr {Scheme Variable} sane-service-type
- This service provides access to scanners @i{via}
- @uref{http://www.sane-project.org, SANE} by installing the necessary
- udev rules. It is included in @code{%desktop-services} (@pxref{Desktop
- Services}) and relies by default on @code{sane-backends-minimal} package
- (see below) for hardware support.
- @end defvr
- @defvr {Scheme Variable} sane-backends-minimal
- The default package which the @code{sane-service-type} installs. It
- supports many recent scanners.
- @end defvr
- @defvr {Scheme Variable} sane-backends
- This package includes support for all scanners that
- @code{sane-backends-minimal} supports, plus older Hewlett-Packard
- scanners supported by @code{hplip} package. In order to use this on
- a system which relies on @code{%desktop-services}, you may use
- @code{modify-services} (@pxref{Service Reference,
- @code{modify-services}}) as illustrated below:
- @lisp
- (use-modules (gnu))
- (use-service-modules
- @dots{}
- desktop)
- (use-package-modules
- @dots{}
- scanner)
- (define %my-desktop-services
- ;; List of desktop services that supports a broader range of scanners.
- (modify-services %desktop-services
- (sane-service-type _ => sane-backends)))
- (operating-system
- @dots{}
- (services %my-desktop-services))
- @end lisp
- @end defvr
- @deffn {Scheme Procedure} geoclue-application name [#:allowed? #t] [#:system? #f] [#:users '()]
- Return a configuration allowing an application to access GeoClue
- location data. @var{name} is the Desktop ID of the application, without
- the @code{.desktop} part. If @var{allowed?} is true, the application
- will have access to location information by default. The boolean
- @var{system?} value indicates whether an application is a system component
- or not. Finally @var{users} is a list of UIDs of all users for which
- this application is allowed location info access. An empty users list
- means that all users are allowed.
- @end deffn
- @defvr {Scheme Variable} %standard-geoclue-applications
- The standard list of well-known GeoClue application configurations,
- granting authority to the GNOME date-and-time utility to ask for the
- current location in order to set the time zone, and allowing the
- IceCat and Epiphany web browsers to request location information.
- IceCat and Epiphany both query the user before allowing a web page to
- know the user's location.
- @end defvr
- @deffn {Scheme Procedure} geoclue-service [#:colord @var{colord}] @
- [#:whitelist '()] @
- [#:wifi-geolocation-url "https://location.services.mozilla.com/v1/geolocate?key=geoclue"] @
- [#:submit-data? #f]
- [#:wifi-submission-url "https://location.services.mozilla.com/v1/submit?key=geoclue"] @
- [#:submission-nick "geoclue"] @
- [#:applications %standard-geoclue-applications]
- Return a service that runs the GeoClue location service. This service
- provides a D-Bus interface to allow applications to request access to a
- user's physical location, and optionally to add information to online
- location databases. See
- @uref{https://wiki.freedesktop.org/www/Software/GeoClue/, the GeoClue
- web site} for more information.
- @end deffn
- @deffn {Scheme Procedure} bluetooth-service [#:bluez @var{bluez}] @
- [@w{#:auto-enable? #f}]
- Return a service that runs the @command{bluetoothd} daemon, which
- manages all the Bluetooth devices and provides a number of D-Bus
- interfaces. When AUTO-ENABLE? is true, the bluetooth controller is
- powered automatically at boot, which can be useful when using a
- bluetooth keyboard or mouse.
- Users need to be in the @code{lp} group to access the D-Bus service.
- @end deffn
- @deffn {Scheme Variable} bluetooth-service-type
- This is the type for the @uref{https://bluez.org/, Linux Bluetooth Protocol
- Stack} (BlueZ) system, which generates the @file{/etc/bluetooth/main.conf}
- configuration file. The value for this type is a @command{bluetooth-configuration}
- record as in this example:
- @lisp
- (service bluetooth-service-type)
- @end lisp
- See below for details about @code{bluetooth-configuration}.
- @end deffn
- @deftp {Data Type} bluetooth-configuration
- Data type representing the configuration for @code{bluetooth-service}.
- @table @asis
- @item @code{bluez} (default: @code{bluez})
- @code{bluez} package to use.
- @item @code{name} (default: @code{"BlueZ"})
- Default adapter name.
- @item @code{class} (default: @code{#x000000})
- Default device class. Only the major and minor device class bits are considered.
- @item @code{discoverable-timeout} (default: @code{180})
- How long to stay in discoverable mode before going back to non-discoverable. The
- value is in seconds.
- @item @code{always-pairable?} (default: @code{#f})
- Always allow pairing even if there are no agents registered.
- @item @code{pairable-timeout} (default: @code{0})
- How long to stay in pairable mode before going back to non-discoverable. The
- value is in seconds.
- @item @code{device-id} (default: @code{#f})
- Use vendor id source (assigner), vendor, product and version information for
- DID profile support. The values are separated by ":" and @var{assigner}, @var{VID},
- @var{PID} and @var{version}.
- Possible values are:
- @itemize @bullet
- @item
- @code{#f} to disable it,
- @item
- @code{"assigner:1234:5678:abcd"}, where @var{assigner} is either @code{usb} (default)
- or @code{bluetooth}.
- @end itemize
- @item @code{reverse-service-discovery?} (default: @code{#t})
- Do reverse service discovery for previously unknown devices that connect to
- us. For BR/EDR this option is really only needed for qualification since the
- BITE tester doesn't like us doing reverse SDP for some test cases, for LE
- this disables the GATT client functionally so it can be used in system which
- can only operate as peripheral.
- @item @code{name-resolving?} (default: @code{#t})
- Enable name resolving after inquiry. Set it to @code{#f} if you don't need
- remote devices name and want shorter discovery cycle.
- @item @code{debug-keys?} (default: @code{#f})
- Enable runtime persistency of debug link keys. Default is false which makes
- debug link keys valid only for the duration of the connection that they were
- created for.
- @item @code{controller-mode} (default: @code{'dual})
- Restricts all controllers to the specified transport. @code{'dual} means both
- BR/EDR and LE are enabled (if supported by the hardware).
- Possible values are:
- @itemize @bullet
- @item
- @code{'dual}
- @item
- @code{'bredr}
- @item
- @code{'le}
- @end itemize
- @item @code{multi-profile} (default: @code{'off})
- Enables Multi Profile Specification support. This allows to specify if system
- supports only Multiple Profiles Single Device (MPSD) configuration or both
- Multiple Profiles Single Device (MPSD) and Multiple Profiles Multiple Devices
- (MPMD) configurations.
- Possible values are:
- @itemize @bullet
- @item
- @code{'off}
- @item
- @code{'single}
- @item
- @code{'multiple}
- @end itemize
- @item @code{fast-connectable?} (default: @code{#f})
- Permanently enables the Fast Connectable setting for adapters that support
- it. When enabled other devices can connect faster to us, however the
- tradeoff is increased power consumptions. This feature will fully work only
- on kernel version 4.1 and newer.
- @item @code{privacy} (default: @code{'off})
- Default privacy settings.
- @itemize @bullet
- @item
- @code{'off}: Disable local privacy
- @item
- @code{'network/on}: A device will only accept advertising packets from peer
- devices that contain private addresses. It may not be compatible with some
- legacy devices since it requires the use of RPA(s) all the time
- @item
- @code{'device}: A device in device privacy mode is only concerned about the
- privacy of the device and will accept advertising packets from peer devices
- that contain their Identity Address as well as ones that contain a private
- address, even if the peer device has distributed its IRK in the past
- @end itemize
- and additionally, if @var{controller-mode} is set to @code{'dual}:
- @itemize @bullet
- @item
- @code{'limited-network}: Apply Limited Discoverable Mode to advertising, which
- follows the same policy as to BR/EDR that publishes the identity address when
- discoverable, and Network Privacy Mode for scanning
- @item
- @code{'limited-device}: Apply Limited Discoverable Mode to advertising, which
- follows the same policy as to BR/EDR that publishes the identity address when
- discoverable, and Device Privacy Mode for scanning.
- @end itemize
- @item @code{just-works-repairing} (default: @code{'never})
- Specify the policy to the JUST-WORKS repairing initiated by peer.
- Possible values:
- @itemize @bullet
- @item
- @code{'never}
- @item
- @code{'confirm}
- @item
- @code{'always}
- @end itemize
- @item @code{temporary-timeout} (default: @code{30})
- How long to keep temporary devices around. The value is in seconds. @code{0}
- disables the timer completely.
- @item @code{refresh-discovery?} (default: @code{#t})
- Enables the device to issue an SDP request to update known services when
- profile is connected.
- @item @code{experimental} (default: @code{#f})
- Enables experimental features and interfaces, alternatively a list of UUIDs
- can be given.
- Possible values:
- @itemize @bullet
- @item
- @code{#t}
- @item
- @code{#f}
- @item
- @code{(list (uuid <uuid-1>) (uuid <uuid-2>) ...)}.
- @end itemize
- List of possible UUIDs:
- @itemize @bullet
- @item
- @code{d4992530-b9ec-469f-ab01-6c481c47da1c}: BlueZ Experimental Debug,
- @item
- @code{671b10b5-42c0-4696-9227-eb28d1b049d6}: BlueZ Experimental Simultaneous Central and Peripheral,
- @item
- @code{"15c0a148-c273-11ea-b3de-0242ac130004}: BlueZ Experimental LL privacy,
- @item
- @code{330859bc-7506-492d-9370-9a6f0614037f}: BlueZ Experimental Bluetooth Quality Report,
- @item
- @code{a6695ace-ee7f-4fb9-881a-5fac66c629af}: BlueZ Experimental Offload Codecs.
- @end itemize
- @item @code{remote-name-request-retry-delay} (default: @code{300})
- The duration to avoid retrying to resolve a peer's name, if the previous
- try failed.
- @item @code{page-scan-type} (default: @code{#f})
- BR/EDR Page scan activity type.
- @item @code{page-scan-interval} (default: @code{#f})
- BR/EDR Page scan activity interval.
- @item @code{page-scan-window} (default: @code{#f})
- BR/EDR Page scan activity window.
- @item @code{inquiry-scan-type} (default: @code{#f})
- BR/EDR Inquiry scan activity type.
- @item @code{inquiry-scan-interval} (default: @code{#f})
- BR/EDR Inquiry scan activity interval.
- @item @code{inquiry-scan-window} (default: @code{#f})
- BR/EDR Inquiry scan activity window.
- @item @code{link-supervision-timeout} (default: @code{#f})
- BR/EDR Link supervision timeout.
- @item @code{page-timeout} (default: @code{#f})
- BR/EDR Page timeout.
- @item @code{min-sniff-interval} (default: @code{#f})
- BR/EDR minimum sniff interval.
- @item @code{max-sniff-interval} (default: @code{#f})
- BR/EDR maximum sniff interval.
- @item @code{min-advertisement-interval} (default: @code{#f})
- LE minimum advertisement interval (used for legacy advertisement only).
- @item @code{max-advertisement-interval} (default: @code{#f})
- LE maximum advertisement interval (used for legacy advertisement only).
- @item @code{multi-advertisement-rotation-interval} (default: @code{#f})
- LE multiple advertisement rotation interval.
- @item @code{scan-interval-auto-connect} (default: @code{#f})
- LE scanning interval used for passive scanning supporting auto connect.
- @item @code{scan-window-auto-connect} (default: @code{#f})
- LE scanning window used for passive scanning supporting auto connect.
- @item @code{scan-interval-suspend} (default: @code{#f})
- LE scanning interval used for active scanning supporting wake from suspend.
- @item @code{scan-window-suspend} (default: @code{#f})
- LE scanning window used for active scanning supporting wake from suspend.
- @item @code{scan-interval-discovery} (default: @code{#f})
- LE scanning interval used for active scanning supporting discovery.
- @item @code{scan-window-discovery} (default: @code{#f})
- LE scanning window used for active scanning supporting discovery.
- @item @code{scan-interval-adv-monitor} (default: @code{#f})
- LE scanning interval used for passive scanning supporting the advertisement monitor APIs.
- @item @code{scan-window-adv-monitor} (default: @code{#f})
- LE scanning window used for passive scanning supporting the advertisement monitor APIs.
- @item @code{scan-interval-connect} (default: @code{#f})
- LE scanning interval used for connection establishment.
- @item @code{scan-window-connect} (default: @code{#f})
- LE scanning window used for connection establishment.
- @item @code{min-connection-interval} (default: @code{#f})
- LE default minimum connection interval. This value is superceeded by any specific
- value provided via the Load Connection Parameters interface.
- @item @code{max-connection-interval} (default: @code{#f})
- LE default maximum connection interval. This value is superceeded by any specific
- value provided via the Load Connection Parameters interface.
- @item @code{connection-latency} (default: @code{#f})
- LE default connection latency. This value is superceeded by any specific
- value provided via the Load Connection Parameters interface.
- @item @code{connection-supervision-timeout} (default: @code{#f})
- LE default connection supervision timeout. This value is superceeded by any specific
- value provided via the Load Connection Parameters interface.
- @item @code{autoconnect-timeout} (default: @code{#f})
- LE default autoconnect timeout. This value is superceeded by any specific
- value provided via the Load Connection Parameters interface.
- @item @code{adv-mon-allowlist-scan-duration} (default: @code{300})
- Allowlist scan duration during interleaving scan. Only used when scanning for ADV
- monitors. The units are msec.
- @item @code{adv-mon-no-filter-scan-duration} (default: @code{500})
- No filter scan duration during interleaving scan. Only used when scanning for ADV
- monitors. The units are msec.
- @item @code{enable-adv-mon-interleave-scan?} (default: @code{#t})
- Enable/Disable Advertisement Monitor interleave scan for power saving.
- @item @code{cache} (default: @code{'always})
- GATT attribute cache.
- Possible values are:
- @itemize @bullet
- @item
- @code{'always}: Always cache attributes even for devices not paired, this is
- recommended as it is best for interoperability, with more consistent
- reconnection times and enables proper tracking of notifications for all
- devices
- @item
- @code{'yes}: Only cache attributes of paired devices
- @item
- @code{'no}: Never cache attributes.
- @end itemize
- @item @code{key-size} (default: @code{0})
- Minimum required Encryption Key Size for accessing secured characteristics.
- Possible values are:
- @itemize @bullet
- @item
- @code{0}: Don't care
- @item
- @code{7 <= N <= 16}
- @end itemize
- @item @code{exchange-mtu} (default: @code{517})
- Exchange MTU size. Possible values are:
- @itemize @bullet
- @item
- @code{23 <= N <= 517}
- @end itemize
- @item @code{att-channels} (default: @code{3})
- Number of ATT channels. Possible values are:
- @itemize @bullet
- @item
- @code{1}: Disables EATT
- @item
- @code{2 <= N <= 5}
- @end itemize
- @item @code{session-mode} (default: @code{'basic})
- AVDTP L2CAP signalling channel mode.
- Possible values are:
- @itemize @bullet
- @item
- @code{'basic}: Use L2CAP basic mode
- @item
- @code{'ertm}: Use L2CAP enhanced retransmission mode.
- @end itemize
- @item @code{stream-mode} (default: @code{'basic})
- AVDTP L2CAP transport channel mode.
- Possible values are:
- @itemize @bullet
- @item
- @code{'basic}: Use L2CAP basic mode
- @item
- @code{'streaming}: Use L2CAP streaming mode.
- @end itemize
- @item @code{reconnect-uuids} (default: @code{'()})
- The ReconnectUUIDs defines the set of remote services that should try
- to be reconnected to in case of a link loss (link supervision
- timeout). The policy plugin should contain a sane set of values by
- default, but this list can be overridden here. By setting the list to
- empty the reconnection feature gets disabled.
- Possible values:
- @itemize @bullet
- @item
- @code{'()}
- @item
- @code{(list (uuid <uuid-1>) (uuid <uuid-2>) ...)}.
- @end itemize
- @item @code{reconnect-attempts} (default: @code{7})
- Defines the number of attempts to reconnect after a link lost. Setting
- the value to 0 disables reconnecting feature.
- @item @code{reconnect-intervals} (default: @code{'(1 2 4 8 16 32 64)})
- Defines a list of intervals in seconds to use in between attempts. If
- the number of attempts defined in @var{reconnect-attempts} is bigger than
- the list of intervals the last interval is repeated until the last attempt.
- @item @code{auto-enable?} (default: @code{#f})
- Defines option to enable all controllers when they are found. This includes
- adapters present on start as well as adapters that are plugged in later on.
- @item @code{resume-delay} (default: @code{2})
- Audio devices that were disconnected due to suspend will be reconnected on
- resume. @var{resume-delay} determines the delay between when the controller
- resumes from suspend and a connection attempt is made. A longer delay is
- better for better co-existence with Wi-Fi. The value is in seconds.
- @item @code{rssi-sampling-period} (default: @code{#xFF})
- Default RSSI Sampling Period. This is used when a client registers an
- advertisement monitor and leaves the RSSISamplingPeriod unset.
- Possible values are:
- @itemize @bullet
- @item
- @code{#x0}: Report all advertisements
- @item
- @code{N = #xXX}: Report advertisements every N x 100 msec (range: #x01 to #xFE)
- @item
- @code{#xFF}: Report only one advertisement per device during monitoring period.
- @end itemize
- @end table
- @end deftp
- @defvr {Scheme Variable} gnome-keyring-service-type
- This is the type of the service that adds the
- @uref{https://wiki.gnome.org/Projects/GnomeKeyring, GNOME Keyring}. Its
- value is a @code{gnome-keyring-configuration} object (see below).
- This service adds the @code{gnome-keyring} package to the system profile
- and extends PAM with entries using @code{pam_gnome_keyring.so}, unlocking
- a user's login keyring when they log in or setting its password with passwd.
- @end defvr
- @deftp {Data Type} gnome-keyring-configuration
- Configuration record for the GNOME Keyring service.
- @table @asis
- @item @code{keyring} (default: @code{gnome-keyring})
- The GNOME keyring package to use.
- @item @code{pam-services}
- A list of @code{(@var{service} . @var{kind})} pairs denoting PAM
- services to extend, where @var{service} is the name of an existing
- service to extend and @var{kind} is one of @code{login} or
- @code{passwd}.
- If @code{login} is given, it adds an optional
- @code{pam_gnome_keyring.so} to the auth block without arguments and to
- the session block with @code{auto_start}. If @code{passwd} is given, it
- adds an optional @code{pam_gnome_keyring.so} to the password block
- without arguments.
- By default, this field contains ``gdm-password'' with the value @code{login}
- and ``passwd'' is with the value @code{passwd}.
- @end table
- @end deftp
- @node Sound Services
- @subsection Sound Services
- @cindex sound support
- @cindex ALSA
- @cindex PulseAudio, sound support
- The @code{(gnu services sound)} module provides a service to configure the
- Advanced Linux Sound Architecture (ALSA) system, which makes PulseAudio the
- preferred ALSA output driver.
- @deffn {Scheme Variable} alsa-service-type
- This is the type for the @uref{https://alsa-project.org/, Advanced Linux Sound
- Architecture} (ALSA) system, which generates the @file{/etc/asound.conf}
- configuration file. The value for this type is a @command{alsa-configuration}
- record as in this example:
- @lisp
- (service alsa-service-type)
- @end lisp
- See below for details about @code{alsa-configuration}.
- @end deffn
- @deftp {Data Type} alsa-configuration
- Data type representing the configuration for @code{alsa-service}.
- @table @asis
- @item @code{alsa-plugins} (default: @var{alsa-plugins})
- @code{alsa-plugins} package to use.
- @item @code{pulseaudio?} (default: @var{#t})
- Whether ALSA applications should transparently be made to use the
- @uref{https://www.pulseaudio.org/, PulseAudio} sound server.
- Using PulseAudio allows you to run several sound-producing applications
- at the same time and to individual control them @i{via}
- @command{pavucontrol}, among other things.
- @item @code{extra-options} (default: @var{""})
- String to append to the @file{/etc/asound.conf} file.
- @end table
- @end deftp
- Individual users who want to override the system configuration of ALSA can do
- it with the @file{~/.asoundrc} file:
- @example
- # In guix, we have to specify the absolute path for plugins.
- pcm_type.jack @{
- lib "/home/alice/.guix-profile/lib/alsa-lib/libasound_module_pcm_jack.so"
- @}
- # Routing ALSA to jack:
- # <http://jackaudio.org/faq/routing_alsa.html>.
- pcm.rawjack @{
- type jack
- playback_ports @{
- 0 system:playback_1
- 1 system:playback_2
- @}
- capture_ports @{
- 0 system:capture_1
- 1 system:capture_2
- @}
- @}
- pcm.!default @{
- type plug
- slave @{
- pcm "rawjack"
- @}
- @}
- @end example
- See @uref{https://www.alsa-project.org/main/index.php/Asoundrc} for the
- details.
- @deffn {Scheme Variable} pulseaudio-service-type
- This is the type for the @uref{https://www.pulseaudio.org/, PulseAudio}
- sound server. It exists to allow system overrides of the default settings
- via @code{pulseaudio-configuration}, see below.
- @quotation Warning
- This service overrides per-user configuration files. If you want
- PulseAudio to honor configuration files in @file{~/.config/pulse} you
- have to unset the environment variables @env{PULSE_CONFIG} and
- @env{PULSE_CLIENTCONFIG} in your @file{~/.bash_profile}.
- @end quotation
- @quotation Warning
- This service on its own does not ensure, that the @code{pulseaudio} package
- exists on your machine. It merely adds configuration files for it, as
- detailed below. In the (admittedly unlikely) case, that you find yourself
- without a @code{pulseaudio} package, consider enabling it through the
- @code{alsa-service-type} above.
- @end quotation
- @end deffn
- @deftp {Data Type} pulseaudio-configuration
- Data type representing the configuration for @code{pulseaudio-service}.
- @table @asis
- @item @code{client-conf} (default: @code{'()})
- List of settings to set in @file{client.conf}.
- Accepts a list of strings or symbol-value pairs. A string will be
- inserted as-is with a newline added. A pair will be formatted as
- ``key = value'', again with a newline added.
- @item @code{daemon-conf} (default: @code{'((flat-volumes . no))})
- List of settings to set in @file{daemon.conf}, formatted just like
- @var{client-conf}.
- @item @code{script-file} (default: @code{(file-append pulseaudio "/etc/pulse/default.pa")})
- Script file to use as @file{default.pa}. In case the
- @code{extra-script-files} field below is used, an @code{.include}
- directive pointing to @file{/etc/pulse/default.pa.d} is appended to the
- provided script.
- @item @code{extra-script-files} (default: @code{'())})
- A list of file-like objects defining extra PulseAudio scripts to run at
- the initialization of the @command{pulseaudio} daemon, after the main
- @code{script-file}. The scripts are deployed to the
- @file{/etc/pulse/default.pa.d} directory; they should have the
- @samp{.pa} file name extension. For a reference of the available
- commands, refer to @command{man pulse-cli-syntax}.
- @item @code{system-script-file} (default: @code{(file-append pulseaudio "/etc/pulse/system.pa")})
- Script file to use as @file{system.pa}.
- @end table
- The example below sets the default PulseAudio card profile, the default
- sink and the default source to use for a old SoundBlaster Audigy sound
- card:
- @lisp
- (pulseaudio-configuration
- (extra-script-files
- (list (plain-file "audigy.pa"
- (string-append "\
- set-card-profile alsa_card.pci-0000_01_01.0 \
- output:analog-surround-40+input:analog-mono
- set-default-source alsa_input.pci-0000_01_01.0.analog-mono
- set-default-sink alsa_output.pci-0000_01_01.0.analog-surround-40\n")))))
- @end lisp
- Note that @code{pulseaudio-service-type} is part of
- @code{%desktop-services}; if your operating system declaration was
- derived from one of the desktop templates, you'll want to adjust the
- above example to modify the existing @code{pulseaudio-service-type} via
- @code{modify-services} (@pxref{Service Reference,
- @code{modify-services}}), instead of defining a new one.
- @end deftp
- @deffn {Scheme Variable} ladspa-service-type
- This service sets the @var{LADSPA_PATH} variable, so that programs, which
- respect it, e.g. PulseAudio, can load LADSPA plugins.
- The following example will setup the service to enable modules from the
- @code{swh-plugins} package:
- @lisp
- (service ladspa-service-type
- (ladspa-configuration (plugins (list swh-plugins))))
- @end lisp
- See @uref{http://plugin.org.uk/ladspa-swh/docs/ladspa-swh.html} for the
- details.
- @end deffn
- @node Database Services
- @subsection Database Services
- @cindex database
- @cindex SQL
- The @code{(gnu services databases)} module provides the following services.
- @subsubheading PostgreSQL
- The following example describes a PostgreSQL service with the default
- configuration.
- @lisp
- (service postgresql-service-type
- (postgresql-configuration
- (postgresql postgresql-10)))
- @end lisp
- If the services fails to start, it may be due to an incompatible
- cluster already present in @var{data-directory}. Adjust it (or, if you
- don't need the cluster anymore, delete @var{data-directory}), then
- restart the service.
- Peer authentication is used by default and the @code{postgres} user
- account has no shell, which prevents the direct execution of @code{psql}
- commands as this user. To use @code{psql}, you can temporarily log in
- as @code{postgres} using a shell, create a PostgreSQL superuser with the
- same name as one of the system users and then create the associated
- database.
- @example
- sudo -u postgres -s /bin/sh
- createuser --interactive
- createdb $MY_USER_LOGIN # Replace appropriately.
- @end example
- @deftp {Data Type} postgresql-configuration
- Data type representing the configuration for the
- @code{postgresql-service-type}.
- @table @asis
- @item @code{postgresql}
- PostgreSQL package to use for the service.
- @item @code{port} (default: @code{5432})
- Port on which PostgreSQL should listen.
- @item @code{locale} (default: @code{"en_US.utf8"})
- Locale to use as the default when creating the database cluster.
- @item @code{config-file} (default: @code{(postgresql-config-file)})
- The configuration file to use when running PostgreSQL@. The default
- behaviour uses the postgresql-config-file record with the default values
- for the fields.
- @item @code{log-directory} (default: @code{"/var/log/postgresql"})
- The directory where @command{pg_ctl} output will be written in a file
- named @code{"pg_ctl.log"}. This file can be useful to debug PostgreSQL
- configuration errors for instance.
- @item @code{data-directory} (default: @code{"/var/lib/postgresql/data"})
- Directory in which to store the data.
- @item @code{extension-packages} (default: @code{'()})
- @cindex postgresql extension-packages
- Additional extensions are loaded from packages listed in
- @var{extension-packages}. Extensions are available at runtime. For instance,
- to create a geographic database using the @code{postgis} extension, a user can
- configure the postgresql-service as in this example:
- @cindex postgis
- @lisp
- (use-package-modules databases geo)
- (operating-system
- ...
- ;; postgresql is required to run `psql' but postgis is not required for
- ;; proper operation.
- (packages (cons* postgresql %base-packages))
- (services
- (cons*
- (service postgresql-service-type
- (postgresql-configuration
- (postgresql postgresql-10)
- (extension-packages (list postgis))))
- %base-services)))
- @end lisp
- Then the extension becomes visible and you can initialise an empty geographic
- database in this way:
- @example
- psql -U postgres
- > create database postgistest;
- > \connect postgistest;
- > create extension postgis;
- > create extension postgis_topology;
- @end example
- There is no need to add this field for contrib extensions such as hstore or
- dblink as they are already loadable by postgresql. This field is only
- required to add extensions provided by other packages.
- @end table
- @end deftp
- @deftp {Data Type} postgresql-config-file
- Data type representing the PostgreSQL configuration file. As shown in
- the following example, this can be used to customize the configuration
- of PostgreSQL@. Note that you can use any G-expression or filename in
- place of this record, if you already have a configuration file you'd
- like to use for example.
- @lisp
- (service postgresql-service-type
- (postgresql-configuration
- (config-file
- (postgresql-config-file
- (log-destination "stderr")
- (hba-file
- (plain-file "pg_hba.conf"
- "
- local all all trust
- host all all 127.0.0.1/32 md5
- host all all ::1/128 md5"))
- (extra-config
- '(("session_preload_libraries" "auto_explain")
- ("random_page_cost" 2)
- ("auto_explain.log_min_duration" "100 ms")
- ("work_mem" "500 MB")
- ("logging_collector" #t)
- ("log_directory" "/var/log/postgresql")))))))
- @end lisp
- @table @asis
- @item @code{log-destination} (default: @code{"syslog"})
- The logging method to use for PostgreSQL@. Multiple values are accepted,
- separated by commas.
- @item @code{hba-file} (default: @code{%default-postgres-hba})
- Filename or G-expression for the host-based authentication
- configuration.
- @item @code{ident-file} (default: @code{%default-postgres-ident})
- Filename or G-expression for the user name mapping configuration.
- @item @code{socket-directory} (default: @code{"/var/run/postgresql"})
- Specifies the directory of the Unix-domain socket(s) on which PostgreSQL
- is to listen for connections from client applications. If set to
- @code{""} PostgreSQL does not listen on any Unix-domain sockets, in
- which case only TCP/IP sockets can be used to connect to the server.
- By default, the @code{#false} value means the PostgreSQL default value
- will be used, which is currently @samp{/tmp}.
- @item @code{extra-config} (default: @code{'()})
- List of additional keys and values to include in the PostgreSQL config
- file. Each entry in the list should be a list where the first element
- is the key, and the remaining elements are the values.
- The values can be numbers, booleans or strings and will be mapped to
- PostgreSQL parameters types @code{Boolean}, @code{String},
- @code{Numeric}, @code{Numeric with Unit} and @code{Enumerated} described
- @uref{https://www.postgresql.org/docs/current/config-setting.html,
- here}.
- @end table
- @end deftp
- @deffn {Scheme Variable} postgresql-role-service-type
- This service allows to create PostgreSQL roles and databases after
- PostgreSQL service start. Here is an example of its use.
- @lisp
- (service postgresql-role-service-type
- (postgresql-role-configuration
- (roles
- (list (postgresql-role
- (name "test")
- (create-database? #t))))))
- @end lisp
- This service can be extended with extra roles, as in this
- example:
- @lisp
- (service-extension postgresql-role-service-type
- (const (postgresql-role
- (name "alice")
- (create-database? #t))))
- @end lisp
- @end deffn
- @deftp {Data Type} postgresql-role
- PostgreSQL manages database access permissions using the concept of
- roles. A role can be thought of as either a database user, or a group
- of database users, depending on how the role is set up. Roles can own
- database objects (for example, tables) and can assign privileges on
- those objects to other roles to control who has access to which objects.
- @table @asis
- @item @code{name}
- The role name.
- @item @code{permissions} (default: @code{'(createdb login)})
- The role permissions list. Supported permissions are @code{bypassrls},
- @code{createdb}, @code{createrole}, @code{login}, @code{replication} and
- @code{superuser}.
- @item @code{create-database?} (default: @code{#f})
- Whether to create a database with the same name as the role.
- @end table
- @end deftp
- @deftp {Data Type} postgresql-role-configuration
- Data type representing the configuration of
- @var{postgresql-role-service-type}.
- @table @asis
- @item @code{host} (default: @code{"/var/run/postgresql"})
- The PostgreSQL host to connect to.
- @item @code{log} (default: @code{"/var/log/postgresql_roles.log"})
- File name of the log file.
- @item @code{roles} (default: @code{'()})
- The initial PostgreSQL roles to create.
- @end table
- @end deftp
- @subsubheading MariaDB/MySQL
- @defvr {Scheme Variable} mysql-service-type
- This is the service type for a MySQL or MariaDB database server. Its value
- is a @code{mysql-configuration} object that specifies which package to use,
- as well as various settings for the @command{mysqld} daemon.
- @end defvr
- @deftp {Data Type} mysql-configuration
- Data type representing the configuration of @var{mysql-service-type}.
- @table @asis
- @item @code{mysql} (default: @var{mariadb})
- Package object of the MySQL database server, can be either @var{mariadb}
- or @var{mysql}.
- For MySQL, a temporary root password will be displayed at activation time.
- For MariaDB, the root password is empty.
- @item @code{bind-address} (default: @code{"127.0.0.1"})
- The IP on which to listen for network connections. Use @code{"0.0.0.0"}
- to bind to all available network interfaces.
- @item @code{port} (default: @code{3306})
- TCP port on which the database server listens for incoming connections.
- @item @code{socket} (default: @code{"/run/mysqld/mysqld.sock"})
- Socket file to use for local (non-network) connections.
- @item @code{extra-content} (default: @code{""})
- Additional settings for the @file{my.cnf} configuration file.
- @item @code{extra-environment} (default: @code{#~'()})
- List of environment variables passed to the @command{mysqld} process.
- @item @code{auto-upgrade?} (default: @code{#t})
- Whether to automatically run @command{mysql_upgrade} after starting the
- service. This is necessary to upgrade the @dfn{system schema} after
- ``major'' updates (such as switching from MariaDB 10.4 to 10.5), but can
- be disabled if you would rather do that manually.
- @end table
- @end deftp
- @subsubheading Memcached
- @defvr {Scheme Variable} memcached-service-type
- This is the service type for the @uref{https://memcached.org/,
- Memcached} service, which provides a distributed in memory cache. The
- value for the service type is a @code{memcached-configuration} object.
- @end defvr
- @lisp
- (service memcached-service-type)
- @end lisp
- @deftp {Data Type} memcached-configuration
- Data type representing the configuration of memcached.
- @table @asis
- @item @code{memcached} (default: @code{memcached})
- The Memcached package to use.
- @item @code{interfaces} (default: @code{'("0.0.0.0")})
- Network interfaces on which to listen.
- @item @code{tcp-port} (default: @code{11211})
- Port on which to accept connections.
- @item @code{udp-port} (default: @code{11211})
- Port on which to accept UDP connections on, a value of 0 will disable
- listening on a UDP socket.
- @item @code{additional-options} (default: @code{'()})
- Additional command line options to pass to @code{memcached}.
- @end table
- @end deftp
- @subsubheading Redis
- @defvr {Scheme Variable} redis-service-type
- This is the service type for the @uref{https://redis.io/, Redis}
- key/value store, whose value is a @code{redis-configuration} object.
- @end defvr
- @deftp {Data Type} redis-configuration
- Data type representing the configuration of redis.
- @table @asis
- @item @code{redis} (default: @code{redis})
- The Redis package to use.
- @item @code{bind} (default: @code{"127.0.0.1"})
- Network interface on which to listen.
- @item @code{port} (default: @code{6379})
- Port on which to accept connections on, a value of 0 will disable
- listening on a TCP socket.
- @item @code{working-directory} (default: @code{"/var/lib/redis"})
- Directory in which to store the database and related files.
- @end table
- @end deftp
- @node Mail Services
- @subsection Mail Services
- @cindex mail
- @cindex email
- The @code{(gnu services mail)} module provides Guix service definitions
- for email services: IMAP, POP3, and LMTP servers, as well as mail
- transport agents (MTAs). Lots of acronyms! These services are detailed
- in the subsections below.
- @subsubheading Dovecot Service
- @deffn {Scheme Procedure} dovecot-service [#:config (dovecot-configuration)]
- Return a service that runs the Dovecot IMAP/POP3/LMTP mail server.
- @end deffn
- By default, Dovecot does not need much configuration; the default
- configuration object created by @code{(dovecot-configuration)} will
- suffice if your mail is delivered to @code{~/Maildir}. A self-signed
- certificate will be generated for TLS-protected connections, though
- Dovecot will also listen on cleartext ports by default. There are a
- number of options, though, which mail administrators might need to change,
- and as is the case with other services, Guix allows the system
- administrator to specify these parameters via a uniform Scheme interface.
- For example, to specify that mail is located at @code{maildir~/.mail},
- one would instantiate the Dovecot service like this:
- @lisp
- (dovecot-service #:config
- (dovecot-configuration
- (mail-location "maildir:~/.mail")))
- @end lisp
- The available configuration parameters follow. Each parameter
- definition is preceded by its type; for example, @samp{string-list foo}
- indicates that the @code{foo} parameter should be specified as a list of
- strings. There is also a way to specify the configuration as a string,
- if you have an old @code{dovecot.conf} file that you want to port over
- from some other system; see the end for more details.
- @c The following documentation was initially generated by
- @c (generate-documentation) in (gnu services mail). Manually maintained
- @c documentation is better, so we shouldn't hesitate to edit below as
- @c needed. However if the change you want to make to this documentation
- @c can be done in an automated way, it's probably easier to change
- @c (generate-documentation) than to make it below and have to deal with
- @c the churn as dovecot updates.
- Available @code{dovecot-configuration} fields are:
- @deftypevr {@code{dovecot-configuration} parameter} package dovecot
- The dovecot package.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} comma-separated-string-list listen
- A list of IPs or hosts where to listen for connections. @samp{*}
- listens on all IPv4 interfaces, @samp{::} listens on all IPv6
- interfaces. If you want to specify non-default ports or anything more
- complex, customize the address and port fields of the
- @samp{inet-listener} of the specific services you are interested in.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} protocol-configuration-list protocols
- List of protocols we want to serve. Available protocols include
- @samp{imap}, @samp{pop3}, and @samp{lmtp}.
- Available @code{protocol-configuration} fields are:
- @deftypevr {@code{protocol-configuration} parameter} string name
- The name of the protocol.
- @end deftypevr
- @deftypevr {@code{protocol-configuration} parameter} string auth-socket-path
- UNIX socket path to the master authentication server to find users.
- This is used by imap (for shared users) and lda.
- It defaults to @samp{"/var/run/dovecot/auth-userdb"}.
- @end deftypevr
- @deftypevr {@code{protocol-configuration} parameter} boolean imap-metadata?
- Whether to enable the @code{IMAP METADATA} extension as defined in
- @uref{https://tools.ietf.org/html/rfc5464,RFC@tie{}5464}, which provides
- a means for clients to set and retrieve per-mailbox, per-user metadata
- and annotations over IMAP.
- If this is @samp{#t}, you must also specify a dictionary @i{via} the
- @code{mail-attribute-dict} setting.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{protocol-configuration} parameter} space-separated-string-list managesieve-notify-capabilities
- Which NOTIFY capabilities to report to clients that first connect to
- the ManageSieve service, before authentication. These may differ from the
- capabilities offered to authenticated users. If this field is left empty,
- report what the Sieve interpreter supports by default.
- Defaults to @samp{()}.
- @end deftypevr
- @deftypevr {@code{protocol-configuration} parameter} space-separated-string-list managesieve-sieve-capability
- Which SIEVE capabilities to report to clients that first connect to
- the ManageSieve service, before authentication. These may differ from the
- capabilities offered to authenticated users. If this field is left empty,
- report what the Sieve interpreter supports by default.
- Defaults to @samp{()}.
- @end deftypevr
- @deftypevr {@code{protocol-configuration} parameter} space-separated-string-list mail-plugins
- Space separated list of plugins to load.
- @end deftypevr
- @deftypevr {@code{protocol-configuration} parameter} non-negative-integer mail-max-userip-connections
- Maximum number of IMAP connections allowed for a user from each IP
- address. NOTE: The username is compared case-sensitively.
- Defaults to @samp{10}.
- @end deftypevr
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} service-configuration-list services
- List of services to enable. Available services include @samp{imap},
- @samp{imap-login}, @samp{pop3}, @samp{pop3-login}, @samp{auth}, and
- @samp{lmtp}.
- Available @code{service-configuration} fields are:
- @deftypevr {@code{service-configuration} parameter} string kind
- The service kind. Valid values include @code{director},
- @code{imap-login}, @code{pop3-login}, @code{lmtp}, @code{imap},
- @code{pop3}, @code{auth}, @code{auth-worker}, @code{dict},
- @code{tcpwrap}, @code{quota-warning}, or anything else.
- @end deftypevr
- @deftypevr {@code{service-configuration} parameter} listener-configuration-list listeners
- Listeners for the service. A listener is either a
- @code{unix-listener-configuration}, a @code{fifo-listener-configuration}, or
- an @code{inet-listener-configuration}.
- Defaults to @samp{()}.
- Available @code{unix-listener-configuration} fields are:
- @deftypevr {@code{unix-listener-configuration} parameter} string path
- Path to the file, relative to @code{base-dir} field. This is also used as
- the section name.
- @end deftypevr
- @deftypevr {@code{unix-listener-configuration} parameter} string mode
- The access mode for the socket.
- Defaults to @samp{"0600"}.
- @end deftypevr
- @deftypevr {@code{unix-listener-configuration} parameter} string user
- The user to own the socket.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{unix-listener-configuration} parameter} string group
- The group to own the socket.
- Defaults to @samp{""}.
- @end deftypevr
- Available @code{fifo-listener-configuration} fields are:
- @deftypevr {@code{fifo-listener-configuration} parameter} string path
- Path to the file, relative to @code{base-dir} field. This is also used as
- the section name.
- @end deftypevr
- @deftypevr {@code{fifo-listener-configuration} parameter} string mode
- The access mode for the socket.
- Defaults to @samp{"0600"}.
- @end deftypevr
- @deftypevr {@code{fifo-listener-configuration} parameter} string user
- The user to own the socket.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{fifo-listener-configuration} parameter} string group
- The group to own the socket.
- Defaults to @samp{""}.
- @end deftypevr
- Available @code{inet-listener-configuration} fields are:
- @deftypevr {@code{inet-listener-configuration} parameter} string protocol
- The protocol to listen for.
- @end deftypevr
- @deftypevr {@code{inet-listener-configuration} parameter} string address
- The address on which to listen, or empty for all addresses.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{inet-listener-configuration} parameter} non-negative-integer port
- The port on which to listen.
- @end deftypevr
- @deftypevr {@code{inet-listener-configuration} parameter} boolean ssl?
- Whether to use SSL for this service; @samp{yes}, @samp{no}, or
- @samp{required}.
- Defaults to @samp{#t}.
- @end deftypevr
- @end deftypevr
- @deftypevr {@code{service-configuration} parameter} non-negative-integer client-limit
- Maximum number of simultaneous client connections per process. Once
- this number of connections is received, the next incoming connection
- will prompt Dovecot to spawn another process. If set to 0,
- @code{default-client-limit} is used instead.
- Defaults to @samp{0}.
- @end deftypevr
- @deftypevr {@code{service-configuration} parameter} non-negative-integer service-count
- Number of connections to handle before starting a new process.
- Typically the only useful values are 0 (unlimited) or 1. 1 is more
- secure, but 0 is faster. <doc/wiki/LoginProcess.txt>.
- Defaults to @samp{1}.
- @end deftypevr
- @deftypevr {@code{service-configuration} parameter} non-negative-integer process-limit
- Maximum number of processes that can exist for this service. If set to
- 0, @code{default-process-limit} is used instead.
- Defaults to @samp{0}.
- @end deftypevr
- @deftypevr {@code{service-configuration} parameter} non-negative-integer process-min-avail
- Number of processes to always keep waiting for more connections.
- Defaults to @samp{0}.
- @end deftypevr
- @deftypevr {@code{service-configuration} parameter} non-negative-integer vsz-limit
- If you set @samp{service-count 0}, you probably need to grow
- this.
- Defaults to @samp{256000000}.
- @end deftypevr
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} dict-configuration dict
- Dict configuration, as created by the @code{dict-configuration}
- constructor.
- Available @code{dict-configuration} fields are:
- @deftypevr {@code{dict-configuration} parameter} free-form-fields entries
- A list of key-value pairs that this dict should hold.
- Defaults to @samp{()}.
- @end deftypevr
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} passdb-configuration-list passdbs
- A list of passdb configurations, each one created by the
- @code{passdb-configuration} constructor.
- Available @code{passdb-configuration} fields are:
- @deftypevr {@code{passdb-configuration} parameter} string driver
- The driver that the passdb should use. Valid values include
- @samp{pam}, @samp{passwd}, @samp{shadow}, @samp{bsdauth}, and
- @samp{static}.
- Defaults to @samp{"pam"}.
- @end deftypevr
- @deftypevr {@code{passdb-configuration} parameter} space-separated-string-list args
- Space separated list of arguments to the passdb driver.
- Defaults to @samp{""}.
- @end deftypevr
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} userdb-configuration-list userdbs
- List of userdb configurations, each one created by the
- @code{userdb-configuration} constructor.
- Available @code{userdb-configuration} fields are:
- @deftypevr {@code{userdb-configuration} parameter} string driver
- The driver that the userdb should use. Valid values include
- @samp{passwd} and @samp{static}.
- Defaults to @samp{"passwd"}.
- @end deftypevr
- @deftypevr {@code{userdb-configuration} parameter} space-separated-string-list args
- Space separated list of arguments to the userdb driver.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{userdb-configuration} parameter} free-form-args override-fields
- Override fields from passwd.
- Defaults to @samp{()}.
- @end deftypevr
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} plugin-configuration plugin-configuration
- Plug-in configuration, created by the @code{plugin-configuration}
- constructor.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} list-of-namespace-configuration namespaces
- List of namespaces. Each item in the list is created by the
- @code{namespace-configuration} constructor.
- Available @code{namespace-configuration} fields are:
- @deftypevr {@code{namespace-configuration} parameter} string name
- Name for this namespace.
- @end deftypevr
- @deftypevr {@code{namespace-configuration} parameter} string type
- Namespace type: @samp{private}, @samp{shared} or @samp{public}.
- Defaults to @samp{"private"}.
- @end deftypevr
- @deftypevr {@code{namespace-configuration} parameter} string separator
- Hierarchy separator to use. You should use the same separator for
- all namespaces or some clients get confused. @samp{/} is usually a good
- one. The default however depends on the underlying mail storage
- format.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{namespace-configuration} parameter} string prefix
- Prefix required to access this namespace. This needs to be
- different for all namespaces. For example @samp{Public/}.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{namespace-configuration} parameter} string location
- Physical location of the mailbox. This is in the same format as
- mail_location, which is also the default for it.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{namespace-configuration} parameter} boolean inbox?
- There can be only one INBOX, and this setting defines which
- namespace has it.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{namespace-configuration} parameter} boolean hidden?
- If namespace is hidden, it's not advertised to clients via NAMESPACE
- extension. You'll most likely also want to set @samp{list? #f}. This is mostly
- useful when converting from another server with different namespaces
- which you want to deprecate but still keep working. For example you can
- create hidden namespaces with prefixes @samp{~/mail/}, @samp{~%u/mail/}
- and @samp{mail/}.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{namespace-configuration} parameter} boolean list?
- Show the mailboxes under this namespace with the LIST command. This
- makes the namespace visible for clients that do not support the NAMESPACE
- extension. The special @code{children} value lists child mailboxes, but
- hides the namespace prefix.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{namespace-configuration} parameter} boolean subscriptions?
- Namespace handles its own subscriptions. If set to @code{#f}, the
- parent namespace handles them. The empty prefix should always have this
- as @code{#t}).
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{namespace-configuration} parameter} mailbox-configuration-list mailboxes
- List of predefined mailboxes in this namespace.
- Defaults to @samp{()}.
- Available @code{mailbox-configuration} fields are:
- @deftypevr {@code{mailbox-configuration} parameter} string name
- Name for this mailbox.
- @end deftypevr
- @deftypevr {@code{mailbox-configuration} parameter} string auto
- @samp{create} will automatically create this mailbox.
- @samp{subscribe} will both create and subscribe to the mailbox.
- Defaults to @samp{"no"}.
- @end deftypevr
- @deftypevr {@code{mailbox-configuration} parameter} space-separated-string-list special-use
- List of IMAP @code{SPECIAL-USE} attributes as specified by RFC 6154.
- Valid values are @code{\All}, @code{\Archive}, @code{\Drafts},
- @code{\Flagged}, @code{\Junk}, @code{\Sent}, and @code{\Trash}.
- Defaults to @samp{()}.
- @end deftypevr
- @end deftypevr
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} file-name base-dir
- Base directory where to store runtime data.
- Defaults to @samp{"/var/run/dovecot/"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string login-greeting
- Greeting message for clients.
- Defaults to @samp{"Dovecot ready."}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list login-trusted-networks
- List of trusted network ranges. Connections from these IPs are
- allowed to override their IP addresses and ports (for logging and for
- authentication checks). @samp{disable-plaintext-auth} is also ignored
- for these networks. Typically you would specify your IMAP proxy servers
- here.
- Defaults to @samp{()}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list login-access-sockets
- List of login access check sockets (e.g.@: tcpwrap).
- Defaults to @samp{()}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean verbose-proctitle?
- Show more verbose process titles (in ps). Currently shows user name
- and IP address. Useful for seeing who is actually using the IMAP
- processes (e.g.@: shared mailboxes or if the same uid is used for multiple
- accounts).
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean shutdown-clients?
- Should all processes be killed when Dovecot master process shuts down.
- Setting this to @code{#f} means that Dovecot can be upgraded without
- forcing existing client connections to close (although that could also
- be a problem if the upgrade is e.g.@: due to a security fix).
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer doveadm-worker-count
- If non-zero, run mail commands via this many connections to doveadm
- server, instead of running them directly in the same process.
- Defaults to @samp{0}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string doveadm-socket-path
- UNIX socket or host:port used for connecting to doveadm server.
- Defaults to @samp{"doveadm-server"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list import-environment
- List of environment variables that are preserved on Dovecot startup
- and passed down to all of its child processes. You can also give
- key=value pairs to always set specific settings.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean disable-plaintext-auth?
- Disable LOGIN command and all other plaintext authentications unless
- SSL/TLS is used (LOGINDISABLED capability). Note that if the remote IP
- matches the local IP (i.e.@: you're connecting from the same computer),
- the connection is considered secure and plaintext authentication is
- allowed. See also ssl=required setting.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer auth-cache-size
- Authentication cache size (e.g.@: @samp{#e10e6}). 0 means it's disabled.
- Note that bsdauth, PAM and vpopmail require @samp{cache-key} to be set
- for caching to be used.
- Defaults to @samp{0}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string auth-cache-ttl
- Time to live for cached data. After TTL expires the cached record
- is no longer used, *except* if the main database lookup returns internal
- failure. We also try to handle password changes automatically: If
- user's previous authentication was successful, but this one wasn't, the
- cache isn't used. For now this works only with plaintext
- authentication.
- Defaults to @samp{"1 hour"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string auth-cache-negative-ttl
- TTL for negative hits (user not found, password mismatch).
- 0 disables caching them completely.
- Defaults to @samp{"1 hour"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list auth-realms
- List of realms for SASL authentication mechanisms that need them.
- You can leave it empty if you don't want to support multiple realms.
- Many clients simply use the first one listed here, so keep the default
- realm first.
- Defaults to @samp{()}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string auth-default-realm
- Default realm/domain to use if none was specified. This is used for
- both SASL realms and appending @@domain to username in plaintext
- logins.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string auth-username-chars
- List of allowed characters in username. If the user-given username
- contains a character not listed in here, the login automatically fails.
- This is just an extra check to make sure user can't exploit any
- potential quote escaping vulnerabilities with SQL/LDAP databases. If
- you want to allow all characters, set this value to empty.
- Defaults to @samp{"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ01234567890.-_@@"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string auth-username-translation
- Username character translations before it's looked up from
- databases. The value contains series of from -> to characters. For
- example @samp{#@@/@@} means that @samp{#} and @samp{/} characters are
- translated to @samp{@@}.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string auth-username-format
- Username formatting before it's looked up from databases. You can
- use the standard variables here, e.g.@: %Lu would lowercase the username,
- %n would drop away the domain if it was given, or @samp{%n-AT-%d} would
- change the @samp{@@} into @samp{-AT-}. This translation is done after
- @samp{auth-username-translation} changes.
- Defaults to @samp{"%Lu"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string auth-master-user-separator
- If you want to allow master users to log in by specifying the master
- username within the normal username string (i.e.@: not using SASL
- mechanism's support for it), you can specify the separator character
- here. The format is then <username><separator><master username>.
- UW-IMAP uses @samp{*} as the separator, so that could be a good
- choice.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string auth-anonymous-username
- Username to use for users logging in with ANONYMOUS SASL
- mechanism.
- Defaults to @samp{"anonymous"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer auth-worker-max-count
- Maximum number of dovecot-auth worker processes. They're used to
- execute blocking passdb and userdb queries (e.g.@: MySQL and PAM).
- They're automatically created and destroyed as needed.
- Defaults to @samp{30}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string auth-gssapi-hostname
- Host name to use in GSSAPI principal names. The default is to use
- the name returned by gethostname(). Use @samp{$ALL} (with quotes) to
- allow all keytab entries.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string auth-krb5-keytab
- Kerberos keytab to use for the GSSAPI mechanism. Will use the
- system default (usually @file{/etc/krb5.keytab}) if not specified. You may
- need to change the auth service to run as root to be able to read this
- file.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean auth-use-winbind?
- Do NTLM and GSS-SPNEGO authentication using Samba's winbind daemon
- and @samp{ntlm-auth} helper.
- <doc/wiki/Authentication/Mechanisms/Winbind.txt>.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} file-name auth-winbind-helper-path
- Path for Samba's @samp{ntlm-auth} helper binary.
- Defaults to @samp{"/usr/bin/ntlm_auth"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string auth-failure-delay
- Time to delay before replying to failed authentications.
- Defaults to @samp{"2 secs"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean auth-ssl-require-client-cert?
- Require a valid SSL client certificate or the authentication
- fails.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean auth-ssl-username-from-cert?
- Take the username from client's SSL certificate, using
- @code{X509_NAME_get_text_by_NID()} which returns the subject's DN's
- CommonName.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list auth-mechanisms
- List of wanted authentication mechanisms. Supported mechanisms are:
- @samp{plain}, @samp{login}, @samp{digest-md5}, @samp{cram-md5},
- @samp{ntlm}, @samp{rpa}, @samp{apop}, @samp{anonymous}, @samp{gssapi},
- @samp{otp}, @samp{skey}, and @samp{gss-spnego}. NOTE: See also
- @samp{disable-plaintext-auth} setting.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list director-servers
- List of IPs or hostnames to all director servers, including ourself.
- Ports can be specified as ip:port. The default port is the same as what
- director service's @samp{inet-listener} is using.
- Defaults to @samp{()}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list director-mail-servers
- List of IPs or hostnames to all backend mail servers. Ranges are
- allowed too, like 10.0.0.10-10.0.0.30.
- Defaults to @samp{()}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string director-user-expire
- How long to redirect users to a specific server after it no longer
- has any connections.
- Defaults to @samp{"15 min"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string director-username-hash
- How the username is translated before being hashed. Useful values
- include %Ln if user can log in with or without @@domain, %Ld if mailboxes
- are shared within domain.
- Defaults to @samp{"%Lu"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string log-path
- Log file to use for error messages. @samp{syslog} logs to syslog,
- @samp{/dev/stderr} logs to stderr.
- Defaults to @samp{"syslog"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string info-log-path
- Log file to use for informational messages. Defaults to
- @samp{log-path}.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string debug-log-path
- Log file to use for debug messages. Defaults to
- @samp{info-log-path}.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string syslog-facility
- Syslog facility to use if you're logging to syslog. Usually if you
- don't want to use @samp{mail}, you'll use local0..local7. Also other
- standard facilities are supported.
- Defaults to @samp{"mail"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean auth-verbose?
- Log unsuccessful authentication attempts and the reasons why they
- failed.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string auth-verbose-passwords
- In case of password mismatches, log the attempted password. Valid
- values are no, plain and sha1. sha1 can be useful for detecting brute
- force password attempts vs. user simply trying the same password over
- and over again. You can also truncate the value to n chars by appending
- ":n" (e.g.@: sha1:6).
- Defaults to @samp{"no"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean auth-debug?
- Even more verbose logging for debugging purposes. Shows for example
- SQL queries.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean auth-debug-passwords?
- In case of password mismatches, log the passwords and used scheme so
- the problem can be debugged. Enabling this also enables
- @samp{auth-debug}.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean mail-debug?
- Enable mail process debugging. This can help you figure out why
- Dovecot isn't finding your mails.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean verbose-ssl?
- Show protocol level SSL errors.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string log-timestamp
- Prefix for each line written to log file. % codes are in
- strftime(3) format.
- Defaults to @samp{"\"%b %d %H:%M:%S \""}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list login-log-format-elements
- List of elements we want to log. The elements which have a
- non-empty variable value are joined together to form a comma-separated
- string.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string login-log-format
- Login log format. %s contains @samp{login-log-format-elements}
- string, %$ contains the data we want to log.
- Defaults to @samp{"%$: %s"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string mail-log-prefix
- Log prefix for mail processes. See doc/wiki/Variables.txt for list
- of possible variables you can use.
- Defaults to @samp{"\"%s(%u)<%@{pid@}><%@{session@}>: \""}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string deliver-log-format
- Format to use for logging mail deliveries. You can use variables:
- @table @code
- @item %$
- Delivery status message (e.g.@: @samp{saved to INBOX})
- @item %m
- Message-ID
- @item %s
- Subject
- @item %f
- From address
- @item %p
- Physical size
- @item %w
- Virtual size.
- @end table
- Defaults to @samp{"msgid=%m: %$"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string mail-location
- Location for users' mailboxes. The default is empty, which means
- that Dovecot tries to find the mailboxes automatically. This won't work
- if the user doesn't yet have any mail, so you should explicitly tell
- Dovecot the full location.
- If you're using mbox, giving a path to the INBOX
- file (e.g.@: @file{/var/mail/%u}) isn't enough. You'll also need to tell Dovecot
- where the other mailboxes are kept. This is called the @emph{root mail
- directory}, and it must be the first path given in the
- @samp{mail-location} setting.
- There are a few special variables you can use, e.g.:
- @table @samp
- @item %u
- username
- @item %n
- user part in user@@domain, same as %u if there's no domain
- @item %d
- domain part in user@@domain, empty if there's no domain
- @item %h
- home director
- @end table
- See doc/wiki/Variables.txt for full list. Some examples:
- @table @samp
- @item maildir:~/Maildir
- @item mbox:~/mail:INBOX=/var/mail/%u
- @item mbox:/var/mail/%d/%1n/%n:INDEX=/var/indexes/%d/%1n/%
- @end table
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string mail-uid
- System user and group used to access mails. If you use multiple,
- userdb can override these by returning uid or gid fields. You can use
- either numbers or names. <doc/wiki/UserIds.txt>.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string mail-gid
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string mail-privileged-group
- Group to enable temporarily for privileged operations. Currently
- this is used only with INBOX when either its initial creation or
- dotlocking fails. Typically this is set to @samp{"mail"} to give access to
- @file{/var/mail}.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string mail-access-groups
- Grant access to these supplementary groups for mail processes.
- Typically these are used to set up access to shared mailboxes. Note
- that it may be dangerous to set these if users can create symlinks
- (e.g.@: if @samp{mail} group is set here, @code{ln -s /var/mail ~/mail/var}
- could allow a user to delete others' mailboxes, or @code{ln -s
- /secret/shared/box ~/mail/mybox} would allow reading it). Defaults to
- @samp{""}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string mail-attribute-dict
- The location of a dictionary used to store @code{IMAP METADATA}
- as defined by @uref{https://tools.ietf.org/html/rfc5464, RFC@tie{}5464}.
- The IMAP METADATA commands are available only if the ``imap''
- protocol configuration's @code{imap-metadata?} field is @samp{#t}.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean mail-full-filesystem-access?
- Allow full file system access to clients. There's no access checks
- other than what the operating system does for the active UID/GID@. It
- works with both maildir and mboxes, allowing you to prefix mailboxes
- names with e.g.@: @file{/path/} or @file{~user/}.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean mmap-disable?
- Don't use @code{mmap()} at all. This is required if you store indexes to
- shared file systems (NFS or clustered file system).
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean dotlock-use-excl?
- Rely on @samp{O_EXCL} to work when creating dotlock files. NFS
- supports @samp{O_EXCL} since version 3, so this should be safe to use
- nowadays by default.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string mail-fsync
- When to use fsync() or fdatasync() calls:
- @table @code
- @item optimized
- Whenever necessary to avoid losing important data
- @item always
- Useful with e.g.@: NFS when @code{write()}s are delayed
- @item never
- Never use it (best performance, but crashes can lose data).
- @end table
- Defaults to @samp{"optimized"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean mail-nfs-storage?
- Mail storage exists in NFS@. Set this to yes to make Dovecot flush
- NFS caches whenever needed. If you're using only a single mail server
- this isn't needed.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean mail-nfs-index?
- Mail index files also exist in NFS@. Setting this to yes requires
- @samp{mmap-disable? #t} and @samp{fsync-disable? #f}.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string lock-method
- Locking method for index files. Alternatives are fcntl, flock and
- dotlock. Dotlocking uses some tricks which may create more disk I/O
- than other locking methods. NFS users: flock doesn't work, remember to
- change @samp{mmap-disable}.
- Defaults to @samp{"fcntl"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} file-name mail-temp-dir
- Directory in which LDA/LMTP temporarily stores incoming mails >128
- kB.
- Defaults to @samp{"/tmp"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer first-valid-uid
- Valid UID range for users. This is mostly to make sure that users can't
- log in as daemons or other system users. Note that denying root logins is
- hardcoded to dovecot binary and can't be done even if @samp{first-valid-uid}
- is set to 0.
- Defaults to @samp{500}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer last-valid-uid
- Defaults to @samp{0}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer first-valid-gid
- Valid GID range for users. Users having non-valid GID as primary group ID
- aren't allowed to log in. If user belongs to supplementary groups with
- non-valid GIDs, those groups are not set.
- Defaults to @samp{1}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer last-valid-gid
- Defaults to @samp{0}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mail-max-keyword-length
- Maximum allowed length for mail keyword name. It's only forced when
- trying to create new keywords.
- Defaults to @samp{50}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} colon-separated-file-name-list valid-chroot-dirs
- List of directories under which chrooting is allowed for mail
- processes (i.e.@: @file{/var/mail} will allow chrooting to @file{/var/mail/foo/bar}
- too). This setting doesn't affect @samp{login-chroot}
- @samp{mail-chroot} or auth chroot settings. If this setting is empty,
- @samp{/./} in home dirs are ignored. WARNING: Never add directories here
- which local users can modify, that may lead to root exploit. Usually
- this should be done only if you don't allow shell access for users.
- <doc/wiki/Chrooting.txt>.
- Defaults to @samp{()}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string mail-chroot
- Default chroot directory for mail processes. This can be overridden
- for specific users in user database by giving @samp{/./} in user's home
- directory (e.g.@: @samp{/home/./user} chroots into @file{/home}). Note that usually
- there is no real need to do chrooting, Dovecot doesn't allow users to
- access files outside their mail directory anyway. If your home
- directories are prefixed with the chroot directory, append @samp{/.} to
- @samp{mail-chroot}. <doc/wiki/Chrooting.txt>.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} file-name auth-socket-path
- UNIX socket path to master authentication server to find users.
- This is used by imap (for shared users) and lda.
- Defaults to @samp{"/var/run/dovecot/auth-userdb"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} file-name mail-plugin-dir
- Directory where to look up mail plugins.
- Defaults to @samp{"/usr/lib/dovecot"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list mail-plugins
- List of plugins to load for all services. Plugins specific to IMAP,
- LDA, etc.@: are added to this list in their own .conf files.
- Defaults to @samp{()}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mail-cache-min-mail-count
- The minimum number of mails in a mailbox before updates are done to
- cache file. This allows optimizing Dovecot's behavior to do less disk
- writes at the cost of more disk reads.
- Defaults to @samp{0}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string mailbox-idle-check-interval
- When IDLE command is running, mailbox is checked once in a while to
- see if there are any new mails or other changes. This setting defines
- the minimum time to wait between those checks. Dovecot can also use
- dnotify, inotify and kqueue to find out immediately when changes
- occur.
- Defaults to @samp{"30 secs"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean mail-save-crlf?
- Save mails with CR+LF instead of plain LF@. This makes sending those
- mails take less CPU, especially with sendfile() syscall with Linux and
- FreeBSD@. But it also creates a bit more disk I/O which may just make it
- slower. Also note that if other software reads the mboxes/maildirs,
- they may handle the extra CRs wrong and cause problems.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean maildir-stat-dirs?
- By default LIST command returns all entries in maildir beginning
- with a dot. Enabling this option makes Dovecot return only entries
- which are directories. This is done by stat()ing each entry, so it
- causes more disk I/O.
- (For systems setting struct @samp{dirent->d_type} this check is free
- and it's done always regardless of this setting).
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean maildir-copy-with-hardlinks?
- When copying a message, do it with hard links whenever possible.
- This makes the performance much better, and it's unlikely to have any
- side effects.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean maildir-very-dirty-syncs?
- Assume Dovecot is the only MUA accessing Maildir: Scan cur/
- directory only when its mtime changes unexpectedly or when we can't find
- the mail otherwise.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list mbox-read-locks
- Which locking methods to use for locking mbox. There are four
- available:
- @table @code
- @item dotlock
- Create <mailbox>.lock file. This is the oldest and most NFS-safe
- solution. If you want to use /var/mail/ like directory, the users will
- need write access to that directory.
- @item dotlock-try
- Same as dotlock, but if it fails because of permissions or because there
- isn't enough disk space, just skip it.
- @item fcntl
- Use this if possible. Works with NFS too if lockd is used.
- @item flock
- May not exist in all systems. Doesn't work with NFS.
- @item lockf
- May not exist in all systems. Doesn't work with NFS.
- @end table
- You can use multiple locking methods; if you do the order they're declared
- in is important to avoid deadlocks if other MTAs/MUAs are using multiple
- locking methods as well. Some operating systems don't allow using some of
- them simultaneously.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list mbox-write-locks
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string mbox-lock-timeout
- Maximum time to wait for lock (all of them) before aborting.
- Defaults to @samp{"5 mins"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string mbox-dotlock-change-timeout
- If dotlock exists but the mailbox isn't modified in any way,
- override the lock file after this much time.
- Defaults to @samp{"2 mins"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean mbox-dirty-syncs?
- When mbox changes unexpectedly we have to fully read it to find out
- what changed. If the mbox is large this can take a long time. Since
- the change is usually just a newly appended mail, it'd be faster to
- simply read the new mails. If this setting is enabled, Dovecot does
- this but still safely fallbacks to re-reading the whole mbox file
- whenever something in mbox isn't how it's expected to be. The only real
- downside to this setting is that if some other MUA changes message
- flags, Dovecot doesn't notice it immediately. Note that a full sync is
- done with SELECT, EXAMINE, EXPUNGE and CHECK commands.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean mbox-very-dirty-syncs?
- Like @samp{mbox-dirty-syncs}, but don't do full syncs even with SELECT,
- EXAMINE, EXPUNGE or CHECK commands. If this is set,
- @samp{mbox-dirty-syncs} is ignored.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean mbox-lazy-writes?
- Delay writing mbox headers until doing a full write sync (EXPUNGE
- and CHECK commands and when closing the mailbox). This is especially
- useful for POP3 where clients often delete all mails. The downside is
- that our changes aren't immediately visible to other MUAs.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mbox-min-index-size
- If mbox size is smaller than this (e.g.@: 100k), don't write index
- files. If an index file already exists it's still read, just not
- updated.
- Defaults to @samp{0}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mdbox-rotate-size
- Maximum dbox file size until it's rotated.
- Defaults to @samp{10000000}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string mdbox-rotate-interval
- Maximum dbox file age until it's rotated. Typically in days. Day
- begins from midnight, so 1d = today, 2d = yesterday, etc. 0 = check
- disabled.
- Defaults to @samp{"1d"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean mdbox-preallocate-space?
- When creating new mdbox files, immediately preallocate their size to
- @samp{mdbox-rotate-size}. This setting currently works only in Linux
- with some file systems (ext4, xfs).
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string mail-attachment-dir
- sdbox and mdbox support saving mail attachments to external files,
- which also allows single instance storage for them. Other backends
- don't support this for now.
- WARNING: This feature hasn't been tested much yet. Use at your own risk.
- Directory root where to store mail attachments. Disabled, if empty.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mail-attachment-min-size
- Attachments smaller than this aren't saved externally. It's also
- possible to write a plugin to disable saving specific attachments
- externally.
- Defaults to @samp{128000}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string mail-attachment-fs
- File system backend to use for saving attachments:
- @table @code
- @item posix
- No SiS done by Dovecot (but this might help FS's own deduplication)
- @item sis posix
- SiS with immediate byte-by-byte comparison during saving
- @item sis-queue posix
- SiS with delayed comparison and deduplication.
- @end table
- Defaults to @samp{"sis posix"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string mail-attachment-hash
- Hash format to use in attachment filenames. You can add any text and
- variables: @code{%@{md4@}}, @code{%@{md5@}}, @code{%@{sha1@}},
- @code{%@{sha256@}}, @code{%@{sha512@}}, @code{%@{size@}}. Variables can be
- truncated, e.g.@: @code{%@{sha256:80@}} returns only first 80 bits.
- Defaults to @samp{"%@{sha1@}"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer default-process-limit
- Defaults to @samp{100}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer default-client-limit
- Defaults to @samp{1000}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer default-vsz-limit
- Default VSZ (virtual memory size) limit for service processes.
- This is mainly intended to catch and kill processes that leak memory
- before they eat up everything.
- Defaults to @samp{256000000}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string default-login-user
- Login user is internally used by login processes. This is the most
- untrusted user in Dovecot system. It shouldn't have access to anything
- at all.
- Defaults to @samp{"dovenull"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string default-internal-user
- Internal user is used by unprivileged processes. It should be
- separate from login user, so that login processes can't disturb other
- processes.
- Defaults to @samp{"dovecot"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string ssl?
- SSL/TLS support: yes, no, required. <doc/wiki/SSL.txt>.
- Defaults to @samp{"required"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string ssl-cert
- PEM encoded X.509 SSL/TLS certificate (public key).
- Defaults to @samp{"</etc/dovecot/default.pem"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string ssl-key
- PEM encoded SSL/TLS private key. The key is opened before
- dropping root privileges, so keep the key file unreadable by anyone but
- root.
- Defaults to @samp{"</etc/dovecot/private/default.pem"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string ssl-key-password
- If key file is password protected, give the password here.
- Alternatively give it when starting dovecot with -p parameter. Since
- this file is often world-readable, you may want to place this setting
- instead to a different.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string ssl-ca
- PEM encoded trusted certificate authority. Set this only if you
- intend to use @samp{ssl-verify-client-cert? #t}. The file should
- contain the CA certificate(s) followed by the matching
- CRL(s). (e.g.@: @samp{ssl-ca </etc/ssl/certs/ca.pem}).
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean ssl-require-crl?
- Require that CRL check succeeds for client certificates.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean ssl-verify-client-cert?
- Request client to send a certificate. If you also want to require
- it, set @samp{auth-ssl-require-client-cert? #t} in auth section.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string ssl-cert-username-field
- Which field from certificate to use for username. commonName and
- x500UniqueIdentifier are the usual choices. You'll also need to set
- @samp{auth-ssl-username-from-cert? #t}.
- Defaults to @samp{"commonName"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string ssl-min-protocol
- Minimum SSL protocol version to accept.
- Defaults to @samp{"TLSv1"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string ssl-cipher-list
- SSL ciphers to use.
- Defaults to @samp{"ALL:!kRSA:!SRP:!kDHd:!DSS:!aNULL:!eNULL:!EXPORT:!DES:!3DES:!MD5:!PSK:!RC4:!ADH:!LOW@@STRENGTH"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string ssl-crypto-device
- SSL crypto device to use, for valid values run "openssl engine".
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string postmaster-address
- Address to use when sending rejection mails.
- %d expands to recipient domain.
- Defaults to @samp{"postmaster@@%d"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string hostname
- Hostname to use in various parts of sent mails (e.g.@: in Message-Id)
- and in LMTP replies. Default is the system's real hostname@@domain.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean quota-full-tempfail?
- If user is over quota, return with temporary failure instead of
- bouncing the mail.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} file-name sendmail-path
- Binary to use for sending mails.
- Defaults to @samp{"/usr/sbin/sendmail"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string submission-host
- If non-empty, send mails via this SMTP host[:port] instead of
- sendmail.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string rejection-subject
- Subject: header to use for rejection mails. You can use the same
- variables as for @samp{rejection-reason} below.
- Defaults to @samp{"Rejected: %s"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string rejection-reason
- Human readable error message for rejection mails. You can use
- variables:
- @table @code
- @item %n
- CRLF
- @item %r
- reason
- @item %s
- original subject
- @item %t
- recipient
- @end table
- Defaults to @samp{"Your message to <%t> was automatically rejected:%n%r"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string recipient-delimiter
- Delimiter character between local-part and detail in email
- address.
- Defaults to @samp{"+"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string lda-original-recipient-header
- Header where the original recipient address (SMTP's RCPT TO:
- address) is taken from if not available elsewhere. With dovecot-lda -a
- parameter overrides this. A commonly used header for this is
- X-Original-To.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean lda-mailbox-autocreate?
- Should saving a mail to a nonexistent mailbox automatically create
- it?.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean lda-mailbox-autosubscribe?
- Should automatically created mailboxes be also automatically
- subscribed?.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer imap-max-line-length
- Maximum IMAP command line length. Some clients generate very long
- command lines with huge mailboxes, so you may need to raise this if you
- get "Too long argument" or "IMAP command line too large" errors
- often.
- Defaults to @samp{64000}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string imap-logout-format
- IMAP logout format string:
- @table @code
- @item %i
- total number of bytes read from client
- @item %o
- total number of bytes sent to client.
- @end table
- See @file{doc/wiki/Variables.txt} for a list of all the variables you can use.
- Defaults to @samp{"in=%i out=%o deleted=%@{deleted@} expunged=%@{expunged@} trashed=%@{trashed@} hdr_count=%@{fetch_hdr_count@} hdr_bytes=%@{fetch_hdr_bytes@} body_count=%@{fetch_body_count@} body_bytes=%@{fetch_body_bytes@}"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string imap-capability
- Override the IMAP CAPABILITY response. If the value begins with '+',
- add the given capabilities on top of the defaults (e.g.@: +XFOO XBAR).
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string imap-idle-notify-interval
- How long to wait between "OK Still here" notifications when client
- is IDLEing.
- Defaults to @samp{"2 mins"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string imap-id-send
- ID field names and values to send to clients. Using * as the value
- makes Dovecot use the default value. The following fields have default
- values currently: name, version, os, os-version, support-url,
- support-email.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string imap-id-log
- ID fields sent by client to log. * means everything.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list imap-client-workarounds
- Workarounds for various client bugs:
- @table @code
- @item delay-newmail
- Send EXISTS/RECENT new mail notifications only when replying to NOOP and
- CHECK commands. Some clients ignore them otherwise, for example OSX
- Mail (<v2.1). Outlook Express breaks more badly though, without this it
- may show user "Message no longer in server" errors. Note that OE6
- still breaks even with this workaround if synchronization is set to
- "Headers Only".
- @item tb-extra-mailbox-sep
- Thunderbird gets somehow confused with LAYOUT=fs (mbox and dbox) and
- adds extra @samp{/} suffixes to mailbox names. This option causes Dovecot to
- ignore the extra @samp{/} instead of treating it as invalid mailbox name.
- @item tb-lsub-flags
- Show \Noselect flags for LSUB replies with LAYOUT=fs (e.g.@: mbox).
- This makes Thunderbird realize they aren't selectable and show them
- greyed out, instead of only later giving "not selectable" popup error.
- @end table
- Defaults to @samp{()}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string imap-urlauth-host
- Host allowed in URLAUTH URLs sent by client. "*" allows all.
- Defaults to @samp{""}.
- @end deftypevr
- Whew! Lots of configuration options. The nice thing about it though is
- that Guix has a complete interface to Dovecot's configuration
- language. This allows not only a nice way to declare configurations,
- but also offers reflective capabilities as well: users can write code to
- inspect and transform configurations from within Scheme.
- However, it could be that you just want to get a @code{dovecot.conf} up
- and running. In that case, you can pass an
- @code{opaque-dovecot-configuration} as the @code{#:config} parameter to
- @code{dovecot-service}. As its name indicates, an opaque configuration
- does not have easy reflective capabilities.
- Available @code{opaque-dovecot-configuration} fields are:
- @deftypevr {@code{opaque-dovecot-configuration} parameter} package dovecot
- The dovecot package.
- @end deftypevr
- @deftypevr {@code{opaque-dovecot-configuration} parameter} string string
- The contents of the @code{dovecot.conf}, as a string.
- @end deftypevr
- For example, if your @code{dovecot.conf} is just the empty string, you
- could instantiate a dovecot service like this:
- @lisp
- (dovecot-service #:config
- (opaque-dovecot-configuration
- (string "")))
- @end lisp
- @subsubheading OpenSMTPD Service
- @deffn {Scheme Variable} opensmtpd-service-type
- This is the type of the @uref{https://www.opensmtpd.org, OpenSMTPD}
- service, whose value should be an @code{opensmtpd-configuration} object
- as in this example:
- @lisp
- (service opensmtpd-service-type
- (opensmtpd-configuration
- (config-file (local-file "./my-smtpd.conf"))))
- @end lisp
- @end deffn
- @deftp {Data Type} opensmtpd-configuration
- Data type representing the configuration of opensmtpd.
- @table @asis
- @item @code{package} (default: @var{opensmtpd})
- Package object of the OpenSMTPD SMTP server.
- @item @code{config-file} (default: @code{%default-opensmtpd-config-file})
- File-like object of the OpenSMTPD configuration file to use. By default
- it listens on the loopback network interface, and allows for mail from
- users and daemons on the local machine, as well as permitting email to
- remote servers. Run @command{man smtpd.conf} for more information.
- @end table
- @end deftp
- @subsubheading Exim Service
- @cindex mail transfer agent (MTA)
- @cindex MTA (mail transfer agent)
- @cindex SMTP
- @deffn {Scheme Variable} exim-service-type
- This is the type of the @uref{https://exim.org, Exim} mail transfer
- agent (MTA), whose value should be an @code{exim-configuration} object
- as in this example:
- @lisp
- (service exim-service-type
- (exim-configuration
- (config-file (local-file "./my-exim.conf"))))
- @end lisp
- @end deffn
- In order to use an @code{exim-service-type} service you must also have a
- @code{mail-aliases-service-type} service present in your
- @code{operating-system} (even if it has no aliases).
- @deftp {Data Type} exim-configuration
- Data type representing the configuration of exim.
- @table @asis
- @item @code{package} (default: @var{exim})
- Package object of the Exim server.
- @item @code{config-file} (default: @code{#f})
- File-like object of the Exim configuration file to use. If its value is
- @code{#f} then use the default configuration file from the package
- provided in @code{package}. The resulting configuration file is loaded
- after setting the @code{exim_user} and @code{exim_group} configuration
- variables.
- @end table
- @end deftp
- @subsubheading Getmail service
- @cindex IMAP
- @cindex POP
- @deffn {Scheme Variable} getmail-service-type
- This is the type of the @uref{http://pyropus.ca/software/getmail/, Getmail}
- mail retriever, whose value should be an @code{getmail-configuration}.
- @end deffn
- Available @code{getmail-configuration} fields are:
- @deftypevr {@code{getmail-configuration} parameter} symbol name
- A symbol to identify the getmail service.
- Defaults to @samp{"unset"}.
- @end deftypevr
- @deftypevr {@code{getmail-configuration} parameter} package package
- The getmail package to use.
- @end deftypevr
- @deftypevr {@code{getmail-configuration} parameter} string user
- The user to run getmail as.
- Defaults to @samp{"getmail"}.
- @end deftypevr
- @deftypevr {@code{getmail-configuration} parameter} string group
- The group to run getmail as.
- Defaults to @samp{"getmail"}.
- @end deftypevr
- @deftypevr {@code{getmail-configuration} parameter} string directory
- The getmail directory to use.
- Defaults to @samp{"/var/lib/getmail/default"}.
- @end deftypevr
- @deftypevr {@code{getmail-configuration} parameter} getmail-configuration-file rcfile
- The getmail configuration file to use.
- Available @code{getmail-configuration-file} fields are:
- @deftypevr {@code{getmail-configuration-file} parameter} getmail-retriever-configuration retriever
- What mail account to retrieve mail from, and how to access that account.
- Available @code{getmail-retriever-configuration} fields are:
- @deftypevr {@code{getmail-retriever-configuration} parameter} string type
- The type of mail retriever to use. Valid values include @samp{passwd}
- and @samp{static}.
- Defaults to @samp{"SimpleIMAPSSLRetriever"}.
- @end deftypevr
- @deftypevr {@code{getmail-retriever-configuration} parameter} string server
- Username to login to the mail server with.
- Defaults to @samp{unset}.
- @end deftypevr
- @deftypevr {@code{getmail-retriever-configuration} parameter} string username
- Username to login to the mail server with.
- Defaults to @samp{unset}.
- @end deftypevr
- @deftypevr {@code{getmail-retriever-configuration} parameter} non-negative-integer port
- Port number to connect to.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{getmail-retriever-configuration} parameter} string password
- Override fields from passwd.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{getmail-retriever-configuration} parameter} list password-command
- Override fields from passwd.
- Defaults to @samp{()}.
- @end deftypevr
- @deftypevr {@code{getmail-retriever-configuration} parameter} string keyfile
- PEM-formatted key file to use for the TLS negotiation.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{getmail-retriever-configuration} parameter} string certfile
- PEM-formatted certificate file to use for the TLS negotiation.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{getmail-retriever-configuration} parameter} string ca-certs
- CA certificates to use.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{getmail-retriever-configuration} parameter} parameter-alist extra-parameters
- Extra retriever parameters.
- Defaults to @samp{()}.
- @end deftypevr
- @end deftypevr
- @deftypevr {@code{getmail-configuration-file} parameter} getmail-destination-configuration destination
- What to do with retrieved messages.
- Available @code{getmail-destination-configuration} fields are:
- @deftypevr {@code{getmail-destination-configuration} parameter} string type
- The type of mail destination. Valid values include @samp{Maildir},
- @samp{Mboxrd} and @samp{MDA_external}.
- Defaults to @samp{unset}.
- @end deftypevr
- @deftypevr {@code{getmail-destination-configuration} parameter} string-or-filelike path
- The path option for the mail destination. The behaviour depends on the
- chosen type.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{getmail-destination-configuration} parameter} parameter-alist extra-parameters
- Extra destination parameters
- Defaults to @samp{()}.
- @end deftypevr
- @end deftypevr
- @deftypevr {@code{getmail-configuration-file} parameter} getmail-options-configuration options
- Configure getmail.
- Available @code{getmail-options-configuration} fields are:
- @deftypevr {@code{getmail-options-configuration} parameter} non-negative-integer verbose
- If set to @samp{0}, getmail will only print warnings and errors. A
- value of @samp{1} means that messages will be printed about retrieving
- and deleting messages. If set to @samp{2}, getmail will print messages
- about each of its actions.
- Defaults to @samp{1}.
- @end deftypevr
- @deftypevr {@code{getmail-options-configuration} parameter} boolean read-all
- If true, getmail will retrieve all available messages. Otherwise it
- will only retrieve messages it hasn't seen previously.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{getmail-options-configuration} parameter} boolean delete
- If set to true, messages will be deleted from the server after
- retrieving and successfully delivering them. Otherwise, messages will
- be left on the server.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{getmail-options-configuration} parameter} non-negative-integer delete-after
- Getmail will delete messages this number of days after seeing them, if
- they have been delivered. This means messages will be left on the
- server this number of days after delivering them. A value of @samp{0}
- disabled this feature.
- Defaults to @samp{0}.
- @end deftypevr
- @deftypevr {@code{getmail-options-configuration} parameter} non-negative-integer delete-bigger-than
- Delete messages larger than this of bytes after retrieving them, even if
- the delete and delete-after options are disabled. A value of @samp{0}
- disables this feature.
- Defaults to @samp{0}.
- @end deftypevr
- @deftypevr {@code{getmail-options-configuration} parameter} non-negative-integer max-bytes-per-session
- Retrieve messages totalling up to this number of bytes before closing
- the session with the server. A value of @samp{0} disables this feature.
- Defaults to @samp{0}.
- @end deftypevr
- @deftypevr {@code{getmail-options-configuration} parameter} non-negative-integer max-message-size
- Don't retrieve messages larger than this number of bytes. A value of
- @samp{0} disables this feature.
- Defaults to @samp{0}.
- @end deftypevr
- @deftypevr {@code{getmail-options-configuration} parameter} boolean delivered-to
- If true, getmail will add a Delivered-To header to messages.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{getmail-options-configuration} parameter} boolean received
- If set, getmail adds a Received header to the messages.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{getmail-options-configuration} parameter} string message-log
- Getmail will record a log of its actions to the named file. A value of
- @samp{""} disables this feature.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{getmail-options-configuration} parameter} boolean message-log-syslog
- If true, getmail will record a log of its actions using the system
- logger.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{getmail-options-configuration} parameter} boolean message-log-verbose
- If true, getmail will log information about messages not retrieved and
- the reason for not retrieving them, as well as starting and ending
- information lines.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{getmail-options-configuration} parameter} parameter-alist extra-parameters
- Extra options to include.
- Defaults to @samp{()}.
- @end deftypevr
- @end deftypevr
- @end deftypevr
- @deftypevr {@code{getmail-configuration} parameter} list idle
- A list of mailboxes that getmail should wait on the server for new mail
- notifications. This depends on the server supporting the IDLE
- extension.
- Defaults to @samp{()}.
- @end deftypevr
- @deftypevr {@code{getmail-configuration} parameter} list environment-variables
- Environment variables to set for getmail.
- Defaults to @samp{()}.
- @end deftypevr
- @subsubheading Mail Aliases Service
- @cindex email aliases
- @cindex aliases, for email addresses
- @deffn {Scheme Variable} mail-aliases-service-type
- This is the type of the service which provides @code{/etc/aliases},
- specifying how to deliver mail to users on this system.
- @lisp
- (service mail-aliases-service-type
- '(("postmaster" "bob")
- ("bob" "bob@@example.com" "bob@@example2.com")))
- @end lisp
- @end deffn
- The configuration for a @code{mail-aliases-service-type} service is an
- association list denoting how to deliver mail that comes to this
- system. Each entry is of the form @code{(alias addresses ...)}, with
- @code{alias} specifying the local alias and @code{addresses} specifying
- where to deliver this user's mail.
- The aliases aren't required to exist as users on the local system. In
- the above example, there doesn't need to be a @code{postmaster} entry in
- the @code{operating-system}'s @code{user-accounts} in order to deliver
- the @code{postmaster} mail to @code{bob} (which subsequently would
- deliver mail to @code{bob@@example.com} and @code{bob@@example2.com}).
- @subsubheading GNU Mailutils IMAP4 Daemon
- @cindex GNU Mailutils IMAP4 Daemon
- @deffn {Scheme Variable} imap4d-service-type
- This is the type of the GNU Mailutils IMAP4 Daemon (@pxref{imap4d,,,
- mailutils, GNU Mailutils Manual}), whose value should be an
- @code{imap4d-configuration} object as in this example:
- @lisp
- (service imap4d-service-type
- (imap4d-configuration
- (config-file (local-file "imap4d.conf"))))
- @end lisp
- @end deffn
- @deftp {Data Type} imap4d-configuration
- Data type representing the configuration of @command{imap4d}.
- @table @asis
- @item @code{package} (default: @code{mailutils})
- The package that provides @command{imap4d}.
- @item @code{config-file} (default: @code{%default-imap4d-config-file})
- File-like object of the configuration file to use, by default it will listen
- on TCP port 143 of @code{localhost}. @xref{Conf-imap4d,,, mailutils, GNU
- Mailutils Manual}, for details.
- @end table
- @end deftp
- @subsubheading Radicale Service
- @cindex CalDAV
- @cindex CardDAV
- @deffn {Scheme Variable} radicale-service-type
- This is the type of the @uref{https://radicale.org, Radicale} CalDAV/CardDAV
- server whose value should be a @code{radicale-configuration}.
- @end deffn
- @deftp {Data Type} radicale-configuration
- Data type representing the configuration of @command{radicale}.
- @table @asis
- @item @code{package} (default: @code{radicale})
- The package that provides @command{radicale}.
- @item @code{config-file} (default: @code{%default-radicale-config-file})
- File-like object of the configuration file to use, by default it will listen
- on TCP port 5232 of @code{localhost} and use the @code{htpasswd} file at
- @file{/var/lib/radicale/users} with no (@code{plain}) encryption.
- @end table
- @end deftp
- @node Messaging Services
- @subsection Messaging Services
- @cindex messaging
- @cindex jabber
- @cindex XMPP
- The @code{(gnu services messaging)} module provides Guix service
- definitions for messaging services. Currently it provides the following
- services:
- @subsubheading Prosody Service
- @deffn {Scheme Variable} prosody-service-type
- This is the type for the @uref{https://prosody.im, Prosody XMPP
- communication server}. Its value must be a @code{prosody-configuration}
- record as in this example:
- @lisp
- (service prosody-service-type
- (prosody-configuration
- (modules-enabled (cons* "groups" "mam" %default-modules-enabled))
- (int-components
- (list
- (int-component-configuration
- (hostname "conference.example.net")
- (plugin "muc")
- (mod-muc (mod-muc-configuration)))))
- (virtualhosts
- (list
- (virtualhost-configuration
- (domain "example.net"))))))
- @end lisp
- See below for details about @code{prosody-configuration}.
- @end deffn
- By default, Prosody does not need much configuration. Only one
- @code{virtualhosts} field is needed: it specifies the domain you wish
- Prosody to serve.
- You can perform various sanity checks on the generated configuration
- with the @code{prosodyctl check} command.
- Prosodyctl will also help you to import certificates from the
- @code{letsencrypt} directory so that the @code{prosody} user can access
- them. See @url{https://prosody.im/doc/letsencrypt}.
- @example
- prosodyctl --root cert import /etc/letsencrypt/live
- @end example
- The available configuration parameters follow. Each parameter
- definition is preceded by its type; for example, @samp{string-list foo}
- indicates that the @code{foo} parameter should be specified as a list of
- strings. Types starting with @code{maybe-} denote parameters that won't
- show up in @code{prosody.cfg.lua} when their value is @code{'disabled}.
- There is also a way to specify the configuration as a string, if you
- have an old @code{prosody.cfg.lua} file that you want to port over from
- some other system; see the end for more details.
- The @code{file-object} type designates either a file-like object
- (@pxref{G-Expressions, file-like objects}) or a file name.
- @c The following documentation was initially generated by
- @c (generate-documentation) in (gnu services messaging). Manually maintained
- @c documentation is better, so we shouldn't hesitate to edit below as
- @c needed. However if the change you want to make to this documentation
- @c can be done in an automated way, it's probably easier to change
- @c (generate-documentation) than to make it below and have to deal with
- @c the churn as Prosody updates.
- Available @code{prosody-configuration} fields are:
- @deftypevr {@code{prosody-configuration} parameter} package prosody
- The Prosody package.
- @end deftypevr
- @deftypevr {@code{prosody-configuration} parameter} file-name data-path
- Location of the Prosody data storage directory. See
- @url{https://prosody.im/doc/configure}.
- Defaults to @samp{"/var/lib/prosody"}.
- @end deftypevr
- @deftypevr {@code{prosody-configuration} parameter} file-object-list plugin-paths
- Additional plugin directories. They are searched in all the specified
- paths in order. See @url{https://prosody.im/doc/plugins_directory}.
- Defaults to @samp{()}.
- @end deftypevr
- @deftypevr {@code{prosody-configuration} parameter} file-name certificates
- Every virtual host and component needs a certificate so that clients and
- servers can securely verify its identity. Prosody will automatically load
- certificates/keys from the directory specified here.
- Defaults to @samp{"/etc/prosody/certs"}.
- @end deftypevr
- @deftypevr {@code{prosody-configuration} parameter} string-list admins
- This is a list of accounts that are admins for the server. Note that you
- must create the accounts separately. See @url{https://prosody.im/doc/admins} and
- @url{https://prosody.im/doc/creating_accounts}.
- Example: @code{(admins '("user1@@example.com" "user2@@example.net"))}
- Defaults to @samp{()}.
- @end deftypevr
- @deftypevr {@code{prosody-configuration} parameter} boolean use-libevent?
- Enable use of libevent for better performance under high load. See
- @url{https://prosody.im/doc/libevent}.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{prosody-configuration} parameter} module-list modules-enabled
- This is the list of modules Prosody will load on startup. It looks for
- @code{mod_modulename.lua} in the plugins folder, so make sure that exists too.
- Documentation on modules can be found at:
- @url{https://prosody.im/doc/modules}.
- Defaults to @samp{("roster" "saslauth" "tls" "dialback" "disco" "carbons" "private" "blocklist" "vcard" "version" "uptime" "time" "ping" "pep" "register" "admin_adhoc")}.
- @end deftypevr
- @deftypevr {@code{prosody-configuration} parameter} string-list modules-disabled
- @samp{"offline"}, @samp{"c2s"} and @samp{"s2s"} are auto-loaded, but
- should you want to disable them then add them to this list.
- Defaults to @samp{()}.
- @end deftypevr
- @deftypevr {@code{prosody-configuration} parameter} file-object groups-file
- Path to a text file where the shared groups are defined. If this path is
- empty then @samp{mod_groups} does nothing. See
- @url{https://prosody.im/doc/modules/mod_groups}.
- Defaults to @samp{"/var/lib/prosody/sharedgroups.txt"}.
- @end deftypevr
- @deftypevr {@code{prosody-configuration} parameter} boolean allow-registration?
- Disable account creation by default, for security. See
- @url{https://prosody.im/doc/creating_accounts}.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{prosody-configuration} parameter} maybe-ssl-configuration ssl
- These are the SSL/TLS-related settings. Most of them are disabled so to
- use Prosody's defaults. If you do not completely understand these options, do
- not add them to your config, it is easy to lower the security of your server
- using them. See @url{https://prosody.im/doc/advanced_ssl_config}.
- Available @code{ssl-configuration} fields are:
- @deftypevr {@code{ssl-configuration} parameter} maybe-string protocol
- This determines what handshake to use.
- @end deftypevr
- @deftypevr {@code{ssl-configuration} parameter} maybe-file-name key
- Path to your private key file.
- @end deftypevr
- @deftypevr {@code{ssl-configuration} parameter} maybe-file-name certificate
- Path to your certificate file.
- @end deftypevr
- @deftypevr {@code{ssl-configuration} parameter} file-object capath
- Path to directory containing root certificates that you wish Prosody to
- trust when verifying the certificates of remote servers.
- Defaults to @samp{"/etc/ssl/certs"}.
- @end deftypevr
- @deftypevr {@code{ssl-configuration} parameter} maybe-file-object cafile
- Path to a file containing root certificates that you wish Prosody to trust.
- Similar to @code{capath} but with all certificates concatenated together.
- @end deftypevr
- @deftypevr {@code{ssl-configuration} parameter} maybe-string-list verify
- A list of verification options (these mostly map to OpenSSL's
- @code{set_verify()} flags).
- @end deftypevr
- @deftypevr {@code{ssl-configuration} parameter} maybe-string-list options
- A list of general options relating to SSL/TLS@. These map to OpenSSL's
- @code{set_options()}. For a full list of options available in LuaSec, see the
- LuaSec source.
- @end deftypevr
- @deftypevr {@code{ssl-configuration} parameter} maybe-non-negative-integer depth
- How long a chain of certificate authorities to check when looking for a
- trusted root certificate.
- @end deftypevr
- @deftypevr {@code{ssl-configuration} parameter} maybe-string ciphers
- An OpenSSL cipher string. This selects what ciphers Prosody will offer to
- clients, and in what order.
- @end deftypevr
- @deftypevr {@code{ssl-configuration} parameter} maybe-file-name dhparam
- A path to a file containing parameters for Diffie-Hellman key exchange. You
- can create such a file with:
- @code{openssl dhparam -out /etc/prosody/certs/dh-2048.pem 2048}
- @end deftypevr
- @deftypevr {@code{ssl-configuration} parameter} maybe-string curve
- Curve for Elliptic curve Diffie-Hellman. Prosody's default is
- @samp{"secp384r1"}.
- @end deftypevr
- @deftypevr {@code{ssl-configuration} parameter} maybe-string-list verifyext
- A list of ``extra'' verification options.
- @end deftypevr
- @deftypevr {@code{ssl-configuration} parameter} maybe-string password
- Password for encrypted private keys.
- @end deftypevr
- @end deftypevr
- @deftypevr {@code{prosody-configuration} parameter} boolean c2s-require-encryption?
- Whether to force all client-to-server connections to be encrypted or not.
- See @url{https://prosody.im/doc/modules/mod_tls}.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{prosody-configuration} parameter} string-list disable-sasl-mechanisms
- Set of mechanisms that will never be offered. See
- @url{https://prosody.im/doc/modules/mod_saslauth}.
- Defaults to @samp{("DIGEST-MD5")}.
- @end deftypevr
- @deftypevr {@code{prosody-configuration} parameter} boolean s2s-require-encryption?
- Whether to force all server-to-server connections to be encrypted or not.
- See @url{https://prosody.im/doc/modules/mod_tls}.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{prosody-configuration} parameter} boolean s2s-secure-auth?
- Whether to require encryption and certificate authentication. This
- provides ideal security, but requires servers you communicate with to support
- encryption AND present valid, trusted certificates. See
- @url{https://prosody.im/doc/s2s#security}.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{prosody-configuration} parameter} string-list s2s-insecure-domains
- Many servers don't support encryption or have invalid or self-signed
- certificates. You can list domains here that will not be required to
- authenticate using certificates. They will be authenticated using DNS@. See
- @url{https://prosody.im/doc/s2s#security}.
- Defaults to @samp{()}.
- @end deftypevr
- @deftypevr {@code{prosody-configuration} parameter} string-list s2s-secure-domains
- Even if you leave @code{s2s-secure-auth?} disabled, you can still require
- valid certificates for some domains by specifying a list here. See
- @url{https://prosody.im/doc/s2s#security}.
- Defaults to @samp{()}.
- @end deftypevr
- @deftypevr {@code{prosody-configuration} parameter} string authentication
- Select the authentication backend to use. The default provider stores
- passwords in plaintext and uses Prosody's configured data storage to store the
- authentication data. If you do not trust your server please see
- @url{https://prosody.im/doc/modules/mod_auth_internal_hashed} for information
- about using the hashed backend. See also
- @url{https://prosody.im/doc/authentication}
- Defaults to @samp{"internal_plain"}.
- @end deftypevr
- @deftypevr {@code{prosody-configuration} parameter} maybe-string log
- Set logging options. Advanced logging configuration is not yet supported
- by the Prosody service. See @url{https://prosody.im/doc/logging}.
- Defaults to @samp{"*syslog"}.
- @end deftypevr
- @deftypevr {@code{prosody-configuration} parameter} file-name pidfile
- File to write pid in. See @url{https://prosody.im/doc/modules/mod_posix}.
- Defaults to @samp{"/var/run/prosody/prosody.pid"}.
- @end deftypevr
- @deftypevr {@code{prosody-configuration} parameter} maybe-non-negative-integer http-max-content-size
- Maximum allowed size of the HTTP body (in bytes).
- @end deftypevr
- @deftypevr {@code{prosody-configuration} parameter} maybe-string http-external-url
- Some modules expose their own URL in various ways. This URL is built
- from the protocol, host and port used. If Prosody sits behind a proxy, the
- public URL will be @code{http-external-url} instead. See
- @url{https://prosody.im/doc/http#external_url}.
- @end deftypevr
- @deftypevr {@code{prosody-configuration} parameter} virtualhost-configuration-list virtualhosts
- A host in Prosody is a domain on which user accounts can be created. For
- example if you want your users to have addresses like
- @samp{"john.smith@@example.com"} then you need to add a host
- @samp{"example.com"}. All options in this list will apply only to this host.
- Note: the name @emph{virtual} host is used in configuration to avoid confusion with
- the actual physical host that Prosody is installed on. A single Prosody
- instance can serve many domains, each one defined as a VirtualHost entry in
- Prosody's configuration. Conversely a server that hosts a single domain would
- have just one VirtualHost entry.
- See @url{https://prosody.im/doc/configure#virtual_host_settings}.
- Available @code{virtualhost-configuration} fields are:
- all these @code{prosody-configuration} fields: @code{admins}, @code{use-libevent?}, @code{modules-enabled}, @code{modules-disabled}, @code{groups-file}, @code{allow-registration?}, @code{ssl}, @code{c2s-require-encryption?}, @code{disable-sasl-mechanisms}, @code{s2s-require-encryption?}, @code{s2s-secure-auth?}, @code{s2s-insecure-domains}, @code{s2s-secure-domains}, @code{authentication}, @code{log}, @code{http-max-content-size}, @code{http-external-url}, @code{raw-content}, plus:
- @deftypevr {@code{virtualhost-configuration} parameter} string domain
- Domain you wish Prosody to serve.
- @end deftypevr
- @end deftypevr
- @deftypevr {@code{prosody-configuration} parameter} int-component-configuration-list int-components
- Components are extra services on a server which are available to clients,
- usually on a subdomain of the main server (such as
- @samp{"mycomponent.example.com"}). Example components might be chatroom
- servers, user directories, or gateways to other protocols.
- Internal components are implemented with Prosody-specific plugins. To add an
- internal component, you simply fill the hostname field, and the plugin you wish
- to use for the component.
- See @url{https://prosody.im/doc/components}.
- Defaults to @samp{()}.
- Available @code{int-component-configuration} fields are:
- all these @code{prosody-configuration} fields: @code{admins}, @code{use-libevent?}, @code{modules-enabled}, @code{modules-disabled}, @code{groups-file}, @code{allow-registration?}, @code{ssl}, @code{c2s-require-encryption?}, @code{disable-sasl-mechanisms}, @code{s2s-require-encryption?}, @code{s2s-secure-auth?}, @code{s2s-insecure-domains}, @code{s2s-secure-domains}, @code{authentication}, @code{log}, @code{http-max-content-size}, @code{http-external-url}, @code{raw-content}, plus:
- @deftypevr {@code{int-component-configuration} parameter} string hostname
- Hostname of the component.
- @end deftypevr
- @deftypevr {@code{int-component-configuration} parameter} string plugin
- Plugin you wish to use for the component.
- @end deftypevr
- @deftypevr {@code{int-component-configuration} parameter} maybe-mod-muc-configuration mod-muc
- Multi-user chat (MUC) is Prosody's module for allowing you to create
- hosted chatrooms/conferences for XMPP users.
- General information on setting up and using multi-user chatrooms can be found
- in the ``Chatrooms'' documentation (@url{https://prosody.im/doc/chatrooms}),
- which you should read if you are new to XMPP chatrooms.
- See also @url{https://prosody.im/doc/modules/mod_muc}.
- Available @code{mod-muc-configuration} fields are:
- @deftypevr {@code{mod-muc-configuration} parameter} string name
- The name to return in service discovery responses.
- Defaults to @samp{"Prosody Chatrooms"}.
- @end deftypevr
- @deftypevr {@code{mod-muc-configuration} parameter} string-or-boolean restrict-room-creation
- If @samp{#t}, this will only allow admins to create new chatrooms.
- Otherwise anyone can create a room. The value @samp{"local"} restricts room
- creation to users on the service's parent domain. E.g.@: @samp{user@@example.com}
- can create rooms on @samp{rooms.example.com}. The value @samp{"admin"}
- restricts to service administrators only.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{mod-muc-configuration} parameter} non-negative-integer max-history-messages
- Maximum number of history messages that will be sent to the member that has
- just joined the room.
- Defaults to @samp{20}.
- @end deftypevr
- @end deftypevr
- @end deftypevr
- @deftypevr {@code{prosody-configuration} parameter} ext-component-configuration-list ext-components
- External components use XEP-0114, which most standalone components
- support. To add an external component, you simply fill the hostname field. See
- @url{https://prosody.im/doc/components}.
- Defaults to @samp{()}.
- Available @code{ext-component-configuration} fields are:
- all these @code{prosody-configuration} fields: @code{admins}, @code{use-libevent?}, @code{modules-enabled}, @code{modules-disabled}, @code{groups-file}, @code{allow-registration?}, @code{ssl}, @code{c2s-require-encryption?}, @code{disable-sasl-mechanisms}, @code{s2s-require-encryption?}, @code{s2s-secure-auth?}, @code{s2s-insecure-domains}, @code{s2s-secure-domains}, @code{authentication}, @code{log}, @code{http-max-content-size}, @code{http-external-url}, @code{raw-content}, plus:
- @deftypevr {@code{ext-component-configuration} parameter} string component-secret
- Password which the component will use to log in.
- @end deftypevr
- @deftypevr {@code{ext-component-configuration} parameter} string hostname
- Hostname of the component.
- @end deftypevr
- @end deftypevr
- @deftypevr {@code{prosody-configuration} parameter} non-negative-integer-list component-ports
- Port(s) Prosody listens on for component connections.
- Defaults to @samp{(5347)}.
- @end deftypevr
- @deftypevr {@code{prosody-configuration} parameter} string component-interface
- Interface Prosody listens on for component connections.
- Defaults to @samp{"127.0.0.1"}.
- @end deftypevr
- @deftypevr {@code{prosody-configuration} parameter} maybe-raw-content raw-content
- Raw content that will be added to the configuration file.
- @end deftypevr
- It could be that you just want to get a @code{prosody.cfg.lua}
- up and running. In that case, you can pass an
- @code{opaque-prosody-configuration} record as the value of
- @code{prosody-service-type}. As its name indicates, an opaque configuration
- does not have easy reflective capabilities.
- Available @code{opaque-prosody-configuration} fields are:
- @deftypevr {@code{opaque-prosody-configuration} parameter} package prosody
- The prosody package.
- @end deftypevr
- @deftypevr {@code{opaque-prosody-configuration} parameter} string prosody.cfg.lua
- The contents of the @code{prosody.cfg.lua} to use.
- @end deftypevr
- For example, if your @code{prosody.cfg.lua} is just the empty
- string, you could instantiate a prosody service like this:
- @lisp
- (service prosody-service-type
- (opaque-prosody-configuration
- (prosody.cfg.lua "")))
- @end lisp
- @c end of Prosody auto-generated documentation
- @subsubheading BitlBee Service
- @cindex IRC (Internet Relay Chat)
- @cindex IRC gateway
- @url{https://bitlbee.org,BitlBee} is a gateway that provides an IRC
- interface to a variety of messaging protocols such as XMPP.
- @defvr {Scheme Variable} bitlbee-service-type
- This is the service type for the @url{https://bitlbee.org,BitlBee} IRC
- gateway daemon. Its value is a @code{bitlbee-configuration} (see
- below).
- To have BitlBee listen on port 6667 on localhost, add this line to your
- services:
- @lisp
- (service bitlbee-service-type)
- @end lisp
- @end defvr
- @deftp {Data Type} bitlbee-configuration
- This is the configuration for BitlBee, with the following fields:
- @table @asis
- @item @code{interface} (default: @code{"127.0.0.1"})
- @itemx @code{port} (default: @code{6667})
- Listen on the network interface corresponding to the IP address
- specified in @var{interface}, on @var{port}.
- When @var{interface} is @code{127.0.0.1}, only local clients can
- connect; when it is @code{0.0.0.0}, connections can come from any
- networking interface.
- @item @code{bitlbee} (default: @code{bitlbee})
- The BitlBee package to use.
- @item @code{plugins} (default: @code{'()})
- List of plugin packages to use---e.g., @code{bitlbee-discord}.
- @item @code{extra-settings} (default: @code{""})
- Configuration snippet added as-is to the BitlBee configuration file.
- @end table
- @end deftp
- @subsubheading Quassel Service
- @cindex IRC (Internet Relay Chat)
- @url{https://quassel-irc.org/,Quassel} is a distributed IRC client,
- meaning that one or more clients can attach to and detach from the
- central core.
- @defvr {Scheme Variable} quassel-service-type
- This is the service type for the @url{https://quassel-irc.org/,Quassel}
- IRC backend daemon. Its value is a @code{quassel-configuration}
- (see below).
- @end defvr
- @deftp {Data Type} quassel-configuration
- This is the configuration for Quassel, with the following fields:
- @table @asis
- @item @code{quassel} (default: @code{quassel})
- The Quassel package to use.
- @item @code{interface} (default: @code{"::,0.0.0.0"})
- @item @code{port} (default: @code{4242})
- Listen on the network interface(s) corresponding to the IPv4 or IPv6
- interfaces specified in the comma delimited @var{interface}, on
- @var{port}.
- @item @code{loglevel} (default: @code{"Info"})
- The level of logging desired. Accepted values are Debug, Info, Warning
- and Error.
- @end table
- @end deftp
- @node Telephony Services
- @subsection Telephony Services
- @cindex telephony, services
- The @code{(gnu services telephony)} module contains Guix service
- definitions for telephony services. Currently it provides the following
- services:
- @subsubheading Jami
- @cindex jami, service
- This section describes how to configure a Jami server that can be used
- to host video (or audio) conferences, among other uses. The following
- example demonstrates how to specify Jami account archives (backups) to
- be provisioned automatically:
- @lisp
- (service jami-service-type
- (jami-configuration
- (accounts
- (list (jami-account
- (archive "/etc/jami/unencrypted-account-1.gz"))
- (jami-account
- (archive "/etc/jami/unencrypted-account-2.gz"))))))
- @end lisp
- When the accounts field is specified, the Jami account files of the
- service found under @file{/var/lib/jami} are recreated every time the
- service starts.
- Jami accounts and their corresponding backup archives can be generated
- using the @code{jami} or @code{jami-gnome} Jami clients. The accounts
- should not be password-protected, but it is wise to ensure their files
- are only readable by @samp{root}.
- The next example shows how to declare that only some contacts should be
- allowed to communicate with a given account:
- @lisp
- (service jami-service-type
- (jami-configuration
- (accounts
- (list (jami-account
- (archive "/etc/jami/unencrypted-account-1.gz")
- (peer-discovery? #t)
- (rendezvous-point? #t)
- (allowed-contacts
- '("1dbcb0f5f37324228235564b79f2b9737e9a008f"
- "2dbcb0f5f37324228235564b79f2b9737e9a008f")))))))
- @end lisp
- In this mode, only the declared @code{allowed-contacts} can initiate
- communication with the Jami account. This can be used, for example,
- with rendezvous point accounts to create a private video conferencing
- space.
- To put the system administrator in full control of the conferences
- hosted on their system, the Jami service supports the following actions:
- @example sh
- # herd doc jami list-actions
- (list-accounts
- list-account-details
- list-banned-contacts
- list-contacts
- list-moderators
- add-moderator
- ban-contact
- enable-account
- disable-account)
- @end example
- The above actions aim to provide the most valuable actions for
- moderation purposes, not to cover the whole Jami API. Users wanting to
- interact with the Jami daemon from Guile may be interested in
- experimenting with the @code{(gnu build jami-service)} module, which
- powers the above Shepherd actions.
- @c TODO: This should be auto-generated from the doc already defined on
- @c the shepherd-actions themselves in (gnu services telephony).
- The @code{add-moderator} and @code{ban-contact} actions accept a contact
- @emph{fingerprint} (40 characters long hash) as first argument and an
- account fingerprint or username as second argument:
- @example sh
- # herd add-moderator jami 1dbcb0f5f37324228235564b79f2b9737e9a008f \
- f3345f2775ddfe07a4b0d95daea111d15fbc1199
- # herd list-moderators jami
- Moderators for account f3345f2775ddfe07a4b0d95daea111d15fbc1199:
- - 1dbcb0f5f37324228235564b79f2b9737e9a008f
- @end example
- In the case of @code{ban-contact}, the second username argument is
- optional; when omitted, the account is banned from all Jami accounts:
- @example sh
- # herd ban-contact jami 1dbcb0f5f37324228235564b79f2b9737e9a008f
- # herd list-banned-contacts jami
- Banned contacts for account f3345f2775ddfe07a4b0d95daea111d15fbc1199:
- - 1dbcb0f5f37324228235564b79f2b9737e9a008f
- @end example
- Banned contacts are also stripped from their moderation privileges.
- The @code{disable-account} action allows to completely disconnect an
- account from the network, making it unreachable, while
- @code{enable-account} does the inverse. They accept a single account
- username or fingerprint as first argument:
- @example sh
- # herd disable-account jami f3345f2775ddfe07a4b0d95daea111d15fbc1199
- # herd list-accounts jami
- The following Jami accounts are available:
- - f3345f2775ddfe07a4b0d95daea111d15fbc1199 (dummy) [disabled]
- @end example
- The @code{list-account-details} action prints the detailed parameters of
- each accounts in the Recutils format, which means the @command{recsel}
- command can be used to select accounts of interest (@pxref{Selection
- Expressions,,,recutils, GNU recutils manual}). Note that period
- characters (@samp{.}) found in the account parameter keys are mapped to
- underscores (@samp{_}) in the output, to meet the requirements of the
- Recutils format. The following example shows how to print the account
- fingerprints for all accounts operating in the rendezvous point mode:
- @example sh
- # herd list-account-details jami | \
- recsel -p Account.username -e 'Account.rendezVous ~ "true"'
- Account_username: f3345f2775ddfe07a4b0d95daea111d15fbc1199
- @end example
- The remaining actions should be self-explanatory.
- The complete set of available configuration options is detailed below.
- @c TODO: Ideally, the following fragments would be auto-generated at
- @c build time, so that they needn't be manually duplicated.
- @c Auto-generated via (configuration->documentation 'jami-configuration)
- @deftp {Data Type} jami-configuration
- Available @code{jami-configuration} fields are:
- @table @asis
- @item @code{jamid} (default: @code{libjami}) (type: package)
- The Jami daemon package to use.
- @item @code{dbus} (default: @code{dbus}) (type: package)
- The D-Bus package to use to start the required D-Bus session.
- @item @code{nss-certs} (default: @code{nss-certs}) (type: package)
- The nss-certs package to use to provide TLS certificates.
- @item @code{enable-logging?} (default: @code{#t}) (type: boolean)
- Whether to enable logging to syslog.
- @item @code{debug?} (default: @code{#f}) (type: boolean)
- Whether to enable debug level messages.
- @item @code{auto-answer?} (default: @code{#f}) (type: boolean)
- Whether to force automatic answer to incoming calls.
- @item @code{accounts} (default: @code{disabled}) (type: maybe-jami-account-list)
- A list of Jami accounts to be (re-)provisioned every time the Jami
- daemon service starts. When providing this field, the account
- directories under @file{/var/lib/jami/} are recreated every time the
- service starts, ensuring a consistent state.
- @end table
- @end deftp
- @c Auto-generated via (configuration->documentation 'jami-account)
- @deftp {Data Type} jami-account
- Available @code{jami-account} fields are:
- @table @asis
- @item @code{archive} (type: string-or-computed-file)
- The account archive (backup) file name of the account. This is used to
- provision the account when the service starts. The account archive
- should @emph{not} be encrypted. It is highly recommended to make it
- readable only to the @samp{root} user (i.e., not in the store), to guard
- against leaking the secret key material of the Jami account it contains.
- @item @code{allowed-contacts} (default: @code{disabled}) (type: maybe-account-fingerprint-list)
- The list of allowed contacts for the account, entered as their 40
- characters long fingerprint. Messages or calls from accounts not in
- that list will be rejected. When unspecified, the configuration of the
- account archive is used as-is with respect to contacts and public
- inbound calls/messaging allowance, which typically defaults to allow any
- contact to communicate with the account.
- @item @code{moderators} (default: @code{disabled}) (type: maybe-account-fingerprint-list)
- The list of contacts that should have moderation privileges (to ban,
- mute, etc. other users) in rendezvous conferences, entered as their 40
- characters long fingerprint. When unspecified, the configuration of the
- account archive is used as-is with respect to moderation, which
- typically defaults to allow anyone to moderate.
- @item @code{rendezvous-point?} (default: @code{disabled}) (type: maybe-boolean)
- Whether the account should operate in the rendezvous mode. In this
- mode, all the incoming audio/video calls are mixed into a conference.
- When left unspecified, the value from the account archive prevails.
- @item @code{peer-discovery?} (default: @code{disabled}) (type: maybe-boolean)
- Whether peer discovery should be enabled. Peer discovery is used to
- discover other OpenDHT nodes on the local network, which can be useful
- to maintain communication between devices on such network even when the
- connection to the the Internet has been lost. When left unspecified,
- the value from the account archive prevails.
- @item @code{bootstrap-hostnames} (default: @code{disabled}) (type: maybe-string-list)
- A list of hostnames or IPs pointing to OpenDHT nodes, that should be
- used to initially join the OpenDHT network. When left unspecified, the
- value from the account archive prevails.
- @item @code{name-server-uri} (default: @code{disabled}) (type: maybe-string)
- The URI of the name server to use, that can be used to retrieve the
- account fingerprint for a registered username.
- @end table
- @end deftp
- @subsubheading Murmur (VoIP server)
- @cindex Murmur (VoIP server)
- @cindex VoIP server
- This section describes how to set up and run a Murmur server. Murmur is
- the server of the @uref{https://mumble.info, Mumble} voice-over-IP
- (VoIP) suite.
- @deftp {Data Type} murmur-configuration
- The service type for the Murmur server. An example configuration can
- look like this:
- @lisp
- (service murmur-service-type
- (murmur-configuration
- (welcome-text
- "Welcome to this Mumble server running on Guix!")
- (cert-required? #t) ;disallow text password logins
- (ssl-cert "/etc/letsencrypt/live/mumble.example.com/fullchain.pem")
- (ssl-key "/etc/letsencrypt/live/mumble.example.com/privkey.pem")))
- @end lisp
- After reconfiguring your system, you can manually set the murmur @code{SuperUser}
- password with the command that is printed during the activation phase.
- It is recommended to register a normal Mumble user account
- and grant it admin or moderator rights.
- You can use the @code{mumble} client to
- login as new normal user, register yourself, and log out.
- For the next step login with the name @code{SuperUser} use
- the @code{SuperUser} password that you set previously,
- and grant your newly registered mumble user administrator or moderator
- rights and create some channels.
- Available @code{murmur-configuration} fields are:
- @table @asis
- @item @code{package} (default: @code{mumble})
- Package that contains @code{bin/murmurd}.
- @item @code{user} (default: @code{"murmur"})
- User who will run the Murmur server.
- @item @code{group} (default: @code{"murmur"})
- Group of the user who will run the murmur server.
- @item @code{port} (default: @code{64738})
- Port on which the server will listen.
- @item @code{welcome-text} (default: @code{""})
- Welcome text sent to clients when they connect.
- @item @code{server-password} (default: @code{""})
- Password the clients have to enter in order to connect.
- @item @code{max-users} (default: @code{100})
- Maximum of users that can be connected to the server at once.
- @item @code{max-user-bandwidth} (default: @code{#f})
- Maximum voice traffic a user can send per second.
- @item @code{database-file} (default: @code{"/var/lib/murmur/db.sqlite"})
- File name of the sqlite database.
- The service's user will become the owner of the directory.
- @item @code{log-file} (default: @code{"/var/log/murmur/murmur.log"})
- File name of the log file.
- The service's user will become the owner of the directory.
- @item @code{autoban-attempts} (default: @code{10})
- Maximum number of logins a user can make in @code{autoban-timeframe}
- without getting auto banned for @code{autoban-time}.
- @item @code{autoban-timeframe} (default: @code{120})
- Timeframe for autoban in seconds.
- @item @code{autoban-time} (default: @code{300})
- Amount of time in seconds for which a client gets banned
- when violating the autoban limits.
- @item @code{opus-threshold} (default: @code{100})
- Percentage of clients that need to support opus
- before switching over to opus audio codec.
- @item @code{channel-nesting-limit} (default: @code{10})
- How deep channels can be nested at maximum.
- @item @code{channelname-regex} (default: @code{#f})
- A string in form of a Qt regular expression that channel names must conform to.
- @item @code{username-regex} (default: @code{#f})
- A string in form of a Qt regular expression that user names must conform to.
- @item @code{text-message-length} (default: @code{5000})
- Maximum size in bytes that a user can send in one text chat message.
- @item @code{image-message-length} (default: @code{(* 128 1024)})
- Maximum size in bytes that a user can send in one image message.
- @item @code{cert-required?} (default: @code{#f})
- If it is set to @code{#t} clients that use weak password authentication
- will not be accepted. Users must have completed the certificate wizard to join.
- @item @code{remember-channel?} (default: @code{#f})
- Should murmur remember the last channel each user was in when they disconnected
- and put them into the remembered channel when they rejoin.
- @item @code{allow-html?} (default: @code{#f})
- Should html be allowed in text messages, user comments, and channel descriptions.
- @item @code{allow-ping?} (default: @code{#f})
- Setting to true exposes the current user count, the maximum user count, and
- the server's maximum bandwidth per client to unauthenticated users. In the
- Mumble client, this information is shown in the Connect dialog.
- Disabling this setting will prevent public listing of the server.
- @item @code{bonjour?} (default: @code{#f})
- Should the server advertise itself in the local network through the bonjour protocol.
- @item @code{send-version?} (default: @code{#f})
- Should the murmur server version be exposed in ping requests.
- @item @code{log-days} (default: @code{31})
- Murmur also stores logs in the database, which are accessible via RPC.
- The default is 31 days of months, but you can set this setting to 0 to keep logs forever,
- or -1 to disable logging to the database.
- @item @code{obfuscate-ips?} (default: @code{#t})
- Should logged ips be obfuscated to protect the privacy of users.
- @item @code{ssl-cert} (default: @code{#f})
- File name of the SSL/TLS certificate used for encrypted connections.
- @lisp
- (ssl-cert "/etc/letsencrypt/live/example.com/fullchain.pem")
- @end lisp
- @item @code{ssl-key} (default: @code{#f})
- Filepath to the ssl private key used for encrypted connections.
- @lisp
- (ssl-key "/etc/letsencrypt/live/example.com/privkey.pem")
- @end lisp
- @item @code{ssl-dh-params} (default: @code{#f})
- File name of a PEM-encoded file with Diffie-Hellman parameters
- for the SSL/TLS encryption. Alternatively you set it to
- @code{"@@ffdhe2048"}, @code{"@@ffdhe3072"}, @code{"@@ffdhe4096"}, @code{"@@ffdhe6144"}
- or @code{"@@ffdhe8192"} to use bundled parameters from RFC 7919.
- @item @code{ssl-ciphers} (default: @code{#f})
- The @code{ssl-ciphers} option chooses the cipher suites to make available for use
- in SSL/TLS.
- This option is specified using
- @uref{https://www.openssl.org/docs/apps/ciphers.html#CIPHER-LIST-FORMAT,
- OpenSSL cipher list notation}.
- It is recommended that you try your cipher string using 'openssl ciphers <string>'
- before setting it here, to get a feel for which cipher suites you will get.
- After setting this option, it is recommend that you inspect your Murmur log
- to ensure that Murmur is using the cipher suites that you expected it to.
- Note: Changing this option may impact the backwards compatibility of your
- Murmur server, and can remove the ability for older Mumble clients to be able
- to connect to it.
- @item @code{public-registration} (default: @code{#f})
- Must be a @code{<murmur-public-registration-configuration>} record or @code{#f}.
- You can optionally register your server in the public server list that the
- @code{mumble} client shows on startup.
- You cannot register your server if you have set a @code{server-password},
- or set @code{allow-ping} to @code{#f}.
- It might take a few hours until it shows up in the public list.
- @item @code{file} (default: @code{#f})
- Optional alternative override for this configuration.
- @end table
- @end deftp
- @deftp {Data Type} murmur-public-registration-configuration
- Configuration for public registration of a murmur service.
- @table @asis
- @item @code{name}
- This is a display name for your server. Not to be confused with the hostname.
- @item @code{password}
- A password to identify your registration.
- Subsequent updates will need the same password. Don't lose your password.
- @item @code{url}
- This should be a @code{http://} or @code{https://} link to your web
- site.
- @item @code{hostname} (default: @code{#f})
- By default your server will be listed by its IP address.
- If it is set your server will be linked by this host name instead.
- @end table
- @end deftp
- @node File-Sharing Services
- @subsection File-Sharing Services
- The @code{(gnu services file-sharing)} module provides services that
- assist with transferring files over peer-to-peer file-sharing networks.
- @subsubheading Transmission Daemon Service
- @uref{https://transmissionbt.com/, Transmission} is a flexible
- BitTorrent client that offers a variety of graphical and command-line
- interfaces. A @code{transmission-daemon-service-type} service provides
- Transmission's headless variant, @command{transmission-daemon}, as a
- system service, allowing users to share files via BitTorrent even when
- they are not logged in.
- @deffn {Scheme Variable} transmission-daemon-service-type
- The service type for the Transmission Daemon BitTorrent client. Its
- value must be a @code{transmission-daemon-configuration} object as in
- this example:
- @lisp
- (service transmission-daemon-service-type
- (transmission-daemon-configuration
- ;; Restrict access to the RPC ("control") interface
- (rpc-authentication-required? #t)
- (rpc-username "transmission")
- (rpc-password
- (transmission-password-hash
- "transmission" ; desired password
- "uKd1uMs9")) ; arbitrary salt value
- ;; Accept requests from this and other hosts on the
- ;; local network
- (rpc-whitelist-enabled? #t)
- (rpc-whitelist '("::1" "127.0.0.1" "192.168.0.*"))
- ;; Limit bandwidth use during work hours
- (alt-speed-down (* 1024 2)) ; 2 MB/s
- (alt-speed-up 512) ; 512 kB/s
- (alt-speed-time-enabled? #t)
- (alt-speed-time-day 'weekdays)
- (alt-speed-time-begin
- (+ (* 60 8) 30)) ; 8:30 am
- (alt-speed-time-end
- (+ (* 60 (+ 12 5)) 30)))) ; 5:30 pm
- @end lisp
- @end deffn
- Once the service is started, users can interact with the daemon through
- its Web interface (at @code{http://localhost:9091/}) or by using the
- @command{transmission-remote} command-line tool, available in the
- @code{transmission} package. (Emacs users may want to also consider the
- @code{emacs-transmission} package.) Both communicate with the daemon
- through its remote procedure call (RPC) interface, which by default is
- available to all users on the system; you may wish to change this by
- assigning values to the @code{rpc-authentication-required?},
- @code{rpc-username} and @code{rpc-password} settings, as shown in the
- example above and documented further below.
- The value for @code{rpc-password} must be a password hash of the type
- generated and used by Transmission clients. This can be copied verbatim
- from an existing @file{settings.json} file, if another Transmission
- client is already being used. Otherwise, the
- @code{transmission-password-hash} and @code{transmission-random-salt}
- procedures provided by this module can be used to obtain a suitable hash
- value.
- @deffn {Scheme Procedure} transmission-password-hash @var{password} @var{salt}
- Returns a string containing the result of hashing @var{password}
- together with @var{salt}, in the format recognized by Transmission
- clients for their @code{rpc-password} configuration setting.
- @var{salt} must be an eight-character string. The
- @code{transmission-random-salt} procedure can be used to generate a
- suitable salt value at random.
- @end deffn
- @deffn {Scheme Procedure} transmission-random-salt
- Returns a string containing a random, eight-character salt value of the
- type generated and used by Transmission clients, suitable for passing to
- the @code{transmission-password-hash} procedure.
- @end deffn
- These procedures are accessible from within a Guile REPL started with
- the @command{guix repl} command (@pxref{Invoking guix repl}). This is
- useful for obtaining a random salt value to provide as the second
- parameter to `transmission-password-hash`, as in this example session:
- @example
- $ guix repl
- scheme@@(guix-user)> ,use (gnu services file-sharing)
- scheme@@(guix-user)> (transmission-random-salt)
- $1 = "uKd1uMs9"
- @end example
- Alternatively, a complete password hash can generated in a single step:
- @example
- scheme@@(guix-user)> (transmission-password-hash "transmission"
- (transmission-random-salt))
- $2 = "@{c8bbc6d1740cd8dc819a6e25563b67812c1c19c9VtFPfdsX"
- @end example
- The resulting string can be used as-is for the value of
- @code{rpc-password}, allowing the password to be kept hidden even in the
- operating-system configuration.
- Torrent files downloaded by the daemon are directly accessible only to
- users in the ``transmission'' user group, who receive read-only access
- to the directory specified by the @code{download-dir} configuration
- setting (and also the directory specified by @code{incomplete-dir}, if
- @code{incomplete-dir-enabled?} is @code{#t}). Downloaded files can be
- moved to another directory or deleted altogether using
- @command{transmission-remote} with its @code{--move} and
- @code{--remove-and-delete} options.
- If the @code{watch-dir-enabled?} setting is set to @code{#t}, users in
- the ``transmission'' group are able also to place @file{.torrent} files
- in the directory specified by @code{watch-dir} to have the corresponding
- torrents added by the daemon. (The @code{trash-original-torrent-files?}
- setting controls whether the daemon deletes these files after processing
- them.)
- Some of the daemon's configuration settings can be changed temporarily
- by @command{transmission-remote} and similar tools. To undo these
- changes, use the service's @code{reload} action to have the daemon
- reload its settings from disk:
- @example
- # herd reload transmission-daemon
- @end example
- The full set of available configuration settings is defined by the
- @code{transmission-daemon-configuration} data type.
- @deftp {Data Type} transmission-daemon-configuration
- The data type representing configuration settings for Transmission
- Daemon. These correspond directly to the settings recognized by
- Transmission clients in their @file{settings.json} file.
- @end deftp
- @c The following documentation was initially generated by
- @c (generate-transmission-daemon-documentation) in (gnu services
- @c file-sharing). Manually maintained documentation is better, so we
- @c shouldn't hesitate to edit below as needed. However if the change
- @c you want to make to this documentation can be done in an automated
- @c way, it's probably easier to change (generate-documentation) than to
- @c make it below and have to deal with the churn as Transmission Daemon
- @c updates.
- @c %start of fragment
- Available @code{transmission-daemon-configuration} fields are:
- @deftypevr {@code{transmission-daemon-configuration} parameter} package transmission
- The Transmission package to use.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer stop-wait-period
- The period, in seconds, to wait when stopping the service for
- @command{transmission-daemon} to exit before killing its process. This
- allows the daemon time to complete its housekeeping and send a final
- update to trackers as it shuts down. On slow hosts, or hosts with a
- slow network connection, this value may need to be increased.
- Defaults to @samp{10}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} string download-dir
- The directory to which torrent files are downloaded.
- Defaults to @samp{"/var/lib/transmission-daemon/downloads"}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} boolean incomplete-dir-enabled?
- If @code{#t}, files will be held in @code{incomplete-dir} while their
- torrent is being downloaded, then moved to @code{download-dir} once the
- torrent is complete. Otherwise, files for all torrents (including those
- still being downloaded) will be placed in @code{download-dir}.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} maybe-string incomplete-dir
- The directory in which files from incompletely downloaded torrents will
- be held when @code{incomplete-dir-enabled?} is @code{#t}.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} umask umask
- The file mode creation mask used for downloaded files. (See the
- @command{umask} man page for more information.)
- Defaults to @samp{18}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} boolean rename-partial-files?
- When @code{#t}, ``.part'' is appended to the name of partially
- downloaded files.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} preallocation-mode preallocation
- The mode by which space should be preallocated for downloaded files, one
- of @code{none}, @code{fast} (or @code{sparse}) and @code{full}.
- Specifying @code{full} will minimize disk fragmentation at a cost to
- file-creation speed.
- Defaults to @samp{fast}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} boolean watch-dir-enabled?
- If @code{#t}, the directory specified by @code{watch-dir} will be
- watched for new @file{.torrent} files and the torrents they describe
- added automatically (and the original files removed, if
- @code{trash-original-torrent-files?} is @code{#t}).
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} maybe-string watch-dir
- The directory to be watched for @file{.torrent} files indicating new
- torrents to be added, when @code{watch-dir-enabled} is @code{#t}.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} boolean trash-original-torrent-files?
- When @code{#t}, @file{.torrent} files will be deleted from the watch
- directory once their torrent has been added (see
- @code{watch-directory-enabled?}).
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} boolean speed-limit-down-enabled?
- When @code{#t}, the daemon's download speed will be limited to the rate
- specified by @code{speed-limit-down}.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer speed-limit-down
- The default global-maximum download speed, in kilobytes per second.
- Defaults to @samp{100}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} boolean speed-limit-up-enabled?
- When @code{#t}, the daemon's upload speed will be limited to the rate
- specified by @code{speed-limit-up}.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer speed-limit-up
- The default global-maximum upload speed, in kilobytes per second.
- Defaults to @samp{100}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} boolean alt-speed-enabled?
- When @code{#t}, the alternate speed limits @code{alt-speed-down} and
- @code{alt-speed-up} are used (in place of @code{speed-limit-down} and
- @code{speed-limit-up}, if they are enabled) to constrain the daemon's
- bandwidth usage. This can be scheduled to occur automatically at
- certain times during the week; see @code{alt-speed-time-enabled?}.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer alt-speed-down
- The alternate global-maximum download speed, in kilobytes per second.
- Defaults to @samp{50}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer alt-speed-up
- The alternate global-maximum upload speed, in kilobytes per second.
- Defaults to @samp{50}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} boolean alt-speed-time-enabled?
- When @code{#t}, the alternate speed limits @code{alt-speed-down} and
- @code{alt-speed-up} will be enabled automatically during the periods
- specified by @code{alt-speed-time-day}, @code{alt-speed-time-begin} and
- @code{alt-time-speed-end}.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} day-list alt-speed-time-day
- The days of the week on which the alternate-speed schedule should be
- used, specified either as a list of days (@code{sunday}, @code{monday},
- and so on) or using one of the symbols @code{weekdays}, @code{weekends}
- or @code{all}.
- Defaults to @samp{all}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer alt-speed-time-begin
- The time of day at which to enable the alternate speed limits, expressed
- as a number of minutes since midnight.
- Defaults to @samp{540}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer alt-speed-time-end
- The time of day at which to disable the alternate speed limits,
- expressed as a number of minutes since midnight.
- Defaults to @samp{1020}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} string bind-address-ipv4
- The IP address at which to listen for peer connections, or ``0.0.0.0''
- to listen at all available IP addresses.
- Defaults to @samp{"0.0.0.0"}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} string bind-address-ipv6
- The IPv6 address at which to listen for peer connections, or ``::'' to
- listen at all available IPv6 addresses.
- Defaults to @samp{"::"}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} boolean peer-port-random-on-start?
- If @code{#t}, when the daemon starts it will select a port at random on
- which to listen for peer connections, from the range specified
- (inclusively) by @code{peer-port-random-low} and
- @code{peer-port-random-high}. Otherwise, it listens on the port
- specified by @code{peer-port}.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} port-number peer-port-random-low
- The lowest selectable port number when @code{peer-port-random-on-start?}
- is @code{#t}.
- Defaults to @samp{49152}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} port-number peer-port-random-high
- The highest selectable port number when @code{peer-port-random-on-start}
- is @code{#t}.
- Defaults to @samp{65535}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} port-number peer-port
- The port on which to listen for peer connections when
- @code{peer-port-random-on-start?} is @code{#f}.
- Defaults to @samp{51413}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} boolean port-forwarding-enabled?
- If @code{#t}, the daemon will attempt to configure port-forwarding on an
- upstream gateway automatically using @acronym{UPnP} and
- @acronym{NAT-PMP}.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} encryption-mode encryption
- The encryption preference for peer connections, one of
- @code{prefer-unencrypted-connections},
- @code{prefer-encrypted-connections} or
- @code{require-encrypted-connections}.
- Defaults to @samp{prefer-encrypted-connections}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} maybe-string peer-congestion-algorithm
- The TCP congestion-control algorithm to use for peer connections,
- specified using a string recognized by the operating system in calls to
- @code{setsockopt} (or set to @code{disabled}, in which case the
- operating-system default is used).
- Note that on GNU/Linux systems, the kernel must be configured to allow
- processes to use a congestion-control algorithm not in the default set;
- otherwise, it will deny these requests with ``Operation not permitted''.
- To see which algorithms are available on your system and which are
- currently permitted for use, look at the contents of the files
- @file{tcp_available_congestion_control} and
- @file{tcp_allowed_congestion_control} in the @file{/proc/sys/net/ipv4}
- directory.
- As an example, to have Transmission Daemon use
- @uref{http://www-ece.rice.edu/networks/TCP-LP/,the TCP Low Priority
- congestion-control algorithm}, you'll need to modify your kernel
- configuration to build in support for the algorithm, then update your
- operating-system configuration to allow its use by adding a
- @code{sysctl-service-type} service (or updating the existing one's
- configuration) with lines like the following:
- @lisp
- (service sysctl-service-type
- (sysctl-configuration
- (settings
- ("net.ipv4.tcp_allowed_congestion_control" .
- "reno cubic lp"))))
- @end lisp
- The Transmission Daemon configuration can then be updated with
- @lisp
- (peer-congestion-algorithm "lp")
- @end lisp
- and the system reconfigured to have the changes take effect.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} tcp-type-of-service peer-socket-tos
- The type of service to request in outgoing @acronym{TCP} packets, one of
- @code{default}, @code{low-cost}, @code{throughput}, @code{low-delay} and
- @code{reliability}.
- Defaults to @samp{default}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer peer-limit-global
- The global limit on the number of connected peers.
- Defaults to @samp{200}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer peer-limit-per-torrent
- The per-torrent limit on the number of connected peers.
- Defaults to @samp{50}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer upload-slots-per-torrent
- The maximum number of peers to which the daemon will upload data
- simultaneously for each torrent.
- Defaults to @samp{14}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer peer-id-ttl-hours
- The maximum lifespan, in hours, of the peer ID associated with each
- public torrent before it is regenerated.
- Defaults to @samp{6}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} boolean blocklist-enabled?
- When @code{#t}, the daemon will ignore peers mentioned in the blocklist
- it has most recently downloaded from @code{blocklist-url}.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} maybe-string blocklist-url
- The URL of a peer blocklist (in @acronym{P2P}-plaintext or eMule
- @file{.dat} format) to be periodically downloaded and applied when
- @code{blocklist-enabled?} is @code{#t}.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} boolean download-queue-enabled?
- If @code{#t}, the daemon will be limited to downloading at most
- @code{download-queue-size} non-stalled torrents simultaneously.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer download-queue-size
- The size of the daemon's download queue, which limits the number of
- non-stalled torrents it will download at any one time when
- @code{download-queue-enabled?} is @code{#t}.
- Defaults to @samp{5}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} boolean seed-queue-enabled?
- If @code{#t}, the daemon will be limited to seeding at most
- @code{seed-queue-size} non-stalled torrents simultaneously.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer seed-queue-size
- The size of the daemon's seed queue, which limits the number of
- non-stalled torrents it will seed at any one time when
- @code{seed-queue-enabled?} is @code{#t}.
- Defaults to @samp{10}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} boolean queue-stalled-enabled?
- When @code{#t}, the daemon will consider torrents for which it has not
- shared data in the past @code{queue-stalled-minutes} minutes to be
- stalled and not count them against its @code{download-queue-size} and
- @code{seed-queue-size} limits.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer queue-stalled-minutes
- The maximum period, in minutes, a torrent may be idle before it is
- considered to be stalled, when @code{queue-stalled-enabled?} is
- @code{#t}.
- Defaults to @samp{30}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} boolean ratio-limit-enabled?
- When @code{#t}, a torrent being seeded will automatically be paused once
- it reaches the ratio specified by @code{ratio-limit}.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-rational ratio-limit
- The ratio at which a torrent being seeded will be paused, when
- @code{ratio-limit-enabled?} is @code{#t}.
- Defaults to @samp{2.0}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} boolean idle-seeding-limit-enabled?
- When @code{#t}, a torrent being seeded will automatically be paused once
- it has been idle for @code{idle-seeding-limit} minutes.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer idle-seeding-limit
- The maximum period, in minutes, a torrent being seeded may be idle
- before it is paused, when @code{idle-seeding-limit-enabled?} is
- @code{#t}.
- Defaults to @samp{30}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} boolean dht-enabled?
- Enable @uref{http://bittorrent.org/beps/bep_0005.html,the distributed
- hash table (@acronym{DHT}) protocol}, which supports the use of
- trackerless torrents.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} boolean lpd-enabled?
- Enable @uref{https://en.wikipedia.org/wiki/Local_Peer_Discovery,local
- peer discovery} (@acronym{LPD}), which allows the discovery of peers on
- the local network and may reduce the amount of data sent over the public
- Internet.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} boolean pex-enabled?
- Enable @uref{https://en.wikipedia.org/wiki/Peer_exchange,peer exchange}
- (@acronym{PEX}), which reduces the daemon's reliance on external
- trackers and may improve its performance.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} boolean utp-enabled?
- Enable @uref{http://bittorrent.org/beps/bep_0029.html,the micro
- transport protocol} (@acronym{uTP}), which aims to reduce the impact of
- BitTorrent traffic on other users of the local network while maintaining
- full utilization of the available bandwidth.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} boolean rpc-enabled?
- If @code{#t}, enable the remote procedure call (@acronym{RPC})
- interface, which allows remote control of the daemon via its Web
- interface, the @command{transmission-remote} command-line client, and
- similar tools.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} string rpc-bind-address
- The IP address at which to listen for @acronym{RPC} connections, or
- ``0.0.0.0'' to listen at all available IP addresses.
- Defaults to @samp{"0.0.0.0"}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} port-number rpc-port
- The port on which to listen for @acronym{RPC} connections.
- Defaults to @samp{9091}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} string rpc-url
- The path prefix to use in the @acronym{RPC}-endpoint @acronym{URL}.
- Defaults to @samp{"/transmission/"}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} boolean rpc-authentication-required?
- When @code{#t}, clients must authenticate (see @code{rpc-username} and
- @code{rpc-password}) when using the @acronym{RPC} interface. Note this
- has the side effect of disabling host-name whitelisting (see
- @code{rpc-host-whitelist-enabled?}.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} maybe-string rpc-username
- The username required by clients to access the @acronym{RPC} interface
- when @code{rpc-authentication-required?} is @code{#t}.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} maybe-transmission-password-hash rpc-password
- The password required by clients to access the @acronym{RPC} interface
- when @code{rpc-authentication-required?} is @code{#t}. This must be
- specified using a password hash in the format recognized by Transmission
- clients, either copied from an existing @file{settings.json} file or
- generated using the @code{transmission-password-hash} procedure.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} boolean rpc-whitelist-enabled?
- When @code{#t}, @acronym{RPC} requests will be accepted only when they
- originate from an address specified in @code{rpc-whitelist}.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} string-list rpc-whitelist
- The list of IP and IPv6 addresses from which @acronym{RPC} requests will
- be accepted when @code{rpc-whitelist-enabled?} is @code{#t}. Wildcards
- may be specified using @samp{*}.
- Defaults to @samp{("127.0.0.1" "::1")}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} boolean rpc-host-whitelist-enabled?
- When @code{#t}, @acronym{RPC} requests will be accepted only when they
- are addressed to a host named in @code{rpc-host-whitelist}. Note that
- requests to ``localhost'' or ``localhost.'', or to a numeric address,
- are always accepted regardless of these settings.
- Note also this functionality is disabled when
- @code{rpc-authentication-required?} is @code{#t}.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} string-list rpc-host-whitelist
- The list of host names recognized by the @acronym{RPC} server when
- @code{rpc-host-whitelist-enabled?} is @code{#t}.
- Defaults to @samp{()}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} message-level message-level
- The minimum severity level of messages to be logged (to
- @file{/var/log/transmission.log}) by the daemon, one of @code{none} (no
- logging), @code{error}, @code{info} and @code{debug}.
- Defaults to @samp{info}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} boolean start-added-torrents?
- When @code{#t}, torrents are started as soon as they are added;
- otherwise, they are added in ``paused'' state.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} boolean script-torrent-done-enabled?
- When @code{#t}, the script specified by
- @code{script-torrent-done-filename} will be invoked each time a torrent
- completes.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} maybe-file-object script-torrent-done-filename
- A file name or file-like object specifying a script to run each time a
- torrent completes, when @code{script-torrent-done-enabled?} is
- @code{#t}.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} boolean scrape-paused-torrents-enabled?
- When @code{#t}, the daemon will scrape trackers for a torrent even when
- the torrent is paused.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer cache-size-mb
- The amount of memory, in megabytes, to allocate for the daemon's
- in-memory cache. A larger value may increase performance by reducing
- the frequency of disk I/O.
- Defaults to @samp{4}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} boolean prefetch-enabled?
- When @code{#t}, the daemon will try to improve I/O performance by
- hinting to the operating system which data is likely to be read next
- from disk to satisfy requests from peers.
- Defaults to @samp{#t}.
- @end deftypevr
- @c %end of fragment
- @node Monitoring Services
- @subsection Monitoring Services
- @subsubheading Tailon Service
- @uref{https://tailon.readthedocs.io/, Tailon} is a web application for
- viewing and searching log files.
- The following example will configure the service with default values.
- By default, Tailon can be accessed on port 8080 (@code{http://localhost:8080}).
- @lisp
- (service tailon-service-type)
- @end lisp
- The following example customises more of the Tailon configuration,
- adding @command{sed} to the list of allowed commands.
- @lisp
- (service tailon-service-type
- (tailon-configuration
- (config-file
- (tailon-configuration-file
- (allowed-commands '("tail" "grep" "awk" "sed"))))))
- @end lisp
- @deftp {Data Type} tailon-configuration
- Data type representing the configuration of Tailon.
- This type has the following parameters:
- @table @asis
- @item @code{config-file} (default: @code{(tailon-configuration-file)})
- The configuration file to use for Tailon. This can be set to a
- @dfn{tailon-configuration-file} record value, or any gexp
- (@pxref{G-Expressions}).
- For example, to instead use a local file, the @code{local-file} function
- can be used:
- @lisp
- (service tailon-service-type
- (tailon-configuration
- (config-file (local-file "./my-tailon.conf"))))
- @end lisp
- @item @code{package} (default: @code{tailon})
- The tailon package to use.
- @end table
- @end deftp
- @deftp {Data Type} tailon-configuration-file
- Data type representing the configuration options for Tailon.
- This type has the following parameters:
- @table @asis
- @item @code{files} (default: @code{(list "/var/log")})
- List of files to display. The list can include strings for a single file
- or directory, or a list, where the first item is the name of a
- subsection, and the remaining items are the files or directories in that
- subsection.
- @item @code{bind} (default: @code{"localhost:8080"})
- Address and port to which Tailon should bind on.
- @item @code{relative-root} (default: @code{#f})
- URL path to use for Tailon, set to @code{#f} to not use a path.
- @item @code{allow-transfers?} (default: @code{#t})
- Allow downloading the log files in the web interface.
- @item @code{follow-names?} (default: @code{#t})
- Allow tailing of not-yet existent files.
- @item @code{tail-lines} (default: @code{200})
- Number of lines to read initially from each file.
- @item @code{allowed-commands} (default: @code{(list "tail" "grep" "awk")})
- Commands to allow running. By default, @code{sed} is disabled.
- @item @code{debug?} (default: @code{#f})
- Set @code{debug?} to @code{#t} to show debug messages.
- @item @code{wrap-lines} (default: @code{#t})
- Initial line wrapping state in the web interface. Set to @code{#t} to
- initially wrap lines (the default), or to @code{#f} to initially not
- wrap lines.
- @item @code{http-auth} (default: @code{#f})
- HTTP authentication type to use. Set to @code{#f} to disable
- authentication (the default). Supported values are @code{"digest"} or
- @code{"basic"}.
- @item @code{users} (default: @code{#f})
- If HTTP authentication is enabled (see @code{http-auth}), access will be
- restricted to the credentials provided here. To configure users, use a
- list of pairs, where the first element of the pair is the username, and
- the 2nd element of the pair is the password.
- @lisp
- (tailon-configuration-file
- (http-auth "basic")
- (users '(("user1" . "password1")
- ("user2" . "password2"))))
- @end lisp
- @end table
- @end deftp
- @subsubheading Darkstat Service
- @cindex darkstat
- Darkstat is a packet sniffer that captures network traffic, calculates
- statistics about usage, and serves reports over HTTP.
- @defvar {Scheme Variable} darkstat-service-type
- This is the service type for the
- @uref{https://unix4lyfe.org/darkstat/, darkstat}
- service, its value must be a @code{darkstat-configuration} record as in
- this example:
- @lisp
- (service darkstat-service-type
- (darkstat-configuration
- (interface "eno1")))
- @end lisp
- @end defvar
- @deftp {Data Type} darkstat-configuration
- Data type representing the configuration of @command{darkstat}.
- @table @asis
- @item @code{package} (default: @code{darkstat})
- The darkstat package to use.
- @item @code{interface}
- Capture traffic on the specified network interface.
- @item @code{port} (default: @code{"667"})
- Bind the web interface to the specified port.
- @item @code{bind-address} (default: @code{"127.0.0.1"})
- Bind the web interface to the specified address.
- @item @code{base} (default: @code{"/"})
- Specify the path of the base URL@. This can be useful if
- @command{darkstat} is accessed via a reverse proxy.
- @end table
- @end deftp
- @anchor{prometheus-node-exporter}
- @subsubheading Prometheus Node Exporter Service
- @cindex prometheus-node-exporter
- The Prometheus ``node exporter'' makes hardware and operating system statistics
- provided by the Linux kernel available for the Prometheus monitoring system.
- This service should be deployed on all physical nodes and virtual machines,
- where monitoring these statistics is desirable.
- @defvar {Scheme variable} prometheus-node-exporter-service-type
- This is the service type for the
- @uref{https://github.com/prometheus/node_exporter/, prometheus-node-exporter}
- service, its value must be a @code{prometheus-node-exporter-configuration}.
- @lisp
- (service prometheus-node-exporter-service-type)
- @end lisp
- @end defvar
- @deftp {Data Type} prometheus-node-exporter-configuration
- Data type representing the configuration of @command{node_exporter}.
- @table @asis
- @item @code{package} (default: @code{go-github-com-prometheus-node-exporter})
- The prometheus-node-exporter package to use.
- @item @code{web-listen-address} (default: @code{":9100"})
- Bind the web interface to the specified address.
- @item @code{textfile-directory} (default: @code{"/var/lib/prometheus/node-exporter"})
- This directory can be used to export metrics specific to this machine.
- Files containing metrics in the text format, with the filename ending in
- @code{.prom} should be placed in this directory.
- @item @code{extra-options} (default: @code{'()})
- Extra options to pass to the Prometheus node exporter.
- @end table
- @end deftp
- @subsubheading Zabbix server
- @cindex zabbix zabbix-server
- Zabbix is a high performance monitoring system that can collect data from a
- variety of sources and provide the results in a web-based interface. Alerting
- and reporting is built-in, as well as @dfn{templates} for common operating
- system metrics such as network utilization, CPU load, and disk space consumption.
- This service provides the central Zabbix monitoring service; you also need
- @ref{zabbix-front-end,@code{zabbix-front-end-service-type}} to configure Zabbix
- and display results, and optionally @ref{zabbix-agent,
- @code{zabbix-agent-service-type}} on machines that should be monitored (other
- data sources are supported, such as @ref{prometheus-node-exporter,
- Prometheus Node Exporter}).
- @defvar {Scheme variable} zabbix-server-service-type
- This is the service type for the Zabbix server service. Its value must be a
- @code{zabbix-server-configuration} record, shown below.
- @end defvar
- @c %start of fragment
- @deftp {Data Type} zabbix-server-configuration
- Available @code{zabbix-server-configuration} fields are:
- @table @asis
- @item @code{zabbix-server} (default: @code{zabbix-server}) (type: file-like)
- The zabbix-server package.
- @item @code{user} (default: @code{"zabbix"}) (type: string)
- User who will run the Zabbix server.
- @item @code{group} (default: @code{"zabbix"}) (type: group)
- Group who will run the Zabbix server.
- @item @code{db-host} (default: @code{"127.0.0.1"}) (type: string)
- Database host name.
- @item @code{db-name} (default: @code{"zabbix"}) (type: string)
- Database name.
- @item @code{db-user} (default: @code{"zabbix"}) (type: string)
- Database user.
- @item @code{db-password} (default: @code{""}) (type: string)
- Database password. Please, use @code{include-files} with
- @code{DBPassword=SECRET} inside a specified file instead.
- @item @code{db-port} (default: @code{5432}) (type: number)
- Database port.
- @item @code{log-type} (default: @code{""}) (type: string)
- Specifies where log messages are written to:
- @itemize @bullet
- @item @code{system} - syslog.
- @item @code{file} - file specified with @code{log-file} parameter.
- @item @code{console} - standard output.
- @end itemize
- @item @code{log-file} (default: @code{"/var/log/zabbix/server.log"}) (type: string)
- Log file name for @code{log-type} @code{file} parameter.
- @item @code{pid-file} (default: @code{"/var/run/zabbix/zabbix_server.pid"}) (type: string)
- Name of PID file.
- @item @code{ssl-ca-location} (default: @code{"/etc/ssl/certs/ca-certificates.crt"}) (type: string)
- The location of certificate authority (CA) files for SSL server
- certificate verification.
- @item @code{ssl-cert-location} (default: @code{"/etc/ssl/certs"}) (type: string)
- Location of SSL client certificates.
- @item @code{extra-options} (default: @code{""}) (type: extra-options)
- Extra options will be appended to Zabbix server configuration file.
- @item @code{include-files} (default: @code{()}) (type: include-files)
- You may include individual files or all files in a directory in the
- configuration file.
- @end table
- @end deftp
- @c %end of fragment
- @anchor{zabbix-agent}
- @subsubheading Zabbix agent
- @cindex zabbix zabbix-agent
- The Zabbix agent gathers information about the running system for the Zabbix
- monitoring server. It has a variety of built-in checks, and can be extended
- with custom
- @uref{https://www.zabbix.com/documentation/current/en/manual/config/items/userparameters,
- @dfn{user parameters}}.
- @defvar {Scheme variable} zabbix-agent-service-type
- This is the service type for the Zabbix agent service. Its value must be a
- @code{zabbix-agent-configuration} record, shown below.
- @end defvar
- @c %start of fragment
- @deftp {Data Type} zabbix-agent-configuration
- Available @code{zabbix-agent-configuration} fields are:
- @table @asis
- @item @code{zabbix-agent} (default: @code{zabbix-agentd}) (type: file-like)
- The zabbix-agent package.
- @item @code{user} (default: @code{"zabbix"}) (type: string)
- User who will run the Zabbix agent.
- @item @code{group} (default: @code{"zabbix"}) (type: group)
- Group who will run the Zabbix agent.
- @item @code{hostname} (default: @code{""}) (type: string)
- Unique, case sensitive hostname which is required for active checks and
- must match hostname as configured on the server.
- @item @code{log-type} (default: @code{""}) (type: string)
- Specifies where log messages are written to:
- @itemize @bullet
- @item
- @code{system} - syslog.
- @item @code{file} - file specified with
- @code{log-file} parameter.
- @item @code{console} - standard output.
- @end itemize
- @item @code{log-file} (default: @code{"/var/log/zabbix/agent.log"}) (type: string)
- Log file name for @code{log-type} @code{file} parameter.
- @item @code{pid-file} (default: @code{"/var/run/zabbix/zabbix_agent.pid"}) (type: string)
- Name of PID file.
- @item @code{server} (default: @code{("127.0.0.1")}) (type: list)
- List of IP addresses, optionally in CIDR notation, or hostnames of
- Zabbix servers and Zabbix proxies. Incoming connections will be
- accepted only from the hosts listed here.
- @item @code{server-active} (default: @code{("127.0.0.1")}) (type: list)
- List of IP:port (or hostname:port) pairs of Zabbix servers and Zabbix
- proxies for active checks. If port is not specified, default port is
- used. If this parameter is not specified, active checks are disabled.
- @item @code{extra-options} (default: @code{""}) (type: extra-options)
- Extra options will be appended to Zabbix server configuration file.
- @item @code{include-files} (default: @code{()}) (type: include-files)
- You may include individual files or all files in a directory in the
- configuration file.
- @end table
- @end deftp
- @c %end of fragment
- @anchor{zabbix-front-end}
- @subsubheading Zabbix front-end
- @cindex zabbix zabbix-front-end
- The Zabbix front-end provides a web interface to Zabbix. It does not need
- to run on the same machine as the Zabbix server. This service works by
- extending the @ref{PHP-FPM} and @ref{NGINX} services with the configuration
- necessary for loading the Zabbix user interface.
- @defvar {Scheme variable} zabbix-front-end-service-type
- This is the service type for the Zabbix web frontend. Its value must be a
- @code{zabbix-front-end-configuration} record, shown below.
- @end defvar
- @c %start of fragment
- @deftp {Data Type} zabbix-front-end-configuration
- Available @code{zabbix-front-end-configuration} fields are:
- @table @asis
- @item @code{zabbix-server} (default: @code{zabbix-server}) (type: file-like)
- The Zabbix server package to use.
- @item @code{nginx} (default: @code{()}) (type: list)
- List of @ref{nginx-server-configuration,@code{nginx-server-configuration}}
- blocks for the Zabbix front-end. When empty, a default that listens on
- port 80 is used.
- @item @code{db-host} (default: @code{"localhost"}) (type: string)
- Database host name.
- @item @code{db-port} (default: @code{5432}) (type: number)
- Database port.
- @item @code{db-name} (default: @code{"zabbix"}) (type: string)
- Database name.
- @item @code{db-user} (default: @code{"zabbix"}) (type: string)
- Database user.
- @item @code{db-password} (default: @code{""}) (type: string)
- Database password. Please, use @code{db-secret-file} instead.
- @item @code{db-secret-file} (default: @code{""}) (type: string)
- Secret file which will be appended to @file{zabbix.conf.php} file. This
- file contains credentials for use by Zabbix front-end. You are expected
- to create it manually.
- @item @code{zabbix-host} (default: @code{"localhost"}) (type: string)
- Zabbix server hostname.
- @item @code{zabbix-port} (default: @code{10051}) (type: number)
- Zabbix server port.
- @end table
- @end deftp
- @c %end of fragment
- @node Kerberos Services
- @subsection Kerberos Services
- @cindex Kerberos
- The @code{(gnu services kerberos)} module provides services relating to
- the authentication protocol @dfn{Kerberos}.
- @subsubheading Krb5 Service
- Programs using a Kerberos client library normally
- expect a configuration file in @file{/etc/krb5.conf}.
- This service generates such a file from a definition provided in the
- operating system declaration.
- It does not cause any daemon to be started.
- No ``keytab'' files are provided by this service---you must explicitly create them.
- This service is known to work with the MIT client library, @code{mit-krb5}.
- Other implementations have not been tested.
- @defvr {Scheme Variable} krb5-service-type
- A service type for Kerberos 5 clients.
- @end defvr
- @noindent
- Here is an example of its use:
- @lisp
- (service krb5-service-type
- (krb5-configuration
- (default-realm "EXAMPLE.COM")
- (allow-weak-crypto? #t)
- (realms (list
- (krb5-realm
- (name "EXAMPLE.COM")
- (admin-server "groucho.example.com")
- (kdc "karl.example.com"))
- (krb5-realm
- (name "ARGRX.EDU")
- (admin-server "kerb-admin.argrx.edu")
- (kdc "keys.argrx.edu"))))))
- @end lisp
- @noindent
- This example provides a Kerberos@tie{}5 client configuration which:
- @itemize
- @item Recognizes two realms, @i{viz:} ``EXAMPLE.COM'' and ``ARGRX.EDU'', both
- of which have distinct administration servers and key distribution centers;
- @item Will default to the realm ``EXAMPLE.COM'' if the realm is not explicitly
- specified by clients;
- @item Accepts services which only support encryption types known to be weak.
- @end itemize
- The @code{krb5-realm} and @code{krb5-configuration} types have many fields.
- Only the most commonly used ones are described here.
- For a full list, and more detailed explanation of each, see the MIT
- @uref{https://web.mit.edu/kerberos/krb5-devel/doc/admin/conf_files/krb5_conf.html,,krb5.conf}
- documentation.
- @deftp {Data Type} krb5-realm
- @cindex realm, kerberos
- @table @asis
- @item @code{name}
- This field is a string identifying the name of the realm.
- A common convention is to use the fully qualified DNS name of your organization,
- converted to upper case.
- @item @code{admin-server}
- This field is a string identifying the host where the administration server is
- running.
- @item @code{kdc}
- This field is a string identifying the key distribution center
- for the realm.
- @end table
- @end deftp
- @deftp {Data Type} krb5-configuration
- @table @asis
- @item @code{allow-weak-crypto?} (default: @code{#f})
- If this flag is @code{#t} then services which only offer encryption algorithms
- known to be weak will be accepted.
- @item @code{default-realm} (default: @code{#f})
- This field should be a string identifying the default Kerberos
- realm for the client.
- You should set this field to the name of your Kerberos realm.
- If this value is @code{#f}
- then a realm must be specified with every Kerberos principal when invoking programs
- such as @command{kinit}.
- @item @code{realms}
- This should be a non-empty list of @code{krb5-realm} objects, which clients may
- access.
- Normally, one of them will have a @code{name} field matching the @code{default-realm}
- field.
- @end table
- @end deftp
- @subsubheading PAM krb5 Service
- @cindex pam-krb5
- The @code{pam-krb5} service allows for login authentication and password
- management via Kerberos.
- You will need this service if you want PAM enabled applications to authenticate
- users using Kerberos.
- @defvr {Scheme Variable} pam-krb5-service-type
- A service type for the Kerberos 5 PAM module.
- @end defvr
- @deftp {Data Type} pam-krb5-configuration
- Data type representing the configuration of the Kerberos 5 PAM module.
- This type has the following parameters:
- @table @asis
- @item @code{pam-krb5} (default: @code{pam-krb5})
- The pam-krb5 package to use.
- @item @code{minimum-uid} (default: @code{1000})
- The smallest user ID for which Kerberos authentications should be attempted.
- Local accounts with lower values will silently fail to authenticate.
- @end table
- @end deftp
- @node LDAP Services
- @subsection LDAP Services
- @cindex LDAP
- @cindex nslcd, LDAP service
- The @code{(gnu services authentication)} module provides the
- @code{nslcd-service-type}, which can be used to authenticate against an LDAP
- server. In addition to configuring the service itself, you may want to add
- @code{ldap} as a name service to the Name Service Switch. @xref{Name Service
- Switch} for detailed information.
- Here is a simple operating system declaration with a default configuration of
- the @code{nslcd-service-type} and a Name Service Switch configuration that
- consults the @code{ldap} name service last:
- @lisp
- (use-service-modules authentication)
- (use-modules (gnu system nss))
- ...
- (operating-system
- ...
- (services
- (cons*
- (service nslcd-service-type)
- (service dhcp-client-service-type)
- %base-services))
- (name-service-switch
- (let ((services (list (name-service (name "db"))
- (name-service (name "files"))
- (name-service (name "ldap")))))
- (name-service-switch
- (inherit %mdns-host-lookup-nss)
- (password services)
- (shadow services)
- (group services)
- (netgroup services)
- (gshadow services)))))
- @end lisp
- @c %start of generated documentation for nslcd-configuration
- Available @code{nslcd-configuration} fields are:
- @deftypevr {@code{nslcd-configuration} parameter} package nss-pam-ldapd
- The @code{nss-pam-ldapd} package to use.
- @end deftypevr
- @deftypevr {@code{nslcd-configuration} parameter} maybe-number threads
- The number of threads to start that can handle requests and perform LDAP
- queries. Each thread opens a separate connection to the LDAP server.
- The default is to start 5 threads.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{nslcd-configuration} parameter} string uid
- This specifies the user id with which the daemon should be run.
- Defaults to @samp{"nslcd"}.
- @end deftypevr
- @deftypevr {@code{nslcd-configuration} parameter} string gid
- This specifies the group id with which the daemon should be run.
- Defaults to @samp{"nslcd"}.
- @end deftypevr
- @deftypevr {@code{nslcd-configuration} parameter} log-option log
- This option controls the way logging is done via a list containing
- SCHEME and LEVEL@. The SCHEME argument may either be the symbols
- @samp{none} or @samp{syslog}, or an absolute file name. The LEVEL
- argument is optional and specifies the log level. The log level may be
- one of the following symbols: @samp{crit}, @samp{error}, @samp{warning},
- @samp{notice}, @samp{info} or @samp{debug}. All messages with the
- specified log level or higher are logged.
- Defaults to @samp{("/var/log/nslcd" info)}.
- @end deftypevr
- @deftypevr {@code{nslcd-configuration} parameter} list uri
- The list of LDAP server URIs. Normally, only the first server will be
- used with the following servers as fall-back.
- Defaults to @samp{("ldap://localhost:389/")}.
- @end deftypevr
- @deftypevr {@code{nslcd-configuration} parameter} maybe-string ldap-version
- The version of the LDAP protocol to use. The default is to use the
- maximum version supported by the LDAP library.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{nslcd-configuration} parameter} maybe-string binddn
- Specifies the distinguished name with which to bind to the directory
- server for lookups. The default is to bind anonymously.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{nslcd-configuration} parameter} maybe-string bindpw
- Specifies the credentials with which to bind. This option is only
- applicable when used with binddn.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{nslcd-configuration} parameter} maybe-string rootpwmoddn
- Specifies the distinguished name to use when the root user tries to
- modify a user's password using the PAM module.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{nslcd-configuration} parameter} maybe-string rootpwmodpw
- Specifies the credentials with which to bind if the root user tries to
- change a user's password. This option is only applicable when used with
- rootpwmoddn
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{nslcd-configuration} parameter} maybe-string sasl-mech
- Specifies the SASL mechanism to be used when performing SASL
- authentication.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{nslcd-configuration} parameter} maybe-string sasl-realm
- Specifies the SASL realm to be used when performing SASL authentication.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{nslcd-configuration} parameter} maybe-string sasl-authcid
- Specifies the authentication identity to be used when performing SASL
- authentication.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{nslcd-configuration} parameter} maybe-string sasl-authzid
- Specifies the authorization identity to be used when performing SASL
- authentication.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{nslcd-configuration} parameter} maybe-boolean sasl-canonicalize?
- Determines whether the LDAP server host name should be canonicalised. If
- this is enabled the LDAP library will do a reverse host name lookup. By
- default, it is left up to the LDAP library whether this check is
- performed or not.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{nslcd-configuration} parameter} maybe-string krb5-ccname
- Set the name for the GSS-API Kerberos credentials cache.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{nslcd-configuration} parameter} string base
- The directory search base.
- Defaults to @samp{"dc=example,dc=com"}.
- @end deftypevr
- @deftypevr {@code{nslcd-configuration} parameter} scope-option scope
- Specifies the search scope (subtree, onelevel, base or children). The
- default scope is subtree; base scope is almost never useful for name
- service lookups; children scope is not supported on all servers.
- Defaults to @samp{(subtree)}.
- @end deftypevr
- @deftypevr {@code{nslcd-configuration} parameter} maybe-deref-option deref
- Specifies the policy for dereferencing aliases. The default policy is
- to never dereference aliases.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{nslcd-configuration} parameter} maybe-boolean referrals
- Specifies whether automatic referral chasing should be enabled. The
- default behaviour is to chase referrals.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{nslcd-configuration} parameter} list-of-map-entries maps
- This option allows for custom attributes to be looked up instead of the
- default RFC 2307 attributes. It is a list of maps, each consisting of
- the name of a map, the RFC 2307 attribute to match and the query
- expression for the attribute as it is available in the directory.
- Defaults to @samp{()}.
- @end deftypevr
- @deftypevr {@code{nslcd-configuration} parameter} list-of-filter-entries filters
- A list of filters consisting of the name of a map to which the filter
- applies and an LDAP search filter expression.
- Defaults to @samp{()}.
- @end deftypevr
- @deftypevr {@code{nslcd-configuration} parameter} maybe-number bind-timelimit
- Specifies the time limit in seconds to use when connecting to the
- directory server. The default value is 10 seconds.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{nslcd-configuration} parameter} maybe-number timelimit
- Specifies the time limit (in seconds) to wait for a response from the
- LDAP server. A value of zero, which is the default, is to wait
- indefinitely for searches to be completed.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{nslcd-configuration} parameter} maybe-number idle-timelimit
- Specifies the period if inactivity (in seconds) after which the con‐
- nection to the LDAP server will be closed. The default is not to time
- out connections.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{nslcd-configuration} parameter} maybe-number reconnect-sleeptime
- Specifies the number of seconds to sleep when connecting to all LDAP
- servers fails. By default one second is waited between the first
- failure and the first retry.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{nslcd-configuration} parameter} maybe-number reconnect-retrytime
- Specifies the time after which the LDAP server is considered to be
- permanently unavailable. Once this time is reached retries will be done
- only once per this time period. The default value is 10 seconds.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{nslcd-configuration} parameter} maybe-ssl-option ssl
- Specifies whether to use SSL/TLS or not (the default is not to). If
- 'start-tls is specified then StartTLS is used rather than raw LDAP over
- SSL.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{nslcd-configuration} parameter} maybe-tls-reqcert-option tls-reqcert
- Specifies what checks to perform on a server-supplied certificate. The
- meaning of the values is described in the ldap.conf(5) manual page.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-cacertdir
- Specifies the directory containing X.509 certificates for peer authen‐
- tication. This parameter is ignored when using GnuTLS.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-cacertfile
- Specifies the path to the X.509 certificate for peer authentication.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-randfile
- Specifies the path to an entropy source. This parameter is ignored when
- using GnuTLS.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-ciphers
- Specifies the ciphers to use for TLS as a string.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-cert
- Specifies the path to the file containing the local certificate for
- client TLS authentication.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-key
- Specifies the path to the file containing the private key for client TLS
- authentication.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{nslcd-configuration} parameter} maybe-number pagesize
- Set this to a number greater than 0 to request paged results from the
- LDAP server in accordance with RFC2696. The default (0) is to not
- request paged results.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{nslcd-configuration} parameter} maybe-ignore-users-option nss-initgroups-ignoreusers
- This option prevents group membership lookups through LDAP for the
- specified users. Alternatively, the value 'all-local may be used. With
- that value nslcd builds a full list of non-LDAP users on startup.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{nslcd-configuration} parameter} maybe-number nss-min-uid
- This option ensures that LDAP users with a numeric user id lower than
- the specified value are ignored.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{nslcd-configuration} parameter} maybe-number nss-uid-offset
- This option specifies an offset that is added to all LDAP numeric user
- ids. This can be used to avoid user id collisions with local users.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{nslcd-configuration} parameter} maybe-number nss-gid-offset
- This option specifies an offset that is added to all LDAP numeric group
- ids. This can be used to avoid user id collisions with local groups.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{nslcd-configuration} parameter} maybe-boolean nss-nested-groups
- If this option is set, the member attribute of a group may point to
- another group. Members of nested groups are also returned in the higher
- level group and parent groups are returned when finding groups for a
- specific user. The default is not to perform extra searches for nested
- groups.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{nslcd-configuration} parameter} maybe-boolean nss-getgrent-skipmembers
- If this option is set, the group member list is not retrieved when
- looking up groups. Lookups for finding which groups a user belongs to
- will remain functional so the user will likely still get the correct
- groups assigned on login.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{nslcd-configuration} parameter} maybe-boolean nss-disable-enumeration
- If this option is set, functions which cause all user/group entries to
- be loaded from the directory will not succeed in doing so. This can
- dramatically reduce LDAP server load in situations where there are a
- great number of users and/or groups. This option is not recommended for
- most configurations.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{nslcd-configuration} parameter} maybe-string validnames
- This option can be used to specify how user and group names are verified
- within the system. This pattern is used to check all user and group
- names that are requested and returned from LDAP.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{nslcd-configuration} parameter} maybe-boolean ignorecase
- This specifies whether or not to perform searches using case-insensitive
- matching. Enabling this could open up the system to authorization
- bypass vulnerabilities and introduce nscd cache poisoning
- vulnerabilities which allow denial of service.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{nslcd-configuration} parameter} maybe-boolean pam-authc-ppolicy
- This option specifies whether password policy controls are requested and
- handled from the LDAP server when performing user authentication.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{nslcd-configuration} parameter} maybe-string pam-authc-search
- By default nslcd performs an LDAP search with the user's credentials
- after BIND (authentication) to ensure that the BIND operation was
- successful. The default search is a simple check to see if the user's
- DN exists. A search filter can be specified that will be used instead.
- It should return at least one entry.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{nslcd-configuration} parameter} maybe-string pam-authz-search
- This option allows flexible fine tuning of the authorisation check that
- should be performed. The search filter specified is executed and if any
- entries match, access is granted, otherwise access is denied.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{nslcd-configuration} parameter} maybe-string pam-password-prohibit-message
- If this option is set password modification using pam_ldap will be
- denied and the specified message will be presented to the user instead.
- The message can be used to direct the user to an alternative means of
- changing their password.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{nslcd-configuration} parameter} list pam-services
- List of pam service names for which LDAP authentication should suffice.
- Defaults to @samp{()}.
- @end deftypevr
- @c %end of generated documentation for nslcd-configuration
- @node Web Services
- @subsection Web Services
- @cindex web
- @cindex www
- @cindex HTTP
- The @code{(gnu services web)} module provides the Apache HTTP Server,
- the nginx web server, and also a fastcgi wrapper daemon.
- @subsubheading Apache HTTP Server
- @deffn {Scheme Variable} httpd-service-type
- Service type for the @uref{https://httpd.apache.org/,Apache HTTP} server
- (@dfn{httpd}). The value for this service type is a
- @code{httpd-configuration} record.
- A simple example configuration is given below.
- @lisp
- (service httpd-service-type
- (httpd-configuration
- (config
- (httpd-config-file
- (server-name "www.example.com")
- (document-root "/srv/http/www.example.com")))))
- @end lisp
- Other services can also extend the @code{httpd-service-type} to add to
- the configuration.
- @lisp
- (simple-service 'www.example.com-server httpd-service-type
- (list
- (httpd-virtualhost
- "*:80"
- (list (string-join '("ServerName www.example.com"
- "DocumentRoot /srv/http/www.example.com")
- "\n")))))
- @end lisp
- @end deffn
- The details for the @code{httpd-configuration}, @code{httpd-module},
- @code{httpd-config-file} and @code{httpd-virtualhost} record types are
- given below.
- @deffn {Data Type} httpd-configuration
- This data type represents the configuration for the httpd service.
- @table @asis
- @item @code{package} (default: @code{httpd})
- The httpd package to use.
- @item @code{pid-file} (default: @code{"/var/run/httpd"})
- The pid file used by the shepherd-service.
- @item @code{config} (default: @code{(httpd-config-file)})
- The configuration file to use with the httpd service. The default value
- is a @code{httpd-config-file} record, but this can also be a different
- G-expression that generates a file, for example a @code{plain-file}. A
- file outside of the store can also be specified through a string.
- @end table
- @end deffn
- @deffn {Data Type} httpd-module
- This data type represents a module for the httpd service.
- @table @asis
- @item @code{name}
- The name of the module.
- @item @code{file}
- The file for the module. This can be relative to the httpd package being
- used, the absolute location of a file, or a G-expression for a file
- within the store, for example @code{(file-append mod-wsgi
- "/modules/mod_wsgi.so")}.
- @end table
- @end deffn
- @defvr {Scheme Variable} %default-httpd-modules
- A default list of @code{httpd-module} objects.
- @end defvr
- @deffn {Data Type} httpd-config-file
- This data type represents a configuration file for the httpd service.
- @table @asis
- @item @code{modules} (default: @code{%default-httpd-modules})
- The modules to load. Additional modules can be added here, or loaded by
- additional configuration.
- For example, in order to handle requests for PHP files, you can use Apache’s
- @code{mod_proxy_fcgi} module along with @code{php-fpm-service-type}:
- @lisp
- (service httpd-service-type
- (httpd-configuration
- (config
- (httpd-config-file
- (modules (cons*
- (httpd-module
- (name "proxy_module")
- (file "modules/mod_proxy.so"))
- (httpd-module
- (name "proxy_fcgi_module")
- (file "modules/mod_proxy_fcgi.so"))
- %default-httpd-modules))
- (extra-config (list "\
- <FilesMatch \\.php$>
- SetHandler \"proxy:unix:/var/run/php-fpm.sock|fcgi://localhost/\"
- </FilesMatch>"))))))
- (service php-fpm-service-type
- (php-fpm-configuration
- (socket "/var/run/php-fpm.sock")
- (socket-group "httpd")))
- @end lisp
- @item @code{server-root} (default: @code{httpd})
- The @code{ServerRoot} in the configuration file, defaults to the httpd
- package. Directives including @code{Include} and @code{LoadModule} are
- taken as relative to the server root.
- @item @code{server-name} (default: @code{#f})
- The @code{ServerName} in the configuration file, used to specify the
- request scheme, hostname and port that the server uses to identify
- itself.
- This doesn't need to be set in the server config, and can be specified
- in virtual hosts. The default is @code{#f} to not specify a
- @code{ServerName}.
- @item @code{document-root} (default: @code{"/srv/http"})
- The @code{DocumentRoot} from which files will be served.
- @item @code{listen} (default: @code{'("80")})
- The list of values for the @code{Listen} directives in the config
- file. The value should be a list of strings, when each string can
- specify the port number to listen on, and optionally the IP address and
- protocol to use.
- @item @code{pid-file} (default: @code{"/var/run/httpd"})
- The @code{PidFile} to use. This should match the @code{pid-file} set in
- the @code{httpd-configuration} so that the Shepherd service is
- configured correctly.
- @item @code{error-log} (default: @code{"/var/log/httpd/error_log"})
- The @code{ErrorLog} to which the server will log errors.
- @item @code{user} (default: @code{"httpd"})
- The @code{User} which the server will answer requests as.
- @item @code{group} (default: @code{"httpd"})
- The @code{Group} which the server will answer requests as.
- @item @code{extra-config} (default: @code{(list "TypesConfig etc/httpd/mime.types")})
- A flat list of strings and G-expressions which will be added to the end
- of the configuration file.
- Any values which the service is extended with will be appended to this
- list.
- @end table
- @end deffn
- @deffn {Data Type} httpd-virtualhost
- This data type represents a virtualhost configuration block for the httpd service.
- These should be added to the extra-config for the httpd-service.
- @lisp
- (simple-service 'www.example.com-server httpd-service-type
- (list
- (httpd-virtualhost
- "*:80"
- (list (string-join '("ServerName www.example.com"
- "DocumentRoot /srv/http/www.example.com")
- "\n")))))
- @end lisp
- @table @asis
- @item @code{addresses-and-ports}
- The addresses and ports for the @code{VirtualHost} directive.
- @item @code{contents}
- The contents of the @code{VirtualHost} directive, this should be a list
- of strings and G-expressions.
- @end table
- @end deffn
- @anchor{NGINX}
- @subsubheading NGINX
- @deffn {Scheme Variable} nginx-service-type
- Service type for the @uref{https://nginx.org/,NGinx} web server. The
- value for this service type is a @code{<nginx-configuration>} record.
- A simple example configuration is given below.
- @lisp
- (service nginx-service-type
- (nginx-configuration
- (server-blocks
- (list (nginx-server-configuration
- (server-name '("www.example.com"))
- (root "/srv/http/www.example.com"))))))
- @end lisp
- In addition to adding server blocks to the service configuration
- directly, this service can be extended by other services to add server
- blocks, as in this example:
- @lisp
- (simple-service 'my-extra-server nginx-service-type
- (list (nginx-server-configuration
- (root "/srv/http/extra-website")
- (try-files (list "$uri" "$uri/index.html")))))
- @end lisp
- @end deffn
- At startup, @command{nginx} has not yet read its configuration file, so
- it uses a default file to log error messages. If it fails to load its
- configuration file, that is where error messages are logged. After the
- configuration file is loaded, the default error log file changes as per
- configuration. In our case, startup error messages can be found in
- @file{/var/run/nginx/logs/error.log}, and after configuration in
- @file{/var/log/nginx/error.log}. The second location can be changed
- with the @var{log-directory} configuration option.
- @deffn {Data Type} nginx-configuration
- This data type represents the configuration for NGinx. Some
- configuration can be done through this and the other provided record
- types, or alternatively, a config file can be provided.
- @table @asis
- @item @code{nginx} (default: @code{nginx})
- The nginx package to use.
- @item @code{log-directory} (default: @code{"/var/log/nginx"})
- The directory to which NGinx will write log files.
- @item @code{run-directory} (default: @code{"/var/run/nginx"})
- The directory in which NGinx will create a pid file, and write temporary
- files.
- @item @code{server-blocks} (default: @code{'()})
- A list of @dfn{server blocks} to create in the generated configuration
- file, the elements should be of type
- @code{<nginx-server-configuration>}.
- The following example would setup NGinx to serve @code{www.example.com}
- from the @code{/srv/http/www.example.com} directory, without using
- HTTPS.
- @lisp
- (service nginx-service-type
- (nginx-configuration
- (server-blocks
- (list (nginx-server-configuration
- (server-name '("www.example.com"))
- (root "/srv/http/www.example.com"))))))
- @end lisp
- @item @code{upstream-blocks} (default: @code{'()})
- A list of @dfn{upstream blocks} to create in the generated configuration
- file, the elements should be of type
- @code{<nginx-upstream-configuration>}.
- Configuring upstreams through the @code{upstream-blocks} can be useful
- when combined with @code{locations} in the
- @code{<nginx-server-configuration>} records. The following example
- creates a server configuration with one location configuration, that
- will proxy requests to a upstream configuration, which will handle
- requests with two servers.
- @lisp
- (service
- nginx-service-type
- (nginx-configuration
- (server-blocks
- (list (nginx-server-configuration
- (server-name '("www.example.com"))
- (root "/srv/http/www.example.com")
- (locations
- (list
- (nginx-location-configuration
- (uri "/path1")
- (body '("proxy_pass http://server-proxy;"))))))))
- (upstream-blocks
- (list (nginx-upstream-configuration
- (name "server-proxy")
- (servers (list "server1.example.com"
- "server2.example.com")))))))
- @end lisp
- @item @code{file} (default: @code{#f})
- If a configuration @var{file} is provided, this will be used, rather than
- generating a configuration file from the provided @code{log-directory},
- @code{run-directory}, @code{server-blocks} and @code{upstream-blocks}. For
- proper operation, these arguments should match what is in @var{file} to ensure
- that the directories are created when the service is activated.
- This can be useful if you have an existing configuration file, or it's
- not possible to do what is required through the other parts of the
- nginx-configuration record.
- @item @code{server-names-hash-bucket-size} (default: @code{#f})
- Bucket size for the server names hash tables, defaults to @code{#f} to
- use the size of the processors cache line.
- @item @code{server-names-hash-bucket-max-size} (default: @code{#f})
- Maximum bucket size for the server names hash tables.
- @item @code{modules} (default: @code{'()})
- List of nginx dynamic modules to load. This should be a list of file
- names of loadable modules, as in this example:
- @lisp
- (modules
- (list
- (file-append nginx-accept-language-module "\
- /etc/nginx/modules/ngx_http_accept_language_module.so")
- (file-append nginx-lua-module "\
- /etc/nginx/modules/ngx_http_lua_module.so")))
- @end lisp
- @item @code{lua-package-path} (default: @code{'()})
- List of nginx lua packages to load. This should be a list of package
- names of loadable lua modules, as in this example:
- @lisp
- (lua-package-path (list lua-resty-core
- lua-resty-lrucache
- lua-resty-signal
- lua-tablepool
- lua-resty-shell))
- @end lisp
- @item @code{lua-package-cpath} (default: @code{'()})
- List of nginx lua C packages to load. This should be a list of package
- names of loadable lua C modules, as in this example:
- @lisp
- (lua-package-cpath (list lua-resty-signal))
- @end lisp
- @item @code{global-directives} (default: @code{'((events . ()))})
- Association list of global directives for the top level of the nginx
- configuration. Values may themselves be association lists.
- @lisp
- (global-directives
- `((worker_processes . 16)
- (pcre_jit . on)
- (events . ((worker_connections . 1024)))))
- @end lisp
- @item @code{extra-content} (default: @code{""})
- Extra content for the @code{http} block. Should be string or a string
- valued G-expression.
- @end table
- @end deffn
- @anchor{nginx-server-configuration}
- @deftp {Data Type} nginx-server-configuration
- Data type representing the configuration of an nginx server block.
- This type has the following parameters:
- @table @asis
- @item @code{listen} (default: @code{'("80" "443 ssl")})
- Each @code{listen} directive sets the address and port for IP, or the
- path for a UNIX-domain socket on which the server will accept requests.
- Both address and port, or only address or only port can be specified.
- An address may also be a hostname, for example:
- @lisp
- '("127.0.0.1:8000" "127.0.0.1" "8000" "*:8000" "localhost:8000")
- @end lisp
- @item @code{server-name} (default: @code{(list 'default)})
- A list of server names this server represents. @code{'default} represents the
- default server for connections matching no other server.
- @item @code{root} (default: @code{"/srv/http"})
- Root of the website nginx will serve.
- @item @code{locations} (default: @code{'()})
- A list of @dfn{nginx-location-configuration} or
- @dfn{nginx-named-location-configuration} records to use within this
- server block.
- @item @code{index} (default: @code{(list "index.html")})
- Index files to look for when clients ask for a directory. If it cannot be found,
- Nginx will send the list of files in the directory.
- @item @code{try-files} (default: @code{'()})
- A list of files whose existence is checked in the specified order.
- @code{nginx} will use the first file it finds to process the request.
- @item @code{ssl-certificate} (default: @code{#f})
- Where to find the certificate for secure connections. Set it to @code{#f} if
- you don't have a certificate or you don't want to use HTTPS.
- @item @code{ssl-certificate-key} (default: @code{#f})
- Where to find the private key for secure connections. Set it to @code{#f} if
- you don't have a key or you don't want to use HTTPS.
- @item @code{server-tokens?} (default: @code{#f})
- Whether the server should add its configuration to response.
- @item @code{raw-content} (default: @code{'()})
- A list of raw lines added to the server block.
- @end table
- @end deftp
- @deftp {Data Type} nginx-upstream-configuration
- Data type representing the configuration of an nginx @code{upstream}
- block. This type has the following parameters:
- @table @asis
- @item @code{name}
- Name for this group of servers.
- @item @code{servers}
- Specify the addresses of the servers in the group. The address can be
- specified as a IP address (e.g.@: @samp{127.0.0.1}), domain name
- (e.g.@: @samp{backend1.example.com}) or a path to a UNIX socket using the
- prefix @samp{unix:}. For addresses using an IP address or domain name,
- the default port is 80, and a different port can be specified
- explicitly.
- @end table
- @end deftp
- @deftp {Data Type} nginx-location-configuration
- Data type representing the configuration of an nginx @code{location}
- block. This type has the following parameters:
- @table @asis
- @item @code{uri}
- URI which this location block matches.
- @anchor{nginx-location-configuration body}
- @item @code{body}
- Body of the location block, specified as a list of strings. This can contain
- many
- configuration directives. For example, to pass requests to a upstream
- server group defined using an @code{nginx-upstream-configuration} block,
- the following directive would be specified in the body @samp{(list "proxy_pass
- http://upstream-name;")}.
- @end table
- @end deftp
- @deftp {Data Type} nginx-named-location-configuration
- Data type representing the configuration of an nginx named location
- block. Named location blocks are used for request redirection, and not
- used for regular request processing. This type has the following
- parameters:
- @table @asis
- @item @code{name}
- Name to identify this location block.
- @item @code{body}
- @xref{nginx-location-configuration body}, as the body for named location
- blocks can be used in a similar way to the
- @code{nginx-location-configuration body}. One restriction is that the
- body of a named location block cannot contain location blocks.
- @end table
- @end deftp
- @subsubheading Varnish Cache
- @cindex Varnish
- Varnish is a fast cache server that sits in between web applications
- and end users. It proxies requests from clients and caches the
- accessed URLs such that multiple requests for the same resource only
- creates one request to the back-end.
- @defvr {Scheme Variable} varnish-service-type
- Service type for the Varnish daemon.
- @end defvr
- @deftp {Data Type} varnish-configuration
- Data type representing the @code{varnish} service configuration.
- This type has the following parameters:
- @table @asis
- @item @code{package} (default: @code{varnish})
- The Varnish package to use.
- @item @code{name} (default: @code{"default"})
- A name for this Varnish instance. Varnish will create a directory in
- @file{/var/varnish/} with this name and keep temporary files there. If
- the name starts with a forward slash, it is interpreted as an absolute
- directory name.
- Pass the @code{-n} argument to other Varnish programs to connect to the
- named instance, e.g.@: @command{varnishncsa -n default}.
- @item @code{backend} (default: @code{"localhost:8080"})
- The backend to use. This option has no effect if @code{vcl} is set.
- @item @code{vcl} (default: #f)
- The @dfn{VCL} (Varnish Configuration Language) program to run. If this
- is @code{#f}, Varnish will proxy @code{backend} using the default
- configuration. Otherwise this must be a file-like object with valid
- VCL syntax.
- @c Varnish does not support HTTPS, so keep this URL to avoid confusion.
- For example, to mirror @url{https://www.gnu.org,www.gnu.org} with VCL you
- can do something along these lines:
- @lisp
- (define %gnu-mirror
- (plain-file "gnu.vcl"
- "vcl 4.1;
- backend gnu @{ .host = \"www.gnu.org\"; @}"))
- (operating-system
- ;; @dots{}
- (services (cons (service varnish-service-type
- (varnish-configuration
- (listen '(":80"))
- (vcl %gnu-mirror)))
- %base-services)))
- @end lisp
- The configuration of an already running Varnish instance can be inspected
- and changed using the @command{varnishadm} program.
- Consult the @url{https://varnish-cache.org/docs/,Varnish User Guide} and
- @url{https://book.varnish-software.com/4.0/,Varnish Book} for
- comprehensive documentation on Varnish and its configuration language.
- @item @code{listen} (default: @code{'("localhost:80")})
- List of addresses Varnish will listen on.
- @item @code{storage} (default: @code{'("malloc,128m")})
- List of storage backends that will be available in VCL.
- @item @code{parameters} (default: @code{'()})
- List of run-time parameters in the form @code{'(("parameter" . "value"))}.
- @item @code{extra-options} (default: @code{'()})
- Additional arguments to pass to the @command{varnishd} process.
- @end table
- @end deftp
- @subsubheading Patchwork
- @cindex Patchwork
- Patchwork is a patch tracking system. It can collect patches sent to a
- mailing list, and display them in a web interface.
- @defvr {Scheme Variable} patchwork-service-type
- Service type for Patchwork.
- @end defvr
- The following example is an example of a minimal service for Patchwork, for
- the @code{patchwork.example.com} domain.
- @lisp
- (service patchwork-service-type
- (patchwork-configuration
- (domain "patchwork.example.com")
- (settings-module
- (patchwork-settings-module
- (allowed-hosts (list domain))
- (default-from-email "patchwork@@patchwork.example.com")))
- (getmail-retriever-config
- (getmail-retriever-configuration
- (type "SimpleIMAPSSLRetriever")
- (server "imap.example.com")
- (port 993)
- (username "patchwork")
- (password-command
- (list (file-append coreutils "/bin/cat")
- "/etc/getmail-patchwork-imap-password"))
- (extra-parameters
- '((mailboxes . ("Patches"))))))))
- @end lisp
- There are three records for configuring the Patchwork service. The
- @code{<patchwork-configuration>} relates to the configuration for Patchwork
- within the HTTPD service.
- The @code{settings-module} field within the @code{<patchwork-configuration>}
- record can be populated with the @code{<patchwork-settings-module>} record,
- which describes a settings module that is generated within the Guix store.
- For the @code{database-configuration} field within the
- @code{<patchwork-settings-module>}, the
- @code{<patchwork-database-configuration>} must be used.
- @deftp {Data Type} patchwork-configuration
- Data type representing the Patchwork service configuration. This type has the
- following parameters:
- @table @asis
- @item @code{patchwork} (default: @code{patchwork})
- The Patchwork package to use.
- @item @code{domain}
- The domain to use for Patchwork, this is used in the HTTPD service virtual
- host.
- @item @code{settings-module}
- The settings module to use for Patchwork. As a Django application, Patchwork
- is configured with a Python module containing the settings. This can either be
- an instance of the @code{<patchwork-settings-module>} record, any other record
- that represents the settings in the store, or a directory outside of the
- store.
- @item @code{static-path} (default: @code{"/static/"})
- The path under which the HTTPD service should serve the static files.
- @item @code{getmail-retriever-config}
- The getmail-retriever-configuration record value to use with
- Patchwork. Getmail will be configured with this value, the messages will be
- delivered to Patchwork.
- @end table
- @end deftp
- @deftp {Data Type} patchwork-settings-module
- Data type representing a settings module for Patchwork. Some of these
- settings relate directly to Patchwork, but others relate to Django, the web
- framework used by Patchwork, or the Django Rest Framework library. This type
- has the following parameters:
- @table @asis
- @item @code{database-configuration} (default: @code{(patchwork-database-configuration)})
- The database connection settings used for Patchwork. See the
- @code{<patchwork-database-configuration>} record type for more information.
- @item @code{secret-key-file} (default: @code{"/etc/patchwork/django-secret-key"})
- Patchwork, as a Django web application uses a secret key for cryptographically
- signing values. This file should contain a unique unpredictable value.
- If this file does not exist, it will be created and populated with a random
- value by the patchwork-setup shepherd service.
- This setting relates to Django.
- @item @code{allowed-hosts}
- A list of valid hosts for this Patchwork service. This should at least include
- the domain specified in the @code{<patchwork-configuration>} record.
- This is a Django setting.
- @item @code{default-from-email}
- The email address from which Patchwork should send email by default.
- This is a Patchwork setting.
- @item @code{static-url} (default: @code{#f})
- The URL to use when serving static assets. It can be part of a URL, or a full
- URL, but must end in a @code{/}.
- If the default value is used, the @code{static-path} value from the
- @code{<patchwork-configuration>} record will be used.
- This is a Django setting.
- @item @code{admins} (default: @code{'()})
- Email addresses to send the details of errors that occur. Each value should
- be a list containing two elements, the name and then the email address.
- This is a Django setting.
- @item @code{debug?} (default: @code{#f})
- Whether to run Patchwork in debug mode. If set to @code{#t}, detailed error
- messages will be shown.
- This is a Django setting.
- @item @code{enable-rest-api?} (default: @code{#t})
- Whether to enable the Patchwork REST API.
- This is a Patchwork setting.
- @item @code{enable-xmlrpc?} (default: @code{#t})
- Whether to enable the XML RPC API.
- This is a Patchwork setting.
- @item @code{force-https-links?} (default: @code{#t})
- Whether to use HTTPS links on Patchwork pages.
- This is a Patchwork setting.
- @item @code{extra-settings} (default: @code{""})
- Extra code to place at the end of the Patchwork settings module.
- @end table
- @end deftp
- @deftp {Data Type} patchwork-database-configuration
- Data type representing the database configuration for Patchwork.
- @table @asis
- @item @code{engine} (default: @code{"django.db.backends.postgresql_psycopg2"})
- The database engine to use.
- @item @code{name} (default: @code{"patchwork"})
- The name of the database to use.
- @item @code{user} (default: @code{"httpd"})
- The user to connect to the database as.
- @item @code{password} (default: @code{""})
- The password to use when connecting to the database.
- @item @code{host} (default: @code{""})
- The host to make the database connection to.
- @item @code{port} (default: @code{""})
- The port on which to connect to the database.
- @end table
- @end deftp
- @subsubheading Mumi
- @cindex Mumi, Debbugs Web interface
- @cindex Debbugs, Mumi Web interface
- @uref{https://git.elephly.net/gitweb.cgi?p=software/mumi.git, Mumi} is a
- Web interface to the Debbugs bug tracker, by default for
- @uref{https://bugs.gnu.org, the GNU instance}. Mumi is a Web server,
- but it also fetches and indexes mail retrieved from Debbugs.
- @defvr {Scheme Variable} mumi-service-type
- This is the service type for Mumi.
- @end defvr
- @deftp {Data Type} mumi-configuration
- Data type representing the Mumi service configuration. This type has the
- following fields:
- @table @asis
- @item @code{mumi} (default: @code{mumi})
- The Mumi package to use.
- @item @code{mailer?} (default: @code{#true})
- Whether to enable or disable the mailer component.
- @item @code{mumi-configuration-sender}
- The email address used as the sender for comments.
- @item @code{mumi-configuration-smtp}
- A URI to configure the SMTP settings for Mailutils. This could be
- something like @code{sendmail:///path/to/bin/msmtp} or any other URI
- supported by Mailutils. @xref{SMTP Mailboxes, SMTP Mailboxes,,
- mailutils, GNU@tie{}Mailutils}.
- @end table
- @end deftp
- @subsubheading FastCGI
- @cindex fastcgi
- @cindex fcgiwrap
- FastCGI is an interface between the front-end and the back-end of a web
- service. It is a somewhat legacy facility; new web services should
- generally just talk HTTP between the front-end and the back-end.
- However there are a number of back-end services such as PHP or the
- optimized HTTP Git repository access that use FastCGI, so we have
- support for it in Guix.
- To use FastCGI, you configure the front-end web server (e.g., nginx) to
- dispatch some subset of its requests to the fastcgi backend, which
- listens on a local TCP or UNIX socket. There is an intermediary
- @code{fcgiwrap} program that sits between the actual backend process and
- the web server. The front-end indicates which backend program to run,
- passing that information to the @code{fcgiwrap} process.
- @defvr {Scheme Variable} fcgiwrap-service-type
- A service type for the @code{fcgiwrap} FastCGI proxy.
- @end defvr
- @deftp {Data Type} fcgiwrap-configuration
- Data type representing the configuration of the @code{fcgiwrap} service.
- This type has the following parameters:
- @table @asis
- @item @code{package} (default: @code{fcgiwrap})
- The fcgiwrap package to use.
- @item @code{socket} (default: @code{tcp:127.0.0.1:9000})
- The socket on which the @code{fcgiwrap} process should listen, as a
- string. Valid @var{socket} values include
- @code{unix:@var{/path/to/unix/socket}},
- @code{tcp:@var{dot.ted.qu.ad}:@var{port}} and
- @code{tcp6:[@var{ipv6_addr}]:port}.
- @item @code{user} (default: @code{fcgiwrap})
- @itemx @code{group} (default: @code{fcgiwrap})
- The user and group names, as strings, under which to run the
- @code{fcgiwrap} process. The @code{fastcgi} service will ensure that if
- the user asks for the specific user or group names @code{fcgiwrap} that
- the corresponding user and/or group is present on the system.
- It is possible to configure a FastCGI-backed web service to pass HTTP
- authentication information from the front-end to the back-end, and to
- allow @code{fcgiwrap} to run the back-end process as a corresponding
- local user. To enable this capability on the back-end, run
- @code{fcgiwrap} as the @code{root} user and group. Note that this
- capability also has to be configured on the front-end as well.
- @end table
- @end deftp
- @anchor{PHP-FPM}
- @subsubheading PHP-FPM
- @cindex php-fpm
- PHP-FPM (FastCGI Process Manager) is an alternative PHP FastCGI implementation
- with some additional features useful for sites of any size.
- These features include:
- @itemize @bullet
- @item Adaptive process spawning
- @item Basic statistics (similar to Apache's mod_status)
- @item Advanced process management with graceful stop/start
- @item Ability to start workers with different uid/gid/chroot/environment
- and different php.ini (replaces safe_mode)
- @item Stdout & stderr logging
- @item Emergency restart in case of accidental opcode cache destruction
- @item Accelerated upload support
- @item Support for a "slowlog"
- @item Enhancements to FastCGI, such as fastcgi_finish_request() -
- a special function to finish request & flush all data while continuing to do
- something time-consuming (video converting, stats processing, etc.)
- @end itemize
- ...@: and much more.
- @defvr {Scheme Variable} php-fpm-service-type
- A Service type for @code{php-fpm}.
- @end defvr
- @deftp {Data Type} php-fpm-configuration
- Data Type for php-fpm service configuration.
- @table @asis
- @item @code{php} (default: @code{php})
- The php package to use.
- @item @code{socket} (default: @code{(string-append "/var/run/php" (version-major (package-version php)) "-fpm.sock")})
- The address on which to accept FastCGI requests. Valid syntaxes are:
- @table @asis
- @item @code{"ip.add.re.ss:port"}
- Listen on a TCP socket to a specific address on a specific port.
- @item @code{"port"}
- Listen on a TCP socket to all addresses on a specific port.
- @item @code{"/path/to/unix/socket"}
- Listen on a unix socket.
- @end table
- @item @code{user} (default: @code{php-fpm})
- User who will own the php worker processes.
- @item @code{group} (default: @code{php-fpm})
- Group of the worker processes.
- @item @code{socket-user} (default: @code{php-fpm})
- User who can speak to the php-fpm socket.
- @item @code{socket-group} (default: @code{nginx})
- Group that can speak to the php-fpm socket.
- @item @code{pid-file} (default: @code{(string-append "/var/run/php" (version-major (package-version php)) "-fpm.pid")})
- The process id of the php-fpm process is written to this file
- once the service has started.
- @item @code{log-file} (default: @code{(string-append "/var/log/php" (version-major (package-version php)) "-fpm.log")})
- Log for the php-fpm master process.
- @item @code{process-manager} (default: @code{(php-fpm-dynamic-process-manager-configuration)})
- Detailed settings for the php-fpm process manager.
- Must be one of:
- @table @asis
- @item @code{<php-fpm-dynamic-process-manager-configuration>}
- @item @code{<php-fpm-static-process-manager-configuration>}
- @item @code{<php-fpm-on-demand-process-manager-configuration>}
- @end table
- @item @code{display-errors} (default @code{#f})
- Determines whether php errors and warning should be sent to clients
- and displayed in their browsers.
- This is useful for local php development, but a security risk for public sites,
- as error messages can reveal passwords and personal data.
- @item @code{timezone} (default @code{#f})
- Specifies @code{php_admin_value[date.timezone]} parameter.
- @item @code{workers-logfile} (default @code{(string-append "/var/log/php" (version-major (package-version php)) "-fpm.www.log")})
- This file will log the @code{stderr} outputs of php worker processes.
- Can be set to @code{#f} to disable logging.
- @item @code{file} (default @code{#f})
- An optional override of the whole configuration.
- You can use the @code{mixed-text-file} function or an absolute filepath for it.
- @item @code{php-ini-file} (default @code{#f})
- An optional override of the default php settings.
- It may be any ``file-like'' object (@pxref{G-Expressions, file-like objects}).
- You can use the @code{mixed-text-file} function or an absolute filepath for it.
- For local development it is useful to set a higher timeout and memory
- limit for spawned php processes. This be accomplished with the
- following operating system configuration snippet:
- @lisp
- (define %local-php-ini
- (plain-file "php.ini"
- "memory_limit = 2G
- max_execution_time = 1800"))
- (operating-system
- ;; @dots{}
- (services (cons (service php-fpm-service-type
- (php-fpm-configuration
- (php-ini-file %local-php-ini)))
- %base-services)))
- @end lisp
- Consult the @url{https://www.php.net/manual/en/ini.core.php,core php.ini
- directives} for comprehensive documentation on the acceptable
- @file{php.ini} directives.
- @end table
- @end deftp
- @deftp {Data type} php-fpm-dynamic-process-manager-configuration
- Data Type for the @code{dynamic} php-fpm process manager. With the
- @code{dynamic} process manager, spare worker processes are kept around
- based on its configured limits.
- @table @asis
- @item @code{max-children} (default: @code{5})
- Maximum of worker processes.
- @item @code{start-servers} (default: @code{2})
- How many worker processes should be started on start-up.
- @item @code{min-spare-servers} (default: @code{1})
- How many spare worker processes should be kept around at minimum.
- @item @code{max-spare-servers} (default: @code{3})
- How many spare worker processes should be kept around at maximum.
- @end table
- @end deftp
- @deftp {Data type} php-fpm-static-process-manager-configuration
- Data Type for the @code{static} php-fpm process manager. With the
- @code{static} process manager, an unchanging number of worker processes
- are created.
- @table @asis
- @item @code{max-children} (default: @code{5})
- Maximum of worker processes.
- @end table
- @end deftp
- @deftp {Data type} php-fpm-on-demand-process-manager-configuration
- Data Type for the @code{on-demand} php-fpm process manager. With the
- @code{on-demand} process manager, worker processes are only created as
- requests arrive.
- @table @asis
- @item @code{max-children} (default: @code{5})
- Maximum of worker processes.
- @item @code{process-idle-timeout} (default: @code{10})
- The time in seconds after which a process with no requests is killed.
- @end table
- @end deftp
- @deffn {Scheme Procedure} nginx-php-location @
- [#:nginx-package nginx] @
- [socket (string-append "/var/run/php" @
- (version-major (package-version php)) @
- "-fpm.sock")]
- A helper function to quickly add php to an @code{nginx-server-configuration}.
- @end deffn
- A simple services setup for nginx with php can look like this:
- @lisp
- (services (cons* (service dhcp-client-service-type)
- (service php-fpm-service-type)
- (service nginx-service-type
- (nginx-server-configuration
- (server-name '("example.com"))
- (root "/srv/http/")
- (locations
- (list (nginx-php-location)))
- (listen '("80"))
- (ssl-certificate #f)
- (ssl-certificate-key #f)))
- %base-services))
- @end lisp
- @cindex cat-avatar-generator
- The cat avatar generator is a simple service to demonstrate the use of php-fpm
- in @code{Nginx}. It is used to generate cat avatar from a seed, for instance
- the hash of a user's email address.
- @deffn {Scheme Procedure} cat-avatar-generator-service @
- [#:cache-dir "/var/cache/cat-avatar-generator"] @
- [#:package cat-avatar-generator] @
- [#:configuration (nginx-server-configuration)]
- Returns an nginx-server-configuration that inherits @code{configuration}. It
- extends the nginx configuration to add a server block that serves @code{package},
- a version of cat-avatar-generator. During execution, cat-avatar-generator will
- be able to use @code{cache-dir} as its cache directory.
- @end deffn
- A simple setup for cat-avatar-generator can look like this:
- @lisp
- (services (cons* (cat-avatar-generator-service
- #:configuration
- (nginx-server-configuration
- (server-name '("example.com"))))
- ...
- %base-services))
- @end lisp
- @subsubheading Hpcguix-web
- @cindex hpcguix-web
- The @uref{https://github.com/UMCUGenetics/hpcguix-web/, hpcguix-web}
- program is a customizable web interface to browse Guix packages,
- initially designed for users of high-performance computing (HPC)
- clusters.
- @defvr {Scheme Variable} hpcguix-web-service-type
- The service type for @code{hpcguix-web}.
- @end defvr
- @deftp {Data Type} hpcguix-web-configuration
- Data type for the hpcguix-web service configuration.
- @table @asis
- @item @code{specs}
- A gexp (@pxref{G-Expressions}) specifying the hpcguix-web service
- configuration. The main items available in this spec are:
- @table @asis
- @item @code{title-prefix} (default: @code{"hpcguix | "})
- The page title prefix.
- @item @code{guix-command} (default: @code{"guix"})
- The @command{guix} command.
- @item @code{package-filter-proc} (default: @code{(const #t)})
- A procedure specifying how to filter packages that are displayed.
- @item @code{package-page-extension-proc} (default: @code{(const '())})
- Extension package for @code{hpcguix-web}.
- @item @code{menu} (default: @code{'()})
- Additional entry in page @code{menu}.
- @item @code{channels} (default: @code{%default-channels})
- List of channels from which the package list is built (@pxref{Channels}).
- @item @code{package-list-expiration} (default: @code{(* 12 3600)})
- The expiration time, in seconds, after which the package list is rebuilt from
- the latest instances of the given channels.
- @end table
- See the hpcguix-web repository for a
- @uref{https://github.com/UMCUGenetics/hpcguix-web/blob/master/hpcweb-configuration.scm,
- complete example}.
- @item @code{package} (default: @code{hpcguix-web})
- The hpcguix-web package to use.
- @item @code{address} (default: @code{"127.0.0.1"})
- The IP address to listen to.
- @item @code{port} (default: @code{5000})
- The port number to listen to.
- @end table
- @end deftp
- A typical hpcguix-web service declaration looks like this:
- @lisp
- (service hpcguix-web-service-type
- (hpcguix-web-configuration
- (specs
- #~(define site-config
- (hpcweb-configuration
- (title-prefix "Guix-HPC - ")
- (menu '(("/about" "ABOUT"))))))))
- @end lisp
- @quotation Note
- The hpcguix-web service periodically updates the package list it publishes by
- pulling channels from Git. To that end, it needs to access X.509 certificates
- so that it can authenticate Git servers when communicating over HTTPS, and it
- assumes that @file{/etc/ssl/certs} contains those certificates.
- Thus, make sure to add @code{nss-certs} or another certificate package to the
- @code{packages} field of your configuration. @ref{X.509 Certificates}, for
- more information on X.509 certificates.
- @end quotation
- @subsubheading gmnisrv
- @cindex gmnisrv
- The @uref{https://git.sr.ht/~sircmpwn/gmnisrv, gmnisrv} program is a
- simple @uref{https://gemini.circumlunar.space/, Gemini} protocol server.
- @deffn {Scheme Variable} gmnisrv-service-type
- This is the type of the gmnisrv service, whose value should be a
- @code{gmnisrv-configuration} object, as in this example:
- @lisp
- (service gmnisrv-service-type
- (gmnisrv-configuration
- (config-file (local-file "./my-gmnisrv.ini"))))
- @end lisp
- @end deffn
- @deftp {Data Type} gmnisrv-configuration
- Data type representing the configuration of gmnisrv.
- @table @asis
- @item @code{package} (default: @var{gmnisrv})
- Package object of the gmnisrv server.
- @item @code{config-file} (default: @code{%default-gmnisrv-config-file})
- File-like object of the gmnisrv configuration file to use. The default
- configuration listens on port 1965 and serves files from
- @file{/srv/gemini}. Certificates are stored in
- @file{/var/lib/gemini/certs}. For more information, run @command{man
- gmnisrv} and @command{man gmnisrv.ini}.
- @end table
- @end deftp
- @subsubheading Agate
- @cindex agate
- The @uref{gemini://qwertqwefsday.eu/agate.gmi, Agate}
- (@uref{https://github.com/mbrubeck/agate, GitHub page over HTTPS})
- program is a simple @uref{https://gemini.circumlunar.space/, Gemini}
- protocol server written in Rust.
- @deffn {Scheme Variable} agate-service-type
- This is the type of the agate service, whose value should be an
- @code{agate-service-type} object, as in this example:
- @lisp
- (service agate-service-type
- (agate-configuration
- (content "/srv/gemini")
- (cert "/srv/cert.pem")
- (key "/srv/key.rsa")))
- @end lisp
- The example above represents the minimal tweaking necessary to get Agate
- up and running. Specifying the path to the certificate and key is
- always necessary, as the Gemini protocol requires TLS by default.
- To obtain a certificate and a key, you could, for example, use OpenSSL,
- running a command similar to the following example:
- @example
- openssl req -x509 -newkey rsa:4096 -keyout key.rsa -out cert.pem \
- -days 3650 -nodes -subj "/CN=example.com"
- @end example
- Of course, you'll have to replace @i{example.com} with your own domain
- name, and then point the Agate configuration towards the path of the
- generated key and certificate.
- @end deffn
- @deftp {Data Type} agate-configuration
- Data type representing the configuration of Agate.
- @table @asis
- @item @code{package} (default: @code{agate})
- The package object of the Agate server.
- @item @code{content} (default: @file{"/srv/gemini"})
- The directory from which Agate will serve files.
- @item @code{cert} (default: @code{#f})
- The path to the TLS certificate PEM file to be used for encrypted
- connections. Must be filled in with a value from the user.
- @item @code{key} (default: @code{#f})
- The path to the PKCS8 private key file to be used for encrypted
- connections. Must be filled in with a value from the user.
- @item @code{addr} (default: @code{'("0.0.0.0:1965" "[::]:1965")})
- A list of the addresses to listen on.
- @item @code{hostname} (default: @code{#f})
- The domain name of this Gemini server. Optional.
- @item @code{lang} (default: @code{#f})
- RFC 4646 language code(s) for text/gemini documents. Optional.
- @item @code{silent?} (default: @code{#f})
- Set to @code{#t} to disable logging output.
- @item @code{serve-secret?} (default: @code{#f})
- Set to @code{#t} to serve secret files (files/directories starting with
- a dot).
- @item @code{log-ip?} (default: @code{#t})
- Whether or not to output IP addresses when logging.
- @item @code{user} (default: @code{"agate"})
- Owner of the @code{agate} process.
- @item @code{group} (default: @code{"agate"})
- Owner's group of the @code{agate} process.
- @item @code{log-file} (default: @file{"/var/log/agate.log"})
- The file which should store the logging output of Agate.
- @end table
- @end deftp
- @node Certificate Services
- @subsection Certificate Services
- @cindex Web
- @cindex HTTP, HTTPS
- @cindex Let's Encrypt
- @cindex TLS certificates
- The @code{(gnu services certbot)} module provides a service to
- automatically obtain a valid TLS certificate from the Let's Encrypt
- certificate authority. These certificates can then be used to serve
- content securely over HTTPS or other TLS-based protocols, with the
- knowledge that the client will be able to verify the server's
- authenticity.
- @url{https://letsencrypt.org/, Let's Encrypt} provides the
- @code{certbot} tool to automate the certification process. This tool
- first securely generates a key on the server. It then makes a request
- to the Let's Encrypt certificate authority (CA) to sign the key. The CA
- checks that the request originates from the host in question by using a
- challenge-response protocol, requiring the server to provide its
- response over HTTP@. If that protocol completes successfully, the CA
- signs the key, resulting in a certificate. That certificate is valid
- for a limited period of time, and therefore to continue to provide TLS
- services, the server needs to periodically ask the CA to renew its
- signature.
- The certbot service automates this process: the initial key
- generation, the initial certification request to the Let's Encrypt
- service, the web server challenge/response integration, writing the
- certificate to disk, the automated periodic renewals, and the deployment
- tasks associated with the renewal (e.g.@: reloading services, copying keys
- with different permissions).
- Certbot is run twice a day, at a random minute within the hour. It
- won't do anything until your certificates are due for renewal or
- revoked, but running it regularly would give your service a chance of
- staying online in case a Let's Encrypt-initiated revocation happened for
- some reason.
- By using this service, you agree to the ACME Subscriber Agreement, which
- can be found there:
- @url{https://acme-v01.api.letsencrypt.org/directory}.
- @defvr {Scheme Variable} certbot-service-type
- A service type for the @code{certbot} Let's Encrypt client. Its value
- must be a @code{certbot-configuration} record as in this example:
- @lisp
- (define %nginx-deploy-hook
- (program-file
- "nginx-deploy-hook"
- #~(let ((pid (call-with-input-file "/var/run/nginx/pid" read)))
- (kill pid SIGHUP))))
- (service certbot-service-type
- (certbot-configuration
- (email "foo@@example.net")
- (certificates
- (list
- (certificate-configuration
- (domains '("example.net" "www.example.net"))
- (deploy-hook %nginx-deploy-hook))
- (certificate-configuration
- (domains '("bar.example.net")))))))
- @end lisp
- See below for details about @code{certbot-configuration}.
- @end defvr
- @deftp {Data Type} certbot-configuration
- Data type representing the configuration of the @code{certbot} service.
- This type has the following parameters:
- @table @asis
- @item @code{package} (default: @code{certbot})
- The certbot package to use.
- @item @code{webroot} (default: @code{/var/www})
- The directory from which to serve the Let's Encrypt challenge/response
- files.
- @item @code{certificates} (default: @code{()})
- A list of @code{certificates-configuration}s for which to generate
- certificates and request signatures. Each certificate has a @code{name}
- and several @code{domains}.
- @item @code{email} (default: @code{#f})
- Optional email address used for registration and recovery contact.
- Setting this is encouraged as it allows you to receive important
- notifications about the account and issued certificates.
- @item @code{server} (default: @code{#f})
- Optional URL of ACME server. Setting this overrides certbot's default,
- which is the Let's Encrypt server.
- @item @code{rsa-key-size} (default: @code{2048})
- Size of the RSA key.
- @item @code{default-location} (default: @i{see below})
- The default @code{nginx-location-configuration}. Because @code{certbot}
- needs to be able to serve challenges and responses, it needs to be able
- to run a web server. It does so by extending the @code{nginx} web
- service with an @code{nginx-server-configuration} listening on the
- @var{domains} on port 80, and which has a
- @code{nginx-location-configuration} for the @code{/.well-known/} URI
- path subspace used by Let's Encrypt. @xref{Web Services}, for more on
- these nginx configuration data types.
- Requests to other URL paths will be matched by the
- @code{default-location}, which if present is added to all
- @code{nginx-server-configuration}s.
- By default, the @code{default-location} will issue a redirect from
- @code{http://@var{domain}/...} to @code{https://@var{domain}/...}, leaving
- you to define what to serve on your site via @code{https}.
- Pass @code{#f} to not issue a default location.
- @end table
- @end deftp
- @deftp {Data Type} certificate-configuration
- Data type representing the configuration of a certificate.
- This type has the following parameters:
- @table @asis
- @item @code{name} (default: @i{see below})
- This name is used by Certbot for housekeeping and in file paths; it
- doesn't affect the content of the certificate itself. To see
- certificate names, run @code{certbot certificates}.
- Its default is the first provided domain.
- @item @code{domains} (default: @code{()})
- The first domain provided will be the subject CN of the certificate, and
- all domains will be Subject Alternative Names on the certificate.
- @item @code{challenge} (default: @code{#f})
- The challenge type that has to be run by certbot. If @code{#f} is specified,
- default to the HTTP challenge. If a value is specified, defaults to the
- manual plugin (see @code{authentication-hook}, @code{cleanup-hook} and
- the documentation at @url{https://certbot.eff.org/docs/using.html#hooks}),
- and gives Let's Encrypt permission to log the public IP address of the
- requesting machine.
- @item @code{csr} (default: @code{#f})
- File name of Certificate Signing Request (CSR) in DER or PEM format.
- If @code{#f} is specified, this argument will not be passed to certbot.
- If a value is specified, certbot will use it to obtain a certificate, instead of
- using a self-generated CSR.
- The domain-name(s) mentioned in @code{domains}, must be consistent with the
- domain-name(s) mentioned in CSR file.
- @item @code{authentication-hook} (default: @code{#f})
- Command to be run in a shell once for each certificate challenge to be
- answered. For this command, the shell variable @code{$CERTBOT_DOMAIN}
- will contain the domain being authenticated, @code{$CERTBOT_VALIDATION}
- contains the validation string and @code{$CERTBOT_TOKEN} contains the
- file name of the resource requested when performing an HTTP-01 challenge.
- @item @code{cleanup-hook} (default: @code{#f})
- Command to be run in a shell once for each certificate challenge that
- have been answered by the @code{auth-hook}. For this command, the shell
- variables available in the @code{auth-hook} script are still available, and
- additionally @code{$CERTBOT_AUTH_OUTPUT} will contain the standard output
- of the @code{auth-hook} script.
- @item @code{deploy-hook} (default: @code{#f})
- Command to be run in a shell once for each successfully issued
- certificate. For this command, the shell variable
- @code{$RENEWED_LINEAGE} will point to the config live subdirectory (for
- example, @samp{"/etc/letsencrypt/live/example.com"}) containing the new
- certificates and keys; the shell variable @code{$RENEWED_DOMAINS} will
- contain a space-delimited list of renewed certificate domains (for
- example, @samp{"example.com www.example.com"}.
- @end table
- @end deftp
- For each @code{certificate-configuration}, the certificate is saved to
- @code{/etc/letsencrypt/live/@var{name}/fullchain.pem} and the key is
- saved to @code{/etc/letsencrypt/live/@var{name}/privkey.pem}.
- @node DNS Services
- @subsection DNS Services
- @cindex DNS (domain name system)
- @cindex domain name system (DNS)
- The @code{(gnu services dns)} module provides services related to the
- @dfn{domain name system} (DNS). It provides a server service for hosting
- an @emph{authoritative} DNS server for multiple zones, slave or master.
- This service uses @uref{https://www.knot-dns.cz/, Knot DNS}. And also a
- caching and forwarding DNS server for the LAN, which uses
- @uref{http://www.thekelleys.org.uk/dnsmasq/doc.html, dnsmasq}.
- @subsubheading Knot Service
- An example configuration of an authoritative server for two zones, one master
- and one slave, is:
- @lisp
- (define-zone-entries example.org.zone
- ;; Name TTL Class Type Data
- ("@@" "" "IN" "A" "127.0.0.1")
- ("@@" "" "IN" "NS" "ns")
- ("ns" "" "IN" "A" "127.0.0.1"))
- (define master-zone
- (knot-zone-configuration
- (domain "example.org")
- (zone (zone-file
- (origin "example.org")
- (entries example.org.zone)))))
- (define slave-zone
- (knot-zone-configuration
- (domain "plop.org")
- (dnssec-policy "default")
- (master (list "plop-master"))))
- (define plop-master
- (knot-remote-configuration
- (id "plop-master")
- (address (list "208.76.58.171"))))
- (operating-system
- ;; ...
- (services (cons* (service knot-service-type
- (knot-configuration
- (remotes (list plop-master))
- (zones (list master-zone slave-zone))))
- ;; ...
- %base-services)))
- @end lisp
- @deffn {Scheme Variable} knot-service-type
- This is the type for the Knot DNS server.
- Knot DNS is an authoritative DNS server, meaning that it can serve multiple
- zones, that is to say domain names you would buy from a registrar. This server
- is not a resolver, meaning that it can only resolve names for which it is
- authoritative. This server can be configured to serve zones as a master server
- or a slave server as a per-zone basis. Slave zones will get their data from
- masters, and will serve it as an authoritative server. From the point of view
- of a resolver, there is no difference between master and slave.
- The following data types are used to configure the Knot DNS server:
- @end deffn
- @deftp {Data Type} knot-key-configuration
- Data type representing a key.
- This type has the following parameters:
- @table @asis
- @item @code{id} (default: @code{""})
- An identifier for other configuration fields to refer to this key. IDs must
- be unique and must not be empty.
- @item @code{algorithm} (default: @code{#f})
- The algorithm to use. Choose between @code{#f}, @code{'hmac-md5},
- @code{'hmac-sha1}, @code{'hmac-sha224}, @code{'hmac-sha256}, @code{'hmac-sha384}
- and @code{'hmac-sha512}.
- @item @code{secret} (default: @code{""})
- The secret key itself.
- @end table
- @end deftp
- @deftp {Data Type} knot-acl-configuration
- Data type representing an Access Control List (ACL) configuration.
- This type has the following parameters:
- @table @asis
- @item @code{id} (default: @code{""})
- An identifier for other configuration fields to refer to this key. IDs must be
- unique and must not be empty.
- @item @code{address} (default: @code{'()})
- An ordered list of IP addresses, network subnets, or network ranges represented
- with strings. The query must match one of them. Empty value means that
- address match is not required.
- @item @code{key} (default: @code{'()})
- An ordered list of references to keys represented with strings. The string
- must match a key ID defined in a @code{knot-key-configuration}. No key means
- that a key is not require to match that ACL.
- @item @code{action} (default: @code{'()})
- An ordered list of actions that are permitted or forbidden by this ACL@. Possible
- values are lists of zero or more elements from @code{'transfer}, @code{'notify}
- and @code{'update}.
- @item @code{deny?} (default: @code{#f})
- When true, the ACL defines restrictions. Listed actions are forbidden. When
- false, listed actions are allowed.
- @end table
- @end deftp
- @deftp {Data Type} zone-entry
- Data type representing a record entry in a zone file.
- This type has the following parameters:
- @table @asis
- @item @code{name} (default: @code{"@@"})
- The name of the record. @code{"@@"} refers to the origin of the zone. Names
- are relative to the origin of the zone. For example, in the @code{example.org}
- zone, @code{"ns.example.org"} actually refers to @code{ns.example.org.example.org}.
- Names ending with a dot are absolute, which means that @code{"ns.example.org."}
- refers to @code{ns.example.org}.
- @item @code{ttl} (default: @code{""})
- The Time-To-Live (TTL) of this record. If not set, the default TTL is used.
- @item @code{class} (default: @code{"IN"})
- The class of the record. Knot currently supports only @code{"IN"} and
- partially @code{"CH"}.
- @item @code{type} (default: @code{"A"})
- The type of the record. Common types include A (IPv4 address), AAAA (IPv6
- address), NS (Name Server) and MX (Mail eXchange). Many other types are
- defined.
- @item @code{data} (default: @code{""})
- The data contained in the record. For instance an IP address associated with
- an A record, or a domain name associated with an NS record. Remember that
- domain names are relative to the origin unless they end with a dot.
- @end table
- @end deftp
- @deftp {Data Type} zone-file
- Data type representing the content of a zone file.
- This type has the following parameters:
- @table @asis
- @item @code{entries} (default: @code{'()})
- The list of entries. The SOA record is taken care of, so you don't need to
- put it in the list of entries. This list should probably contain an entry
- for your primary authoritative DNS server. Other than using a list of entries
- directly, you can use @code{define-zone-entries} to define a object containing
- the list of entries more easily, that you can later pass to the @code{entries}
- field of the @code{zone-file}.
- @item @code{origin} (default: @code{""})
- The name of your zone. This parameter cannot be empty.
- @item @code{ns} (default: @code{"ns"})
- The domain of your primary authoritative DNS server. The name is relative to
- the origin, unless it ends with a dot. It is mandatory that this primary
- DNS server corresponds to an NS record in the zone and that it is associated
- to an IP address in the list of entries.
- @item @code{mail} (default: @code{"hostmaster"})
- An email address people can contact you at, as the owner of the zone. This
- is translated as @code{<mail>@@<origin>}.
- @item @code{serial} (default: @code{1})
- The serial number of the zone. As this is used to keep track of changes by
- both slaves and resolvers, it is mandatory that it @emph{never} decreases.
- Always increment it when you make a change in your zone.
- @item @code{refresh} (default: @code{(* 2 24 3600)})
- The frequency at which slaves will do a zone transfer. This value is a number
- of seconds. It can be computed by multiplications or with
- @code{(string->duration)}.
- @item @code{retry} (default: @code{(* 15 60)})
- The period after which a slave will retry to contact its master when it fails
- to do so a first time.
- @item @code{expiry} (default: @code{(* 14 24 3600)})
- Default TTL of records. Existing records are considered correct for at most
- this amount of time. After this period, resolvers will invalidate their cache
- and check again that it still exists.
- @item @code{nx} (default: @code{3600})
- Default TTL of inexistent records. This delay is usually short because you want
- your new domains to reach everyone quickly.
- @end table
- @end deftp
- @deftp {Data Type} knot-remote-configuration
- Data type representing a remote configuration.
- This type has the following parameters:
- @table @asis
- @item @code{id} (default: @code{""})
- An identifier for other configuration fields to refer to this remote. IDs must
- be unique and must not be empty.
- @item @code{address} (default: @code{'()})
- An ordered list of destination IP addresses. Addresses are tried in sequence.
- An optional port can be given with the @@ separator. For instance:
- @code{(list "1.2.3.4" "2.3.4.5@@53")}. Default port is 53.
- @item @code{via} (default: @code{'()})
- An ordered list of source IP addresses. An empty list will have Knot choose
- an appropriate source IP@. An optional port can be given with the @@ separator.
- The default is to choose at random.
- @item @code{key} (default: @code{#f})
- A reference to a key, that is a string containing the identifier of a key
- defined in a @code{knot-key-configuration} field.
- @end table
- @end deftp
- @deftp {Data Type} knot-keystore-configuration
- Data type representing a keystore to hold dnssec keys.
- This type has the following parameters:
- @table @asis
- @item @code{id} (default: @code{""})
- The id of the keystore. It must not be empty.
- @item @code{backend} (default: @code{'pem})
- The backend to store the keys in. Can be @code{'pem} or @code{'pkcs11}.
- @item @code{config} (default: @code{"/var/lib/knot/keys/keys"})
- The configuration string of the backend. An example for the PKCS#11 is:
- @code{"pkcs11:token=knot;pin-value=1234 /gnu/store/.../lib/pkcs11/libsofthsm2.so"}.
- For the pem backend, the string represents a path in the file system.
- @end table
- @end deftp
- @deftp {Data Type} knot-policy-configuration
- Data type representing a dnssec policy. Knot DNS is able to automatically
- sign your zones. It can either generate and manage your keys automatically or
- use keys that you generate.
- Dnssec is usually implemented using two keys: a Key Signing Key (KSK) that is
- used to sign the second, and a Zone Signing Key (ZSK) that is used to sign the
- zone. In order to be trusted, the KSK needs to be present in the parent zone
- (usually a top-level domain). If your registrar supports dnssec, you will
- have to send them your KSK's hash so they can add a DS record in their zone.
- This is not automated and need to be done each time you change your KSK.
- The policy also defines the lifetime of keys. Usually, ZSK can be changed
- easily and use weaker cryptographic functions (they use lower parameters) in
- order to sign records quickly, so they are changed often. The KSK however
- requires manual interaction with the registrar, so they are changed less often
- and use stronger parameters because they sign only one record.
- This type has the following parameters:
- @table @asis
- @item @code{id} (default: @code{""})
- The id of the policy. It must not be empty.
- @item @code{keystore} (default: @code{"default"})
- A reference to a keystore, that is a string containing the identifier of a
- keystore defined in a @code{knot-keystore-configuration} field. The
- @code{"default"} identifier means the default keystore (a kasp database that
- was setup by this service).
- @item @code{manual?} (default: @code{#f})
- Whether the key management is manual or automatic.
- @item @code{single-type-signing?} (default: @code{#f})
- When @code{#t}, use the Single-Type Signing Scheme.
- @item @code{algorithm} (default: @code{"ecdsap256sha256"})
- An algorithm of signing keys and issued signatures.
- @item @code{ksk-size} (default: @code{256})
- The length of the KSK@. Note that this value is correct for the default
- algorithm, but would be unsecure for other algorithms.
- @item @code{zsk-size} (default: @code{256})
- The length of the ZSK@. Note that this value is correct for the default
- algorithm, but would be unsecure for other algorithms.
- @item @code{dnskey-ttl} (default: @code{'default})
- The TTL value for DNSKEY records added into zone apex. The special
- @code{'default} value means same as the zone SOA TTL.
- @item @code{zsk-lifetime} (default: @code{(* 30 24 3600)})
- The period between ZSK publication and the next rollover initiation.
- @item @code{propagation-delay} (default: @code{(* 24 3600)})
- An extra delay added for each key rollover step. This value should be high
- enough to cover propagation of data from the master server to all slaves.
- @item @code{rrsig-lifetime} (default: @code{(* 14 24 3600)})
- A validity period of newly issued signatures.
- @item @code{rrsig-refresh} (default: @code{(* 7 24 3600)})
- A period how long before a signature expiration the signature will be refreshed.
- @item @code{nsec3?} (default: @code{#f})
- When @code{#t}, NSEC3 will be used instead of NSEC.
- @item @code{nsec3-iterations} (default: @code{5})
- The number of additional times the hashing is performed.
- @item @code{nsec3-salt-length} (default: @code{8})
- The length of a salt field in octets, which is appended to the original owner
- name before hashing.
- @item @code{nsec3-salt-lifetime} (default: @code{(* 30 24 3600)})
- The validity period of newly issued salt field.
- @end table
- @end deftp
- @deftp {Data Type} knot-zone-configuration
- Data type representing a zone served by Knot.
- This type has the following parameters:
- @table @asis
- @item @code{domain} (default: @code{""})
- The domain served by this configuration. It must not be empty.
- @item @code{file} (default: @code{""})
- The file where this zone is saved. This parameter is ignored by master zones.
- Empty means default location that depends on the domain name.
- @item @code{zone} (default: @code{(zone-file)})
- The content of the zone file. This parameter is ignored by slave zones. It
- must contain a zone-file record.
- @item @code{master} (default: @code{'()})
- A list of master remotes. When empty, this zone is a master. When set, this
- zone is a slave. This is a list of remotes identifiers.
- @item @code{ddns-master} (default: @code{#f})
- The main master. When empty, it defaults to the first master in the list of
- masters.
- @item @code{notify} (default: @code{'()})
- A list of slave remote identifiers.
- @item @code{acl} (default: @code{'()})
- A list of acl identifiers.
- @item @code{semantic-checks?} (default: @code{#f})
- When set, this adds more semantic checks to the zone.
- @item @code{zonefile-sync} (default: @code{0})
- The delay between a modification in memory and on disk. 0 means immediate
- synchronization.
- @item @code{zonefile-load} (default: @code{#f})
- The way the zone file contents are applied during zone load. Possible values
- are:
- @itemize
- @item @code{#f} for using the default value from Knot,
- @item @code{'none} for not using the zone file at all,
- @item @code{'difference} for computing the difference between already available
- contents and zone contents and applying it to the current zone contents,
- @item @code{'difference-no-serial} for the same as @code{'difference}, but
- ignoring the SOA serial in the zone file, while the server takes care of it
- automatically.
- @item @code{'whole} for loading zone contents from the zone file.
- @end itemize
- @item @code{journal-content} (default: @code{#f})
- The way the journal is used to store zone and its changes. Possible values
- are @code{'none} to not use it at all, @code{'changes} to store changes and
- @code{'all} to store contents. @code{#f} does not set this option, so the
- default value from Knot is used.
- @item @code{max-journal-usage} (default: @code{#f})
- The maximum size for the journal on disk. @code{#f} does not set this option,
- so the default value from Knot is used.
- @item @code{max-journal-depth} (default: @code{#f})
- The maximum size of the history. @code{#f} does not set this option, so the
- default value from Knot is used.
- @item @code{max-zone-size} (default: @code{#f})
- The maximum size of the zone file. This limit is enforced for incoming
- transfer and updates. @code{#f} does not set this option, so the default
- value from Knot is used.
- @item @code{dnssec-policy} (default: @code{#f})
- A reference to a @code{knot-policy-configuration} record, or the special
- name @code{"default"}. If the value is @code{#f}, there is no dnssec signing
- on this zone.
- @item @code{serial-policy} (default: @code{'increment})
- A policy between @code{'increment} and @code{'unixtime}.
- @end table
- @end deftp
- @deftp {Data Type} knot-configuration
- Data type representing the Knot configuration.
- This type has the following parameters:
- @table @asis
- @item @code{knot} (default: @code{knot})
- The Knot package.
- @item @code{run-directory} (default: @code{"/var/run/knot"})
- The run directory. This directory will be used for pid file and sockets.
- @item @code{includes} (default: @code{'()})
- A list of strings or file-like objects denoting other files that must be
- included at the top of the configuration file.
- @cindex secrets, Knot service
- This can be used to manage secrets out-of-band. For example, secret
- keys may be stored in an out-of-band file not managed by Guix, and
- thus not visible in @file{/gnu/store}---e.g., you could store secret
- key configuration in @file{/etc/knot/secrets.conf} and add this file
- to the @code{includes} list.
- One can generate a secret tsig key (for nsupdate and zone transfers with the
- keymgr command from the knot package. Note that the package is not automatically
- installed by the service. The following example shows how to generate a new
- tsig key:
- @example
- keymgr -t mysecret > /etc/knot/secrets.conf
- chmod 600 /etc/knot/secrets.conf
- @end example
- Also note that the generated key will be named @var{mysecret}, so it is the
- name that needs to be used in the @var{key} field of the
- @code{knot-acl-configuration} record and in other places that need to refer
- to that key.
- It can also be used to add configuration not supported by this interface.
- @item @code{listen-v4} (default: @code{"0.0.0.0"})
- An ip address on which to listen.
- @item @code{listen-v6} (default: @code{"::"})
- An ip address on which to listen.
- @item @code{listen-port} (default: @code{53})
- A port on which to listen.
- @item @code{keys} (default: @code{'()})
- The list of knot-key-configuration used by this configuration.
- @item @code{acls} (default: @code{'()})
- The list of knot-acl-configuration used by this configuration.
- @item @code{remotes} (default: @code{'()})
- The list of knot-remote-configuration used by this configuration.
- @item @code{zones} (default: @code{'()})
- The list of knot-zone-configuration used by this configuration.
- @end table
- @end deftp
- @subsubheading Knot Resolver Service
- @deffn {Scheme Variable} knot-resolver-service-type
- This is the type of the knot resolver service, whose value should be
- an @code{knot-resolver-configuration} object as in this example:
- @lisp
- (service knot-resolver-service-type
- (knot-resolver-configuration
- (kresd-config-file (plain-file "kresd.conf" "
- net.listen('192.168.0.1', 5353)
- user('knot-resolver', 'knot-resolver')
- modules = @{ 'hints > iterate', 'stats', 'predict' @}
- cache.size = 100 * MB
- "))))
- @end lisp
- For more information, refer its @url{https://knot-resolver.readthedocs.org/en/stable/daemon.html#configuration, manual}.
- @end deffn
- @deftp {Data Type} knot-resolver-configuration
- Data type representing the configuration of knot-resolver.
- @table @asis
- @item @code{package} (default: @var{knot-resolver})
- Package object of the knot DNS resolver.
- @item @code{kresd-config-file} (default: %kresd.conf)
- File-like object of the kresd configuration file to use, by default it
- will listen on @code{127.0.0.1} and @code{::1}.
- @item @code{garbage-collection-interval} (default: 1000)
- Number of milliseconds for @code{kres-cache-gc} to periodically trim the cache.
- @end table
- @end deftp
- @subsubheading Dnsmasq Service
- @deffn {Scheme Variable} dnsmasq-service-type
- This is the type of the dnsmasq service, whose value should be an
- @code{dnsmasq-configuration} object as in this example:
- @lisp
- (service dnsmasq-service-type
- (dnsmasq-configuration
- (no-resolv? #t)
- (servers '("192.168.1.1"))))
- @end lisp
- @end deffn
- @deftp {Data Type} dnsmasq-configuration
- Data type representing the configuration of dnsmasq.
- @table @asis
- @item @code{package} (default: @var{dnsmasq})
- Package object of the dnsmasq server.
- @item @code{no-hosts?} (default: @code{#f})
- When true, don't read the hostnames in /etc/hosts.
- @item @code{port} (default: @code{53})
- The port to listen on. Setting this to zero completely disables DNS
- responses, leaving only DHCP and/or TFTP functions.
- @item @code{local-service?} (default: @code{#t})
- Accept DNS queries only from hosts whose address is on a local subnet,
- ie a subnet for which an interface exists on the server.
- @item @code{listen-addresses} (default: @code{'()})
- Listen on the given IP addresses.
- @item @code{resolv-file} (default: @code{"/etc/resolv.conf"})
- The file to read the IP address of the upstream nameservers from.
- @item @code{no-resolv?} (default: @code{#f})
- When true, don't read @var{resolv-file}.
- @item @code{forward-private-reverse-lookup?} (default: @code{#t})
- When false, all reverse lookups for private IP ranges are answered with
- "no such domain" rather than being forwarded upstream.
- @item @code{query-servers-in-order?} (default: @code{#f})
- When true, dnsmasq queries the servers in the same order as they appear
- in @var{servers}.
- @item @code{servers} (default: @code{'()})
- Specify IP address of upstream servers directly.
- @item @code{addresses} (default: @code{'()})
- For each entry, specify an IP address to return for any host in the
- given domains. Queries in the domains are never forwarded and always
- replied to with the specified IP address.
- This is useful for redirecting hosts locally, for example:
- @lisp
- (service dnsmasq-service-type
- (dnsmasq-configuration
- (addresses
- '(; Redirect to a local web-server.
- "/example.org/127.0.0.1"
- ; Redirect subdomain to a specific IP.
- "/subdomain.example.org/192.168.1.42"))))
- @end lisp
- Note that rules in @file{/etc/hosts} take precedence over this.
- @item @code{cache-size} (default: @code{150})
- Set the size of dnsmasq's cache. Setting the cache size to zero
- disables caching.
- @item @code{negative-cache?} (default: @code{#t})
- When false, disable negative caching.
- @item @code{cpe-id} (default: @code{#f})
- If set, add a CPE (Customer-Premises Equipment) identifier to DNS
- queries which are forwarded upstream.
- @item @code{tftp-enable?} (default: @code{#f})
- Whether to enable the built-in TFTP server.
- @item @code{tftp-no-fail?} (default: @code{#f})
- If true, does not fail dnsmasq if the TFTP server could not start up.
- @item @code{tftp-single-port?} (default: @code{#f})
- Whether to use only one single port for TFTP.
- @item @code{tftp-secure?} (default: @code{#f})
- If true, only files owned by the user running the dnsmasq process are accessible.
- If dnsmasq is being run as root, different rules apply:
- @code{tftp-secure?} has no effect, but only files which have the
- world-readable bit set are accessible.
- @item @code{tftp-max} (default: @code{#f})
- If set, sets the maximal number of concurrent connections allowed.
- @item @code{tftp-mtu} (default: @code{#f})
- If set, sets the MTU for TFTP packets to that value.
- @item @code{tftp-no-blocksize?} (default: @code{#f})
- If true, stops the TFTP server from negotiating the blocksize with a client.
- @item @code{tftp-lowercase?} (default: @code{#f})
- Whether to convert all filenames in TFTP requests to lowercase.
- @item @code{tftp-port-range} (default: @code{#f})
- If set, fixes the dynamical ports (one per client) to the given range
- (@code{"<start>,<end>"}).
- @item @code{tftp-root} (default: @code{/var/empty,lo})
- Look for files to transfer using TFTP relative to the given directory.
- When this is set, TFTP paths which include @samp{..} are rejected, to stop clients
- getting outside the specified root. Absolute paths (starting with @samp{/}) are
- allowed, but they must be within the TFTP-root. If the optional interface
- argument is given, the directory is only used for TFTP requests via that
- interface.
- @item @code{tftp-unique-root} (default: @code{#f})
- If set, add the IP or hardware address of the TFTP client as a path component
- on the end of the TFTP-root. Only valid if a TFTP root is set and the
- directory exists. Defaults to adding IP address (in standard dotted-quad
- format).
- For instance, if @option{--tftp-root} is @samp{/tftp} and client
- @samp{1.2.3.4} requests file @file{myfile} then the effective path will
- be @file{/tftp/1.2.3.4/myfile} if @file{/tftp/1.2.3.4} exists or
- @file{/tftp/myfile} otherwise. When @samp{=mac} is specified it will
- append the MAC address instead, using lowercase zero padded digits
- separated by dashes, e.g.: @samp{01-02-03-04-aa-bb}. Note that
- resolving MAC addresses is only possible if the client is in the local
- network or obtained a DHCP lease from dnsmasq.
- @end table
- @end deftp
- @subsubheading ddclient Service
- @cindex ddclient
- The ddclient service described below runs the ddclient daemon, which takes
- care of automatically updating DNS entries for service providers such as
- @uref{https://dyn.com/dns/, Dyn}.
- The following example show instantiates the service with its default
- configuration:
- @lisp
- (service ddclient-service-type)
- @end lisp
- Note that ddclient needs to access credentials that are stored in a
- @dfn{secret file}, by default @file{/etc/ddclient/secrets} (see
- @code{secret-file} below). You are expected to create this file manually, in
- an ``out-of-band'' fashion (you @emph{could} make this file part of the
- service configuration, for instance by using @code{plain-file}, but it will be
- world-readable @i{via} @file{/gnu/store}). See the examples in the
- @file{share/ddclient} directory of the @code{ddclient} package.
- @c %start of fragment
- Available @code{ddclient-configuration} fields are:
- @deftypevr {@code{ddclient-configuration} parameter} package ddclient
- The ddclient package.
- @end deftypevr
- @deftypevr {@code{ddclient-configuration} parameter} integer daemon
- The period after which ddclient will retry to check IP and domain name.
- Defaults to @samp{300}.
- @end deftypevr
- @deftypevr {@code{ddclient-configuration} parameter} boolean syslog
- Use syslog for the output.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{ddclient-configuration} parameter} string mail
- Mail to user.
- Defaults to @samp{"root"}.
- @end deftypevr
- @deftypevr {@code{ddclient-configuration} parameter} string mail-failure
- Mail failed update to user.
- Defaults to @samp{"root"}.
- @end deftypevr
- @deftypevr {@code{ddclient-configuration} parameter} string pid
- The ddclient PID file.
- Defaults to @samp{"/var/run/ddclient/ddclient.pid"}.
- @end deftypevr
- @deftypevr {@code{ddclient-configuration} parameter} boolean ssl
- Enable SSL support.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{ddclient-configuration} parameter} string user
- Specifies the user name or ID that is used when running ddclient
- program.
- Defaults to @samp{"ddclient"}.
- @end deftypevr
- @deftypevr {@code{ddclient-configuration} parameter} string group
- Group of the user who will run the ddclient program.
- Defaults to @samp{"ddclient"}.
- @end deftypevr
- @deftypevr {@code{ddclient-configuration} parameter} string secret-file
- Secret file which will be appended to @file{ddclient.conf} file. This
- file contains credentials for use by ddclient. You are expected to
- create it manually.
- Defaults to @samp{"/etc/ddclient/secrets.conf"}.
- @end deftypevr
- @deftypevr {@code{ddclient-configuration} parameter} list extra-options
- Extra options will be appended to @file{ddclient.conf} file.
- Defaults to @samp{()}.
- @end deftypevr
- @c %end of fragment
- @node VPN Services
- @subsection VPN Services
- @cindex VPN (virtual private network)
- @cindex virtual private network (VPN)
- The @code{(gnu services vpn)} module provides services related to
- @dfn{virtual private networks} (VPNs).
- @subsubheading Bitmask
- @defvr {Scheme Variable} bitmask-service-type
- A service type for the @uref{https://bitmask.net, Bitmask} VPN client. It makes
- the client available in the system and loads its polkit policy. Please note that
- the client expects an active polkit-agent, which is either run by your
- desktop-environment or should be run manually.
- @end defvr
- @subsubheading OpenVPN
- It provides a @emph{client} service for your machine to connect to a
- VPN, and a @emph{server} service for your machine to host a VPN@.
- @deffn {Scheme Procedure} openvpn-client-service @
- [#:config (openvpn-client-configuration)]
- Return a service that runs @command{openvpn}, a VPN daemon, as a client.
- @end deffn
- @deffn {Scheme Procedure} openvpn-server-service @
- [#:config (openvpn-server-configuration)]
- Return a service that runs @command{openvpn}, a VPN daemon, as a server.
- Both can be run simultaneously.
- @end deffn
- @c %automatically generated documentation
- Available @code{openvpn-client-configuration} fields are:
- @deftypevr {@code{openvpn-client-configuration} parameter} package openvpn
- The OpenVPN package.
- @end deftypevr
- @deftypevr {@code{openvpn-client-configuration} parameter} string pid-file
- The OpenVPN pid file.
- Defaults to @samp{"/var/run/openvpn/openvpn.pid"}.
- @end deftypevr
- @deftypevr {@code{openvpn-client-configuration} parameter} proto proto
- The protocol (UDP or TCP) used to open a channel between clients and
- servers.
- Defaults to @samp{udp}.
- @end deftypevr
- @deftypevr {@code{openvpn-client-configuration} parameter} dev dev
- The device type used to represent the VPN connection.
- Defaults to @samp{tun}.
- @end deftypevr
- If you do not have some of these files (eg.@: you use a username and
- password), you can disable any of the following three fields by setting
- it to @code{'disabled}.
- @deftypevr {@code{openvpn-client-configuration} parameter} maybe-string ca
- The certificate authority to check connections against.
- Defaults to @samp{"/etc/openvpn/ca.crt"}.
- @end deftypevr
- @deftypevr {@code{openvpn-client-configuration} parameter} maybe-string cert
- The certificate of the machine the daemon is running on. It should be
- signed by the authority given in @code{ca}.
- Defaults to @samp{"/etc/openvpn/client.crt"}.
- @end deftypevr
- @deftypevr {@code{openvpn-client-configuration} parameter} maybe-string key
- The key of the machine the daemon is running on. It must be the key whose
- certificate is @code{cert}.
- Defaults to @samp{"/etc/openvpn/client.key"}.
- @end deftypevr
- @deftypevr {@code{openvpn-client-configuration} parameter} boolean comp-lzo?
- Whether to use the lzo compression algorithm.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{openvpn-client-configuration} parameter} boolean persist-key?
- Don't re-read key files across SIGUSR1 or --ping-restart.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{openvpn-client-configuration} parameter} boolean persist-tun?
- Don't close and reopen TUN/TAP device or run up/down scripts across
- SIGUSR1 or --ping-restart restarts.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{openvpn-client-configuration} parameter} boolean fast-io?
- (Experimental) Optimize TUN/TAP/UDP I/O writes by avoiding a call to
- poll/epoll/select prior to the write operation.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{openvpn-client-configuration} parameter} number verbosity
- Verbosity level.
- Defaults to @samp{3}.
- @end deftypevr
- @deftypevr {@code{openvpn-client-configuration} parameter} tls-auth-client tls-auth
- Add an additional layer of HMAC authentication on top of the TLS control
- channel to protect against DoS attacks.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{openvpn-client-configuration} parameter} maybe-string auth-user-pass
- Authenticate with server using username/password. The option is a file
- containing username/password on 2 lines. Do not use a file-like object as it
- would be added to the store and readable by any user.
- Defaults to @samp{'disabled}.
- @end deftypevr
- @deftypevr {@code{openvpn-client-configuration} parameter} key-usage verify-key-usage?
- Whether to check the server certificate has server usage extension.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{openvpn-client-configuration} parameter} bind bind?
- Bind to a specific local port number.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{openvpn-client-configuration} parameter} resolv-retry resolv-retry?
- Retry resolving server address.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{openvpn-client-configuration} parameter} openvpn-remote-list remote
- A list of remote servers to connect to.
- Defaults to @samp{()}.
- Available @code{openvpn-remote-configuration} fields are:
- @deftypevr {@code{openvpn-remote-configuration} parameter} string name
- Server name.
- Defaults to @samp{"my-server"}.
- @end deftypevr
- @deftypevr {@code{openvpn-remote-configuration} parameter} number port
- Port number the server listens to.
- Defaults to @samp{1194}.
- @end deftypevr
- @end deftypevr
- @c %end of automatic openvpn-client documentation
- @c %automatically generated documentation
- Available @code{openvpn-server-configuration} fields are:
- @deftypevr {@code{openvpn-server-configuration} parameter} package openvpn
- The OpenVPN package.
- @end deftypevr
- @deftypevr {@code{openvpn-server-configuration} parameter} string pid-file
- The OpenVPN pid file.
- Defaults to @samp{"/var/run/openvpn/openvpn.pid"}.
- @end deftypevr
- @deftypevr {@code{openvpn-server-configuration} parameter} proto proto
- The protocol (UDP or TCP) used to open a channel between clients and
- servers.
- Defaults to @samp{udp}.
- @end deftypevr
- @deftypevr {@code{openvpn-server-configuration} parameter} dev dev
- The device type used to represent the VPN connection.
- Defaults to @samp{tun}.
- @end deftypevr
- If you do not have some of these files (eg.@: you use a username and
- password), you can disable any of the following three fields by setting
- it to @code{'disabled}.
- @deftypevr {@code{openvpn-server-configuration} parameter} maybe-string ca
- The certificate authority to check connections against.
- Defaults to @samp{"/etc/openvpn/ca.crt"}.
- @end deftypevr
- @deftypevr {@code{openvpn-server-configuration} parameter} maybe-string cert
- The certificate of the machine the daemon is running on. It should be
- signed by the authority given in @code{ca}.
- Defaults to @samp{"/etc/openvpn/client.crt"}.
- @end deftypevr
- @deftypevr {@code{openvpn-server-configuration} parameter} maybe-string key
- The key of the machine the daemon is running on. It must be the key whose
- certificate is @code{cert}.
- Defaults to @samp{"/etc/openvpn/client.key"}.
- @end deftypevr
- @deftypevr {@code{openvpn-server-configuration} parameter} boolean comp-lzo?
- Whether to use the lzo compression algorithm.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{openvpn-server-configuration} parameter} boolean persist-key?
- Don't re-read key files across SIGUSR1 or --ping-restart.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{openvpn-server-configuration} parameter} boolean persist-tun?
- Don't close and reopen TUN/TAP device or run up/down scripts across
- SIGUSR1 or --ping-restart restarts.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{openvpn-server-configuration} parameter} boolean fast-io?
- (Experimental) Optimize TUN/TAP/UDP I/O writes by avoiding a call to
- poll/epoll/select prior to the write operation.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{openvpn-server-configuration} parameter} number verbosity
- Verbosity level.
- Defaults to @samp{3}.
- @end deftypevr
- @deftypevr {@code{openvpn-server-configuration} parameter} tls-auth-server tls-auth
- Add an additional layer of HMAC authentication on top of the TLS control
- channel to protect against DoS attacks.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{openvpn-server-configuration} parameter} number port
- Specifies the port number on which the server listens.
- Defaults to @samp{1194}.
- @end deftypevr
- @deftypevr {@code{openvpn-server-configuration} parameter} ip-mask server
- An ip and mask specifying the subnet inside the virtual network.
- Defaults to @samp{"10.8.0.0 255.255.255.0"}.
- @end deftypevr
- @deftypevr {@code{openvpn-server-configuration} parameter} cidr6 server-ipv6
- A CIDR notation specifying the IPv6 subnet inside the virtual network.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{openvpn-server-configuration} parameter} string dh
- The Diffie-Hellman parameters file.
- Defaults to @samp{"/etc/openvpn/dh2048.pem"}.
- @end deftypevr
- @deftypevr {@code{openvpn-server-configuration} parameter} string ifconfig-pool-persist
- The file that records client IPs.
- Defaults to @samp{"/etc/openvpn/ipp.txt"}.
- @end deftypevr
- @deftypevr {@code{openvpn-server-configuration} parameter} gateway redirect-gateway?
- When true, the server will act as a gateway for its clients.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{openvpn-server-configuration} parameter} boolean client-to-client?
- When true, clients are allowed to talk to each other inside the VPN.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{openvpn-server-configuration} parameter} keepalive keepalive
- Causes ping-like messages to be sent back and forth over the link so
- that each side knows when the other side has gone down. @code{keepalive}
- requires a pair. The first element is the period of the ping sending,
- and the second element is the timeout before considering the other side
- down.
- @end deftypevr
- @deftypevr {@code{openvpn-server-configuration} parameter} number max-clients
- The maximum number of clients.
- Defaults to @samp{100}.
- @end deftypevr
- @deftypevr {@code{openvpn-server-configuration} parameter} string status
- The status file. This file shows a small report on current connection.
- It is truncated and rewritten every minute.
- Defaults to @samp{"/var/run/openvpn/status"}.
- @end deftypevr
- @deftypevr {@code{openvpn-server-configuration} parameter} openvpn-ccd-list client-config-dir
- The list of configuration for some clients.
- Defaults to @samp{()}.
- Available @code{openvpn-ccd-configuration} fields are:
- @deftypevr {@code{openvpn-ccd-configuration} parameter} string name
- Client name.
- Defaults to @samp{"client"}.
- @end deftypevr
- @deftypevr {@code{openvpn-ccd-configuration} parameter} ip-mask iroute
- Client own network
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{openvpn-ccd-configuration} parameter} ip-mask ifconfig-push
- Client VPN IP.
- Defaults to @samp{#f}.
- @end deftypevr
- @end deftypevr
- @c %end of automatic openvpn-server documentation
- @subheading strongSwan
- Currently, the strongSwan service only provides legacy-style configuration with
- @file{ipsec.conf} and @file{ipsec.secrets} files.
- @defvr {Scheme Variable} strongswan-service-type
- A service type for configuring strongSwan for IPsec @acronym{VPN,
- Virtual Private Networking}. Its value must be a
- @code{strongswan-configuration} record as in this example:
- @lisp
- (service strongswan-service-type
- (strongswan-configuration
- (ipsec-conf "/etc/ipsec.conf")
- (ipsec-secrets "/etc/ipsec.secrets")))
- @end lisp
- @end defvr
- @deftp {Data Type} strongswan-configuration
- Data type representing the configuration of the StrongSwan service.
- @table @asis
- @item @code{strongswan}
- The strongSwan package to use for this service.
- @item @code{ipsec-conf} (default: @code{#f})
- The file name of your @file{ipsec.conf}. If not @code{#f}, then this and
- @code{ipsec-secrets} must both be strings.
- @item @code{ipsec-secrets} (default @code{#f})
- The file name of your @file{ipsec.secrets}. If not @code{#f}, then this and
- @code{ipsec-conf} must both be strings.
- @end table
- @end deftp
- @subsubheading Wireguard
- @defvr {Scheme Variable} wireguard-service-type
- A service type for a Wireguard tunnel interface. Its value must be a
- @code{wireguard-configuration} record as in this example:
- @lisp
- (service wireguard-service-type
- (wireguard-configuration
- (peers
- (list
- (wireguard-peer
- (name "my-peer")
- (endpoint "my.wireguard.com:51820")
- (public-key "hzpKg9X1yqu1axN6iJp0mWf6BZGo8m1wteKwtTmDGF4=")
- (allowed-ips '("10.0.0.2/32")))))))
- @end lisp
- @end defvr
- @deftp {Data Type} wireguard-configuration
- Data type representing the configuration of the Wireguard service.
- @table @asis
- @item @code{wireguard}
- The wireguard package to use for this service.
- @item @code{interface} (default: @code{"wg0"})
- The interface name for the VPN.
- @item @code{addresses} (default: @code{'("10.0.0.1/32")})
- The IP addresses to be assigned to the above interface.
- @item @code{port} (default: @code{51820})
- The port on which to listen for incoming connections.
- @item @code{dns} (default: @code{#f})
- The DNS server(s) to announce to VPN clients via DHCP.
- @item @code{private-key} (default: @code{"/etc/wireguard/private.key"})
- The private key file for the interface. It is automatically generated if
- the file does not exist.
- @item @code{peers} (default: @code{'()})
- The authorized peers on this interface. This is a list of
- @var{wireguard-peer} records.
- @end table
- @end deftp
- @deftp {Data Type} wireguard-peer
- Data type representing a Wireguard peer attached to a given interface.
- @table @asis
- @item @code{name}
- The peer name.
- @item @code{endpoint} (default: @code{#f})
- The optional endpoint for the peer, such as
- @code{"demo.wireguard.com:51820"}.
- @item @code{public-key}
- The peer public-key represented as a base64 string.
- @item @code{allowed-ips}
- A list of IP addresses from which incoming traffic for this peer is
- allowed and to which incoming traffic for this peer is directed.
- @item @code{keep-alive} (default: @code{#f})
- An optional time interval in seconds. A packet will be sent to the
- server endpoint once per time interval. This helps receiving
- incoming connections from this peer when you are behind a NAT or
- a firewall.
- @end table
- @end deftp
- @node Network File System
- @subsection Network File System
- @cindex NFS
- The @code{(gnu services nfs)} module provides the following services,
- which are most commonly used in relation to mounting or exporting
- directory trees as @dfn{network file systems} (NFS).
- While it is possible to use the individual components that together make
- up a Network File System service, we recommended to configure an NFS
- server with the @code{nfs-service-type}.
- @subsubheading NFS Service
- @cindex NFS, server
- The NFS service takes care of setting up all NFS component services,
- kernel configuration file systems, and installs configuration files in
- the locations that NFS expects.
- @defvr {Scheme Variable} nfs-service-type
- A service type for a complete NFS server.
- @end defvr
- @deftp {Data Type} nfs-configuration
- This data type represents the configuration of the NFS service and all
- of its subsystems.
- It has the following parameters:
- @table @asis
- @item @code{nfs-utils} (default: @code{nfs-utils})
- The nfs-utils package to use.
- @item @code{nfs-versions} (default: @code{'("4.2" "4.1" "4.0")})
- If a list of string values is provided, the @command{rpc.nfsd} daemon
- will be limited to supporting the given versions of the NFS protocol.
- @item @code{exports} (default: @code{'()})
- This is a list of directories the NFS server should export. Each entry
- is a list consisting of two elements: a directory name and a string
- containing all options. This is an example in which the directory
- @file{/export} is served to all NFS clients as a read-only share:
- @lisp
- (nfs-configuration
- (exports
- '(("/export"
- "*(ro,insecure,no_subtree_check,crossmnt,fsid=0)"))))
- @end lisp
- @item @code{rpcmountd-port} (default: @code{#f})
- The network port that the @command{rpc.mountd} daemon should use.
- @item @code{rpcstatd-port} (default: @code{#f})
- The network port that the @command{rpc.statd} daemon should use.
- @item @code{rpcbind} (default: @code{rpcbind})
- The rpcbind package to use.
- @item @code{idmap-domain} (default: @code{"localdomain"})
- The local NFSv4 domain name.
- @item @code{nfsd-port} (default: @code{2049})
- The network port that the @command{nfsd} daemon should use.
- @item @code{nfsd-threads} (default: @code{8})
- The number of threads used by the @command{nfsd} daemon.
- @item @code{nfsd-tcp?} (default: @code{#t})
- Whether the @command{nfsd} daemon should listen on a TCP socket.
- @item @code{nfsd-udp?} (default: @code{#f})
- Whether the @command{nfsd} daemon should listen on a UDP socket.
- @item @code{pipefs-directory} (default: @code{"/var/lib/nfs/rpc_pipefs"})
- The directory where the pipefs file system is mounted.
- @item @code{debug} (default: @code{'()"})
- A list of subsystems for which debugging output should be enabled. This
- is a list of symbols. Any of these symbols are valid: @code{nfsd},
- @code{nfs}, @code{rpc}, @code{idmap}, @code{statd}, or @code{mountd}.
- @end table
- @end deftp
- If you don't need a complete NFS service or prefer to build it yourself
- you can use the individual component services that are documented below.
- @subsubheading RPC Bind Service
- @cindex rpcbind
- The RPC Bind service provides a facility to map program numbers into
- universal addresses.
- Many NFS related services use this facility. Hence it is automatically
- started when a dependent service starts.
- @defvr {Scheme Variable} rpcbind-service-type
- A service type for the RPC portmapper daemon.
- @end defvr
- @deftp {Data Type} rpcbind-configuration
- Data type representing the configuration of the RPC Bind Service.
- This type has the following parameters:
- @table @asis
- @item @code{rpcbind} (default: @code{rpcbind})
- The rpcbind package to use.
- @item @code{warm-start?} (default: @code{#t})
- If this parameter is @code{#t}, then the daemon will read a
- state file on startup thus reloading state information saved by a previous
- instance.
- @end table
- @end deftp
- @subsubheading Pipefs Pseudo File System
- @cindex pipefs
- @cindex rpc_pipefs
- The pipefs file system is used to transfer NFS related data
- between the kernel and user space programs.
- @defvr {Scheme Variable} pipefs-service-type
- A service type for the pipefs pseudo file system.
- @end defvr
- @deftp {Data Type} pipefs-configuration
- Data type representing the configuration of the pipefs pseudo file system service.
- This type has the following parameters:
- @table @asis
- @item @code{mount-point} (default: @code{"/var/lib/nfs/rpc_pipefs"})
- The directory to which the file system is to be attached.
- @end table
- @end deftp
- @subsubheading GSS Daemon Service
- @cindex GSSD
- @cindex GSS
- @cindex global security system
- The @dfn{global security system} (GSS) daemon provides strong security for RPC
- based protocols.
- Before exchanging RPC requests an RPC client must establish a security
- context. Typically this is done using the Kerberos command @command{kinit}
- or automatically at login time using PAM services (@pxref{Kerberos Services}).
- @defvr {Scheme Variable} gss-service-type
- A service type for the Global Security System (GSS) daemon.
- @end defvr
- @deftp {Data Type} gss-configuration
- Data type representing the configuration of the GSS daemon service.
- This type has the following parameters:
- @table @asis
- @item @code{nfs-utils} (default: @code{nfs-utils})
- The package in which the @command{rpc.gssd} command is to be found.
- @item @code{pipefs-directory} (default: @code{"/var/lib/nfs/rpc_pipefs"})
- The directory where the pipefs file system is mounted.
- @end table
- @end deftp
- @subsubheading IDMAP Daemon Service
- @cindex idmapd
- @cindex name mapper
- The idmap daemon service provides mapping between user IDs and user names.
- Typically it is required in order to access file systems mounted via NFSv4.
- @defvr {Scheme Variable} idmap-service-type
- A service type for the Identity Mapper (IDMAP) daemon.
- @end defvr
- @deftp {Data Type} idmap-configuration
- Data type representing the configuration of the IDMAP daemon service.
- This type has the following parameters:
- @table @asis
- @item @code{nfs-utils} (default: @code{nfs-utils})
- The package in which the @command{rpc.idmapd} command is to be found.
- @item @code{pipefs-directory} (default: @code{"/var/lib/nfs/rpc_pipefs"})
- The directory where the pipefs file system is mounted.
- @item @code{domain} (default: @code{#f})
- The local NFSv4 domain name.
- This must be a string or @code{#f}.
- If it is @code{#f} then the daemon will use the host's fully qualified domain name.
- @item @code{verbosity} (default: @code{0})
- The verbosity level of the daemon.
- @end table
- @end deftp
- @node Continuous Integration
- @subsection Continuous Integration
- @cindex continuous integration
- @uref{https://guix.gnu.org/cuirass/, Cuirass} is a continuous
- integration tool for Guix. It can be used both for development and for
- providing substitutes to others (@pxref{Substitutes}).
- The @code{(gnu services cuirass)} module provides the following service.
- @defvr {Scheme Procedure} cuirass-service-type
- The type of the Cuirass service. Its value must be a
- @code{cuirass-configuration} object, as described below.
- @end defvr
- To add build jobs, you have to set the @code{specifications} field of
- the configuration. For instance, the following example will build all
- the packages provided by the @code{my-channel} channel.
- @lisp
- (define %cuirass-specs
- #~(list (specification
- (name "my-channel")
- (build '(channels my-channel))
- (channels
- (cons (channel
- (name 'my-channel)
- (url "https://my-channel.git"))
- %default-channels)))))
- (service cuirass-service-type
- (cuirass-configuration
- (specifications %cuirass-specs)))
- @end lisp
- To build the @code{linux-libre} package defined by the default Guix
- channel, one can use the following configuration.
- @lisp
- (define %cuirass-specs
- #~(list (specification
- (name "my-linux")
- (build '(packages "linux-libre")))))
- (service cuirass-service-type
- (cuirass-configuration
- (specifications %cuirass-specs)))
- @end lisp
- The other configuration possibilities, as well as the specification
- record itself are described in the Cuirass manual
- (@pxref{Specifications,,, cuirass, Cuirass}).
- While information related to build jobs is located directly in the
- specifications, global settings for the @command{cuirass} process are
- accessible in other @code{cuirass-configuration} fields.
- @deftp {Data Type} cuirass-configuration
- Data type representing the configuration of Cuirass.
- @table @asis
- @item @code{cuirass} (default: @code{cuirass})
- The Cuirass package to use.
- @item @code{log-file} (default: @code{"/var/log/cuirass.log"})
- Location of the log file.
- @item @code{web-log-file} (default: @code{"/var/log/cuirass-web.log"})
- Location of the log file used by the web interface.
- @item @code{cache-directory} (default: @code{"/var/cache/cuirass"})
- Location of the repository cache.
- @item @code{user} (default: @code{"cuirass"})
- Owner of the @code{cuirass} process.
- @item @code{group} (default: @code{"cuirass"})
- Owner's group of the @code{cuirass} process.
- @item @code{interval} (default: @code{60})
- Number of seconds between the poll of the repositories followed by the
- Cuirass jobs.
- @item @code{parameters} (default: @code{#f})
- Read parameters from the given @var{parameters} file. The supported
- parameters are described here (@pxref{Parameters,,, cuirass, Cuirass}).
- @item @code{remote-server} (default: @code{#f})
- A @code{cuirass-remote-server-configuration} record to use the build
- remote mechanism or @code{#f} to use the default build mechanism.
- @item @code{database} (default: @code{"dbname=cuirass host=/var/run/postgresql"})
- Use @var{database} as the database containing the jobs and the past
- build results. Since Cuirass uses PostgreSQL as a database engine,
- @var{database} must be a string such as @code{"dbname=cuirass
- host=localhost"}.
- @item @code{port} (default: @code{8081})
- Port number used by the HTTP server.
- @item @code{host} (default: @code{"localhost"})
- Listen on the network interface for @var{host}. The default is to
- accept connections from localhost.
- @item @code{specifications} (default: @code{#~'()})
- A gexp (@pxref{G-Expressions}) that evaluates to a list of
- specifications records. The specification record is described in the
- Cuirass manual (@pxref{Specifications,,, cuirass, Cuirass}).
- @item @code{use-substitutes?} (default: @code{#f})
- This allows using substitutes to avoid building every dependencies of a job
- from source.
- @item @code{one-shot?} (default: @code{#f})
- Only evaluate specifications and build derivations once.
- @item @code{fallback?} (default: @code{#f})
- When substituting a pre-built binary fails, fall back to building
- packages locally.
- @item @code{extra-options} (default: @code{'()})
- Extra options to pass when running the Cuirass processes.
- @end table
- @end deftp
- @cindex remote build
- @subsubheading Cuirass remote building
- Cuirass supports two mechanisms to build derivations.
- @itemize
- @item Using the local Guix daemon.
- This is the default build mechanism. Once the build jobs are
- evaluated, they are sent to the local Guix daemon. Cuirass then
- listens to the Guix daemon output to detect the various build events.
- @item Using the remote build mechanism.
- The build jobs are not submitted to the local Guix daemon. Instead, a
- remote server dispatches build requests to the connect remote workers,
- according to the build priorities.
- @end itemize
- To enable this build mode a @code{cuirass-remote-server-configuration}
- record must be passed as @code{remote-server} argument of the
- @code{cuirass-configuration} record. The
- @code{cuirass-remote-server-configuration} record is described below.
- This build mode scales way better than the default build mode. This is
- the build mode that is used on the GNU Guix build farm at
- @url{https://ci.guix.gnu.org}. It should be preferred when using
- Cuirass to build large amount of packages.
- @deftp {Data Type} cuirass-remote-server-configuration
- Data type representing the configuration of the Cuirass remote-server.
- @table @asis
- @item @code{backend-port} (default: @code{5555})
- The TCP port for communicating with @code{remote-worker} processes
- using ZMQ. It defaults to @code{5555}.
- @item @code{log-port} (default: @code{5556})
- The TCP port of the log server. It defaults to @code{5556}.
- @item @code{publish-port} (default: @code{5557})
- The TCP port of the publish server. It defaults to @code{5557}.
- @item @code{log-file} (default: @code{"/var/log/cuirass-remote-server.log"})
- Location of the log file.
- @item @code{cache} (default: @code{"/var/cache/cuirass/remote"})
- Use @var{cache} directory to cache build log files.
- @item @code{trigger-url} (default: @code{#f})
- Once a substitute is successfully fetched, trigger substitute baking at
- @var{trigger-url}.
- @item @code{publish?} (default: @code{#t})
- If set to false, do not start a publish server and ignore the
- @code{publish-port} argument. This can be useful if there is already a
- standalone publish server standing next to the remote server.
- @item @code{public-key}
- @item @code{private-key}
- Use the specific @var{file}s as the public/private key pair used to sign
- the store items being published.
- @end table
- @end deftp
- At least one remote worker must also be started on any machine of the
- local network to actually perform the builds and report their status.
- @deftp {Data Type} cuirass-remote-worker-configuration
- Data type representing the configuration of the Cuirass remote-worker.
- @table @asis
- @item @code{cuirass} (default: @code{cuirass})
- The Cuirass package to use.
- @item @code{workers} (default: @code{1})
- Start @var{workers} parallel workers.
- @item @code{server} (default: @code{#f})
- Do not use Avahi discovery and connect to the given @code{server} IP
- address instead.
- @item @code{systems} (default: @code{(list (%current-system))})
- Only request builds for the given @var{systems}.
- @item @code{log-file} (default: @code{"/var/log/cuirass-remote-worker.log"})
- Location of the log file.
- @item @code{publish-port} (default: @code{5558})
- The TCP port of the publish server. It defaults to @code{5558}.
- @item @code{substitute-urls} (default: @code{%default-substitute-urls})
- The list of URLs where to look for substitutes by default.
- @item @code{public-key}
- @item @code{private-key}
- Use the specific @var{file}s as the public/private key pair used to sign
- the store items being published.
- @end table
- @end deftp
- @subsubheading Laminar
- @uref{https://laminar.ohwg.net/, Laminar} is a lightweight and modular
- Continuous Integration service. It doesn't have a configuration web UI
- instead uses version-controllable configuration files and scripts.
- Laminar encourages the use of existing tools such as bash and cron
- instead of reinventing them.
- @defvr {Scheme Procedure} laminar-service-type
- The type of the Laminar service. Its value must be a
- @code{laminar-configuration} object, as described below.
- All configuration values have defaults, a minimal configuration to get
- Laminar running is shown below. By default, the web interface is
- available on port 8080.
- @lisp
- (service laminar-service-type)
- @end lisp
- @end defvr
- @deftp {Data Type} laminar-configuration
- Data type representing the configuration of Laminar.
- @table @asis
- @item @code{laminar} (default: @code{laminar})
- The Laminar package to use.
- @item @code{home-directory} (default: @code{"/var/lib/laminar"})
- The directory for job configurations and run directories.
- @item @code{bind-http} (default: @code{"*:8080"})
- The interface/port or unix socket on which laminard should listen for
- incoming connections to the web frontend.
- @item @code{bind-rpc} (default: @code{"unix-abstract:laminar"})
- The interface/port or unix socket on which laminard should listen for
- incoming commands such as build triggers.
- @item @code{title} (default: @code{"Laminar"})
- The page title to show in the web frontend.
- @item @code{keep-rundirs} (default: @code{0})
- Set to an integer defining how many rundirs to keep per job. The
- lowest-numbered ones will be deleted. The default is 0, meaning all run
- dirs will be immediately deleted.
- @item @code{archive-url} (default: @code{#f})
- The web frontend served by laminard will use this URL to form links to
- artefacts archived jobs.
- @item @code{base-url} (default: @code{#f})
- Base URL to use for links to laminar itself.
- @end table
- @end deftp
- @node Power Management Services
- @subsection Power Management Services
- @cindex tlp
- @cindex power management with TLP
- @subsubheading TLP daemon
- The @code{(gnu services pm)} module provides a Guix service definition
- for the Linux power management tool TLP.
- TLP enables various powersaving modes in userspace and kernel.
- Contrary to @code{upower-service}, it is not a passive,
- monitoring tool, as it will apply custom settings each time a new power
- source is detected. More information can be found at
- @uref{https://linrunner.de/en/tlp/tlp.html, TLP home page}.
- @deffn {Scheme Variable} tlp-service-type
- The service type for the TLP tool. The default settings are optimised
- for battery life on most systems, but you can tweak them to your heart's
- content by adding a valid @code{tlp-configuration}:
- @lisp
- (service tlp-service-type
- (tlp-configuration
- (cpu-scaling-governor-on-ac (list "performance"))
- (sched-powersave-on-bat? #t)))
- @end lisp
- @end deffn
- Each parameter definition is preceded by its type; for example,
- @samp{boolean foo} indicates that the @code{foo} parameter
- should be specified as a boolean. Types starting with
- @code{maybe-} denote parameters that won't show up in TLP config file
- when their value is @code{'disabled}.
- @c The following documentation was initially generated by
- @c (generate-tlp-documentation) in (gnu services pm). Manually maintained
- @c documentation is better, so we shouldn't hesitate to edit below as
- @c needed. However if the change you want to make to this documentation
- @c can be done in an automated way, it's probably easier to change
- @c (generate-documentation) than to make it below and have to deal with
- @c the churn as TLP updates.
- Available @code{tlp-configuration} fields are:
- @deftypevr {@code{tlp-configuration} parameter} package tlp
- The TLP package.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} boolean tlp-enable?
- Set to true if you wish to enable TLP.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} string tlp-default-mode
- Default mode when no power supply can be detected. Alternatives are AC
- and BAT.
- Defaults to @samp{"AC"}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} non-negative-integer disk-idle-secs-on-ac
- Number of seconds Linux kernel has to wait after the disk goes idle,
- before syncing on AC.
- Defaults to @samp{0}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} non-negative-integer disk-idle-secs-on-bat
- Same as @code{disk-idle-ac} but on BAT mode.
- Defaults to @samp{2}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} non-negative-integer max-lost-work-secs-on-ac
- Dirty pages flushing periodicity, expressed in seconds.
- Defaults to @samp{15}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} non-negative-integer max-lost-work-secs-on-bat
- Same as @code{max-lost-work-secs-on-ac} but on BAT mode.
- Defaults to @samp{60}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list cpu-scaling-governor-on-ac
- CPU frequency scaling governor on AC mode. With intel_pstate driver,
- alternatives are powersave and performance. With acpi-cpufreq driver,
- alternatives are ondemand, powersave, performance and conservative.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list cpu-scaling-governor-on-bat
- Same as @code{cpu-scaling-governor-on-ac} but on BAT mode.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-scaling-min-freq-on-ac
- Set the min available frequency for the scaling governor on AC.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-scaling-max-freq-on-ac
- Set the max available frequency for the scaling governor on AC.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-scaling-min-freq-on-bat
- Set the min available frequency for the scaling governor on BAT.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-scaling-max-freq-on-bat
- Set the max available frequency for the scaling governor on BAT.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-min-perf-on-ac
- Limit the min P-state to control the power dissipation of the CPU, in AC
- mode. Values are stated as a percentage of the available performance.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-max-perf-on-ac
- Limit the max P-state to control the power dissipation of the CPU, in AC
- mode. Values are stated as a percentage of the available performance.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-min-perf-on-bat
- Same as @code{cpu-min-perf-on-ac} on BAT mode.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-max-perf-on-bat
- Same as @code{cpu-max-perf-on-ac} on BAT mode.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-boolean cpu-boost-on-ac?
- Enable CPU turbo boost feature on AC mode.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-boolean cpu-boost-on-bat?
- Same as @code{cpu-boost-on-ac?} on BAT mode.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} boolean sched-powersave-on-ac?
- Allow Linux kernel to minimize the number of CPU cores/hyper-threads
- used under light load conditions.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} boolean sched-powersave-on-bat?
- Same as @code{sched-powersave-on-ac?} but on BAT mode.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} boolean nmi-watchdog?
- Enable Linux kernel NMI watchdog.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-string phc-controls
- For Linux kernels with PHC patch applied, change CPU voltages. An
- example value would be @samp{"F:V F:V F:V F:V"}.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} string energy-perf-policy-on-ac
- Set CPU performance versus energy saving policy on AC@. Alternatives are
- performance, normal, powersave.
- Defaults to @samp{"performance"}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} string energy-perf-policy-on-bat
- Same as @code{energy-perf-policy-ac} but on BAT mode.
- Defaults to @samp{"powersave"}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} space-separated-string-list disks-devices
- Hard disk devices.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} space-separated-string-list disk-apm-level-on-ac
- Hard disk advanced power management level.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} space-separated-string-list disk-apm-level-on-bat
- Same as @code{disk-apm-bat} but on BAT mode.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list disk-spindown-timeout-on-ac
- Hard disk spin down timeout. One value has to be specified for each
- declared hard disk.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list disk-spindown-timeout-on-bat
- Same as @code{disk-spindown-timeout-on-ac} but on BAT mode.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list disk-iosched
- Select IO scheduler for disk devices. One value has to be specified for
- each declared hard disk. Example alternatives are cfq, deadline and
- noop.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} string sata-linkpwr-on-ac
- SATA aggressive link power management (ALPM) level. Alternatives are
- min_power, medium_power, max_performance.
- Defaults to @samp{"max_performance"}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} string sata-linkpwr-on-bat
- Same as @code{sata-linkpwr-ac} but on BAT mode.
- Defaults to @samp{"min_power"}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-string sata-linkpwr-blacklist
- Exclude specified SATA host devices for link power management.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-on-off-boolean ahci-runtime-pm-on-ac?
- Enable Runtime Power Management for AHCI controller and disks on AC
- mode.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-on-off-boolean ahci-runtime-pm-on-bat?
- Same as @code{ahci-runtime-pm-on-ac} on BAT mode.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} non-negative-integer ahci-runtime-pm-timeout
- Seconds of inactivity before disk is suspended.
- Defaults to @samp{15}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} string pcie-aspm-on-ac
- PCI Express Active State Power Management level. Alternatives are
- default, performance, powersave.
- Defaults to @samp{"performance"}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} string pcie-aspm-on-bat
- Same as @code{pcie-aspm-ac} but on BAT mode.
- Defaults to @samp{"powersave"}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer start-charge-thresh-bat0
- Percentage when battery 0 should begin charging. Only supported on some laptops.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer stop-charge-thresh-bat0
- Percentage when battery 0 should stop charging. Only supported on some laptops.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer start-charge-thresh-bat1
- Percentage when battery 1 should begin charging. Only supported on some laptops.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer stop-charge-thresh-bat1
- Percentage when battery 1 should stop charging. Only supported on some laptops.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} string radeon-power-profile-on-ac
- Radeon graphics clock speed level. Alternatives are low, mid, high,
- auto, default.
- Defaults to @samp{"high"}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} string radeon-power-profile-on-bat
- Same as @code{radeon-power-ac} but on BAT mode.
- Defaults to @samp{"low"}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} string radeon-dpm-state-on-ac
- Radeon dynamic power management method (DPM). Alternatives are battery,
- performance.
- Defaults to @samp{"performance"}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} string radeon-dpm-state-on-bat
- Same as @code{radeon-dpm-state-ac} but on BAT mode.
- Defaults to @samp{"battery"}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} string radeon-dpm-perf-level-on-ac
- Radeon DPM performance level. Alternatives are auto, low, high.
- Defaults to @samp{"auto"}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} string radeon-dpm-perf-level-on-bat
- Same as @code{radeon-dpm-perf-ac} but on BAT mode.
- Defaults to @samp{"auto"}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} on-off-boolean wifi-pwr-on-ac?
- Wifi power saving mode.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} on-off-boolean wifi-pwr-on-bat?
- Same as @code{wifi-power-ac?} but on BAT mode.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} y-n-boolean wol-disable?
- Disable wake on LAN.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} non-negative-integer sound-power-save-on-ac
- Timeout duration in seconds before activating audio power saving on
- Intel HDA and AC97 devices. A value of 0 disables power saving.
- Defaults to @samp{0}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} non-negative-integer sound-power-save-on-bat
- Same as @code{sound-powersave-ac} but on BAT mode.
- Defaults to @samp{1}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} y-n-boolean sound-power-save-controller?
- Disable controller in powersaving mode on Intel HDA devices.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} boolean bay-poweroff-on-bat?
- Enable optical drive in UltraBay/MediaBay on BAT mode. Drive can be
- powered on again by releasing (and reinserting) the eject lever or by
- pressing the disc eject button on newer models.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} string bay-device
- Name of the optical drive device to power off.
- Defaults to @samp{"sr0"}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} string runtime-pm-on-ac
- Runtime Power Management for PCI(e) bus devices. Alternatives are on
- and auto.
- Defaults to @samp{"on"}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} string runtime-pm-on-bat
- Same as @code{runtime-pm-ac} but on BAT mode.
- Defaults to @samp{"auto"}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} boolean runtime-pm-all?
- Runtime Power Management for all PCI(e) bus devices, except blacklisted
- ones.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list runtime-pm-blacklist
- Exclude specified PCI(e) device addresses from Runtime Power Management.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} space-separated-string-list runtime-pm-driver-blacklist
- Exclude PCI(e) devices assigned to the specified drivers from Runtime
- Power Management.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} boolean usb-autosuspend?
- Enable USB autosuspend feature.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-string usb-blacklist
- Exclude specified devices from USB autosuspend.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} boolean usb-blacklist-wwan?
- Exclude WWAN devices from USB autosuspend.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-string usb-whitelist
- Include specified devices into USB autosuspend, even if they are already
- excluded by the driver or via @code{usb-blacklist-wwan?}.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-boolean usb-autosuspend-disable-on-shutdown?
- Enable USB autosuspend before shutdown.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} boolean restore-device-state-on-startup?
- Restore radio device state (bluetooth, wifi, wwan) from previous
- shutdown on system startup.
- Defaults to @samp{#f}.
- @end deftypevr
- @cindex thermald
- @cindex CPU frequency scaling with thermald
- @subsubheading Thermald daemon
- The @code{(gnu services pm)} module provides an interface to
- thermald, a CPU frequency scaling service which helps prevent overheating.
- @defvr {Scheme Variable} thermald-service-type
- This is the service type for
- @uref{https://01.org/linux-thermal-daemon/, thermald}, the Linux
- Thermal Daemon, which is responsible for controlling the thermal state
- of processors and preventing overheating.
- @end defvr
- @deftp {Data Type} thermald-configuration
- Data type representing the configuration of @code{thermald-service-type}.
- @table @asis
- @item @code{adaptive?} (default: @code{#f})
- Use @acronym{DPTF, Dynamic Power and Thermal Framework} adaptive tables
- when present.
- @item @code{ignore-cpuid-check?} (default: @code{#f})
- Ignore cpuid check for supported CPU models.
- @item @code{thermald} (default: @var{thermald})
- Package object of thermald.
- @end table
- @end deftp
- @node Audio Services
- @subsection Audio Services
- The @code{(gnu services audio)} module provides a service to start MPD
- (the Music Player Daemon).
- @cindex mpd
- @subsubheading Music Player Daemon
- The Music Player Daemon (MPD) is a service that can play music while
- being controlled from the local machine or over the network by a variety
- of clients.
- The following example shows how one might run @code{mpd} as user
- @code{"bob"} on port @code{6666}. It uses pulseaudio for output.
- @lisp
- (service mpd-service-type
- (mpd-configuration
- (user "bob")
- (port "6666")))
- @end lisp
- @defvr {Scheme Variable} mpd-service-type
- The service type for @command{mpd}
- @end defvr
- @deftp {Data Type} mpd-configuration
- Data type representing the configuration of @command{mpd}.
- @table @asis
- @item @code{user} (default: @code{"mpd"})
- The user to run mpd as.
- @item @code{music-dir} (default: @code{"~/Music"})
- The directory to scan for music files.
- @item @code{playlist-dir} (default: @code{"~/.mpd/playlists"})
- The directory to store playlists.
- @item @code{db-file} (default: @code{"~/.mpd/tag_cache"})
- The location of the music database.
- @item @code{state-file} (default: @code{"~/.mpd/state"})
- The location of the file that stores current MPD's state.
- @item @code{sticker-file} (default: @code{"~/.mpd/sticker.sql"})
- The location of the sticker database.
- @item @code{port} (default: @code{"6600"})
- The port to run mpd on.
- @item @code{address} (default: @code{"any"})
- The address that mpd will bind to. To use a Unix domain socket,
- an absolute path can be specified here.
- @item @code{outputs} (default: @code{"(list (mpd-output))"})
- The audio outputs that MPD can use. By default this is a single output using pulseaudio.
- @end table
- @end deftp
- @deftp {Data Type} mpd-output
- Data type representing an @command{mpd} audio output.
- @table @asis
- @item @code{name} (default: @code{"MPD"})
- The name of the audio output.
- @item @code{type} (default: @code{"pulse"})
- The type of audio output.
- @item @code{enabled?} (default: @code{#t})
- Specifies whether this audio output is enabled when MPD is started. By
- default, all audio outputs are enabled. This is just the default
- setting when there is no state file; with a state file, the previous
- state is restored.
- @item @code{tags?} (default: @code{#t})
- If set to @code{#f}, then MPD will not send tags to this output. This
- is only useful for output plugins that can receive tags, for example the
- @code{httpd} output plugin.
- @item @code{always-on?} (default: @code{#f})
- If set to @code{#t}, then MPD attempts to keep this audio output always
- open. This may be useful for streaming servers, when you don’t want to
- disconnect all listeners even when playback is accidentally stopped.
- @item @code{mixer-type}
- This field accepts a symbol that specifies which mixer should be used
- for this audio output: the @code{hardware} mixer, the @code{software}
- mixer, the @code{null} mixer (allows setting the volume, but with no
- effect; this can be used as a trick to implement an external mixer
- External Mixer) or no mixer (@code{none}).
- @item @code{extra-options} (default: @code{'()})
- An association list of option symbols to string values to be appended to
- the audio output configuration.
- @end table
- @end deftp
- The following example shows a configuration of @code{mpd} that provides
- an HTTP audio streaming output.
- @lisp
- (service mpd-service-type
- (mpd-configuration
- (outputs
- (list (mpd-output
- (name "streaming")
- (type "httpd")
- (mixer-type 'null)
- (extra-options
- `((encoder . "vorbis")
- (port . "8080"))))))))
- @end lisp
- @node Virtualization Services
- @subsection Virtualization Services
- The @code{(gnu services virtualization)} module provides services for
- the libvirt and virtlog daemons, as well as other virtualization-related
- services.
- @subsubheading Libvirt daemon
- @code{libvirtd} is the server side daemon component of the libvirt
- virtualization management system. This daemon runs on host servers
- and performs required management tasks for virtualized guests.
- @deffn {Scheme Variable} libvirt-service-type
- This is the type of the @uref{https://libvirt.org, libvirt daemon}.
- Its value must be a @code{libvirt-configuration}.
- @lisp
- (service libvirt-service-type
- (libvirt-configuration
- (unix-sock-group "libvirt")
- (tls-port "16555")))
- @end lisp
- @end deffn
- @c Auto-generated with (generate-libvirt-documentation)
- Available @code{libvirt-configuration} fields are:
- @deftypevr {@code{libvirt-configuration} parameter} package libvirt
- Libvirt package.
- @end deftypevr
- @deftypevr {@code{libvirt-configuration} parameter} boolean listen-tls?
- Flag listening for secure TLS connections on the public TCP/IP port.
- You must set @code{listen} for this to have any effect.
- It is necessary to setup a CA and issue server certificates before using
- this capability.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{libvirt-configuration} parameter} boolean listen-tcp?
- Listen for unencrypted TCP connections on the public TCP/IP port. You must
- set @code{listen} for this to have any effect.
- Using the TCP socket requires SASL authentication by default. Only SASL
- mechanisms which support data encryption are allowed. This is
- DIGEST_MD5 and GSSAPI (Kerberos5).
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{libvirt-configuration} parameter} string tls-port
- Port for accepting secure TLS connections. This can be a port number,
- or service name.
- Defaults to @samp{"16514"}.
- @end deftypevr
- @deftypevr {@code{libvirt-configuration} parameter} string tcp-port
- Port for accepting insecure TCP connections. This can be a port number,
- or service name.
- Defaults to @samp{"16509"}.
- @end deftypevr
- @deftypevr {@code{libvirt-configuration} parameter} string listen-addr
- IP address or hostname used for client connections.
- Defaults to @samp{"0.0.0.0"}.
- @end deftypevr
- @deftypevr {@code{libvirt-configuration} parameter} boolean mdns-adv?
- Flag toggling mDNS advertisement of the libvirt service.
- Alternatively can disable for all services on a host by stopping the
- Avahi daemon.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{libvirt-configuration} parameter} string mdns-name
- Default mDNS advertisement name. This must be unique on the immediate
- broadcast network.
- Defaults to @samp{"Virtualization Host <hostname>"}.
- @end deftypevr
- @deftypevr {@code{libvirt-configuration} parameter} string unix-sock-group
- UNIX domain socket group ownership. This can be used to allow a
- 'trusted' set of users access to management capabilities without
- becoming root.
- Defaults to @samp{"root"}.
- @end deftypevr
- @deftypevr {@code{libvirt-configuration} parameter} string unix-sock-ro-perms
- UNIX socket permissions for the R/O socket. This is used for monitoring
- VM status only.
- Defaults to @samp{"0777"}.
- @end deftypevr
- @deftypevr {@code{libvirt-configuration} parameter} string unix-sock-rw-perms
- UNIX socket permissions for the R/W socket. Default allows only root.
- If PolicyKit is enabled on the socket, the default will change to allow
- everyone (eg, 0777)
- Defaults to @samp{"0770"}.
- @end deftypevr
- @deftypevr {@code{libvirt-configuration} parameter} string unix-sock-admin-perms
- UNIX socket permissions for the admin socket. Default allows only owner
- (root), do not change it unless you are sure to whom you are exposing
- the access to.
- Defaults to @samp{"0777"}.
- @end deftypevr
- @deftypevr {@code{libvirt-configuration} parameter} string unix-sock-dir
- The directory in which sockets will be found/created.
- Defaults to @samp{"/var/run/libvirt"}.
- @end deftypevr
- @deftypevr {@code{libvirt-configuration} parameter} string auth-unix-ro
- Authentication scheme for UNIX read-only sockets. By default socket
- permissions allow anyone to connect
- Defaults to @samp{"polkit"}.
- @end deftypevr
- @deftypevr {@code{libvirt-configuration} parameter} string auth-unix-rw
- Authentication scheme for UNIX read-write sockets. By default socket
- permissions only allow root. If PolicyKit support was compiled into
- libvirt, the default will be to use 'polkit' auth.
- Defaults to @samp{"polkit"}.
- @end deftypevr
- @deftypevr {@code{libvirt-configuration} parameter} string auth-tcp
- Authentication scheme for TCP sockets. If you don't enable SASL, then
- all TCP traffic is cleartext. Don't do this outside of a dev/test
- scenario.
- Defaults to @samp{"sasl"}.
- @end deftypevr
- @deftypevr {@code{libvirt-configuration} parameter} string auth-tls
- Authentication scheme for TLS sockets. TLS sockets already have
- encryption provided by the TLS layer, and limited authentication is done
- by certificates.
- It is possible to make use of any SASL authentication mechanism as well,
- by using 'sasl' for this option
- Defaults to @samp{"none"}.
- @end deftypevr
- @deftypevr {@code{libvirt-configuration} parameter} optional-list access-drivers
- API access control scheme.
- By default an authenticated user is allowed access to all APIs. Access
- drivers can place restrictions on this.
- Defaults to @samp{()}.
- @end deftypevr
- @deftypevr {@code{libvirt-configuration} parameter} string key-file
- Server key file path. If set to an empty string, then no private key is
- loaded.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{libvirt-configuration} parameter} string cert-file
- Server key file path. If set to an empty string, then no certificate is
- loaded.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{libvirt-configuration} parameter} string ca-file
- Server key file path. If set to an empty string, then no CA certificate
- is loaded.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{libvirt-configuration} parameter} string crl-file
- Certificate revocation list path. If set to an empty string, then no
- CRL is loaded.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{libvirt-configuration} parameter} boolean tls-no-sanity-cert
- Disable verification of our own server certificates.
- When libvirtd starts it performs some sanity checks against its own
- certificates.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{libvirt-configuration} parameter} boolean tls-no-verify-cert
- Disable verification of client certificates.
- Client certificate verification is the primary authentication mechanism.
- Any client which does not present a certificate signed by the CA will be
- rejected.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{libvirt-configuration} parameter} optional-list tls-allowed-dn-list
- Whitelist of allowed x509 Distinguished Name.
- Defaults to @samp{()}.
- @end deftypevr
- @deftypevr {@code{libvirt-configuration} parameter} optional-list sasl-allowed-usernames
- Whitelist of allowed SASL usernames. The format for username depends on
- the SASL authentication mechanism.
- Defaults to @samp{()}.
- @end deftypevr
- @deftypevr {@code{libvirt-configuration} parameter} string tls-priority
- Override the compile time default TLS priority string. The default is
- usually @samp{"NORMAL"} unless overridden at build time. Only set this is it
- is desired for libvirt to deviate from the global default settings.
- Defaults to @samp{"NORMAL"}.
- @end deftypevr
- @deftypevr {@code{libvirt-configuration} parameter} integer max-clients
- Maximum number of concurrent client connections to allow over all
- sockets combined.
- Defaults to @samp{5000}.
- @end deftypevr
- @deftypevr {@code{libvirt-configuration} parameter} integer max-queued-clients
- Maximum length of queue of connections waiting to be accepted by the
- daemon. Note, that some protocols supporting retransmission may obey
- this so that a later reattempt at connection succeeds.
- Defaults to @samp{1000}.
- @end deftypevr
- @deftypevr {@code{libvirt-configuration} parameter} integer max-anonymous-clients
- Maximum length of queue of accepted but not yet authenticated clients.
- Set this to zero to turn this feature off
- Defaults to @samp{20}.
- @end deftypevr
- @deftypevr {@code{libvirt-configuration} parameter} integer min-workers
- Number of workers to start up initially.
- Defaults to @samp{5}.
- @end deftypevr
- @deftypevr {@code{libvirt-configuration} parameter} integer max-workers
- Maximum number of worker threads.
- If the number of active clients exceeds @code{min-workers}, then more
- threads are spawned, up to max_workers limit. Typically you'd want
- max_workers to equal maximum number of clients allowed.
- Defaults to @samp{20}.
- @end deftypevr
- @deftypevr {@code{libvirt-configuration} parameter} integer prio-workers
- Number of priority workers. If all workers from above pool are stuck,
- some calls marked as high priority (notably domainDestroy) can be
- executed in this pool.
- Defaults to @samp{5}.
- @end deftypevr
- @deftypevr {@code{libvirt-configuration} parameter} integer max-requests
- Total global limit on concurrent RPC calls.
- Defaults to @samp{20}.
- @end deftypevr
- @deftypevr {@code{libvirt-configuration} parameter} integer max-client-requests
- Limit on concurrent requests from a single client connection. To avoid
- one client monopolizing the server this should be a small fraction of
- the global max_requests and max_workers parameter.
- Defaults to @samp{5}.
- @end deftypevr
- @deftypevr {@code{libvirt-configuration} parameter} integer admin-min-workers
- Same as @code{min-workers} but for the admin interface.
- Defaults to @samp{1}.
- @end deftypevr
- @deftypevr {@code{libvirt-configuration} parameter} integer admin-max-workers
- Same as @code{max-workers} but for the admin interface.
- Defaults to @samp{5}.
- @end deftypevr
- @deftypevr {@code{libvirt-configuration} parameter} integer admin-max-clients
- Same as @code{max-clients} but for the admin interface.
- Defaults to @samp{5}.
- @end deftypevr
- @deftypevr {@code{libvirt-configuration} parameter} integer admin-max-queued-clients
- Same as @code{max-queued-clients} but for the admin interface.
- Defaults to @samp{5}.
- @end deftypevr
- @deftypevr {@code{libvirt-configuration} parameter} integer admin-max-client-requests
- Same as @code{max-client-requests} but for the admin interface.
- Defaults to @samp{5}.
- @end deftypevr
- @deftypevr {@code{libvirt-configuration} parameter} integer log-level
- Logging level. 4 errors, 3 warnings, 2 information, 1 debug.
- Defaults to @samp{3}.
- @end deftypevr
- @deftypevr {@code{libvirt-configuration} parameter} string log-filters
- Logging filters.
- A filter allows to select a different logging level for a given category
- of logs. The format for a filter is one of:
- @itemize @bullet
- @item
- x:name
- @item
- x:+name
- @end itemize
- where @code{name} is a string which is matched against the category
- given in the @code{VIR_LOG_INIT()} at the top of each libvirt source
- file, e.g., @samp{"remote"}, @samp{"qemu"}, or @samp{"util.json"} (the
- name in the filter can be a substring of the full category name, in
- order to match multiple similar categories), the optional @samp{"+"}
- prefix tells libvirt to log stack trace for each message matching name,
- and @code{x} is the minimal level where matching messages should be
- logged:
- @itemize @bullet
- @item
- 1: DEBUG
- @item
- 2: INFO
- @item
- 3: WARNING
- @item
- 4: ERROR
- @end itemize
- Multiple filters can be defined in a single filters statement, they just
- need to be separated by spaces.
- Defaults to @samp{"3:remote 4:event"}.
- @end deftypevr
- @deftypevr {@code{libvirt-configuration} parameter} string log-outputs
- Logging outputs.
- An output is one of the places to save logging information. The format
- for an output can be:
- @table @code
- @item x:stderr
- output goes to stderr
- @item x:syslog:name
- use syslog for the output and use the given name as the ident
- @item x:file:file_path
- output to a file, with the given filepath
- @item x:journald
- output to journald logging system
- @end table
- In all case the x prefix is the minimal level, acting as a filter
- @itemize @bullet
- @item
- 1: DEBUG
- @item
- 2: INFO
- @item
- 3: WARNING
- @item
- 4: ERROR
- @end itemize
- Multiple outputs can be defined, they just need to be separated by
- spaces.
- Defaults to @samp{"3:stderr"}.
- @end deftypevr
- @deftypevr {@code{libvirt-configuration} parameter} integer audit-level
- Allows usage of the auditing subsystem to be altered
- @itemize @bullet
- @item
- 0: disable all auditing
- @item
- 1: enable auditing, only if enabled on host
- @item
- 2: enable auditing, and exit if disabled on host.
- @end itemize
- Defaults to @samp{1}.
- @end deftypevr
- @deftypevr {@code{libvirt-configuration} parameter} boolean audit-logging
- Send audit messages via libvirt logging infrastructure.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{libvirt-configuration} parameter} optional-string host-uuid
- Host UUID@. UUID must not have all digits be the same.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{libvirt-configuration} parameter} string host-uuid-source
- Source to read host UUID.
- @itemize @bullet
- @item
- @code{smbios}: fetch the UUID from @code{dmidecode -s system-uuid}
- @item
- @code{machine-id}: fetch the UUID from @code{/etc/machine-id}
- @end itemize
- If @code{dmidecode} does not provide a valid UUID a temporary UUID will
- be generated.
- Defaults to @samp{"smbios"}.
- @end deftypevr
- @deftypevr {@code{libvirt-configuration} parameter} integer keepalive-interval
- A keepalive message is sent to a client after @code{keepalive_interval}
- seconds of inactivity to check if the client is still responding. If
- set to -1, libvirtd will never send keepalive requests; however clients
- can still send them and the daemon will send responses.
- Defaults to @samp{5}.
- @end deftypevr
- @deftypevr {@code{libvirt-configuration} parameter} integer keepalive-count
- Maximum number of keepalive messages that are allowed to be sent to the
- client without getting any response before the connection is considered
- broken.
- In other words, the connection is automatically closed approximately
- after @code{keepalive_interval * (keepalive_count + 1)} seconds since
- the last message received from the client. When @code{keepalive-count}
- is set to 0, connections will be automatically closed after
- @code{keepalive-interval} seconds of inactivity without sending any
- keepalive messages.
- Defaults to @samp{5}.
- @end deftypevr
- @deftypevr {@code{libvirt-configuration} parameter} integer admin-keepalive-interval
- Same as above but for admin interface.
- Defaults to @samp{5}.
- @end deftypevr
- @deftypevr {@code{libvirt-configuration} parameter} integer admin-keepalive-count
- Same as above but for admin interface.
- Defaults to @samp{5}.
- @end deftypevr
- @deftypevr {@code{libvirt-configuration} parameter} integer ovs-timeout
- Timeout for Open vSwitch calls.
- The @code{ovs-vsctl} utility is used for the configuration and its
- timeout option is set by default to 5 seconds to avoid potential
- infinite waits blocking libvirt.
- Defaults to @samp{5}.
- @end deftypevr
- @c %end of autogenerated docs
- @subsubheading Virtlog daemon
- The virtlogd service is a server side daemon component of libvirt that is
- used to manage logs from virtual machine consoles.
- This daemon is not used directly by libvirt client applications, rather it
- is called on their behalf by @code{libvirtd}. By maintaining the logs in a
- standalone daemon, the main @code{libvirtd} daemon can be restarted without
- risk of losing logs. The @code{virtlogd} daemon has the ability to re-exec()
- itself upon receiving @code{SIGUSR1}, to allow live upgrades without downtime.
- @deffn {Scheme Variable} virtlog-service-type
- This is the type of the virtlog daemon.
- Its value must be a @code{virtlog-configuration}.
- @lisp
- (service virtlog-service-type
- (virtlog-configuration
- (max-clients 1000)))
- @end lisp
- @end deffn
- @deftypevar {@code{libvirt} parameter} package libvirt
- Libvirt package.
- @end deftypevar
- @deftypevr {@code{virtlog-configuration} parameter} integer log-level
- Logging level. 4 errors, 3 warnings, 2 information, 1 debug.
- Defaults to @samp{3}.
- @end deftypevr
- @deftypevr {@code{virtlog-configuration} parameter} string log-filters
- Logging filters.
- A filter allows to select a different logging level for a given category
- of logs The format for a filter is one of:
- @itemize @bullet
- @item
- x:name
- @item
- x:+name
- @end itemize
- where @code{name} is a string which is matched against the category
- given in the @code{VIR_LOG_INIT()} at the top of each libvirt source
- file, e.g., "remote", "qemu", or "util.json" (the name in the filter can
- be a substring of the full category name, in order to match multiple
- similar categories), the optional "+" prefix tells libvirt to log stack
- trace for each message matching name, and @code{x} is the minimal level
- where matching messages should be logged:
- @itemize @bullet
- @item
- 1: DEBUG
- @item
- 2: INFO
- @item
- 3: WARNING
- @item
- 4: ERROR
- @end itemize
- Multiple filters can be defined in a single filters statement, they just
- need to be separated by spaces.
- Defaults to @samp{"3:remote 4:event"}.
- @end deftypevr
- @deftypevr {@code{virtlog-configuration} parameter} string log-outputs
- Logging outputs.
- An output is one of the places to save logging information The format
- for an output can be:
- @table @code
- @item x:stderr
- output goes to stderr
- @item x:syslog:name
- use syslog for the output and use the given name as the ident
- @item x:file:file_path
- output to a file, with the given filepath
- @item x:journald
- output to journald logging system
- @end table
- In all case the x prefix is the minimal level, acting as a filter
- @itemize @bullet
- @item
- 1: DEBUG
- @item
- 2: INFO
- @item
- 3: WARNING
- @item
- 4: ERROR
- @end itemize
- Multiple outputs can be defined, they just need to be separated by
- spaces.
- Defaults to @samp{"3:stderr"}.
- @end deftypevr
- @deftypevr {@code{virtlog-configuration} parameter} integer max-clients
- Maximum number of concurrent client connections to allow over all
- sockets combined.
- Defaults to @samp{1024}.
- @end deftypevr
- @deftypevr {@code{virtlog-configuration} parameter} integer max-size
- Maximum file size before rolling over.
- Defaults to @samp{2MB}
- @end deftypevr
- @deftypevr {@code{virtlog-configuration} parameter} integer max-backups
- Maximum number of backup files to keep.
- Defaults to @samp{3}
- @end deftypevr
- @anchor{transparent-emulation-qemu}
- @subsubheading Transparent Emulation with QEMU
- @cindex emulation
- @cindex @code{binfmt_misc}
- @code{qemu-binfmt-service-type} provides support for transparent
- emulation of program binaries built for different architectures---e.g.,
- it allows you to transparently execute an ARMv7 program on an x86_64
- machine. It achieves this by combining the @uref{https://www.qemu.org,
- QEMU} emulator and the @code{binfmt_misc} feature of the kernel Linux.
- This feature only allows you to emulate GNU/Linux on a different
- architecture, but see below for GNU/Hurd support.
- @defvr {Scheme Variable} qemu-binfmt-service-type
- This is the type of the QEMU/binfmt service for transparent emulation.
- Its value must be a @code{qemu-binfmt-configuration} object, which
- specifies the QEMU package to use as well as the architecture we want to
- emulated:
- @lisp
- (service qemu-binfmt-service-type
- (qemu-binfmt-configuration
- (platforms (lookup-qemu-platforms "arm" "aarch64"))))
- @end lisp
- In this example, we enable transparent emulation for the ARM and aarch64
- platforms. Running @code{herd stop qemu-binfmt} turns it off, and
- running @code{herd start qemu-binfmt} turns it back on (@pxref{Invoking
- herd, the @command{herd} command,, shepherd, The GNU Shepherd Manual}).
- @end defvr
- @deftp {Data Type} qemu-binfmt-configuration
- This is the configuration for the @code{qemu-binfmt} service.
- @table @asis
- @item @code{platforms} (default: @code{'()})
- The list of emulated QEMU platforms. Each item must be a @dfn{platform
- object} as returned by @code{lookup-qemu-platforms} (see below).
- For example, let's suppose you're on an x86_64 machine and you have this
- service:
- @lisp
- (service qemu-binfmt-service-type
- (qemu-binfmt-configuration
- (platforms (lookup-qemu-platforms "arm"))))
- @end lisp
- You can run:
- @example
- guix build -s armhf-linux inkscape
- @end example
- @noindent
- and it will build Inkscape for ARMv7 @emph{as if it were a native
- build}, transparently using QEMU to emulate the ARMv7 CPU@. Pretty handy
- if you'd like to test a package build for an architecture you don't have
- access to!
- @item @code{qemu} (default: @code{qemu})
- The QEMU package to use.
- @end table
- @end deftp
- @deffn {Scheme Procedure} lookup-qemu-platforms @var{platforms}@dots{}
- Return the list of QEMU platform objects corresponding to
- @var{platforms}@dots{}. @var{platforms} must be a list of strings
- corresponding to platform names, such as @code{"arm"}, @code{"sparc"},
- @code{"mips64el"}, and so on.
- @end deffn
- @deffn {Scheme Procedure} qemu-platform? @var{obj}
- Return true if @var{obj} is a platform object.
- @end deffn
- @deffn {Scheme Procedure} qemu-platform-name @var{platform}
- Return the name of @var{platform}---a string such as @code{"arm"}.
- @end deffn
- @subsubheading QEMU Guest Agent
- @cindex emulation
- The QEMU guest agent provides control over the emulated system to the
- host. The @code{qemu-guest-agent} service runs the agent on Guix
- guests. To control the agent from the host, open a socket by invoking
- QEMU with the following arguments:
- @example
- qemu-system-x86_64 \
- -chardev socket,path=/tmp/qga.sock,server=on,wait=off,id=qga0 \
- -device virtio-serial \
- -device virtserialport,chardev=qga0,name=org.qemu.guest_agent.0 \
- ...
- @end example
- This creates a socket at @file{/tmp/qga.sock} on the host. Once the
- guest agent is running, you can issue commands with @code{socat}:
- @example
- $ guix shell socat -- socat unix-connect:/tmp/qga.sock stdio
- @{"execute": "guest-get-host-name"@}
- @{"return": @{"host-name": "guix"@}@}
- @end example
- See @url{https://wiki.qemu.org/Features/GuestAgent,QEMU guest agent
- documentation} for more options and commands.
- @defvr {Scheme Variable} qemu-guest-agent-service-type
- Service type for the QEMU guest agent service.
- @end defvr
- @deftp {Data Type} qemu-guest-agent-configuration
- Configuration for the @code{qemu-guest-agent} service.
- @table @asis
- @item @code{qemu} (default: @code{qemu-minimal})
- The QEMU package to use.
- @item @code{device} (default: @code{""})
- File name of the device or socket the agent uses to communicate with the
- host. If empty, QEMU uses a default file name.
- @end table
- @end deftp
- @subsubheading The Hurd in a Virtual Machine
- @cindex @code{hurd}
- @cindex the Hurd
- @cindex childhurd
- Service @code{hurd-vm} provides support for running GNU/Hurd in a
- virtual machine (VM), a so-called @dfn{childhurd}. This service is meant
- to be used on GNU/Linux and the given GNU/Hurd operating system
- configuration is cross-compiled. The virtual machine is a Shepherd
- service that can be referred to by the names @code{hurd-vm} and
- @code{childhurd} and be controlled with commands such as:
- @example
- herd start hurd-vm
- herd stop childhurd
- @end example
- When the service is running, you can view its console by connecting to
- it with a VNC client, for example with:
- @example
- guix shell tigervnc-client -- vncviewer localhost:5900
- @end example
- The default configuration (see @code{hurd-vm-configuration} below)
- spawns a secure shell (SSH) server in your GNU/Hurd system, which QEMU
- (the virtual machine emulator) redirects to port 10222 on the host.
- Thus, you can connect over SSH to the childhurd with:
- @example
- ssh root@@localhost -p 10022
- @end example
- The childhurd is volatile and stateless: it starts with a fresh root
- file system every time you restart it. By default though, all the files
- under @file{/etc/childhurd} on the host are copied as is to the root
- file system of the childhurd when it boots. This allows you to
- initialize ``secrets'' inside the VM: SSH host keys, authorized
- substitute keys, and so on---see the explanation of @code{secret-root}
- below.
- @defvr {Scheme Variable} hurd-vm-service-type
- This is the type of the Hurd in a Virtual Machine service. Its value
- must be a @code{hurd-vm-configuration} object, which specifies the
- operating system (@pxref{operating-system Reference}) and the disk size
- for the Hurd Virtual Machine, the QEMU package to use as well as the
- options for running it.
- For example:
- @lisp
- (service hurd-vm-service-type
- (hurd-vm-configuration
- (disk-size (* 5000 (expt 2 20))) ;5G
- (memory-size 1024))) ;1024MiB
- @end lisp
- would create a disk image big enough to build GNU@tie{}Hello, with some
- extra memory.
- @end defvr
- @deftp {Data Type} hurd-vm-configuration
- The data type representing the configuration for
- @code{hurd-vm-service-type}.
- @table @asis
- @item @code{os} (default: @var{%hurd-vm-operating-system})
- The operating system to instantiate. This default is bare-bones with a
- permissive OpenSSH secure shell daemon listening on port 2222
- (@pxref{Networking Services, @code{openssh-service-type}}).
- @item @code{qemu} (default: @code{qemu-minimal})
- The QEMU package to use.
- @item @code{image} (default: @var{hurd-vm-disk-image})
- The procedure used to build the disk-image built from this
- configuration.
- @item @code{disk-size} (default: @code{'guess})
- The size of the disk image.
- @item @code{memory-size} (default: @code{512})
- The memory size of the Virtual Machine in mebibytes.
- @item @code{options} (default: @code{'("--snapshot")})
- The extra options for running QEMU.
- @item @code{id} (default: @code{#f})
- If set, a non-zero positive integer used to parameterize Childhurd
- instances. It is appended to the service's name,
- e.g. @code{childhurd1}.
- @item @code{net-options} (default: @var{hurd-vm-net-options})
- The procedure used to produce the list of QEMU networking options.
- By default, it produces
- @lisp
- '("--device" "rtl8139,netdev=net0"
- "--netdev" (string-append
- "user,id=net0,"
- "hostfwd=tcp:127.0.0.1:@var{secrets-port}-:1004,"
- "hostfwd=tcp:127.0.0.1:@var{ssh-port}-:2222,"
- "hostfwd=tcp:127.0.0.1:@var{vnc-port}-:5900"))
- @end lisp
- with forwarded ports:
- @example
- @var{secrets-port}: @code{(+ 11004 (* 1000 @var{ID}))}
- @var{ssh-port}: @code{(+ 10022 (* 1000 @var{ID}))}
- @var{vnc-port}: @code{(+ 15900 (* 1000 @var{ID}))}
- @end example
- @item @code{secret-root} (default: @file{/etc/childhurd})
- The root directory with out-of-band secrets to be installed into the
- childhurd once it runs. Childhurds are volatile which means that on
- every startup, secrets such as the SSH host keys and Guix signing key
- are recreated.
- If the @file{/etc/childhurd} directory does not exist, the
- @code{secret-service} running in the Childhurd will be sent an empty
- list of secrets.
- By default, the service automatically populates @file{/etc/childhurd}
- with the following non-volatile secrets, unless they already exist:
- @example
- /etc/childhurd/etc/guix/acl
- /etc/childhurd/etc/guix/signing-key.pub
- /etc/childhurd/etc/guix/signing-key.sec
- /etc/childhurd/etc/ssh/ssh_host_ed25519_key
- /etc/childhurd/etc/ssh/ssh_host_ecdsa_key
- /etc/childhurd/etc/ssh/ssh_host_ed25519_key.pub
- /etc/childhurd/etc/ssh/ssh_host_ecdsa_key.pub
- @end example
- These files are automatically sent to the guest Hurd VM when it boots,
- including permissions.
- @cindex childhurd, offloading
- @cindex Hurd, offloading
- Having these files in place means that only a couple of things are
- missing to allow the host to offload @code{i586-gnu} builds to the
- childhurd:
- @enumerate
- @item
- Authorizing the childhurd's key on the host so that the host accepts
- build results coming from the childhurd, which can be done like so:
- @example
- guix archive --authorize < \
- /etc/childhurd/etc/guix/signing-key.pub
- @end example
- @item
- Adding the childhurd to @file{/etc/guix/machines.scm} (@pxref{Daemon
- Offload Setup}).
- @end enumerate
- We're working towards making that happen automatically---get in touch
- with us at @email{guix-devel@@gnu.org} to discuss it!
- @end table
- @end deftp
- Note that by default the VM image is volatile, i.e., once stopped the
- contents are lost. If you want a stateful image instead, override the
- configuration's @code{image} and @code{options} without
- the @code{--snapshot} flag using something along these lines:
- @lisp
- (service hurd-vm-service-type
- (hurd-vm-configuration
- (image (const "/out/of/store/writable/hurd.img"))
- (options '())))
- @end lisp
- @subsubheading Ganeti
- @cindex ganeti
- @quotation Note
- This service is considered experimental. Configuration options may be changed
- in a backwards-incompatible manner, and not all features have been thorougly
- tested. Users of this service are encouraged to share their experience at
- @email{guix-devel@@gnu.org}.
- @end quotation
- Ganeti is a virtual machine management system. It is designed to keep virtual
- machines running on a cluster of servers even in the event of hardware failures,
- and to make maintenance and recovery tasks easy. It consists of multiple
- services which are described later in this section. In addition to the Ganeti
- service, you will need the OpenSSH service (@pxref{Networking Services,
- @code{openssh-service-type}}), and update the @file{/etc/hosts} file
- (@pxref{operating-system Reference, @code{hosts-file}}) with the cluster name
- and address (or use a DNS server).
- All nodes participating in a Ganeti cluster should have the same Ganeti and
- @file{/etc/hosts} configuration. Here is an example configuration for a Ganeti
- cluster node that supports multiple storage backends, and installs the
- @code{debootstrap} and @code{guix} @dfn{OS providers}:
- @lisp
- (use-package-modules virtualization)
- (use-service-modules base ganeti networking ssh)
- (operating-system
- ;; @dots{}
- (host-name "node1")
- (hosts-file (plain-file "hosts" (format #f "
- 127.0.0.1 localhost
- ::1 localhost
- 192.168.1.200 ganeti.example.com
- 192.168.1.201 node1.example.com node1
- 192.168.1.202 node2.example.com node2
- ")))
- ;; Install QEMU so we can use KVM-based instances, and LVM, DRBD and Ceph
- ;; in order to use the "plain", "drbd" and "rbd" storage backends.
- (packages (append (map specification->package
- '("qemu" "lvm2" "drbd-utils" "ceph"
- ;; Add the debootstrap and guix OS providers.
- "ganeti-instance-guix" "ganeti-instance-debootstrap"))
- %base-packages))
- (services
- (append (list (service static-networking-service-type
- (list (static-networking
- (addresses
- (list (network-address
- (device "eth0")
- (value "192.168.1.201/24"))))
- (routes
- (list (network-route
- (destination "default")
- (gateway "192.168.1.254"))))
- (name-servers '("192.168.1.252"
- "192.168.1.253")))))
- ;; Ganeti uses SSH to communicate between nodes.
- (service openssh-service-type
- (openssh-configuration
- (permit-root-login 'prohibit-password)))
- (service ganeti-service-type
- (ganeti-configuration
- ;; This list specifies allowed file system paths
- ;; for storing virtual machine images.
- (file-storage-paths '("/srv/ganeti/file-storage"))
- ;; This variable configures a single "variant" for
- ;; both Debootstrap and Guix that works with KVM.
- (os %default-ganeti-os))))
- %base-services)))
- @end lisp
- Users are advised to read the
- @url{http://docs.ganeti.org/ganeti/master/html/admin.html,Ganeti
- administrators guide} to learn about the various cluster options and
- day-to-day operations. There is also a
- @url{https://guix.gnu.org/blog/2020/running-a-ganeti-cluster-on-guix/,blog post}
- describing how to configure and initialize a small cluster.
- @defvr {Scheme Variable} ganeti-service-type
- This is a service type that includes all the various services that Ganeti
- nodes should run.
- Its value is a @code{ganeti-configuration} object that defines the package
- to use for CLI operations, as well as configuration for the various daemons.
- Allowed file storage paths and available guest operating systems are also
- configured through this data type.
- @end defvr
- @deftp {Data Type} ganeti-configuration
- The @code{ganeti} service takes the following configuration options:
- @table @asis
- @item @code{ganeti} (default: @code{ganeti})
- The @code{ganeti} package to use. It will be installed to the system profile
- and make @command{gnt-cluster}, @command{gnt-instance}, etc available. Note
- that the value specified here does not affect the other services as each refer
- to a specific @code{ganeti} package (see below).
- @item @code{noded-configuration} (default: @code{(ganeti-noded-configuration)})
- @itemx @code{confd-configuration} (default: @code{(ganeti-confd-configuration)})
- @itemx @code{wconfd-configuration} (default: @code{(ganeti-wconfd-configuration)})
- @itemx @code{luxid-configuration} (default: @code{(ganeti-luxid-configuration)})
- @itemx @code{rapi-configuration} (default: @code{(ganeti-rapi-configuration)})
- @itemx @code{kvmd-configuration} (default: @code{(ganeti-kvmd-configuration)})
- @itemx @code{mond-configuration} (default: @code{(ganeti-mond-configuration)})
- @itemx @code{metad-configuration} (default: @code{(ganeti-metad-configuration)})
- @itemx @code{watcher-configuration} (default: @code{(ganeti-watcher-configuration)})
- @itemx @code{cleaner-configuration} (default: @code{(ganeti-cleaner-configuration)})
- These options control the various daemons and cron jobs that are distributed
- with Ganeti. The possible values for these are described in detail below.
- To override a setting, you must use the configuration type for that service:
- @lisp
- (service ganeti-service-type
- (ganeti-configuration
- (rapi-configuration
- (ganeti-rapi-configuration
- (interface "eth1"))))
- (watcher-configuration
- (ganeti-watcher-configuration
- (rapi-ip "10.0.0.1"))))
- @end lisp
- @item @code{file-storage-paths} (default: @code{'()})
- List of allowed directories for file storage backend.
- @item @code{os} (default: @code{%default-ganeti-os})
- List of @code{<ganeti-os>} records.
- @end table
- In essence @code{ganeti-service-type} is shorthand for declaring each service
- individually:
- @lisp
- (service ganeti-noded-service-type)
- (service ganeti-confd-service-type)
- (service ganeti-wconfd-service-type)
- (service ganeti-luxid-service-type)
- (service ganeti-kvmd-service-type)
- (service ganeti-mond-service-type)
- (service ganeti-metad-service-type)
- (service ganeti-watcher-service-type)
- (service ganeti-cleaner-service-type)
- @end lisp
- Plus a service extension for @code{etc-service-type} that configures the file
- storage backend and OS variants.
- @end deftp
- @deftp {Data Type} ganeti-os
- This data type is suitable for passing to the @code{os} parameter of
- @code{ganeti-configuration}. It takes the following parameters:
- @table @asis
- @item @code{name}
- The name for this OS provider. It is only used to specify where the
- configuration ends up. Setting it to ``debootstrap'' will create
- @file{/etc/ganeti/instance-debootstrap}.
- @item @code{extension}
- The file extension for variants of this OS type. For example
- @file{.conf} or @file{.scm}.
- @item @code{variants} (default: @code{'()})
- List of @code{ganeti-os-variant} objects for this OS.
- @end table
- @end deftp
- @deftp {Data Type} ganeti-os-variant
- This is the data type for a Ganeti OS variant. It takes the following
- parameters:
- @table @asis
- @item @code{name}
- The name of this variant.
- @item @code{configuration}
- A configuration file for this variant.
- @end table
- @end deftp
- @defvr {Scheme Variable} %default-debootstrap-hooks
- This variable contains hooks to configure networking and the GRUB bootloader.
- @end defvr
- @defvr {Scheme Variable} %default-debootstrap-extra-pkgs
- This variable contains a list of packages suitable for a fully-virtualized guest.
- @end defvr
- @deftp {Data Type} debootstrap-configuration
- This data type creates configuration files suitable for the debootstrap OS provider.
- @table @asis
- @item @code{hooks} (default: @code{%default-debootstrap-hooks})
- When not @code{#f}, this must be a G-expression that specifies a directory with
- scripts that will run when the OS is installed. It can also be a list of
- @code{(name . file-like)} pairs. For example:
- @lisp
- `((99-hello-world . ,(plain-file "#!/bin/sh\necho Hello, World")))
- @end lisp
- That will create a directory with one executable named @code{99-hello-world}
- and run it every time this variant is installed. If set to @code{#f}, hooks
- in @file{/etc/ganeti/instance-debootstrap/hooks} will be used, if any.
- @item @code{proxy} (default: @code{#f})
- Optional HTTP proxy to use.
- @item @code{mirror} (default: @code{#f})
- The Debian mirror. Typically something like @code{http://ftp.no.debian.org/debian}.
- The default varies depending on the distribution.
- @item @code{arch} (default: @code{#f})
- The dpkg architecture. Set to @code{armhf} to debootstrap an ARMv7 instance
- on an AArch64 host. Default is to use the current system architecture.
- @item @code{suite} (default: @code{"stable"})
- When set, this must be a Debian distribution ``suite'' such as @code{buster}
- or @code{focal}. If set to @code{#f}, the default for the OS provider is used.
- @item @code{extra-pkgs} (default: @code{%default-debootstrap-extra-pkgs})
- List of extra packages that will get installed by dpkg in addition
- to the minimal system.
- @item @code{components} (default: @code{#f})
- When set, must be a list of Debian repository ``components''. For example
- @code{'("main" "contrib")}.
- @item @code{generate-cache?} (default: @code{#t})
- Whether to automatically cache the generated debootstrap archive.
- @item @code{clean-cache} (default: @code{14})
- Discard the cache after this amount of days. Use @code{#f} to never
- clear the cache.
- @item @code{partition-style} (default: @code{'msdos})
- The type of partition to create. When set, it must be one of
- @code{'msdos}, @code{'none} or a string.
- @item @code{partition-alignment} (default: @code{2048})
- Alignment of the partition in sectors.
- @end table
- @end deftp
- @deffn {Scheme Procedure} debootstrap-variant @var{name} @var{configuration}
- This is a helper procedure that creates a @code{ganeti-os-variant} record. It
- takes two parameters: a name and a @code{debootstrap-configuration} object.
- @end deffn
- @deffn {Scheme Procedure} debootstrap-os @var{variants}@dots{}
- This is a helper procedure that creates a @code{ganeti-os} record. It takes
- a list of variants created with @code{debootstrap-variant}.
- @end deffn
- @deffn {Scheme Procedure} guix-variant @var{name} @var{configuration}
- This is a helper procedure that creates a @code{ganeti-os-variant} record for
- use with the Guix OS provider. It takes a name and a G-expression that returns
- a ``file-like'' (@pxref{G-Expressions, file-like objects}) object containing a
- Guix System configuration.
- @end deffn
- @deffn {Scheme Procedure} guix-os @var{variants}@dots{}
- This is a helper procedure that creates a @code{ganeti-os} record. It
- takes a list of variants produced by @code{guix-variant}.
- @end deffn
- @defvr {Scheme Variable} %default-debootstrap-variants
- This is a convenience variable to make the debootstrap provider work
- ``out of the box'' without users having to declare variants manually. It
- contains a single debootstrap variant with the default configuration:
- @lisp
- (list (debootstrap-variant
- "default"
- (debootstrap-configuration)))
- @end lisp
- @end defvr
- @defvr {Scheme Variable} %default-guix-variants
- This is a convenience variable to make the Guix OS provider work without
- additional configuration. It creates a virtual machine that has an SSH
- server, a serial console, and authorizes the Ganeti hosts SSH keys.
- @lisp
- (list (guix-variant
- "default"
- (file-append ganeti-instance-guix
- "/share/doc/ganeti-instance-guix/examples/dynamic.scm")))
- @end lisp
- @end defvr
- Users can implement support for OS providers unbeknownst to Guix by extending
- the @code{ganeti-os} and @code{ganeti-os-variant} records appropriately.
- For example:
- @lisp
- (ganeti-os
- (name "custom")
- (extension ".conf")
- (variants
- (list (ganeti-os-variant
- (name "foo")
- (configuration (plain-file "bar" "this is fine"))))))
- @end lisp
- That creates @file{/etc/ganeti/instance-custom/variants/foo.conf} which points
- to a file in the store with contents @code{this is fine}. It also creates
- @file{/etc/ganeti/instance-custom/variants/variants.list} with contents @code{foo}.
- Obviously this may not work for all OS providers out there. If you find the
- interface limiting, please reach out to @email{guix-devel@@gnu.org}.
- The rest of this section documents the various services that are included by
- @code{ganeti-service-type}.
- @defvr {Scheme Variable} ganeti-noded-service-type
- @command{ganeti-noded} is the daemon responsible for node-specific functions
- within the Ganeti system. The value of this service must be a
- @code{ganeti-noded-configuration} object.
- @end defvr
- @deftp {Data Type} ganeti-noded-configuration
- This is the configuration for the @code{ganeti-noded} service.
- @table @asis
- @item @code{ganeti} (default: @code{ganeti})
- The @code{ganeti} package to use for this service.
- @item @code{port} (default: @code{1811})
- The TCP port on which the node daemon listens for network requests.
- @item @code{address} (default: @code{"0.0.0.0"})
- The network address that the daemon will bind to. The default address means
- bind to all available addresses.
- @item @code{interface} (default: @code{#f})
- When this is set, it must be a specific network interface (e.g.@: @code{eth0})
- that the daemon will bind to.
- @item @code{max-clients} (default: @code{20})
- This sets a limit on the maximum number of simultaneous client connections
- that the daemon will handle. Connections above this count are accepted, but
- no responses will be sent until enough connections have closed.
- @item @code{ssl?} (default: @code{#t})
- Whether to use SSL/TLS to encrypt network communications. The certificate
- is automatically provisioned by the cluster and can be rotated with
- @command{gnt-cluster renew-crypto}.
- @item @code{ssl-key} (default: @file{"/var/lib/ganeti/server.pem"})
- This can be used to provide a specific encryption key for TLS communications.
- @item @code{ssl-cert} (default: @file{"/var/lib/ganeti/server.pem"})
- This can be used to provide a specific certificate for TLS communications.
- @item @code{debug?} (default: @code{#f})
- When true, the daemon performs additional logging for debugging purposes.
- Note that this will leak encryption details to the log files, use with caution.
- @end table
- @end deftp
- @defvr {Scheme Variable} ganeti-confd-service-type
- @command{ganeti-confd} answers queries related to the configuration of a
- Ganeti cluster. The purpose of this daemon is to have a highly available
- and fast way to query cluster configuration values. It is automatically
- active on all @dfn{master candidates}. The value of this service must be a
- @code{ganeti-confd-configuration} object.
- @end defvr
- @deftp {Data Type} ganeti-confd-configuration
- This is the configuration for the @code{ganeti-confd} service.
- @table @asis
- @item @code{ganeti} (default: @code{ganeti})
- The @code{ganeti} package to use for this service.
- @item @code{port} (default: @code{1814})
- The UDP port on which to listen for network requests.
- @item @code{address} (default: @code{"0.0.0.0"})
- Network address that the daemon will bind to.
- @item @code{debug?} (default: @code{#f})
- When true, the daemon performs additional logging for debugging purposes.
- @end table
- @end deftp
- @defvr {Scheme Variable} ganeti-wconfd-service-type
- @command{ganeti-wconfd} is the daemon that has authoritative knowledge
- about the cluster configuration and is the only entity that can accept
- changes to it. All jobs that need to modify the configuration will do so
- by sending appropriate requests to this daemon. It only runs on the
- @dfn{master node} and will automatically disable itself on other nodes.
- The value of this service must be a
- @code{ganeti-wconfd-configuration} object.
- @end defvr
- @deftp {Data Type} ganeti-wconfd-configuration
- This is the configuration for the @code{ganeti-wconfd} service.
- @table @asis
- @item @code{ganeti} (default: @code{ganeti})
- The @code{ganeti} package to use for this service.
- @item @code{no-voting?} (default: @code{#f})
- The daemon will refuse to start if the majority of cluster nodes does not
- agree that it is running on the master node. Set to @code{#t} to start
- even if a quorum can not be reached (dangerous, use with caution).
- @item @code{debug?} (default: @code{#f})
- When true, the daemon performs additional logging for debugging purposes.
- @end table
- @end deftp
- @defvr {Scheme Variable} ganeti-luxid-service-type
- @command{ganeti-luxid} is a daemon used to answer queries related to the
- configuration and the current live state of a Ganeti cluster. Additionally,
- it is the authoritative daemon for the Ganeti job queue. Jobs can be
- submitted via this daemon and it schedules and starts them.
- It takes a @code{ganeti-luxid-configuration} object.
- @end defvr
- @deftp {Data Type} ganeti-luxid-configuration
- This is the configuration for the @code{ganeti-luxid} service.
- @table @asis
- @item @code{ganeti} (default: @code{ganeti})
- The @code{ganeti} package to use for this service.
- @item @code{no-voting?} (default: @code{#f})
- The daemon will refuse to start if it cannot verify that the majority of
- cluster nodes believes that it is running on the master node. Set to
- @code{#t} to ignore such checks and start anyway (this can be dangerous).
- @item @code{debug?} (default: @code{#f})
- When true, the daemon performs additional logging for debugging purposes.
- @end table
- @end deftp
- @defvr {Scheme Variable} ganeti-rapi-service-type
- @command{ganeti-rapi} provides a remote API for Ganeti clusters. It runs on
- the master node and can be used to perform cluster actions programmatically
- via a JSON-based RPC protocol.
- Most query operations are allowed without authentication (unless
- @var{require-authentication?} is set), whereas write operations require
- explicit authorization via the @file{/var/lib/ganeti/rapi/users} file. See
- the @url{http://docs.ganeti.org/ganeti/master/html/rapi.html, Ganeti Remote
- API documentation} for more information.
- The value of this service must be a @code{ganeti-rapi-configuration} object.
- @end defvr
- @deftp {Data Type} ganeti-rapi-configuration
- This is the configuration for the @code{ganeti-rapi} service.
- @table @asis
- @item @code{ganeti} (default: @code{ganeti})
- The @code{ganeti} package to use for this service.
- @item @code{require-authentication?} (default: @code{#f})
- Whether to require authentication even for read-only operations.
- @item @code{port} (default: @code{5080})
- The TCP port on which to listen to API requests.
- @item @code{address} (default: @code{"0.0.0.0"})
- The network address that the service will bind to. By default it listens
- on all configured addresses.
- @item @code{interface} (default: @code{#f})
- When set, it must specify a specific network interface such as @code{eth0}
- that the daemon will bind to.
- @item @code{max-clients} (default: @code{20})
- The maximum number of simultaneous client requests to handle. Further
- connections are allowed, but no responses are sent until enough connections
- have closed.
- @item @code{ssl?} (default: @code{#t})
- Whether to use SSL/TLS encryption on the RAPI port.
- @item @code{ssl-key} (default: @file{"/var/lib/ganeti/server.pem"})
- This can be used to provide a specific encryption key for TLS communications.
- @item @code{ssl-cert} (default: @file{"/var/lib/ganeti/server.pem"})
- This can be used to provide a specific certificate for TLS communications.
- @item @code{debug?} (default: @code{#f})
- When true, the daemon performs additional logging for debugging purposes.
- Note that this will leak encryption details to the log files, use with caution.
- @end table
- @end deftp
- @defvr {Scheme Variable} ganeti-kvmd-service-type
- @command{ganeti-kvmd} is responsible for determining whether a given KVM
- instance was shut down by an administrator or a user. Normally Ganeti will
- restart an instance that was not stopped through Ganeti itself. If the
- cluster option @code{user_shutdown} is true, this daemon monitors the
- @code{QMP} socket provided by QEMU and listens for shutdown events, and
- marks the instance as @dfn{USER_down} instead of @dfn{ERROR_down} when
- it shuts down gracefully by itself.
- It takes a @code{ganeti-kvmd-configuration} object.
- @end defvr
- @deftp {Data Type} ganeti-kvmd-configuration
- @table @asis
- @item @code{ganeti} (default: @code{ganeti})
- The @code{ganeti} package to use for this service.
- @item @code{debug?} (default: @code{#f})
- When true, the daemon performs additional logging for debugging purposes.
- @end table
- @end deftp
- @defvr {Scheme Variable} ganeti-mond-service-type
- @command{ganeti-mond} is an optional daemon that provides Ganeti monitoring
- functionality. It is responsible for running data collectors and publish the
- collected information through a HTTP interface.
- It takes a @code{ganeti-mond-configuration} object.
- @end defvr
- @deftp {Data Type} ganeti-mond-configuration
- @table @asis
- @item @code{ganeti} (default: @code{ganeti})
- The @code{ganeti} package to use for this service.
- @item @code{port} (default: @code{1815})
- The port on which the daemon will listen.
- @item @code{address} (default: @code{"0.0.0.0"})
- The network address that the daemon will bind to. By default it binds to all
- available interfaces.
- @item @code{debug?} (default: @code{#f})
- When true, the daemon performs additional logging for debugging purposes.
- @end table
- @end deftp
- @defvr {Scheme Variable} ganeti-metad-service-type
- @command{ganeti-metad} is an optional daemon that can be used to provide
- information about the cluster to instances or OS install scripts.
- It takes a @code{ganeti-metad-configuration} object.
- @end defvr
- @deftp {Data Type} ganeti-metad-configuration
- @table @asis
- @item @code{ganeti} (default: @code{ganeti})
- The @code{ganeti} package to use for this service.
- @item @code{port} (default: @code{80})
- The port on which the daemon will listen.
- @item @code{address} (default: @code{#f})
- If set, the daemon will bind to this address only. If left unset, the behavior
- depends on the cluster configuration.
- @item @code{debug?} (default: @code{#f})
- When true, the daemon performs additional logging for debugging purposes.
- @end table
- @end deftp
- @defvr {Scheme Variable} ganeti-watcher-service-type
- @command{ganeti-watcher} is a script designed to run periodically and ensure
- the health of a cluster. It will automatically restart instances that have
- stopped without Ganeti's consent, and repairs DRBD links in case a node has
- rebooted. It also archives old cluster jobs and restarts Ganeti daemons
- that are not running. If the cluster parameter @code{ensure_node_health}
- is set, the watcher will also shutdown instances and DRBD devices if the
- node it is running on is declared offline by known master candidates.
- It can be paused on all nodes with @command{gnt-cluster watcher pause}.
- The service takes a @code{ganeti-watcher-configuration} object.
- @end defvr
- @deftp {Data Type} ganeti-watcher-configuration
- @table @asis
- @item @code{ganeti} (default: @code{ganeti})
- The @code{ganeti} package to use for this service.
- @item @code{schedule} (default: @code{'(next-second-from (next-minute (range 0 60 5)))})
- How often to run the script. The default is every five minutes.
- @item @code{rapi-ip} (default: @code{#f})
- This option needs to be specified only if the RAPI daemon is configured to use
- a particular interface or address. By default the cluster address is used.
- @item @code{job-age} (default: @code{(* 6 3600)})
- Archive cluster jobs older than this age, specified in seconds. The default
- is 6 hours. This keeps @command{gnt-job list} manageable.
- @item @code{verify-disks?} (default: @code{#t})
- If this is @code{#f}, the watcher will not try to repair broken DRBD links
- automatically. Administrators will need to use @command{gnt-cluster verify-disks}
- manually instead.
- @item @code{debug?} (default: @code{#f})
- When @code{#t}, the script performs additional logging for debugging purposes.
- @end table
- @end deftp
- @defvr {Scheme Variable} ganeti-cleaner-service-type
- @command{ganeti-cleaner} is a script designed to run periodically and remove
- old files from the cluster. This service type controls two @dfn{cron jobs}:
- one intended for the master node that permanently purges old cluster jobs,
- and one intended for every node that removes expired X509 certificates, keys,
- and outdated @command{ganeti-watcher} information. Like all Ganeti services,
- it is safe to include even on non-master nodes as it will disable itself as
- necessary.
- It takes a @code{ganeti-cleaner-configuration} object.
- @end defvr
- @deftp {Data Type} ganeti-cleaner-configuration
- @table @asis
- @item @code{ganeti} (default: @code{ganeti})
- The @code{ganeti} package to use for the @command{gnt-cleaner} command.
- @item @code{master-schedule} (default: @code{"45 1 * * *"})
- How often to run the master cleaning job. The default is once per day, at
- 01:45:00.
- @item @code{node-schedule} (default: @code{"45 2 * * *"})
- How often to run the node cleaning job. The default is once per day, at
- 02:45:00.
- @end table
- @end deftp
- @node Version Control Services
- @subsection Version Control Services
- The @code{(gnu services version-control)} module provides a service to
- allow remote access to local Git repositories. There are three options:
- the @code{git-daemon-service}, which provides access to repositories via
- the @code{git://} unsecured TCP-based protocol, extending the
- @code{nginx} web server to proxy some requests to
- @code{git-http-backend}, or providing a web interface with
- @code{cgit-service-type}.
- @deffn {Scheme Procedure} git-daemon-service [#:config (git-daemon-configuration)]
- Return a service that runs @command{git daemon}, a simple TCP server to
- expose repositories over the Git protocol for anonymous access.
- The optional @var{config} argument should be a
- @code{<git-daemon-configuration>} object, by default it allows read-only
- access to exported@footnote{By creating the magic file
- @file{git-daemon-export-ok} in the repository directory.} repositories under
- @file{/srv/git}.
- @end deffn
- @deftp {Data Type} git-daemon-configuration
- Data type representing the configuration for @code{git-daemon-service}.
- @table @asis
- @item @code{package} (default: @code{git})
- Package object of the Git distributed version control system.
- @item @code{export-all?} (default: @code{#f})
- Whether to allow access for all Git repositories, even if they do not
- have the @file{git-daemon-export-ok} file.
- @item @code{base-path} (default: @file{/srv/git})
- Whether to remap all the path requests as relative to the given path.
- If you run @command{git daemon} with @code{(base-path "/srv/git")} on
- @samp{example.com}, then if you later try to pull
- @indicateurl{git://example.com/hello.git}, git daemon will interpret the
- path as @file{/srv/git/hello.git}.
- @item @code{user-path} (default: @code{#f})
- Whether to allow @code{~user} notation to be used in requests. When
- specified with empty string, requests to
- @indicateurl{git://host/~alice/foo} is taken as a request to access
- @code{foo} repository in the home directory of user @code{alice}. If
- @code{(user-path "@var{path}")} is specified, the same request is taken
- as a request to access @file{@var{path}/foo} repository in the home
- directory of user @code{alice}.
- @item @code{listen} (default: @code{'()})
- Whether to listen on specific IP addresses or hostnames, defaults to
- all.
- @item @code{port} (default: @code{#f})
- Whether to listen on an alternative port, which defaults to 9418.
- @item @code{whitelist} (default: @code{'()})
- If not empty, only allow access to this list of directories.
- @item @code{extra-options} (default: @code{'()})
- Extra options will be passed to @command{git daemon}, please run
- @command{man git-daemon} for more information.
- @end table
- @end deftp
- The @code{git://} protocol lacks authentication. When you pull from a
- repository fetched via @code{git://}, you don't know whether the data you
- receive was modified or is even coming from the specified host, and your
- connection is subject to eavesdropping. It's better to use an authenticated
- and encrypted transport, such as @code{https}. Although Git allows you
- to serve repositories using unsophisticated file-based web servers,
- there is a faster protocol implemented by the @code{git-http-backend}
- program. This program is the back-end of a proper Git web service. It
- is designed to sit behind a FastCGI proxy. @xref{Web Services}, for more
- on running the necessary @code{fcgiwrap} daemon.
- Guix has a separate configuration data type for serving Git repositories
- over HTTP.
- @deftp {Data Type} git-http-configuration
- Data type representing the configuration for a future
- @code{git-http-service-type}; can currently be used to configure Nginx
- through @code{git-http-nginx-location-configuration}.
- @table @asis
- @item @code{package} (default: @var{git})
- Package object of the Git distributed version control system.
- @item @code{git-root} (default: @file{/srv/git})
- Directory containing the Git repositories to expose to the world.
- @item @code{export-all?} (default: @code{#f})
- Whether to expose access for all Git repositories in @var{git-root},
- even if they do not have the @file{git-daemon-export-ok} file.
- @item @code{uri-path} (default: @samp{/git/})
- Path prefix for Git access. With the default @samp{/git/} prefix, this
- will map @indicateurl{http://@var{server}/git/@var{repo}.git} to
- @file{/srv/git/@var{repo}.git}. Requests whose URI paths do not begin
- with this prefix are not passed on to this Git instance.
- @item @code{fcgiwrap-socket} (default: @code{127.0.0.1:9000})
- The socket on which the @code{fcgiwrap} daemon is listening. @xref{Web
- Services}.
- @end table
- @end deftp
- There is no @code{git-http-service-type}, currently; instead you can
- create an @code{nginx-location-configuration} from a
- @code{git-http-configuration} and then add that location to a web
- server.
- @deffn {Scheme Procedure} git-http-nginx-location-configuration @
- [config=(git-http-configuration)]
- Compute an @code{nginx-location-configuration} that corresponds to the
- given Git http configuration. An example nginx service definition to
- serve the default @file{/srv/git} over HTTPS might be:
- @lisp
- (service nginx-service-type
- (nginx-configuration
- (server-blocks
- (list
- (nginx-server-configuration
- (listen '("443 ssl"))
- (server-name "git.my-host.org")
- (ssl-certificate
- "/etc/letsencrypt/live/git.my-host.org/fullchain.pem")
- (ssl-certificate-key
- "/etc/letsencrypt/live/git.my-host.org/privkey.pem")
- (locations
- (list
- (git-http-nginx-location-configuration
- (git-http-configuration (uri-path "/"))))))))))
- @end lisp
- This example assumes that you are using Let's Encrypt to get your TLS
- certificate. @xref{Certificate Services}. The default @code{certbot}
- service will redirect all HTTP traffic on @code{git.my-host.org} to
- HTTPS@. You will also need to add an @code{fcgiwrap} proxy to your
- system services. @xref{Web Services}.
- @end deffn
- @subsubheading Cgit Service
- @cindex Cgit service
- @cindex Git, web interface
- @uref{https://git.zx2c4.com/cgit/, Cgit} is a web frontend for Git
- repositories written in C.
- The following example will configure the service with default values.
- By default, Cgit can be accessed on port 80 (@code{http://localhost:80}).
- @lisp
- (service cgit-service-type)
- @end lisp
- The @code{file-object} type designates either a file-like object
- (@pxref{G-Expressions, file-like objects}) or a string.
- @c %start of fragment
- Available @code{cgit-configuration} fields are:
- @deftypevr {@code{cgit-configuration} parameter} package package
- The CGIT package.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} nginx-server-configuration-list nginx
- NGINX configuration.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} file-object about-filter
- Specifies a command which will be invoked to format the content of about
- pages (both top-level and for each repository).
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} string agefile
- Specifies a path, relative to each repository path, which can be used to
- specify the date and time of the youngest commit in the repository.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} file-object auth-filter
- Specifies a command that will be invoked for authenticating repository
- access.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} string branch-sort
- Flag which, when set to @samp{age}, enables date ordering in the branch
- ref list, and when set @samp{name} enables ordering by branch name.
- Defaults to @samp{"name"}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} string cache-root
- Path used to store the cgit cache entries.
- Defaults to @samp{"/var/cache/cgit"}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} integer cache-static-ttl
- Number which specifies the time-to-live, in minutes, for the cached
- version of repository pages accessed with a fixed SHA1.
- Defaults to @samp{-1}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} integer cache-dynamic-ttl
- Number which specifies the time-to-live, in minutes, for the cached
- version of repository pages accessed without a fixed SHA1.
- Defaults to @samp{5}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} integer cache-repo-ttl
- Number which specifies the time-to-live, in minutes, for the cached
- version of the repository summary page.
- Defaults to @samp{5}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} integer cache-root-ttl
- Number which specifies the time-to-live, in minutes, for the cached
- version of the repository index page.
- Defaults to @samp{5}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} integer cache-scanrc-ttl
- Number which specifies the time-to-live, in minutes, for the result of
- scanning a path for Git repositories.
- Defaults to @samp{15}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} integer cache-about-ttl
- Number which specifies the time-to-live, in minutes, for the cached
- version of the repository about page.
- Defaults to @samp{15}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} integer cache-snapshot-ttl
- Number which specifies the time-to-live, in minutes, for the cached
- version of snapshots.
- Defaults to @samp{5}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} integer cache-size
- The maximum number of entries in the cgit cache. When set to @samp{0},
- caching is disabled.
- Defaults to @samp{0}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} boolean case-sensitive-sort?
- Sort items in the repo list case sensitively.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} list clone-prefix
- List of common prefixes which, when combined with a repository URL,
- generates valid clone URLs for the repository.
- Defaults to @samp{()}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} list clone-url
- List of @code{clone-url} templates.
- Defaults to @samp{()}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} file-object commit-filter
- Command which will be invoked to format commit messages.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} string commit-sort
- Flag which, when set to @samp{date}, enables strict date ordering in the
- commit log, and when set to @samp{topo} enables strict topological
- ordering.
- Defaults to @samp{"git log"}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} file-object css
- URL which specifies the css document to include in all cgit pages.
- Defaults to @samp{"/share/cgit/cgit.css"}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} file-object email-filter
- Specifies a command which will be invoked to format names and email
- address of committers, authors, and taggers, as represented in various
- places throughout the cgit interface.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} boolean embedded?
- Flag which, when set to @samp{#t}, will make cgit generate a HTML
- fragment suitable for embedding in other HTML pages.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} boolean enable-commit-graph?
- Flag which, when set to @samp{#t}, will make cgit print an ASCII-art
- commit history graph to the left of the commit messages in the
- repository log page.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} boolean enable-filter-overrides?
- Flag which, when set to @samp{#t}, allows all filter settings to be
- overridden in repository-specific cgitrc files.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} boolean enable-follow-links?
- Flag which, when set to @samp{#t}, allows users to follow a file in the
- log view.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} boolean enable-http-clone?
- If set to @samp{#t}, cgit will act as an dumb HTTP endpoint for Git
- clones.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} boolean enable-index-links?
- Flag which, when set to @samp{#t}, will make cgit generate extra links
- "summary", "commit", "tree" for each repo in the repository index.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} boolean enable-index-owner?
- Flag which, when set to @samp{#t}, will make cgit display the owner of
- each repo in the repository index.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} boolean enable-log-filecount?
- Flag which, when set to @samp{#t}, will make cgit print the number of
- modified files for each commit on the repository log page.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} boolean enable-log-linecount?
- Flag which, when set to @samp{#t}, will make cgit print the number of
- added and removed lines for each commit on the repository log page.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} boolean enable-remote-branches?
- Flag which, when set to @code{#t}, will make cgit display remote
- branches in the summary and refs views.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} boolean enable-subject-links?
- Flag which, when set to @code{1}, will make cgit use the subject of the
- parent commit as link text when generating links to parent commits in
- commit view.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} boolean enable-html-serving?
- Flag which, when set to @samp{#t}, will make cgit use the subject of the
- parent commit as link text when generating links to parent commits in
- commit view.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} boolean enable-tree-linenumbers?
- Flag which, when set to @samp{#t}, will make cgit generate linenumber
- links for plaintext blobs printed in the tree view.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} boolean enable-git-config?
- Flag which, when set to @samp{#f}, will allow cgit to use Git config to
- set any repo specific settings.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} file-object favicon
- URL used as link to a shortcut icon for cgit.
- Defaults to @samp{"/favicon.ico"}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} string footer
- The content of the file specified with this option will be included
- verbatim at the bottom of all pages (i.e.@: it replaces the standard
- "generated by..."@: message).
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} string head-include
- The content of the file specified with this option will be included
- verbatim in the HTML HEAD section on all pages.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} string header
- The content of the file specified with this option will be included
- verbatim at the top of all pages.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} file-object include
- Name of a configfile to include before the rest of the current config-
- file is parsed.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} string index-header
- The content of the file specified with this option will be included
- verbatim above the repository index.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} string index-info
- The content of the file specified with this option will be included
- verbatim below the heading on the repository index page.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} boolean local-time?
- Flag which, if set to @samp{#t}, makes cgit print commit and tag times
- in the servers timezone.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} file-object logo
- URL which specifies the source of an image which will be used as a logo
- on all cgit pages.
- Defaults to @samp{"/share/cgit/cgit.png"}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} string logo-link
- URL loaded when clicking on the cgit logo image.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} file-object owner-filter
- Command which will be invoked to format the Owner column of the main
- page.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} integer max-atom-items
- Number of items to display in atom feeds view.
- Defaults to @samp{10}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} integer max-commit-count
- Number of entries to list per page in "log" view.
- Defaults to @samp{50}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} integer max-message-length
- Number of commit message characters to display in "log" view.
- Defaults to @samp{80}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} integer max-repo-count
- Specifies the number of entries to list per page on the repository index
- page.
- Defaults to @samp{50}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} integer max-repodesc-length
- Specifies the maximum number of repo description characters to display
- on the repository index page.
- Defaults to @samp{80}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} integer max-blob-size
- Specifies the maximum size of a blob to display HTML for in KBytes.
- Defaults to @samp{0}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} string max-stats
- Maximum statistics period. Valid values are @samp{week},@samp{month},
- @samp{quarter} and @samp{year}.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} mimetype-alist mimetype
- Mimetype for the specified filename extension.
- Defaults to @samp{((gif "image/gif") (html "text/html") (jpg
- "image/jpeg") (jpeg "image/jpeg") (pdf "application/pdf") (png
- "image/png") (svg "image/svg+xml"))}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} file-object mimetype-file
- Specifies the file to use for automatic mimetype lookup.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} string module-link
- Text which will be used as the formatstring for a hyperlink when a
- submodule is printed in a directory listing.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} boolean nocache?
- If set to the value @samp{#t} caching will be disabled.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} boolean noplainemail?
- If set to @samp{#t} showing full author email addresses will be
- disabled.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} boolean noheader?
- Flag which, when set to @samp{#t}, will make cgit omit the standard
- header on all pages.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} project-list project-list
- A list of subdirectories inside of @code{repository-directory}, relative
- to it, that should loaded as Git repositories. An empty list means that
- all subdirectories will be loaded.
- Defaults to @samp{()}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} file-object readme
- Text which will be used as default value for @code{cgit-repo-readme}.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} boolean remove-suffix?
- If set to @code{#t} and @code{repository-directory} is enabled, if any
- repositories are found with a suffix of @code{.git}, this suffix will be
- removed for the URL and name.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} integer renamelimit
- Maximum number of files to consider when detecting renames.
- Defaults to @samp{-1}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} string repository-sort
- The way in which repositories in each section are sorted.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} robots-list robots
- Text used as content for the @code{robots} meta-tag.
- Defaults to @samp{("noindex" "nofollow")}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} string root-desc
- Text printed below the heading on the repository index page.
- Defaults to @samp{"a fast webinterface for the git dscm"}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} string root-readme
- The content of the file specified with this option will be included
- verbatim below the ``about'' link on the repository index page.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} string root-title
- Text printed as heading on the repository index page.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} boolean scan-hidden-path
- If set to @samp{#t} and repository-directory is enabled,
- repository-directory will recurse into directories whose name starts
- with a period. Otherwise, repository-directory will stay away from such
- directories, considered as ``hidden''. Note that this does not apply to
- the @file{.git} directory in non-bare repos.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} list snapshots
- Text which specifies the default set of snapshot formats that cgit
- generates links for.
- Defaults to @samp{()}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} repository-directory repository-directory
- Name of the directory to scan for repositories (represents
- @code{scan-path}).
- Defaults to @samp{"/srv/git"}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} string section
- The name of the current repository section - all repositories defined
- after this option will inherit the current section name.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} string section-sort
- Flag which, when set to @samp{1}, will sort the sections on the
- repository listing by name.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} integer section-from-path
- A number which, if defined prior to repository-directory, specifies how
- many path elements from each repo path to use as a default section name.
- Defaults to @samp{0}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} boolean side-by-side-diffs?
- If set to @samp{#t} shows side-by-side diffs instead of unidiffs per
- default.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} file-object source-filter
- Specifies a command which will be invoked to format plaintext blobs in
- the tree view.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} integer summary-branches
- Specifies the number of branches to display in the repository ``summary''
- view.
- Defaults to @samp{10}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} integer summary-log
- Specifies the number of log entries to display in the repository
- ``summary'' view.
- Defaults to @samp{10}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} integer summary-tags
- Specifies the number of tags to display in the repository ``summary''
- view.
- Defaults to @samp{10}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} string strict-export
- Filename which, if specified, needs to be present within the repository
- for cgit to allow access to that repository.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} string virtual-root
- URL which, if specified, will be used as root for all cgit links.
- Defaults to @samp{"/"}.
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} repository-cgit-configuration-list repositories
- A list of @dfn{cgit-repo} records to use with config.
- Defaults to @samp{()}.
- Available @code{repository-cgit-configuration} fields are:
- @deftypevr {@code{repository-cgit-configuration} parameter} repo-list snapshots
- A mask of snapshot formats for this repo that cgit generates links for,
- restricted by the global @code{snapshots} setting.
- Defaults to @samp{()}.
- @end deftypevr
- @deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object source-filter
- Override the default @code{source-filter}.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{repository-cgit-configuration} parameter} repo-string url
- The relative URL used to access the repository.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object about-filter
- Override the default @code{about-filter}.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{repository-cgit-configuration} parameter} repo-string branch-sort
- Flag which, when set to @samp{age}, enables date ordering in the branch
- ref list, and when set to @samp{name} enables ordering by branch name.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{repository-cgit-configuration} parameter} repo-list clone-url
- A list of URLs which can be used to clone repo.
- Defaults to @samp{()}.
- @end deftypevr
- @deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object commit-filter
- Override the default @code{commit-filter}.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{repository-cgit-configuration} parameter} repo-string commit-sort
- Flag which, when set to @samp{date}, enables strict date ordering in the
- commit log, and when set to @samp{topo} enables strict topological
- ordering.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{repository-cgit-configuration} parameter} repo-string defbranch
- The name of the default branch for this repository. If no such branch
- exists in the repository, the first branch name (when sorted) is used as
- default instead. By default branch pointed to by HEAD, or ``master'' if
- there is no suitable HEAD.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{repository-cgit-configuration} parameter} repo-string desc
- The value to show as repository description.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{repository-cgit-configuration} parameter} repo-string homepage
- The value to show as repository homepage.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object email-filter
- Override the default @code{email-filter}.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{repository-cgit-configuration} parameter} maybe-repo-boolean enable-commit-graph?
- A flag which can be used to disable the global setting
- @code{enable-commit-graph?}.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{repository-cgit-configuration} parameter} maybe-repo-boolean enable-log-filecount?
- A flag which can be used to disable the global setting
- @code{enable-log-filecount?}.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{repository-cgit-configuration} parameter} maybe-repo-boolean enable-log-linecount?
- A flag which can be used to disable the global setting
- @code{enable-log-linecount?}.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{repository-cgit-configuration} parameter} maybe-repo-boolean enable-remote-branches?
- Flag which, when set to @code{#t}, will make cgit display remote
- branches in the summary and refs views.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{repository-cgit-configuration} parameter} maybe-repo-boolean enable-subject-links?
- A flag which can be used to override the global setting
- @code{enable-subject-links?}.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{repository-cgit-configuration} parameter} maybe-repo-boolean enable-html-serving?
- A flag which can be used to override the global setting
- @code{enable-html-serving?}.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{repository-cgit-configuration} parameter} repo-boolean hide?
- Flag which, when set to @code{#t}, hides the repository from the
- repository index.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{repository-cgit-configuration} parameter} repo-boolean ignore?
- Flag which, when set to @samp{#t}, ignores the repository.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object logo
- URL which specifies the source of an image which will be used as a logo
- on this repo’s pages.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{repository-cgit-configuration} parameter} repo-string logo-link
- URL loaded when clicking on the cgit logo image.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object owner-filter
- Override the default @code{owner-filter}.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{repository-cgit-configuration} parameter} repo-string module-link
- Text which will be used as the formatstring for a hyperlink when a
- submodule is printed in a directory listing. The arguments for the
- formatstring are the path and SHA1 of the submodule commit.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{repository-cgit-configuration} parameter} module-link-path module-link-path
- Text which will be used as the formatstring for a hyperlink when a
- submodule with the specified subdirectory path is printed in a directory
- listing.
- Defaults to @samp{()}.
- @end deftypevr
- @deftypevr {@code{repository-cgit-configuration} parameter} repo-string max-stats
- Override the default maximum statistics period.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{repository-cgit-configuration} parameter} repo-string name
- The value to show as repository name.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{repository-cgit-configuration} parameter} repo-string owner
- A value used to identify the owner of the repository.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{repository-cgit-configuration} parameter} repo-string path
- An absolute path to the repository directory.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{repository-cgit-configuration} parameter} repo-string readme
- A path (relative to repo) which specifies a file to include verbatim as
- the ``About'' page for this repo.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{repository-cgit-configuration} parameter} repo-string section
- The name of the current repository section - all repositories defined
- after this option will inherit the current section name.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{repository-cgit-configuration} parameter} repo-list extra-options
- Extra options will be appended to cgitrc file.
- Defaults to @samp{()}.
- @end deftypevr
- @end deftypevr
- @deftypevr {@code{cgit-configuration} parameter} list extra-options
- Extra options will be appended to cgitrc file.
- Defaults to @samp{()}.
- @end deftypevr
- @c %end of fragment
- However, it could be that you just want to get a @code{cgitrc} up and
- running. In that case, you can pass an @code{opaque-cgit-configuration}
- as a record to @code{cgit-service-type}. As its name indicates, an
- opaque configuration does not have easy reflective capabilities.
- Available @code{opaque-cgit-configuration} fields are:
- @deftypevr {@code{opaque-cgit-configuration} parameter} package cgit
- The cgit package.
- @end deftypevr
- @deftypevr {@code{opaque-cgit-configuration} parameter} string string
- The contents of the @code{cgitrc}, as a string.
- @end deftypevr
- For example, if your @code{cgitrc} is just the empty string, you
- could instantiate a cgit service like this:
- @lisp
- (service cgit-service-type
- (opaque-cgit-configuration
- (cgitrc "")))
- @end lisp
- @subsubheading Gitolite Service
- @cindex Gitolite service
- @cindex Git, hosting
- @uref{https://gitolite.com/gitolite/, Gitolite} is a tool for hosting Git
- repositories on a central server.
- Gitolite can handle multiple repositories and users, and supports flexible
- configuration of the permissions for the users on the repositories.
- The following example will configure Gitolite using the default @code{git}
- user, and the provided SSH public key.
- @lisp
- (service gitolite-service-type
- (gitolite-configuration
- (admin-pubkey (plain-file
- "yourname.pub"
- "ssh-rsa AAAA... guix@@example.com"))))
- @end lisp
- Gitolite is configured through a special admin repository which you can clone,
- for example, if you setup Gitolite on @code{example.com}, you would run the
- following command to clone the admin repository.
- @example
- git clone git@@example.com:gitolite-admin
- @end example
- When the Gitolite service is activated, the provided @code{admin-pubkey} will
- be inserted in to the @file{keydir} directory in the gitolite-admin
- repository. If this results in a change in the repository, it will be
- committed using the message ``gitolite setup by GNU Guix''.
- @deftp {Data Type} gitolite-configuration
- Data type representing the configuration for @code{gitolite-service-type}.
- @table @asis
- @item @code{package} (default: @var{gitolite})
- Gitolite package to use.
- @item @code{user} (default: @var{git})
- User to use for Gitolite. This will be user that you use when accessing
- Gitolite over SSH.
- @item @code{group} (default: @var{git})
- Group to use for Gitolite.
- @item @code{home-directory} (default: @var{"/var/lib/gitolite"})
- Directory in which to store the Gitolite configuration and repositories.
- @item @code{rc-file} (default: @var{(gitolite-rc-file)})
- A ``file-like'' object (@pxref{G-Expressions, file-like objects}),
- representing the configuration for Gitolite.
- @item @code{admin-pubkey} (default: @var{#f})
- A ``file-like'' object (@pxref{G-Expressions, file-like objects}) used to
- setup Gitolite. This will be inserted in to the @file{keydir} directory
- within the gitolite-admin repository.
- To specify the SSH key as a string, use the @code{plain-file} function.
- @lisp
- (plain-file "yourname.pub" "ssh-rsa AAAA... guix@@example.com")
- @end lisp
- @end table
- @end deftp
- @deftp {Data Type} gitolite-rc-file
- Data type representing the Gitolite RC file.
- @table @asis
- @item @code{umask} (default: @code{#o0077})
- This controls the permissions Gitolite sets on the repositories and their
- contents.
- A value like @code{#o0027} will give read access to the group used by Gitolite
- (by default: @code{git}). This is necessary when using Gitolite with software
- like cgit or gitweb.
- @item @code{unsafe-pattern} (default: @code{#f})
- An optional Perl regular expression for catching unsafe configurations in
- the configuration file. See
- @uref{https://gitolite.com/gitolite/git-config.html#compensating-for-unsafe_patt,
- Gitolite's documentation} for more information.
- When the value is not @code{#f}, it should be a string containing a Perl
- regular expression, such as @samp{"[`~#\$\&()|;<>]"}, which is the default
- value used by gitolite. It rejects any special character in configuration
- that might be interpreted by a shell, which is useful when sharing the
- administration burden with other people that do not otherwise have shell
- access on the server.
- @item @code{git-config-keys} (default: @code{""})
- Gitolite allows you to set git config values using the @samp{config}
- keyword. This setting allows control over the config keys to accept.
- @item @code{roles} (default: @code{'(("READERS" . 1) ("WRITERS" . ))})
- Set the role names allowed to be used by users running the perms command.
- @item @code{enable} (default: @code{'("help" "desc" "info" "perms" "writable" "ssh-authkeys" "git-config" "daemon" "gitweb")})
- This setting controls the commands and features to enable within Gitolite.
- @end table
- @end deftp
- @subsubheading Gitile Service
- @cindex Gitile service
- @cindex Git, forge
- @uref{https://git.lepiller.eu/gitile, Gitile} is a Git forge for viewing
- public git repository contents from a web browser.
- Gitile works best in collaboration with Gitolite, and will serve the public
- repositories from Gitolite by default. The service should listen only on
- a local port, and a webserver should be configured to serve static resources.
- The gitile service provides an easy way to extend the Nginx service for
- that purpose (@pxref{NGINX}).
- The following example will configure Gitile to serve repositories from a
- custom location, with some default messages for the home page and the
- footers.
- @lisp
- (service gitile-service-type
- (gitile-configuration
- (repositories "/srv/git")
- (base-git-url "https://myweb.site/git")
- (index-title "My git repositories")
- (intro '((p "This is all my public work!")))
- (footer '((p "This is the end")))
- (nginx-server-block
- (nginx-server-configuration
- (ssl-certificate
- "/etc/letsencrypt/live/myweb.site/fullchain.pem")
- (ssl-certificate-key
- "/etc/letsencrypt/live/myweb.site/privkey.pem")
- (listen '("443 ssl http2" "[::]:443 ssl http2"))
- (locations
- (list
- ;; Allow for https anonymous fetch on /git/ urls.
- (git-http-nginx-location-configuration
- (git-http-configuration
- (uri-path "/git/")
- (git-root "/var/lib/gitolite/repositories")))))))))
- @end lisp
- In addition to the configuration record, you should configure your git
- repositories to contain some optional information. First, your public
- repositories need to contain the @file{git-daemon-export-ok} magic file
- that allows Git to export the repository. Gitile uses the presence of this
- file to detect public repositories it should make accessible. To do so with
- Gitolite for instance, modify your @file{conf/gitolite.conf} to include
- this in the repositories you want to make public:
- @example
- repo foo
- R = daemon
- @end example
- In addition, Gitile can read the repository configuration to display more
- information on the repository. Gitile uses the gitweb namespace for its
- configuration. As an example, you can use the following in your
- @file{conf/gitolite.conf}:
- @example
- repo foo
- R = daemon
- desc = A long description, optionally with <i>HTML</i>, shown on the index page
- config gitweb.name = The Foo Project
- config gitweb.synopsis = A short description, shown on the main page of the project
- @end example
- Do not forget to commit and push these changes once you are satisfied. You
- may need to change your gitolite configuration to allow the previous
- configuration options to be set. One way to do that is to add the
- following service definition:
- @lisp
- (service gitolite-service-type
- (gitolite-configuration
- (admin-pubkey (local-file "key.pub"))
- (rc-file
- (gitolite-rc-file
- (umask #o0027)
- ;; Allow to set any configuration key
- (git-config-keys ".*")
- ;; Allow any text as a valid configuration value
- (unsafe-patt "^$")))))
- @end lisp
- @deftp {Data Type} gitile-configuration
- Data type representing the configuration for @code{gitile-service-type}.
- @table @asis
- @item @code{package} (default: @var{gitile})
- Gitile package to use.
- @item @code{host} (default: @code{"localhost"})
- The host on which gitile is listening.
- @item @code{port} (default: @code{8080})
- The port on which gitile is listening.
- @item @code{database} (default: @code{"/var/lib/gitile/gitile-db.sql"})
- The location of the database.
- @item @code{repositories} (default: @code{"/var/lib/gitolite/repositories"})
- The location of the repositories. Note that only public repositories will
- be shown by Gitile. To make a repository public, add an empty
- @file{git-daemon-export-ok} file at the root of that repository.
- @item @code{base-git-url}
- The base git url that will be used to show clone commands.
- @item @code{index-title} (default: @code{"Index"})
- The page title for the index page that lists all the available repositories.
- @item @code{intro} (default: @code{'()})
- The intro content, as a list of sxml expressions. This is shown above the list
- of repositories, on the index page.
- @item @code{footer} (default: @code{'()})
- The footer content, as a list of sxml expressions. This is shown on every
- page served by Gitile.
- @item @code{nginx-server-block}
- An nginx server block that will be extended and used as a reverse proxy by
- Gitile to serve its pages, and as a normal web server to serve its assets.
- You can use this block to add more custom URLs to your domain, such as a
- @code{/git/} URL for anonymous clones, or serving any other files you would
- like to serve.
- @end table
- @end deftp
- @node Game Services
- @subsection Game Services
- @subsubheading The Battle for Wesnoth Service
- @cindex wesnothd
- @uref{https://wesnoth.org, The Battle for Wesnoth} is a fantasy, turn
- based tactical strategy game, with several single player campaigns, and
- multiplayer games (both networked and local).
- @defvar {Scheme Variable} wesnothd-service-type
- Service type for the wesnothd service. Its value must be a
- @code{wesnothd-configuration} object. To run wesnothd in the default
- configuration, instantiate it as:
- @lisp
- (service wesnothd-service-type)
- @end lisp
- @end defvar
- @deftp {Data Type} wesnothd-configuration
- Data type representing the configuration of @command{wesnothd}.
- @table @asis
- @item @code{package} (default: @code{wesnoth-server})
- The wesnoth server package to use.
- @item @code{port} (default: @code{15000})
- The port to bind the server to.
- @end table
- @end deftp
- @node PAM Mount Service
- @subsection PAM Mount Service
- @cindex pam-mount
- The @code{(gnu services pam-mount)} module provides a service allowing
- users to mount volumes when they log in. It should be able to mount any
- volume format supported by the system.
- @defvar {Scheme Variable} pam-mount-service-type
- Service type for PAM Mount support.
- @end defvar
- @deftp {Data Type} pam-mount-configuration
- Data type representing the configuration of PAM Mount.
- It takes the following parameters:
- @table @asis
- @item @code{rules}
- The configuration rules that will be used to generate
- @file{/etc/security/pam_mount.conf.xml}.
- The configuration rules are SXML elements (@pxref{SXML,,, guile, GNU
- Guile Reference Manual}), and the default ones don't mount anything for
- anyone at login:
- @lisp
- `((debug (@@ (enable "0")))
- (mntoptions (@@ (allow ,(string-join
- '("nosuid" "nodev" "loop"
- "encryption" "fsck" "nonempty"
- "allow_root" "allow_other")
- ","))))
- (mntoptions (@@ (require "nosuid,nodev")))
- (logout (@@ (wait "0")
- (hup "0")
- (term "no")
- (kill "no")))
- (mkmountpoint (@@ (enable "1")
- (remove "true"))))
- @end lisp
- Some @code{volume} elements must be added to automatically mount volumes
- at login. Here's an example allowing the user @code{alice} to mount her
- encrypted @env{HOME} directory and allowing the user @code{bob} to mount
- the partition where he stores his data:
- @lisp
- (define pam-mount-rules
- `((debug (@@ (enable "0")))
- (volume (@@ (user "alice")
- (fstype "crypt")
- (path "/dev/sda2")
- (mountpoint "/home/alice")))
- (volume (@@ (user "bob")
- (fstype "auto")
- (path "/dev/sdb3")
- (mountpoint "/home/bob/data")
- (options "defaults,autodefrag,compress")))
- (mntoptions (@@ (allow ,(string-join
- '("nosuid" "nodev" "loop"
- "encryption" "fsck" "nonempty"
- "allow_root" "allow_other")
- ","))))
- (mntoptions (@@ (require "nosuid,nodev")))
- (logout (@@ (wait "0")
- (hup "0")
- (term "no")
- (kill "no")))
- (mkmountpoint (@@ (enable "1")
- (remove "true")))))
- (service pam-mount-service-type
- (pam-mount-configuration
- (rules pam-mount-rules)))
- @end lisp
- The complete list of possible options can be found in the man page for
- @uref{http://pam-mount.sourceforge.net/pam_mount.conf.5.html, pam_mount.conf}.
- @end table
- @end deftp
- @node Guix Services
- @subsection Guix Services
- @subsubheading Guix Build Coordinator
- The @uref{https://git.cbaines.net/guix/build-coordinator/,Guix Build
- Coordinator} aids in distributing derivation builds among machines
- running an @dfn{agent}. The build daemon is still used to build the
- derivations, but the Guix Build Coordinator manages allocating builds
- and working with the results.
- The Guix Build Coordinator consists of one @dfn{coordinator}, and one or
- more connected @dfn{agent} processes. The coordinator process handles
- clients submitting builds, and allocating builds to agents. The agent
- processes talk to a build daemon to actually perform the builds, then
- send the results back to the coordinator.
- There is a script to run the coordinator component of the Guix Build
- Coordinator, but the Guix service uses a custom Guile script instead, to
- provide better integration with G-expressions used in the configuration.
- @defvar {Scheme Variable} guix-build-coordinator-service-type
- Service type for the Guix Build Coordinator. Its value must be a
- @code{guix-build-coordinator-configuration} object.
- @end defvar
- @deftp {Data Type} guix-build-coordinator-configuration
- Data type representing the configuration of the Guix Build Coordinator.
- @table @asis
- @item @code{package} (default: @code{guix-build-coordinator})
- The Guix Build Coordinator package to use.
- @item @code{user} (default: @code{"guix-build-coordinator"})
- The system user to run the service as.
- @item @code{group} (default: @code{"guix-build-coordinator"})
- The system group to run the service as.
- @item @code{database-uri-string} (default: @code{"sqlite:///var/lib/guix-build-coordinator/guix_build_coordinator.db"})
- The URI to use for the database.
- @item @code{agent-communication-uri} (default: @code{"http://0.0.0.0:8745"})
- The URI describing how to listen to requests from agent processes.
- @item @code{client-communication-uri} (default: @code{"http://127.0.0.1:8746"})
- The URI describing how to listen to requests from clients. The client
- API allows submitting builds and currently isn't authenticated, so take
- care when configuring this value.
- @item @code{allocation-strategy} (default: @code{#~basic-build-allocation-strategy})
- A G-expression for the allocation strategy to be used. This is a
- procedure that takes the datastore as an argument and populates the
- allocation plan in the database.
- @item @code{hooks} (default: @var{'()})
- An association list of hooks. These provide a way to execute arbitrary
- code upon certain events, like a build result being processed.
- @item @code{guile} (default: @code{guile-3.0-latest})
- The Guile package with which to run the Guix Build Coordinator.
- @end table
- @end deftp
- @defvar {Scheme Variable} guix-build-coordinator-agent-service-type
- Service type for a Guix Build Coordinator agent. Its value must be a
- @code{guix-build-coordinator-agent-configuration} object.
- @end defvar
- @deftp {Data Type} guix-build-coordinator-agent-configuration
- Data type representing the configuration a Guix Build Coordinator agent.
- @table @asis
- @item @code{package} (default: @code{guix-build-coordinator/agent-only})
- The Guix Build Coordinator package to use.
- @item @code{user} (default: @code{"guix-build-coordinator-agent"})
- The system user to run the service as.
- @item @code{coordinator} (default: @code{"http://localhost:8745"})
- The URI to use when connecting to the coordinator.
- @item @code{authentication}
- Record describing how this agent should authenticate with the
- coordinator. Possible record types are described below.
- @item @code{systems} (default: @code{#f})
- The systems for which this agent should fetch builds. The agent process
- will use the current system it's running on as the default.
- @item @code{max-parallel-builds} (default: @code{1})
- The number of builds to perform in parallel.
- @item @code{max-1min-load-average} (default: @code{#f})
- Load average value to look at when considering starting new builds, if
- the 1 minute load average exceeds this value, the agent will wait before
- starting new builds.
- This will be unspecified if the value is @code{#f}, and the agent will
- use the number of cores reported by the system as the max 1 minute load
- average.
- @item @code{derivation-substitute-urls} (default: @code{#f})
- URLs from which to attempt to fetch substitutes for derivations, if the
- derivations aren't already available.
- @item @code{non-derivation-substitute-urls} (default: @code{#f})
- URLs from which to attempt to fetch substitutes for build inputs, if the
- input store items aren't already available.
- @end table
- @end deftp
- @deftp {Data Type} guix-build-coordinator-agent-password-auth
- Data type representing an agent authenticating with a coordinator via a
- UUID and password.
- @table @asis
- @item @code{uuid}
- The UUID of the agent. This should be generated by the coordinator
- process, stored in the coordinator database, and used by the intended
- agent.
- @item @code{password}
- The password to use when connecting to the coordinator.
- @end table
- @end deftp
- @deftp {Data Type} guix-build-coordinator-agent-password-file-auth
- Data type representing an agent authenticating with a coordinator via a
- UUID and password read from a file.
- @table @asis
- @item @code{uuid}
- The UUID of the agent. This should be generated by the coordinator
- process, stored in the coordinator database, and used by the intended
- agent.
- @item @code{password-file}
- A file containing the password to use when connecting to the
- coordinator.
- @end table
- @end deftp
- @deftp {Data Type} guix-build-coordinator-agent-dynamic-auth
- Data type representing an agent authenticating with a coordinator via a
- dynamic auth token and agent name.
- @table @asis
- @item @code{agent-name}
- Name of an agent, this is used to match up to an existing entry in the
- database if there is one. When no existing entry is found, a new entry
- is automatically added.
- @item @code{token}
- Dynamic auth token, this is created and stored in the coordinator
- database, and is used by the agent to authenticate.
- @end table
- @end deftp
- @deftp {Data Type} guix-build-coordinator-agent-dynamic-auth-with-file
- Data type representing an agent authenticating with a coordinator via a
- dynamic auth token read from a file and agent name.
- @table @asis
- @item @code{agent-name}
- Name of an agent, this is used to match up to an existing entry in the
- database if there is one. When no existing entry is found, a new entry
- is automatically added.
- @item @code{token-file}
- File containing the dynamic auth token, this is created and stored in
- the coordinator database, and is used by the agent to authenticate.
- @end table
- @end deftp
- The Guix Build Coordinator package contains a script to query an
- instance of the Guix Data Service for derivations to build, and then
- submit builds for those derivations to the coordinator. The service
- type below assists in running this script. This is an additional tool
- that may be useful when building derivations contained within an
- instance of the Guix Data Service.
- @defvar {Scheme Variable} guix-build-coordinator-queue-builds-service-type
- Service type for the
- guix-build-coordinator-queue-builds-from-guix-data-service script. Its
- value must be a @code{guix-build-coordinator-queue-builds-configuration}
- object.
- @end defvar
- @deftp {Data Type} guix-build-coordinator-queue-builds-configuration
- Data type representing the options to the queue builds from guix data
- service script.
- @table @asis
- @item @code{package} (default: @code{guix-build-coordinator})
- The Guix Build Coordinator package to use.
- @item @code{user} (default: @code{"guix-build-coordinator-queue-builds"})
- The system user to run the service as.
- @item @code{coordinator} (default: @code{"http://localhost:8746"})
- The URI to use when connecting to the coordinator.
- @item @code{systems} (default: @code{#f})
- The systems for which to fetch derivations to build.
- @item @code{systems-and-targets} (default: @code{#f})
- An association list of system and target pairs for which to fetch
- derivations to build.
- @item @code{guix-data-service} (default: @code{"https://data.guix.gnu.org"})
- The Guix Data Service instance from which to query to find out about
- derivations to build.
- @item @code{processed-commits-file} (default: @code{"/var/cache/guix-build-coordinator-queue-builds/processed-commits"})
- A file to record which commits have been processed, to avoid needlessly
- processing them again if the service is restarted.
- @end table
- @end deftp
- @subsubheading Guix Data Service
- The @uref{http://data.guix.gnu.org,Guix Data Service} processes, stores
- and provides data about GNU Guix. This includes information about
- packages, derivations and lint warnings.
- The data is stored in a PostgreSQL database, and available through a web
- interface.
- @defvar {Scheme Variable} guix-data-service-type
- Service type for the Guix Data Service. Its value must be a
- @code{guix-data-service-configuration} object. The service optionally
- extends the getmail service, as the guix-commits mailing list is used to
- find out about changes in the Guix git repository.
- @end defvar
- @deftp {Data Type} guix-data-service-configuration
- Data type representing the configuration of the Guix Data Service.
- @table @asis
- @item @code{package} (default: @code{guix-data-service})
- The Guix Data Service package to use.
- @item @code{user} (default: @code{"guix-data-service"})
- The system user to run the service as.
- @item @code{group} (default: @code{"guix-data-service"})
- The system group to run the service as.
- @item @code{port} (default: @code{8765})
- The port to bind the web service to.
- @item @code{host} (default: @code{"127.0.0.1"})
- The host to bind the web service to.
- @item @code{getmail-idle-mailboxes} (default: @code{#f})
- If set, this is the list of mailboxes that the getmail service will be
- configured to listen to.
- @item @code{commits-getmail-retriever-configuration} (default: @code{#f})
- If set, this is the @code{getmail-retriever-configuration} object with
- which to configure getmail to fetch mail from the guix-commits mailing
- list.
- @item @code{extra-options} (default: @var{'()})
- Extra command line options for @code{guix-data-service}.
- @item @code{extra-process-jobs-options} (default: @var{'()})
- Extra command line options for @code{guix-data-service-process-jobs}.
- @end table
- @end deftp
- @subsubheading Nar Herder
- The @uref{https://git.cbaines.net/guix/nar-herder/about/,Nar Herder} is
- a utility for managing a collection of nars.
- @defvar {Scheme Variable} nar-herder-type
- Service type for the Guix Data Service. Its value must be a
- @code{nar-herder-configuration} object. The service optionally
- extends the getmail service, as the guix-commits mailing list is used to
- find out about changes in the Guix git repository.
- @end defvar
- @deftp {Data Type} nar-herder-configuration
- Data type representing the configuration of the Guix Data Service.
- @table @asis
- @item @code{package} (default: @code{nar-herder})
- The Nar Herder package to use.
- @item @code{user} (default: @code{"nar-herder"})
- The system user to run the service as.
- @item @code{group} (default: @code{"nar-herder"})
- The system group to run the service as.
- @item @code{port} (default: @code{8734})
- The port to bind the server to.
- @item @code{host} (default: @code{"127.0.0.1"})
- The host to bind the server to.
- @item @code{mirror} (default: @code{#f})
- Optional URL of the other Nar Herder instance which should be mirrored.
- This means that this Nar Herder instance will download it's database,
- and keep it up to date.
- @item @code{database} (default: @code{"/var/lib/nar-herder/nar_herder.db"})
- Location for the database. If this Nar Herder instance is mirroring
- another, the database will be downloaded if it doesn't exist. If this
- Nar Herder instance isn't mirroring another, an empty database will be
- created.
- @item @code{database-dump} (default: @code{"/var/lib/nar-herder/nar_herder_dump.db"})
- Location of the database dump. This is created and regularly updated by
- taking a copy of the database. This is the version of the database that
- is available to download.
- @item @code{storage} (default: @code{#f})
- Optional location in which to store nars.
- @item @code{storage-limit} (default: @code{"none"})
- Limit in bytes for the nars stored in the storage location. This can
- also be set to ``none'' so that there is no limit.
- When the storage location exceeds this size, nars are removed according
- to the nar removal criteria.
- @item @code{storage-nar-removal-criteria} (default: @code{'()})
- Criteria used to remove nars from the storage location. These are used
- in conjunction with the storage limit.
- When the storage location exceeds the storage limit size, nars will be
- checked against the nar removal criteria and if any of the criteria
- match, they will be removed. This will continue until the storage
- location is below the storage limit size.
- Each criteria is specified by a string, then an equals sign, then
- another string. Currently, only one criteria is supported, checking if a
- nar is stored on another Nar Herder instance.
- @item @code{ttl} (default: @code{#f})
- Produce @code{Cache-Control} HTTP headers that advertise a time-to-live
- (TTL) of @var{ttl}. @var{ttl} must denote a duration: @code{5d} means 5
- days, @code{1m} means 1 month, and so on.
- This allows the user's Guix to keep substitute information in cache for
- @var{ttl}.
- @item @code{negative-ttl} (default: @code{#f})
- Similarly produce @code{Cache-Control} HTTP headers to advertise the
- time-to-live (TTL) of @emph{negative} lookups---missing store items, for
- which the HTTP 404 code is returned. By default, no negative TTL is
- advertised.
- @end table
- @end deftp
- @node Linux Services
- @subsection Linux Services
- @cindex oom
- @cindex out of memory killer
- @cindex earlyoom
- @cindex early out of memory daemon
- @subsubheading Early OOM Service
- @uref{https://github.com/rfjakob/earlyoom,Early OOM}, also known as
- Earlyoom, is a minimalist out of memory (OOM) daemon that runs in user
- space and provides a more responsive and configurable alternative to the
- in-kernel OOM killer. It is useful to prevent the system from becoming
- unresponsive when it runs out of memory.
- @deffn {Scheme Variable} earlyoom-service-type
- The service type for running @command{earlyoom}, the Early OOM daemon.
- Its value must be a @code{earlyoom-configuration} object, described
- below. The service can be instantiated in its default configuration
- with:
- @lisp
- (service earlyoom-service-type)
- @end lisp
- @end deffn
- @deftp {Data Type} earlyoom-configuration
- This is the configuration record for the @code{earlyoom-service-type}.
- @table @asis
- @item @code{earlyoom} (default: @var{earlyoom})
- The Earlyoom package to use.
- @item @code{minimum-available-memory} (default: @code{10})
- The threshold for the minimum @emph{available} memory, in percentages.
- @item @code{minimum-free-swap} (default: @code{10})
- The threshold for the minimum free swap memory, in percentages.
- @item @code{prefer-regexp} (default: @code{#f})
- A regular expression (as a string) to match the names of the processes
- that should be preferably killed.
- @item @code{avoid-regexp} (default: @code{#f})
- A regular expression (as a string) to match the names of the processes
- that should @emph{not} be killed.
- @item @code{memory-report-interval} (default: @code{0})
- The interval in seconds at which a memory report is printed. It is
- disabled by default.
- @item @code{ignore-positive-oom-score-adj?} (default: @code{#f})
- A boolean indicating whether the positive adjustments set in
- @file{/proc/*/oom_score_adj} should be ignored.
- @item @code{show-debug-messages?} (default: @code{#f})
- A boolean indicating whether debug messages should be printed. The logs
- are saved at @file{/var/log/earlyoom.log}.
- @item @code{send-notification-command} (default: @code{#f})
- This can be used to provide a custom command used for sending
- notifications.
- @end table
- @end deftp
- @cindex modprobe
- @cindex kernel module loader
- @subsubheading Kernel Module Loader Service
- The kernel module loader service allows one to load loadable kernel
- modules at boot. This is especially useful for modules that don't
- autoload and need to be manually loaded, as is the case with
- @code{ddcci}.
- @deffn {Scheme Variable} kernel-module-loader-service-type
- The service type for loading loadable kernel modules at boot with
- @command{modprobe}. Its value must be a list of strings representing
- module names. For example loading the drivers provided by
- @code{ddcci-driver-linux}, in debugging mode by passing some module
- parameters, can be done as follow:
- @lisp
- (use-modules (gnu) (gnu services))
- (use-package-modules linux)
- (use-service-modules linux)
- (define ddcci-config
- (plain-file "ddcci.conf"
- "options ddcci dyndbg delay=120"))
- (operating-system
- ...
- (services (cons* (service kernel-module-loader-service-type
- '("ddcci" "ddcci_backlight"))
- (simple-service 'ddcci-config etc-service-type
- (list `("modprobe.d/ddcci.conf"
- ,ddcci-config)))
- %base-services))
- (kernel-loadable-modules (list ddcci-driver-linux)))
- @end lisp
- @end deffn
- @cindex rasdaemon
- @cindex Platform Reliability, Availability and Serviceability daemon
- @subsubheading Rasdaemon Service
- The Rasdaemon service provides a daemon which monitors platform
- @acronym{RAS, Reliability@comma{} Availability@comma{} and Serviceability} reports from
- Linux kernel trace events, logging them to syslogd.
- Reliability, Availability and Serviceability is a concept used on servers meant
- to measure their robustness.
- @strong{Relability} is the probability that a system will produce correct
- outputs:
- @itemize @bullet
- @item Generally measured as Mean Time Between Failures (MTBF), and
- @item Enhanced by features that help to avoid, detect and repair hardware
- faults
- @end itemize
- @strong{Availability} is the probability that a system is operational at a
- given time:
- @itemize @bullet
- @item Generally measured as a percentage of downtime per a period of time, and
- @item Often uses mechanisms to detect and correct hardware faults in runtime.
- @end itemize
- @strong{Serviceability} is the simplicity and speed with which a system can be
- repaired or maintained:
- @itemize @bullet
- @item Generally measured on Mean Time Between Repair (MTBR).
- @end itemize
- Among the monitoring measures, the most usual ones include:
- @itemize @bullet
- @item CPU – detect errors at instruction execution and at L1/L2/L3 caches;
- @item Memory – add error correction logic (ECC) to detect and correct errors;
- @item I/O – add CRC checksums for transferred data;
- @item Storage – RAID, journal file systems, checksums, Self-Monitoring,
- Analysis and Reporting Technology (SMART).
- @end itemize
- By monitoring the number of occurrences of error detections, it is possible to
- identify if the probability of hardware errors is increasing, and, on such
- case, do a preventive maintenance to replace a degraded component while those
- errors are correctable.
- For detailed information about the types of error events gathered and how to
- make sense of them, see the kernel administrator's guide at
- @url{https://www.kernel.org/doc/html/latest/admin-guide/ras.html}.
- @defvr {Scheme Variable} rasdaemon-service-type
- Service type for the @command{rasdaemon} service. It accepts a
- @code{rasdaemon-configuration} object. Instantiating like
- @lisp
- (service rasdaemon-service-type)
- @end lisp
- will load with a default configuration, which monitors all events and logs to
- syslogd.
- @end defvr
- @deftp {Data Type} rasdaemon-configuration
- The data type representing the configuration of @command{rasdaemon}.
- @table @asis
- @item @code{record?} (default: @code{#f})
- A boolean indicating whether to record the events in an SQLite database. This
- provides a more structured access to the information contained in the log file.
- The database location is hard-coded to @file{/var/lib/rasdaemon/ras-mc_event.db}.
- @end table
- @end deftp
- @cindex zram
- @cindex compressed swap
- @cindex Compressed RAM-based block devices
- @subsubheading Zram Device Service
- The Zram device service provides a compressed swap device in system
- memory. The Linux Kernel documentation has more information about
- @uref{https://www.kernel.org/doc/html/latest/admin-guide/blockdev/zram.html,zram}
- devices.
- @deffn {Scheme Variable} zram-device-service-type
- This service creates the zram block device, formats it as swap and
- enables it as a swap device. The service's value is a
- @code{zram-device-configuration} record.
- @deftp {Data Type} zram-device-configuration
- This is the data type representing the configuration for the zram-device
- service.
- @table @asis
- @item @code{size} (default @code{"1G"})
- This is the amount of space you wish to provide for the zram device. It
- accepts a string and can be a number of bytes or use a suffix, eg.:
- @code{"512M"} or @code{1024000}.
- @item @code{compression-algorithm} (default @code{'lzo})
- This is the compression algorithm you wish to use. It is difficult to
- list all the possible compression options, but common ones supported by
- Guix's Linux Libre Kernel include @code{'lzo}, @code{'lz4} and @code{'zstd}.
- @item @code{memory-limit} (default @code{0})
- This is the maximum amount of memory which the zram device can use.
- Setting it to '0' disables the limit. While it is generally expected
- that compression will be 2:1, it is possible that uncompressable data
- can be written to swap and this is a method to limit how much memory can
- be used. It accepts a string and can be a number of bytes or use a
- suffix, eg.: @code{"2G"}.
- @item @code{priority} (default @code{-1})
- This is the priority of the swap device created from the zram device.
- @code{swapon} accepts values between -1 and 32767, with higher values
- indicating higher priority. Higher priority swap will generally be used
- first.
- @end table
- @end deftp
- @end deffn
- @node Hurd Services
- @subsection Hurd Services
- @defvr {Scheme Variable} hurd-console-service-type
- This service starts the fancy @code{VGA} console client on the Hurd.
- The service's value is a @code{hurd-console-configuration} record.
- @end defvr
- @deftp {Data Type} hurd-console-configuration
- This is the data type representing the configuration for the
- hurd-console-service.
- @table @asis
- @item @code{hurd} (default: @var{hurd})
- The Hurd package to use.
- @end table
- @end deftp
- @defvr {Scheme Variable} hurd-getty-service-type
- This service starts a tty using the Hurd @code{getty} program.
- The service's value is a @code{hurd-getty-configuration} record.
- @end defvr
- @deftp {Data Type} hurd-getty-configuration
- This is the data type representing the configuration for the
- hurd-getty-service.
- @table @asis
- @item @code{hurd} (default: @var{hurd})
- The Hurd package to use.
- @item @code{tty}
- The name of the console this Getty runs on---e.g., @code{"tty1"}.
- @item @code{baud-rate} (default: @code{38400})
- An integer specifying the baud rate of the tty.
- @end table
- @end deftp
- @node Miscellaneous Services
- @subsection Miscellaneous Services
- @cindex fingerprint
- @subsubheading Fingerprint Service
- The @code{(gnu services authentication)} module provides a DBus service to
- read and identify fingerprints via a fingerprint sensor.
- @defvr {Scheme Variable} fprintd-service-type
- The service type for @command{fprintd}, which provides the fingerprint
- reading capability.
- @lisp
- (service fprintd-service-type)
- @end lisp
- @end defvr
- @cindex sysctl
- @subsubheading System Control Service
- The @code{(gnu services sysctl)} provides a service to configure kernel
- parameters at boot.
- @defvr {Scheme Variable} sysctl-service-type
- The service type for @command{sysctl}, which modifies kernel parameters
- under @file{/proc/sys/}. To enable IPv4 forwarding, it can be
- instantiated as:
- @lisp
- (service sysctl-service-type
- (sysctl-configuration
- (settings '(("net.ipv4.ip_forward" . "1")))))
- @end lisp
- Since @code{sysctl-service-type} is used in the default lists of
- services, @code{%base-services} and @code{%desktop-services}, you can
- use @code{modify-services} to change its configuration and add the
- kernel parameters that you want (@pxref{Service Reference,
- @code{modify-services}}).
- @lisp
- (modify-services %base-services
- (sysctl-service-type config =>
- (sysctl-configuration
- (settings (append '(("net.ipv4.ip_forward" . "1"))
- %default-sysctl-settings)))))
- @end lisp
- @end defvr
- @deftp {Data Type} sysctl-configuration
- The data type representing the configuration of @command{sysctl}.
- @table @asis
- @item @code{sysctl} (default: @code{(file-append procps "/sbin/sysctl"})
- The @command{sysctl} executable to use.
- @item @code{settings} (default: @code{%default-sysctl-settings})
- An association list specifies kernel parameters and their values.
- @end table
- @end deftp
- @defvr {Scheme Variable} %default-sysctl-settings
- An association list specifying the default @command{sysctl} parameters
- on Guix System.
- @end defvr
- @cindex pcscd
- @subsubheading PC/SC Smart Card Daemon Service
- The @code{(gnu services security-token)} module provides the following service
- to run @command{pcscd}, the PC/SC Smart Card Daemon. @command{pcscd} is the
- daemon program for pcsc-lite and the MuscleCard framework. It is a resource
- manager that coordinates communications with smart card readers, smart cards
- and cryptographic tokens that are connected to the system.
- @defvr {Scheme Variable} pcscd-service-type
- Service type for the @command{pcscd} service. Its value must be a
- @code{pcscd-configuration} object. To run pcscd in the default
- configuration, instantiate it as:
- @lisp
- (service pcscd-service-type)
- @end lisp
- @end defvr
- @deftp {Data Type} pcscd-configuration
- The data type representing the configuration of @command{pcscd}.
- @table @asis
- @item @code{pcsc-lite} (default: @code{pcsc-lite})
- The pcsc-lite package that provides pcscd.
- @item @code{usb-drivers} (default: @code{(list ccid)})
- List of packages that provide USB drivers to pcscd. Drivers are expected to be
- under @file{pcsc/drivers} in the store directory of the package.
- @end table
- @end deftp
- @cindex lirc
- @subsubheading Lirc Service
- The @code{(gnu services lirc)} module provides the following service.
- @deffn {Scheme Procedure} lirc-service [#:lirc lirc] @
- [#:device #f] [#:driver #f] [#:config-file #f] @
- [#:extra-options '()]
- Return a service that runs @url{http://www.lirc.org,LIRC}, a daemon that
- decodes infrared signals from remote controls.
- Optionally, @var{device}, @var{driver} and @var{config-file}
- (configuration file name) may be specified. See @command{lircd} manual
- for details.
- Finally, @var{extra-options} is a list of additional command-line options
- passed to @command{lircd}.
- @end deffn
- @cindex spice
- @subsubheading Spice Service
- The @code{(gnu services spice)} module provides the following service.
- @deffn {Scheme Procedure} spice-vdagent-service [#:spice-vdagent]
- Returns a service that runs @url{https://www.spice-space.org,VDAGENT}, a daemon
- that enables sharing the clipboard with a vm and setting the guest display
- resolution when the graphical console window resizes.
- @end deffn
- @cindex inputattach
- @subsubheading inputattach Service
- @cindex tablet input, for Xorg
- @cindex touchscreen input, for Xorg
- The @uref{https://linuxwacom.github.io/, inputattach} service allows you to
- use input devices such as Wacom tablets, touchscreens, or joysticks with the
- Xorg display server.
- @deffn {Scheme Variable} inputattach-service-type
- Type of a service that runs @command{inputattach} on a device and
- dispatches events from it.
- @end deffn
- @deftp {Data Type} inputattach-configuration
- @table @asis
- @item @code{device-type} (default: @code{"wacom"})
- The type of device to connect to. Run @command{inputattach --help}, from the
- @code{inputattach} package, to see the list of supported device types.
- @item @code{device} (default: @code{"/dev/ttyS0"})
- The device file to connect to the device.
- @item @code{baud-rate} (default: @code{#f})
- Baud rate to use for the serial connection.
- Should be a number or @code{#f}.
- @item @code{log-file} (default: @code{#f})
- If true, this must be the name of a file to log messages to.
- @end table
- @end deftp
- @subsubheading Dictionary Service
- @cindex dictionary
- The @code{(gnu services dict)} module provides the following service:
- @defvr {Scheme Variable} dicod-service-type
- This is the type of the service that runs the @command{dicod} daemon, an
- implementation of DICT server (@pxref{Dicod,,, dico, GNU Dico Manual}).
- @end defvr
- @deffn {Scheme Procedure} dicod-service [#:config (dicod-configuration)]
- Return a service that runs the @command{dicod} daemon, an implementation
- of DICT server (@pxref{Dicod,,, dico, GNU Dico Manual}).
- The optional @var{config} argument specifies the configuration for
- @command{dicod}, which should be a @code{<dicod-configuration>} object, by
- default it serves the GNU Collaborative International Dictionary of English.
- You can add @command{open localhost} to your @file{~/.dico} file to make
- @code{localhost} the default server for @command{dico} client
- (@pxref{Initialization File,,, dico, GNU Dico Manual}).
- @end deffn
- @deftp {Data Type} dicod-configuration
- Data type representing the configuration of dicod.
- @table @asis
- @item @code{dico} (default: @var{dico})
- Package object of the GNU Dico dictionary server.
- @item @code{interfaces} (default: @var{'("localhost")})
- This is the list of IP addresses and ports and possibly socket file
- names to listen to (@pxref{Server Settings, @code{listen} directive,,
- dico, GNU Dico Manual}).
- @item @code{handlers} (default: @var{'()})
- List of @code{<dicod-handler>} objects denoting handlers (module instances).
- @item @code{databases} (default: @var{(list %dicod-database:gcide)})
- List of @code{<dicod-database>} objects denoting dictionaries to be served.
- @end table
- @end deftp
- @deftp {Data Type} dicod-handler
- Data type representing a dictionary handler (module instance).
- @table @asis
- @item @code{name}
- Name of the handler (module instance).
- @item @code{module} (default: @var{#f})
- Name of the dicod module of the handler (instance). If it is @code{#f},
- the module has the same name as the handler.
- (@pxref{Modules,,, dico, GNU Dico Manual}).
- @item @code{options}
- List of strings or gexps representing the arguments for the module handler
- @end table
- @end deftp
- @deftp {Data Type} dicod-database
- Data type representing a dictionary database.
- @table @asis
- @item @code{name}
- Name of the database, will be used in DICT commands.
- @item @code{handler}
- Name of the dicod handler (module instance) used by this database
- (@pxref{Handlers,,, dico, GNU Dico Manual}).
- @item @code{complex?} (default: @var{#f})
- Whether the database configuration complex. The complex configuration
- will need a corresponding @code{<dicod-handler>} object, otherwise not.
- @item @code{options}
- List of strings or gexps representing the arguments for the database
- (@pxref{Databases,,, dico, GNU Dico Manual}).
- @end table
- @end deftp
- @defvr {Scheme Variable} %dicod-database:gcide
- A @code{<dicod-database>} object serving the GNU Collaborative International
- Dictionary of English using the @code{gcide} package.
- @end defvr
- The following is an example @code{dicod-service} configuration.
- @lisp
- (dicod-service #:config
- (dicod-configuration
- (handlers (list (dicod-handler
- (name "wordnet")
- (module "dictorg")
- (options
- (list #~(string-append "dbdir=" #$wordnet))))))
- (databases (list (dicod-database
- (name "wordnet")
- (complex? #t)
- (handler "wordnet")
- (options '("database=wn")))
- %dicod-database:gcide))))
- @end lisp
- @cindex Docker
- @subsubheading Docker Service
- The @code{(gnu services docker)} module provides the following services.
- @defvr {Scheme Variable} docker-service-type
- This is the type of the service that runs @url{https://www.docker.com,Docker},
- a daemon that can execute application bundles (sometimes referred to as
- ``containers'') in isolated environments.
- @end defvr
- @deftp {Data Type} docker-configuration
- This is the data type representing the configuration of Docker and Containerd.
- @table @asis
- @item @code{docker} (default: @code{docker})
- The Docker daemon package to use.
- @item @code{docker-cli} (default: @code{docker-cli})
- The Docker client package to use.
- @item @code{containerd} (default: @var{containerd})
- The Containerd package to use.
- @item @code{proxy} (default @var{docker-libnetwork-cmd-proxy})
- The Docker user-land networking proxy package to use.
- @item @code{enable-proxy?} (default @code{#t})
- Enable or disable the use of the Docker user-land networking proxy.
- @item @code{debug?} (default @code{#f})
- Enable or disable debug output.
- @item @code{enable-iptables?} (default @code{#t})
- Enable or disable the addition of iptables rules.
- @item @code{environment-variables} (default: @code{()})
- List of environment variables to set for @command{dockerd}.
- This must be a list of strings where each string has the form
- @samp{@var{key}=@var{value}} as in this example:
- @lisp
- (list "LANGUAGE=eo:ca:eu"
- "TMPDIR=/tmp/dockerd")
- @end lisp
- @end table
- @end deftp
- @cindex Singularity, container service
- @defvr {Scheme Variable} singularity-service-type
- This is the type of the service that allows you to run
- @url{https://www.sylabs.io/singularity/, Singularity}, a Docker-style tool to
- create and run application bundles (aka. ``containers''). The value for this
- service is the Singularity package to use.
- The service does not install a daemon; instead, it installs helper programs as
- setuid-root (@pxref{Setuid Programs}) such that unprivileged users can invoke
- @command{singularity run} and similar commands.
- @end defvr
- @cindex Audit
- @subsubheading Auditd Service
- The @code{(gnu services auditd)} module provides the following service.
- @defvr {Scheme Variable} auditd-service-type
- This is the type of the service that runs
- @url{https://people.redhat.com/sgrubb/audit/,auditd},
- a daemon that tracks security-relevant information on your system.
- Examples of things that can be tracked:
- @enumerate
- @item
- File accesses
- @item
- System calls
- @item
- Invoked commands
- @item
- Failed login attempts
- @item
- Firewall filtering
- @item
- Network access
- @end enumerate
- @command{auditctl} from the @code{audit} package can be used in order
- to add or remove events to be tracked (until the next reboot).
- In order to permanently track events, put the command line arguments
- of auditctl into a file called @code{audit.rules} in the configuration
- directory (see below).
- @command{aureport} from the @code{audit} package can be used in order
- to view a report of all recorded events.
- The audit daemon by default logs into the file
- @file{/var/log/audit.log}.
- @end defvr
- @deftp {Data Type} auditd-configuration
- This is the data type representing the configuration of auditd.
- @table @asis
- @item @code{audit} (default: @code{audit})
- The audit package to use.
- @item @code{configuration-directory} (default: @code{%default-auditd-configuration-directory})
- The directory containing the configuration file for the audit package, which
- must be named @code{auditd.conf}, and optionally some audit rules to
- instantiate on startup.
- @end table
- @end deftp
- @cindex rshiny
- @subsubheading R-Shiny service
- The @code{(gnu services science)} module provides the following service.
- @defvr {Scheme Variable} rshiny-service-type
- This is a type of service which is used to run a webapp created with
- @code{r-shiny}. This service sets the @env{R_LIBS_USER} environment
- variable and runs the provided script to call @code{runApp}.
- @deftp {Data Type} rshiny-configuration
- This is the data type representing the configuration of rshiny.
- @table @asis
- @item @code{package} (default: @code{r-shiny})
- The package to use.
- @item @code{binary} (defaunlt @code{"rshiny"})
- The name of the binary or shell script located at @code{package/bin/} to
- run when the service is run.
- The common way to create this file is as follows:
- @lisp
- @dots{}
- (let* ((out (assoc-ref %outputs "out"))
- (targetdir (string-append out "/share/" ,name))
- (app (string-append out "/bin/" ,name))
- (Rbin (search-input-file %build-inputs "/bin/Rscript")))
- ;; @dots{}
- (mkdir-p (string-append out "/bin"))
- (call-with-output-file app
- (lambda (port)
- (format port
- "#!~a
- library(shiny)
- setwd(\"~a\")
- runApp(launch.browser=0, port=4202)~%\n"
- Rbin targetdir))))
- @end lisp
- @end table
- @end deftp
- @end defvr
- @cindex Nix
- @subsubheading Nix service
- The @code{(gnu services nix)} module provides the following service.
- @defvr {Scheme Variable} nix-service-type
- This is the type of the service that runs build daemon of the
- @url{https://nixos.org/nix/, Nix} package manager. Here is an example showing
- how to use it:
- @lisp
- (use-modules (gnu))
- (use-service-modules nix)
- (use-package-modules package-management)
- (operating-system
- ;; @dots{}
- (packages (append (list nix)
- %base-packages))
- (services (append (list (service nix-service-type))
- %base-services)))
- @end lisp
- After @command{guix system reconfigure} configure Nix for your user:
- @itemize
- @item Add a Nix channel and update it. See
- @url{https://nixos.org/nix/manual/, Nix Package Manager Guide}.
- @item Create a symlink to your profile and activate Nix profile:
- @end itemize
- @example
- $ ln -s "/nix/var/nix/profiles/per-user/$USER/profile" ~/.nix-profile
- $ source /run/current-system/profile/etc/profile.d/nix.sh
- @end example
- @end defvr
- @deftp {Data Type} nix-configuration
- This data type represents the configuration of the Nix daemon.
- @table @asis
- @item @code{nix} (default: @code{nix})
- The Nix package to use.
- @item @code{sandbox} (default: @code{#t})
- Specifies whether builds are sandboxed by default.
- @item @code{build-sandbox-items} (default: @code{'()})
- This is a list of strings or objects appended to the
- @code{build-sandbox-items} field of the configuration file.
- @item @code{extra-config} (default: @code{'()})
- This is a list of strings or objects appended to the configuration file.
- It is used to pass extra text to be added verbatim to the configuration
- file.
- @item @code{extra-options} (default: @code{'()})
- Extra command line options for @code{nix-service-type}.
- @end table
- @end deftp
- @node Setuid Programs
- @section Setuid Programs
- @cindex setuid programs
- Some programs need to run with ``root'' privileges, even when they are
- launched by unprivileged users. A notorious example is the
- @command{passwd} program, which users can run to change their
- password, and which needs to access the @file{/etc/passwd} and
- @file{/etc/shadow} files---something normally restricted to root, for
- obvious security reasons. To address that, these executables are
- @dfn{setuid-root}, meaning that they always run with root privileges
- (@pxref{How Change Persona,,, libc, The GNU C Library Reference Manual},
- for more info about the setuid mechanism).
- The store itself @emph{cannot} contain setuid programs: that would be a
- security issue since any user on the system can write derivations that
- populate the store (@pxref{The Store}). Thus, a different mechanism is
- used: instead of changing the setuid bit directly on files that are in
- the store, we let the system administrator @emph{declare} which programs
- should be setuid root.
- The @code{setuid-programs} field of an @code{operating-system}
- declaration contains a list of @code{<setuid-program>} denoting the
- names of programs to have a setuid or setgid bit set (@pxref{Using the
- Configuration System}). For instance, the @command{mount.nfs} program,
- which is part of the nfs-utils package, with a setuid root can be
- designated like this:
- @lisp
- (setuid-program
- (program (file-append nfs-utils "/sbin/mount.nfs")))
- @end lisp
- And then, to make @command{mount.nfs} setuid on your system, add the
- previous example to your operating system declaration by appending it to
- @code{%setuid-programs} like this:
- @lisp
- (operating-system
- ;; Some fields omitted...
- (setuid-programs
- (append (list (setuid-program
- (program (file-append nfs-utils "/sbin/mount.nfs"))))
- %setuid-programs)))
- @end lisp
- @deftp {Data Type} setuid-program
- This data type represents a program with a setuid or setgid bit set.
- @table @asis
- @item @code{program}
- A file-like object having its setuid and/or setgid bit set.
- @item @code{setuid?} (default: @code{#t})
- Whether to set user setuid bit.
- @item @code{setgid?} (default: @code{#f})
- Whether to set group setgid bit.
- @item @code{user} (default: @code{0})
- UID (integer) or user name (string) for the user owner of the program,
- defaults to root.
- @item @code{group} (default: @code{0})
- GID (integer) goup name (string) for the group owner of the program,
- defaults to root.
- @end table
- @end deftp
- A default set of setuid programs is defined by the
- @code{%setuid-programs} variable of the @code{(gnu system)} module.
- @defvr {Scheme Variable} %setuid-programs
- A list of @code{<setuid-program>} denoting common programs that are
- setuid-root.
- The list includes commands such as @command{passwd}, @command{ping},
- @command{su}, and @command{sudo}.
- @end defvr
- Under the hood, the actual setuid programs are created in the
- @file{/run/setuid-programs} directory at system activation time. The
- files in this directory refer to the ``real'' binaries, which are in the
- store.
- @node X.509 Certificates
- @section X.509 Certificates
- @cindex HTTPS, certificates
- @cindex X.509 certificates
- @cindex TLS
- Web servers available over HTTPS (that is, HTTP over the transport-layer
- security mechanism, TLS) send client programs an @dfn{X.509 certificate}
- that the client can then use to @emph{authenticate} the server. To do
- that, clients verify that the server's certificate is signed by a
- so-called @dfn{certificate authority} (CA). But to verify the CA's
- signature, clients must have first acquired the CA's certificate.
- Web browsers such as GNU@tie{}IceCat include their own set of CA
- certificates, such that they are able to verify CA signatures
- out-of-the-box.
- However, most other programs that can talk HTTPS---@command{wget},
- @command{git}, @command{w3m}, etc.---need to be told where CA
- certificates can be found.
- @cindex @code{nss-certs}
- In Guix, this is done by adding a package that provides certificates
- to the @code{packages} field of the @code{operating-system} declaration
- (@pxref{operating-system Reference}). Guix includes one such package,
- @code{nss-certs}, which is a set of CA certificates provided as part of
- Mozilla's Network Security Services.
- Note that it is @emph{not} part of @code{%base-packages}, so you need to
- explicitly add it. The @file{/etc/ssl/certs} directory, which is where
- most applications and libraries look for certificates by default, points
- to the certificates installed globally.
- Unprivileged users, including users of Guix on a foreign distro,
- can also install their own certificate package in
- their profile. A number of environment variables need to be defined so
- that applications and libraries know where to find them. Namely, the
- OpenSSL library honors the @env{SSL_CERT_DIR} and @env{SSL_CERT_FILE}
- variables. Some applications add their own environment variables; for
- instance, the Git version control system honors the certificate bundle
- pointed to by the @env{GIT_SSL_CAINFO} environment variable. Thus, you
- would typically run something like:
- @example
- guix install nss-certs
- export SSL_CERT_DIR="$HOME/.guix-profile/etc/ssl/certs"
- export SSL_CERT_FILE="$HOME/.guix-profile/etc/ssl/certs/ca-certificates.crt"
- export GIT_SSL_CAINFO="$SSL_CERT_FILE"
- @end example
- As another example, R requires the @env{CURL_CA_BUNDLE} environment
- variable to point to a certificate bundle, so you would have to run
- something like this:
- @example
- guix install nss-certs
- export CURL_CA_BUNDLE="$HOME/.guix-profile/etc/ssl/certs/ca-certificates.crt"
- @end example
- For other applications you may want to look up the required environment
- variable in the relevant documentation.
- @node Name Service Switch
- @section Name Service Switch
- @cindex name service switch
- @cindex NSS
- The @code{(gnu system nss)} module provides bindings to the
- configuration file of the libc @dfn{name service switch} or @dfn{NSS}
- (@pxref{NSS Configuration File,,, libc, The GNU C Library Reference
- Manual}). In a nutshell, the NSS is a mechanism that allows libc to be
- extended with new ``name'' lookup methods for system databases, which
- includes host names, service names, user accounts, and more (@pxref{Name
- Service Switch, System Databases and Name Service Switch,, libc, The GNU
- C Library Reference Manual}).
- The NSS configuration specifies, for each system database, which lookup
- method is to be used, and how the various methods are chained
- together---for instance, under which circumstances NSS should try the
- next method in the list. The NSS configuration is given in the
- @code{name-service-switch} field of @code{operating-system} declarations
- (@pxref{operating-system Reference, @code{name-service-switch}}).
- @cindex nss-mdns
- @cindex .local, host name lookup
- As an example, the declaration below configures the NSS to use the
- @uref{https://0pointer.de/lennart/projects/nss-mdns/, @code{nss-mdns}
- back-end}, which supports host name lookups over multicast DNS (mDNS)
- for host names ending in @code{.local}:
- @lisp
- (name-service-switch
- (hosts (list %files ;first, check /etc/hosts
- ;; If the above did not succeed, try
- ;; with 'mdns_minimal'.
- (name-service
- (name "mdns_minimal")
- ;; 'mdns_minimal' is authoritative for
- ;; '.local'. When it returns "not found",
- ;; no need to try the next methods.
- (reaction (lookup-specification
- (not-found => return))))
- ;; Then fall back to DNS.
- (name-service
- (name "dns"))
- ;; Finally, try with the "full" 'mdns'.
- (name-service
- (name "mdns")))))
- @end lisp
- Do not worry: the @code{%mdns-host-lookup-nss} variable (see below)
- contains this configuration, so you will not have to type it if all you
- want is to have @code{.local} host lookup working.
- Note that, in this case, in addition to setting the
- @code{name-service-switch} of the @code{operating-system} declaration,
- you also need to use @code{avahi-service-type} (@pxref{Networking Services,
- @code{avahi-service-type}}), or @code{%desktop-services}, which includes it
- (@pxref{Desktop Services}). Doing this makes @code{nss-mdns} accessible
- to the name service cache daemon (@pxref{Base Services,
- @code{nscd-service}}).
- For convenience, the following variables provide typical NSS
- configurations.
- @defvr {Scheme Variable} %default-nss
- This is the default name service switch configuration, a
- @code{name-service-switch} object.
- @end defvr
- @defvr {Scheme Variable} %mdns-host-lookup-nss
- This is the name service switch configuration with support for host name
- lookup over multicast DNS (mDNS) for host names ending in @code{.local}.
- @end defvr
- The reference for name service switch configuration is given below. It
- is a direct mapping of the configuration file format of the C library , so
- please refer to the C library manual for more information (@pxref{NSS
- Configuration File,,, libc, The GNU C Library Reference Manual}).
- Compared to the configuration file format of libc NSS, it has the advantage
- not only of adding this warm parenthetic feel that we like, but also
- static checks: you will know about syntax errors and typos as soon as you
- run @command{guix system}.
- @deftp {Data Type} name-service-switch
- This is the data type representation the configuration of libc's name
- service switch (NSS). Each field below represents one of the supported
- system databases.
- @table @code
- @item aliases
- @itemx ethers
- @itemx group
- @itemx gshadow
- @itemx hosts
- @itemx initgroups
- @itemx netgroup
- @itemx networks
- @itemx password
- @itemx public-key
- @itemx rpc
- @itemx services
- @itemx shadow
- The system databases handled by the NSS@. Each of these fields must be a
- list of @code{<name-service>} objects (see below).
- @end table
- @end deftp
- @deftp {Data Type} name-service
- This is the data type representing an actual name service and the
- associated lookup action.
- @table @code
- @item name
- A string denoting the name service (@pxref{Services in the NSS
- configuration,,, libc, The GNU C Library Reference Manual}).
- Note that name services listed here must be visible to nscd. This is
- achieved by passing the @code{#:name-services} argument to
- @code{nscd-service} the list of packages providing the needed name
- services (@pxref{Base Services, @code{nscd-service}}).
- @item reaction
- An action specified using the @code{lookup-specification} macro
- (@pxref{Actions in the NSS configuration,,, libc, The GNU C Library
- Reference Manual}). For example:
- @lisp
- (lookup-specification (unavailable => continue)
- (success => return))
- @end lisp
- @end table
- @end deftp
- @node Initial RAM Disk
- @section Initial RAM Disk
- @cindex initrd
- @cindex initial RAM disk
- For bootstrapping purposes, the Linux-Libre kernel is passed an
- @dfn{initial RAM disk}, or @dfn{initrd}. An initrd contains a temporary
- root file system as well as an initialization script. The latter is
- responsible for mounting the real root file system, and for loading any
- kernel modules that may be needed to achieve that.
- The @code{initrd-modules} field of an @code{operating-system}
- declaration allows you to specify Linux-libre kernel modules that must
- be available in the initrd. In particular, this is where you would list
- modules needed to actually drive the hard disk where your root partition
- is---although the default value of @code{initrd-modules} should cover
- most use cases. For example, assuming you need the @code{megaraid_sas}
- module in addition to the default modules to be able to access your root
- file system, you would write:
- @lisp
- (operating-system
- ;; @dots{}
- (initrd-modules (cons "megaraid_sas" %base-initrd-modules)))
- @end lisp
- @defvr {Scheme Variable} %base-initrd-modules
- This is the list of kernel modules included in the initrd by default.
- @end defvr
- Furthermore, if you need lower-level customization, the @code{initrd}
- field of an @code{operating-system} declaration allows
- you to specify which initrd you would like to use. The @code{(gnu
- system linux-initrd)} module provides three ways to build an initrd: the
- high-level @code{base-initrd} procedure and the low-level
- @code{raw-initrd} and @code{expression->initrd} procedures.
- The @code{base-initrd} procedure is intended to cover most common uses.
- For example, if you want to add a bunch of kernel modules to be loaded
- at boot time, you can define the @code{initrd} field of the operating
- system declaration like this:
- @lisp
- (initrd (lambda (file-systems . rest)
- ;; Create a standard initrd but set up networking
- ;; with the parameters QEMU expects by default.
- (apply base-initrd file-systems
- #:qemu-networking? #t
- rest)))
- @end lisp
- The @code{base-initrd} procedure also handles common use cases that
- involves using the system as a QEMU guest, or as a ``live'' system with
- volatile root file system.
- The @code{base-initrd} procedure is built from @code{raw-initrd} procedure.
- Unlike @code{base-initrd}, @code{raw-initrd} doesn't do anything high-level,
- such as trying to guess which kernel modules and packages should be included
- to the initrd. An example use of @code{raw-initrd} is when a user has
- a custom Linux kernel configuration and default kernel modules included by
- @code{base-initrd} are not available.
- The initial RAM disk produced by @code{base-initrd} or @code{raw-initrd}
- honors several options passed on the Linux kernel command line
- (that is, arguments passed @i{via} the @code{linux} command of GRUB, or the
- @code{-append} option of QEMU), notably:
- @table @code
- @item gnu.load=@var{boot}
- Tell the initial RAM disk to load @var{boot}, a file containing a Scheme
- program, once it has mounted the root file system.
- Guix uses this option to yield control to a boot program that runs the
- service activation programs and then spawns the GNU@tie{}Shepherd, the
- initialization system.
- @item root=@var{root}
- Mount @var{root} as the root file system. @var{root} can be a device
- name like @code{/dev/sda1}, a file system label, or a file system UUID.
- When unspecified, the device name from the root file system of the
- operating system declaration is used.
- @item rootfstype=@var{type}
- Set the type of the root file system. It overrides the @code{type}
- field of the root file system specified via the @code{operating-system}
- declaration, if any.
- @item rootflags=@var{options}
- Set the mount @emph{options} of the root file system. It overrides the
- @code{options} field of the root file system specified via the
- @code{operating-system} declaration, if any.
- @item fsck.mode=@var{mode}
- Whether to check the @var{root} file system for errors before mounting
- it. @var{mode} is one of @code{skip} (never check), @code{force} (always
- check), or @code{auto} to respect the root file-system object's 'check?'
- setting (@pxref{File Systems}) and run a full scan only if the file system
- was not cleanly shut down.
- @code{auto} is the default if this option is not present or if @var{mode}
- is not one of the above.
- @item fsck.repair=@var{level}
- The level of repairs to perform automatically if errors are found in the
- @var{root} file system. @var{level} is one of @code{no} (do not write to
- @var{root} at all if possible), @code{yes} (repair as much as possible),
- or @code{preen} to repair problems considered safe to repair automatically.
- @code{preen} is the default if this option is not present or if @var{level}
- is not one of the above.
- @item gnu.system=@var{system}
- Have @file{/run/booted-system} and @file{/run/current-system} point to
- @var{system}.
- @item modprobe.blacklist=@var{modules}@dots{}
- @cindex module, black-listing
- @cindex black list, of kernel modules
- Instruct the initial RAM disk as well as the @command{modprobe} command
- (from the kmod package) to refuse to load @var{modules}. @var{modules}
- must be a comma-separated list of module names---e.g.,
- @code{usbkbd,9pnet}.
- @item gnu.repl
- Start a read-eval-print loop (REPL) from the initial RAM disk before it
- tries to load kernel modules and to mount the root file system. Our
- marketing team calls it @dfn{boot-to-Guile}. The Schemer in you will
- love it. @xref{Using Guile Interactively,,, guile, GNU Guile Reference
- Manual}, for more information on Guile's REPL.
- @end table
- Now that you know all the features that initial RAM disks produced by
- @code{base-initrd} and @code{raw-initrd} provide,
- here is how to use it and customize it further.
- @cindex initrd
- @cindex initial RAM disk
- @deffn {Scheme Procedure} raw-initrd @var{file-systems} @
- [#:linux-modules '()] [#:mapped-devices '()] @
- [#:keyboard-layout #f] @
- [#:helper-packages '()] [#:qemu-networking? #f] [#:volatile-root? #f]
- Return a derivation that builds a raw initrd. @var{file-systems} is
- a list of file systems to be mounted by the initrd, possibly in addition to
- the root file system specified on the kernel command line via @option{root}.
- @var{linux-modules} is a list of kernel modules to be loaded at boot time.
- @var{mapped-devices} is a list of device mappings to realize before
- @var{file-systems} are mounted (@pxref{Mapped Devices}).
- @var{helper-packages} is a list of packages to be copied in the initrd.
- It may
- include @code{e2fsck/static} or other packages needed by the initrd to check
- the root file system.
- When true, @var{keyboard-layout} is a @code{<keyboard-layout>} record denoting
- the desired console keyboard layout. This is done before @var{mapped-devices}
- are set up and before @var{file-systems} are mounted such that, should the
- user need to enter a passphrase or use the REPL, this happens using the
- intended keyboard layout.
- When @var{qemu-networking?} is true, set up networking with the standard QEMU
- parameters. When @var{virtio?} is true, load additional modules so that the
- initrd can be used as a QEMU guest with para-virtualized I/O drivers.
- When @var{volatile-root?} is true, the root file system is writable but any changes
- to it are lost.
- @end deffn
- @deffn {Scheme Procedure} base-initrd @var{file-systems} @
- [#:mapped-devices '()] [#:keyboard-layout #f] @
- [#:qemu-networking? #f] [#:volatile-root? #f] @
- [#:linux-modules '()]
- Return as a file-like object a generic initrd, with kernel
- modules taken from @var{linux}. @var{file-systems} is a list of file-systems to be
- mounted by the initrd, possibly in addition to the root file system specified
- on the kernel command line via @option{root}. @var{mapped-devices} is a list of device
- mappings to realize before @var{file-systems} are mounted.
- When true, @var{keyboard-layout} is a @code{<keyboard-layout>} record denoting
- the desired console keyboard layout. This is done before @var{mapped-devices}
- are set up and before @var{file-systems} are mounted such that, should the
- user need to enter a passphrase or use the REPL, this happens using the
- intended keyboard layout.
- @var{qemu-networking?} and @var{volatile-root?} behaves as in @code{raw-initrd}.
- The initrd is automatically populated with all the kernel modules necessary
- for @var{file-systems} and for the given options. Additional kernel
- modules can be listed in @var{linux-modules}. They will be added to the initrd, and
- loaded at boot time in the order in which they appear.
- @end deffn
- Needless to say, the initrds we produce and use embed a
- statically-linked Guile, and the initialization program is a Guile
- program. That gives a lot of flexibility. The
- @code{expression->initrd} procedure builds such an initrd, given the
- program to run in that initrd.
- @deffn {Scheme Procedure} expression->initrd @var{exp} @
- [#:guile %guile-static-stripped] [#:name "guile-initrd"]
- Return as a file-like object a Linux initrd (a gzipped cpio archive)
- containing @var{guile} and that evaluates @var{exp}, a G-expression,
- upon booting. All the derivations referenced by @var{exp} are
- automatically copied to the initrd.
- @end deffn
- @node Bootloader Configuration
- @section Bootloader Configuration
- @cindex bootloader
- @cindex boot loader
- The operating system supports multiple bootloaders. The bootloader is
- configured using @code{bootloader-configuration} declaration. All the
- fields of this structure are bootloader agnostic except for one field,
- @code{bootloader} that indicates the bootloader to be configured and
- installed.
- Some of the bootloaders do not honor every field of
- @code{bootloader-configuration}. For instance, the extlinux
- bootloader does not support themes and thus ignores the @code{theme}
- field.
- @deftp {Data Type} bootloader-configuration
- The type of a bootloader configuration declaration.
- @table @asis
- @item @code{bootloader}
- @cindex EFI, bootloader
- @cindex UEFI, bootloader
- @cindex BIOS, bootloader
- The bootloader to use, as a @code{bootloader} object. For now
- @code{grub-bootloader}, @code{grub-efi-bootloader},
- @code{grub-efi-netboot-bootloader}, @code{extlinux-bootloader} and
- @code{u-boot-bootloader} are supported.
- @cindex ARM, bootloaders
- @cindex AArch64, bootloaders
- Available bootloaders are described in @code{(gnu bootloader @dots{})}
- modules. In particular, @code{(gnu bootloader u-boot)} contains definitions
- of bootloaders for a wide range of ARM and AArch64 systems, using the
- @uref{https://www.denx.de/wiki/U-Boot/, U-Boot bootloader}.
- @vindex grub-efi-bootloader
- @code{grub-efi-bootloader} allows to boot on modern systems using the
- @dfn{Unified Extensible Firmware Interface} (UEFI). This is what you should
- use if the installation image contains a @file{/sys/firmware/efi} directory
- when you boot it on your system.
- @vindex grub-bootloader
- @code{grub-bootloader} allows you to boot in particular Intel-based machines
- in ``legacy'' BIOS mode.
- @vindex grub-efi-netboot-bootloader
- @code{grub-efi-netboot-bootloader} allows you to boot your system over network
- through TFTP@. In combination with an NFS root file system this allows you to
- build a diskless Guix system.
- The installation of the @code{grub-efi-netboot-bootloader} generates the
- content of the TFTP root directory at @code{targets} (@pxref{Bootloader
- Configuration, @code{targets}}), to be served by a TFTP server. You may
- want to mount your TFTP server directories onto the @code{targets} to
- move the required files to the TFTP server automatically.
- If you plan to use an NFS root file system as well (actually if you mount the
- store from an NFS share), then the TFTP server needs to serve the file
- @file{/boot/grub/grub.cfg} and other files from the store (like GRUBs background
- image, the kernel (@pxref{operating-system Reference, @code{kernel}}) and the
- initrd (@pxref{operating-system Reference, @code{initrd}})), too. All these
- files from the store will be accessed by GRUB through TFTP with their normal
- store path, for example as
- @file{tftp://tftp-server/gnu/store/…-initrd/initrd.cpio.gz}.
- Two symlinks are created to make this possible. For each target in the
- @code{targets} field, the first symlink is
- @samp{target}@file{/efi/Guix/boot/grub/grub.cfg} pointing to
- @file{../../../boot/grub/grub.cfg}, where @samp{target} may be
- @file{/boot}. In this case the link is not leaving the served TFTP root
- directory, but otherwise it does. The second link is
- @samp{target}@file{/gnu/store} and points to @file{../gnu/store}. This
- link is leaving the served TFTP root directory.
- The assumption behind all this is that you have an NFS server exporting
- the root file system for your Guix system, and additionally a TFTP
- server exporting your @code{targets} directories—usually a single
- @file{/boot}—from that same root file system for your Guix system. In
- this constellation the symlinks will work.
- For other constellations you will have to program your own bootloader
- installer, which then takes care to make necessary files from the store
- accessible through TFTP, for example by copying them into the TFTP root
- directory to your @code{targets}.
- It is important to note that symlinks pointing outside the TFTP root directory
- may need to be allowed in the configuration of your TFTP server. Further the
- store link exposes the whole store through TFTP@. Both points need to be
- considered carefully for security aspects.
- Beside the @code{grub-efi-netboot-bootloader}, the already mentioned TFTP and
- NFS servers, you also need a properly configured DHCP server to make the booting
- over netboot possible. For all this we can currently only recommend you to look
- for instructions about @acronym{PXE, Preboot eXecution Environment}.
- @item @code{targets}
- This is a list of strings denoting the targets onto which to install the
- bootloader.
- The interpretation of targets depends on the bootloader in question.
- For @code{grub-bootloader}, for example, they should be device names
- understood by the bootloader @command{installer} command, such as
- @code{/dev/sda} or @code{(hd0)} (@pxref{Invoking grub-install,,, grub,
- GNU GRUB Manual}). For @code{grub-efi-bootloader}, they should be mount
- points of the EFI file system, usually @file{/boot/efi}. For
- @code{grub-efi-netboot-bootloader}, @code{targets} should be the mount
- points corresponding to TFTP root directories served by your TFTP
- server.
- @item @code{menu-entries} (default: @code{()})
- A possibly empty list of @code{menu-entry} objects (see below), denoting
- entries to appear in the bootloader menu, in addition to the current
- system entry and the entry pointing to previous system generations.
- @item @code{default-entry} (default: @code{0})
- The index of the default boot menu entry. Index 0 is for the entry of the
- current system.
- @item @code{timeout} (default: @code{5})
- The number of seconds to wait for keyboard input before booting. Set to
- 0 to boot immediately, and to -1 to wait indefinitely.
- @cindex keyboard layout, for the bootloader
- @item @code{keyboard-layout} (default: @code{#f})
- If this is @code{#f}, the bootloader's menu (if any) uses the default keyboard
- layout, usually US@tie{}English (``qwerty'').
- Otherwise, this must be a @code{keyboard-layout} object (@pxref{Keyboard
- Layout}).
- @quotation Note
- This option is currently ignored by bootloaders other than @code{grub} and
- @code{grub-efi}.
- @end quotation
- @item @code{theme} (default: @var{#f})
- The bootloader theme object describing the theme to use. If no theme
- is provided, some bootloaders might use a default theme, that's true
- for GRUB.
- @item @code{terminal-outputs} (default: @code{'(gfxterm)})
- The output terminals used for the bootloader boot menu, as a list of
- symbols. GRUB accepts the values: @code{console}, @code{serial},
- @code{serial_@{0-3@}}, @code{gfxterm}, @code{vga_text},
- @code{mda_text}, @code{morse}, and @code{pkmodem}. This field
- corresponds to the GRUB variable @code{GRUB_TERMINAL_OUTPUT} (@pxref{Simple
- configuration,,, grub,GNU GRUB manual}).
- @item @code{terminal-inputs} (default: @code{'()})
- The input terminals used for the bootloader boot menu, as a list of
- symbols. For GRUB, the default is the native platform terminal as
- determined at run-time. GRUB accepts the values: @code{console},
- @code{serial}, @code{serial_@{0-3@}}, @code{at_keyboard}, and
- @code{usb_keyboard}. This field corresponds to the GRUB variable
- @code{GRUB_TERMINAL_INPUT} (@pxref{Simple configuration,,, grub,GNU GRUB
- manual}).
- @item @code{serial-unit} (default: @code{#f})
- The serial unit used by the bootloader, as an integer from 0 to 3.
- For GRUB, it is chosen at run-time; currently GRUB chooses 0, which
- corresponds to COM1 (@pxref{Serial terminal,,, grub,GNU GRUB manual}).
- @item @code{serial-speed} (default: @code{#f})
- The speed of the serial interface, as an integer. For GRUB, the
- default value is chosen at run-time; currently GRUB chooses
- 9600@tie{}bps (@pxref{Serial terminal,,, grub,GNU GRUB manual}).
- @end table
- @end deftp
- @cindex dual boot
- @cindex boot menu
- Should you want to list additional boot menu entries @i{via} the
- @code{menu-entries} field above, you will need to create them with the
- @code{menu-entry} form. For example, imagine you want to be able to
- boot another distro (hard to imagine!), you can define a menu entry
- along these lines:
- @lisp
- (menu-entry
- (label "The Other Distro")
- (linux "/boot/old/vmlinux-2.6.32")
- (linux-arguments '("root=/dev/sda2"))
- (initrd "/boot/old/initrd"))
- @end lisp
- Details below.
- @deftp {Data Type} menu-entry
- The type of an entry in the bootloader menu.
- @table @asis
- @item @code{label}
- The label to show in the menu---e.g., @code{"GNU"}.
- @item @code{linux} (default: @code{#f})
- The Linux kernel image to boot, for example:
- @lisp
- (file-append linux-libre "/bzImage")
- @end lisp
- For GRUB, it is also possible to specify a device explicitly in the
- file path using GRUB's device naming convention (@pxref{Naming
- convention,,, grub, GNU GRUB manual}), for example:
- @example
- "(hd0,msdos1)/boot/vmlinuz"
- @end example
- If the device is specified explicitly as above, then the @code{device}
- field is ignored entirely.
- @item @code{linux-arguments} (default: @code{()})
- The list of extra Linux kernel command-line arguments---e.g.,
- @code{("console=ttyS0")}.
- @item @code{initrd} (default: @code{#f})
- A G-Expression or string denoting the file name of the initial RAM disk
- to use (@pxref{G-Expressions}).
- @item @code{device} (default: @code{#f})
- The device where the kernel and initrd are to be found---i.e., for GRUB,
- @dfn{root} for this menu entry (@pxref{root,,, grub, GNU GRUB manual}).
- This may be a file system label (a string), a file system UUID (a
- bytevector, @pxref{File Systems}), or @code{#f}, in which case
- the bootloader will search the device containing the file specified by
- the @code{linux} field (@pxref{search,,, grub, GNU GRUB manual}). It
- must @emph{not} be an OS device name such as @file{/dev/sda1}.
- @item @code{multiboot-kernel} (default: @code{#f})
- The kernel to boot in Multiboot-mode (@pxref{multiboot,,, grub, GNU GRUB
- manual}). When this field is set, a Multiboot menu-entry is generated.
- For example:
- @lisp
- (file-append mach "/boot/gnumach")
- @end lisp
- @item @code{multiboot-arguments} (default: @code{()})
- The list of extra command-line arguments for the multiboot-kernel.
- @item @code{multiboot-modules} (default: @code{()})
- The list of commands for loading Multiboot modules. For example:
- @lisp
- (list (list (file-append hurd "/hurd/ext2fs.static") "ext2fs"
- @dots{})
- (list (file-append libc "/lib/ld.so.1") "exec"
- @dots{}))
- @end lisp
- @end table
- @end deftp
- @cindex HDPI
- @cindex HiDPI
- @cindex resolution
- @c FIXME: Write documentation once it's stable.
- For now only GRUB has theme support. GRUB themes are created using
- the @code{grub-theme} form, which is not fully documented yet.
- @deftp {Data Type} grub-theme
- Data type representing the configuration of the GRUB theme.
- @table @asis
- @item @code{gfxmode} (default: @code{'("auto")})
- The GRUB @code{gfxmode} to set (a list of screen resolution strings,
- @pxref{gfxmode,,, grub, GNU GRUB manual}).
- @end table
- @end deftp
- @deffn {Scheme Procedure} grub-theme
- Return the default GRUB theme used by the operating system if no
- @code{theme} field is specified in @code{bootloader-configuration}
- record.
- It comes with a fancy background image displaying the GNU and Guix
- logos.
- @end deffn
- For example, to override the default resolution, you may use something
- like
- @lisp
- (bootloader
- (bootloader-configuration
- ;; @dots{}
- (theme (grub-theme
- (inherit (grub-theme))
- (gfxmode '("1024x786x32" "auto"))))))
- @end lisp
- @node Invoking guix system
- @section Invoking @code{guix system}
- Once you have written an operating system declaration as seen in the
- previous section, it can be @dfn{instantiated} using the @command{guix
- system} command. The synopsis is:
- @example
- guix system @var{options}@dots{} @var{action} @var{file}
- @end example
- @var{file} must be the name of a file containing an
- @code{operating-system} declaration. @var{action} specifies how the
- operating system is instantiated. Currently the following values are
- supported:
- @table @code
- @item search
- Display available service type definitions that match the given regular
- expressions, sorted by relevance:
- @cindex HDPI
- @cindex HiDPI
- @cindex resolution
- @example
- $ guix system search console
- name: console-fonts
- location: gnu/services/base.scm:806:2
- extends: shepherd-root
- description: Install the given fonts on the specified ttys (fonts are per
- + virtual console on GNU/Linux). The value of this service is a list of
- + tty/font pairs. The font can be the name of a font provided by the `kbd'
- + package or any valid argument to `setfont', as in this example:
- +
- + '(("tty1" . "LatGrkCyr-8x16")
- + ("tty2" . (file-append
- + font-tamzen
- + "/share/kbd/consolefonts/TamzenForPowerline10x20.psf"))
- + ("tty3" . (file-append
- + font-terminus
- + "/share/consolefonts/ter-132n"))) ; for HDPI
- relevance: 9
- name: mingetty
- location: gnu/services/base.scm:1190:2
- extends: shepherd-root
- description: Provide console login using the `mingetty' program.
- relevance: 2
- name: login
- location: gnu/services/base.scm:860:2
- extends: pam
- description: Provide a console log-in service as specified by its
- + configuration value, a `login-configuration' object.
- relevance: 2
- @dots{}
- @end example
- As for @command{guix package --search}, the result is written in
- @code{recutils} format, which makes it easy to filter the output
- (@pxref{Top, GNU recutils databases,, recutils, GNU recutils manual}).
- @item reconfigure
- Build the operating system described in @var{file}, activate it, and
- switch to it@footnote{This action (and the related actions
- @code{switch-generation} and @code{roll-back}) are usable only on
- systems already running Guix System.}.
- @quotation Note
- @c The paragraph below refers to the problem discussed at
- @c <https://lists.gnu.org/archive/html/guix-devel/2014-08/msg00057.html>.
- It is highly recommended to run @command{guix pull} once before you run
- @command{guix system reconfigure} for the first time (@pxref{Invoking
- guix pull}). Failing to do that you would see an older version of Guix
- once @command{reconfigure} has completed.
- @end quotation
- This effects all the configuration specified in @var{file}: user
- accounts, system services, global package list, setuid programs, etc.
- The command starts system services specified in @var{file} that are not
- currently running; if a service is currently running this command will
- arrange for it to be upgraded the next time it is stopped (e.g.@: by
- @code{herd stop X} or @code{herd restart X}).
- This command creates a new generation whose number is one greater than
- the current generation (as reported by @command{guix system
- list-generations}). If that generation already exists, it will be
- overwritten. This behavior mirrors that of @command{guix package}
- (@pxref{Invoking guix package}).
- It also adds a bootloader menu entry for the new OS configuration,
- ---unless @option{--no-bootloader} is passed. For GRUB, it moves
- entries for older configurations to a submenu, allowing you to choose
- an older system generation at boot time should you need it.
- @cindex provenance tracking, of the operating system
- Upon completion, the new system is deployed under
- @file{/run/current-system}. This directory contains @dfn{provenance
- meta-data}: the list of channels in use (@pxref{Channels}) and
- @var{file} itself, when available. You can view it by running:
- @example
- guix system describe
- @end example
- This information is useful should you later want to inspect how this
- particular generation was built. In fact, assuming @var{file} is
- self-contained, you can later rebuild generation @var{n} of your
- operating system with:
- @example
- guix time-machine \
- -C /var/guix/profiles/system-@var{n}-link/channels.scm -- \
- system reconfigure \
- /var/guix/profiles/system-@var{n}-link/configuration.scm
- @end example
- You can think of it as some sort of built-in version control! Your
- system is not just a binary artifact: @emph{it carries its own source}.
- @xref{Service Reference, @code{provenance-service-type}}, for more
- information on provenance tracking.
- By default, @command{reconfigure} @emph{prevents you from downgrading
- your system}, which could (re)introduce security vulnerabilities and
- also cause problems with ``stateful'' services such as database
- management systems. You can override that behavior by passing
- @option{--allow-downgrades}.
- @item switch-generation
- @cindex generations
- Switch to an existing system generation. This action atomically
- switches the system profile to the specified system generation. It
- also rearranges the system's existing bootloader menu entries. It
- makes the menu entry for the specified system generation the default,
- and it moves the entries for the other generations to a submenu, if
- supported by the bootloader being used. The next time the system
- boots, it will use the specified system generation.
- The bootloader itself is not being reinstalled when using this
- command. Thus, the installed bootloader is used with an updated
- configuration file.
- The target generation can be specified explicitly by its generation
- number. For example, the following invocation would switch to system
- generation 7:
- @example
- guix system switch-generation 7
- @end example
- The target generation can also be specified relative to the current
- generation with the form @code{+N} or @code{-N}, where @code{+3} means
- ``3 generations ahead of the current generation,'' and @code{-1} means
- ``1 generation prior to the current generation.'' When specifying a
- negative value such as @code{-1}, you must precede it with @code{--} to
- prevent it from being parsed as an option. For example:
- @example
- guix system switch-generation -- -1
- @end example
- Currently, the effect of invoking this action is @emph{only} to switch
- the system profile to an existing generation and rearrange the
- bootloader menu entries. To actually start using the target system
- generation, you must reboot after running this action. In the future,
- it will be updated to do the same things as @command{reconfigure},
- like activating and deactivating services.
- This action will fail if the specified generation does not exist.
- @item roll-back
- @cindex rolling back
- Switch to the preceding system generation. The next time the system
- boots, it will use the preceding system generation. This is the inverse
- of @command{reconfigure}, and it is exactly the same as invoking
- @command{switch-generation} with an argument of @code{-1}.
- Currently, as with @command{switch-generation}, you must reboot after
- running this action to actually start using the preceding system
- generation.
- @item delete-generations
- @cindex deleting system generations
- @cindex saving space
- Delete system generations, making them candidates for garbage collection
- (@pxref{Invoking guix gc}, for information on how to run the ``garbage
- collector'').
- This works in the same way as @samp{guix package --delete-generations}
- (@pxref{Invoking guix package, @option{--delete-generations}}). With no
- arguments, all system generations but the current one are deleted:
- @example
- guix system delete-generations
- @end example
- You can also select the generations you want to delete. The example below
- deletes all the system generations that are more than two months old:
- @example
- guix system delete-generations 2m
- @end example
- Running this command automatically reinstalls the bootloader with an updated
- list of menu entries---e.g., the ``old generations'' sub-menu in GRUB no
- longer lists the generations that have been deleted.
- @item build
- Build the derivation of the operating system, which includes all the
- configuration files and programs needed to boot and run the system.
- This action does not actually install anything.
- @item init
- Populate the given directory with all the files necessary to run the
- operating system specified in @var{file}. This is useful for first-time
- installations of Guix System. For instance:
- @example
- guix system init my-os-config.scm /mnt
- @end example
- copies to @file{/mnt} all the store items required by the configuration
- specified in @file{my-os-config.scm}. This includes configuration
- files, packages, and so on. It also creates other essential files
- needed for the system to operate correctly---e.g., the @file{/etc},
- @file{/var}, and @file{/run} directories, and the @file{/bin/sh} file.
- This command also installs bootloader on the targets specified in
- @file{my-os-config}, unless the @option{--no-bootloader} option was
- passed.
- @item vm
- @cindex virtual machine
- @cindex VM
- @anchor{guix system vm}
- Build a virtual machine (VM) that contains the operating system declared
- in @var{file}, and return a script to run that VM.
- @quotation Note
- The @code{vm} action and others below
- can use KVM support in the Linux-libre kernel. Specifically, if the
- machine has hardware virtualization support, the corresponding
- KVM kernel module should be loaded, and the @file{/dev/kvm} device node
- must exist and be readable and writable by the user and by the
- build users of the daemon (@pxref{Build Environment Setup}).
- @end quotation
- Arguments given to the script are passed to QEMU as in the example
- below, which enables networking and requests 1@tie{}GiB of RAM for the
- emulated machine:
- @example
- $ /gnu/store/@dots{}-run-vm.sh -m 1024 -smp 2 -nic user,model=virtio-net-pci
- @end example
- It's possible to combine the two steps into one:
- @example
- $ $(guix system vm my-config.scm) -m 1024 -smp 2 -nic user,model=virtio-net-pci
- @end example
- The VM shares its store with the host system.
- By default, the root file system of the VM is mounted volatile; the
- @option{--persistent} option can be provided to make it persistent
- instead. In that case, the VM disk-image file will be copied from the
- store to the @env{TMPDIR} directory to make it writable.
- Additional file systems can be shared between the host and the VM using
- the @option{--share} and @option{--expose} command-line options: the former
- specifies a directory to be shared with write access, while the latter
- provides read-only access to the shared directory.
- The example below creates a VM in which the user's home directory is
- accessible read-only, and where the @file{/exchange} directory is a
- read-write mapping of @file{$HOME/tmp} on the host:
- @example
- guix system vm my-config.scm \
- --expose=$HOME --share=$HOME/tmp=/exchange
- @end example
- On GNU/Linux, the default is to boot directly to the kernel; this has
- the advantage of requiring only a very tiny root disk image since the
- store of the host can then be mounted.
- The @option{--full-boot} option forces a complete boot sequence, starting
- with the bootloader. This requires more disk space since a root image
- containing at least the kernel, initrd, and bootloader data files must
- be created.
- The @option{--image-size} option can be used to specify the size of the
- image.
- The @option{--no-graphic} option will instruct @command{guix system} to
- spawn a headless VM that will use the invoking tty for IO. Among other
- things, this enables copy-pasting, and scrollback. Use the @kbd{ctrl-a}
- prefix to issue QEMU commands; e.g. @kbd{ctrl-a h} prints a help,
- @kbd{ctrl-a x} quits the VM, and @kbd{ctrl-a c} switches between the
- QEMU monitor and the VM.
- @cindex System images, creation in various formats
- @cindex Creating system images in various formats
- @item image
- @cindex image, creating disk images
- The @code{image} command can produce various image types. The image
- type can be selected using the @option{--image-type} option. It
- defaults to @code{efi-raw}. When its value is @code{iso9660}, the
- @option{--label} option can be used to specify a volume ID with
- @code{image}. By default, the root file system of a disk image is
- mounted non-volatile; the @option{--volatile} option can be provided to
- make it volatile instead. When using @code{image}, the bootloader
- installed on the generated image is taken from the provided
- @code{operating-system} definition. The following example demonstrates
- how to generate an image that uses the @code{grub-efi-bootloader}
- bootloader and boot it with QEMU:
- @example
- image=$(guix system image --image-type=qcow2 \
- gnu/system/examples/lightweight-desktop.tmpl)
- cp $image /tmp/my-image.qcow2
- chmod +w /tmp/my-image.qcow2
- qemu-system-x86_64 -enable-kvm -hda /tmp/my-image.qcow2 -m 1000 \
- -bios $(guix build ovmf)/share/firmware/ovmf_x64.bin
- @end example
- When using the @code{efi-raw} image type, a raw disk image is produced;
- it can be copied as is to a USB stick, for instance. Assuming
- @code{/dev/sdc} is the device corresponding to a USB stick, one can copy
- the image to it using the following command:
- @example
- # dd if=$(guix system image my-os.scm) of=/dev/sdc status=progress
- @end example
- The @code{--list-image-types} command lists all the available image
- types.
- @cindex creating virtual machine images
- When using the @code{qcow2} image type, the returned image is in qcow2
- format, which the QEMU emulator can efficiently use. @xref{Running Guix
- in a VM}, for more information on how to run the image in a virtual
- machine. The @code{grub-bootloader} bootloader is always used
- independently of what is declared in the @code{operating-system} file
- passed as argument. This is to make it easier to work with QEMU, which
- uses the SeaBIOS BIOS by default, expecting a bootloader to be installed
- in the Master Boot Record (MBR).
- @cindex docker-image, creating docker images
- When using the @code{docker} image type, a Docker image is produced.
- Guix builds the image from scratch, not from a pre-existing Docker base
- image. As a result, it contains @emph{exactly} what you define in the
- operating system configuration file. You can then load the image and
- launch a Docker container using commands like the following:
- @example
- image_id="$(docker load < guix-system-docker-image.tar.gz)"
- container_id="$(docker create $image_id)"
- docker start $container_id
- @end example
- This command starts a new Docker container from the specified image. It
- will boot the Guix system in the usual manner, which means it will
- start any services you have defined in the operating system
- configuration. You can get an interactive shell running in the container
- using @command{docker exec}:
- @example
- docker exec -ti $container_id /run/current-system/profile/bin/bash --login
- @end example
- Depending on what you run in the Docker container, it
- may be necessary to give the container additional permissions. For
- example, if you intend to build software using Guix inside of the Docker
- container, you may need to pass the @option{--privileged} option to
- @code{docker create}.
- Last, the @option{--network} option applies to @command{guix system
- docker-image}: it produces an image where network is supposedly shared
- with the host, and thus without services like nscd or NetworkManager.
- @item container
- Return a script to run the operating system declared in @var{file}
- within a container. Containers are a set of lightweight isolation
- mechanisms provided by the kernel Linux-libre. Containers are
- substantially less resource-demanding than full virtual machines since
- the kernel, shared objects, and other resources can be shared with the
- host system; this also means they provide thinner isolation.
- Currently, the script must be run as root in order to support more than
- a single user and group. The container shares its store with the host
- system.
- As with the @code{vm} action (@pxref{guix system vm}), additional file
- systems to be shared between the host and container can be specified
- using the @option{--share} and @option{--expose} options:
- @example
- guix system container my-config.scm \
- --expose=$HOME --share=$HOME/tmp=/exchange
- @end example
- @quotation Note
- This option requires Linux-libre 3.19 or newer.
- @end quotation
- @end table
- @var{options} can contain any of the common build options (@pxref{Common
- Build Options}). In addition, @var{options} can contain one of the
- following:
- @table @option
- @item --expression=@var{expr}
- @itemx -e @var{expr}
- Consider the operating-system @var{expr} evaluates to.
- This is an alternative to specifying a file which evaluates to an
- operating system.
- This is used to generate the Guix system installer @pxref{Building the
- Installation Image}).
- @item --system=@var{system}
- @itemx -s @var{system}
- Attempt to build for @var{system} instead of the host system type.
- This works as per @command{guix build} (@pxref{Invoking guix build}).
- @item --derivation
- @itemx -d
- Return the derivation file name of the given operating system without
- building anything.
- @cindex provenance tracking, of the operating system
- @item --save-provenance
- As discussed above, @command{guix system init} and @command{guix system
- reconfigure} always save provenance information @i{via} a dedicated
- service (@pxref{Service Reference, @code{provenance-service-type}}).
- However, other commands don't do that by default. If you wish to, say,
- create a virtual machine image that contains provenance information, you
- can run:
- @example
- guix system image -t qcow2 --save-provenance config.scm
- @end example
- That way, the resulting image will effectively ``embed its own source''
- in the form of meta-data in @file{/run/current-system}. With that
- information, one can rebuild the image to make sure it really contains
- what it pretends to contain; or they could use that to derive a variant
- of the image.
- @item --image-type=@var{type}
- @itemx -t @var{type}
- For the @code{image} action, create an image with given @var{type}.
- When this option is omitted, @command{guix system} uses the
- @code{efi-raw} image type.
- @cindex ISO-9660 format
- @cindex CD image format
- @cindex DVD image format
- @option{--image-type=iso9660} produces an ISO-9660 image, suitable
- for burning on CDs and DVDs.
- @item --image-size=@var{size}
- For the @code{image} action, create an image of the given @var{size}.
- @var{size} may be a number of bytes, or it may include a unit as a
- suffix (@pxref{Block size, size specifications,, coreutils, GNU
- Coreutils}).
- When this option is omitted, @command{guix system} computes an estimate
- of the image size as a function of the size of the system declared in
- @var{file}.
- @item --network
- @itemx -N
- For the @code{container} action, allow containers to access the host network,
- that is, do not create a network namespace.
- @item --root=@var{file}
- @itemx -r @var{file}
- Make @var{file} a symlink to the result, and register it as a garbage
- collector root.
- @item --skip-checks
- Skip pre-installation safety checks.
- By default, @command{guix system init} and @command{guix system
- reconfigure} perform safety checks: they make sure the file systems that
- appear in the @code{operating-system} declaration actually exist
- (@pxref{File Systems}), and that any Linux kernel modules that may be
- needed at boot time are listed in @code{initrd-modules} (@pxref{Initial
- RAM Disk}). Passing this option skips these tests altogether.
- @item --allow-downgrades
- Instruct @command{guix system reconfigure} to allow system downgrades.
- By default, @command{reconfigure} prevents you from downgrading your
- system. It achieves that by comparing the provenance info of your
- system (shown by @command{guix system describe}) with that of your
- @command{guix} command (shown by @command{guix describe}). If the
- commits for @command{guix} are not descendants of those used for your
- system, @command{guix system reconfigure} errors out. Passing
- @option{--allow-downgrades} allows you to bypass these checks.
- @quotation Note
- Make sure you understand its security implications before using
- @option{--allow-downgrades}.
- @end quotation
- @cindex on-error
- @cindex on-error strategy
- @cindex error strategy
- @item --on-error=@var{strategy}
- Apply @var{strategy} when an error occurs when reading @var{file}.
- @var{strategy} may be one of the following:
- @table @code
- @item nothing-special
- Report the error concisely and exit. This is the default strategy.
- @item backtrace
- Likewise, but also display a backtrace.
- @item debug
- Report the error and enter Guile's debugger. From there, you can run
- commands such as @code{,bt} to get a backtrace, @code{,locals} to
- display local variable values, and more generally inspect the state of the
- program. @xref{Debug Commands,,, guile, GNU Guile Reference Manual}, for
- a list of available debugging commands.
- @end table
- @end table
- Once you have built, configured, re-configured, and re-re-configured
- your Guix installation, you may find it useful to list the operating
- system generations available on disk---and that you can choose from the
- bootloader boot menu:
- @table @code
- @item describe
- Describe the running system generation: its file name, the kernel and
- bootloader used, etc., as well as provenance information when available.
- @quotation Note
- The @emph{running} system generation---referred to by
- @file{/run/current-system}---is not necessarily the @emph{current}
- system generation---referred to by @file{/var/guix/profiles/system}: it
- differs when, for instance, you chose from the bootloader menu to boot
- an older generation.
- It can also differ from the @emph{booted} system generation---referred
- to by @file{/run/booted-system}---for instance because you reconfigured
- the system in the meantime.
- @end quotation
- @item list-generations
- List a summary of each generation of the operating system available on
- disk, in a human-readable way. This is similar to the
- @option{--list-generations} option of @command{guix package}
- (@pxref{Invoking guix package}).
- Optionally, one can specify a pattern, with the same syntax that is used
- in @command{guix package --list-generations}, to restrict the list of
- generations displayed. For instance, the following command displays
- generations that are up to 10 days old:
- @example
- $ guix system list-generations 10d
- @end example
- @end table
- The @command{guix system} command has even more to offer! The following
- sub-commands allow you to visualize how your system services relate to
- each other:
- @anchor{system-extension-graph}
- @table @code
- @item extension-graph
- Emit to standard output the @dfn{service
- extension graph} of the operating system defined in @var{file}
- (@pxref{Service Composition}, for more information on service
- extensions). By default the output is in Dot/Graphviz format, but you
- can choose a different format with @option{--graph-backend}, as with
- @command{guix graph} (@pxref{Invoking guix graph, @option{--backend}}):
- The command:
- @example
- $ guix system extension-graph @var{file} | xdot -
- @end example
- shows the extension relations among services.
- @anchor{system-shepherd-graph}
- @item shepherd-graph
- Emit to standard output the @dfn{dependency
- graph} of shepherd services of the operating system defined in
- @var{file}. @xref{Shepherd Services}, for more information and for an
- example graph.
- Again, the default output format is Dot/Graphviz, but you can pass
- @option{--graph-backend} to select a different one.
- @end table
- @node Invoking guix deploy
- @section Invoking @code{guix deploy}
- We've already seen @code{operating-system} declarations used to manage a
- machine's configuration locally. Suppose you need to configure multiple
- machines, though---perhaps you're managing a service on the web that's
- comprised of several servers. @command{guix deploy} enables you to use those
- same @code{operating-system} declarations to manage multiple remote hosts at
- once as a logical ``deployment''.
- @quotation Note
- The functionality described in this section is still under development
- and is subject to change. Get in touch with us on
- @email{guix-devel@@gnu.org}!
- @end quotation
- @example
- guix deploy @var{file}
- @end example
- Such an invocation will deploy the machines that the code within @var{file}
- evaluates to. As an example, @var{file} might contain a definition like this:
- @lisp
- ;; This is a Guix deployment of a "bare bones" setup, with
- ;; no X11 display server, to a machine with an SSH daemon
- ;; listening on localhost:2222. A configuration such as this
- ;; may be appropriate for virtual machine with ports
- ;; forwarded to the host's loopback interface.
- (use-service-modules networking ssh)
- (use-package-modules bootloaders)
- (define %system
- (operating-system
- (host-name "gnu-deployed")
- (timezone "Etc/UTC")
- (bootloader (bootloader-configuration
- (bootloader grub-bootloader)
- (targets '("/dev/vda"))
- (terminal-outputs '(console))))
- (file-systems (cons (file-system
- (mount-point "/")
- (device "/dev/vda1")
- (type "ext4"))
- %base-file-systems))
- (services
- (append (list (service dhcp-client-service-type)
- (service openssh-service-type
- (openssh-configuration
- (permit-root-login #t)
- (allow-empty-passwords? #t))))
- %base-services))))
- (list (machine
- (operating-system %system)
- (environment managed-host-environment-type)
- (configuration (machine-ssh-configuration
- (host-name "localhost")
- (system "x86_64-linux")
- (user "alice")
- (identity "./id_rsa")
- (port 2222)))))
- @end lisp
- The file should evaluate to a list of @var{machine} objects. This example,
- upon being deployed, will create a new generation on the remote system
- realizing the @code{operating-system} declaration @code{%system}.
- @code{environment} and @code{configuration} specify how the machine should be
- provisioned---that is, how the computing resources should be created and
- managed. The above example does not create any resources, as a
- @code{'managed-host} is a machine that is already running the Guix system and
- available over the network. This is a particularly simple case; a more
- complex deployment may involve, for example, starting virtual machines through
- a Virtual Private Server (VPS) provider. In such a case, a different
- @var{environment} type would be used.
- Do note that you first need to generate a key pair on the coordinator machine
- to allow the daemon to export signed archives of files from the store
- (@pxref{Invoking guix archive}), though this step is automatic on Guix
- System:
- @example
- # guix archive --generate-key
- @end example
- @noindent
- Each target machine must authorize the key of the master machine so that it
- accepts store items it receives from the coordinator:
- @example
- # guix archive --authorize < coordinator-public-key.txt
- @end example
- @code{user}, in this example, specifies the name of the user account to log in
- as to perform the deployment. Its default value is @code{root}, but root
- login over SSH may be forbidden in some cases. To work around this,
- @command{guix deploy} can log in as an unprivileged user and employ
- @code{sudo} to escalate privileges. This will only work if @code{sudo} is
- currently installed on the remote and can be invoked non-interactively as
- @code{user}. That is, the line in @code{sudoers} granting @code{user} the
- ability to use @code{sudo} must contain the @code{NOPASSWD} tag. This can
- be accomplished with the following operating system configuration snippet:
- @lisp
- (use-modules ...
- (gnu system)) ;for %sudoers-specification
- (define %user "username")
- (operating-system
- ...
- (sudoers-file
- (plain-file "sudoers"
- (string-append (plain-file-content %sudoers-specification)
- (format #f "~a ALL = NOPASSWD: ALL~%"
- %user)))))
- @end lisp
- For more information regarding the format of the @file{sudoers} file,
- consult @command{man sudoers}.
- Once you've deployed a system on a set of machines, you may find it
- useful to run a command on all of them. The @option{--execute} or
- @option{-x} option lets you do that; the example below runs
- @command{uname -a} on all the machines listed in the deployment file:
- @example
- guix deploy @var{file} -x -- uname -a
- @end example
- One thing you may often need to do after deployment is restart specific
- services on all the machines, which you can do like so:
- @example
- guix deploy @var{file} -x -- herd restart @var{service}
- @end example
- The @command{guix deploy -x} command returns zero if and only if the
- command succeeded on all the machines.
- @c FIXME/TODO: Separate the API doc from the CLI doc.
- Below are the data types you need to know about when writing a
- deployment file.
- @deftp {Data Type} machine
- This is the data type representing a single machine in a heterogeneous Guix
- deployment.
- @table @asis
- @item @code{operating-system}
- The object of the operating system configuration to deploy.
- @item @code{environment}
- An @code{environment-type} describing how the machine should be provisioned.
- @item @code{configuration} (default: @code{#f})
- An object describing the configuration for the machine's @code{environment}.
- If the @code{environment} has a default configuration, @code{#f} may be used.
- If @code{#f} is used for an environment with no default configuration,
- however, an error will be thrown.
- @end table
- @end deftp
- @deftp {Data Type} machine-ssh-configuration
- This is the data type representing the SSH client parameters for a machine
- with an @code{environment} of @code{managed-host-environment-type}.
- @table @asis
- @item @code{host-name}
- @item @code{build-locally?} (default: @code{#t})
- If false, system derivations will be built on the machine being deployed to.
- @item @code{system}
- The system type describing the architecture of the machine being deployed
- to---e.g., @code{"x86_64-linux"}.
- @item @code{authorize?} (default: @code{#t})
- If true, the coordinator's signing key will be added to the remote's ACL
- keyring.
- @item @code{port} (default: @code{22})
- @item @code{user} (default: @code{"root"})
- @item @code{identity} (default: @code{#f})
- If specified, the path to the SSH private key to use to authenticate with the
- remote host.
- @item @code{host-key} (default: @code{#f})
- This should be the SSH host key of the machine, which looks like this:
- @example
- ssh-ed25519 AAAAC3Nz@dots{} root@@example.org
- @end example
- When @code{host-key} is @code{#f}, the server is authenticated against
- the @file{~/.ssh/known_hosts} file, just like the OpenSSH @command{ssh}
- client does.
- @item @code{allow-downgrades?} (default: @code{#f})
- Whether to allow potential downgrades.
- Like @command{guix system reconfigure}, @command{guix deploy} compares
- the channel commits currently deployed on the remote host (as returned
- by @command{guix system describe}) to those currently in use (as
- returned by @command{guix describe}) to determine whether commits
- currently in use are descendants of those deployed. When this is not
- the case and @code{allow-downgrades?} is false, it raises an error.
- This ensures you do not accidentally downgrade remote machines.
- @item @code{safety-checks?} (default: @code{#t})
- Whether to perform ``safety checks'' before deployment. This includes
- verifying that devices and file systems referred to in the operating
- system configuration actually exist on the target machine, and making
- sure that Linux modules required to access storage devices at boot time
- are listed in the @code{initrd-modules} field of the operating system.
- These safety checks ensure that you do not inadvertently deploy a system
- that would fail to boot. Be careful before turning them off!
- @end table
- @end deftp
- @deftp {Data Type} digital-ocean-configuration
- This is the data type describing the Droplet that should be created for a
- machine with an @code{environment} of @code{digital-ocean-environment-type}.
- @table @asis
- @item @code{ssh-key}
- The path to the SSH private key to use to authenticate with the remote
- host. In the future, this field may not exist.
- @item @code{tags}
- A list of string ``tags'' that uniquely identify the machine. Must be given
- such that no two machines in the deployment have the same set of tags.
- @item @code{region}
- A Digital Ocean region slug, such as @code{"nyc3"}.
- @item @code{size}
- A Digital Ocean size slug, such as @code{"s-1vcpu-1gb"}
- @item @code{enable-ipv6?}
- Whether or not the droplet should be created with IPv6 networking.
- @end table
- @end deftp
- @node Running Guix in a VM
- @section Running Guix in a Virtual Machine
- @cindex virtual machine
- To run Guix in a virtual machine (VM), one can use the pre-built Guix VM
- image distributed at
- @url{@value{BASE-URL}/guix-system-vm-image-@value{VERSION}.x86_64-linux.qcow2}.
- This image is a compressed image in QCOW format. You can pass it to an
- emulator such as @uref{https://qemu.org/, QEMU} (see below for details).
- This image boots the Xfce graphical environment and it contains some
- commonly used tools. You can install more software in the image by running
- @command{guix package} in a terminal (@pxref{Invoking guix package}). You can
- also reconfigure the system based on its initial configuration file available
- as @file{/run/current-system/configuration.scm} (@pxref{Using the
- Configuration System}).
- Instead of using this pre-built image, one can also build their own
- image using @command{guix system image} (@pxref{Invoking guix system}).
- @cindex QEMU
- If you built your own image, you must copy it out of the store
- (@pxref{The Store}) and give yourself permission to write to the copy
- before you can use it. When invoking QEMU, you must choose a system
- emulator that is suitable for your hardware platform. Here is a minimal
- QEMU invocation that will boot the result of @command{guix system
- image -t qcow2} on x86_64 hardware:
- @example
- $ qemu-system-x86_64 \
- -nic user,model=virtio-net-pci \
- -enable-kvm -m 1024 \
- -device virtio-blk,drive=myhd \
- -drive if=none,file=/tmp/qemu-image,id=myhd
- @end example
- Here is what each of these options means:
- @table @code
- @item qemu-system-x86_64
- This specifies the hardware platform to emulate. This should match the
- host.
- @item -nic user,model=virtio-net-pci
- Enable the unprivileged user-mode network stack. The guest OS can
- access the host but not vice versa. This is the simplest way to get the
- guest OS online. @code{model} specifies which network device to emulate:
- @code{virtio-net-pci} is a special device made for virtualized operating
- systems and recommended for most uses. Assuming your hardware platform is
- x86_64, you can get a list of available NIC models by running
- @command{qemu-system-x86_64 -nic model=help}.
- @item -enable-kvm
- If your system has hardware virtualization extensions, enabling the
- virtual machine support (KVM) of the Linux kernel will make things run
- faster.
- @c To run Xfce + 'guix pull', we need at least 1G of RAM.
- @item -m 1024
- RAM available to the guest OS, in mebibytes. Defaults to 128@tie{}MiB,
- which may be insufficient for some operations.
- @item -device virtio-blk,drive=myhd
- Create a @code{virtio-blk} drive called ``myhd''. @code{virtio-blk} is a
- ``paravirtualization'' mechanism for block devices that allows QEMU to achieve
- better performance than if it were emulating a complete disk drive. See the
- QEMU and KVM documentation for more info.
- @item -drive if=none,file=/tmp/qemu-image,id=myhd
- Use our QCOW image, the @file{/tmp/qemu-image} file, as the backing
- store of the ``myhd'' drive.
- @end table
- The default @command{run-vm.sh} script that is returned by an invocation of
- @command{guix system vm} does not add a @command{-nic user} flag by default.
- To get network access from within the vm add the @code{(dhcp-client-service)}
- to your system definition and start the VM using
- @command{$(guix system vm config.scm) -nic user}. An important caveat of using
- @command{-nic user} for networking is that @command{ping} will not work, because
- it uses the ICMP protocol. You'll have to use a different command to check for
- network connectivity, for example @command{guix download}.
- @subsection Connecting Through SSH
- @cindex SSH
- @cindex SSH server
- To enable SSH inside a VM you need to add an SSH server like
- @code{openssh-service-type} to your VM (@pxref{Networking Services,
- @code{openssh-service-type}}). In addition you need to forward the SSH port,
- 22 by default, to the host. You can do this with
- @example
- $(guix system vm config.scm) -nic user,model=virtio-net-pci,hostfwd=tcp::10022-:22
- @end example
- To connect to the VM you can run
- @example
- ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -p 10022 localhost
- @end example
- The @command{-p} tells @command{ssh} the port you want to connect to.
- @command{-o UserKnownHostsFile=/dev/null} prevents @command{ssh} from complaining
- every time you modify your @command{config.scm} file and the
- @command{-o StrictHostKeyChecking=no} prevents you from having to allow a
- connection to an unknown host every time you connect.
- @quotation Note
- If you find the above @samp{hostfwd} example not to be working (e.g.,
- your SSH client hangs attempting to connect to the mapped port of your
- VM), make sure that your Guix System VM has networking support, such as
- by using the @code{dhcp-client-service-type} service type.
- @end quotation
- @subsection Using @command{virt-viewer} with Spice
- As an alternative to the default @command{qemu} graphical client you can
- use the @command{remote-viewer} from the @command{virt-viewer} package. To
- connect pass the @command{-spice port=5930,disable-ticketing} flag to
- @command{qemu}. See previous section for further information on how to do this.
- Spice also allows you to do some nice stuff like share your clipboard with your
- VM@. To enable that you'll also have to pass the following flags to @command{qemu}:
- @example
- -device virtio-serial-pci,id=virtio-serial0,max_ports=16,bus=pci.0,addr=0x5
- -chardev spicevmc,name=vdagent,id=vdagent
- -device virtserialport,nr=1,bus=virtio-serial0.0,chardev=vdagent,\
- name=com.redhat.spice.0
- @end example
- You'll also need to add the @code{(spice-vdagent-service)} to your
- system definition (@pxref{Miscellaneous Services, Spice service}).
- @node Defining Services
- @section Defining Services
- The previous sections show the available services and how one can combine
- them in an @code{operating-system} declaration. But how do we define
- them in the first place? And what is a service anyway?
- @menu
- * Service Composition:: The model for composing services.
- * Service Types and Services:: Types and services.
- * Service Reference:: API reference.
- * Shepherd Services:: A particular type of service.
- * Complex Configurations:: Defining bindings for complex configurations.
- @end menu
- @node Service Composition
- @subsection Service Composition
- @cindex services
- @cindex daemons
- Here we define a @dfn{service} as, broadly, something that extends the
- functionality of the operating system. Often a service is a process---a
- @dfn{daemon}---started when the system boots: a secure shell server, a
- Web server, the Guix build daemon, etc. Sometimes a service is a daemon
- whose execution can be triggered by another daemon---e.g., an FTP server
- started by @command{inetd} or a D-Bus service activated by
- @command{dbus-daemon}. Occasionally, a service does not map to a
- daemon. For instance, the ``account'' service collects user accounts
- and makes sure they exist when the system runs; the ``udev'' service
- collects device management rules and makes them available to the eudev
- daemon; the @file{/etc} service populates the @file{/etc} directory
- of the system.
- @cindex service extensions
- Guix system services are connected by @dfn{extensions}. For instance, the
- secure shell service @emph{extends} the Shepherd---the
- initialization system, running as PID@tie{}1---by giving it the command
- lines to start and stop the secure shell daemon (@pxref{Networking
- Services, @code{openssh-service-type}}); the UPower service extends the D-Bus
- service by passing it its @file{.service} specification, and extends the
- udev service by passing it device management rules (@pxref{Desktop
- Services, @code{upower-service}}); the Guix daemon service extends the
- Shepherd by passing it the command lines to start and stop the daemon,
- and extends the account service by passing it a list of required build
- user accounts (@pxref{Base Services}).
- All in all, services and their ``extends'' relations form a directed
- acyclic graph (DAG). If we represent services as boxes and extensions
- as arrows, a typical system might provide something like this:
- @image{images/service-graph,,5in,Typical service extension graph.}
- @cindex system service
- At the bottom, we see the @dfn{system service}, which produces the
- directory containing everything to run and boot the system, as returned
- by the @command{guix system build} command. @xref{Service Reference},
- to learn about the other service types shown here.
- @xref{system-extension-graph, the @command{guix system extension-graph}
- command}, for information on how to generate this representation for a
- particular operating system definition.
- @cindex service types
- Technically, developers can define @dfn{service types} to express these
- relations. There can be any number of services of a given type on the
- system---for instance, a system running two instances of the GNU secure
- shell server (lsh) has two instances of @code{lsh-service-type}, with
- different parameters.
- The following section describes the programming interface for service
- types and services.
- @node Service Types and Services
- @subsection Service Types and Services
- A @dfn{service type} is a node in the DAG described above. Let us start
- with a simple example, the service type for the Guix build daemon
- (@pxref{Invoking guix-daemon}):
- @lisp
- (define guix-service-type
- (service-type
- (name 'guix)
- (extensions
- (list (service-extension shepherd-root-service-type guix-shepherd-service)
- (service-extension account-service-type guix-accounts)
- (service-extension activation-service-type guix-activation)))
- (default-value (guix-configuration))))
- @end lisp
- @noindent
- It defines three things:
- @enumerate
- @item
- A name, whose sole purpose is to make inspection and debugging easier.
- @item
- A list of @dfn{service extensions}, where each extension designates the
- target service type and a procedure that, given the parameters of the
- service, returns a list of objects to extend the service of that type.
- Every service type has at least one service extension. The only
- exception is the @dfn{boot service type}, which is the ultimate service.
- @item
- Optionally, a default value for instances of this type.
- @end enumerate
- In this example, @code{guix-service-type} extends three services:
- @table @code
- @item shepherd-root-service-type
- The @code{guix-shepherd-service} procedure defines how the Shepherd
- service is extended. Namely, it returns a @code{<shepherd-service>}
- object that defines how @command{guix-daemon} is started and stopped
- (@pxref{Shepherd Services}).
- @item account-service-type
- This extension for this service is computed by @code{guix-accounts},
- which returns a list of @code{user-group} and @code{user-account}
- objects representing the build user accounts (@pxref{Invoking
- guix-daemon}).
- @item activation-service-type
- Here @code{guix-activation} is a procedure that returns a gexp, which is
- a code snippet to run at ``activation time''---e.g., when the service is
- booted.
- @end table
- A service of this type is instantiated like this:
- @lisp
- (service guix-service-type
- (guix-configuration
- (build-accounts 5)
- (extra-options '("--gc-keep-derivations"))))
- @end lisp
- The second argument to the @code{service} form is a value representing
- the parameters of this specific service instance.
- @xref{guix-configuration-type, @code{guix-configuration}}, for
- information about the @code{guix-configuration} data type. When the
- value is omitted, the default value specified by
- @code{guix-service-type} is used:
- @lisp
- (service guix-service-type)
- @end lisp
- @code{guix-service-type} is quite simple because it extends other
- services but is not extensible itself.
- @c @subsubsubsection Extensible Service Types
- The service type for an @emph{extensible} service looks like this:
- @lisp
- (define udev-service-type
- (service-type (name 'udev)
- (extensions
- (list (service-extension shepherd-root-service-type
- udev-shepherd-service)))
- (compose concatenate) ;concatenate the list of rules
- (extend (lambda (config rules)
- (match config
- (($ <udev-configuration> udev initial-rules)
- (udev-configuration
- (udev udev) ;the udev package to use
- (rules (append initial-rules rules)))))))))
- @end lisp
- This is the service type for the
- @uref{https://wiki.gentoo.org/wiki/Project:Eudev, eudev device
- management daemon}. Compared to the previous example, in addition to an
- extension of @code{shepherd-root-service-type}, we see two new fields:
- @table @code
- @item compose
- This is the procedure to @dfn{compose} the list of extensions to
- services of this type.
- Services can extend the udev service by passing it lists of rules; we
- compose those extensions simply by concatenating them.
- @item extend
- This procedure defines how the value of the service is @dfn{extended} with
- the composition of the extensions.
- Udev extensions are composed into a list of rules, but the udev service
- value is itself a @code{<udev-configuration>} record. So here, we
- extend that record by appending the list of rules it contains to the
- list of contributed rules.
- @item description
- This is a string giving an overview of the service type. The string can
- contain Texinfo markup (@pxref{Overview,,, texinfo, GNU Texinfo}). The
- @command{guix system search} command searches these strings and displays
- them (@pxref{Invoking guix system}).
- @end table
- There can be only one instance of an extensible service type such as
- @code{udev-service-type}. If there were more, the
- @code{service-extension} specifications would be ambiguous.
- Still here? The next section provides a reference of the programming
- interface for services.
- @node Service Reference
- @subsection Service Reference
- We have seen an overview of service types (@pxref{Service Types and
- Services}). This section provides a reference on how to manipulate
- services and service types. This interface is provided by the
- @code{(gnu services)} module.
- @deffn {Scheme Procedure} service @var{type} [@var{value}]
- Return a new service of @var{type}, a @code{<service-type>} object (see
- below). @var{value} can be any object; it represents the parameters of
- this particular service instance.
- When @var{value} is omitted, the default value specified by @var{type}
- is used; if @var{type} does not specify a default value, an error is
- raised.
- For instance, this:
- @lisp
- (service openssh-service-type)
- @end lisp
- @noindent
- is equivalent to this:
- @lisp
- (service openssh-service-type
- (openssh-configuration))
- @end lisp
- In both cases the result is an instance of @code{openssh-service-type}
- with the default configuration.
- @end deffn
- @deffn {Scheme Procedure} service? @var{obj}
- Return true if @var{obj} is a service.
- @end deffn
- @deffn {Scheme Procedure} service-kind @var{service}
- Return the type of @var{service}---i.e., a @code{<service-type>} object.
- @end deffn
- @deffn {Scheme Procedure} service-value @var{service}
- Return the value associated with @var{service}. It represents its
- parameters.
- @end deffn
- Here is an example of how a service is created and manipulated:
- @lisp
- (define s
- (service nginx-service-type
- (nginx-configuration
- (nginx nginx)
- (log-directory log-directory)
- (run-directory run-directory)
- (file config-file))))
- (service? s)
- @result{} #t
- (eq? (service-kind s) nginx-service-type)
- @result{} #t
- @end lisp
- The @code{modify-services} form provides a handy way to change the
- parameters of some of the services of a list such as
- @code{%base-services} (@pxref{Base Services, @code{%base-services}}). It
- evaluates to a list of services. Of course, you could always use
- standard list combinators such as @code{map} and @code{fold} to do that
- (@pxref{SRFI-1, List Library,, guile, GNU Guile Reference Manual});
- @code{modify-services} simply provides a more concise form for this
- common pattern.
- @deffn {Scheme Syntax} modify-services @var{services} @
- (@var{type} @var{variable} => @var{body}) @dots{}
- Modify the services listed in @var{services} according to the given
- clauses. Each clause has the form:
- @example
- (@var{type} @var{variable} => @var{body})
- @end example
- where @var{type} is a service type---e.g.,
- @code{guix-service-type}---and @var{variable} is an identifier that is
- bound within the @var{body} to the service parameters---e.g., a
- @code{guix-configuration} instance---of the original service of that
- @var{type}.
- The @var{body} should evaluate to the new service parameters, which will
- be used to configure the new service. This new service will replace the
- original in the resulting list. Because a service's service parameters
- are created using @code{define-record-type*}, you can write a succinct
- @var{body} that evaluates to the new service parameters by using the
- @code{inherit} feature that @code{define-record-type*} provides.
- Clauses can also have the following form:
- @lisp
- (delete @var{type})
- @end lisp
- Such a clause removes all services of the given @var{type} from
- @var{services}.
- @xref{Using the Configuration System}, for example usage.
- @end deffn
- Next comes the programming interface for service types. This is
- something you want to know when writing new service definitions, but not
- necessarily when simply looking for ways to customize your
- @code{operating-system} declaration.
- @deftp {Data Type} service-type
- @cindex service type
- This is the representation of a @dfn{service type} (@pxref{Service Types
- and Services}).
- @table @asis
- @item @code{name}
- This is a symbol, used only to simplify inspection and debugging.
- @item @code{extensions}
- A non-empty list of @code{<service-extension>} objects (see below).
- @item @code{compose} (default: @code{#f})
- If this is @code{#f}, then the service type denotes services that cannot
- be extended---i.e., services that do not receive ``values'' from other
- services.
- Otherwise, it must be a one-argument procedure. The procedure is called
- by @code{fold-services} and is passed a list of values collected from
- extensions. It may return any single value.
- @item @code{extend} (default: @code{#f})
- If this is @code{#f}, services of this type cannot be extended.
- Otherwise, it must be a two-argument procedure: @code{fold-services}
- calls it, passing it the initial value of the service as the first
- argument and the result of applying @code{compose} to the extension
- values as the second argument. It must return a value that is a valid
- parameter value for the service instance.
- @item @code{description}
- This is a string, possibly using Texinfo markup, describing in a couple
- of sentences what the service is about. This string allows users to
- find about the service through @command{guix system search}
- (@pxref{Invoking guix system}).
- @item @code{default-value} (default: @code{&no-default-value})
- The default value associated for instances of this service type. This
- allows users to use the @code{service} form without its second argument:
- @lisp
- (service @var{type})
- @end lisp
- The returned service in this case has the default value specified by
- @var{type}.
- @end table
- @xref{Service Types and Services}, for examples.
- @end deftp
- @deffn {Scheme Procedure} service-extension @var{target-type} @
- @var{compute}
- Return a new extension for services of type @var{target-type}.
- @var{compute} must be a one-argument procedure: @code{fold-services}
- calls it, passing it the value associated with the service that provides
- the extension; it must return a valid value for the target service.
- @end deffn
- @deffn {Scheme Procedure} service-extension? @var{obj}
- Return true if @var{obj} is a service extension.
- @end deffn
- Occasionally, you might want to simply extend an existing service. This
- involves creating a new service type and specifying the extension of
- interest, which can be verbose; the @code{simple-service} procedure
- provides a shorthand for this.
- @deffn {Scheme Procedure} simple-service @var{name} @var{target} @var{value}
- Return a service that extends @var{target} with @var{value}. This works
- by creating a singleton service type @var{name}, of which the returned
- service is an instance.
- For example, this extends mcron (@pxref{Scheduled Job Execution}) with
- an additional job:
- @lisp
- (simple-service 'my-mcron-job mcron-service-type
- #~(job '(next-hour (3)) "guix gc -F 2G"))
- @end lisp
- @end deffn
- At the core of the service abstraction lies the @code{fold-services}
- procedure, which is responsible for ``compiling'' a list of services
- down to a single directory that contains everything needed to boot and
- run the system---the directory shown by the @command{guix system build}
- command (@pxref{Invoking guix system}). In essence, it propagates
- service extensions down the service graph, updating each node parameters
- on the way, until it reaches the root node.
- @deffn {Scheme Procedure} fold-services @var{services} @
- [#:target-type @var{system-service-type}]
- Fold @var{services} by propagating their extensions down to the root of
- type @var{target-type}; return the root service adjusted accordingly.
- @end deffn
- Lastly, the @code{(gnu services)} module also defines several essential
- service types, some of which are listed below.
- @defvr {Scheme Variable} system-service-type
- This is the root of the service graph. It produces the system directory
- as returned by the @command{guix system build} command.
- @end defvr
- @defvr {Scheme Variable} boot-service-type
- The type of the ``boot service'', which produces the @dfn{boot script}.
- The boot script is what the initial RAM disk runs when booting.
- @end defvr
- @defvr {Scheme Variable} etc-service-type
- The type of the @file{/etc} service. This service is used to create
- files under @file{/etc} and can be extended by
- passing it name/file tuples such as:
- @lisp
- (list `("issue" ,(plain-file "issue" "Welcome!\n")))
- @end lisp
- In this example, the effect would be to add an @file{/etc/issue} file
- pointing to the given file.
- @end defvr
- @defvr {Scheme Variable} setuid-program-service-type
- Type for the ``setuid-program service''. This service collects lists of
- executable file names, passed as gexps, and adds them to the set of
- setuid-root programs on the system (@pxref{Setuid Programs}).
- @end defvr
- @defvr {Scheme Variable} profile-service-type
- Type of the service that populates the @dfn{system profile}---i.e., the
- programs under @file{/run/current-system/profile}. Other services can
- extend it by passing it lists of packages to add to the system profile.
- @end defvr
- @cindex provenance tracking, of the operating system
- @anchor{provenance-service-type}
- @defvr {Scheme Variable} provenance-service-type
- This is the type of the service that records @dfn{provenance meta-data}
- in the system itself. It creates several files under
- @file{/run/current-system}:
- @table @file
- @item channels.scm
- This is a ``channel file'' that can be passed to @command{guix pull -C}
- or @command{guix time-machine -C}, and which describes the channels used
- to build the system, if that information was available
- (@pxref{Channels}).
- @item configuration.scm
- This is the file that was passed as the value for this
- @code{provenance-service-type} service. By default, @command{guix
- system reconfigure} automatically passes the OS configuration file it
- received on the command line.
- @item provenance
- This contains the same information as the two other files but in a
- format that is more readily processable.
- @end table
- In general, these two pieces of information (channels and configuration
- file) are enough to reproduce the operating system ``from source''.
- @quotation Caveats
- This information is necessary to rebuild your operating system, but it
- is not always sufficient. In particular, @file{configuration.scm}
- itself is insufficient if it is not self-contained---if it refers to
- external Guile modules or to extra files. If you want
- @file{configuration.scm} to be self-contained, we recommend that modules
- or files it refers to be part of a channel.
- Besides, provenance meta-data is ``silent'' in the sense that it does
- not change the bits contained in your system, @emph{except for the
- meta-data bits themselves}. Two different OS configurations or sets of
- channels can lead to the same system, bit-for-bit; when
- @code{provenance-service-type} is used, these two systems will have
- different meta-data and thus different store file names, which makes
- comparison less trivial.
- @end quotation
- This service is automatically added to your operating system
- configuration when you use @command{guix system reconfigure},
- @command{guix system init}, or @command{guix deploy}.
- @end defvr
- @defvr {Scheme Variable} linux-loadable-module-service-type
- Type of the service that collects lists of packages containing
- kernel-loadable modules, and adds them to the set of kernel-loadable
- modules.
- This service type is intended to be extended by other service types,
- such as below:
- @lisp
- (simple-service 'installing-module
- linux-loadable-module-service-type
- (list module-to-install-1
- module-to-install-2))
- @end lisp
- This does not actually load modules at bootup, only adds it to the
- kernel profile so that it @emph{can} be loaded by other means.
- @end defvr
- @node Shepherd Services
- @subsection Shepherd Services
- @cindex shepherd services
- @cindex PID 1
- @cindex init system
- The @code{(gnu services shepherd)} module provides a way to define
- services managed by the GNU@tie{}Shepherd, which is the
- initialization system---the first process that is started when the
- system boots, also known as PID@tie{}1
- (@pxref{Introduction,,, shepherd, The GNU Shepherd Manual}).
- Services in the Shepherd can depend on each other. For instance, the
- SSH daemon may need to be started after the syslog daemon has been
- started, which in turn can only happen once all the file systems have
- been mounted. The simple operating system defined earlier (@pxref{Using
- the Configuration System}) results in a service graph like this:
- @image{images/shepherd-graph,,5in,Typical shepherd service graph.}
- You can actually generate such a graph for any operating system
- definition using the @command{guix system shepherd-graph} command
- (@pxref{system-shepherd-graph, @command{guix system shepherd-graph}}).
- The @code{%shepherd-root-service} is a service object representing
- PID@tie{}1, of type @code{shepherd-root-service-type}; it can be extended
- by passing it lists of @code{<shepherd-service>} objects.
- @deftp {Data Type} shepherd-service
- The data type representing a service managed by the Shepherd.
- @table @asis
- @item @code{provision}
- This is a list of symbols denoting what the service provides.
- These are the names that may be passed to @command{herd start},
- @command{herd status}, and similar commands (@pxref{Invoking herd,,,
- shepherd, The GNU Shepherd Manual}). @xref{Slots of services, the
- @code{provides} slot,, shepherd, The GNU Shepherd Manual}, for details.
- @item @code{requirement} (default: @code{'()})
- List of symbols denoting the Shepherd services this one depends on.
- @cindex one-shot services, for the Shepherd
- @item @code{one-shot?} (default: @code{#f})
- Whether this service is @dfn{one-shot}. One-shot services stop immediately
- after their @code{start} action has completed. @xref{Slots of services,,,
- shepherd, The GNU Shepherd Manual}, for more info.
- @item @code{respawn?} (default: @code{#t})
- Whether to restart the service when it stops, for instance when the
- underlying process dies.
- @item @code{start}
- @itemx @code{stop} (default: @code{#~(const #f)})
- The @code{start} and @code{stop} fields refer to the Shepherd's
- facilities to start and stop processes (@pxref{Service De- and
- Constructors,,, shepherd, The GNU Shepherd Manual}). They are given as
- G-expressions that get expanded in the Shepherd configuration file
- (@pxref{G-Expressions}).
- @item @code{actions} (default: @code{'()})
- @cindex actions, of Shepherd services
- This is a list of @code{shepherd-action} objects (see below) defining
- @dfn{actions} supported by the service, in addition to the standard
- @code{start} and @code{stop} actions. Actions listed here become available as
- @command{herd} sub-commands:
- @example
- herd @var{action} @var{service} [@var{arguments}@dots{}]
- @end example
- @item @code{auto-start?} (default: @code{#t})
- Whether this service should be started automatically by the Shepherd. If it
- is @code{#f} the service has to be started manually with @code{herd start}.
- @item @code{documentation}
- A documentation string, as shown when running:
- @example
- herd doc @var{service-name}
- @end example
- where @var{service-name} is one of the symbols in @code{provision}
- (@pxref{Invoking herd,,, shepherd, The GNU Shepherd Manual}).
- @item @code{modules} (default: @code{%default-modules})
- This is the list of modules that must be in scope when @code{start} and
- @code{stop} are evaluated.
- @end table
- @end deftp
- The example below defines a Shepherd service that spawns
- @command{syslogd}, the system logger from the GNU Networking Utilities
- (@pxref{syslogd invocation, @command{syslogd},, inetutils, GNU
- Inetutils}):
- @example
- (let ((config (plain-file "syslogd.conf" "@dots{}")))
- (shepherd-service
- (documentation "Run the syslog daemon (syslogd).")
- (provision '(syslogd))
- (requirement '(user-processes))
- (start #~(make-forkexec-constructor
- (list #$(file-append inetutils "/libexec/syslogd")
- "--rcfile" #$config)
- #:pid-file "/var/run/syslog.pid"))
- (stop #~(make-kill-destructor))))
- @end example
- Key elements in this example are the @code{start} and @code{stop}
- fields: they are @dfn{staged} code snippets that use the
- @code{make-forkexec-constructor} procedure provided by the Shepherd and
- its dual, @code{make-kill-destructor} (@pxref{Service De- and
- Constructors,,, shepherd, The GNU Shepherd Manual}). The @code{start}
- field will have @command{shepherd} spawn @command{syslogd} with the
- given option; note that we pass @code{config} after @option{--rcfile},
- which is a configuration file declared above (contents of this file are
- omitted). Likewise, the @code{stop} field tells how this service is to
- be stopped; in this case, it is stopped by making the @code{kill} system
- call on its PID@. Code staging is achieved using G-expressions:
- @code{#~} stages code, while @code{#$} ``escapes'' back to host code
- (@pxref{G-Expressions}).
- @deftp {Data Type} shepherd-action
- This is the data type that defines additional actions implemented by a
- Shepherd service (see above).
- @table @code
- @item name
- Symbol naming the action.
- @item documentation
- This is a documentation string for the action. It can be viewed by running:
- @example
- herd doc @var{service} action @var{action}
- @end example
- @item procedure
- This should be a gexp that evaluates to a procedure of at least one argument,
- which is the ``running value'' of the service (@pxref{Slots of services,,,
- shepherd, The GNU Shepherd Manual}).
- @end table
- The following example defines an action called @code{say-hello} that kindly
- greets the user:
- @lisp
- (shepherd-action
- (name 'say-hello)
- (documentation "Say hi!")
- (procedure #~(lambda (running . args)
- (format #t "Hello, friend! arguments: ~s\n"
- args)
- #t)))
- @end lisp
- Assuming this action is added to the @code{example} service, then you can do:
- @example
- # herd say-hello example
- Hello, friend! arguments: ()
- # herd say-hello example a b c
- Hello, friend! arguments: ("a" "b" "c")
- @end example
- This, as you can see, is a fairly sophisticated way to say hello.
- @xref{Service Convenience,,, shepherd, The GNU Shepherd Manual}, for more
- info on actions.
- @end deftp
- @defvr {Scheme Variable} shepherd-root-service-type
- The service type for the Shepherd ``root service''---i.e., PID@tie{}1.
- This is the service type that extensions target when they want to create
- shepherd services (@pxref{Service Types and Services}, for an example).
- Each extension must pass a list of @code{<shepherd-service>}. Its
- value must be a @code{shepherd-configuration}, as described below.
- @end defvr
- @deftp {Data Type} shepherd-configuration
- This data type represents the Shepherd's configuration.
- @table @code
- @item shepherd (default: @code{shepherd})
- The Shepherd package to use.
- @item services (default: @code{'()})
- A list of @code{<shepherd-service>} to start.
- You should probably use the service extension
- mechanism instead (@pxref{Shepherd Services}).
- @end table
- @end deftp
- The following example specifies the Shepherd package for the operating
- system:
- @lisp
- (operating-system
- ;; ...
- (services (append (list openssh-service-type))
- ;; ...
- %desktop-services)
- ;; ...
- ;; Use own Shepherd package.
- (essential-services
- (modify-services (operating-system-default-essential-services
- this-operating-system)
- (shepherd-root-service-type config => (shepherd-configuration
- (inherit config)
- (shepherd my-shepherd))))))
- @end lisp
- @defvr {Scheme Variable} %shepherd-root-service
- This service represents PID@tie{}1.
- @end defvr
- @node Complex Configurations
- @subsection Complex Configurations
- @cindex complex configurations
- Some programs might have rather complex configuration files or formats,
- and to make it easier to create Scheme bindings for these configuration
- files, you can use the utilities defined in the @code{(gnu services
- configuration)} module.
- The main utility is the @code{define-configuration} macro, which you
- will use to define a Scheme record type (@pxref{Record Overview,,,
- guile, GNU Guile Reference Manual}). The Scheme record will be
- serialized to a configuration file by using @dfn{serializers}, which are
- procedures that take some kind of Scheme value and returns a
- G-expression (@pxref{G-Expressions}), which should, once serialized to
- the disk, return a string. More details are listed below.
- @deffn {Scheme Syntax} define-configuration @var{name} @var{clause1} @
- @var{clause2} ...
- Create a record type named @code{@var{name}} that contains the
- fields found in the clauses.
- A clause can have one of the following forms:
- @example
- (@var{field-name}
- (@var{type} @var{default-value})
- @var{documentation})
-
- (@var{field-name}
- (@var{type} @var{default-value})
- @var{documentation}
- @var{serializer})
- (@var{field-name}
- (@var{type})
- @var{documentation})
- (@var{field-name}
- (@var{type})
- @var{documentation}
- @var{serializer})
- @end example
- @var{field-name} is an identifier that denotes the name of the field in
- the generated record.
- @var{type} is the type of the value corresponding to @var{field-name};
- since Guile is untyped, a predicate
- procedure---@code{@var{type}?}---will be called on the value
- corresponding to the field to ensure that the value is of the correct
- type. This means that if say, @var{type} is @code{package}, then a
- procedure named @code{package?} will be applied on the value to make
- sure that it is indeed a @code{<package>} object.
- @var{default-value} is the default value corresponding to the field; if
- none is specified, the user is forced to provide a value when creating
- an object of the record type.
- @c XXX: Should these be full sentences or are they allow to be very
- @c short like package synopses?
- @var{documentation} is a string formatted with Texinfo syntax which
- should provide a description of what setting this field does.
- @var{serializer} is the name of a procedure which takes two arguments,
- the first is the name of the field, and the second is the value
- corresponding to the field. The procedure should return a string or
- G-expression (@pxref{G-Expressions}) that represents the content that
- will be serialized to the configuration file. If none is specified, a
- procedure of the name @code{serialize-@var{type}} will be used.
- A simple serializer procedure could look like this:
- @lisp
- (define (serialize-boolean field-name value)
- (let ((value (if value "true" "false")))
- #~(string-append #$field-name #$value)))
- @end lisp
- In some cases multiple different configuration records might be defined
- in the same file, but their serializers for the same type might have to
- be different, because they have different configuration formats. For
- example, the @code{serialize-boolean} procedure for the Getmail service
- would have to be different for the one for the Transmission service. To
- make it easier to deal with this situation, one can specify a serializer
- prefix by using the @code{prefix} literal in the
- @code{define-configuration} form. This means that one doesn't have to
- manually specify a custom @var{serializer} for every field.
- @lisp
- (define (foo-serialize-string field-name value)
- @dots{})
- (define (bar-serialize-string field-name value)
- @dots{})
-
- (define-configuration foo-configuration
- (label
- (string)
- "The name of label.")
- (prefix foo-))
- (define-configuration bar-configuration
- (ip-address
- (string)
- "The IPv4 address for this device.")
- (prefix bar-))
- @end lisp
- However, in some cases you might not want to serialize any of the values
- of the record, to do this, you can use the @code{no-serialization}
- literal. There is also the @code{define-configuration/no-serialization}
- macro which is a shorthand of this.
- @lisp
- ;; Nothing will be serialized to disk.
- (define-configuration foo-configuration
- (field
- (string "test")
- "Some documentation.")
- (no-serialization))
- ;; The same thing as above.
- (define-configuration/no-serialization bar-configuration
- (field
- (string "test")
- "Some documentation."))
- @end lisp
- @end deffn
- @deffn {Scheme Syntax} define-maybe @var{type}
- Sometimes a field should not be serialized if the user doesn’t specify a
- value. To achieve this, you can use the @code{define-maybe} macro to
- define a ``maybe type''; if the value of a maybe type is set to the
- @code{disabled}, it will not be serialized.
- When defining a ``maybe type'', the corresponding serializer for the
- regular type will be used by default. For example, a field of type
- @code{maybe-string} will be serialized using the @code{serialize-string}
- procedure by default, you can of course change this by specifying a
- custom serializer procedure. Likewise, the type of the value would have
- to be a string, unless it is set to the @code{disabled} symbol.
- @lisp
- (define-maybe string)
- (define (serialize-string field-name value)
- @dots{})
- (define-configuration baz-configuration
- (name
- ;; Nothing will be serialized by default. If set to a string, the
- ;; `serialize-string' procedure will be used to serialize the string.
- (maybe-string 'disabled)
- "The name of this module."))
- @end lisp
- Like with @code{define-configuration}, one can set a prefix for the
- serializer name by using the @code{prefix} literal.
- @lisp
- (define-maybe integer
- (prefix baz-))
- (define (baz-serialize-interger field-name value)
- @dots{})
- @end lisp
- There is also the @code{no-serialization} literal, which when set means
- that no serializer will be defined for the ``maybe type'', regardless of
- its value is @code{disabled} or not.
- @code{define-maybe/no-serialization} is a shorthand for specifying the
- @code{no-serialization} literal.
- @lisp
- (define-maybe/no-serialization symbol)
- (define-configuration/no-serialization test-configuration
- (mode
- (maybe-symbol 'disabled)
- "Docstring."))
- @end lisp
- @end deffn
- @deffn {Scheme Procedure} serialize-configuration @var{configuration} @
- @var{fields}
- Return a G-expression that contains the values corresponding to the
- @var{fields} of @var{configuration}, a record that has been generated by
- @code{define-configuration}. The G-expression can then be serialized to
- disk by using something like @code{mixed-text-file}.
- @end deffn
- @deffn {Scheme Procedure} validate-configuration @var{configuration}
- @var{fields}
- Type-check @var{fields}, a list of field names of @var{configuration}, a
- configuration record created by @code{define-configuration}.
- @end deffn
- @deffn {Scheme Procedure} empty-serializer @var{field-name} @var{value}
- A serializer that just returns an empty string. The
- @code{serialize-package} procedure is an alias for this.
- @end deffn
- Once you have defined a configuration record, you will most likely also
- want to document it so that other people know to use it. To help with
- that, there are two procedures, both of which are documented below.
- @deffn {Scheme Procedure} generate-documentation @var{documentation} @
- @var{documentation-name}
- Generate a Texinfo fragment from the docstrings in @var{documentation},
- a list of @code{(@var{label} @var{fields} @var{sub-documentation} ...)}.
- @var{label} should be a symbol and should be the name of the
- configuration record. @var{fields} should be a list of all the fields
- available for the configuration record.
- @var{sub-documentation} is a @code{(@var{field-name}
- @var{configuration-name})} tuple. @var{field-name} is the name of the
- field which takes another configuration record as its value, and
- @var{configuration-name} is the name of that configuration record.
- @var{sub-documentation} is only needed if there are nested configuration
- records. For example, the @code{getmail-configuration} record
- (@pxref{Mail Services}) accepts a @code{getmail-configuration-file}
- record in one of its @code{rcfile} field, therefore documentation for
- @code{getmail-configuration-file} is nested in
- @code{getmail-configuration}.
- @lisp
- (generate-documentation
- `((getmail-configuration ,getmail-configuration-fields
- (rcfile getmail-configuration-file))
- @dots{})
- 'getmail-configuration)
- @end lisp
- @var{documentation-name} should be a symbol and should be the name of
- the configuration record.
- @end deffn
- @deffn {Scheme Procedure} configuration->documentation
- @var{configuration-symbol}
- Take @var{configuration-symbol}, the symbol corresponding to the name
- used when defining a configuration record with
- @code{define-configuration}, and print the Texinfo documentation of its
- fields. This is useful if there aren’t any nested configuration records
- since it only prints the documentation for the top-level fields.
- @end deffn
- As of right now, there is no automated way to generate documentation for
- configuration records and put them in the manual. Instead, every
- time you make a change to the docstrings of a configuration record, you
- have to manually call @code{generate-documentation} or
- @code{configuration->documentation}, and paste the output into the
- @file{doc/guix.texi} file.
- @c TODO: Actually test this
- Below is an example of a record type created using
- @code{define-configuration} and friends.
- @lisp
- (use-modules (gnu services)
- (guix gexp)
- (gnu services configuration)
- (srfi srfi-26)
- (srfi srfi-1))
- ;; Turn field names, which are Scheme symbols into strings
- (define (uglify-field-name field-name)
- (let ((str (symbol->string field-name)))
- ;; field? -> is-field
- (if (string-suffix? "?" str)
- (string-append "is-" (string-drop-right str 1))
- str)))
- (define (serialize-string field-name value)
- #~(string-append #$(uglify-field-name field-name) " = " #$value "\n"))
- (define (serialize-integer field-name value)
- (serialize-string field-name (number->string value)))
- (define (serialize-boolean field-name value)
- (serialize-string field-name (if value "true" "false")))
- (define (serialize-contact-name field-name value)
- #~(string-append "\n[" #$value "]\n"))
- (define (list-of-contact-configurations? lst)
- (every contact-configuration? lst))
- (define (serialize-list-of-contact-configurations field-name value)
- #~(string-append #$@@(map (cut serialize-configuration <>
- contact-configuration-fields)
- value)))
- (define (serialize-contacts-list-configuration configuration)
- (mixed-text-file
- "contactrc"
- #~(string-append "[Owner]\n"
- #$(serialize-configuration
- configuration contacts-list-configuration-fields))))
- (define-maybe integer)
- (define-maybe string)
- (define-configuration contact-configuration
- (name
- (string)
- "The name of the contact."
- serialize-contact-name)
- (phone-number
- (maybe-integer 'disabled)
- "The person's phone number.")
- (email
- (maybe-string 'disabled)
- "The person's email address.")
- (married?
- (boolean)
- "Whether the person is married."))
- (define-configuration contacts-list-configuration
- (name
- (string)
- "The name of the owner of this contact list.")
- (email
- (string)
- "The owner's email address.")
- (contacts
- (list-of-contact-configurations '())
- "A list of @@code@{contact-configuation@} records which contain
- information about all your contacts."))
- @end lisp
- A contacts list configuration could then be created like this:
- @lisp
- (define my-contacts
- (contacts-list-configuration
- (name "Alice")
- (email "alice@@example.org")
- (contacts
- (list (contact-configuration
- (name "Bob")
- (phone-number 1234)
- (email "bob@@gnu.org")
- (married? #f))
- (contact-configuration
- (name "Charlie")
- (phone-number 0000)
- (married? #t))))))
- @end lisp
- After serializing the configuration to disk, the resulting file would
- look like this:
- @example
- [owner]
- name = Alice
- email = alice@@example.org
- [Bob]
- phone-number = 1234
- email = bob@@gnu.org
- is-married = false
- [Charlie]
- phone-number = 0
- is-married = true
- @end example
- @node Home Configuration
- @chapter Home Configuration
- @cindex home configuration
- Guix supports declarative configuration of @dfn{home environments} by
- utilizing the configuration mechanism described in the previous chapter
- (@pxref{Defining Services}), but for user's dotfiles and packages. It
- works both on Guix System and foreign distros and allows users to
- declare all the packages and services that should be installed and
- configured for the user. Once a user has written a file containing
- @code{home-environment} record, such a configuration can be
- @dfn{instantiated} by an unprivileged user with the @command{guix home}
- command (@pxref{Invoking guix home}).
- @c Maybe later, it will be possible to make home configuration a part of
- @c system configuration to make everything managed by guix system.
- @quotation Note
- The functionality described in this section is still under development
- and is subject to change. Get in touch with us on
- @email{guix-devel@@gnu.org}!
- @end quotation
- The user's home environment usually consists of three basic parts:
- software, configuration, and state. Software in mainstream distros are
- usually installed system-wide, but with GNU Guix most software packages
- can be installed on a per-user basis without needing root privileges,
- and are thus considered part of the user’s @dfn{home environment}.
- Packages on their own not very useful in many cases, because often they
- require some additional configuration, usually config files that reside
- in @env{XDG_CONFIG_HOME} (@file{~/.config} by default) or other
- directories. Everything else can be considered state, like media files,
- application databases, and logs.
- Using Guix for managing home environments provides a number of
- advantages:
- @itemize
- @item All software can be configured in one language (Guile Scheme),
- this gives users the ability to share values between configurations of
- different programs.
- @item A well-defined home environment is self-contained and can be
- created in a declarative and reproducible way---there is no need to grab
- external binaries or manually edit some configuration file.
- @item After every @command{guix home reconfigure} invocation, a new home
- environment generation will be created. This means that users can
- rollback to a previous home environment generation so they don’t have to
- worry about breaking their configuration.
- @item It is possible to manage stateful data with Guix Home, this
- includes the ability to automatically clone Git repositories on the
- initial setup of the machine, and periodically running commands like
- @command{rsync} to sync data with another host. This functionality is
- still in an experimental stage, though.
- @end itemize
- @menu
- * Declaring the Home Environment:: Customizing your Home.
- * Configuring the Shell:: Enabling home environment.
- * Home Services:: Specifying home services.
- * Invoking guix home:: Instantiating a home configuration.
- @end menu
- @node Declaring the Home Environment
- @section Declaring the Home Environment
- The home environment is configured by providing a
- @code{home-environment} declaration in a file that can be passed to the
- @command{guix home} command (@pxref{Invoking guix home}). The easiest
- way to get started is by generating an initial configuration with
- @command{guix home import}:
- @example
- guix home import ~/src/guix-config
- @end example
- The @command{guix home import} command reads some of the ``dot files''
- such as @file{~/.bashrc} found in your home directory and copies them to
- the given directory, @file{~/src/guix-config} in this case; it also
- reads the contents of your profile, @file{~/.guix-profile}, and, based
- on that, it populates @file{~/src/guix-config/home-configuration.scm}
- with a Home configuration that resembles your current configuration.
- A simple setup can include Bash and a custom text configuration, like in
- the example below. Don't be afraid to declare home environment parts,
- which overlaps with your current dot files: before installing any
- configuration files, Guix Home will back up existing config files to a
- separate place in the home directory.
- @quotation Note
- It is highly recommended that you manage your shell or shells with Guix
- Home, because it will make sure that all the necessary scripts are
- sourced by the shell configuration file. Otherwise you will need to do
- it manually. (@pxref{Configuring the Shell}).
- @end quotation
- @findex home-environment
- @lisp
- @include he-config-bare-bones.scm
- @end lisp
- The @code{packages} field should be self-explanatory, it will install
- the list of packages into the user's profile. The most important field
- is @code{services}, it contains a list of @dfn{home services}, which are
- the basic building blocks of a home environment.
- There is no daemon (at least not necessarily) related to a home service,
- a home service is just an element that is used to declare part of home
- environment and extend other parts of it. The extension mechanism
- discussed in the previous chapter (@pxref{Defining Services}) should not
- be confused with Shepherd services (@pxref{Shepherd Services}). Using this extension
- mechanism and some Scheme code that glues things together gives the user
- the freedom to declare their own, very custom, home environments.
- @cindex container, for @command{guix home}
- Once the configuration looks good, you can first test it in a throw-away
- ``container'':
- @example
- guix home container config.scm
- @end example
- The command above spawns a shell where your home environment is running.
- The shell runs in a container, meaning it's isolated from the rest of
- the system, so it's a good way to try out your configuration---you can
- see if configuration bits are missing or misbehaving, if daemons get
- started, and so on. Once you exit that shell, you're back to the prompt
- of your original shell ``in the real world''.
- Once you have a configuration file that suits your needs, you can
- reconfigure your home by running:
- @example
- guix home reconfigure config.scm
- @end example
- This ``builds'' your home environment and creates @file{~/.guix-home}
- pointing to it. Voilà!
- @quotation Note
- Make sure the operating system has elogind, systemd, or a similar
- mechanism to create the XDG run-time directory and has the
- @env{XDG_RUNTIME_DIR} variable set. Failing that, the
- @file{on-first-login} script will not execute anything, and processes
- like user Shepherd and its descendants will not start.
- @end quotation
- @node Configuring the Shell
- @section Configuring the Shell
- This section is safe to skip if your shell or shells are managed by
- Guix Home. Otherwise, read it carefully.
- There are a few scripts that must be evaluated by a login shell to
- activate the home environment. The shell startup files only read by
- login shells often have @code{profile} suffix. For more information
- about login shells see @ref{Invoking Bash,,, bash, The GNU Bash
- Reference Manual} and see @ref{Bash Startup Files,,, bash, The GNU Bash
- Reference Manual}.
- The first script that needs to be sourced is @file{setup-environment},
- which sets all the necessary environment variables (including variables
- declared by the user) and the second one is @file{on-first-login}, which
- starts Shepherd for the current user and performs actions declared by
- other home services that extends
- @code{home-run-on-first-login-service-type}.
- Guix Home will always create @file{~/.profile}, which contains the
- following lines:
- @example
- HOME_ENVIRONMENT=$HOME/.guix-home
- . $HOME_ENVIRONMENT/setup-environment
- $HOME_ENVIRONMENT/on-first-login
- @end example
- This makes POSIX compliant login shells activate the home environment.
- However, in most cases this file won't be read by most modern shells,
- because they are run in non POSIX mode by default and have their own
- @file{*profile} startup files. For example Bash will prefer
- @file{~/.bash_profile} in case it exists and only if it doesn't will it
- fallback to @file{~/.profile}. Zsh (if no additional options are
- specified) will ignore @file{~/.profile}, even if @file{~/.zprofile}
- doesn't exist.
- To make your shell respect @file{~/.profile}, add @code{. ~/.profile} or
- @code{source ~/profile} to the startup file for the login shell. In
- case of Bash, it is @file{~/.bash_profile}, and in case of Zsh, it is
- @file{~/.zprofile}.
- @quotation Note
- This step is only required if your shell is NOT managed by Guix Home.
- Otherwise, everything will be done automatically.
- @end quotation
- @node Home Services
- @section Home Services
- @cindex home services
- A @dfn{home service} is not necessarily something that has a daemon and
- is managed by Shepherd (@pxref{Jump Start,,, shepherd, The GNU Shepherd
- Manual}), in most cases it doesn't. It's a simple building block of the
- home environment, often declaring a set of packages to be installed in
- the home environment profile, a set of config files to be symlinked into
- @env{XDG_CONFIG_HOME} (@file{~/.config} by default), and environment
- variables to be set by a login shell.
- There is a service extension mechanism (@pxref{Service Composition})
- which allows home services to extend other home services and utilize
- capabilities they provide; for example: declare mcron jobs
- (@pxref{Top,,, mcron, GNU@tie{}Mcron}) by extending @ref{Mcron Home
- Service}; declare daemons by extending @ref{Shepherd Home Service}; add
- commands, which will be invoked on by the Bash by extending
- @ref{Shells Home Services, @code{home-bash-service-type}}.
- A good way to discover available home services is using the
- @command{guix home search} command (@pxref{Invoking guix home}). After
- the required home services are found, include its module with the
- @code{use-modules} form (@pxref{use-modules,, Using Guile Modules,
- guile, The GNU Guile Reference Manual}), or the @code{#:use-modules}
- directive (@pxref{define-module,, Creating Guile Modules, guile, The GNU
- Guile Reference Manual}) and declare a home service using the
- @code{service} function, or extend a service type by declaring a new
- service with the @code{simple-service} procedure from @code{(gnu
- services)}.
- @menu
- * Essential Home Services:: Environment variables, packages, on-* scripts.
- * Shells: Shells Home Services. POSIX shells, Bash, Zsh.
- * Mcron: Mcron Home Service. Scheduled User's Job Execution.
- * Shepherd: Shepherd Home Service. Managing User's Daemons.
- * Desktop: Desktop Home Services. Services for graphical environments.
- @end menu
- @c In addition to that Home Services can provide
- @node Essential Home Services
- @subsection Essential Home Services
- There are a few essential home services defined in
- @code{(gnu services)}, they are mostly for internal use and are required
- to build a home environment, but some of them will be useful for the end
- user.
- @cindex environment variables
- @defvr {Scheme Variable} home-environment-variables-service-type
- The service of this type will be instantiated by every home environment
- automatically by default, there is no need to define it, but someone may
- want to extend it with a list of pairs to set some environment
- variables.
- @lisp
- (list ("ENV_VAR1" . "value1")
- ("ENV_VAR2" . "value2"))
- @end lisp
- The easiest way to extend a service type, without defining a new service
- type is to use the @code{simple-service} helper from @code{(gnu
- services)}.
- @lisp
- (simple-service 'some-useful-env-vars-service
- home-environment-variables-service-type
- `(("LESSHISTFILE" . "$XDG_CACHE_HOME/.lesshst")
- ("SHELL" . ,(file-append zsh "/bin/zsh"))
- ("USELESS_VAR" . #f)
- ("_JAVA_AWT_WM_NONREPARENTING" . #t)))
- @end lisp
- If you include such a service in you home environment definition, it
- will add the following content to the @file{setup-environment} script
- (which is expected to be sourced by the login shell):
- @example
- export LESSHISTFILE=$XDG_CACHE_HOME/.lesshst
- export SHELL=/gnu/store/2hsg15n644f0glrcbkb1kqknmmqdar03-zsh-5.8/bin/zsh
- export _JAVA_AWT_WM_NONREPARENTING
- @end example
- @quotation Note
- Make sure that module @code{(gnu packages shells)} is imported with
- @code{use-modules} or any other way, this namespace contains the
- definition of the @code{zsh} packages, which is used in the example
- above.
- @end quotation
- The association list (@pxref{Association Lists, alists, Association
- Lists, guile, The GNU Guile Reference manual}) is a data structure
- containing key-value pairs, for
- @code{home-environment-variables-service-type} the key is always a
- string, the value can be a string, string-valued gexp
- (@pxref{G-Expressions}), file-like object (@pxref{G-Expressions,
- file-like object}) or boolean. For gexps, the variable will be set to
- the value of the gexp; for file-like objects, it will be set to the path
- of the file in the store (@pxref{The Store}); for @code{#t}, it will
- export the variable without any value; and for @code{#f}, it will omit
- variable.
- @end defvr
- @defvr {Scheme Variable} home-profile-service-type
- The service of this type will be instantiated by every home environment
- automatically, there is no need to define it, but you may want to extend
- it with a list of packages if you want to install additional packages
- into your profile. Other services, which need to make some programs
- available to the user will also extend this service type.
- The extension value is just a list of packages:
- @lisp
- (list htop vim emacs)
- @end lisp
- The same approach as @code{simple-service} (@pxref{Service Reference,
- simple-service}) for @code{home-environment-variables-service-type} can
- be used here, too. Make sure that modules containing the specified
- packages are imported with @code{use-modules}. To find a package or
- information about its module use @command{guix search} (@pxref{Invoking
- guix package}). Alternatively, @code{specification->package} can be
- used to get the package record from string without importing related
- module.
- @end defvr
- There are few more essential services, but users are not expected to
- extend them.
- @defvr {Scheme Variable} home-service-type
- The root of home services DAG, it generates a folder, which later will be
- symlinked to @file{~/.guix-home}, it contains configurations,
- profile with binaries and libraries, and some necessary scripts to glue
- things together.
- @end defvr
- @defvr {Scheme Variable} home-run-on-first-login-service-type
- The service of this type generates a Guile script, which is expected to
- be executed by the login shell. It is only executed if the special flag
- file inside @env{XDG_RUNTIME_DIR} hasn't been created, this prevents
- redundant executions of the script if multiple login shells are spawned.
- It can be extended with a gexp. However, to autostart an application,
- users @emph{should not} use this service, in most cases it's better to extend
- @code{home-shepherd-service-type} with a Shepherd service
- (@pxref{Shepherd Services}), or extend the shell's startup file with
- the required command using the appropriate service type.
- @end defvr
- @defvr {Scheme Variable} home-activation-service-type
- The service of this type generates a guile script, which runs on every
- @command{guix home reconfigure} invocation or any other action, which
- leads to the activation of the home environment.
- @end defvr
- @node Shells Home Services
- @subsection Shells
- @cindex shell
- @cindex login shell
- @cindex interactive shell
- @cindex bash
- @cindex zsh
- Shells play a quite important role in the environment initialization
- process, you can configure them manually as described in section
- @ref{Configuring the Shell}, but the recommended way is to use home services
- listed below. It's both easier and more reliable.
- Each home environment instantiates
- @code{home-shell-profile-service-type}, which creates a
- @file{~/.profile} startup file for all POSIX-compatible shells. This
- file contains all the necessary steps to properly initialize the
- environment, but many modern shells like Bash or Zsh prefer their own
- startup files, that's why the respective home services
- (@code{home-bash-service-type} and @code{home-zsh-service-type}) ensure
- that @file{~/.profile} is sourced by @file{~/.bash_profile} and
- @file{~/.zprofile}, respectively.
- @subsubheading Shell Profile Service
- @deftp {Data Type} home-shell-profile-configuration
- Available @code{home-shell-profile-configuration} fields are:
- @table @asis
- @item @code{profile} (default: @code{()}) (type: text-config)
- @code{home-shell-profile} is instantiated automatically by
- @code{home-environment}, DO NOT create this service manually, it can
- only be extended. @code{profile} is a list of file-like objects, which
- will go to @file{~/.profile}. By default @file{~/.profile} contains the
- initialization code which must be evaluated by the login shell to make
- home-environment's profile available to the user, but other commands can
- be added to the file if it is really necessary. In most cases shell's
- configuration files are preferred places for user's customizations.
- Extend home-shell-profile service only if you really know what you do.
- @end table
- @end deftp
- @subsubheading Bash Home Service
- @anchor{home-bash-configuration}
- @deftp {Data Type} home-bash-configuration
- Available @code{home-bash-configuration} fields are:
- @table @asis
- @item @code{package} (default: @code{bash}) (type: package)
- The Bash package to use.
- @item @code{guix-defaults?} (default: @code{#t}) (type: boolean)
- Add sane defaults like reading @file{/etc/bashrc} and coloring the output of
- @command{ls} to the top of the @file{.bashrc} file.
- @item @code{environment-variables} (default: @code{()}) (type: alist)
- Association list of environment variables to set for the Bash session. The
- rules for the @code{home-environment-variables-service-type} apply
- here (@pxref{Essential Home Services}). The contents of this field will be
- added after the contents of the @code{bash-profile} field.
- @item @code{aliases} (default: @code{()}) (type: alist)
- Association list of aliases to set for the Bash session. The aliases
- will be defined after the contents of the @code{bashrc} field has been
- put in the @file{.bashrc} file. The alias will automatically be quoted,
- so something line this:
- @lisp
- '(("ls" . "ls -alF"))
- @end lisp
- turns into
- @example
- alias ls="ls -alF"
- @end example
- @item @code{bash-profile} (default: @code{()}) (type: text-config)
- List of file-like objects, which will be added to @file{.bash_profile}.
- Used for executing user's commands at start of login shell (In most
- cases the shell started on tty just after login). @file{.bash_login}
- won't be ever read, because @file{.bash_profile} always present.
- @item @code{bashrc} (default: @code{()}) (type: text-config)
- List of file-like objects, which will be added to @file{.bashrc}. Used
- for executing user's commands at start of interactive shell (The shell
- for interactive usage started by typing @code{bash} or by terminal app
- or any other program).
- @item @code{bash-logout} (default: @code{()}) (type: text-config)
- List of file-like objects, which will be added to @file{.bash_logout}.
- Used for executing user's commands at the exit of login shell. It won't
- be read in some cases (if the shell terminates by exec'ing another
- process for example).
- @end table
- @end deftp
- You can extend the Bash service by using the @code{home-bash-extension}
- configuration record, whose fields most mirror that of
- @code{home-bash-configuration} (@pxref{home-bash-configuration}). The
- contents of the extensions will be added to the end of the corresponding
- Bash configuration files (@pxref{Bash Startup Files,,, bash, The GNU
- Bash Reference Manual}.
- @deftp {Data Type} home-bash-extension
- Available @code{home-bash-extension} fields are:
- @table @asis
- @item @code{environment-variables} (default: @code{()}) (type: alist)
- Additional environment variables to set. These will be combined with the
- environment variables from other extensions and the base service to form one
- coherent block of environment variables.
- @item @code{aliases} (default: @code{()}) (type: alist)
- Additional aliases to set. These will be combined with the aliases from
- other extensions and the base service.
- @item @code{bash-profile} (default: @code{()}) (type: text-config)
- Additional text blocks to add to @file{.bash_profile}, which will be combined
- with text blocks from other extensions and the base service.
- @item @code{bashrc} (default: @code{()}) (type: text-config)
- Additional text blocks to add to @file{.bashrc}, which will be combined
- with text blocks from other extensions and the base service.
- @item @code{bash-logout} (default: @code{()}) (type: text-config)
- Additional text blocks to add to @file{.bash_logout}, which will be combined
- with text blocks from other extensions and the base service.
- @end table
- @end deftp
- @subsubheading Zsh Home Service
- @deftp {Data Type} home-zsh-configuration
- Available @code{home-zsh-configuration} fields are:
- @table @asis
- @item @code{package} (default: @code{zsh}) (type: package)
- The Zsh package to use.
- @item @code{xdg-flavor?} (default: @code{#t}) (type: boolean)
- Place all the configs to @file{$XDG_CONFIG_HOME/zsh}. Makes
- @file{~/.zshenv} to set @env{ZDOTDIR} to @file{$XDG_CONFIG_HOME/zsh}.
- Shell startup process will continue with
- @file{$XDG_CONFIG_HOME/zsh/.zshenv}.
- @item @code{environment-variables} (default: @code{()}) (type: alist)
- Association list of environment variables to set for the Zsh session.
- @item @code{zshenv} (default: @code{()}) (type: text-config)
- List of file-like objects, which will be added to @file{.zshenv}. Used
- for setting user's shell environment variables. Must not contain
- commands assuming the presence of tty or producing output. Will be read
- always. Will be read before any other file in @env{ZDOTDIR}.
- @item @code{zprofile} (default: @code{()}) (type: text-config)
- List of file-like objects, which will be added to @file{.zprofile}. Used
- for executing user's commands at start of login shell (In most cases the
- shell started on tty just after login). Will be read before
- @file{.zlogin}.
- @item @code{zshrc} (default: @code{()}) (type: text-config)
- List of file-like objects, which will be added to @file{.zshrc}. Used
- for executing user's commands at start of interactive shell (The shell
- for interactive usage started by typing @code{zsh} or by terminal app or
- any other program).
- @item @code{zlogin} (default: @code{()}) (type: text-config)
- List of file-like objects, which will be added to @file{.zlogin}. Used
- for executing user's commands at the end of starting process of login
- shell.
- @item @code{zlogout} (default: @code{()}) (type: text-config)
- List of file-like objects, which will be added to @file{.zlogout}. Used
- for executing user's commands at the exit of login shell. It won't be
- read in some cases (if the shell terminates by exec'ing another process
- for example).
- @end table
- @end deftp
- @node Mcron Home Service
- @subsection Scheduled User's Job Execution
- @cindex cron
- @cindex mcron
- @cindex scheduling jobs
- The @code{(gnu home services mcron)} module provides an interface to
- GNU@tie{}mcron, a daemon to run jobs at scheduled times (@pxref{Top,,,
- mcron, GNU@tie{}mcron}). The information about system's mcron is
- applicable here (@pxref{Scheduled Job Execution}), the only difference
- for home services is that they have to be declared in a
- @code{home-envirnoment} record instead of an @code{operating-system}
- record.
- @defvr {Scheme Variable} home-mcron-service-type
- This is the type of the @code{mcron} home service, whose value is an
- @code{home-mcron-configuration} object. It allows to manage scheduled
- tasks.
- This service type can be the target of a service extension that provides
- additional job specifications (@pxref{Service Composition}). In other
- words, it is possible to define services that provide additional mcron
- jobs to run.
- @end defvr
- @deftp {Data Type} home-mcron-configuration
- Data type representing the configuration of mcron.
- @table @asis
- @item @code{mcron} (default: @var{mcron})
- The mcron package to use.
- @item @code{jobs}
- This is a list of gexps (@pxref{G-Expressions}), where each gexp
- corresponds to an mcron job specification (@pxref{Syntax, mcron job
- specifications,, mcron, GNU@tie{}mcron}).
- @end table
- @end deftp
- @node Shepherd Home Service
- @subsection Managing User Daemons
- @cindex shepherd services, for users
- The @code{(gnu home services shepherd)} module supports the definitions
- of per-user Shepherd services (@pxref{Introduction,,, shepherd, The GNU
- Shepherd Manual}). You extend @code{home-shepherd-service-type} with
- new services; Guix Home then takes care of starting the @code{shepherd}
- daemon for you when you log in, which in turns starts the services you
- asked for.
- @defvr {Scheme Variable} home-shepherd-service-type
- The service type for the userland Shepherd, which allows one to manage
- long-running processes or one-shot tasks. User's Shepherd is not an
- init process (PID 1), but almost all other information described in
- (@pxref{Shepherd Services}) is applicable here too.
- This is the service type that extensions target when they want to create
- shepherd services (@pxref{Service Types and Services}, for an example).
- Each extension must pass a list of @code{<shepherd-service>}. Its
- value must be a @code{home-shepherd-configuration}, as described below.
- @end defvr
- @deftp {Data Type} home-shepherd-configuration
- This data type represents the Shepherd's configuration.
- @table @code
- @item shepherd (default: @code{shepherd})
- The Shepherd package to use.
- @item auto-start? (default: @code{#t})
- Whether or not to start Shepherd on first login.
- @item services (default: @code{'()})
- A list of @code{<shepherd-service>} to start.
- You should probably use the service extension
- mechanism instead (@pxref{Shepherd Services}).
- @end table
- @end deftp
- @node Desktop Home Services
- @subsection Desktop Home Services
- The @code{(gnu home services desktop)} module provides services that you
- may find useful on ``desktop'' systems running a graphical user
- environment such as Xorg.
- @defvr {Scheme Variable} home-redshift-service-type
- This is the service type for @uref{https://github.com/jonls/redshift,
- Redshift}, a program that adjusts the display color temperature
- according to the time of day. Its associated value must be a
- @code{home-redshift-configuration} record, as shown below.
- A typical configuration, where we manually specify the latitude and
- longitude, might look like this:
- @lisp
- (service home-redshift-service-type
- (home-redshift-configuration
- (location-provider 'manual)
- (latitude 35.81) ;northern hemisphere
- (longitude -0.80))) ;west of Greenwich
- @end lisp
- @end defvr
- @deftp {Data Type} home-redshift-configuration
- Available @code{home-redshift-configuration} fields are:
- @table @asis
- @item @code{redshift} (default: @code{redshift}) (type: file-like)
- Redshift package to use.
- @item @code{location-provider} (default: @code{geoclue2}) (type: symbol)
- Geolocation provider---@code{'manual} or @code{'geoclue2}. In the
- former case, you must also specify the @code{latitude} and
- @code{longitude} fields so Redshift can determine daytime at your place.
- In the latter case, the Geoclue system service must be running; it will
- be queried for location information.
- @item @code{adjustment-method} (default: @code{randr}) (type: symbol)
- Color adjustment method.
- @item @code{daytime-temperature} (default: @code{6500}) (type: integer)
- Daytime color temperature (kelvins).
- @item @code{nighttime-temperature} (default: @code{4500}) (type: integer)
- Nighttime color temperature (kelvins).
- @item @code{daytime-brightness} (default: @code{disabled}) (type: maybe-inexact-number)
- Daytime screen brightness, between 0.1 and 1.0.
- @item @code{nighttime-brightness} (default: @code{disabled}) (type: maybe-inexact-number)
- Nighttime screen brightness, between 0.1 and 1.0.
- @item @code{latitude} (default: @code{disabled}) (type: maybe-inexact-number)
- Latitude, when @code{location-provider} is @code{'manual}.
- @item @code{longitude} (default: @code{disabled}) (type: maybe-inexact-number)
- Longitude, when @code{location-provider} is @code{'manual}.
- @item @code{dawn-time} (default: @code{disabled}) (type: maybe-string)
- Custom time for the transition from night to day in the
- morning---@code{"HH:MM"} format. When specified, solar elevation is not
- used to determine the daytime/nighttime period.
- @item @code{dusk-time} (default: @code{disabled}) (type: maybe-string)
- Likewise, custom time for the transition from day to night in the
- evening.
- @item @code{extra-content} (default: @code{""}) (type: raw-configuration-string)
- Extra content appended as-is to the Redshift configuration file. Run
- @command{man redshift} for more information about the configuration file
- format.
- @end table
- @end deftp
- @node Invoking guix home
- @section Invoking @code{guix home}
- Once you have written a home environment declaration (@pxref{Declaring
- the Home Environment,,,,}, it can be @dfn{instantiated} using the
- @command{guix home} command. The synopsis is:
- @example
- guix home @var{options}@dots{} @var{action} @var{file}
- @end example
- @var{file} must be the name of a file containing a
- @code{home-environment} declaration. @var{action} specifies how the
- home environment is instantiated, but there are few auxiliary actions
- which don't instantiate it. Currently the following values are
- supported:
- @table @code
- @item search
- Display available home service type definitions that match the given
- regular expressions, sorted by relevance:
- @cindex shell
- @cindex shell-profile
- @cindex bash
- @cindex zsh
- @example
- $ guix home search shell
- name: home-shell-profile
- location: gnu/home/services/shells.scm:100:2
- extends: home-files
- description: Create `~/.profile', which is used for environment initialization of POSIX compliant login shells.
- + This service type can be extended with a list of file-like objects.
- relevance: 6
- name: home-fish
- location: gnu/home/services/shells.scm:640:2
- extends: home-files home-profile
- description: Install and configure Fish, the friendly interactive shell.
- relevance: 3
- name: home-zsh
- location: gnu/home/services/shells.scm:290:2
- extends: home-files home-profile
- description: Install and configure Zsh.
- relevance: 1
- name: home-bash
- location: gnu/home/services/shells.scm:508:2
- extends: home-files home-profile
- description: Install and configure GNU Bash.
- relevance: 1
- @dots{}
- @end example
- As for @command{guix search}, the result is written in
- @code{recutils} format, which makes it easy to filter the output
- (@pxref{Top, GNU recutils databases,, recutils, GNU recutils manual}).
- @cindex container, for @command{guix home}
- @item container
- Spawn a shell in an isolated environment---a
- @dfn{container}---containing your home as specified by @var{file}.
- For example, this is how you would start an interactive shell in a
- container with your home:
- @example
- guix home container config.scm
- @end example
- This is a throw-away container where you can lightheartedly fiddle with
- files; any changes made within the container, any process started---all
- this disappears as soon as you exit that shell.
- As with @command{guix shell}, several options control that container:
- @table @option
- @item --network
- @itemx -N
- Enable networking within the container (it is disabled by default).
- @item --expose=@var{source}[=@var{target}]
- @itemx --share=@var{source}[=@var{target}]
- As with @command{guix shell}, make directory @var{source} of the host
- system available as @var{target} inside the container---read-only if you
- pass @option{--expose}, and writable if you pass @option{--share}
- (@pxref{Invoking guix shell, @option{--expose} and @option{--share}}).
- @end table
- Additionally, you can run a command in that container, instead of
- spawning an interactive shell. For instance, here is how you would
- check which Shepherd services are started in a throw-away home
- container:
- @example
- guix home container config.scm -- herd status
- @end example
- The command to run in the container must come after @code{--} (double
- hyphen).
- @item reconfigure
- Build the home environment described in @var{file}, and switch to it.
- Switching means that the activation script will be evaluated and (in
- basic scenario) symlinks to configuration files generated from
- @code{home-environment} declaration will be created in @file{~}. If the
- file with the same path already exists in home folder it will be moved
- to @file{~/@var{timestamp}-guix-home-legacy-configs-backup}, where @var{timestamp}
- is a current UNIX epoch time.
- @quotation Note
- It is highly recommended to run @command{guix pull} once before you run
- @command{guix home reconfigure} for the first time (@pxref{Invoking guix
- pull}).
- @end quotation
- This effects all the configuration specified in @var{file}. The command
- starts Shepherd services specified in @var{file} that are not currently
- running; if a service is currently running, this command will arrange
- for it to be upgraded the next time it is stopped (e.g.@: by @code{herd
- stop @var{service}} or @code{herd restart @var{service}}).
- This command creates a new generation whose number is one greater than
- the current generation (as reported by @command{guix home
- list-generations}). If that generation already exists, it will be
- overwritten. This behavior mirrors that of @command{guix package}
- (@pxref{Invoking guix package}).
- @cindex provenance tracking, of the home environment
- Upon completion, the new home is deployed under @file{~/.guix-home}.
- This directory contains @dfn{provenance meta-data}: the list of channels
- in use (@pxref{Channels}) and @var{file} itself, when available. You
- can view the provenance information by running:
- @example
- guix home describe
- @end example
- This information is useful should you later want to inspect how this
- particular generation was built. In fact, assuming @var{file} is
- self-contained, you can later rebuild generation @var{n} of your
- home environment with:
- @example
- guix time-machine \
- -C /var/guix/profiles/per-user/@var{USER}/guix-home-@var{n}-link/channels.scm -- \
- home reconfigure \
- /var/guix/profiles/per-user/@var{USER}/guix-home-@var{n}-link/configuration.scm
- @end example
- You can think of it as some sort of built-in version control! Your
- home is not just a binary artifact: @emph{it carries its own source}.
- @c @xref{Service Reference, @code{provenance-service-type}}, for more
- @c information on provenance tracking.
- @c @footnote{This action (and the related actions
- @c @code{switch-generation} and @code{roll-back}) are usable after the
- @c home environment is initialized.}.
- @item switch-generation
- @cindex home generations
- Switch to an existing home generation. This action atomically switches
- the home profile to the specified home generation.
- The target generation can be specified explicitly by its generation
- number. For example, the following invocation would switch to home
- generation 7:
- @example
- guix home switch-generation 7
- @end example
- The target generation can also be specified relative to the current
- generation with the form @code{+N} or @code{-N}, where @code{+3} means
- ``3 generations ahead of the current generation,'' and @code{-1} means
- ``1 generation prior to the current generation.'' When specifying a
- negative value such as @code{-1}, you must precede it with @code{--} to
- prevent it from being parsed as an option. For example:
- @example
- guix home switch-generation -- -1
- @end example
- This action will fail if the specified generation does not exist.
- @item roll-back
- @cindex rolling back
- Switch to the preceding home generation. This is the inverse
- of @command{reconfigure}, and it is exactly the same as invoking
- @command{switch-generation} with an argument of @code{-1}.
- @item delete-generations
- @cindex deleting home generations
- @cindex saving space
- Delete home generations, making them candidates for garbage collection
- (@pxref{Invoking guix gc}, for information on how to run the ``garbage
- collector'').
- This works in the same way as @samp{guix package --delete-generations}
- (@pxref{Invoking guix package, @option{--delete-generations}}). With no
- arguments, all home generations but the current one are deleted:
- @example
- guix home delete-generations
- @end example
- You can also select the generations you want to delete. The example below
- deletes all the home generations that are more than two months old:
- @example
- guix home delete-generations 2m
- @end example
- @item build
- Build the derivation of the home environment, which includes all the
- configuration files and programs needed. This action does not actually
- install anything.
- @item describe
- Describe the current home generation: its file name, as well as
- provenance information when available.
- @item list-generations
- List a summary of each generation of the home environment available on
- disk, in a human-readable way. This is similar to the
- @option{--list-generations} option of @command{guix package}
- (@pxref{Invoking guix package}).
- Optionally, one can specify a pattern, with the same syntax that is used
- in @command{guix package --list-generations}, to restrict the list of
- generations displayed. For instance, the following command displays
- generations that are up to 10 days old:
- @example
- $ guix home list-generations 10d
- @end example
- @item import
- Generate a @dfn{home environment} from the packages in the default
- profile and configuration files found in the user's home directory. The
- configuration files will be copied to the specified directory, and a
- @file{home-configuration.scm} will be populated with the home
- environment. Note that not every home service that exists is supported
- (@pxref{Home Services}).
- @example
- $ guix home import ~/guix-config
- guix home: '/home/alice/guix-config' populated with all the Home configuration files
- @end example
- @end table
- And there's more! @command{guix home} also provides the following
- sub-commands to visualize how the services of your home environment
- relate to one another:
- @table @code
- @cindex service extension graph, of a home environment
- @item extension-graph
- Emit to standard output the @dfn{service extension graph} of the home
- environment defined in @var{file} (@pxref{Service Composition}, for more
- information on service extensions). By default the output is in
- Dot/Graphviz format, but you can choose a different format with
- @option{--graph-backend}, as with @command{guix graph} (@pxref{Invoking
- guix graph, @option{--backend}}):
- The command:
- @example
- guix home extension-graph @var{file} | xdot -
- @end example
- shows the extension relations among services.
- @cindex Shepherd dependency graph, for a home environment
- @item shepherd-graph
- Emit to standard output the @dfn{dependency graph} of shepherd services
- of the home environment defined in @var{file}. @xref{Shepherd
- Services}, for more information and for an example graph.
- Again, the default output format is Dot/Graphviz, but you can pass
- @option{--graph-backend} to select a different one.
- @end table
- @var{options} can contain any of the common build options (@pxref{Common
- Build Options}). In addition, @var{options} can contain one of the
- following:
- @table @option
- @item --expression=@var{expr}
- @itemx -e @var{expr}
- Consider the home-environment @var{expr} evaluates to.
- This is an alternative to specifying a file which evaluates to a home
- environment.
- @item --allow-downgrades
- Instruct @command{guix home reconfigure} to allow system downgrades.
- Just like @command{guix system}, @command{guix home reconfigure}, by
- default, prevents you from downgrading your home to older or unrelated
- revisions compared to the channel revisions that were used to deploy
- it---those shown by @command{guix home describe}. Using
- @option{--allow-downgrades} allows you to bypass that check, at the risk
- of downgrading your home---be careful!
- @end table
- @node Documentation
- @chapter Documentation
- @cindex documentation, searching for
- @cindex searching for documentation
- @cindex Info, documentation format
- @cindex man pages
- @cindex manual pages
- In most cases packages installed with Guix come with documentation.
- There are two main documentation formats: ``Info'', a browsable
- hypertext format used for GNU software, and ``manual pages'' (or ``man
- pages''), the linear documentation format traditionally found on Unix.
- Info manuals are accessed with the @command{info} command or with Emacs,
- and man pages are accessed using @command{man}.
- You can look for documentation of software installed on your system by
- keyword. For example, the following command searches for information
- about ``TLS'' in Info manuals:
- @example
- $ info -k TLS
- "(emacs)Network Security" -- STARTTLS
- "(emacs)Network Security" -- TLS
- "(gnutls)Core TLS API" -- gnutls_certificate_set_verify_flags
- "(gnutls)Core TLS API" -- gnutls_certificate_set_verify_function
- @dots{}
- @end example
- @noindent
- The command below searches for the same keyword in man
- pages@footnote{The database searched by @command{man -k} is only created
- in profiles that contain the @code{man-db} package.}:
- @example
- $ man -k TLS
- SSL (7) - OpenSSL SSL/TLS library
- certtool (1) - GnuTLS certificate tool
- @dots {}
- @end example
- These searches are purely local to your computer so you have the
- guarantee that documentation you find corresponds to what you have
- actually installed, you can access it off-line, and your privacy is
- respected.
- Once you have these results, you can view the relevant documentation by
- running, say:
- @example
- $ info "(gnutls)Core TLS API"
- @end example
- @noindent
- or:
- @example
- $ man certtool
- @end example
- Info manuals contain sections and indices as well as hyperlinks like
- those found in Web pages. The @command{info} reader (@pxref{Top, Info
- reader,, info-stnd, Stand-alone GNU Info}) and its Emacs counterpart
- (@pxref{Misc Help,,, emacs, The GNU Emacs Manual}) provide intuitive key
- bindings to navigate manuals. @xref{Getting Started,,, info, Info: An
- Introduction}, for an introduction to Info navigation.
- @node Installing Debugging Files
- @chapter Installing Debugging Files
- @cindex debugging files
- Program binaries, as produced by the GCC compilers for instance, are
- typically written in the ELF format, with a section containing
- @dfn{debugging information}. Debugging information is what allows the
- debugger, GDB, to map binary code to source code; it is required to
- debug a compiled program in good conditions.
- This chapter explains how to use separate debug info when packages
- provide it, and how to rebuild packages with debug info when it's
- missing.
- @menu
- * Separate Debug Info:: Installing 'debug' outputs.
- * Rebuilding Debug Info:: Building missing debug info.
- @end menu
- @node Separate Debug Info
- @section Separate Debug Info
- The problem with debugging information is that is takes up a fair amount
- of disk space. For example, debugging information for the GNU C Library
- weighs in at more than 60 MiB@. Thus, as a user, keeping all the
- debugging info of all the installed programs is usually not an option.
- Yet, space savings should not come at the cost of an impediment to
- debugging---especially in the GNU system, which should make it easier
- for users to exert their computing freedom (@pxref{GNU Distribution}).
- Thankfully, the GNU Binary Utilities (Binutils) and GDB provide a
- mechanism that allows users to get the best of both worlds: debugging
- information can be stripped from the binaries and stored in separate
- files. GDB is then able to load debugging information from those files,
- when they are available (@pxref{Separate Debug Files,,, gdb, Debugging
- with GDB}).
- The GNU distribution takes advantage of this by storing debugging
- information in the @code{lib/debug} sub-directory of a separate package
- output unimaginatively called @code{debug} (@pxref{Packages with
- Multiple Outputs}). Users can choose to install the @code{debug} output
- of a package when they need it. For instance, the following command
- installs the debugging information for the GNU C Library and for GNU
- Guile:
- @example
- guix install glibc:debug guile:debug
- @end example
- GDB must then be told to look for debug files in the user's profile, by
- setting the @code{debug-file-directory} variable (consider setting it
- from the @file{~/.gdbinit} file, @pxref{Startup,,, gdb, Debugging with
- GDB}):
- @example
- (gdb) set debug-file-directory ~/.guix-profile/lib/debug
- @end example
- From there on, GDB will pick up debugging information from the
- @file{.debug} files under @file{~/.guix-profile/lib/debug}.
- Below is an alternative GDB script which is useful when working with
- other profiles. It takes advantage of the optional Guile integration in
- GDB. This snippet is included by default on Guix System in the
- @file{~/.gdbinit} file.
- @example
- guile
- (use-modules (gdb))
- (execute (string-append "set debug-file-directory "
- (or (getenv "GDB_DEBUG_FILE_DIRECTORY")
- "~/.guix-profile/lib/debug")))
- end
- @end example
- In addition, you will most likely want GDB to be able to show the source
- code being debugged. To do that, you will have to unpack the source
- code of the package of interest (obtained with @code{guix build
- --source}, @pxref{Invoking guix build}), and to point GDB to that source
- directory using the @code{directory} command (@pxref{Source Path,
- @code{directory},, gdb, Debugging with GDB}).
- @c XXX: keep me up-to-date
- The @code{debug} output mechanism in Guix is implemented by the
- @code{gnu-build-system} (@pxref{Build Systems}). Currently, it is
- opt-in---debugging information is available only for the packages with
- definitions explicitly declaring a @code{debug} output. To check
- whether a package has a @code{debug} output, use @command{guix package
- --list-available} (@pxref{Invoking guix package}).
- Read on for how to deal with packages lacking a @code{debug} output.
- @node Rebuilding Debug Info
- @section Rebuilding Debug Info
- @cindex debugging info, rebuilding
- As we saw above, some packages, but not all, provide debugging info in a
- @code{debug} output. What can you do when debugging info is missing?
- The @option{--with-debug-info} option provides a solution to that: it
- allows you to rebuild the package(s) for which debugging info is
- missing---and only those---and to graft those onto the application
- you're debugging. Thus, while it's not as fast as installing a
- @code{debug} output, it is relatively inexpensive.
- Let's illustrate that. Suppose you're experiencing a bug in Inkscape
- and would like to see what's going on in GLib, a library that's deep
- down in its dependency graph. As it turns out, GLib does not have a
- @code{debug} output and the backtrace GDB shows is all sadness:
- @example
- (gdb) bt
- #0 0x00007ffff5f92190 in g_getenv ()
- from /gnu/store/@dots{}-glib-2.62.6/lib/libglib-2.0.so.0
- #1 0x00007ffff608a7d6 in gobject_init_ctor ()
- from /gnu/store/@dots{}-glib-2.62.6/lib/libgobject-2.0.so.0
- #2 0x00007ffff7fe275a in call_init (l=<optimized out>, argc=argc@@entry=1, argv=argv@@entry=0x7fffffffcfd8,
- env=env@@entry=0x7fffffffcfe8) at dl-init.c:72
- #3 0x00007ffff7fe2866 in call_init (env=0x7fffffffcfe8, argv=0x7fffffffcfd8, argc=1, l=<optimized out>)
- at dl-init.c:118
- @end example
- To address that, you install Inkscape linked against a variant GLib that
- contains debug info:
- @example
- guix install inkscape --with-debug-info=glib
- @end example
- This time, debugging will be a whole lot nicer:
- @example
- $ gdb --args sh -c 'exec inkscape'
- @dots{}
- (gdb) b g_getenv
- Function "g_getenv" not defined.
- Make breakpoint pending on future shared library load? (y or [n]) y
- Breakpoint 1 (g_getenv) pending.
- (gdb) r
- Starting program: /gnu/store/@dots{}-profile/bin/sh -c exec\ inkscape
- @dots{}
- (gdb) bt
- #0 g_getenv (variable=variable@@entry=0x7ffff60c7a2e "GOBJECT_DEBUG") at ../glib-2.62.6/glib/genviron.c:252
- #1 0x00007ffff608a7d6 in gobject_init () at ../glib-2.62.6/gobject/gtype.c:4380
- #2 gobject_init_ctor () at ../glib-2.62.6/gobject/gtype.c:4493
- #3 0x00007ffff7fe275a in call_init (l=<optimized out>, argc=argc@@entry=3, argv=argv@@entry=0x7fffffffd088,
- env=env@@entry=0x7fffffffd0a8) at dl-init.c:72
- @dots{}
- @end example
- Much better!
- Note that there can be packages for which @option{--with-debug-info}
- will not have the desired effect. @xref{Package Transformation Options,
- @option{--with-debug-info}}, for more information.
- @node Using TeX and LaTeX
- @chapter Using @TeX{} and @LaTeX{}
- @cindex @TeX{} packages
- @cindex @LaTeX{} packages
- Guix provides packages for the @TeX{}, @LaTeX{}, ConTeXt, LuaTeX, and
- related typesetting systems, taken from the
- @uref{https://www.tug.org/texlive/, @TeX{} Live distribution}. However,
- because @TeX{} Live is so huge and because finding your way in this maze
- is tricky, we thought that you, dear user, would welcome guidance on how
- to deploy the relevant packages so you can compile your @TeX{} and
- @LaTeX{} documents.
- @TeX{} Live currently comes in two flavors in Guix:
- @itemize
- @item
- The ``monolithic'' @code{texlive} package: it comes with @emph{every
- single @TeX{} Live package} (more than 7,000 of them), but it is huge
- (more than 4@tie{}GiB for a single package!).
- @item
- The ``modular'' @code{texlive-} packages: you install
- @code{texlive-base}, which provides core functionality and the main
- commands---@command{pdflatex}, @command{dvips}, @command{luatex},
- @command{mf}, etc.---together with individual packages that provide just
- the features you need---@code{texlive-listings} for the
- @code{listings} package, @code{texlive-hyperref} for @code{hyperref},
- @code{texlive-beamer} for Beamer, @code{texlive-pgf} for PGF/TikZ,
- and so on.
- @end itemize
- We recommend using the modular package set because it is much less
- resource-hungry. To build your documents, you would use commands such
- as:
- @example
- guix shell texlive-base texlive-wrapfig \
- texlive-hyperref texlive-cm-super -- pdflatex doc.tex
- @end example
- You can quickly end up with unreasonably long command lines though. The
- solution is to instead write a manifest, for example like this one:
- @lisp
- (specifications->manifest
- '("rubber"
- "texlive-base"
- "texlive-wrapfig"
- "texlive-microtype"
- "texlive-listings" "texlive-hyperref"
- ;; PGF/TikZ
- "texlive-pgf"
- ;; Additional fonts.
- "texlive-cm-super" "texlive-amsfonts"
- "texlive-times" "texlive-helvetic" "texlive-courier"))
- @end lisp
- You can then pass it to any command with the @option{-m} option:
- @example
- guix shell -m manifest.scm -- pdflatex doc.tex
- @end example
- @xref{Invoking guix package, @option{--manifest}}, for more on
- manifests. In the future, we plan to provide packages for @TeX{} Live
- @dfn{collections}---``meta-packages'' such as @code{fontsrecommended},
- @code{humanities}, or @code{langarabic} that provide the set of packages
- needed in this particular domain. That will allow you to list fewer
- packages.
- The main difficulty here is that using the modular package set forces
- you to select precisely the packages that you need. You can use
- @command{guix search}, but finding the right package can prove to be
- tedious. When a package is missing, @command{pdflatex} and similar
- commands fail with an obscure message along the lines of:
- @example
- doc.tex: File `tikz.sty' not found.
- doc.tex:7: Emergency stop.
- @end example
- @noindent
- or, for a missing font:
- @example
- kpathsea: Running mktexmf phvr7t
- ! I can't find file `phvr7t'.
- @end example
- How do you determine what the missing package is? In the first case,
- you'll find the answer by running:
- @example
- $ guix search texlive tikz
- name: texlive-pgf
- version: 59745
- @dots{}
- @end example
- In the second case, @command{guix search} turns up nothing. Instead,
- you can search the @TeX{} Live package database using the @command{tlmgr}
- command:
- @example
- $ guix shell texlive-base -- tlmgr info phvr7t
- tlmgr: cannot find package phvr7t, searching for other matches:
- Packages containing `phvr7t' in their title/description:
- Packages containing files matching `phvr7t':
- helvetic:
- texmf-dist/fonts/tfm/adobe/helvetic/phvr7t.tfm
- texmf-dist/fonts/tfm/adobe/helvetic/phvr7tn.tfm
- texmf-dist/fonts/vf/adobe/helvetic/phvr7t.vf
- texmf-dist/fonts/vf/adobe/helvetic/phvr7tn.vf
- tex4ht:
- texmf-dist/tex4ht/ht-fonts/alias/adobe/helvetic/phvr7t.htf
- @end example
- The file is available in the @TeX{} Live @code{helvetic} package, which is
- known in Guix as @code{texlive-helvetic}. Quite a ride, but we found
- it!
- There is one important limitation though: Guix currently provides a
- subset of the @TeX{} Live packages. If you stumble upon a missing
- package, you can try and import it (@pxref{Invoking guix import}):
- @example
- guix import texlive @var{package}
- @end example
- @quotation Note
- @TeX{} Live packaging is still very much work in progress, but you can
- help! @xref{Contributing}, for more information.
- @end quotation
- @node Security Updates
- @chapter Security Updates
- @cindex security updates
- @cindex security vulnerabilities
- Occasionally, important security vulnerabilities are discovered in software
- packages and must be patched. Guix developers try hard to keep track of
- known vulnerabilities and to apply fixes as soon as possible in the
- @code{master} branch of Guix (we do not yet provide a ``stable'' branch
- containing only security updates). The @command{guix lint} tool helps
- developers find out about vulnerable versions of software packages in the
- distribution:
- @smallexample
- $ guix lint -c cve
- gnu/packages/base.scm:652:2: glibc@@2.21: probably vulnerable to CVE-2015-1781, CVE-2015-7547
- gnu/packages/gcc.scm:334:2: gcc@@4.9.3: probably vulnerable to CVE-2015-5276
- gnu/packages/image.scm:312:2: openjpeg@@2.1.0: probably vulnerable to CVE-2016-1923, CVE-2016-1924
- @dots{}
- @end smallexample
- @xref{Invoking guix lint}, for more information.
- Guix follows a functional
- package management discipline (@pxref{Introduction}), which implies
- that, when a package is changed, @emph{every package that depends on it}
- must be rebuilt. This can significantly slow down the deployment of
- fixes in core packages such as libc or Bash, since basically the whole
- distribution would need to be rebuilt. Using pre-built binaries helps
- (@pxref{Substitutes}), but deployment may still take more time than
- desired.
- @cindex grafts
- To address this, Guix implements @dfn{grafts}, a mechanism that allows
- for fast deployment of critical updates without the costs associated
- with a whole-distribution rebuild. The idea is to rebuild only the
- package that needs to be patched, and then to ``graft'' it onto packages
- explicitly installed by the user and that were previously referring to
- the original package. The cost of grafting is typically very low, and
- order of magnitudes lower than a full rebuild of the dependency chain.
- @cindex replacements of packages, for grafts
- For instance, suppose a security update needs to be applied to Bash.
- Guix developers will provide a package definition for the ``fixed''
- Bash, say @code{bash-fixed}, in the usual way (@pxref{Defining
- Packages}). Then, the original package definition is augmented with a
- @code{replacement} field pointing to the package containing the bug fix:
- @lisp
- (define bash
- (package
- (name "bash")
- ;; @dots{}
- (replacement bash-fixed)))
- @end lisp
- From there on, any package depending directly or indirectly on Bash---as
- reported by @command{guix gc --requisites} (@pxref{Invoking guix
- gc})---that is installed is automatically ``rewritten'' to refer to
- @code{bash-fixed} instead of @code{bash}. This grafting process takes
- time proportional to the size of the package, usually less than a
- minute for an ``average'' package on a recent machine. Grafting is
- recursive: when an indirect dependency requires grafting, then grafting
- ``propagates'' up to the package that the user is installing.
- Currently, the length of the name and version of the graft and that of
- the package it replaces (@code{bash-fixed} and @code{bash} in the example
- above) must be equal. This restriction mostly comes from the fact that
- grafting works by patching files, including binary files, directly.
- Other restrictions may apply: for instance, when adding a graft to a
- package providing a shared library, the original shared library and its
- replacement must have the same @code{SONAME} and be binary-compatible.
- The @option{--no-grafts} command-line option allows you to forcefully
- avoid grafting (@pxref{Common Build Options, @option{--no-grafts}}).
- Thus, the command:
- @example
- guix build bash --no-grafts
- @end example
- @noindent
- returns the store file name of the original Bash, whereas:
- @example
- guix build bash
- @end example
- @noindent
- returns the store file name of the ``fixed'', replacement Bash. This
- allows you to distinguish between the two variants of Bash.
- To verify which Bash your whole profile refers to, you can run
- (@pxref{Invoking guix gc}):
- @example
- guix gc -R $(readlink -f ~/.guix-profile) | grep bash
- @end example
- @noindent
- @dots{} and compare the store file names that you get with those above.
- Likewise for a complete Guix system generation:
- @example
- guix gc -R $(guix system build my-config.scm) | grep bash
- @end example
- Lastly, to check which Bash running processes are using, you can use the
- @command{lsof} command:
- @example
- lsof | grep /gnu/store/.*bash
- @end example
- @node Bootstrapping
- @chapter Bootstrapping
- @c Adapted from the ELS 2013 paper.
- @cindex bootstrapping
- Bootstrapping in our context refers to how the distribution gets built
- ``from nothing''. Remember that the build environment of a derivation
- contains nothing but its declared inputs (@pxref{Introduction}). So
- there's an obvious chicken-and-egg problem: how does the first package
- get built? How does the first compiler get compiled?
- It is tempting to think of this question as one that only die-hard
- hackers may care about. However, while the answer to that question is
- technical in nature, its implications are wide-ranging. How the
- distribution is bootstrapped defines the extent to which we, as
- individuals and as a collective of users and hackers, can trust the
- software we run. It is a central concern from the standpoint of
- @emph{security} and from a @emph{user freedom} viewpoint.
- @cindex bootstrap binaries
- The GNU system is primarily made of C code, with libc at its core. The
- GNU build system itself assumes the availability of a Bourne shell and
- command-line tools provided by GNU Coreutils, Awk, Findutils, `sed', and
- `grep'. Furthermore, build programs---programs that run
- @code{./configure}, @code{make}, etc.---are written in Guile Scheme
- (@pxref{Derivations}). Consequently, to be able to build anything at
- all, from scratch, Guix relies on pre-built binaries of Guile, GCC,
- Binutils, libc, and the other packages mentioned above---the
- @dfn{bootstrap binaries}.
- These bootstrap binaries are ``taken for granted'', though we can also
- re-create them if needed (@pxref{Preparing to Use the Bootstrap
- Binaries}).
- @menu
- * Reduced Binary Seed Bootstrap:: A Bootstrap worthy of GNU.
- * Preparing to Use the Bootstrap Binaries:: Building that what matters most.
- @end menu
- @node Reduced Binary Seed Bootstrap
- @section The Reduced Binary Seed Bootstrap
- Guix---like other GNU/Linux distributions---is traditionally bootstrapped from
- a set of bootstrap binaries: Bourne shell, command-line tools provided by GNU
- Coreutils, Awk, Findutils, `sed', and `grep' and Guile, GCC, Binutils, and the
- GNU C Library (@pxref{Bootstrapping}). Usually, these bootstrap binaries are
- ``taken for granted.''
- Taking the bootstrap binaries for granted means that we consider them to
- be a correct and trustworthy ``seed'' for building the complete system.
- Therein lies a problem: the combined size of these bootstrap binaries is
- about 250MB (@pxref{Bootstrappable Builds,,, mes, GNU Mes}). Auditing
- or even inspecting these is next to impossible.
- For @code{i686-linux} and @code{x86_64-linux}, Guix now features a
- ``Reduced Binary Seed'' bootstrap @footnote{We would like to say: ``Full
- Source Bootstrap'' and while we are working towards that goal it would
- be hyperbole to use that term for what we do now.}.
- The Reduced Binary Seed bootstrap removes the most critical tools---from a
- trust perspective---from the bootstrap binaries: GCC, Binutils and the GNU C
- Library are replaced by: @code{bootstrap-mescc-tools} (a tiny assembler and
- linker) and @code{bootstrap-mes} (a small Scheme Interpreter and a C compiler
- written in Scheme and the Mes C Library, built for TinyCC and for GCC).
- Using these new binary seeds the ``missing'' Binutils, GCC, and the GNU
- C Library are built from source. From here on the more traditional
- bootstrap process resumes. This approach has reduced the bootstrap
- binaries in size to about 145MB in Guix v1.1.
- The next step that Guix has taken is to replace the shell and all its
- utilities with implementations in Guile Scheme, the @emph{Scheme-only
- bootstrap}. Gash (@pxref{Gash,,, gash, The Gash manual}) is a
- POSIX-compatible shell that replaces Bash, and it comes with Gash Utils
- which has minimalist replacements for Awk, the GNU Core Utilities, Grep,
- Gzip, Sed, and Tar. The rest of the bootstrap binary seeds that were
- removed are now built from source.
- Building the GNU System from source is currently only possible by adding
- some historical GNU packages as intermediate steps@footnote{Packages
- such as @code{gcc-2.95.3}, @code{binutils-2.14}, @code{glibc-2.2.5},
- @code{gzip-1.2.4}, @code{tar-1.22}, and some others. For details, see
- @file{gnu/packages/commencement.scm}.}. As Gash and Gash Utils mature,
- and GNU packages become more bootstrappable again (e.g., new releases of
- GNU Sed will also ship as gzipped tarballs again, as alternative to the
- hard to bootstrap @code{xz}-compression), this set of added packages can
- hopefully be reduced again.
- The graph below shows the resulting dependency graph for
- @code{gcc-core-mesboot0}, the bootstrap compiler used for the
- traditional bootstrap of the rest of the Guix System.
- @c ./pre-inst-env guix graph -e '(@@ (gnu packages commencement) gcc-core-mesboot0)' | sed -re 's,((bootstrap-mescc-tools|bootstrap-mes|guile-bootstrap).*shape =) box,\1 ellipse,' > doc/images/gcc-core-mesboot0-graph.dot
- @image{images/gcc-core-mesboot0-graph,6in,,Dependency graph of gcc-core-mesboot0}
- The only significant binary bootstrap seeds that remain@footnote{
- Ignoring the 68KB @code{mescc-tools}; that will be removed later,
- together with @code{mes}.} are a Scheme interpreter and a Scheme
- compiler: GNU Mes and GNU Guile@footnote{Not shown in this graph are the
- static binaries for @file{bash}, @code{tar}, and @code{xz} that are used
- to get Guile running.}.
- This further reduction has brought down the size of the binary seed to
- about 60MB for @code{i686-linux} and @code{x86_64-linux}.
- Work is ongoing to remove all binary blobs from our free software
- bootstrap stack, working towards a Full Source Bootstrap. Also ongoing
- is work to bring these bootstraps to the @code{arm-linux} and
- @code{aarch64-linux} architectures and to the Hurd.
- If you are interested, join us on @samp{#bootstrappable} on the Freenode
- IRC network or discuss on @email{bug-mes@@gnu.org} or
- @email{gash-devel@@nongnu.org}.
- @node Preparing to Use the Bootstrap Binaries
- @section Preparing to Use the Bootstrap Binaries
- @c As of Emacs 24.3, Info-mode displays the image, but since it's a
- @c large image, it's hard to scroll. Oh well.
- @image{images/bootstrap-graph,6in,,Dependency graph of the early bootstrap derivations}
- The figure above shows the very beginning of the dependency graph of the
- distribution, corresponding to the package definitions of the @code{(gnu
- packages bootstrap)} module. A similar figure can be generated with
- @command{guix graph} (@pxref{Invoking guix graph}), along the lines of:
- @example
- guix graph -t derivation \
- -e '(@@@@ (gnu packages bootstrap) %bootstrap-gcc)' \
- | dot -Tps > gcc.ps
- @end example
- or, for the further Reduced Binary Seed bootstrap
- @example
- guix graph -t derivation \
- -e '(@@@@ (gnu packages bootstrap) %bootstrap-mes)' \
- | dot -Tps > mes.ps
- @end example
- At this level of detail, things are
- slightly complex. First, Guile itself consists of an ELF executable,
- along with many source and compiled Scheme files that are dynamically
- loaded when it runs. This gets stored in the @file{guile-2.0.7.tar.xz}
- tarball shown in this graph. This tarball is part of Guix's ``source''
- distribution, and gets inserted into the store with @code{add-to-store}
- (@pxref{The Store}).
- But how do we write a derivation that unpacks this tarball and adds it
- to the store? To solve this problem, the @code{guile-bootstrap-2.0.drv}
- derivation---the first one that gets built---uses @code{bash} as its
- builder, which runs @code{build-bootstrap-guile.sh}, which in turn calls
- @code{tar} to unpack the tarball. Thus, @file{bash}, @file{tar},
- @file{xz}, and @file{mkdir} are statically-linked binaries, also part of
- the Guix source distribution, whose sole purpose is to allow the Guile
- tarball to be unpacked.
- Once @code{guile-bootstrap-2.0.drv} is built, we have a functioning
- Guile that can be used to run subsequent build programs. Its first task
- is to download tarballs containing the other pre-built binaries---this
- is what the @file{.tar.xz.drv} derivations do. Guix modules such as
- @code{ftp-client.scm} are used for this purpose. The
- @code{module-import.drv} derivations import those modules in a directory
- in the store, using the original layout. The
- @code{module-import-compiled.drv} derivations compile those modules, and
- write them in an output directory with the right layout. This
- corresponds to the @code{#:modules} argument of
- @code{build-expression->derivation} (@pxref{Derivations}).
- Finally, the various tarballs are unpacked by the derivations
- @code{gcc-bootstrap-0.drv}, @code{glibc-bootstrap-0.drv}, or
- @code{bootstrap-mes-0.drv} and @code{bootstrap-mescc-tools-0.drv}, at which
- point we have a working C tool chain.
- @unnumberedsec Building the Build Tools
- Bootstrapping is complete when we have a full tool chain that does not
- depend on the pre-built bootstrap tools discussed above. This
- no-dependency requirement is verified by checking whether the files of
- the final tool chain contain references to the @file{/gnu/store}
- directories of the bootstrap inputs. The process that leads to this
- ``final'' tool chain is described by the package definitions found in
- the @code{(gnu packages commencement)} module.
- The @command{guix graph} command allows us to ``zoom out'' compared to
- the graph above, by looking at the level of package objects instead of
- individual derivations---remember that a package may translate to
- several derivations, typically one derivation to download its source,
- one to build the Guile modules it needs, and one to actually build the
- package from source. The command:
- @example
- guix graph -t bag \
- -e '(@@@@ (gnu packages commencement)
- glibc-final-with-bootstrap-bash)' | xdot -
- @end example
- @noindent
- displays the dependency graph leading to the ``final'' C
- library@footnote{You may notice the @code{glibc-intermediate} label,
- suggesting that it is not @emph{quite} final, but as a good
- approximation, we will consider it final.}, depicted below.
- @image{images/bootstrap-packages,6in,,Dependency graph of the early packages}
- @c See <https://lists.gnu.org/archive/html/gnu-system-discuss/2012-10/msg00000.html>.
- The first tool that gets built with the bootstrap binaries is
- GNU@tie{}Make---noted @code{make-boot0} above---which is a prerequisite
- for all the following packages. From there Findutils and Diffutils get
- built.
- Then come the first-stage Binutils and GCC, built as pseudo cross
- tools---i.e., with @option{--target} equal to @option{--host}. They are
- used to build libc. Thanks to this cross-build trick, this libc is
- guaranteed not to hold any reference to the initial tool chain.
- From there the final Binutils and GCC (not shown above) are built. GCC
- uses @command{ld} from the final Binutils, and links programs against
- the just-built libc. This tool chain is used to build the other
- packages used by Guix and by the GNU Build System: Guile, Bash,
- Coreutils, etc.
- And voilà! At this point we have the complete set of build tools that
- the GNU Build System expects. These are in the @code{%final-inputs}
- variable of the @code{(gnu packages commencement)} module, and are
- implicitly used by any package that uses @code{gnu-build-system}
- (@pxref{Build Systems, @code{gnu-build-system}}).
- @unnumberedsec Building the Bootstrap Binaries
- @cindex bootstrap binaries
- Because the final tool chain does not depend on the bootstrap binaries,
- those rarely need to be updated. Nevertheless, it is useful to have an
- automated way to produce them, should an update occur, and this is what
- the @code{(gnu packages make-bootstrap)} module provides.
- The following command builds the tarballs containing the bootstrap binaries
- (Binutils, GCC, glibc, for the traditional bootstrap and linux-libre-headers,
- bootstrap-mescc-tools, bootstrap-mes for the Reduced Binary Seed bootstrap,
- and Guile, and a tarball containing a mixture of Coreutils and other basic
- command-line tools):
- @example
- guix build bootstrap-tarballs
- @end example
- The generated tarballs are those that should be referred to in the
- @code{(gnu packages bootstrap)} module mentioned at the beginning of
- this section.
- Still here? Then perhaps by now you've started to wonder: when do we
- reach a fixed point? That is an interesting question! The answer is
- unknown, but if you would like to investigate further (and have
- significant computational and storage resources to do so), then let us
- know.
- @unnumberedsec Reducing the Set of Bootstrap Binaries
- Our traditional bootstrap includes GCC, GNU Libc, Guile, etc. That's a lot of
- binary code! Why is that a problem? It's a problem because these big chunks
- of binary code are practically non-auditable, which makes it hard to establish
- what source code produced them. Every unauditable binary also leaves us
- vulnerable to compiler backdoors as described by Ken Thompson in the 1984
- paper @emph{Reflections on Trusting Trust}.
- This is mitigated by the fact that our bootstrap binaries were generated
- from an earlier Guix revision. Nevertheless it lacks the level of
- transparency that we get in the rest of the package dependency graph,
- where Guix always gives us a source-to-binary mapping. Thus, our goal
- is to reduce the set of bootstrap binaries to the bare minimum.
- The @uref{https://bootstrappable.org, Bootstrappable.org web site} lists
- on-going projects to do that. One of these is about replacing the
- bootstrap GCC with a sequence of assemblers, interpreters, and compilers
- of increasing complexity, which could be built from source starting from
- a simple and auditable assembler.
- Our first major achievement is the replacement of of GCC, the GNU C Library
- and Binutils by MesCC-Tools (a simple hex linker and macro assembler) and Mes
- (@pxref{Top, GNU Mes Reference Manual,, mes, GNU Mes}, a Scheme interpreter
- and C compiler in Scheme). Neither MesCC-Tools nor Mes can be fully
- bootstrapped yet and thus we inject them as binary seeds. We call this the
- Reduced Binary Seed bootstrap, as it has halved the size of our bootstrap
- binaries! Also, it has eliminated the C compiler binary; i686-linux and
- x86_64-linux Guix packages are now bootstrapped without any binary C compiler.
- Work is ongoing to make MesCC-Tools and Mes fully bootstrappable and we are
- also looking at any other bootstrap binaries. Your help is welcome!
- @node Porting
- @chapter Porting to a New Platform
- As discussed above, the GNU distribution is self-contained, and
- self-containment is achieved by relying on pre-built ``bootstrap
- binaries'' (@pxref{Bootstrapping}). These binaries are specific to an
- operating system kernel, CPU architecture, and application binary
- interface (ABI). Thus, to port the distribution to a platform that is
- not yet supported, one must build those bootstrap binaries, and update
- the @code{(gnu packages bootstrap)} module to use them on that platform.
- Fortunately, Guix can @emph{cross compile} those bootstrap binaries.
- When everything goes well, and assuming the GNU tool chain supports the
- target platform, this can be as simple as running a command like this
- one:
- @example
- guix build --target=armv5tel-linux-gnueabi bootstrap-tarballs
- @end example
- For this to work, the @code{glibc-dynamic-linker} procedure in
- @code{(gnu packages bootstrap)} must be augmented to return the right
- file name for libc's dynamic linker on that platform; likewise,
- @code{system->linux-architecture} in @code{(gnu packages linux)} must be
- taught about the new platform.
- Once these are built, the @code{(gnu packages bootstrap)} module needs
- to be updated to refer to these binaries on the target platform. That
- is, the hashes and URLs of the bootstrap tarballs for the new platform
- must be added alongside those of the currently supported platforms. The
- bootstrap Guile tarball is treated specially: it is expected to be
- available locally, and @file{gnu/local.mk} has rules to download it for
- the supported architectures; a rule for the new platform must be added
- as well.
- In practice, there may be some complications. First, it may be that the
- extended GNU triplet that specifies an ABI (like the @code{eabi} suffix
- above) is not recognized by all the GNU tools. Typically, glibc
- recognizes some of these, whereas GCC uses an extra @option{--with-abi}
- configure flag (see @code{gcc.scm} for examples of how to handle this).
- Second, some of the required packages could fail to build for that
- platform. Lastly, the generated binaries could be broken for some
- reason.
- @c *********************************************************************
- @include contributing.texi
- @c *********************************************************************
- @node Acknowledgments
- @chapter Acknowledgments
- Guix is based on the @uref{https://nixos.org/nix/, Nix package manager},
- which was designed and
- implemented by Eelco Dolstra, with contributions from other people (see
- the @file{nix/AUTHORS} file in Guix). Nix pioneered functional package
- management, and promoted unprecedented features, such as transactional
- package upgrades and rollbacks, per-user profiles, and referentially
- transparent build processes. Without this work, Guix would not exist.
- The Nix-based software distributions, Nixpkgs and NixOS, have also been
- an inspiration for Guix.
- GNU@tie{}Guix itself is a collective work with contributions from a
- number of people. See the @file{AUTHORS} file in Guix for more
- information on these fine people. The @file{THANKS} file lists people
- who have helped by reporting bugs, taking care of the infrastructure,
- providing artwork and themes, making suggestions, and more---thank you!
- @c *********************************************************************
- @node GNU Free Documentation License
- @appendix GNU Free Documentation License
- @cindex license, GNU Free Documentation License
- @include fdl-1.3.texi
- @c *********************************************************************
- @node Concept Index
- @unnumbered Concept Index
- @printindex cp
- @node Programming Index
- @unnumbered Programming Index
- @syncodeindex tp fn
- @syncodeindex vr fn
- @printindex fn
- @bye
- @c Local Variables:
- @c ispell-local-dictionary: "american";
- @c End:
|
