| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566156715681569157015711572157315741575157615771578157915801581158215831584158515861587158815891590159115921593159415951596159715981599160016011602160316041605160616071608160916101611161216131614161516161617161816191620162116221623162416251626162716281629163016311632163316341635163616371638163916401641164216431644164516461647164816491650165116521653165416551656165716581659166016611662166316641665166616671668166916701671167216731674167516761677167816791680168116821683168416851686168716881689169016911692169316941695169616971698169917001701170217031704170517061707170817091710171117121713171417151716171717181719172017211722172317241725172617271728172917301731173217331734173517361737173817391740174117421743174417451746174717481749175017511752175317541755175617571758175917601761176217631764176517661767176817691770177117721773177417751776177717781779178017811782178317841785178617871788178917901791179217931794179517961797179817991800180118021803180418051806180718081809181018111812181318141815181618171818181918201821182218231824182518261827182818291830183118321833183418351836183718381839184018411842184318441845184618471848184918501851185218531854185518561857185818591860186118621863186418651866186718681869187018711872187318741875187618771878187918801881188218831884188518861887188818891890189118921893189418951896189718981899190019011902190319041905190619071908190919101911191219131914191519161917191819191920192119221923192419251926192719281929193019311932193319341935193619371938193919401941194219431944194519461947194819491950195119521953195419551956195719581959196019611962196319641965196619671968196919701971197219731974197519761977197819791980198119821983198419851986198719881989199019911992199319941995199619971998199920002001200220032004200520062007200820092010201120122013201420152016201720182019202020212022202320242025202620272028202920302031203220332034203520362037203820392040204120422043204420452046204720482049205020512052205320542055205620572058205920602061206220632064206520662067206820692070207120722073207420752076207720782079208020812082208320842085208620872088208920902091209220932094209520962097209820992100210121022103210421052106210721082109211021112112211321142115211621172118211921202121212221232124212521262127212821292130213121322133213421352136213721382139214021412142214321442145214621472148214921502151215221532154215521562157215821592160216121622163216421652166216721682169217021712172217321742175217621772178217921802181218221832184218521862187218821892190219121922193219421952196219721982199220022012202220322042205220622072208220922102211221222132214221522162217221822192220222122222223222422252226222722282229223022312232223322342235223622372238223922402241224222432244224522462247224822492250225122522253225422552256225722582259226022612262226322642265226622672268226922702271227222732274227522762277227822792280228122822283228422852286228722882289229022912292229322942295229622972298229923002301230223032304230523062307230823092310231123122313231423152316231723182319232023212322232323242325232623272328232923302331233223332334233523362337233823392340234123422343234423452346234723482349235023512352235323542355235623572358235923602361236223632364236523662367236823692370237123722373237423752376237723782379238023812382238323842385238623872388238923902391239223932394239523962397239823992400240124022403240424052406240724082409241024112412241324142415241624172418241924202421242224232424242524262427242824292430243124322433243424352436243724382439244024412442244324442445244624472448244924502451245224532454245524562457245824592460246124622463246424652466246724682469247024712472247324742475247624772478247924802481248224832484248524862487248824892490249124922493249424952496249724982499250025012502250325042505250625072508250925102511251225132514251525162517251825192520252125222523252425252526252725282529253025312532253325342535253625372538253925402541254225432544254525462547254825492550255125522553255425552556255725582559256025612562256325642565256625672568256925702571257225732574257525762577257825792580258125822583258425852586258725882589259025912592259325942595259625972598259926002601260226032604260526062607260826092610261126122613261426152616261726182619262026212622262326242625262626272628262926302631263226332634263526362637263826392640264126422643264426452646264726482649265026512652265326542655265626572658265926602661266226632664266526662667266826692670267126722673267426752676267726782679268026812682268326842685268626872688268926902691269226932694269526962697269826992700270127022703270427052706270727082709271027112712271327142715271627172718271927202721272227232724272527262727272827292730273127322733273427352736273727382739274027412742274327442745274627472748274927502751275227532754275527562757275827592760276127622763276427652766276727682769277027712772277327742775277627772778277927802781278227832784278527862787278827892790279127922793279427952796279727982799280028012802280328042805280628072808280928102811281228132814281528162817281828192820282128222823282428252826282728282829283028312832283328342835283628372838283928402841284228432844284528462847284828492850285128522853285428552856285728582859286028612862286328642865286628672868286928702871287228732874287528762877287828792880288128822883288428852886288728882889289028912892289328942895289628972898289929002901290229032904290529062907290829092910291129122913291429152916291729182919292029212922292329242925292629272928292929302931293229332934293529362937293829392940294129422943294429452946294729482949295029512952295329542955295629572958295929602961296229632964296529662967296829692970297129722973297429752976297729782979298029812982298329842985298629872988298929902991299229932994299529962997299829993000300130023003300430053006300730083009301030113012301330143015301630173018301930203021302230233024302530263027302830293030303130323033303430353036303730383039304030413042304330443045304630473048304930503051305230533054305530563057305830593060306130623063306430653066306730683069307030713072307330743075307630773078307930803081308230833084308530863087308830893090309130923093309430953096309730983099310031013102310331043105310631073108310931103111311231133114311531163117311831193120312131223123312431253126312731283129313031313132313331343135313631373138313931403141314231433144314531463147314831493150315131523153315431553156315731583159316031613162316331643165316631673168316931703171317231733174317531763177317831793180318131823183318431853186318731883189319031913192319331943195319631973198319932003201320232033204320532063207320832093210321132123213321432153216321732183219322032213222322332243225322632273228322932303231323232333234323532363237323832393240324132423243324432453246324732483249325032513252325332543255325632573258325932603261326232633264326532663267326832693270327132723273327432753276327732783279328032813282328332843285328632873288328932903291329232933294329532963297329832993300330133023303330433053306330733083309331033113312331333143315331633173318331933203321332233233324332533263327332833293330333133323333333433353336333733383339334033413342334333443345334633473348334933503351335233533354335533563357335833593360336133623363336433653366336733683369337033713372337333743375337633773378337933803381338233833384338533863387338833893390339133923393339433953396339733983399340034013402340334043405340634073408340934103411341234133414341534163417341834193420342134223423342434253426342734283429343034313432343334343435343634373438343934403441344234433444344534463447344834493450345134523453345434553456345734583459346034613462346334643465346634673468346934703471347234733474347534763477347834793480348134823483348434853486348734883489349034913492349334943495349634973498349935003501350235033504350535063507350835093510351135123513351435153516351735183519352035213522352335243525352635273528352935303531353235333534353535363537353835393540354135423543354435453546354735483549355035513552355335543555355635573558355935603561356235633564356535663567356835693570357135723573357435753576357735783579358035813582358335843585358635873588358935903591359235933594359535963597359835993600360136023603360436053606360736083609361036113612361336143615361636173618361936203621362236233624362536263627362836293630363136323633363436353636363736383639364036413642364336443645364636473648364936503651365236533654365536563657365836593660366136623663366436653666366736683669367036713672367336743675367636773678367936803681368236833684368536863687368836893690369136923693369436953696369736983699370037013702370337043705370637073708370937103711371237133714371537163717371837193720372137223723372437253726372737283729373037313732373337343735373637373738373937403741374237433744374537463747374837493750375137523753375437553756375737583759376037613762376337643765376637673768376937703771377237733774377537763777377837793780378137823783378437853786378737883789379037913792379337943795379637973798379938003801380238033804380538063807380838093810381138123813381438153816381738183819382038213822382338243825382638273828382938303831383238333834383538363837383838393840384138423843384438453846384738483849385038513852385338543855385638573858385938603861386238633864386538663867386838693870387138723873387438753876387738783879388038813882388338843885388638873888388938903891389238933894389538963897389838993900390139023903390439053906390739083909391039113912391339143915391639173918391939203921392239233924392539263927392839293930393139323933393439353936393739383939394039413942394339443945394639473948394939503951395239533954395539563957395839593960396139623963396439653966396739683969397039713972397339743975397639773978397939803981398239833984398539863987398839893990399139923993399439953996399739983999400040014002400340044005400640074008400940104011401240134014401540164017401840194020402140224023402440254026402740284029403040314032403340344035403640374038403940404041404240434044404540464047404840494050405140524053405440554056405740584059406040614062406340644065406640674068406940704071407240734074407540764077407840794080408140824083408440854086408740884089409040914092409340944095409640974098409941004101410241034104410541064107410841094110411141124113411441154116411741184119412041214122412341244125412641274128412941304131413241334134413541364137413841394140414141424143414441454146414741484149415041514152415341544155415641574158415941604161416241634164416541664167416841694170417141724173417441754176417741784179418041814182418341844185418641874188418941904191419241934194419541964197419841994200420142024203420442054206420742084209421042114212421342144215421642174218421942204221422242234224422542264227422842294230423142324233423442354236423742384239424042414242424342444245424642474248424942504251425242534254425542564257425842594260426142624263426442654266426742684269427042714272427342744275427642774278427942804281428242834284428542864287428842894290429142924293429442954296429742984299430043014302430343044305430643074308430943104311431243134314431543164317431843194320432143224323432443254326432743284329433043314332433343344335433643374338433943404341434243434344434543464347434843494350435143524353435443554356435743584359436043614362436343644365436643674368436943704371437243734374437543764377437843794380438143824383438443854386438743884389439043914392439343944395439643974398439944004401440244034404440544064407440844094410441144124413441444154416441744184419442044214422442344244425442644274428442944304431443244334434443544364437443844394440444144424443444444454446444744484449445044514452445344544455445644574458445944604461446244634464446544664467446844694470447144724473447444754476447744784479448044814482448344844485448644874488448944904491449244934494449544964497449844994500450145024503450445054506450745084509451045114512451345144515451645174518451945204521452245234524452545264527452845294530453145324533453445354536453745384539454045414542454345444545454645474548454945504551455245534554455545564557455845594560456145624563456445654566456745684569457045714572457345744575457645774578457945804581458245834584458545864587458845894590459145924593459445954596459745984599460046014602460346044605460646074608460946104611461246134614461546164617461846194620462146224623462446254626462746284629463046314632463346344635463646374638463946404641464246434644464546464647464846494650465146524653465446554656465746584659466046614662466346644665466646674668466946704671467246734674467546764677467846794680468146824683468446854686468746884689469046914692469346944695469646974698469947004701470247034704470547064707470847094710471147124713471447154716471747184719472047214722472347244725472647274728472947304731473247334734473547364737473847394740474147424743474447454746474747484749475047514752475347544755475647574758475947604761476247634764476547664767476847694770477147724773477447754776477747784779478047814782478347844785478647874788478947904791479247934794479547964797479847994800480148024803480448054806480748084809481048114812481348144815481648174818481948204821482248234824482548264827482848294830483148324833483448354836483748384839484048414842484348444845484648474848484948504851485248534854485548564857485848594860486148624863486448654866486748684869487048714872487348744875487648774878487948804881488248834884488548864887488848894890489148924893489448954896489748984899490049014902490349044905490649074908490949104911491249134914491549164917491849194920492149224923492449254926492749284929493049314932493349344935493649374938493949404941494249434944494549464947494849494950495149524953495449554956495749584959496049614962496349644965496649674968496949704971497249734974497549764977497849794980498149824983498449854986498749884989499049914992499349944995499649974998499950005001500250035004500550065007500850095010501150125013501450155016501750185019502050215022502350245025502650275028502950305031503250335034503550365037503850395040504150425043504450455046504750485049505050515052505350545055505650575058505950605061506250635064506550665067506850695070507150725073507450755076507750785079508050815082508350845085508650875088508950905091509250935094509550965097509850995100510151025103510451055106510751085109511051115112511351145115511651175118511951205121512251235124512551265127512851295130513151325133513451355136513751385139514051415142514351445145514651475148514951505151515251535154515551565157515851595160516151625163516451655166516751685169517051715172517351745175517651775178517951805181518251835184518551865187518851895190519151925193519451955196519751985199520052015202520352045205520652075208520952105211521252135214521552165217521852195220522152225223522452255226522752285229523052315232523352345235523652375238523952405241524252435244524552465247524852495250525152525253525452555256525752585259526052615262526352645265526652675268526952705271527252735274527552765277527852795280528152825283528452855286528752885289529052915292529352945295529652975298529953005301530253035304530553065307530853095310531153125313531453155316531753185319532053215322532353245325532653275328532953305331533253335334533553365337533853395340534153425343534453455346534753485349535053515352535353545355535653575358535953605361536253635364536553665367536853695370537153725373537453755376537753785379538053815382538353845385538653875388538953905391539253935394539553965397539853995400540154025403540454055406540754085409541054115412541354145415541654175418541954205421542254235424542554265427542854295430543154325433543454355436543754385439544054415442544354445445544654475448544954505451545254535454545554565457545854595460546154625463546454655466546754685469547054715472547354745475547654775478547954805481548254835484548554865487548854895490549154925493549454955496549754985499550055015502550355045505550655075508550955105511551255135514551555165517551855195520552155225523552455255526552755285529553055315532553355345535553655375538553955405541554255435544554555465547554855495550555155525553555455555556555755585559556055615562556355645565556655675568556955705571557255735574557555765577557855795580558155825583558455855586558755885589559055915592559355945595559655975598559956005601560256035604560556065607560856095610561156125613561456155616561756185619562056215622562356245625562656275628562956305631563256335634563556365637563856395640564156425643564456455646564756485649565056515652565356545655565656575658565956605661566256635664566556665667566856695670567156725673567456755676567756785679568056815682568356845685568656875688568956905691569256935694569556965697569856995700570157025703570457055706570757085709571057115712571357145715571657175718571957205721572257235724572557265727572857295730573157325733573457355736573757385739574057415742574357445745574657475748574957505751575257535754575557565757575857595760576157625763576457655766576757685769577057715772577357745775577657775778577957805781578257835784578557865787578857895790579157925793579457955796579757985799580058015802580358045805580658075808580958105811581258135814581558165817581858195820582158225823582458255826582758285829583058315832583358345835583658375838583958405841584258435844584558465847584858495850585158525853585458555856585758585859586058615862586358645865586658675868586958705871587258735874587558765877587858795880588158825883588458855886588758885889589058915892589358945895589658975898589959005901590259035904590559065907590859095910591159125913591459155916591759185919592059215922592359245925592659275928592959305931593259335934593559365937593859395940594159425943594459455946594759485949595059515952595359545955595659575958595959605961596259635964596559665967596859695970597159725973597459755976597759785979598059815982598359845985598659875988598959905991599259935994599559965997599859996000600160026003600460056006600760086009601060116012601360146015601660176018601960206021602260236024602560266027602860296030603160326033603460356036603760386039604060416042604360446045604660476048604960506051605260536054605560566057605860596060606160626063606460656066606760686069607060716072607360746075607660776078607960806081608260836084608560866087608860896090609160926093609460956096609760986099610061016102610361046105610661076108610961106111611261136114611561166117611861196120612161226123612461256126612761286129613061316132613361346135613661376138613961406141614261436144614561466147614861496150615161526153615461556156615761586159616061616162616361646165616661676168616961706171617261736174617561766177617861796180618161826183618461856186618761886189619061916192619361946195619661976198619962006201620262036204620562066207620862096210621162126213621462156216621762186219622062216222622362246225622662276228622962306231623262336234623562366237623862396240624162426243624462456246624762486249625062516252625362546255625662576258625962606261626262636264626562666267626862696270627162726273627462756276627762786279628062816282628362846285628662876288628962906291629262936294629562966297629862996300630163026303630463056306630763086309631063116312631363146315631663176318631963206321632263236324632563266327632863296330633163326333633463356336633763386339634063416342634363446345634663476348634963506351635263536354635563566357635863596360636163626363636463656366636763686369637063716372637363746375637663776378637963806381638263836384638563866387638863896390639163926393639463956396639763986399640064016402640364046405640664076408640964106411641264136414641564166417641864196420642164226423642464256426642764286429643064316432643364346435643664376438643964406441644264436444644564466447644864496450645164526453645464556456645764586459646064616462646364646465646664676468646964706471647264736474647564766477647864796480648164826483648464856486648764886489649064916492649364946495649664976498649965006501650265036504650565066507650865096510651165126513651465156516651765186519652065216522652365246525652665276528652965306531653265336534653565366537653865396540654165426543654465456546654765486549655065516552655365546555655665576558655965606561656265636564656565666567656865696570657165726573657465756576657765786579658065816582658365846585658665876588658965906591659265936594659565966597659865996600660166026603660466056606660766086609661066116612661366146615661666176618661966206621662266236624662566266627662866296630663166326633663466356636663766386639664066416642664366446645664666476648664966506651665266536654665566566657665866596660666166626663666466656666666766686669667066716672667366746675667666776678667966806681668266836684668566866687668866896690669166926693669466956696669766986699670067016702670367046705670667076708670967106711671267136714671567166717671867196720672167226723672467256726672767286729673067316732673367346735673667376738673967406741674267436744674567466747674867496750675167526753675467556756675767586759676067616762676367646765676667676768676967706771677267736774677567766777677867796780678167826783678467856786678767886789679067916792679367946795679667976798679968006801680268036804680568066807680868096810681168126813681468156816681768186819682068216822682368246825682668276828682968306831683268336834683568366837683868396840684168426843684468456846684768486849685068516852685368546855685668576858685968606861686268636864686568666867686868696870687168726873687468756876687768786879688068816882688368846885688668876888688968906891689268936894689568966897689868996900690169026903690469056906690769086909691069116912691369146915691669176918691969206921692269236924692569266927692869296930693169326933693469356936693769386939694069416942694369446945694669476948694969506951695269536954695569566957695869596960696169626963696469656966696769686969697069716972697369746975697669776978697969806981698269836984698569866987698869896990699169926993699469956996699769986999700070017002700370047005700670077008700970107011701270137014701570167017701870197020702170227023702470257026702770287029703070317032703370347035703670377038703970407041704270437044704570467047704870497050705170527053705470557056705770587059706070617062706370647065706670677068706970707071707270737074707570767077707870797080708170827083708470857086708770887089709070917092709370947095709670977098709971007101710271037104710571067107710871097110711171127113711471157116711771187119712071217122712371247125712671277128712971307131713271337134713571367137713871397140714171427143714471457146714771487149715071517152715371547155715671577158715971607161716271637164716571667167716871697170717171727173717471757176717771787179718071817182718371847185718671877188718971907191719271937194719571967197719871997200720172027203720472057206720772087209721072117212721372147215721672177218721972207221722272237224722572267227722872297230723172327233723472357236723772387239724072417242724372447245724672477248724972507251725272537254725572567257725872597260726172627263726472657266726772687269727072717272727372747275727672777278727972807281728272837284728572867287728872897290729172927293729472957296729772987299730073017302730373047305730673077308730973107311731273137314731573167317731873197320732173227323732473257326732773287329733073317332733373347335733673377338733973407341734273437344734573467347734873497350735173527353735473557356735773587359736073617362736373647365736673677368736973707371737273737374737573767377737873797380738173827383738473857386738773887389739073917392739373947395739673977398739974007401740274037404740574067407740874097410741174127413741474157416741774187419742074217422742374247425742674277428742974307431743274337434743574367437743874397440744174427443744474457446744774487449745074517452745374547455745674577458745974607461746274637464746574667467746874697470747174727473747474757476747774787479748074817482748374847485748674877488748974907491749274937494749574967497749874997500750175027503750475057506750775087509751075117512751375147515751675177518751975207521752275237524752575267527752875297530753175327533753475357536753775387539754075417542754375447545754675477548754975507551755275537554755575567557755875597560756175627563756475657566756775687569757075717572757375747575757675777578757975807581758275837584758575867587758875897590759175927593759475957596759775987599760076017602760376047605760676077608760976107611761276137614761576167617761876197620762176227623762476257626762776287629763076317632763376347635763676377638763976407641764276437644764576467647764876497650765176527653765476557656765776587659766076617662766376647665766676677668766976707671767276737674767576767677767876797680768176827683768476857686768776887689769076917692769376947695769676977698769977007701770277037704770577067707770877097710771177127713771477157716771777187719772077217722772377247725772677277728772977307731773277337734773577367737773877397740774177427743774477457746774777487749775077517752775377547755775677577758775977607761776277637764776577667767776877697770777177727773777477757776777777787779778077817782778377847785778677877788778977907791779277937794779577967797779877997800780178027803780478057806780778087809781078117812781378147815781678177818781978207821782278237824782578267827782878297830783178327833783478357836783778387839784078417842784378447845784678477848784978507851785278537854785578567857785878597860786178627863786478657866786778687869787078717872787378747875787678777878787978807881788278837884788578867887788878897890789178927893789478957896789778987899790079017902790379047905790679077908790979107911791279137914791579167917791879197920792179227923792479257926792779287929793079317932793379347935793679377938793979407941794279437944794579467947794879497950795179527953795479557956795779587959796079617962796379647965796679677968796979707971797279737974797579767977797879797980798179827983798479857986798779887989799079917992799379947995799679977998799980008001800280038004800580068007800880098010801180128013801480158016801780188019802080218022802380248025802680278028802980308031803280338034803580368037803880398040804180428043804480458046804780488049805080518052805380548055805680578058805980608061806280638064806580668067806880698070807180728073807480758076807780788079808080818082808380848085808680878088808980908091809280938094809580968097809880998100810181028103810481058106810781088109811081118112811381148115811681178118811981208121812281238124812581268127812881298130813181328133813481358136813781388139814081418142814381448145814681478148814981508151815281538154815581568157815881598160816181628163816481658166816781688169817081718172817381748175817681778178817981808181818281838184818581868187818881898190819181928193819481958196819781988199820082018202820382048205820682078208820982108211821282138214821582168217821882198220822182228223822482258226822782288229823082318232823382348235823682378238823982408241824282438244824582468247824882498250825182528253825482558256825782588259826082618262826382648265826682678268826982708271827282738274827582768277827882798280828182828283828482858286828782888289829082918292829382948295829682978298829983008301830283038304830583068307830883098310831183128313831483158316831783188319832083218322832383248325832683278328832983308331833283338334833583368337833883398340834183428343834483458346834783488349835083518352835383548355835683578358835983608361836283638364836583668367836883698370837183728373837483758376837783788379838083818382838383848385838683878388838983908391839283938394839583968397839883998400840184028403840484058406840784088409841084118412841384148415841684178418841984208421842284238424842584268427842884298430843184328433843484358436843784388439844084418442844384448445844684478448844984508451845284538454845584568457845884598460846184628463846484658466846784688469847084718472847384748475847684778478847984808481848284838484848584868487848884898490849184928493849484958496849784988499850085018502850385048505850685078508850985108511851285138514851585168517851885198520852185228523852485258526852785288529853085318532853385348535853685378538853985408541854285438544854585468547854885498550855185528553855485558556855785588559856085618562856385648565856685678568856985708571857285738574857585768577857885798580858185828583858485858586858785888589859085918592859385948595859685978598859986008601860286038604860586068607860886098610861186128613861486158616861786188619862086218622862386248625862686278628862986308631863286338634863586368637863886398640864186428643864486458646864786488649865086518652865386548655865686578658865986608661866286638664866586668667866886698670867186728673867486758676867786788679868086818682868386848685868686878688868986908691869286938694869586968697869886998700870187028703870487058706870787088709871087118712871387148715871687178718871987208721872287238724872587268727872887298730873187328733873487358736873787388739874087418742874387448745874687478748874987508751875287538754875587568757875887598760876187628763876487658766876787688769877087718772877387748775877687778778877987808781878287838784878587868787878887898790879187928793879487958796879787988799880088018802880388048805880688078808880988108811881288138814881588168817881888198820882188228823882488258826882788288829883088318832883388348835883688378838883988408841884288438844884588468847884888498850885188528853885488558856885788588859886088618862886388648865886688678868886988708871887288738874887588768877887888798880888188828883888488858886888788888889889088918892889388948895889688978898889989008901890289038904890589068907890889098910891189128913891489158916891789188919892089218922892389248925892689278928892989308931893289338934893589368937893889398940894189428943894489458946894789488949895089518952895389548955895689578958895989608961896289638964896589668967896889698970897189728973897489758976897789788979898089818982898389848985898689878988898989908991899289938994899589968997899889999000900190029003900490059006900790089009901090119012901390149015901690179018901990209021902290239024902590269027902890299030903190329033903490359036903790389039904090419042904390449045904690479048904990509051905290539054905590569057905890599060906190629063906490659066906790689069907090719072907390749075907690779078907990809081908290839084908590869087908890899090909190929093909490959096909790989099910091019102910391049105910691079108910991109111911291139114911591169117911891199120912191229123912491259126912791289129913091319132913391349135913691379138913991409141914291439144914591469147914891499150915191529153915491559156915791589159916091619162916391649165916691679168916991709171917291739174917591769177917891799180918191829183918491859186918791889189919091919192919391949195919691979198919992009201920292039204920592069207920892099210921192129213921492159216921792189219922092219222922392249225922692279228922992309231923292339234923592369237923892399240924192429243924492459246924792489249925092519252925392549255925692579258925992609261926292639264926592669267926892699270927192729273927492759276927792789279928092819282928392849285928692879288928992909291929292939294929592969297929892999300930193029303930493059306930793089309931093119312931393149315931693179318931993209321932293239324932593269327932893299330933193329333933493359336933793389339934093419342934393449345934693479348934993509351935293539354935593569357935893599360936193629363936493659366936793689369937093719372937393749375937693779378937993809381938293839384938593869387938893899390939193929393939493959396939793989399940094019402940394049405940694079408940994109411941294139414941594169417941894199420942194229423942494259426942794289429943094319432943394349435943694379438943994409441944294439444944594469447944894499450945194529453945494559456945794589459946094619462946394649465946694679468946994709471947294739474947594769477947894799480948194829483948494859486948794889489949094919492949394949495949694979498949995009501950295039504950595069507950895099510951195129513951495159516951795189519952095219522952395249525952695279528952995309531953295339534953595369537953895399540954195429543954495459546954795489549955095519552955395549555955695579558955995609561956295639564956595669567956895699570957195729573957495759576957795789579958095819582958395849585958695879588958995909591959295939594959595969597959895999600960196029603960496059606960796089609961096119612961396149615961696179618961996209621962296239624962596269627962896299630963196329633963496359636963796389639964096419642964396449645964696479648964996509651965296539654965596569657965896599660966196629663966496659666966796689669967096719672967396749675967696779678967996809681968296839684968596869687968896899690969196929693969496959696969796989699970097019702970397049705970697079708970997109711971297139714971597169717971897199720972197229723972497259726972797289729973097319732973397349735973697379738973997409741974297439744974597469747974897499750975197529753975497559756975797589759976097619762976397649765976697679768976997709771977297739774977597769777977897799780978197829783978497859786978797889789979097919792979397949795979697979798979998009801980298039804980598069807980898099810981198129813981498159816981798189819982098219822982398249825982698279828982998309831983298339834983598369837983898399840984198429843984498459846984798489849985098519852985398549855985698579858985998609861986298639864986598669867986898699870987198729873987498759876987798789879988098819882988398849885988698879888988998909891989298939894989598969897989898999900990199029903990499059906990799089909991099119912991399149915991699179918991999209921992299239924992599269927992899299930993199329933993499359936993799389939994099419942994399449945994699479948994999509951995299539954995599569957995899599960996199629963996499659966996799689969997099719972997399749975997699779978997999809981998299839984998599869987998899899990999199929993999499959996999799989999100001000110002100031000410005100061000710008100091001010011100121001310014100151001610017100181001910020100211002210023100241002510026100271002810029100301003110032100331003410035100361003710038100391004010041100421004310044100451004610047100481004910050100511005210053100541005510056100571005810059100601006110062100631006410065100661006710068100691007010071100721007310074100751007610077100781007910080100811008210083100841008510086100871008810089100901009110092100931009410095100961009710098100991010010101101021010310104101051010610107101081010910110101111011210113101141011510116101171011810119101201012110122101231012410125101261012710128101291013010131101321013310134101351013610137101381013910140101411014210143101441014510146101471014810149101501015110152101531015410155101561015710158101591016010161101621016310164101651016610167101681016910170101711017210173101741017510176101771017810179101801018110182101831018410185101861018710188101891019010191101921019310194101951019610197101981019910200102011020210203102041020510206102071020810209102101021110212102131021410215102161021710218102191022010221102221022310224102251022610227102281022910230102311023210233102341023510236102371023810239102401024110242102431024410245102461024710248102491025010251102521025310254102551025610257102581025910260102611026210263102641026510266102671026810269102701027110272102731027410275102761027710278102791028010281102821028310284102851028610287102881028910290102911029210293102941029510296102971029810299103001030110302103031030410305103061030710308103091031010311103121031310314103151031610317103181031910320103211032210323103241032510326103271032810329103301033110332103331033410335103361033710338103391034010341103421034310344103451034610347103481034910350103511035210353103541035510356103571035810359103601036110362103631036410365103661036710368103691037010371103721037310374103751037610377103781037910380103811038210383103841038510386103871038810389103901039110392103931039410395103961039710398103991040010401104021040310404104051040610407104081040910410104111041210413104141041510416104171041810419104201042110422104231042410425104261042710428104291043010431104321043310434104351043610437104381043910440104411044210443104441044510446104471044810449104501045110452104531045410455104561045710458104591046010461104621046310464104651046610467104681046910470104711047210473104741047510476104771047810479104801048110482104831048410485104861048710488104891049010491104921049310494104951049610497104981049910500105011050210503105041050510506105071050810509105101051110512105131051410515105161051710518105191052010521105221052310524105251052610527105281052910530105311053210533105341053510536105371053810539105401054110542105431054410545105461054710548105491055010551105521055310554105551055610557105581055910560105611056210563105641056510566105671056810569105701057110572105731057410575105761057710578105791058010581105821058310584105851058610587105881058910590105911059210593105941059510596105971059810599106001060110602106031060410605106061060710608106091061010611106121061310614106151061610617106181061910620106211062210623106241062510626106271062810629106301063110632106331063410635106361063710638106391064010641106421064310644106451064610647106481064910650106511065210653106541065510656106571065810659106601066110662106631066410665106661066710668106691067010671106721067310674106751067610677106781067910680106811068210683106841068510686106871068810689106901069110692106931069410695106961069710698106991070010701107021070310704107051070610707107081070910710107111071210713107141071510716107171071810719107201072110722107231072410725107261072710728107291073010731107321073310734107351073610737107381073910740107411074210743107441074510746107471074810749107501075110752107531075410755107561075710758107591076010761107621076310764107651076610767107681076910770107711077210773107741077510776107771077810779107801078110782107831078410785107861078710788107891079010791107921079310794107951079610797107981079910800108011080210803108041080510806108071080810809108101081110812108131081410815108161081710818108191082010821108221082310824108251082610827108281082910830108311083210833108341083510836108371083810839108401084110842108431084410845108461084710848108491085010851108521085310854108551085610857108581085910860108611086210863108641086510866108671086810869108701087110872108731087410875108761087710878108791088010881108821088310884108851088610887108881088910890108911089210893108941089510896108971089810899109001090110902109031090410905109061090710908109091091010911109121091310914109151091610917109181091910920109211092210923109241092510926109271092810929109301093110932109331093410935109361093710938109391094010941109421094310944109451094610947109481094910950109511095210953109541095510956109571095810959109601096110962109631096410965109661096710968109691097010971109721097310974109751097610977109781097910980109811098210983109841098510986109871098810989109901099110992109931099410995109961099710998109991100011001110021100311004110051100611007110081100911010110111101211013110141101511016110171101811019110201102111022110231102411025110261102711028110291103011031110321103311034110351103611037110381103911040110411104211043110441104511046110471104811049110501105111052110531105411055110561105711058110591106011061110621106311064110651106611067110681106911070110711107211073110741107511076110771107811079110801108111082110831108411085110861108711088110891109011091110921109311094110951109611097110981109911100111011110211103111041110511106111071110811109111101111111112111131111411115111161111711118111191112011121111221112311124111251112611127111281112911130111311113211133111341113511136111371113811139111401114111142111431114411145111461114711148111491115011151111521115311154111551115611157111581115911160111611116211163111641116511166111671116811169111701117111172111731117411175111761117711178111791118011181111821118311184111851118611187111881118911190111911119211193111941119511196111971119811199112001120111202112031120411205112061120711208112091121011211112121121311214112151121611217112181121911220112211122211223112241122511226112271122811229112301123111232112331123411235112361123711238112391124011241112421124311244112451124611247112481124911250112511125211253112541125511256112571125811259112601126111262112631126411265112661126711268112691127011271112721127311274112751127611277112781127911280112811128211283112841128511286112871128811289112901129111292112931129411295112961129711298112991130011301113021130311304113051130611307113081130911310113111131211313113141131511316113171131811319113201132111322113231132411325113261132711328113291133011331113321133311334113351133611337113381133911340113411134211343113441134511346113471134811349113501135111352113531135411355113561135711358113591136011361113621136311364113651136611367113681136911370113711137211373113741137511376113771137811379113801138111382113831138411385113861138711388113891139011391113921139311394113951139611397113981139911400114011140211403114041140511406114071140811409114101141111412114131141411415114161141711418114191142011421114221142311424114251142611427114281142911430114311143211433114341143511436114371143811439114401144111442114431144411445114461144711448114491145011451114521145311454114551145611457114581145911460114611146211463114641146511466114671146811469114701147111472114731147411475114761147711478114791148011481114821148311484114851148611487114881148911490114911149211493114941149511496114971149811499115001150111502115031150411505115061150711508115091151011511115121151311514115151151611517115181151911520115211152211523115241152511526115271152811529115301153111532115331153411535115361153711538115391154011541115421154311544115451154611547115481154911550115511155211553115541155511556115571155811559115601156111562115631156411565115661156711568115691157011571115721157311574115751157611577115781157911580115811158211583115841158511586115871158811589115901159111592115931159411595115961159711598115991160011601116021160311604116051160611607116081160911610116111161211613116141161511616116171161811619116201162111622116231162411625116261162711628116291163011631116321163311634116351163611637116381163911640116411164211643116441164511646116471164811649116501165111652116531165411655116561165711658116591166011661116621166311664116651166611667116681166911670116711167211673116741167511676116771167811679116801168111682116831168411685116861168711688116891169011691116921169311694116951169611697116981169911700117011170211703117041170511706117071170811709117101171111712117131171411715117161171711718117191172011721117221172311724117251172611727117281172911730117311173211733117341173511736117371173811739117401174111742117431174411745117461174711748117491175011751117521175311754117551175611757117581175911760117611176211763117641176511766117671176811769117701177111772117731177411775117761177711778117791178011781117821178311784117851178611787117881178911790117911179211793117941179511796117971179811799118001180111802118031180411805118061180711808118091181011811118121181311814118151181611817118181181911820118211182211823118241182511826118271182811829118301183111832118331183411835118361183711838118391184011841118421184311844118451184611847118481184911850118511185211853118541185511856118571185811859118601186111862118631186411865118661186711868118691187011871118721187311874118751187611877118781187911880118811188211883118841188511886118871188811889118901189111892118931189411895118961189711898118991190011901119021190311904119051190611907119081190911910119111191211913119141191511916119171191811919119201192111922119231192411925119261192711928119291193011931119321193311934119351193611937119381193911940119411194211943119441194511946119471194811949119501195111952119531195411955119561195711958119591196011961119621196311964119651196611967119681196911970119711197211973119741197511976119771197811979119801198111982119831198411985119861198711988119891199011991119921199311994119951199611997119981199912000120011200212003120041200512006120071200812009120101201112012120131201412015120161201712018120191202012021120221202312024120251202612027120281202912030120311203212033120341203512036120371203812039120401204112042120431204412045120461204712048120491205012051120521205312054120551205612057120581205912060120611206212063120641206512066120671206812069120701207112072120731207412075120761207712078120791208012081120821208312084120851208612087120881208912090120911209212093120941209512096120971209812099121001210112102121031210412105121061210712108121091211012111121121211312114121151211612117121181211912120121211212212123121241212512126121271212812129121301213112132121331213412135121361213712138121391214012141121421214312144121451214612147121481214912150121511215212153121541215512156121571215812159121601216112162121631216412165121661216712168121691217012171121721217312174121751217612177121781217912180121811218212183121841218512186121871218812189121901219112192121931219412195121961219712198121991220012201122021220312204122051220612207122081220912210122111221212213122141221512216122171221812219122201222112222122231222412225122261222712228122291223012231122321223312234122351223612237122381223912240122411224212243122441224512246122471224812249122501225112252122531225412255122561225712258122591226012261122621226312264122651226612267122681226912270122711227212273122741227512276122771227812279122801228112282122831228412285122861228712288122891229012291122921229312294122951229612297122981229912300123011230212303123041230512306123071230812309123101231112312123131231412315123161231712318123191232012321123221232312324123251232612327123281232912330123311233212333123341233512336123371233812339123401234112342123431234412345123461234712348123491235012351123521235312354123551235612357123581235912360123611236212363123641236512366123671236812369123701237112372123731237412375123761237712378123791238012381123821238312384123851238612387123881238912390123911239212393123941239512396123971239812399124001240112402124031240412405124061240712408124091241012411124121241312414124151241612417124181241912420124211242212423124241242512426124271242812429124301243112432124331243412435124361243712438124391244012441124421244312444124451244612447124481244912450124511245212453124541245512456124571245812459124601246112462124631246412465124661246712468124691247012471124721247312474124751247612477124781247912480124811248212483124841248512486124871248812489124901249112492124931249412495124961249712498124991250012501125021250312504125051250612507125081250912510125111251212513125141251512516125171251812519125201252112522125231252412525125261252712528125291253012531125321253312534125351253612537125381253912540125411254212543125441254512546125471254812549125501255112552125531255412555125561255712558125591256012561125621256312564125651256612567125681256912570125711257212573125741257512576125771257812579125801258112582125831258412585125861258712588125891259012591125921259312594125951259612597125981259912600126011260212603126041260512606126071260812609126101261112612126131261412615126161261712618126191262012621126221262312624126251262612627126281262912630126311263212633126341263512636126371263812639126401264112642126431264412645126461264712648126491265012651126521265312654126551265612657126581265912660126611266212663126641266512666126671266812669126701267112672126731267412675126761267712678126791268012681126821268312684126851268612687126881268912690126911269212693126941269512696126971269812699127001270112702127031270412705127061270712708127091271012711127121271312714127151271612717127181271912720127211272212723127241272512726127271272812729127301273112732127331273412735127361273712738127391274012741127421274312744127451274612747127481274912750127511275212753127541275512756127571275812759127601276112762127631276412765127661276712768127691277012771127721277312774127751277612777127781277912780127811278212783127841278512786127871278812789127901279112792127931279412795127961279712798127991280012801128021280312804128051280612807128081280912810128111281212813128141281512816128171281812819128201282112822128231282412825128261282712828128291283012831128321283312834128351283612837128381283912840128411284212843128441284512846128471284812849128501285112852128531285412855128561285712858128591286012861128621286312864128651286612867128681286912870128711287212873128741287512876128771287812879128801288112882128831288412885128861288712888128891289012891128921289312894128951289612897128981289912900129011290212903129041290512906129071290812909129101291112912129131291412915129161291712918129191292012921129221292312924129251292612927129281292912930129311293212933129341293512936129371293812939129401294112942129431294412945129461294712948129491295012951129521295312954129551295612957129581295912960129611296212963129641296512966129671296812969129701297112972129731297412975129761297712978129791298012981129821298312984129851298612987129881298912990129911299212993129941299512996129971299812999130001300113002130031300413005130061300713008130091301013011130121301313014130151301613017130181301913020130211302213023130241302513026130271302813029130301303113032130331303413035130361303713038130391304013041130421304313044130451304613047130481304913050130511305213053130541305513056130571305813059130601306113062130631306413065130661306713068130691307013071130721307313074130751307613077130781307913080130811308213083130841308513086130871308813089130901309113092130931309413095130961309713098130991310013101131021310313104131051310613107131081310913110131111311213113131141311513116131171311813119131201312113122131231312413125131261312713128131291313013131131321313313134131351313613137131381313913140131411314213143131441314513146131471314813149131501315113152131531315413155131561315713158131591316013161131621316313164131651316613167131681316913170131711317213173131741317513176131771317813179131801318113182131831318413185131861318713188131891319013191131921319313194131951319613197131981319913200132011320213203132041320513206132071320813209132101321113212132131321413215132161321713218132191322013221132221322313224132251322613227132281322913230132311323213233132341323513236132371323813239132401324113242132431324413245132461324713248132491325013251132521325313254132551325613257132581325913260132611326213263132641326513266132671326813269132701327113272132731327413275132761327713278132791328013281132821328313284132851328613287132881328913290132911329213293132941329513296132971329813299133001330113302133031330413305133061330713308133091331013311133121331313314133151331613317133181331913320133211332213323133241332513326133271332813329133301333113332133331333413335133361333713338133391334013341133421334313344133451334613347133481334913350133511335213353133541335513356133571335813359133601336113362133631336413365133661336713368133691337013371133721337313374133751337613377133781337913380133811338213383133841338513386133871338813389133901339113392133931339413395133961339713398133991340013401134021340313404134051340613407134081340913410134111341213413134141341513416134171341813419134201342113422134231342413425134261342713428134291343013431134321343313434134351343613437134381343913440134411344213443134441344513446134471344813449134501345113452134531345413455134561345713458134591346013461134621346313464134651346613467134681346913470134711347213473134741347513476134771347813479134801348113482134831348413485134861348713488134891349013491134921349313494134951349613497134981349913500135011350213503135041350513506135071350813509135101351113512135131351413515135161351713518135191352013521135221352313524135251352613527135281352913530135311353213533135341353513536135371353813539135401354113542135431354413545135461354713548135491355013551135521355313554135551355613557135581355913560135611356213563135641356513566135671356813569135701357113572135731357413575135761357713578135791358013581135821358313584135851358613587135881358913590135911359213593135941359513596135971359813599136001360113602136031360413605136061360713608136091361013611136121361313614136151361613617136181361913620136211362213623136241362513626136271362813629136301363113632136331363413635136361363713638136391364013641136421364313644136451364613647136481364913650136511365213653136541365513656136571365813659136601366113662136631366413665136661366713668136691367013671136721367313674136751367613677136781367913680136811368213683136841368513686136871368813689136901369113692136931369413695136961369713698136991370013701137021370313704137051370613707137081370913710137111371213713137141371513716137171371813719137201372113722137231372413725137261372713728137291373013731137321373313734137351373613737137381373913740137411374213743137441374513746137471374813749137501375113752137531375413755137561375713758137591376013761137621376313764137651376613767137681376913770137711377213773137741377513776137771377813779137801378113782137831378413785137861378713788137891379013791137921379313794137951379613797137981379913800138011380213803138041380513806138071380813809138101381113812138131381413815138161381713818138191382013821138221382313824138251382613827138281382913830138311383213833138341383513836138371383813839138401384113842138431384413845138461384713848138491385013851138521385313854138551385613857138581385913860138611386213863138641386513866138671386813869138701387113872138731387413875138761387713878138791388013881138821388313884138851388613887138881388913890138911389213893138941389513896138971389813899139001390113902139031390413905139061390713908139091391013911139121391313914139151391613917139181391913920139211392213923139241392513926139271392813929139301393113932139331393413935139361393713938139391394013941139421394313944139451394613947139481394913950139511395213953139541395513956139571395813959139601396113962139631396413965139661396713968139691397013971139721397313974139751397613977139781397913980139811398213983139841398513986139871398813989139901399113992139931399413995139961399713998139991400014001140021400314004140051400614007140081400914010140111401214013140141401514016140171401814019140201402114022140231402414025140261402714028140291403014031140321403314034140351403614037140381403914040140411404214043140441404514046140471404814049140501405114052140531405414055140561405714058140591406014061140621406314064140651406614067140681406914070140711407214073140741407514076140771407814079140801408114082140831408414085140861408714088140891409014091140921409314094140951409614097140981409914100141011410214103141041410514106141071410814109141101411114112141131411414115141161411714118141191412014121141221412314124141251412614127141281412914130141311413214133141341413514136141371413814139141401414114142141431414414145141461414714148141491415014151141521415314154141551415614157141581415914160141611416214163141641416514166141671416814169141701417114172141731417414175141761417714178141791418014181141821418314184141851418614187141881418914190141911419214193141941419514196141971419814199142001420114202142031420414205142061420714208142091421014211142121421314214142151421614217142181421914220142211422214223142241422514226142271422814229142301423114232142331423414235142361423714238142391424014241142421424314244142451424614247142481424914250142511425214253142541425514256142571425814259142601426114262142631426414265142661426714268142691427014271142721427314274142751427614277142781427914280142811428214283142841428514286142871428814289142901429114292142931429414295142961429714298142991430014301143021430314304143051430614307143081430914310143111431214313143141431514316143171431814319143201432114322143231432414325143261432714328143291433014331143321433314334143351433614337143381433914340143411434214343143441434514346143471434814349143501435114352143531435414355143561435714358143591436014361143621436314364143651436614367143681436914370143711437214373143741437514376143771437814379143801438114382143831438414385143861438714388143891439014391143921439314394143951439614397143981439914400144011440214403144041440514406144071440814409144101441114412144131441414415144161441714418144191442014421144221442314424144251442614427144281442914430144311443214433144341443514436144371443814439144401444114442144431444414445144461444714448144491445014451144521445314454144551445614457144581445914460144611446214463144641446514466144671446814469144701447114472144731447414475144761447714478144791448014481144821448314484144851448614487144881448914490144911449214493144941449514496144971449814499145001450114502145031450414505145061450714508145091451014511145121451314514145151451614517145181451914520145211452214523145241452514526145271452814529145301453114532145331453414535145361453714538145391454014541145421454314544145451454614547145481454914550145511455214553145541455514556145571455814559145601456114562145631456414565145661456714568145691457014571145721457314574145751457614577145781457914580145811458214583145841458514586145871458814589145901459114592145931459414595145961459714598145991460014601146021460314604146051460614607146081460914610146111461214613146141461514616146171461814619146201462114622146231462414625146261462714628146291463014631146321463314634146351463614637146381463914640146411464214643146441464514646146471464814649146501465114652146531465414655146561465714658146591466014661146621466314664146651466614667146681466914670146711467214673146741467514676146771467814679146801468114682146831468414685146861468714688146891469014691146921469314694146951469614697146981469914700147011470214703147041470514706147071470814709147101471114712147131471414715147161471714718147191472014721147221472314724147251472614727147281472914730147311473214733147341473514736147371473814739147401474114742147431474414745147461474714748147491475014751147521475314754147551475614757147581475914760147611476214763147641476514766147671476814769147701477114772147731477414775147761477714778147791478014781147821478314784147851478614787147881478914790147911479214793147941479514796147971479814799148001480114802148031480414805148061480714808148091481014811148121481314814148151481614817148181481914820148211482214823148241482514826148271482814829148301483114832148331483414835148361483714838148391484014841148421484314844148451484614847148481484914850148511485214853148541485514856148571485814859148601486114862148631486414865148661486714868148691487014871148721487314874148751487614877148781487914880148811488214883148841488514886148871488814889148901489114892148931489414895148961489714898148991490014901149021490314904149051490614907149081490914910149111491214913149141491514916149171491814919149201492114922149231492414925149261492714928149291493014931149321493314934149351493614937149381493914940149411494214943149441494514946149471494814949149501495114952149531495414955149561495714958149591496014961149621496314964149651496614967149681496914970149711497214973149741497514976149771497814979149801498114982149831498414985149861498714988149891499014991149921499314994149951499614997149981499915000150011500215003150041500515006150071500815009150101501115012150131501415015150161501715018150191502015021150221502315024150251502615027150281502915030150311503215033150341503515036150371503815039150401504115042150431504415045150461504715048150491505015051150521505315054150551505615057150581505915060150611506215063150641506515066150671506815069150701507115072150731507415075150761507715078150791508015081150821508315084150851508615087150881508915090150911509215093150941509515096150971509815099151001510115102151031510415105151061510715108151091511015111151121511315114151151511615117151181511915120151211512215123151241512515126151271512815129151301513115132151331513415135151361513715138151391514015141151421514315144151451514615147151481514915150151511515215153151541515515156151571515815159151601516115162151631516415165151661516715168151691517015171151721517315174151751517615177151781517915180151811518215183151841518515186151871518815189151901519115192151931519415195151961519715198151991520015201152021520315204152051520615207152081520915210152111521215213152141521515216152171521815219152201522115222152231522415225152261522715228152291523015231152321523315234152351523615237152381523915240152411524215243152441524515246152471524815249152501525115252152531525415255152561525715258152591526015261152621526315264152651526615267152681526915270152711527215273152741527515276152771527815279152801528115282152831528415285152861528715288152891529015291152921529315294152951529615297152981529915300153011530215303153041530515306153071530815309153101531115312153131531415315153161531715318153191532015321153221532315324153251532615327153281532915330153311533215333153341533515336153371533815339153401534115342153431534415345153461534715348153491535015351153521535315354153551535615357153581535915360153611536215363153641536515366153671536815369153701537115372153731537415375153761537715378153791538015381153821538315384153851538615387153881538915390153911539215393153941539515396153971539815399154001540115402154031540415405154061540715408154091541015411154121541315414154151541615417154181541915420154211542215423154241542515426154271542815429154301543115432154331543415435154361543715438154391544015441154421544315444154451544615447154481544915450154511545215453154541545515456154571545815459154601546115462154631546415465154661546715468154691547015471154721547315474154751547615477154781547915480154811548215483154841548515486154871548815489154901549115492154931549415495154961549715498154991550015501155021550315504155051550615507155081550915510155111551215513155141551515516155171551815519155201552115522155231552415525155261552715528155291553015531155321553315534155351553615537155381553915540155411554215543155441554515546155471554815549155501555115552155531555415555155561555715558155591556015561155621556315564155651556615567155681556915570155711557215573155741557515576155771557815579155801558115582155831558415585155861558715588155891559015591155921559315594155951559615597155981559915600156011560215603156041560515606156071560815609156101561115612156131561415615156161561715618156191562015621156221562315624156251562615627156281562915630156311563215633156341563515636156371563815639156401564115642156431564415645156461564715648156491565015651156521565315654156551565615657156581565915660156611566215663156641566515666156671566815669156701567115672156731567415675156761567715678156791568015681156821568315684156851568615687156881568915690156911569215693156941569515696156971569815699157001570115702157031570415705157061570715708157091571015711157121571315714157151571615717157181571915720157211572215723157241572515726157271572815729157301573115732157331573415735157361573715738157391574015741157421574315744157451574615747157481574915750157511575215753157541575515756157571575815759157601576115762157631576415765157661576715768157691577015771157721577315774157751577615777157781577915780157811578215783157841578515786157871578815789157901579115792157931579415795157961579715798157991580015801158021580315804158051580615807158081580915810158111581215813158141581515816158171581815819158201582115822158231582415825158261582715828158291583015831158321583315834158351583615837158381583915840158411584215843158441584515846158471584815849158501585115852158531585415855158561585715858158591586015861158621586315864158651586615867158681586915870158711587215873158741587515876158771587815879158801588115882158831588415885158861588715888158891589015891158921589315894158951589615897158981589915900159011590215903159041590515906159071590815909159101591115912159131591415915159161591715918159191592015921159221592315924159251592615927159281592915930159311593215933159341593515936159371593815939159401594115942159431594415945159461594715948159491595015951159521595315954159551595615957159581595915960159611596215963159641596515966159671596815969159701597115972159731597415975159761597715978159791598015981159821598315984159851598615987159881598915990159911599215993159941599515996159971599815999160001600116002160031600416005160061600716008160091601016011160121601316014160151601616017160181601916020160211602216023160241602516026160271602816029160301603116032160331603416035160361603716038160391604016041160421604316044160451604616047160481604916050160511605216053160541605516056160571605816059160601606116062160631606416065160661606716068160691607016071160721607316074160751607616077160781607916080160811608216083160841608516086160871608816089160901609116092160931609416095160961609716098160991610016101161021610316104161051610616107161081610916110161111611216113161141611516116161171611816119161201612116122161231612416125161261612716128161291613016131161321613316134161351613616137161381613916140161411614216143161441614516146161471614816149161501615116152161531615416155161561615716158161591616016161161621616316164161651616616167161681616916170161711617216173161741617516176161771617816179161801618116182161831618416185161861618716188161891619016191161921619316194161951619616197161981619916200162011620216203162041620516206162071620816209162101621116212162131621416215162161621716218162191622016221162221622316224162251622616227162281622916230162311623216233162341623516236162371623816239162401624116242162431624416245162461624716248162491625016251162521625316254162551625616257162581625916260162611626216263162641626516266162671626816269162701627116272162731627416275162761627716278162791628016281162821628316284162851628616287162881628916290162911629216293162941629516296162971629816299163001630116302163031630416305163061630716308163091631016311163121631316314163151631616317163181631916320163211632216323163241632516326163271632816329163301633116332163331633416335163361633716338163391634016341163421634316344163451634616347163481634916350163511635216353163541635516356163571635816359163601636116362163631636416365163661636716368163691637016371163721637316374163751637616377163781637916380163811638216383163841638516386163871638816389163901639116392163931639416395163961639716398163991640016401164021640316404164051640616407164081640916410164111641216413164141641516416164171641816419164201642116422164231642416425164261642716428164291643016431164321643316434164351643616437164381643916440164411644216443164441644516446164471644816449164501645116452164531645416455164561645716458164591646016461164621646316464164651646616467164681646916470164711647216473164741647516476164771647816479164801648116482164831648416485164861648716488164891649016491164921649316494164951649616497164981649916500165011650216503165041650516506165071650816509165101651116512165131651416515165161651716518165191652016521165221652316524165251652616527165281652916530165311653216533165341653516536165371653816539165401654116542165431654416545165461654716548165491655016551165521655316554165551655616557165581655916560165611656216563165641656516566165671656816569165701657116572165731657416575165761657716578165791658016581165821658316584165851658616587165881658916590165911659216593165941659516596165971659816599166001660116602166031660416605166061660716608166091661016611166121661316614166151661616617166181661916620166211662216623166241662516626166271662816629166301663116632166331663416635166361663716638166391664016641166421664316644166451664616647166481664916650166511665216653166541665516656166571665816659166601666116662166631666416665166661666716668166691667016671166721667316674166751667616677166781667916680166811668216683166841668516686166871668816689166901669116692166931669416695166961669716698166991670016701167021670316704167051670616707167081670916710167111671216713167141671516716167171671816719167201672116722167231672416725167261672716728167291673016731167321673316734167351673616737167381673916740167411674216743167441674516746167471674816749167501675116752167531675416755167561675716758167591676016761167621676316764167651676616767167681676916770167711677216773167741677516776167771677816779167801678116782167831678416785167861678716788167891679016791167921679316794167951679616797167981679916800168011680216803168041680516806168071680816809168101681116812168131681416815168161681716818168191682016821168221682316824168251682616827168281682916830168311683216833168341683516836168371683816839168401684116842168431684416845168461684716848168491685016851168521685316854168551685616857168581685916860168611686216863168641686516866168671686816869168701687116872168731687416875168761687716878168791688016881168821688316884168851688616887168881688916890168911689216893168941689516896168971689816899169001690116902169031690416905169061690716908169091691016911169121691316914169151691616917169181691916920169211692216923169241692516926169271692816929169301693116932169331693416935169361693716938169391694016941169421694316944169451694616947169481694916950169511695216953169541695516956169571695816959169601696116962169631696416965169661696716968169691697016971169721697316974169751697616977169781697916980169811698216983169841698516986169871698816989169901699116992169931699416995169961699716998169991700017001170021700317004170051700617007170081700917010170111701217013170141701517016170171701817019170201702117022170231702417025170261702717028170291703017031170321703317034170351703617037170381703917040170411704217043170441704517046170471704817049170501705117052170531705417055170561705717058170591706017061170621706317064170651706617067170681706917070170711707217073170741707517076170771707817079170801708117082170831708417085170861708717088170891709017091170921709317094170951709617097170981709917100171011710217103171041710517106171071710817109171101711117112171131711417115171161711717118171191712017121171221712317124171251712617127171281712917130171311713217133171341713517136171371713817139171401714117142171431714417145171461714717148171491715017151171521715317154171551715617157171581715917160171611716217163171641716517166171671716817169171701717117172171731717417175171761717717178171791718017181171821718317184171851718617187171881718917190171911719217193171941719517196171971719817199172001720117202172031720417205172061720717208172091721017211172121721317214172151721617217172181721917220172211722217223172241722517226172271722817229172301723117232172331723417235172361723717238172391724017241172421724317244172451724617247172481724917250172511725217253172541725517256172571725817259172601726117262172631726417265172661726717268172691727017271172721727317274172751727617277172781727917280172811728217283172841728517286172871728817289172901729117292172931729417295172961729717298172991730017301173021730317304173051730617307173081730917310173111731217313173141731517316173171731817319173201732117322173231732417325173261732717328173291733017331173321733317334173351733617337173381733917340173411734217343173441734517346173471734817349173501735117352173531735417355173561735717358173591736017361173621736317364173651736617367173681736917370173711737217373173741737517376173771737817379173801738117382173831738417385173861738717388173891739017391173921739317394173951739617397173981739917400174011740217403174041740517406174071740817409174101741117412174131741417415174161741717418174191742017421174221742317424174251742617427174281742917430174311743217433174341743517436174371743817439174401744117442174431744417445174461744717448174491745017451174521745317454174551745617457174581745917460174611746217463174641746517466174671746817469174701747117472174731747417475174761747717478174791748017481174821748317484174851748617487174881748917490174911749217493174941749517496174971749817499175001750117502175031750417505175061750717508175091751017511175121751317514175151751617517175181751917520175211752217523175241752517526175271752817529175301753117532175331753417535175361753717538175391754017541175421754317544175451754617547175481754917550175511755217553175541755517556175571755817559175601756117562175631756417565175661756717568175691757017571175721757317574175751757617577175781757917580175811758217583175841758517586175871758817589175901759117592175931759417595175961759717598175991760017601176021760317604176051760617607176081760917610176111761217613176141761517616176171761817619176201762117622176231762417625176261762717628176291763017631176321763317634176351763617637176381763917640176411764217643176441764517646176471764817649176501765117652176531765417655176561765717658176591766017661176621766317664176651766617667176681766917670176711767217673176741767517676176771767817679176801768117682176831768417685176861768717688176891769017691176921769317694176951769617697176981769917700177011770217703177041770517706177071770817709177101771117712177131771417715177161771717718177191772017721177221772317724177251772617727177281772917730177311773217733177341773517736177371773817739177401774117742177431774417745177461774717748177491775017751177521775317754177551775617757177581775917760177611776217763177641776517766177671776817769177701777117772177731777417775177761777717778177791778017781177821778317784177851778617787177881778917790177911779217793177941779517796177971779817799178001780117802178031780417805178061780717808178091781017811178121781317814178151781617817178181781917820178211782217823178241782517826178271782817829178301783117832178331783417835178361783717838178391784017841178421784317844178451784617847178481784917850178511785217853178541785517856178571785817859178601786117862178631786417865178661786717868178691787017871178721787317874178751787617877178781787917880178811788217883178841788517886178871788817889178901789117892178931789417895178961789717898178991790017901179021790317904179051790617907179081790917910179111791217913179141791517916179171791817919179201792117922179231792417925179261792717928179291793017931179321793317934179351793617937179381793917940179411794217943179441794517946179471794817949179501795117952179531795417955179561795717958179591796017961179621796317964179651796617967179681796917970179711797217973179741797517976179771797817979179801798117982179831798417985179861798717988179891799017991179921799317994179951799617997179981799918000180011800218003180041800518006180071800818009180101801118012180131801418015180161801718018180191802018021180221802318024180251802618027180281802918030180311803218033180341803518036180371803818039180401804118042180431804418045180461804718048180491805018051180521805318054180551805618057180581805918060180611806218063180641806518066180671806818069180701807118072180731807418075180761807718078180791808018081180821808318084180851808618087180881808918090180911809218093180941809518096180971809818099181001810118102181031810418105181061810718108181091811018111181121811318114181151811618117181181811918120181211812218123181241812518126181271812818129181301813118132181331813418135181361813718138181391814018141181421814318144181451814618147181481814918150181511815218153181541815518156181571815818159181601816118162181631816418165181661816718168181691817018171181721817318174181751817618177181781817918180181811818218183181841818518186181871818818189181901819118192181931819418195181961819718198181991820018201182021820318204182051820618207182081820918210182111821218213182141821518216182171821818219182201822118222182231822418225182261822718228182291823018231182321823318234182351823618237182381823918240182411824218243182441824518246182471824818249182501825118252182531825418255182561825718258182591826018261182621826318264182651826618267182681826918270182711827218273182741827518276182771827818279182801828118282182831828418285182861828718288182891829018291182921829318294182951829618297182981829918300183011830218303183041830518306183071830818309183101831118312183131831418315183161831718318183191832018321183221832318324183251832618327183281832918330183311833218333183341833518336183371833818339183401834118342183431834418345183461834718348183491835018351183521835318354183551835618357183581835918360183611836218363183641836518366183671836818369183701837118372183731837418375183761837718378183791838018381183821838318384183851838618387183881838918390183911839218393183941839518396183971839818399184001840118402184031840418405184061840718408184091841018411184121841318414184151841618417184181841918420184211842218423184241842518426184271842818429184301843118432184331843418435184361843718438184391844018441184421844318444184451844618447184481844918450184511845218453184541845518456184571845818459184601846118462184631846418465184661846718468184691847018471184721847318474184751847618477184781847918480184811848218483184841848518486184871848818489184901849118492184931849418495184961849718498184991850018501185021850318504185051850618507185081850918510185111851218513185141851518516185171851818519185201852118522185231852418525185261852718528185291853018531185321853318534185351853618537185381853918540185411854218543185441854518546185471854818549185501855118552185531855418555185561855718558185591856018561185621856318564185651856618567185681856918570185711857218573185741857518576185771857818579185801858118582185831858418585185861858718588185891859018591185921859318594185951859618597185981859918600186011860218603186041860518606186071860818609186101861118612186131861418615186161861718618186191862018621186221862318624186251862618627186281862918630186311863218633186341863518636186371863818639186401864118642186431864418645186461864718648186491865018651186521865318654186551865618657186581865918660186611866218663186641866518666186671866818669186701867118672186731867418675186761867718678186791868018681186821868318684186851868618687186881868918690186911869218693186941869518696186971869818699187001870118702187031870418705187061870718708187091871018711187121871318714187151871618717187181871918720187211872218723187241872518726187271872818729187301873118732187331873418735187361873718738187391874018741187421874318744187451874618747187481874918750187511875218753187541875518756187571875818759187601876118762187631876418765187661876718768187691877018771187721877318774187751877618777187781877918780187811878218783187841878518786187871878818789187901879118792187931879418795187961879718798187991880018801188021880318804188051880618807188081880918810188111881218813188141881518816188171881818819188201882118822188231882418825188261882718828188291883018831188321883318834188351883618837188381883918840188411884218843188441884518846188471884818849188501885118852188531885418855188561885718858188591886018861188621886318864188651886618867188681886918870188711887218873188741887518876188771887818879188801888118882188831888418885188861888718888188891889018891188921889318894188951889618897188981889918900189011890218903189041890518906189071890818909189101891118912189131891418915189161891718918189191892018921189221892318924189251892618927189281892918930189311893218933189341893518936189371893818939189401894118942189431894418945189461894718948189491895018951189521895318954189551895618957189581895918960189611896218963189641896518966189671896818969189701897118972189731897418975189761897718978189791898018981189821898318984189851898618987189881898918990189911899218993189941899518996189971899818999190001900119002190031900419005190061900719008190091901019011190121901319014190151901619017190181901919020190211902219023190241902519026190271902819029190301903119032190331903419035190361903719038190391904019041190421904319044190451904619047190481904919050190511905219053190541905519056190571905819059190601906119062190631906419065190661906719068190691907019071190721907319074190751907619077190781907919080190811908219083190841908519086190871908819089190901909119092190931909419095190961909719098190991910019101191021910319104191051910619107191081910919110191111911219113191141911519116191171911819119191201912119122191231912419125191261912719128191291913019131191321913319134191351913619137191381913919140191411914219143191441914519146191471914819149191501915119152191531915419155191561915719158191591916019161191621916319164191651916619167191681916919170191711917219173191741917519176191771917819179191801918119182191831918419185191861918719188191891919019191191921919319194191951919619197191981919919200192011920219203192041920519206192071920819209192101921119212192131921419215192161921719218192191922019221192221922319224192251922619227192281922919230192311923219233192341923519236192371923819239192401924119242192431924419245192461924719248192491925019251192521925319254192551925619257192581925919260192611926219263192641926519266192671926819269192701927119272192731927419275192761927719278192791928019281192821928319284192851928619287192881928919290192911929219293192941929519296192971929819299193001930119302193031930419305193061930719308193091931019311193121931319314193151931619317193181931919320193211932219323193241932519326193271932819329193301933119332193331933419335193361933719338193391934019341193421934319344193451934619347193481934919350193511935219353193541935519356193571935819359193601936119362193631936419365193661936719368193691937019371193721937319374193751937619377193781937919380193811938219383193841938519386193871938819389193901939119392193931939419395193961939719398193991940019401194021940319404194051940619407194081940919410194111941219413194141941519416194171941819419194201942119422194231942419425194261942719428194291943019431194321943319434194351943619437194381943919440194411944219443194441944519446194471944819449194501945119452194531945419455194561945719458194591946019461194621946319464194651946619467194681946919470194711947219473194741947519476194771947819479194801948119482194831948419485194861948719488194891949019491194921949319494194951949619497194981949919500195011950219503195041950519506195071950819509195101951119512195131951419515195161951719518195191952019521195221952319524195251952619527195281952919530195311953219533195341953519536195371953819539195401954119542195431954419545195461954719548195491955019551195521955319554195551955619557195581955919560195611956219563195641956519566195671956819569195701957119572195731957419575195761957719578195791958019581195821958319584195851958619587195881958919590195911959219593195941959519596195971959819599196001960119602196031960419605196061960719608196091961019611196121961319614196151961619617196181961919620196211962219623196241962519626196271962819629196301963119632196331963419635196361963719638196391964019641196421964319644196451964619647196481964919650196511965219653196541965519656196571965819659196601966119662196631966419665196661966719668196691967019671196721967319674196751967619677196781967919680196811968219683196841968519686196871968819689196901969119692196931969419695196961969719698196991970019701197021970319704197051970619707197081970919710197111971219713197141971519716197171971819719197201972119722197231972419725197261972719728197291973019731197321973319734197351973619737197381973919740197411974219743197441974519746197471974819749197501975119752197531975419755197561975719758197591976019761197621976319764197651976619767197681976919770197711977219773197741977519776197771977819779197801978119782197831978419785197861978719788197891979019791197921979319794197951979619797197981979919800198011980219803198041980519806198071980819809198101981119812198131981419815198161981719818198191982019821198221982319824198251982619827198281982919830198311983219833198341983519836198371983819839198401984119842198431984419845198461984719848198491985019851198521985319854198551985619857198581985919860198611986219863198641986519866198671986819869198701987119872198731987419875198761987719878198791988019881198821988319884198851988619887198881988919890198911989219893198941989519896198971989819899199001990119902199031990419905199061990719908199091991019911199121991319914199151991619917199181991919920199211992219923199241992519926199271992819929199301993119932199331993419935199361993719938199391994019941199421994319944199451994619947199481994919950199511995219953199541995519956199571995819959199601996119962199631996419965199661996719968199691997019971199721997319974199751997619977199781997919980199811998219983199841998519986199871998819989199901999119992199931999419995199961999719998199992000020001200022000320004200052000620007200082000920010200112001220013200142001520016200172001820019200202002120022200232002420025200262002720028200292003020031200322003320034200352003620037200382003920040200412004220043200442004520046200472004820049200502005120052200532005420055200562005720058200592006020061200622006320064200652006620067200682006920070200712007220073200742007520076200772007820079200802008120082200832008420085200862008720088200892009020091200922009320094200952009620097200982009920100201012010220103201042010520106201072010820109201102011120112201132011420115201162011720118201192012020121201222012320124201252012620127201282012920130201312013220133201342013520136201372013820139201402014120142201432014420145201462014720148201492015020151201522015320154201552015620157201582015920160201612016220163201642016520166201672016820169201702017120172201732017420175201762017720178201792018020181201822018320184201852018620187201882018920190201912019220193201942019520196201972019820199202002020120202202032020420205202062020720208202092021020211202122021320214202152021620217202182021920220202212022220223202242022520226202272022820229202302023120232202332023420235202362023720238202392024020241202422024320244202452024620247202482024920250202512025220253202542025520256202572025820259202602026120262202632026420265202662026720268202692027020271202722027320274202752027620277202782027920280202812028220283202842028520286202872028820289202902029120292202932029420295202962029720298202992030020301203022030320304203052030620307203082030920310203112031220313203142031520316203172031820319203202032120322203232032420325203262032720328203292033020331203322033320334203352033620337203382033920340203412034220343203442034520346203472034820349203502035120352203532035420355203562035720358203592036020361203622036320364203652036620367203682036920370203712037220373203742037520376203772037820379203802038120382203832038420385203862038720388203892039020391203922039320394203952039620397203982039920400204012040220403204042040520406204072040820409204102041120412204132041420415204162041720418204192042020421204222042320424204252042620427204282042920430204312043220433204342043520436204372043820439204402044120442204432044420445204462044720448204492045020451204522045320454204552045620457204582045920460204612046220463204642046520466204672046820469204702047120472204732047420475204762047720478204792048020481204822048320484204852048620487204882048920490204912049220493204942049520496204972049820499205002050120502205032050420505205062050720508205092051020511205122051320514205152051620517205182051920520205212052220523205242052520526205272052820529205302053120532205332053420535205362053720538205392054020541205422054320544205452054620547205482054920550205512055220553205542055520556205572055820559205602056120562205632056420565205662056720568205692057020571205722057320574205752057620577205782057920580205812058220583205842058520586205872058820589205902059120592205932059420595205962059720598205992060020601206022060320604206052060620607206082060920610206112061220613206142061520616206172061820619206202062120622206232062420625206262062720628206292063020631206322063320634206352063620637206382063920640206412064220643206442064520646206472064820649206502065120652206532065420655206562065720658206592066020661206622066320664206652066620667206682066920670206712067220673206742067520676206772067820679206802068120682206832068420685206862068720688206892069020691206922069320694206952069620697206982069920700207012070220703207042070520706207072070820709207102071120712207132071420715207162071720718207192072020721207222072320724207252072620727207282072920730207312073220733207342073520736207372073820739207402074120742207432074420745207462074720748207492075020751207522075320754207552075620757207582075920760207612076220763207642076520766207672076820769207702077120772207732077420775207762077720778207792078020781207822078320784207852078620787207882078920790207912079220793207942079520796207972079820799208002080120802208032080420805208062080720808208092081020811208122081320814208152081620817208182081920820208212082220823208242082520826208272082820829208302083120832208332083420835208362083720838208392084020841208422084320844208452084620847208482084920850208512085220853208542085520856208572085820859208602086120862208632086420865208662086720868208692087020871208722087320874208752087620877208782087920880208812088220883208842088520886208872088820889208902089120892208932089420895208962089720898208992090020901209022090320904209052090620907209082090920910209112091220913209142091520916209172091820919209202092120922209232092420925209262092720928209292093020931209322093320934209352093620937209382093920940209412094220943209442094520946209472094820949209502095120952209532095420955209562095720958209592096020961209622096320964209652096620967209682096920970209712097220973209742097520976209772097820979209802098120982209832098420985209862098720988209892099020991209922099320994209952099620997209982099921000210012100221003210042100521006210072100821009210102101121012210132101421015210162101721018210192102021021210222102321024210252102621027210282102921030210312103221033210342103521036210372103821039210402104121042210432104421045210462104721048210492105021051210522105321054210552105621057210582105921060210612106221063210642106521066210672106821069210702107121072210732107421075210762107721078210792108021081210822108321084210852108621087210882108921090210912109221093210942109521096210972109821099211002110121102211032110421105211062110721108211092111021111211122111321114211152111621117211182111921120211212112221123211242112521126211272112821129211302113121132211332113421135211362113721138211392114021141211422114321144211452114621147211482114921150211512115221153211542115521156211572115821159211602116121162211632116421165211662116721168211692117021171211722117321174211752117621177211782117921180211812118221183211842118521186211872118821189211902119121192211932119421195211962119721198211992120021201212022120321204212052120621207212082120921210212112121221213212142121521216212172121821219212202122121222212232122421225212262122721228212292123021231212322123321234212352123621237212382123921240212412124221243212442124521246212472124821249212502125121252212532125421255212562125721258212592126021261212622126321264212652126621267212682126921270212712127221273212742127521276212772127821279212802128121282212832128421285212862128721288212892129021291212922129321294212952129621297212982129921300213012130221303213042130521306213072130821309213102131121312213132131421315213162131721318213192132021321213222132321324213252132621327213282132921330213312133221333213342133521336213372133821339213402134121342213432134421345213462134721348213492135021351213522135321354213552135621357213582135921360213612136221363213642136521366213672136821369213702137121372213732137421375213762137721378213792138021381213822138321384213852138621387213882138921390213912139221393213942139521396213972139821399214002140121402214032140421405214062140721408214092141021411214122141321414214152141621417214182141921420214212142221423214242142521426214272142821429214302143121432214332143421435214362143721438214392144021441214422144321444214452144621447214482144921450214512145221453214542145521456214572145821459214602146121462214632146421465214662146721468214692147021471214722147321474214752147621477214782147921480214812148221483214842148521486214872148821489214902149121492214932149421495214962149721498214992150021501215022150321504215052150621507215082150921510215112151221513215142151521516215172151821519215202152121522215232152421525215262152721528215292153021531215322153321534215352153621537215382153921540215412154221543215442154521546215472154821549215502155121552215532155421555215562155721558215592156021561215622156321564215652156621567215682156921570215712157221573215742157521576215772157821579215802158121582215832158421585215862158721588215892159021591215922159321594215952159621597215982159921600216012160221603216042160521606216072160821609216102161121612216132161421615216162161721618216192162021621216222162321624216252162621627216282162921630216312163221633216342163521636216372163821639216402164121642216432164421645216462164721648216492165021651216522165321654216552165621657216582165921660216612166221663216642166521666216672166821669216702167121672216732167421675216762167721678216792168021681216822168321684216852168621687216882168921690216912169221693216942169521696216972169821699217002170121702217032170421705217062170721708217092171021711217122171321714217152171621717217182171921720217212172221723217242172521726217272172821729217302173121732217332173421735217362173721738217392174021741217422174321744217452174621747217482174921750217512175221753217542175521756217572175821759217602176121762217632176421765217662176721768217692177021771217722177321774217752177621777217782177921780217812178221783217842178521786217872178821789217902179121792217932179421795217962179721798217992180021801218022180321804218052180621807218082180921810218112181221813218142181521816218172181821819218202182121822218232182421825218262182721828218292183021831218322183321834218352183621837218382183921840218412184221843218442184521846218472184821849218502185121852218532185421855218562185721858218592186021861218622186321864218652186621867218682186921870218712187221873218742187521876218772187821879218802188121882218832188421885218862188721888218892189021891218922189321894218952189621897218982189921900219012190221903219042190521906219072190821909219102191121912219132191421915219162191721918219192192021921219222192321924219252192621927219282192921930219312193221933219342193521936219372193821939219402194121942219432194421945219462194721948219492195021951219522195321954219552195621957219582195921960219612196221963219642196521966219672196821969219702197121972219732197421975219762197721978219792198021981219822198321984219852198621987219882198921990219912199221993219942199521996219972199821999220002200122002220032200422005220062200722008220092201022011220122201322014220152201622017220182201922020220212202222023220242202522026220272202822029220302203122032220332203422035220362203722038220392204022041220422204322044220452204622047220482204922050220512205222053220542205522056220572205822059220602206122062220632206422065220662206722068220692207022071220722207322074220752207622077220782207922080220812208222083220842208522086220872208822089220902209122092220932209422095220962209722098220992210022101221022210322104221052210622107221082210922110221112211222113221142211522116221172211822119221202212122122221232212422125221262212722128221292213022131221322213322134221352213622137221382213922140221412214222143221442214522146221472214822149221502215122152221532215422155221562215722158221592216022161221622216322164221652216622167221682216922170221712217222173221742217522176221772217822179221802218122182221832218422185221862218722188221892219022191221922219322194221952219622197221982219922200222012220222203222042220522206222072220822209222102221122212222132221422215222162221722218222192222022221222222222322224222252222622227222282222922230222312223222233222342223522236222372223822239222402224122242222432224422245222462224722248222492225022251222522225322254222552225622257222582225922260222612226222263222642226522266222672226822269222702227122272222732227422275222762227722278222792228022281222822228322284222852228622287222882228922290222912229222293222942229522296222972229822299223002230122302223032230422305223062230722308223092231022311223122231322314223152231622317223182231922320223212232222323223242232522326223272232822329223302233122332223332233422335223362233722338223392234022341223422234322344223452234622347223482234922350223512235222353223542235522356223572235822359223602236122362223632236422365223662236722368223692237022371223722237322374223752237622377223782237922380223812238222383223842238522386223872238822389223902239122392223932239422395223962239722398223992240022401224022240322404224052240622407224082240922410224112241222413224142241522416224172241822419224202242122422224232242422425224262242722428224292243022431224322243322434224352243622437224382243922440224412244222443224442244522446224472244822449224502245122452224532245422455224562245722458224592246022461224622246322464224652246622467224682246922470224712247222473224742247522476224772247822479224802248122482224832248422485224862248722488224892249022491224922249322494224952249622497224982249922500225012250222503225042250522506225072250822509225102251122512225132251422515225162251722518225192252022521225222252322524225252252622527225282252922530225312253222533225342253522536225372253822539225402254122542225432254422545225462254722548225492255022551225522255322554225552255622557225582255922560225612256222563225642256522566225672256822569225702257122572225732257422575225762257722578225792258022581225822258322584225852258622587225882258922590225912259222593225942259522596225972259822599226002260122602226032260422605226062260722608226092261022611226122261322614226152261622617226182261922620226212262222623226242262522626226272262822629226302263122632226332263422635226362263722638226392264022641226422264322644226452264622647226482264922650226512265222653226542265522656226572265822659226602266122662226632266422665226662266722668226692267022671226722267322674226752267622677226782267922680226812268222683226842268522686226872268822689226902269122692226932269422695226962269722698226992270022701227022270322704227052270622707227082270922710227112271222713227142271522716227172271822719227202272122722227232272422725227262272722728227292273022731227322273322734227352273622737227382273922740227412274222743227442274522746227472274822749227502275122752227532275422755227562275722758227592276022761227622276322764227652276622767227682276922770227712277222773227742277522776227772277822779227802278122782227832278422785227862278722788227892279022791227922279322794227952279622797227982279922800228012280222803228042280522806228072280822809228102281122812228132281422815228162281722818228192282022821228222282322824228252282622827228282282922830228312283222833228342283522836228372283822839228402284122842228432284422845228462284722848228492285022851228522285322854228552285622857228582285922860228612286222863228642286522866228672286822869228702287122872228732287422875228762287722878228792288022881228822288322884228852288622887228882288922890228912289222893228942289522896228972289822899229002290122902229032290422905229062290722908229092291022911229122291322914229152291622917229182291922920229212292222923229242292522926229272292822929229302293122932229332293422935229362293722938229392294022941229422294322944229452294622947229482294922950229512295222953229542295522956229572295822959229602296122962229632296422965229662296722968229692297022971229722297322974229752297622977229782297922980229812298222983229842298522986229872298822989229902299122992229932299422995229962299722998229992300023001230022300323004230052300623007230082300923010230112301223013230142301523016230172301823019230202302123022230232302423025230262302723028230292303023031230322303323034230352303623037230382303923040230412304223043230442304523046230472304823049230502305123052230532305423055230562305723058230592306023061230622306323064230652306623067230682306923070230712307223073230742307523076230772307823079230802308123082230832308423085230862308723088230892309023091230922309323094230952309623097230982309923100231012310223103231042310523106231072310823109231102311123112231132311423115231162311723118231192312023121231222312323124231252312623127231282312923130231312313223133231342313523136231372313823139231402314123142231432314423145231462314723148231492315023151231522315323154231552315623157231582315923160231612316223163231642316523166231672316823169231702317123172231732317423175231762317723178231792318023181231822318323184231852318623187231882318923190231912319223193231942319523196231972319823199232002320123202232032320423205232062320723208232092321023211232122321323214232152321623217232182321923220232212322223223232242322523226232272322823229232302323123232232332323423235232362323723238232392324023241232422324323244232452324623247232482324923250232512325223253232542325523256232572325823259232602326123262232632326423265232662326723268232692327023271232722327323274232752327623277232782327923280232812328223283232842328523286232872328823289232902329123292232932329423295232962329723298232992330023301233022330323304233052330623307233082330923310233112331223313233142331523316233172331823319233202332123322233232332423325233262332723328233292333023331233322333323334233352333623337233382333923340233412334223343233442334523346233472334823349233502335123352233532335423355233562335723358233592336023361233622336323364233652336623367233682336923370233712337223373233742337523376233772337823379233802338123382233832338423385233862338723388233892339023391233922339323394233952339623397233982339923400234012340223403234042340523406234072340823409234102341123412234132341423415234162341723418234192342023421234222342323424234252342623427234282342923430234312343223433234342343523436234372343823439234402344123442234432344423445234462344723448234492345023451234522345323454234552345623457234582345923460234612346223463234642346523466234672346823469234702347123472234732347423475234762347723478234792348023481234822348323484234852348623487234882348923490234912349223493234942349523496234972349823499235002350123502235032350423505235062350723508235092351023511235122351323514235152351623517235182351923520235212352223523235242352523526235272352823529235302353123532235332353423535235362353723538235392354023541235422354323544235452354623547235482354923550235512355223553235542355523556235572355823559235602356123562235632356423565235662356723568235692357023571235722357323574235752357623577235782357923580235812358223583235842358523586235872358823589235902359123592235932359423595235962359723598235992360023601236022360323604236052360623607236082360923610236112361223613236142361523616236172361823619236202362123622236232362423625236262362723628236292363023631236322363323634236352363623637236382363923640236412364223643236442364523646236472364823649236502365123652236532365423655236562365723658236592366023661236622366323664236652366623667236682366923670236712367223673236742367523676236772367823679236802368123682236832368423685236862368723688236892369023691236922369323694236952369623697236982369923700237012370223703237042370523706237072370823709237102371123712237132371423715237162371723718237192372023721237222372323724237252372623727237282372923730237312373223733237342373523736237372373823739237402374123742237432374423745237462374723748237492375023751237522375323754237552375623757237582375923760237612376223763237642376523766237672376823769237702377123772237732377423775237762377723778237792378023781237822378323784237852378623787237882378923790237912379223793237942379523796237972379823799238002380123802238032380423805238062380723808238092381023811238122381323814238152381623817238182381923820238212382223823238242382523826238272382823829238302383123832238332383423835238362383723838238392384023841238422384323844238452384623847238482384923850238512385223853238542385523856238572385823859238602386123862238632386423865238662386723868238692387023871238722387323874238752387623877238782387923880238812388223883238842388523886238872388823889238902389123892238932389423895238962389723898238992390023901239022390323904239052390623907239082390923910239112391223913239142391523916239172391823919239202392123922239232392423925239262392723928239292393023931239322393323934239352393623937239382393923940239412394223943239442394523946239472394823949239502395123952239532395423955239562395723958239592396023961239622396323964239652396623967239682396923970239712397223973239742397523976239772397823979239802398123982239832398423985239862398723988239892399023991239922399323994239952399623997239982399924000240012400224003240042400524006240072400824009240102401124012240132401424015240162401724018240192402024021240222402324024240252402624027240282402924030240312403224033240342403524036240372403824039240402404124042240432404424045240462404724048240492405024051240522405324054240552405624057240582405924060240612406224063240642406524066240672406824069240702407124072240732407424075240762407724078240792408024081240822408324084240852408624087240882408924090240912409224093240942409524096240972409824099241002410124102241032410424105241062410724108241092411024111241122411324114241152411624117241182411924120241212412224123241242412524126241272412824129241302413124132241332413424135241362413724138241392414024141241422414324144241452414624147241482414924150241512415224153241542415524156241572415824159241602416124162241632416424165241662416724168241692417024171241722417324174241752417624177241782417924180241812418224183241842418524186241872418824189241902419124192241932419424195241962419724198241992420024201242022420324204242052420624207242082420924210242112421224213242142421524216242172421824219242202422124222242232422424225242262422724228242292423024231242322423324234242352423624237242382423924240242412424224243242442424524246242472424824249242502425124252242532425424255242562425724258242592426024261242622426324264242652426624267242682426924270242712427224273242742427524276242772427824279242802428124282242832428424285242862428724288242892429024291242922429324294242952429624297242982429924300243012430224303243042430524306243072430824309243102431124312243132431424315243162431724318243192432024321243222432324324243252432624327243282432924330243312433224333243342433524336243372433824339243402434124342243432434424345243462434724348243492435024351243522435324354243552435624357243582435924360243612436224363243642436524366243672436824369243702437124372243732437424375243762437724378243792438024381243822438324384243852438624387243882438924390243912439224393243942439524396243972439824399244002440124402244032440424405244062440724408244092441024411244122441324414244152441624417244182441924420244212442224423244242442524426244272442824429244302443124432244332443424435244362443724438244392444024441244422444324444244452444624447244482444924450244512445224453244542445524456244572445824459244602446124462244632446424465244662446724468244692447024471244722447324474244752447624477244782447924480244812448224483244842448524486244872448824489244902449124492244932449424495244962449724498244992450024501245022450324504245052450624507245082450924510245112451224513245142451524516245172451824519245202452124522245232452424525245262452724528245292453024531245322453324534245352453624537245382453924540245412454224543245442454524546245472454824549245502455124552245532455424555245562455724558245592456024561245622456324564245652456624567245682456924570245712457224573245742457524576245772457824579245802458124582245832458424585245862458724588245892459024591245922459324594245952459624597245982459924600246012460224603246042460524606246072460824609246102461124612246132461424615246162461724618246192462024621246222462324624246252462624627246282462924630246312463224633246342463524636246372463824639246402464124642246432464424645246462464724648246492465024651246522465324654246552465624657246582465924660246612466224663246642466524666246672466824669246702467124672246732467424675246762467724678246792468024681246822468324684246852468624687246882468924690246912469224693246942469524696246972469824699247002470124702247032470424705247062470724708247092471024711247122471324714247152471624717247182471924720247212472224723247242472524726247272472824729247302473124732247332473424735247362473724738247392474024741247422474324744247452474624747247482474924750247512475224753247542475524756247572475824759247602476124762247632476424765247662476724768247692477024771247722477324774247752477624777247782477924780247812478224783247842478524786247872478824789247902479124792247932479424795247962479724798247992480024801248022480324804248052480624807248082480924810248112481224813248142481524816248172481824819248202482124822248232482424825248262482724828248292483024831248322483324834248352483624837248382483924840248412484224843248442484524846248472484824849248502485124852248532485424855248562485724858248592486024861248622486324864248652486624867248682486924870248712487224873248742487524876248772487824879248802488124882248832488424885248862488724888248892489024891248922489324894248952489624897248982489924900249012490224903249042490524906249072490824909249102491124912249132491424915249162491724918249192492024921249222492324924249252492624927249282492924930249312493224933249342493524936249372493824939249402494124942249432494424945249462494724948249492495024951249522495324954249552495624957249582495924960249612496224963249642496524966249672496824969249702497124972249732497424975249762497724978249792498024981249822498324984249852498624987249882498924990249912499224993249942499524996249972499824999250002500125002250032500425005250062500725008250092501025011250122501325014250152501625017250182501925020250212502225023250242502525026250272502825029250302503125032250332503425035250362503725038250392504025041250422504325044250452504625047250482504925050250512505225053250542505525056250572505825059250602506125062250632506425065250662506725068250692507025071250722507325074250752507625077250782507925080250812508225083250842508525086250872508825089250902509125092250932509425095250962509725098250992510025101251022510325104251052510625107251082510925110251112511225113251142511525116251172511825119251202512125122251232512425125251262512725128251292513025131251322513325134251352513625137251382513925140251412514225143251442514525146251472514825149251502515125152251532515425155251562515725158251592516025161251622516325164251652516625167251682516925170251712517225173251742517525176251772517825179251802518125182251832518425185251862518725188251892519025191251922519325194251952519625197251982519925200252012520225203252042520525206252072520825209252102521125212252132521425215252162521725218252192522025221252222522325224252252522625227252282522925230252312523225233252342523525236252372523825239252402524125242252432524425245252462524725248252492525025251252522525325254252552525625257252582525925260252612526225263252642526525266252672526825269252702527125272252732527425275252762527725278252792528025281252822528325284252852528625287252882528925290252912529225293252942529525296252972529825299253002530125302253032530425305253062530725308253092531025311253122531325314253152531625317253182531925320253212532225323253242532525326253272532825329253302533125332253332533425335253362533725338253392534025341253422534325344253452534625347253482534925350253512535225353253542535525356253572535825359253602536125362253632536425365253662536725368253692537025371253722537325374253752537625377253782537925380253812538225383253842538525386253872538825389253902539125392253932539425395253962539725398253992540025401254022540325404254052540625407254082540925410254112541225413254142541525416254172541825419254202542125422254232542425425254262542725428254292543025431254322543325434254352543625437254382543925440254412544225443254442544525446254472544825449254502545125452254532545425455254562545725458254592546025461254622546325464254652546625467254682546925470254712547225473254742547525476254772547825479254802548125482254832548425485254862548725488254892549025491254922549325494254952549625497254982549925500255012550225503255042550525506255072550825509255102551125512255132551425515255162551725518255192552025521255222552325524255252552625527255282552925530255312553225533255342553525536255372553825539255402554125542255432554425545255462554725548255492555025551255522555325554255552555625557255582555925560255612556225563255642556525566255672556825569255702557125572255732557425575255762557725578255792558025581255822558325584255852558625587255882558925590255912559225593255942559525596255972559825599256002560125602256032560425605256062560725608256092561025611256122561325614256152561625617256182561925620256212562225623256242562525626256272562825629256302563125632256332563425635256362563725638256392564025641256422564325644256452564625647256482564925650256512565225653256542565525656256572565825659256602566125662256632566425665256662566725668256692567025671256722567325674256752567625677256782567925680256812568225683256842568525686256872568825689256902569125692256932569425695256962569725698256992570025701257022570325704257052570625707257082570925710257112571225713257142571525716257172571825719257202572125722257232572425725257262572725728257292573025731257322573325734257352573625737257382573925740257412574225743257442574525746257472574825749257502575125752257532575425755257562575725758257592576025761257622576325764257652576625767257682576925770257712577225773257742577525776257772577825779257802578125782257832578425785257862578725788257892579025791257922579325794257952579625797257982579925800258012580225803258042580525806258072580825809258102581125812258132581425815258162581725818258192582025821258222582325824258252582625827258282582925830258312583225833258342583525836258372583825839258402584125842258432584425845258462584725848258492585025851258522585325854258552585625857258582585925860258612586225863258642586525866258672586825869258702587125872258732587425875258762587725878258792588025881258822588325884258852588625887258882588925890258912589225893258942589525896258972589825899259002590125902259032590425905259062590725908259092591025911259122591325914259152591625917259182591925920259212592225923259242592525926259272592825929259302593125932259332593425935259362593725938259392594025941259422594325944259452594625947259482594925950259512595225953259542595525956259572595825959259602596125962259632596425965259662596725968259692597025971259722597325974259752597625977259782597925980259812598225983259842598525986259872598825989259902599125992259932599425995259962599725998259992600026001260022600326004260052600626007260082600926010260112601226013260142601526016260172601826019260202602126022260232602426025260262602726028260292603026031260322603326034260352603626037260382603926040260412604226043260442604526046260472604826049260502605126052260532605426055260562605726058260592606026061260622606326064260652606626067260682606926070260712607226073260742607526076260772607826079260802608126082260832608426085260862608726088260892609026091260922609326094260952609626097260982609926100261012610226103261042610526106261072610826109261102611126112261132611426115261162611726118261192612026121261222612326124261252612626127261282612926130261312613226133261342613526136261372613826139261402614126142261432614426145261462614726148261492615026151261522615326154261552615626157261582615926160261612616226163261642616526166261672616826169261702617126172261732617426175261762617726178261792618026181261822618326184261852618626187261882618926190261912619226193261942619526196261972619826199262002620126202262032620426205262062620726208262092621026211262122621326214262152621626217262182621926220262212622226223262242622526226262272622826229262302623126232262332623426235262362623726238262392624026241262422624326244262452624626247262482624926250262512625226253262542625526256262572625826259262602626126262262632626426265262662626726268262692627026271262722627326274262752627626277262782627926280262812628226283262842628526286262872628826289262902629126292262932629426295262962629726298262992630026301263022630326304263052630626307263082630926310263112631226313263142631526316263172631826319263202632126322263232632426325263262632726328263292633026331263322633326334263352633626337263382633926340263412634226343263442634526346263472634826349263502635126352263532635426355263562635726358263592636026361263622636326364263652636626367263682636926370263712637226373263742637526376263772637826379263802638126382263832638426385263862638726388263892639026391263922639326394263952639626397263982639926400264012640226403264042640526406264072640826409264102641126412264132641426415264162641726418264192642026421264222642326424264252642626427264282642926430264312643226433264342643526436264372643826439264402644126442264432644426445264462644726448264492645026451264522645326454264552645626457264582645926460264612646226463264642646526466264672646826469264702647126472264732647426475264762647726478264792648026481264822648326484264852648626487264882648926490264912649226493264942649526496264972649826499265002650126502265032650426505265062650726508265092651026511265122651326514265152651626517265182651926520265212652226523265242652526526265272652826529265302653126532265332653426535265362653726538265392654026541265422654326544265452654626547265482654926550265512655226553265542655526556265572655826559265602656126562265632656426565265662656726568265692657026571265722657326574265752657626577265782657926580265812658226583265842658526586265872658826589265902659126592265932659426595265962659726598265992660026601266022660326604266052660626607266082660926610266112661226613266142661526616266172661826619266202662126622266232662426625266262662726628266292663026631266322663326634266352663626637266382663926640266412664226643266442664526646266472664826649266502665126652266532665426655266562665726658266592666026661266622666326664266652666626667266682666926670266712667226673266742667526676266772667826679266802668126682266832668426685266862668726688266892669026691266922669326694266952669626697266982669926700267012670226703267042670526706267072670826709267102671126712267132671426715267162671726718267192672026721267222672326724267252672626727267282672926730267312673226733267342673526736267372673826739267402674126742267432674426745267462674726748267492675026751267522675326754267552675626757267582675926760267612676226763267642676526766267672676826769267702677126772267732677426775267762677726778267792678026781267822678326784267852678626787267882678926790267912679226793267942679526796267972679826799268002680126802268032680426805268062680726808268092681026811268122681326814268152681626817268182681926820268212682226823268242682526826268272682826829268302683126832268332683426835268362683726838268392684026841268422684326844268452684626847268482684926850268512685226853268542685526856268572685826859268602686126862268632686426865268662686726868268692687026871268722687326874268752687626877268782687926880268812688226883268842688526886268872688826889268902689126892268932689426895268962689726898268992690026901269022690326904269052690626907269082690926910269112691226913269142691526916269172691826919269202692126922269232692426925269262692726928269292693026931269322693326934269352693626937269382693926940269412694226943269442694526946269472694826949269502695126952269532695426955269562695726958269592696026961269622696326964269652696626967269682696926970269712697226973269742697526976269772697826979269802698126982269832698426985269862698726988269892699026991269922699326994269952699626997269982699927000270012700227003270042700527006270072700827009270102701127012270132701427015270162701727018270192702027021270222702327024270252702627027270282702927030270312703227033270342703527036270372703827039270402704127042270432704427045270462704727048270492705027051270522705327054270552705627057270582705927060270612706227063270642706527066270672706827069270702707127072270732707427075270762707727078270792708027081270822708327084270852708627087270882708927090270912709227093270942709527096270972709827099271002710127102271032710427105271062710727108271092711027111271122711327114271152711627117271182711927120271212712227123271242712527126271272712827129271302713127132271332713427135271362713727138271392714027141271422714327144271452714627147271482714927150271512715227153271542715527156271572715827159271602716127162271632716427165271662716727168271692717027171271722717327174271752717627177271782717927180271812718227183271842718527186271872718827189271902719127192271932719427195271962719727198271992720027201272022720327204272052720627207272082720927210272112721227213272142721527216272172721827219272202722127222272232722427225272262722727228272292723027231272322723327234272352723627237272382723927240272412724227243272442724527246272472724827249272502725127252272532725427255272562725727258272592726027261272622726327264272652726627267272682726927270272712727227273272742727527276272772727827279272802728127282272832728427285272862728727288272892729027291272922729327294272952729627297272982729927300273012730227303273042730527306273072730827309273102731127312273132731427315273162731727318273192732027321273222732327324273252732627327273282732927330273312733227333273342733527336273372733827339273402734127342273432734427345273462734727348273492735027351273522735327354273552735627357273582735927360273612736227363273642736527366273672736827369273702737127372273732737427375273762737727378273792738027381273822738327384273852738627387273882738927390273912739227393273942739527396273972739827399274002740127402274032740427405274062740727408274092741027411274122741327414274152741627417274182741927420274212742227423274242742527426274272742827429274302743127432274332743427435274362743727438274392744027441274422744327444274452744627447274482744927450274512745227453274542745527456274572745827459274602746127462274632746427465274662746727468274692747027471274722747327474274752747627477274782747927480274812748227483274842748527486274872748827489274902749127492274932749427495274962749727498274992750027501275022750327504275052750627507275082750927510275112751227513275142751527516275172751827519275202752127522275232752427525275262752727528275292753027531275322753327534275352753627537275382753927540275412754227543275442754527546275472754827549275502755127552275532755427555275562755727558275592756027561275622756327564275652756627567275682756927570275712757227573275742757527576275772757827579275802758127582275832758427585275862758727588275892759027591275922759327594275952759627597275982759927600276012760227603276042760527606276072760827609276102761127612276132761427615276162761727618276192762027621276222762327624276252762627627276282762927630276312763227633276342763527636276372763827639276402764127642276432764427645276462764727648276492765027651276522765327654276552765627657276582765927660276612766227663276642766527666276672766827669276702767127672276732767427675276762767727678276792768027681276822768327684276852768627687276882768927690276912769227693276942769527696276972769827699277002770127702277032770427705277062770727708277092771027711277122771327714277152771627717277182771927720277212772227723277242772527726277272772827729277302773127732277332773427735277362773727738277392774027741277422774327744277452774627747277482774927750277512775227753277542775527756277572775827759277602776127762277632776427765277662776727768277692777027771277722777327774277752777627777277782777927780277812778227783277842778527786277872778827789277902779127792277932779427795277962779727798277992780027801278022780327804278052780627807278082780927810278112781227813278142781527816278172781827819278202782127822278232782427825278262782727828278292783027831278322783327834278352783627837278382783927840278412784227843278442784527846278472784827849278502785127852278532785427855278562785727858278592786027861278622786327864278652786627867278682786927870278712787227873278742787527876278772787827879278802788127882278832788427885278862788727888278892789027891278922789327894278952789627897278982789927900279012790227903279042790527906279072790827909279102791127912279132791427915279162791727918279192792027921279222792327924279252792627927279282792927930279312793227933279342793527936279372793827939279402794127942279432794427945279462794727948279492795027951279522795327954279552795627957279582795927960279612796227963279642796527966279672796827969279702797127972279732797427975279762797727978279792798027981279822798327984279852798627987279882798927990279912799227993279942799527996279972799827999280002800128002280032800428005280062800728008280092801028011280122801328014280152801628017280182801928020280212802228023280242802528026280272802828029280302803128032280332803428035280362803728038280392804028041280422804328044280452804628047280482804928050280512805228053280542805528056280572805828059280602806128062280632806428065280662806728068280692807028071280722807328074280752807628077280782807928080280812808228083280842808528086280872808828089280902809128092280932809428095280962809728098280992810028101281022810328104281052810628107281082810928110281112811228113281142811528116281172811828119281202812128122281232812428125281262812728128281292813028131281322813328134281352813628137281382813928140281412814228143281442814528146281472814828149281502815128152281532815428155281562815728158281592816028161281622816328164281652816628167281682816928170281712817228173281742817528176281772817828179281802818128182281832818428185281862818728188281892819028191281922819328194281952819628197281982819928200282012820228203282042820528206282072820828209282102821128212282132821428215282162821728218282192822028221282222822328224282252822628227282282822928230282312823228233282342823528236282372823828239282402824128242282432824428245282462824728248282492825028251282522825328254282552825628257282582825928260282612826228263282642826528266282672826828269282702827128272282732827428275282762827728278282792828028281282822828328284282852828628287282882828928290282912829228293282942829528296282972829828299283002830128302283032830428305283062830728308283092831028311283122831328314283152831628317283182831928320283212832228323283242832528326283272832828329283302833128332283332833428335283362833728338283392834028341283422834328344283452834628347283482834928350283512835228353283542835528356283572835828359283602836128362283632836428365283662836728368283692837028371283722837328374283752837628377283782837928380283812838228383283842838528386283872838828389283902839128392283932839428395283962839728398283992840028401284022840328404284052840628407284082840928410284112841228413284142841528416284172841828419284202842128422284232842428425284262842728428284292843028431284322843328434284352843628437284382843928440284412844228443284442844528446284472844828449284502845128452284532845428455284562845728458284592846028461284622846328464284652846628467284682846928470284712847228473284742847528476284772847828479284802848128482284832848428485284862848728488284892849028491284922849328494284952849628497284982849928500285012850228503285042850528506285072850828509285102851128512285132851428515285162851728518285192852028521285222852328524285252852628527285282852928530285312853228533285342853528536285372853828539285402854128542285432854428545285462854728548285492855028551285522855328554285552855628557285582855928560285612856228563285642856528566285672856828569285702857128572285732857428575285762857728578285792858028581285822858328584285852858628587285882858928590285912859228593285942859528596285972859828599286002860128602286032860428605286062860728608286092861028611286122861328614286152861628617286182861928620286212862228623286242862528626286272862828629286302863128632286332863428635286362863728638286392864028641286422864328644286452864628647286482864928650286512865228653286542865528656286572865828659286602866128662286632866428665286662866728668286692867028671286722867328674286752867628677286782867928680286812868228683286842868528686286872868828689286902869128692286932869428695286962869728698286992870028701287022870328704287052870628707287082870928710287112871228713287142871528716287172871828719287202872128722287232872428725287262872728728287292873028731287322873328734287352873628737287382873928740287412874228743287442874528746287472874828749287502875128752287532875428755287562875728758287592876028761287622876328764287652876628767287682876928770287712877228773287742877528776287772877828779287802878128782287832878428785287862878728788287892879028791287922879328794287952879628797287982879928800288012880228803288042880528806288072880828809288102881128812288132881428815288162881728818288192882028821288222882328824288252882628827288282882928830288312883228833288342883528836288372883828839288402884128842288432884428845288462884728848288492885028851288522885328854288552885628857288582885928860288612886228863288642886528866288672886828869288702887128872288732887428875288762887728878288792888028881288822888328884288852888628887288882888928890288912889228893288942889528896288972889828899289002890128902289032890428905289062890728908289092891028911289122891328914289152891628917289182891928920289212892228923289242892528926289272892828929289302893128932289332893428935289362893728938289392894028941289422894328944289452894628947289482894928950289512895228953289542895528956289572895828959289602896128962289632896428965289662896728968289692897028971289722897328974289752897628977289782897928980289812898228983289842898528986289872898828989289902899128992289932899428995289962899728998289992900029001290022900329004290052900629007290082900929010290112901229013290142901529016290172901829019290202902129022290232902429025290262902729028290292903029031290322903329034290352903629037290382903929040290412904229043290442904529046290472904829049290502905129052290532905429055290562905729058290592906029061290622906329064290652906629067290682906929070290712907229073290742907529076290772907829079290802908129082290832908429085290862908729088290892909029091290922909329094290952909629097290982909929100291012910229103291042910529106291072910829109291102911129112291132911429115291162911729118291192912029121291222912329124291252912629127291282912929130291312913229133291342913529136291372913829139291402914129142291432914429145291462914729148291492915029151291522915329154291552915629157291582915929160291612916229163291642916529166291672916829169291702917129172291732917429175291762917729178291792918029181291822918329184291852918629187291882918929190291912919229193291942919529196291972919829199292002920129202292032920429205292062920729208292092921029211292122921329214292152921629217292182921929220292212922229223292242922529226292272922829229292302923129232292332923429235292362923729238292392924029241292422924329244292452924629247292482924929250292512925229253292542925529256292572925829259292602926129262292632926429265292662926729268292692927029271292722927329274292752927629277292782927929280292812928229283292842928529286292872928829289292902929129292292932929429295292962929729298292992930029301293022930329304293052930629307293082930929310293112931229313293142931529316293172931829319293202932129322293232932429325293262932729328293292933029331293322933329334293352933629337293382933929340293412934229343293442934529346293472934829349293502935129352293532935429355293562935729358293592936029361293622936329364293652936629367293682936929370293712937229373293742937529376293772937829379293802938129382293832938429385293862938729388293892939029391293922939329394293952939629397293982939929400294012940229403294042940529406294072940829409294102941129412294132941429415294162941729418294192942029421294222942329424294252942629427294282942929430294312943229433294342943529436294372943829439294402944129442294432944429445294462944729448294492945029451294522945329454294552945629457294582945929460294612946229463294642946529466294672946829469294702947129472294732947429475294762947729478294792948029481294822948329484294852948629487294882948929490294912949229493294942949529496294972949829499295002950129502295032950429505295062950729508295092951029511295122951329514295152951629517295182951929520295212952229523295242952529526295272952829529295302953129532295332953429535295362953729538295392954029541295422954329544295452954629547295482954929550295512955229553295542955529556295572955829559295602956129562295632956429565295662956729568295692957029571295722957329574295752957629577295782957929580295812958229583295842958529586295872958829589295902959129592295932959429595295962959729598295992960029601296022960329604296052960629607296082960929610296112961229613296142961529616296172961829619296202962129622296232962429625296262962729628296292963029631296322963329634296352963629637296382963929640296412964229643296442964529646296472964829649296502965129652296532965429655296562965729658296592966029661296622966329664296652966629667296682966929670296712967229673296742967529676296772967829679296802968129682296832968429685296862968729688296892969029691296922969329694296952969629697296982969929700297012970229703297042970529706297072970829709297102971129712297132971429715297162971729718297192972029721297222972329724297252972629727297282972929730297312973229733297342973529736297372973829739297402974129742297432974429745297462974729748297492975029751297522975329754297552975629757297582975929760297612976229763297642976529766297672976829769297702977129772297732977429775297762977729778297792978029781297822978329784297852978629787297882978929790297912979229793297942979529796297972979829799298002980129802298032980429805298062980729808298092981029811298122981329814298152981629817298182981929820298212982229823298242982529826298272982829829298302983129832298332983429835298362983729838298392984029841298422984329844298452984629847298482984929850298512985229853298542985529856298572985829859298602986129862298632986429865298662986729868298692987029871298722987329874298752987629877298782987929880298812988229883298842988529886298872988829889298902989129892298932989429895298962989729898298992990029901299022990329904299052990629907299082990929910299112991229913299142991529916299172991829919299202992129922299232992429925299262992729928299292993029931299322993329934299352993629937299382993929940299412994229943299442994529946299472994829949299502995129952299532995429955299562995729958299592996029961299622996329964299652996629967299682996929970299712997229973299742997529976299772997829979299802998129982299832998429985299862998729988299892999029991299922999329994299952999629997299982999930000300013000230003300043000530006300073000830009300103001130012300133001430015300163001730018300193002030021300223002330024300253002630027300283002930030300313003230033300343003530036300373003830039300403004130042300433004430045300463004730048300493005030051300523005330054300553005630057300583005930060300613006230063300643006530066300673006830069300703007130072300733007430075300763007730078300793008030081300823008330084300853008630087300883008930090300913009230093300943009530096300973009830099301003010130102301033010430105301063010730108301093011030111301123011330114301153011630117301183011930120301213012230123301243012530126301273012830129301303013130132301333013430135301363013730138301393014030141301423014330144301453014630147301483014930150301513015230153301543015530156301573015830159301603016130162301633016430165301663016730168301693017030171301723017330174301753017630177301783017930180301813018230183301843018530186301873018830189301903019130192301933019430195301963019730198301993020030201302023020330204302053020630207302083020930210302113021230213302143021530216302173021830219302203022130222302233022430225302263022730228302293023030231302323023330234302353023630237302383023930240302413024230243302443024530246302473024830249302503025130252302533025430255302563025730258302593026030261302623026330264302653026630267302683026930270302713027230273302743027530276302773027830279302803028130282302833028430285302863028730288302893029030291302923029330294302953029630297302983029930300303013030230303303043030530306303073030830309303103031130312303133031430315303163031730318303193032030321303223032330324303253032630327303283032930330303313033230333303343033530336303373033830339303403034130342303433034430345303463034730348303493035030351303523035330354303553035630357303583035930360303613036230363303643036530366303673036830369303703037130372303733037430375303763037730378303793038030381303823038330384303853038630387303883038930390303913039230393303943039530396303973039830399304003040130402304033040430405304063040730408304093041030411304123041330414304153041630417304183041930420304213042230423304243042530426304273042830429304303043130432304333043430435304363043730438304393044030441304423044330444304453044630447304483044930450304513045230453304543045530456304573045830459304603046130462304633046430465304663046730468304693047030471304723047330474304753047630477304783047930480304813048230483304843048530486304873048830489304903049130492304933049430495304963049730498304993050030501305023050330504305053050630507305083050930510305113051230513305143051530516305173051830519305203052130522305233052430525305263052730528305293053030531305323053330534305353053630537305383053930540305413054230543305443054530546305473054830549305503055130552305533055430555305563055730558305593056030561305623056330564305653056630567305683056930570305713057230573305743057530576305773057830579305803058130582305833058430585305863058730588305893059030591305923059330594305953059630597305983059930600306013060230603306043060530606306073060830609306103061130612306133061430615306163061730618306193062030621306223062330624306253062630627306283062930630306313063230633306343063530636306373063830639306403064130642306433064430645306463064730648306493065030651306523065330654306553065630657306583065930660306613066230663306643066530666306673066830669306703067130672306733067430675306763067730678306793068030681306823068330684306853068630687306883068930690306913069230693306943069530696306973069830699307003070130702307033070430705307063070730708307093071030711307123071330714307153071630717307183071930720307213072230723307243072530726307273072830729307303073130732307333073430735307363073730738307393074030741307423074330744307453074630747307483074930750307513075230753307543075530756307573075830759307603076130762307633076430765307663076730768307693077030771307723077330774307753077630777307783077930780307813078230783307843078530786307873078830789307903079130792307933079430795307963079730798307993080030801308023080330804308053080630807308083080930810308113081230813308143081530816308173081830819308203082130822308233082430825308263082730828308293083030831308323083330834308353083630837308383083930840308413084230843308443084530846308473084830849308503085130852308533085430855308563085730858308593086030861308623086330864308653086630867308683086930870308713087230873308743087530876308773087830879308803088130882308833088430885308863088730888308893089030891308923089330894308953089630897308983089930900309013090230903309043090530906309073090830909309103091130912309133091430915309163091730918309193092030921309223092330924309253092630927309283092930930309313093230933309343093530936309373093830939309403094130942309433094430945309463094730948309493095030951309523095330954309553095630957309583095930960309613096230963309643096530966309673096830969309703097130972309733097430975309763097730978309793098030981309823098330984309853098630987309883098930990309913099230993309943099530996309973099830999310003100131002310033100431005310063100731008310093101031011310123101331014310153101631017310183101931020310213102231023310243102531026310273102831029310303103131032310333103431035310363103731038310393104031041310423104331044310453104631047310483104931050310513105231053310543105531056310573105831059310603106131062310633106431065310663106731068310693107031071310723107331074310753107631077310783107931080310813108231083310843108531086310873108831089310903109131092310933109431095310963109731098310993110031101311023110331104311053110631107311083110931110311113111231113311143111531116311173111831119311203112131122311233112431125311263112731128311293113031131311323113331134311353113631137311383113931140311413114231143311443114531146311473114831149311503115131152311533115431155311563115731158311593116031161311623116331164311653116631167311683116931170311713117231173311743117531176311773117831179311803118131182311833118431185311863118731188311893119031191311923119331194311953119631197311983119931200312013120231203312043120531206312073120831209312103121131212312133121431215312163121731218312193122031221312223122331224312253122631227312283122931230312313123231233312343123531236312373123831239312403124131242312433124431245312463124731248312493125031251312523125331254312553125631257312583125931260312613126231263312643126531266312673126831269312703127131272312733127431275312763127731278312793128031281312823128331284312853128631287312883128931290312913129231293312943129531296312973129831299313003130131302313033130431305313063130731308313093131031311313123131331314313153131631317313183131931320313213132231323313243132531326313273132831329313303133131332313333133431335313363133731338313393134031341313423134331344313453134631347313483134931350313513135231353313543135531356313573135831359313603136131362313633136431365313663136731368313693137031371313723137331374313753137631377313783137931380313813138231383313843138531386313873138831389313903139131392313933139431395313963139731398313993140031401314023140331404314053140631407314083140931410314113141231413314143141531416314173141831419314203142131422314233142431425314263142731428314293143031431314323143331434314353143631437314383143931440314413144231443314443144531446314473144831449314503145131452314533145431455314563145731458314593146031461314623146331464314653146631467314683146931470314713147231473314743147531476314773147831479314803148131482314833148431485314863148731488314893149031491314923149331494314953149631497314983149931500315013150231503315043150531506315073150831509315103151131512315133151431515315163151731518315193152031521315223152331524315253152631527315283152931530315313153231533315343153531536315373153831539315403154131542315433154431545315463154731548315493155031551315523155331554315553155631557315583155931560315613156231563315643156531566315673156831569315703157131572315733157431575315763157731578315793158031581315823158331584315853158631587315883158931590315913159231593315943159531596315973159831599316003160131602316033160431605316063160731608316093161031611316123161331614316153161631617316183161931620316213162231623316243162531626316273162831629316303163131632316333163431635316363163731638316393164031641316423164331644316453164631647316483164931650316513165231653316543165531656316573165831659316603166131662316633166431665316663166731668316693167031671316723167331674316753167631677316783167931680316813168231683316843168531686316873168831689316903169131692316933169431695316963169731698316993170031701317023170331704317053170631707317083170931710317113171231713317143171531716317173171831719317203172131722317233172431725317263172731728317293173031731317323173331734317353173631737317383173931740317413174231743317443174531746317473174831749317503175131752317533175431755317563175731758317593176031761317623176331764317653176631767317683176931770317713177231773317743177531776317773177831779317803178131782317833178431785317863178731788317893179031791317923179331794317953179631797317983179931800318013180231803318043180531806318073180831809318103181131812318133181431815318163181731818318193182031821318223182331824318253182631827318283182931830318313183231833318343183531836318373183831839318403184131842318433184431845318463184731848318493185031851318523185331854318553185631857318583185931860318613186231863318643186531866318673186831869318703187131872318733187431875318763187731878318793188031881318823188331884318853188631887318883188931890318913189231893318943189531896318973189831899319003190131902319033190431905319063190731908319093191031911319123191331914319153191631917319183191931920319213192231923319243192531926319273192831929319303193131932319333193431935319363193731938319393194031941319423194331944319453194631947319483194931950319513195231953319543195531956319573195831959319603196131962319633196431965319663196731968319693197031971319723197331974319753197631977319783197931980319813198231983319843198531986319873198831989319903199131992319933199431995319963199731998319993200032001320023200332004320053200632007320083200932010320113201232013320143201532016320173201832019320203202132022320233202432025320263202732028320293203032031320323203332034320353203632037320383203932040320413204232043320443204532046320473204832049320503205132052320533205432055320563205732058320593206032061320623206332064320653206632067320683206932070320713207232073320743207532076320773207832079320803208132082320833208432085320863208732088320893209032091320923209332094320953209632097320983209932100321013210232103321043210532106321073210832109321103211132112321133211432115321163211732118321193212032121321223212332124321253212632127321283212932130321313213232133321343213532136321373213832139321403214132142321433214432145321463214732148321493215032151321523215332154321553215632157321583215932160321613216232163321643216532166321673216832169321703217132172321733217432175321763217732178321793218032181321823218332184321853218632187321883218932190321913219232193321943219532196321973219832199322003220132202322033220432205322063220732208322093221032211322123221332214322153221632217322183221932220322213222232223322243222532226322273222832229322303223132232322333223432235322363223732238322393224032241322423224332244322453224632247322483224932250322513225232253322543225532256322573225832259322603226132262322633226432265322663226732268322693227032271322723227332274322753227632277322783227932280322813228232283322843228532286322873228832289322903229132292322933229432295322963229732298322993230032301323023230332304323053230632307323083230932310323113231232313323143231532316323173231832319323203232132322323233232432325323263232732328323293233032331323323233332334323353233632337323383233932340323413234232343323443234532346323473234832349323503235132352323533235432355323563235732358323593236032361323623236332364323653236632367323683236932370323713237232373323743237532376323773237832379323803238132382323833238432385323863238732388323893239032391323923239332394323953239632397323983239932400324013240232403324043240532406324073240832409324103241132412324133241432415324163241732418324193242032421324223242332424324253242632427324283242932430324313243232433324343243532436324373243832439324403244132442324433244432445324463244732448324493245032451324523245332454324553245632457324583245932460324613246232463324643246532466324673246832469324703247132472324733247432475324763247732478324793248032481324823248332484324853248632487324883248932490324913249232493324943249532496324973249832499325003250132502325033250432505325063250732508325093251032511325123251332514325153251632517325183251932520325213252232523325243252532526325273252832529325303253132532325333253432535325363253732538325393254032541325423254332544325453254632547325483254932550325513255232553325543255532556325573255832559325603256132562325633256432565325663256732568325693257032571325723257332574325753257632577325783257932580325813258232583325843258532586325873258832589325903259132592325933259432595325963259732598325993260032601326023260332604326053260632607326083260932610326113261232613326143261532616326173261832619326203262132622326233262432625326263262732628326293263032631326323263332634326353263632637326383263932640326413264232643326443264532646326473264832649326503265132652326533265432655326563265732658326593266032661326623266332664326653266632667326683266932670326713267232673326743267532676326773267832679326803268132682326833268432685326863268732688326893269032691326923269332694326953269632697326983269932700327013270232703327043270532706327073270832709327103271132712327133271432715327163271732718327193272032721327223272332724327253272632727327283272932730327313273232733327343273532736327373273832739327403274132742327433274432745327463274732748327493275032751327523275332754327553275632757327583275932760327613276232763327643276532766327673276832769327703277132772327733277432775327763277732778327793278032781327823278332784327853278632787327883278932790327913279232793327943279532796327973279832799328003280132802328033280432805328063280732808328093281032811328123281332814328153281632817328183281932820328213282232823328243282532826328273282832829328303283132832328333283432835328363283732838328393284032841328423284332844328453284632847328483284932850328513285232853328543285532856328573285832859328603286132862328633286432865328663286732868328693287032871328723287332874328753287632877328783287932880328813288232883328843288532886328873288832889328903289132892328933289432895328963289732898328993290032901329023290332904329053290632907329083290932910329113291232913329143291532916329173291832919329203292132922329233292432925329263292732928329293293032931329323293332934329353293632937329383293932940329413294232943329443294532946329473294832949329503295132952329533295432955329563295732958329593296032961329623296332964329653296632967329683296932970329713297232973329743297532976329773297832979329803298132982329833298432985329863298732988329893299032991329923299332994329953299632997329983299933000330013300233003330043300533006330073300833009330103301133012330133301433015330163301733018330193302033021330223302333024330253302633027330283302933030330313303233033330343303533036330373303833039330403304133042330433304433045330463304733048330493305033051330523305333054330553305633057330583305933060330613306233063330643306533066330673306833069330703307133072330733307433075330763307733078330793308033081330823308333084330853308633087330883308933090330913309233093330943309533096330973309833099331003310133102331033310433105331063310733108331093311033111331123311333114331153311633117331183311933120331213312233123331243312533126331273312833129331303313133132331333313433135331363313733138331393314033141331423314333144331453314633147331483314933150331513315233153331543315533156331573315833159331603316133162331633316433165331663316733168331693317033171331723317333174331753317633177331783317933180331813318233183331843318533186331873318833189331903319133192331933319433195331963319733198331993320033201332023320333204332053320633207332083320933210332113321233213332143321533216332173321833219332203322133222332233322433225332263322733228332293323033231332323323333234332353323633237332383323933240332413324233243332443324533246332473324833249332503325133252332533325433255332563325733258332593326033261332623326333264332653326633267332683326933270332713327233273332743327533276332773327833279332803328133282332833328433285332863328733288332893329033291332923329333294332953329633297332983329933300333013330233303333043330533306333073330833309333103331133312333133331433315333163331733318333193332033321333223332333324333253332633327333283332933330333313333233333333343333533336333373333833339333403334133342333433334433345333463334733348333493335033351333523335333354333553335633357333583335933360333613336233363333643336533366333673336833369333703337133372333733337433375333763337733378333793338033381333823338333384333853338633387333883338933390333913339233393333943339533396333973339833399334003340133402334033340433405334063340733408334093341033411334123341333414334153341633417334183341933420334213342233423334243342533426334273342833429334303343133432334333343433435334363343733438334393344033441334423344333444334453344633447334483344933450334513345233453334543345533456334573345833459334603346133462334633346433465334663346733468334693347033471334723347333474334753347633477334783347933480334813348233483334843348533486334873348833489334903349133492334933349433495334963349733498334993350033501335023350333504335053350633507335083350933510335113351233513335143351533516335173351833519335203352133522335233352433525335263352733528335293353033531335323353333534335353353633537335383353933540335413354233543335443354533546335473354833549335503355133552335533355433555335563355733558335593356033561335623356333564335653356633567335683356933570335713357233573335743357533576335773357833579335803358133582335833358433585335863358733588335893359033591335923359333594335953359633597335983359933600336013360233603336043360533606336073360833609336103361133612336133361433615336163361733618336193362033621336223362333624336253362633627336283362933630336313363233633336343363533636336373363833639336403364133642336433364433645336463364733648336493365033651336523365333654336553365633657336583365933660336613366233663336643366533666336673366833669336703367133672336733367433675336763367733678336793368033681336823368333684336853368633687336883368933690336913369233693336943369533696336973369833699337003370133702337033370433705337063370733708337093371033711337123371333714337153371633717337183371933720337213372233723337243372533726337273372833729337303373133732337333373433735337363373733738337393374033741337423374333744337453374633747337483374933750337513375233753337543375533756337573375833759337603376133762337633376433765337663376733768337693377033771337723377333774337753377633777337783377933780337813378233783337843378533786337873378833789337903379133792337933379433795337963379733798337993380033801338023380333804338053380633807338083380933810338113381233813338143381533816338173381833819338203382133822338233382433825338263382733828338293383033831338323383333834338353383633837338383383933840338413384233843338443384533846338473384833849338503385133852338533385433855338563385733858338593386033861338623386333864338653386633867338683386933870338713387233873338743387533876338773387833879338803388133882338833388433885338863388733888338893389033891338923389333894338953389633897338983389933900339013390233903339043390533906339073390833909339103391133912339133391433915339163391733918339193392033921339223392333924339253392633927339283392933930339313393233933339343393533936339373393833939339403394133942339433394433945339463394733948339493395033951339523395333954339553395633957339583395933960339613396233963339643396533966339673396833969339703397133972339733397433975339763397733978339793398033981339823398333984339853398633987339883398933990339913399233993339943399533996339973399833999340003400134002340033400434005340063400734008340093401034011340123401334014340153401634017340183401934020340213402234023340243402534026340273402834029340303403134032340333403434035340363403734038340393404034041340423404334044340453404634047340483404934050340513405234053340543405534056340573405834059340603406134062340633406434065340663406734068340693407034071340723407334074340753407634077340783407934080340813408234083340843408534086340873408834089340903409134092340933409434095340963409734098340993410034101341023410334104341053410634107341083410934110341113411234113341143411534116341173411834119341203412134122341233412434125341263412734128341293413034131341323413334134341353413634137341383413934140341413414234143341443414534146341473414834149341503415134152341533415434155341563415734158341593416034161341623416334164341653416634167341683416934170341713417234173341743417534176341773417834179341803418134182341833418434185341863418734188341893419034191341923419334194341953419634197341983419934200342013420234203342043420534206342073420834209342103421134212342133421434215342163421734218342193422034221342223422334224342253422634227342283422934230342313423234233342343423534236342373423834239342403424134242342433424434245342463424734248342493425034251342523425334254342553425634257342583425934260342613426234263342643426534266342673426834269342703427134272342733427434275342763427734278342793428034281342823428334284342853428634287342883428934290342913429234293342943429534296342973429834299343003430134302343033430434305343063430734308343093431034311343123431334314343153431634317343183431934320343213432234323343243432534326343273432834329343303433134332343333433434335343363433734338343393434034341343423434334344343453434634347343483434934350343513435234353343543435534356343573435834359343603436134362343633436434365343663436734368343693437034371343723437334374343753437634377343783437934380343813438234383343843438534386343873438834389343903439134392343933439434395343963439734398343993440034401344023440334404344053440634407344083440934410344113441234413344143441534416344173441834419344203442134422344233442434425344263442734428344293443034431344323443334434344353443634437344383443934440344413444234443344443444534446344473444834449344503445134452344533445434455344563445734458344593446034461344623446334464344653446634467344683446934470344713447234473344743447534476344773447834479344803448134482344833448434485344863448734488344893449034491344923449334494344953449634497344983449934500345013450234503345043450534506345073450834509345103451134512345133451434515345163451734518345193452034521345223452334524345253452634527345283452934530345313453234533345343453534536345373453834539345403454134542345433454434545345463454734548345493455034551345523455334554345553455634557345583455934560345613456234563345643456534566345673456834569345703457134572345733457434575345763457734578345793458034581345823458334584345853458634587345883458934590345913459234593345943459534596345973459834599346003460134602346033460434605346063460734608346093461034611346123461334614346153461634617346183461934620346213462234623346243462534626346273462834629346303463134632346333463434635346363463734638346393464034641346423464334644346453464634647346483464934650346513465234653346543465534656346573465834659346603466134662346633466434665346663466734668346693467034671346723467334674346753467634677346783467934680346813468234683346843468534686346873468834689346903469134692346933469434695346963469734698346993470034701347023470334704347053470634707347083470934710347113471234713347143471534716347173471834719347203472134722347233472434725347263472734728347293473034731347323473334734347353473634737347383473934740347413474234743347443474534746347473474834749347503475134752347533475434755347563475734758347593476034761347623476334764347653476634767347683476934770347713477234773347743477534776347773477834779347803478134782347833478434785347863478734788347893479034791347923479334794347953479634797347983479934800348013480234803348043480534806348073480834809348103481134812348133481434815348163481734818348193482034821348223482334824348253482634827348283482934830 |
- \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 3CE464558A84FDC69DB40CFB090B11993D9AEBB5
- @set OPENPGP-SIGNING-KEY-URL https://sv.gnu.org/people/viewgpg.php?user_id=15145
- @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 ci.guix.gnu.org
- @set SUBSTITUTE-URL https://@value{SUBSTITUTE-SERVER}
- @copying
- Copyright @copyright{} 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020, 2021 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 Ricardo Wurmus@*
- Copyright @copyright{} 2016 Ben Woodcroft@*
- Copyright @copyright{} 2016, 2017, 2018 Chris Marusich@*
- Copyright @copyright{} 2016, 2017, 2018, 2019, 2020 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 Julien Lepiller@*
- Copyright @copyright{} 2016 Alex ter Weele@*
- Copyright @copyright{} 2016, 2017, 2018, 2019 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 Christopher Lemmer Webber@*
- Copyright @copyright{} 2017, 2018, 2019, 2020 Marius Bakke@*
- Copyright @copyright{} 2017, 2019, 2020 Hartmut Goebel@*
- Copyright @copyright{} 2017, 2019, 2020, 2021 Maxim Cournoyer@*
- Copyright @copyright{} 2017, 2018, 2019, 2020 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 Guillaume Le Vaillant@*
- Copyright @copyright{} 2020 Leo Prikler@*
- Copyright @copyright{} 2019, 2020 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 Brice Waegeneire@*
- Copyright @copyright{} 2020 R Veera Kumar@*
- Copyright @copyright{} 2020 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{} 2021 Maxime Devos@*
- 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 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}.
- @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.
- * Documentation:: Browsing software user manuals.
- * Installing Debugging Files:: Feeding the debugger.
- * 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 Server:: One particular source of substitutes.
- * Substitute Server Authorization:: How to enable or disable substitutes.
- * Getting Substitutes from Other Servers:: Substitute diversity.
- * Getting Substitutes from Other Protocols:: Different sources of substitutes.
- * 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.
- * 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.
- * Channels with Substitutes:: Using channels with available substitutes.
- Development
- * 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.
- * 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 Substituters:: Defining new substitution methods.
- 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 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.
- * 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.
- Services
- * Base Services:: Essential system services.
- * Scheduled Job Execution:: The mcron service.
- * Log Rotation:: The rottlog service.
- * Networking Services:: Network setup, 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:: The Cuirass service.
- * 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.
- 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 (deprecated)
- 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.
- @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}.
- @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
- 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}} or one of its mirrors
- (@pxref{Substitutes}), authorize them:
- @example
- # guix archive --authorize < \
- ~root/.config/guix/current/share/guix/@value{SUBSTITUTE-SERVER}.pub
- @end example
- @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 or
- 2.2.x;
- @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};
- @item @uref{https://notabug.org/guile-lzlib/guile-lzlib, Guile-lzlib};
- @item @uref{https://www.nongnu.org/guile-avahi/, Guile-Avahi};
- @item
- @c FIXME: Specify a version number once a release has been made.
- @uref{https://gitlab.com/guile-git/guile-git, Guile-Git}, version 0.3.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
- 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
- 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")
- (private-key
- (string-append (getenv "HOME")
- "/.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 preferrable 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{Invoking guix build, @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{https://@value{SUBSTITUTE-SERVER}} 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.
- @item --substitute-methods=@var{methods}
- Consider @var{methods} the whitespace-separated list of substitution
- methods (‘substituters’) to use. When this option is omitted, @code{http}
- is used. The @code{http} substituter supports both the HTTP and HTTPS
- protocol.
- @xref{Defining Substituters} for information on how to define new
- substituters, and @pxref{Getting Substitutes from Other Protocols}
- on how to use non-HTTP and non-HTTPS substituters.
- @c TODO: see <section> for information on how to configure the
- @c IPFS and GNUnet substituters
- @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 Bzip2 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
- 917@tie{}MiB@. Alternatively, the @code{glibc-utf8-locales} is smaller but
- limited to a few UTF-8 locales.
- 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{gs-fonts}, @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.xz},
- 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.xz.sig
- $ gpg --verify guix-system-install-@value{VERSION}.x86_64-linux.iso.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 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
- To copy the image to a USB stick, follow these steps:
- @enumerate
- @item
- Decompress the image using the @command{xz} command:
- @example
- xz -d guix-system-install-@value{VERSION}.x86_64-linux.iso.xz
- @end example
- @item
- 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.
- @end enumerate
- @unnumberedsubsec Burning on a DVD
- To copy the image to a DVD, follow these steps:
- @enumerate
- @item
- Decompress the image using the @command{xz} command:
- @example
- xz -d guix-system-install-@value{VERSION}.x86_64-linux.iso.xz
- @end example
- @item
- 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.
- @end enumerate
- @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, and F2FS 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). Assuming you want to
- store the root partition on @file{/dev/sda2}, the command sequence would
- be along these lines:
- @example
- cryptsetup luksFormat /dev/sda2
- cryptsetup open --type luks /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{Memory
- Concepts, swap space,, libc, The GNU C Library Reference Manual}), 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 GNU Zile (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 target
- 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{target} field
- names a device, like @code{/dev/sda}; for UEFI systems it names a path
- to a mounted EFI partition, like @code{/boot/efi}; do make sure the path is
- 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 ran
- 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 Freenode 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
- You've installed your first package, congrats! 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, @code{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 environment} 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 environment}).
- @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
- 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. It 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 environment}).
- 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
- @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.
- 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.
- @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=python | recsel -p name,version
- name: python
- version: 2.7.6
- name: python
- version: 3.3.5
- @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 python@@3.4 | recsel -p name,version
- name: python
- version: 3.4.3
- @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 Server:: One particular source of substitutes.
- * Substitute Server Authorization:: How to enable or disable substitutes.
- * Getting Substitutes from Other Servers:: Substitute diversity.
- * Getting Substitutes from Other Protocols:: Different sources of substitutes.
- * 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 Server
- @subsection Official Substitute Server
- @cindex build farm
- The @code{@value{SUBSTITUTE-SERVER}} server is a front-end to an official build farm
- that builds packages from Guix continuously for some
- architectures, and makes them available as substitutes. This is the
- default source of substitutes; it 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 farm 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}} or a
- mirror thereof, you
- must add its 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 @code{@value{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}} by default.
- @end quotation
- The public key for @code{@value{SUBSTITUTE-SERVER}} is installed along with Guix, in
- @code{@var{prefix}/share/guix/@value{SUBSTITUTE-SERVER}.pub}, 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}.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
- @code{@value{SUBSTITUTE-SERVER}} 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}}. 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 https://@value{SUBSTITUTE-SERVER}'
- @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}}
- as a fallback. 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 Getting Substitutes from Other Protocols
- @subsection Getting Substitutes from Other Protocols
- @cindex substitute servers, alternative protocols
- This subsection probably won't make much sense yet,
- as currently only the HTTP and HTTPS protocols are supported
- for substitution. Consider what follows as a peek into the future!
- Guix will support multiple substitution methods -- currently only
- a substituter for HTTP and HTTPS is defined, but a substituter for
- the P2P networks IPFS and GNUnet will be defined in the future.
- @c The IPFS substituter has actually already been implemented,
- @c see http://issues.guix.gnu.org/33899, but it requires some changes
- @c and is not yet available to the end-user.
- In order to use a substition method, it must first be enabled in the
- guix daemon
- (@pxref{Invoking guix-daemon, @option{--substitute-methods}}).
- For example, to enable the HTTP/S and the yet-to-be-written IPFS
- substituter, pass @code{--substitute-methods='http ipfs'}.
- This must be set in the daemon, and cannot be done from a user process.
- @c XXX ^ is this sentence clear? I mean ``guix build --substitute-methods``
- @c won't work, as substitution happens in the daemon (well, in a process
- @c started by the daemon to be precise).
- Also include an URL supported by the substituter in the list of
- substitute server URLs. That's all there is to it!
- @c TODO ^ when using the IPFS substituter, the daemon also needs -
- @c to know the IPFS gateway, and when using the GNUnet substituter,
- @c GNUnet needs to be running. But let's first actually implement
- @c & merge these substituters ...
- @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 @code{@value{SUBSTITUTE-SERVER}} substitutes can be
- convenient, we encourage users to also build on their own, or even run
- their own build farm, such that @code{@value{SUBSTITUTE-SERVER}} is 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
- 2 new packages: keepalived, libnfnetlink
- 6 packages upgraded: emacs-nix-mode@@2.0.4,
- guile2.0-guix@@0.14.0-12.77a1aac, guix@@0.14.0-12.77a1aac,
- heimdal@@7.5.0, milkytracker@@1.02.00, nix@@2.0.4
- 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
- 28 new packages: emacs-helm-ls-git, emacs-helm-mu, @dots{}
- 69 packages upgraded: borg@@1.1.6, cheese@@3.28.0, @dots{}
- @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 the list of packages added or upgraded since the previous
- generation, as well as, occasionally, news written by channel authors
- for their users (@pxref{Channels, Writing Channel News}).
- The package information is the same as displayed upon @command{guix
- pull} completion, but without ellipses; it is also similar to the output
- of @command{guix pull -l} for the last generation (see below).
- @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}).
- @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 use 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}} to @file{/tmp/emacs}:
- @example
- $ wget -O - \
- https://@value{SUBSTITUTE-SERVER}/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}/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.
- * 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.
- * Channels with Substitutes:: Using channels with available substitutes.
- @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 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.
- 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.
- @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.
- @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 environment} command provides a convenient way to set up
- @dfn{development environments} containing all the dependencies and tools
- necessary to work on the software package of your choice. 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 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 environment
- @section Invoking @command{guix environment}
- @cindex reproducible build environments
- @cindex development environments
- @cindex @command{guix environment}
- @cindex environment, package build environment
- The purpose of @command{guix environment} is to assist hackers in
- creating reproducible development environments without polluting their
- package profile. The @command{guix environment} tool takes one or more
- packages, builds all of their inputs, and creates a shell
- environment to use them.
- 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{}2.7 and
- NumPy:
- @example
- guix environment --ad-hoc python2-numpy python-2.7 -- python
- @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 --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.
- @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 --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 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 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 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
- @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.
- @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.
- * 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 Substituters:: Defining new substitution methods.
- @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 `(("gawk" ,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
- What about these quote (@code{'}) characters? They are Scheme syntax to
- introduce a literal list; @code{'} is synonymous with @code{quote}.
- @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 define an
- input called @code{"gawk"} whose value is that of the @code{gawk}
- variable; @code{gawk} is itself bound to a @code{<package>} object.
- @cindex backquote (quasiquote)
- @findex `
- @findex quasiquote
- @cindex comma (unquote)
- @findex ,
- @findex unquote
- @findex ,@@
- @findex unquote-splicing
- Again, @code{`} (a backquote, synonymous with @code{quasiquote}) allows
- us to introduce a literal list in the @code{inputs} field, while
- @code{,} (a comma, synonymous with @code{unquote}) allows us to insert a
- value in that list (@pxref{Expression Syntax, unquote,, guile, GNU Guile
- Reference Manual}).
- 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.
- @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 one is 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"} (@pxref{Packages with Multiple Outputs}, for
- more on package outputs). For example, the list below specifies three
- inputs:
- @lisp
- `(("libffi" ,libffi)
- ("libunistring" ,libunistring)
- ("glib:bin" ,glib "bin")) ;the "bin" output of Glib
- @end lisp
- @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.
- @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.
- @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)
- `(("self" ,this-package))
- '())))
- @end lisp
- It is an error to refer to @code{this-package} outside a package definition.
- @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,
- either the full SHA1 commit or a ``short'' commit string; the latter is
- not recommended) or the tag to fetch.
- @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'
- (srfi srfi-1)) ;for 'alist-delete'
- (define gdb-sans-guile
- (package
- (inherit gdb)
- (inputs (alist-delete "guile"
- (package-inputs gdb)))))
- @end lisp
- The @code{alist-delete} call above removes the tuple from the
- @code{inputs} field that has @code{"guile"} as its first element
- (@pxref{SRFI-1 Association Lists,,, guile, GNU Guile Reference
- Manual}).
- 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
- `(("lua" ,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},
- notably@footnote{Please see the @code{(guix build gnu-build-system)}
- modules for more details about the build phases.}:
- @table @code
- @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
- @vindex %standard-phases
- The build-side module @code{(guix build gnu-build-system)} defines
- @code{%standard-phases} as the default list of build phases.
- @code{%standard-phases} is a list of symbol/procedure pairs, where the
- procedure implements the actual phase.
- @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.
- @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 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{install} phase installs the binaries
- defined by the crate.
- @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.
- @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 is read from the file @file{Project.toml}. This
- value can be overridden by passing the argument @code{#:julia-file-name}
- (which must be correctly capitalized).
- For packages requiring shared library dependencies, you may need to write the
- @file{/deps/deps.jl} file manually. It's usually a line of @code{const
- variable = /gnu/store/library.so} for each dependency, plus a void function
- @code{check_deps() = nothing}.
- Some older packages that aren't using @file{Package.toml} yet, will require
- this file to be created, too. The function @code{julia-create-package-toml}
- helps creating the file. You need to pass the outputs and the source of the
- package, it's name (the same as the @code{file-name} parameter), the package
- uuid, the package version, and a list of dependencies specified by their name
- and their uuid.
- @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} 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{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}.
- @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. The default Meson is
- @code{meson-for-build}, which is special because it doesn't clear the
- @code{RUNPATH} of binaries and libraries when they are installed.
- 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 @code{ninja} with the target specified in @code{#:test-target},
- which is @code{"test"} by default.
- @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-for-build}, 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 standard
- phases include an @code{unpack} phase to unpack the source code tarball,
- a @command{configure} phase to run @code{./configure}, a @code{build}
- phase to run @command{make}, and (among others) an @code{install} phase
- to run @command{make install}; @pxref{Build Systems}, for a more
- detailed view of these phases. Likewise, @code{cmake-build-system}
- inherits these phases, but its @code{configure} phase runs
- @command{cmake} instead of @command{./configure}. Other build systems,
- 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.
- 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] [#:keep-mtime? #f]
- Copy @var{source} directory to @var{destination}. Follow symlinks if
- @var{follow-symlinks?} is true; otherwise, just preserve them. When
- @var{keep-mtime?} is true, keep the modification time of the files in
- @var{source} on those of @var{destination}. 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" letter 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
- @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")))
- #t))))
- @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)
- #t))))
- @end lisp
- @c TODO: Add more examples.
- @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 vm)))
- (gexp->derivation "something-with-vms"
- #~(begin
- (use-modules (guix build utils)
- (gnu build vm))
- @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
- @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
- @include substituters.texi
- @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 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 | cut -f1,2 --output-delimiter=@@`
- @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, and 2 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
- @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 or a tag.
- @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}/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{Invoking guix build, @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 environment --no-grafts -C foo --ad-hoc strace gdb
- [env]# source ./environment-variables
- [env]# cd foo-1.2
- @end example
- Here, @command{guix environment -C} creates a container and spawns a new
- shell in it (@pxref{Invoking guix environment}). The @command{--ad-hoc
- 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 environment}.)
- 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 a file, 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 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
- Compute the hash on @var{file} recursively.
- In this case, the hash is computed on an archive 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 has no impact on the
- hash (@pxref{Invoking guix archive}).
- @c FIXME: Replace xref above with xref to an ``Archive'' section when
- @c it exists.
- @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 -rx .
- @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 @code{itsdangerous} Python
- package:
- @example
- guix import pypi itsdangerous
- @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 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
- 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 metadata from @uref{https://www.ctan.org/, CTAN}, the
- comprehensive TeX archive network for TeX packages that are part of the
- @uref{https://www.tug.org/texlive/, TeX Live distribution}.
- Information about the package is obtained through the XML API provided
- by CTAN, while the source code is downloaded from the SVN repository of
- the Tex Live project. This is done because the CTAN does not keep
- versioned archives.
- The command command below imports metadata for the @code{fontspec}
- TeX package:
- @example
- guix import texlive fontspec
- @end example
- When @option{--archive=@var{directory}} is added, the source code is
- downloaded not from the @file{latex} sub-directory of the
- @file{texmf-dist/source} tree in the TeX Live SVN repository, but from
- the specified sibling @var{directory} under the same root.
- The command below imports metadata for the @code{ifxetex} package from
- CTAN while fetching the sources from the directory
- @file{texmf/source/generic}:
- @example
- guix import texlive --archive=generic ifxetex
- @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 nix
- Import metadata from a local copy of the source of the
- @uref{https://nixos.org/nixpkgs/, Nixpkgs distribution}@footnote{This
- relies on the @command{nix-instantiate} command of
- @uref{https://nixos.org/nix/, Nix}.}. Package definitions in Nixpkgs are
- typically written in a mixture of Nix-language and Bash code. This
- command only imports the high-level package structure that is written in
- the Nix language. It normally includes all the basic fields of a
- package definition.
- When importing a GNU package, the synopsis and descriptions are replaced
- by their canonical upstream variant.
- Usually, you will first need to do:
- @example
- export NIX_REMOTE=daemon
- @end example
- @noindent
- so that @command{nix-instantiate} does not try to open the Nix database.
- As an example, the command below imports the package definition of
- LibreOffice (more precisely, it imports the definition of the package
- bound to the @code{libreoffice} top-level attribute):
- @example
- guix import nix ~/path/to/nixpkgs libreoffice
- @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://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
- Select the given repository (a repository name). Possible values include:
- @itemize
- @item @code{opam}, the default opam repository,
- @item @code{coq} or @code{coq-released}, the stable repository for coq packages,
- @item @code{coq-core-dev}, the repository that contains development versions of coq,
- @item @code{coq-extra-dev}, the repository that contains development versions
- of coq packages.
- @end itemize
- @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 developers
- of the GNU software distribution. By default, it 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:35:2: warning: no updater for acl
- gnu/packages/m4.scm:30:12: info: 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: info: 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 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 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.
- @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
- @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.
- 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-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.
- @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 geiser@@0.4 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
- @ref{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 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.
- @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
- 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}} 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 --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} https://guix.example.org"
- updating list of substitutes from 'https://@value{SUBSTITUTE-SERVER}'... 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}/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}/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}/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}} 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} 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}/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}} (@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}} 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 environment}
- (@pxref{Invoking guix environment}) 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-URL} -c 10
- computing 8,983 package derivations for x86_64-linux...
- looking for 9,343 store items on @value{SUBSTITUTE-URL}...
- updating substitutes from '@value{SUBSTITUTE-URL}'... 100.0%
- @value{SUBSTITUTE-URL}
- 64.7% substitutes available (6,047 out of 9,343)
- @dots{}
- 2502 packages are missing from '@value{SUBSTITUTE-URL}' 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}}; 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 environment --ad-hoc 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.
- * 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)
- (target "/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 GNU Zile 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 bind "utils")
- %base-packages)))
- @end lisp
- @findex specification->package
- Referring to packages by variable name, like @code{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.
- 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)
- ;; Automatially 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.
- 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, 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
- @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}.
- @cindex swap devices
- @cindex swap space
- @item @code{swap-devices} (default: @code{'()})
- A list of UUIDs, file system labels, or strings identifying devices or
- files to be used for ``swap
- space'' (@pxref{Memory Concepts,,, libc, The GNU C Library Reference
- Manual}). Here are some examples:
- @table @code
- @item (list (uuid "4dab5feb-d176-45de-b287-9b0a6e4c01cb"))
- 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.
- @item (list (file-system-label "swap"))
- Use the partition with label @code{swap}. Again, the
- @command{swaplabel} command allows you to view and change the label of a
- Linux swap partition.
- @item (list "/swapfile")
- Use the file @file{/swapfile} as swap space.
- @item (list "/dev/sda3" "/dev/sdb2")
- Use the @file{/dev/sda3} and @file{/dev/sdb2} partitions as swap space.
- We recommend referring to swap devices by UUIDs or labels as shown above
- instead.
- @end table
- It is possible to specify a swap file in a file system on a mapped
- device (under @file{/dev/mapper}), provided that the necessary device
- mapping and file system are also specified. @xref{Mapped Devices} and
- @ref{File Systems}.
- @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 string-valued G-expressions denoting setuid programs.
- @xref{Setuid Programs}.
- @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 needs to be checked for
- errors before being mounted.
- @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{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 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.
- @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)
- (target "/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 Services:: Network setup, 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:: The Cuirass service.
- * 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.
- @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{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}}
- (@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}} (@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}}. 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{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{'bzip2})
- 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))})
- 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.
- @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"))))
- (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
- 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
- it 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
- @node Networking Services
- @subsection Networking Services
- The @code{(gnu services networking)} module provides services to configure
- the network interface.
- @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
- @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
- @defvr {Scheme Variable} static-networking-service-type
- This is the type for statically-configured network interfaces.
- @c TODO Document <static-networking> data structures.
- @end defvr
- @deffn {Scheme Procedure} static-networking-service @var{interface} @var{ip} @
- [#:netmask #f] [#:gateway #f] [#:name-servers @code{'()}] @
- [#:requirement @code{'(udev)}]
- Return a service that starts @var{interface} with address @var{ip}. If
- @var{netmask} is true, use it as the network mask. If @var{gateway} is true,
- it must be a string specifying the default network gateway. @var{requirement}
- can be used to declare a dependency on another service before configuring the
- interface.
- This procedure can be called several times, one for each network
- interface of interest. Behind the scenes what it does is extend
- @code{static-networking-service-type} with additional network interfaces
- to handle.
- For example:
- @lisp
- (static-networking-service "eno1" "192.168.1.82"
- #:gateway "192.168.1.2"
- #:name-servers '("192.168.1.2"))
- @end lisp
- @end deffn
- @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
- @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
- @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 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 -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 -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 incomming 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 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
- (service rsync-service-type)
- @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{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{use-chroot?} (default: @var{#t})
- Whether to use chroot for @command{rsync} shared directory.
- @item @code{share-path} (default: @file{/srv/rsync})
- Location of the @command{rsync} shared directory.
- @item @code{share-comment} (default: @code{"Rsync share"})
- Comment of the @command{rsync} shared directory.
- @item @code{read-only?} (default: @var{#f})
- Read-write permissions to shared directory.
- @item @code{timeout} (default: @code{300})
- I/O timeout in seconds.
- @item @code{user} (default: @var{"root"})
- Owner of the @code{rsync} process.
- @item @code{group} (default: @var{"root"})
- Group of the @code{rsync} process.
- @item @code{uid} (default: @var{"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: @var{"rsyncd"})
- Group name or group ID that will be used when accessing the module.
- @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 loging 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 'without-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{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{'without-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{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 encryption key. Your peers may ask you for this to put
- # into their AllowedEncryptionPublicKeys configuration.
- EncryptionPublicKey: 378dc5...
- # Your private encryption key. DO NOT share this with anyone!
- EncryptionPrivateKey: 0777...
- # Your public signing key. You should not ordinarily need to share
- # this with anyone.
- SigningPublicKey: e1664...
- # Your private signing key. DO NOT share this with anyone!
- SigningPrivateKey: 0589d...
- @}
- @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 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}).
- @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 (X11)
- @cindex X11 session types
- GDM looks for @dfn{session types} described by the @file{.desktop} files in
- @file{/run/current-system/profile/share/xsessions} and allows users to choose
- a session from the log-in screen. Packages such as @code{gnome}, @code{xfce},
- and @code{i3} 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.
- @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)
- (srfi srfi-1)) ;for 'remove'
- (operating-system
- ;; ...
- (services (cons* (service slim-service-type (slim-configuration
- (display ":0")
- (vt "vt7")))
- (service slim-service-type (slim-configuration
- (display ":1")
- (vt "vt8")))
- (remove (lambda (service)
- (eq? (service-kind service) gdm-service-type))
- %desktop-services))))
- @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{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-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 keep-alive-timeout
- Specifies how long an idle client connection remains open, in seconds.
- Defaults to @samp{30}.
- @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{300}.
- @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-config} 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-config} 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{300}.
- @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 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.github.io,
- 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
- @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 a 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}.
- @item @code{system-script-file} (default: @code{(file-append pulseaudio "/etc/pulse/system.pa")})
- Script file to use as @file{system.pa}.
- @end table
- @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{#false} PostgreSQL does not listen on any Unix-domain sockets, in
- which case only TCP/IP sockets can be used to connect to the server.
- @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{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 MongoDB
- @defvr {Scheme Variable} mongodb-service-type
- This is the service type for @uref{https://www.mongodb.com/, MongoDB}.
- The value for the service type is a @code{mongodb-configuration} object.
- @end defvr
- @lisp
- (service mongodb-service-type)
- @end lisp
- @deftp {Data Type} mongodb-configuration
- Data type representing the configuration of mongodb.
- @table @asis
- @item @code{mongodb} (default: @code{mongodb})
- The MongoDB package to use.
- @item @code{config-file} (default: @code{%default-mongodb-configuration-file})
- The configuration file for MongoDB.
- @item @code{data-directory} (default: @code{"/var/lib/mongodb"})
- This value is used to create the directory, so that it exists and is
- owned by the mongodb user. It should match the data-directory which
- MongoDB is configured to use through the configuration file.
- @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} 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} 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-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 it's 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 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
- @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 provides monitoring metrics, among others network utilization, CPU load
- and disk space consumption:
- @itemize
- @item High performance, high capacity (able to monitor hundreds of thousands of devices).
- @item Auto-discovery of servers and network devices and interfaces.
- @item Low-level discovery, allows to automatically start monitoring new items, file systems or network interfaces among others.
- @item Distributed monitoring with centralized web administration.
- @item Native high performance agents.
- @item SLA, and ITIL KPI metrics on reporting.
- @item High-level (business) view of monitored resources through user-defined visual console screens and dashboards.
- @item Remote command execution through Zabbix proxies.
- @end itemize
- @c %start of fragment
- Available @code{zabbix-server-configuration} fields are:
- @deftypevr {@code{zabbix-server-configuration} parameter} package zabbix-server
- The zabbix-server package.
- @end deftypevr
- @deftypevr {@code{zabbix-server-configuration} parameter} string user
- User who will run the Zabbix server.
- Defaults to @samp{"zabbix"}.
- @end deftypevr
- @deftypevr {@code{zabbix-server-configuration} parameter} group group
- Group who will run the Zabbix server.
- Defaults to @samp{"zabbix"}.
- @end deftypevr
- @deftypevr {@code{zabbix-server-configuration} parameter} string db-host
- Database host name.
- Defaults to @samp{"127.0.0.1"}.
- @end deftypevr
- @deftypevr {@code{zabbix-server-configuration} parameter} string db-name
- Database name.
- Defaults to @samp{"zabbix"}.
- @end deftypevr
- @deftypevr {@code{zabbix-server-configuration} parameter} string db-user
- Database user.
- Defaults to @samp{"zabbix"}.
- @end deftypevr
- @deftypevr {@code{zabbix-server-configuration} parameter} string db-password
- Database password. Please, use @code{include-files} with
- @code{DBPassword=SECRET} inside a specified file instead.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{zabbix-server-configuration} parameter} number db-port
- Database port.
- Defaults to @samp{5432}.
- @end deftypevr
- @deftypevr {@code{zabbix-server-configuration} parameter} string log-type
- 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
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{zabbix-server-configuration} parameter} string log-file
- Log file name for @code{log-type} @code{file} parameter.
- Defaults to @samp{"/var/log/zabbix/server.log"}.
- @end deftypevr
- @deftypevr {@code{zabbix-server-configuration} parameter} string pid-file
- Name of PID file.
- Defaults to @samp{"/var/run/zabbix/zabbix_server.pid"}.
- @end deftypevr
- @deftypevr {@code{zabbix-server-configuration} parameter} string ssl-ca-location
- The location of certificate authority (CA) files for SSL server
- certificate verification.
- Defaults to @samp{"/etc/ssl/certs/ca-certificates.crt"}.
- @end deftypevr
- @deftypevr {@code{zabbix-server-configuration} parameter} string ssl-cert-location
- Location of SSL client certificates.
- Defaults to @samp{"/etc/ssl/certs"}.
- @end deftypevr
- @deftypevr {@code{zabbix-server-configuration} parameter} string extra-options
- Extra options will be appended to Zabbix server configuration file.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{zabbix-server-configuration} parameter} include-files include-files
- You may include individual files or all files in a directory in the
- configuration file.
- Defaults to @samp{()}.
- @end deftypevr
- @c %end of fragment
- @subsubheading Zabbix agent
- @cindex zabbix zabbix-agent
- Zabbix agent gathers information for Zabbix server.
- @c %start of fragment
- Available @code{zabbix-agent-configuration} fields are:
- @deftypevr {@code{zabbix-agent-configuration} parameter} package zabbix-agent
- The zabbix-agent package.
- @end deftypevr
- @deftypevr {@code{zabbix-agent-configuration} parameter} string user
- User who will run the Zabbix agent.
- Defaults to @samp{"zabbix"}.
- @end deftypevr
- @deftypevr {@code{zabbix-agent-configuration} parameter} group group
- Group who will run the Zabbix agent.
- Defaults to @samp{"zabbix"}.
- @end deftypevr
- @deftypevr {@code{zabbix-agent-configuration} parameter} string hostname
- Unique, case sensitive hostname which is required for active checks and
- must match hostname as configured on the server.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{zabbix-agent-configuration} parameter} string log-type
- 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
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{zabbix-agent-configuration} parameter} string log-file
- Log file name for @code{log-type} @code{file} parameter.
- Defaults to @samp{"/var/log/zabbix/agent.log"}.
- @end deftypevr
- @deftypevr {@code{zabbix-agent-configuration} parameter} string pid-file
- Name of PID file.
- Defaults to @samp{"/var/run/zabbix/zabbix_agent.pid"}.
- @end deftypevr
- @deftypevr {@code{zabbix-agent-configuration} parameter} list server
- 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.
- Defaults to @samp{("127.0.0.1")}.
- @end deftypevr
- @deftypevr {@code{zabbix-agent-configuration} parameter} list server-active
- 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.
- Defaults to @samp{("127.0.0.1")}.
- @end deftypevr
- @deftypevr {@code{zabbix-agent-configuration} parameter} string extra-options
- Extra options will be appended to Zabbix server configuration file.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{zabbix-agent-configuration} parameter} include-files include-files
- You may include individual files or all files in a directory in the
- configuration file.
- Defaults to @samp{()}.
- @end deftypevr
- @c %end of fragment
- @subsubheading Zabbix front-end
- @cindex zabbix zabbix-front-end
- This service provides a WEB interface to Zabbix server.
- @c %start of fragment
- Available @code{zabbix-front-end-configuration} fields are:
- @deftypevr {@code{zabbix-front-end-configuration} parameter} nginx-server-configuration-list nginx
- NGINX configuration.
- @end deftypevr
- @deftypevr {@code{zabbix-front-end-configuration} parameter} string db-host
- Database host name.
- Defaults to @samp{"localhost"}.
- @end deftypevr
- @deftypevr {@code{zabbix-front-end-configuration} parameter} number db-port
- Database port.
- Defaults to @samp{5432}.
- @end deftypevr
- @deftypevr {@code{zabbix-front-end-configuration} parameter} string db-name
- Database name.
- Defaults to @samp{"zabbix"}.
- @end deftypevr
- @deftypevr {@code{zabbix-front-end-configuration} parameter} string db-user
- Database user.
- Defaults to @samp{"zabbix"}.
- @end deftypevr
- @deftypevr {@code{zabbix-front-end-configuration} parameter} string db-password
- Database password. Please, use @code{db-secret-file} instead.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{zabbix-front-end-configuration} parameter} string db-secret-file
- Secret file containing the credentials for the Zabbix front-end. The value
- must be a local file name, not a G-expression. You are expected to create
- this file manually. Its contents will be copied into @file{zabbix.conf.php}
- as the value of @code{$DB['PASSWORD']}.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{zabbix-front-end-configuration} parameter} string zabbix-host
- Zabbix server hostname.
- Defaults to @samp{"localhost"}.
- @end deftypevr
- @deftypevr {@code{zabbix-front-end-configuration} parameter} number zabbix-port
- Zabbix server port.
- Defaults to @samp{10051}.
- @end deftypevr
- @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
- @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
- @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
- @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 it's 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.
- @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{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 inexistant 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{disable-any?} (default: @code{#f})
- When set, this forbids queries of the ANY type.
- @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{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{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 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
- @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{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.
- @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://git.savannah.gnu.org/cgit/guix/guix-cuirass.git, 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. Here is an example of a service that polls the Guix repository
- and builds the packages from a manifest. Some of the packages are defined in
- the @code{"custom-packages"} input, which is the equivalent of
- @env{GUIX_PACKAGE_PATH}.
- @lisp
- (define %cuirass-specs
- #~(list
- '((#:name . "my-manifest")
- (#:load-path-inputs . ("guix"))
- (#:package-path-inputs . ("custom-packages"))
- (#:proc-input . "guix")
- (#:proc-file . "build-aux/cuirass/gnu-system.scm")
- (#:proc . cuirass-jobs)
- (#:proc-args . ((subset . "manifests")
- (systems . ("x86_64-linux"))
- (manifests . (("config" . "guix/manifest.scm")))))
- (#:inputs . (((#:name . "guix")
- (#:url . "git://git.savannah.gnu.org/guix.git")
- (#:load-path . ".")
- (#:branch . "master")
- (#:no-compile? . #t))
- ((#:name . "config")
- (#:url . "https://git.example.org/config.git")
- (#:load-path . ".")
- (#:branch . "master")
- (#:no-compile? . #t))
- ((#:name . "custom-packages")
- (#:url . "https://git.example.org/custom-packages.git")
- (#:load-path . ".")
- (#:branch . "master")
- (#:no-compile? . #t)))))))
- (service cuirass-service-type
- (cuirass-configuration
- (specifications %cuirass-specs)))
- @end lisp
- 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{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{queries-log-file} (default: @code{#f})
- Location of the SQL queries log file. By default, SQL queries logging is
- disabled.
- @item @code{web-queries-log-file} (default: @code{#f})
- Location of the web SQL queries log file. By default, web SQL queries
- logging is disabled.
- @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{queue-size} (default: @code{1})
- Size of the database writer queue.
- @item @code{database} (default: @code{"/var/lib/cuirass/cuirass.db"})
- Location of sqlite database which contains the build results and previously
- added specifications.
- @item @code{ttl} (default: @code{(* 30 24 3600)})
- Specifies the time-to-live (TTL) in seconds of garbage collector roots that
- are registered for build results. This means that build results are protected
- from garbage collection for at least @var{ttl} seconds.
- @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,
- where a specification is an association list
- (@pxref{Associations Lists,,, guile, GNU Guile Reference Manual}) whose
- keys are keywords (@code{#:keyword-example}) as shown in the example
- above.
- @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.
- @item @code{cuirass} (default: @code{cuirass})
- The Cuirass package to use.
- @end table
- @end deftp
- @cindex simple cuirass
- @subsubheading Simple Cuirass
- The Cuirass service configuration described above can be a little
- intimidating. In particular, getting the right @code{specifications}
- can prove difficult. The @code{simple-cuirass-configuration->specs}
- procedure offers a way to generate those @code{specifications} and thus
- setup a continuous integration server more readily.
- @deffn {Scheme Procedure} simple-cuirass-configuration->specs @var{configuration}
- This procedure takes a @code{simple-cuirass-configuration} record as
- argument and returns the corresponding Cuirass specifications gexp.
- @end deffn
- @deftp {Data Type} simple-cuirass-configuration
- Data type representing the configuration of a simple Cuirass instance.
- @table @asis
- @item @code{build} (default: @code{all})
- The packages to be built by Cuirass. It defaults to @code{all}, which
- means that all the discovered packages in the subsequent @code{channels}
- field are to be selected.
- It is also possible to set this field to a list of @code{build-manifest}
- records, so that only the packages that are part of the declared
- manifests are built. This record is described below.
- @deftp {Data Type} build-manifest
- @table @asis
- @item @code{channel-name}
- The name of the channel where the manifest is located.
- @item @code{manifest}
- The manifest path inside the channel.
- @end table
- @end deftp
- @item @code{channels} (default: @code{%default-channels})
- The channels to be fetched by Cuirass (@pxref{Channels}).
- @item @code{non-package-channels} (default: @code{'()})
- List the channel names that must not be searched for packages. That is
- often the case for the channel containing the manifest.
- @item @code{systems} (default: @code{(list (%current-system))})
- Build every discovered package for each system in this list. By default
- only the current system is selected.
- @end table
- @end deftp
- Here is an example of how to setup a Cuirass instance that builds all
- the packages declared by Guix and a user repository. The package list
- is re-evaluated each time a commit is pushed in one of the declared
- channels.
- @lisp
- (service cuirass-service-type
- (cuirass-configuration
- (specifications
- (simple-cuirass-configuration->specs
- (simple-cuirass-configuration
- (build 'all)
- (channels (cons (channel
- (name 'my-guix)
- (url "https://my-git-repo/guix.git"))
- %default-channels)))))))
- @end lisp
- In the same spirit, this builds all the packages that are part of the
- @code{guix} or @code{my-guix} channels and declared in the manifest
- located in the @code{conf} channel.
- @lisp
- (service cuirass-service-type
- (cuirass-configuration
- (specifications
- (simple-cuirass-configuration->specs
- (simple-cuirass-configuration
- (build (list
- (build-manifest
- (channel-name 'conf)
- (manifest "guix/manifest.scm"))))
- (channels (cons* (channel
- (name 'my-guix)
- (url "https://my-git-repo/guix.git"))
- (channel
- (name 'conf)
- (url "https://my-git-repo/conf.git"))
- %default-channels))
- (non-package-channels '(conf)))))))
- @end lisp
- Finally, @code{simple-cuirass-services} takes as a second optional
- argument a @code{cuirass-configuration} record. It can be used to
- customize the configuration of the Cuirass instance.
- @lisp
- (simple-cuirass-services
- (simple-cuirass-configuration
- (build 'all)
- (channels (cons (channel
- (name 'my-guix)
- (url "https://my-git-repo/guix.git"))
- %default-channels))
- (non-package-channels '(conf)))
- (cuirass-configuration
- (inherit %default-cuirass-config)
- (host "0.0.0.0"))) ;listen on all interfaces.
- @end lisp
- @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} 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{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
- @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).
- @item @code{guix-support?} (default: @code{#t})
- When it is true, QEMU and all its dependencies are added to the build
- environment of @command{guix-daemon} (@pxref{Invoking guix-daemon,
- @option{--chroot-directory} option}). This allows the @code{binfmt_misc}
- handlers to be used within the build environment, which in turn means
- that you can transparently build programs for another architecture.
- 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"))
- (guix-support? #t)))
- @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!
- When @code{guix-support?} is set to @code{#f}, programs for other
- architectures can still be executed transparently, but invoking commands
- like @command{guix build -s armhf-linux @dots{}} will fail.
- @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 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 environment --ad-hoc 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" "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 (static-networking-service "eth0" "192.168.1.201"
- #:netmask "255.255.255.0"
- #: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 'without-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-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 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{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
- @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.
- @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.
- @end quotation
- 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})
- 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{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} (default: @code{#f})
- The password to use when connecting to the coordinator. A file to read
- the password from can also be specified, and this is more secure.
- @item @code{password-file} (default: @code{#f})
- A file containing the password to use when connecting to the
- coordinator.
- @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{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
- 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:8745"})
- 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
- @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 it's 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 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
- @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{'()})
- An association list specifies kernel parameters and their values.
- @end table
- @end deftp
- @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{package} (default: @code{docker})
- The Docker daemon package to use.
- @item @code{package} (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.
- @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 (string-append (assoc-ref %build-inputs "r-min")
- "/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 G-expressions denoting the names of
- programs to be setuid-root (@pxref{Using the Configuration System}).
- For instance, the @command{passwd} program, which is part of the Shadow
- package, can be designated by this G-expression (@pxref{G-Expressions}):
- @example
- #~(string-append #$shadow "/bin/passwd")
- @end example
- 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 G-expressions 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 --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 --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 --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-3.0-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{target}
- (@pxref{Bootloader Configuration, @code{target}}), to be served by a TFTP server.
- You may want to mount your TFTP server directory onto @code{target} 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. The first symlink is
- @code{target}@file{/efi/Guix/boot/grub/grub.cfg} pointing to
- @file{../../../boot/grub/grub.cfg},
- where @code{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
- @code{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{target} directory—usually @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 at @code{target}.
- 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{target}
- This is a string denoting the target onto which to install the
- bootloader.
- The interpretation depends on the bootloader in question. For
- @code{grub-bootloader}, for example, it should be a device name 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}, it should be the mount point of the EFI file
- system, usually @file{/boot/efi}. For @code{grub-efi-netboot-bootloader},
- @code{target} should be the mount point corresponding to the TFTP root
- directory of 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 month 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 target 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 that contains the operating system declared in
- @var{file}, and return a script to run that virtual machine (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 -net user,model=virtio-net-pci
- @end example
- The VM shares its store with the host system.
- 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.
- @cindex System images, creation in various formats
- @cindex Creating system images in various formats
- @item image
- @itemx docker-image
- Return a virtual machine, disk image, or Docker image of the operating
- system declared in @var{file} that stands alone. By default,
- @command{guix system} estimates the size of the image needed to store
- the system, but you can use the @option{--image-size} option to specify
- a value. Docker images are built to contain exactly what they need, so
- the @option{--image-size} option is ignored in the case of
- @code{docker-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 @code{docker-image}, 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 current system generation: its file name, the kernel and
- bootloader used, etc., as well as provenance information when available.
- @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)
- (target "/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}.
- @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.
- @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.xz}.
- This image is a compressed image in QCOW format. You will first need to
- decompress with @command{xz -d}, and then you can pass it to an emulator such
- as 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 virtual
- machine image using @command{guix system vm-image} (@pxref{Invoking guix
- system}). The returned image is in qcow2 format, which the
- @uref{https://qemu.org/, QEMU emulator} can efficiently use.
- @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
- @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.
- @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.
- @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.
- @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
- @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
- @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 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 browseable
- 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:
- @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}.
- 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 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 intepreter 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:
|
