| 1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714171517161717171817191720172117221723172417251726172717281729173017311732173317341735173617371738173917401741174217431744174517461747174817491750175117521753175417551756175717581759176017611762176317641765176617671768176917701771177217731774177517761777177817791780178117821783178417851786178717881789179017911792179317941795179617971798179918001801180218031804180518061807180818091810181118121813181418151816181718181819182018211822182318241825182618271828182918301831183218331834183518361837183818391840184118421843184418451846184718481849185018511852185318541855185618571858185918601861186218631864186518661867186818691870187118721873187418751876187718781879188018811882188318841885188618871888188918901891189218931894189518961897189818991900190119021903190419051906190719081909191019111912191319141915191619171918191919201921192219231924192519261927192819291930193119321933193419351936193719381939194019411942194319441945194619471948194919501951195219531954195519561957195819591960196119621963196419651966196719681969197019711972197319741975197619771978197919801981198219831984198519861987198819891990199119921993199419951996199719981999200020012002200320042005200620072008200920102011201220132014201520162017201820192020202120222023202420252026202720282029203020312032203320342035203620372038203920402041204220432044204520462047204820492050205120522053205420552056205720582059206020612062206320642065206620672068206920702071207220732074207520762077207820792080208120822083208420852086208720882089209020912092209320942095209620972098209921002101210221032104210521062107210821092110211121122113211421152116211721182119212021212122212321242125212621272128212921302131213221332134213521362137213821392140214121422143214421452146214721482149215021512152215321542155215621572158215921602161216221632164216521662167216821692170217121722173217421752176217721782179218021812182218321842185218621872188218921902191219221932194219521962197219821992200220122022203220422052206220722082209221022112212221322142215221622172218221922202221222222232224222522262227222822292230223122322233223422352236223722382239224022412242224322442245224622472248224922502251225222532254225522562257225822592260226122622263226422652266226722682269227022712272227322742275227622772278227922802281228222832284228522862287228822892290229122922293229422952296229722982299230023012302230323042305230623072308230923102311231223132314231523162317231823192320232123222323232423252326232723282329233023312332233323342335233623372338233923402341234223432344234523462347234823492350235123522353235423552356235723582359236023612362236323642365236623672368236923702371237223732374237523762377237823792380238123822383238423852386238723882389239023912392239323942395239623972398239924002401240224032404240524062407240824092410241124122413241424152416241724182419242024212422242324242425242624272428242924302431243224332434243524362437243824392440244124422443244424452446244724482449245024512452245324542455245624572458245924602461246224632464246524662467246824692470247124722473247424752476247724782479248024812482248324842485248624872488248924902491249224932494249524962497249824992500250125022503250425052506250725082509251025112512251325142515251625172518251925202521252225232524252525262527252825292530253125322533253425352536253725382539254025412542254325442545254625472548254925502551255225532554255525562557255825592560256125622563256425652566256725682569257025712572257325742575257625772578257925802581258225832584258525862587258825892590259125922593259425952596259725982599260026012602260326042605260626072608260926102611261226132614261526162617261826192620262126222623262426252626262726282629263026312632263326342635263626372638263926402641264226432644264526462647264826492650265126522653265426552656265726582659266026612662266326642665266626672668266926702671267226732674267526762677267826792680268126822683268426852686268726882689269026912692269326942695269626972698269927002701270227032704270527062707270827092710271127122713271427152716271727182719272027212722272327242725272627272728272927302731273227332734273527362737273827392740274127422743274427452746274727482749275027512752275327542755275627572758275927602761276227632764276527662767276827692770277127722773277427752776277727782779278027812782278327842785278627872788278927902791279227932794279527962797279827992800280128022803280428052806280728082809281028112812281328142815281628172818281928202821282228232824282528262827282828292830283128322833283428352836283728382839284028412842284328442845284628472848284928502851285228532854285528562857285828592860286128622863286428652866286728682869287028712872287328742875287628772878287928802881288228832884288528862887288828892890289128922893289428952896289728982899290029012902290329042905290629072908290929102911291229132914291529162917291829192920292129222923292429252926292729282929293029312932293329342935293629372938293929402941294229432944294529462947294829492950295129522953295429552956295729582959296029612962296329642965296629672968296929702971297229732974297529762977297829792980298129822983298429852986298729882989299029912992299329942995299629972998299930003001300230033004300530063007300830093010301130123013301430153016301730183019302030213022302330243025302630273028302930303031303230333034303530363037303830393040304130423043304430453046304730483049305030513052305330543055305630573058305930603061306230633064306530663067306830693070307130723073307430753076307730783079308030813082308330843085308630873088308930903091309230933094309530963097309830993100310131023103310431053106310731083109311031113112311331143115311631173118311931203121312231233124312531263127312831293130313131323133313431353136313731383139314031413142314331443145314631473148314931503151315231533154315531563157315831593160316131623163316431653166316731683169317031713172317331743175317631773178317931803181318231833184318531863187318831893190319131923193319431953196319731983199320032013202320332043205320632073208320932103211321232133214321532163217321832193220322132223223322432253226322732283229323032313232323332343235323632373238323932403241324232433244324532463247324832493250325132523253325432553256325732583259326032613262326332643265326632673268326932703271327232733274327532763277327832793280328132823283328432853286328732883289329032913292329332943295329632973298329933003301330233033304330533063307330833093310331133123313331433153316331733183319332033213322332333243325332633273328332933303331333233333334333533363337333833393340334133423343334433453346334733483349335033513352335333543355335633573358335933603361336233633364336533663367336833693370337133723373337433753376337733783379338033813382338333843385338633873388338933903391339233933394339533963397339833993400340134023403340434053406340734083409341034113412341334143415341634173418341934203421342234233424342534263427342834293430343134323433343434353436343734383439344034413442344334443445344634473448344934503451345234533454345534563457345834593460346134623463346434653466346734683469347034713472347334743475347634773478347934803481348234833484348534863487348834893490349134923493349434953496349734983499350035013502350335043505350635073508350935103511351235133514351535163517351835193520352135223523352435253526352735283529353035313532353335343535353635373538353935403541354235433544354535463547354835493550355135523553355435553556355735583559356035613562356335643565356635673568356935703571357235733574357535763577357835793580358135823583358435853586358735883589359035913592359335943595359635973598359936003601360236033604360536063607360836093610361136123613361436153616361736183619362036213622362336243625362636273628362936303631363236333634363536363637363836393640364136423643364436453646364736483649365036513652365336543655365636573658365936603661366236633664366536663667366836693670367136723673367436753676367736783679368036813682368336843685368636873688368936903691369236933694369536963697369836993700370137023703370437053706370737083709371037113712371337143715371637173718371937203721372237233724372537263727372837293730373137323733373437353736373737383739374037413742374337443745374637473748374937503751375237533754375537563757375837593760376137623763376437653766376737683769377037713772377337743775377637773778377937803781378237833784378537863787378837893790379137923793379437953796379737983799380038013802380338043805380638073808380938103811381238133814381538163817381838193820382138223823382438253826382738283829383038313832383338343835383638373838383938403841384238433844384538463847384838493850385138523853385438553856385738583859386038613862386338643865386638673868386938703871387238733874387538763877387838793880388138823883388438853886388738883889389038913892389338943895389638973898389939003901390239033904390539063907390839093910391139123913391439153916391739183919392039213922392339243925392639273928392939303931393239333934393539363937393839393940394139423943394439453946394739483949395039513952395339543955395639573958395939603961396239633964396539663967396839693970397139723973397439753976397739783979398039813982398339843985398639873988398939903991399239933994399539963997399839994000400140024003400440054006400740084009401040114012401340144015401640174018401940204021402240234024402540264027402840294030403140324033403440354036403740384039404040414042404340444045404640474048404940504051405240534054405540564057405840594060406140624063406440654066406740684069407040714072407340744075407640774078407940804081408240834084408540864087408840894090409140924093409440954096409740984099410041014102410341044105410641074108410941104111411241134114411541164117411841194120412141224123412441254126412741284129413041314132413341344135413641374138413941404141414241434144414541464147414841494150415141524153415441554156415741584159416041614162416341644165416641674168416941704171417241734174417541764177417841794180418141824183418441854186418741884189419041914192419341944195419641974198419942004201420242034204420542064207420842094210421142124213421442154216421742184219422042214222422342244225422642274228422942304231423242334234423542364237423842394240424142424243424442454246424742484249425042514252425342544255425642574258425942604261426242634264426542664267426842694270427142724273427442754276427742784279428042814282428342844285428642874288428942904291429242934294429542964297429842994300430143024303430443054306430743084309431043114312431343144315431643174318431943204321432243234324432543264327432843294330433143324333433443354336433743384339434043414342434343444345434643474348434943504351435243534354435543564357435843594360436143624363436443654366436743684369437043714372437343744375437643774378437943804381438243834384438543864387438843894390439143924393439443954396439743984399440044014402440344044405440644074408440944104411441244134414441544164417441844194420442144224423442444254426442744284429443044314432443344344435443644374438443944404441444244434444444544464447444844494450445144524453445444554456445744584459446044614462446344644465446644674468446944704471447244734474447544764477447844794480448144824483448444854486448744884489449044914492449344944495449644974498449945004501450245034504450545064507450845094510451145124513451445154516451745184519452045214522452345244525452645274528452945304531453245334534453545364537453845394540454145424543454445454546454745484549455045514552455345544555455645574558455945604561456245634564456545664567456845694570457145724573457445754576457745784579458045814582458345844585458645874588458945904591459245934594459545964597459845994600460146024603460446054606460746084609461046114612461346144615461646174618461946204621462246234624462546264627462846294630463146324633463446354636463746384639464046414642464346444645464646474648464946504651465246534654465546564657465846594660466146624663466446654666466746684669467046714672467346744675467646774678467946804681468246834684468546864687468846894690469146924693469446954696469746984699470047014702470347044705470647074708470947104711471247134714471547164717471847194720472147224723472447254726472747284729473047314732473347344735473647374738473947404741474247434744474547464747474847494750475147524753475447554756475747584759476047614762476347644765476647674768476947704771477247734774477547764777477847794780478147824783478447854786478747884789479047914792479347944795479647974798479948004801480248034804480548064807480848094810481148124813481448154816481748184819482048214822482348244825482648274828482948304831483248334834483548364837483848394840484148424843484448454846484748484849485048514852485348544855485648574858485948604861486248634864486548664867486848694870487148724873487448754876487748784879488048814882488348844885488648874888488948904891489248934894489548964897489848994900490149024903490449054906490749084909491049114912491349144915491649174918491949204921492249234924492549264927492849294930493149324933493449354936493749384939494049414942494349444945494649474948494949504951495249534954495549564957495849594960496149624963496449654966496749684969497049714972497349744975497649774978497949804981498249834984498549864987498849894990499149924993499449954996499749984999500050015002500350045005500650075008500950105011501250135014501550165017501850195020502150225023502450255026502750285029503050315032503350345035503650375038503950405041504250435044504550465047504850495050505150525053505450555056505750585059506050615062506350645065506650675068506950705071507250735074507550765077507850795080508150825083508450855086508750885089509050915092509350945095509650975098509951005101510251035104510551065107510851095110511151125113511451155116511751185119512051215122512351245125512651275128512951305131513251335134513551365137513851395140514151425143514451455146514751485149515051515152515351545155515651575158515951605161516251635164516551665167516851695170517151725173517451755176517751785179518051815182518351845185518651875188518951905191519251935194519551965197519851995200520152025203520452055206520752085209521052115212521352145215521652175218521952205221522252235224522552265227522852295230523152325233523452355236523752385239524052415242524352445245524652475248524952505251525252535254525552565257525852595260526152625263526452655266526752685269527052715272527352745275527652775278527952805281528252835284528552865287528852895290529152925293529452955296529752985299530053015302530353045305530653075308530953105311531253135314531553165317531853195320532153225323532453255326532753285329533053315332533353345335533653375338533953405341534253435344534553465347534853495350535153525353535453555356535753585359536053615362536353645365536653675368536953705371537253735374537553765377537853795380538153825383538453855386538753885389539053915392539353945395539653975398539954005401540254035404540554065407540854095410541154125413541454155416541754185419542054215422542354245425542654275428542954305431543254335434543554365437543854395440544154425443544454455446544754485449545054515452545354545455545654575458545954605461546254635464546554665467546854695470547154725473547454755476547754785479548054815482548354845485548654875488548954905491549254935494549554965497549854995500550155025503550455055506550755085509551055115512551355145515551655175518551955205521552255235524552555265527552855295530553155325533553455355536553755385539554055415542554355445545554655475548554955505551555255535554555555565557555855595560556155625563556455655566556755685569557055715572557355745575557655775578557955805581558255835584558555865587558855895590559155925593559455955596559755985599560056015602560356045605560656075608560956105611561256135614561556165617561856195620562156225623562456255626562756285629563056315632563356345635563656375638563956405641564256435644564556465647564856495650565156525653565456555656565756585659566056615662566356645665566656675668566956705671567256735674567556765677567856795680568156825683568456855686568756885689569056915692569356945695569656975698569957005701570257035704570557065707570857095710571157125713571457155716571757185719572057215722572357245725572657275728572957305731573257335734573557365737573857395740574157425743574457455746574757485749575057515752575357545755575657575758575957605761576257635764576557665767576857695770577157725773577457755776577757785779578057815782578357845785578657875788578957905791579257935794579557965797579857995800580158025803580458055806580758085809581058115812581358145815581658175818581958205821582258235824582558265827582858295830583158325833583458355836583758385839584058415842584358445845584658475848584958505851585258535854585558565857585858595860586158625863586458655866586758685869587058715872587358745875587658775878587958805881588258835884588558865887588858895890589158925893589458955896589758985899590059015902590359045905590659075908590959105911591259135914591559165917591859195920592159225923592459255926592759285929593059315932593359345935593659375938593959405941594259435944594559465947594859495950595159525953595459555956595759585959596059615962596359645965596659675968596959705971597259735974597559765977597859795980598159825983598459855986598759885989599059915992599359945995599659975998599960006001600260036004600560066007600860096010601160126013601460156016601760186019602060216022602360246025602660276028602960306031603260336034603560366037603860396040604160426043604460456046604760486049605060516052605360546055605660576058605960606061606260636064606560666067606860696070607160726073607460756076607760786079608060816082608360846085608660876088608960906091609260936094609560966097609860996100610161026103610461056106610761086109611061116112611361146115611661176118611961206121612261236124612561266127612861296130613161326133613461356136613761386139614061416142614361446145614661476148614961506151615261536154615561566157615861596160616161626163616461656166616761686169617061716172617361746175617661776178617961806181618261836184618561866187618861896190619161926193619461956196619761986199620062016202620362046205620662076208620962106211621262136214621562166217621862196220622162226223622462256226622762286229623062316232623362346235623662376238623962406241624262436244624562466247624862496250625162526253625462556256625762586259626062616262626362646265626662676268626962706271627262736274627562766277627862796280628162826283628462856286628762886289629062916292629362946295629662976298629963006301630263036304630563066307630863096310631163126313631463156316631763186319632063216322632363246325632663276328632963306331633263336334633563366337633863396340634163426343634463456346634763486349635063516352635363546355635663576358635963606361636263636364636563666367636863696370637163726373637463756376637763786379638063816382638363846385638663876388638963906391639263936394639563966397639863996400640164026403640464056406640764086409641064116412641364146415641664176418641964206421642264236424642564266427642864296430643164326433643464356436643764386439644064416442644364446445644664476448644964506451645264536454645564566457645864596460646164626463646464656466646764686469647064716472647364746475647664776478647964806481648264836484648564866487648864896490649164926493649464956496649764986499650065016502650365046505650665076508650965106511651265136514651565166517651865196520652165226523652465256526652765286529653065316532653365346535653665376538653965406541654265436544654565466547654865496550655165526553655465556556655765586559656065616562656365646565656665676568656965706571657265736574657565766577657865796580658165826583658465856586658765886589659065916592659365946595659665976598659966006601660266036604660566066607660866096610661166126613661466156616661766186619662066216622662366246625662666276628662966306631663266336634663566366637663866396640664166426643664466456646664766486649665066516652665366546655665666576658665966606661666266636664666566666667666866696670667166726673667466756676667766786679668066816682668366846685668666876688668966906691669266936694669566966697669866996700670167026703670467056706670767086709671067116712671367146715671667176718671967206721672267236724672567266727672867296730673167326733673467356736673767386739674067416742674367446745674667476748674967506751675267536754675567566757675867596760676167626763676467656766676767686769677067716772677367746775677667776778677967806781678267836784678567866787678867896790679167926793679467956796679767986799680068016802680368046805680668076808680968106811681268136814681568166817681868196820682168226823682468256826682768286829683068316832683368346835683668376838683968406841684268436844684568466847684868496850685168526853685468556856685768586859686068616862686368646865686668676868686968706871687268736874687568766877687868796880688168826883688468856886688768886889689068916892689368946895689668976898689969006901690269036904690569066907690869096910691169126913691469156916691769186919692069216922692369246925692669276928692969306931693269336934693569366937693869396940694169426943694469456946694769486949695069516952695369546955695669576958695969606961696269636964696569666967696869696970697169726973697469756976697769786979698069816982698369846985698669876988698969906991699269936994699569966997699869997000700170027003700470057006700770087009701070117012701370147015701670177018701970207021702270237024702570267027702870297030703170327033703470357036703770387039704070417042704370447045704670477048704970507051705270537054705570567057705870597060706170627063706470657066706770687069707070717072707370747075707670777078707970807081708270837084708570867087708870897090709170927093709470957096709770987099710071017102710371047105710671077108710971107111711271137114711571167117711871197120712171227123712471257126712771287129713071317132713371347135713671377138713971407141714271437144714571467147714871497150715171527153715471557156715771587159716071617162716371647165716671677168716971707171717271737174717571767177717871797180718171827183718471857186718771887189719071917192719371947195719671977198719972007201720272037204720572067207720872097210721172127213721472157216721772187219722072217222722372247225722672277228722972307231723272337234723572367237723872397240724172427243724472457246724772487249725072517252725372547255725672577258725972607261726272637264726572667267726872697270727172727273727472757276727772787279728072817282728372847285728672877288728972907291729272937294729572967297729872997300730173027303730473057306730773087309731073117312731373147315731673177318731973207321732273237324732573267327732873297330733173327333733473357336733773387339734073417342734373447345734673477348734973507351735273537354735573567357735873597360736173627363736473657366736773687369737073717372737373747375737673777378737973807381738273837384738573867387738873897390739173927393739473957396739773987399740074017402740374047405740674077408740974107411741274137414741574167417741874197420742174227423742474257426742774287429743074317432743374347435743674377438743974407441744274437444744574467447744874497450745174527453745474557456745774587459746074617462746374647465746674677468746974707471747274737474747574767477747874797480748174827483748474857486748774887489749074917492749374947495749674977498749975007501750275037504750575067507750875097510751175127513751475157516751775187519752075217522752375247525752675277528752975307531753275337534753575367537753875397540754175427543754475457546754775487549755075517552755375547555755675577558755975607561756275637564756575667567756875697570757175727573757475757576757775787579758075817582758375847585758675877588758975907591759275937594759575967597759875997600760176027603760476057606760776087609761076117612761376147615761676177618761976207621762276237624762576267627762876297630763176327633763476357636763776387639764076417642764376447645764676477648764976507651765276537654765576567657765876597660766176627663766476657666766776687669767076717672767376747675767676777678767976807681768276837684768576867687768876897690769176927693769476957696769776987699770077017702770377047705770677077708770977107711771277137714771577167717771877197720772177227723772477257726772777287729773077317732773377347735773677377738773977407741774277437744774577467747774877497750775177527753775477557756775777587759776077617762776377647765776677677768776977707771777277737774777577767777777877797780778177827783778477857786778777887789779077917792779377947795779677977798779978007801780278037804780578067807780878097810781178127813781478157816781778187819782078217822782378247825782678277828782978307831783278337834783578367837783878397840784178427843784478457846784778487849785078517852785378547855785678577858785978607861786278637864786578667867786878697870787178727873787478757876787778787879788078817882788378847885788678877888788978907891789278937894789578967897789878997900790179027903790479057906790779087909791079117912791379147915791679177918791979207921792279237924792579267927792879297930793179327933793479357936793779387939794079417942794379447945794679477948794979507951795279537954795579567957795879597960796179627963796479657966796779687969797079717972797379747975797679777978797979807981798279837984798579867987798879897990799179927993799479957996799779987999800080018002800380048005800680078008800980108011801280138014801580168017801880198020802180228023802480258026802780288029803080318032803380348035803680378038803980408041804280438044804580468047804880498050805180528053805480558056805780588059806080618062806380648065806680678068806980708071807280738074807580768077807880798080808180828083808480858086808780888089809080918092809380948095809680978098809981008101810281038104810581068107810881098110811181128113811481158116811781188119812081218122812381248125812681278128812981308131813281338134813581368137813881398140814181428143814481458146814781488149815081518152815381548155815681578158815981608161816281638164816581668167816881698170817181728173817481758176817781788179818081818182818381848185818681878188818981908191819281938194819581968197819881998200820182028203820482058206820782088209821082118212821382148215821682178218821982208221822282238224822582268227822882298230823182328233823482358236823782388239824082418242824382448245824682478248824982508251825282538254825582568257825882598260826182628263826482658266826782688269827082718272827382748275827682778278827982808281828282838284828582868287828882898290829182928293829482958296829782988299830083018302830383048305830683078308830983108311831283138314831583168317831883198320832183228323832483258326832783288329833083318332833383348335833683378338833983408341834283438344834583468347834883498350835183528353835483558356835783588359836083618362836383648365836683678368836983708371837283738374837583768377837883798380838183828383838483858386838783888389839083918392839383948395839683978398839984008401840284038404840584068407840884098410841184128413841484158416841784188419842084218422842384248425842684278428842984308431843284338434843584368437843884398440844184428443844484458446844784488449845084518452845384548455845684578458845984608461846284638464846584668467846884698470847184728473847484758476847784788479848084818482848384848485848684878488848984908491849284938494849584968497849884998500850185028503850485058506850785088509851085118512851385148515851685178518851985208521852285238524852585268527852885298530853185328533853485358536853785388539854085418542854385448545854685478548854985508551855285538554855585568557855885598560856185628563856485658566856785688569857085718572857385748575857685778578857985808581858285838584858585868587858885898590859185928593859485958596859785988599860086018602860386048605860686078608860986108611861286138614861586168617861886198620862186228623862486258626862786288629863086318632863386348635863686378638863986408641864286438644864586468647864886498650865186528653865486558656865786588659866086618662866386648665866686678668866986708671867286738674867586768677867886798680868186828683868486858686868786888689869086918692869386948695869686978698869987008701870287038704870587068707870887098710871187128713871487158716871787188719872087218722872387248725872687278728872987308731873287338734873587368737873887398740874187428743874487458746874787488749875087518752875387548755875687578758875987608761876287638764876587668767876887698770877187728773877487758776877787788779878087818782878387848785878687878788878987908791879287938794879587968797879887998800880188028803880488058806880788088809881088118812881388148815881688178818881988208821882288238824882588268827882888298830883188328833883488358836883788388839884088418842884388448845884688478848884988508851885288538854885588568857885888598860886188628863886488658866886788688869887088718872887388748875887688778878887988808881888288838884888588868887888888898890889188928893889488958896889788988899890089018902890389048905890689078908890989108911891289138914891589168917891889198920892189228923892489258926892789288929893089318932893389348935893689378938893989408941894289438944894589468947894889498950895189528953895489558956895789588959896089618962896389648965896689678968896989708971897289738974897589768977897889798980898189828983898489858986898789888989899089918992899389948995899689978998899990009001900290039004900590069007900890099010901190129013901490159016901790189019902090219022902390249025902690279028902990309031903290339034903590369037903890399040904190429043904490459046904790489049905090519052905390549055905690579058905990609061906290639064906590669067906890699070907190729073907490759076907790789079908090819082908390849085908690879088908990909091909290939094909590969097909890999100910191029103910491059106910791089109911091119112911391149115911691179118911991209121912291239124912591269127912891299130913191329133913491359136913791389139914091419142914391449145914691479148914991509151915291539154915591569157915891599160916191629163916491659166916791689169917091719172917391749175917691779178917991809181918291839184918591869187918891899190919191929193919491959196919791989199920092019202920392049205920692079208920992109211921292139214921592169217921892199220922192229223922492259226922792289229923092319232923392349235923692379238923992409241924292439244924592469247924892499250925192529253925492559256925792589259926092619262926392649265926692679268926992709271927292739274927592769277927892799280928192829283928492859286928792889289929092919292929392949295929692979298929993009301930293039304930593069307930893099310931193129313931493159316931793189319932093219322932393249325932693279328932993309331933293339334933593369337933893399340934193429343934493459346934793489349935093519352935393549355935693579358935993609361936293639364936593669367936893699370937193729373937493759376937793789379938093819382938393849385938693879388938993909391939293939394939593969397939893999400940194029403940494059406940794089409941094119412941394149415941694179418941994209421942294239424942594269427942894299430943194329433943494359436943794389439944094419442944394449445944694479448944994509451945294539454945594569457945894599460946194629463946494659466946794689469947094719472947394749475947694779478947994809481948294839484948594869487948894899490949194929493949494959496949794989499950095019502950395049505950695079508950995109511951295139514951595169517951895199520952195229523952495259526952795289529953095319532953395349535953695379538953995409541954295439544954595469547954895499550955195529553955495559556955795589559956095619562956395649565956695679568956995709571957295739574957595769577957895799580958195829583958495859586958795889589959095919592959395949595959695979598959996009601960296039604960596069607960896099610961196129613961496159616961796189619962096219622962396249625962696279628962996309631963296339634963596369637963896399640964196429643964496459646964796489649965096519652965396549655965696579658965996609661966296639664966596669667966896699670967196729673967496759676967796789679968096819682968396849685968696879688968996909691969296939694969596969697969896999700970197029703970497059706970797089709971097119712971397149715971697179718971997209721972297239724972597269727972897299730973197329733973497359736973797389739974097419742974397449745974697479748974997509751975297539754975597569757975897599760976197629763976497659766976797689769977097719772977397749775977697779778977997809781978297839784978597869787978897899790979197929793979497959796979797989799980098019802980398049805980698079808980998109811981298139814981598169817981898199820982198229823982498259826982798289829983098319832983398349835983698379838983998409841984298439844984598469847984898499850985198529853985498559856985798589859986098619862986398649865986698679868986998709871987298739874987598769877987898799880988198829883988498859886988798889889989098919892989398949895989698979898989999009901990299039904990599069907990899099910991199129913991499159916991799189919992099219922992399249925992699279928992999309931993299339934993599369937993899399940994199429943994499459946994799489949995099519952995399549955995699579958995999609961996299639964996599669967996899699970997199729973997499759976997799789979998099819982998399849985998699879988998999909991999299939994999599969997999899991000010001100021000310004100051000610007100081000910010100111001210013100141001510016100171001810019100201002110022100231002410025100261002710028100291003010031100321003310034100351003610037100381003910040100411004210043100441004510046100471004810049100501005110052100531005410055100561005710058100591006010061100621006310064100651006610067100681006910070100711007210073100741007510076100771007810079100801008110082100831008410085100861008710088100891009010091100921009310094100951009610097100981009910100101011010210103101041010510106101071010810109101101011110112101131011410115101161011710118101191012010121101221012310124101251012610127101281012910130101311013210133101341013510136101371013810139101401014110142101431014410145101461014710148101491015010151101521015310154101551015610157101581015910160101611016210163101641016510166101671016810169101701017110172101731017410175101761017710178101791018010181101821018310184101851018610187101881018910190101911019210193101941019510196101971019810199102001020110202102031020410205102061020710208102091021010211102121021310214102151021610217102181021910220102211022210223102241022510226102271022810229102301023110232102331023410235102361023710238102391024010241102421024310244102451024610247102481024910250102511025210253102541025510256102571025810259102601026110262102631026410265102661026710268102691027010271102721027310274102751027610277102781027910280102811028210283102841028510286102871028810289102901029110292102931029410295102961029710298102991030010301103021030310304103051030610307103081030910310103111031210313103141031510316103171031810319103201032110322103231032410325103261032710328103291033010331103321033310334103351033610337103381033910340103411034210343103441034510346103471034810349103501035110352103531035410355103561035710358103591036010361103621036310364103651036610367103681036910370103711037210373103741037510376103771037810379103801038110382103831038410385103861038710388103891039010391103921039310394103951039610397103981039910400104011040210403104041040510406104071040810409104101041110412104131041410415104161041710418104191042010421104221042310424104251042610427104281042910430104311043210433104341043510436104371043810439104401044110442104431044410445104461044710448104491045010451104521045310454104551045610457104581045910460104611046210463104641046510466104671046810469104701047110472104731047410475104761047710478104791048010481104821048310484104851048610487104881048910490104911049210493104941049510496104971049810499105001050110502105031050410505105061050710508105091051010511105121051310514105151051610517105181051910520105211052210523105241052510526105271052810529105301053110532105331053410535105361053710538105391054010541105421054310544105451054610547105481054910550105511055210553105541055510556105571055810559105601056110562105631056410565105661056710568105691057010571105721057310574105751057610577105781057910580105811058210583105841058510586105871058810589105901059110592105931059410595105961059710598105991060010601106021060310604106051060610607106081060910610106111061210613106141061510616106171061810619106201062110622106231062410625106261062710628106291063010631106321063310634106351063610637106381063910640106411064210643106441064510646106471064810649106501065110652106531065410655106561065710658106591066010661106621066310664106651066610667106681066910670106711067210673106741067510676106771067810679106801068110682106831068410685106861068710688106891069010691106921069310694106951069610697106981069910700107011070210703107041070510706107071070810709107101071110712107131071410715107161071710718107191072010721107221072310724107251072610727107281072910730107311073210733107341073510736107371073810739107401074110742107431074410745107461074710748107491075010751107521075310754107551075610757107581075910760107611076210763107641076510766107671076810769107701077110772107731077410775107761077710778107791078010781107821078310784107851078610787107881078910790107911079210793107941079510796107971079810799108001080110802108031080410805108061080710808108091081010811108121081310814108151081610817108181081910820108211082210823108241082510826108271082810829108301083110832108331083410835108361083710838108391084010841108421084310844108451084610847108481084910850108511085210853108541085510856108571085810859108601086110862108631086410865108661086710868108691087010871108721087310874108751087610877108781087910880108811088210883108841088510886108871088810889108901089110892108931089410895108961089710898108991090010901109021090310904109051090610907109081090910910109111091210913109141091510916109171091810919109201092110922109231092410925109261092710928109291093010931109321093310934109351093610937109381093910940109411094210943109441094510946109471094810949109501095110952109531095410955109561095710958109591096010961109621096310964109651096610967109681096910970109711097210973109741097510976109771097810979109801098110982109831098410985109861098710988109891099010991109921099310994109951099610997109981099911000110011100211003110041100511006110071100811009110101101111012110131101411015110161101711018110191102011021110221102311024110251102611027110281102911030110311103211033110341103511036110371103811039110401104111042110431104411045110461104711048110491105011051110521105311054110551105611057110581105911060110611106211063110641106511066110671106811069110701107111072110731107411075110761107711078110791108011081110821108311084110851108611087110881108911090110911109211093110941109511096110971109811099111001110111102111031110411105111061110711108111091111011111111121111311114111151111611117111181111911120111211112211123111241112511126111271112811129111301113111132111331113411135111361113711138111391114011141111421114311144111451114611147111481114911150111511115211153111541115511156111571115811159111601116111162111631116411165111661116711168111691117011171111721117311174111751117611177111781117911180111811118211183111841118511186111871118811189111901119111192111931119411195111961119711198111991120011201112021120311204112051120611207112081120911210112111121211213112141121511216112171121811219112201122111222112231122411225112261122711228112291123011231112321123311234112351123611237112381123911240112411124211243112441124511246112471124811249112501125111252112531125411255112561125711258112591126011261112621126311264112651126611267112681126911270112711127211273112741127511276112771127811279112801128111282112831128411285112861128711288112891129011291112921129311294112951129611297112981129911300113011130211303113041130511306113071130811309113101131111312113131131411315113161131711318113191132011321113221132311324113251132611327113281132911330113311133211333113341133511336113371133811339113401134111342113431134411345113461134711348113491135011351113521135311354113551135611357113581135911360113611136211363113641136511366113671136811369113701137111372113731137411375113761137711378113791138011381113821138311384113851138611387113881138911390113911139211393113941139511396113971139811399114001140111402114031140411405114061140711408114091141011411114121141311414114151141611417114181141911420114211142211423114241142511426114271142811429114301143111432114331143411435114361143711438114391144011441114421144311444114451144611447114481144911450114511145211453114541145511456114571145811459114601146111462114631146411465114661146711468114691147011471114721147311474114751147611477114781147911480114811148211483114841148511486114871148811489114901149111492114931149411495114961149711498114991150011501115021150311504115051150611507115081150911510115111151211513115141151511516115171151811519115201152111522115231152411525115261152711528115291153011531115321153311534115351153611537115381153911540115411154211543115441154511546115471154811549115501155111552115531155411555115561155711558115591156011561115621156311564115651156611567115681156911570115711157211573115741157511576115771157811579115801158111582115831158411585115861158711588115891159011591115921159311594115951159611597115981159911600116011160211603116041160511606116071160811609116101161111612116131161411615116161161711618116191162011621116221162311624116251162611627116281162911630116311163211633116341163511636116371163811639116401164111642116431164411645116461164711648116491165011651116521165311654116551165611657116581165911660116611166211663116641166511666116671166811669116701167111672116731167411675116761167711678116791168011681116821168311684116851168611687116881168911690116911169211693116941169511696116971169811699117001170111702117031170411705117061170711708117091171011711117121171311714117151171611717117181171911720117211172211723117241172511726117271172811729117301173111732117331173411735117361173711738117391174011741117421174311744117451174611747117481174911750117511175211753117541175511756117571175811759117601176111762117631176411765117661176711768117691177011771117721177311774117751177611777117781177911780117811178211783117841178511786117871178811789117901179111792117931179411795117961179711798117991180011801118021180311804118051180611807118081180911810118111181211813118141181511816118171181811819118201182111822118231182411825118261182711828118291183011831118321183311834118351183611837118381183911840118411184211843118441184511846118471184811849118501185111852118531185411855118561185711858118591186011861118621186311864118651186611867118681186911870118711187211873118741187511876118771187811879118801188111882118831188411885118861188711888118891189011891118921189311894118951189611897118981189911900119011190211903119041190511906119071190811909119101191111912119131191411915119161191711918119191192011921119221192311924119251192611927119281192911930119311193211933119341193511936119371193811939119401194111942119431194411945119461194711948119491195011951119521195311954119551195611957119581195911960119611196211963119641196511966119671196811969119701197111972119731197411975119761197711978119791198011981119821198311984119851198611987119881198911990119911199211993119941199511996119971199811999120001200112002120031200412005120061200712008120091201012011120121201312014120151201612017120181201912020120211202212023120241202512026120271202812029120301203112032120331203412035120361203712038120391204012041120421204312044120451204612047120481204912050120511205212053120541205512056120571205812059120601206112062120631206412065120661206712068120691207012071120721207312074120751207612077120781207912080120811208212083120841208512086120871208812089120901209112092120931209412095120961209712098120991210012101121021210312104121051210612107121081210912110121111211212113121141211512116121171211812119121201212112122121231212412125121261212712128121291213012131121321213312134121351213612137121381213912140121411214212143121441214512146121471214812149121501215112152121531215412155121561215712158121591216012161121621216312164121651216612167121681216912170121711217212173121741217512176121771217812179121801218112182121831218412185121861218712188121891219012191121921219312194121951219612197121981219912200122011220212203122041220512206122071220812209122101221112212122131221412215122161221712218122191222012221122221222312224122251222612227122281222912230122311223212233122341223512236122371223812239122401224112242122431224412245122461224712248122491225012251122521225312254122551225612257122581225912260122611226212263122641226512266122671226812269122701227112272122731227412275122761227712278122791228012281122821228312284122851228612287122881228912290122911229212293122941229512296122971229812299123001230112302123031230412305123061230712308123091231012311123121231312314123151231612317123181231912320123211232212323123241232512326123271232812329123301233112332123331233412335123361233712338123391234012341123421234312344123451234612347123481234912350123511235212353123541235512356123571235812359123601236112362123631236412365123661236712368123691237012371123721237312374123751237612377123781237912380123811238212383123841238512386123871238812389123901239112392123931239412395123961239712398123991240012401124021240312404124051240612407124081240912410124111241212413124141241512416124171241812419124201242112422124231242412425124261242712428124291243012431124321243312434124351243612437124381243912440124411244212443124441244512446124471244812449124501245112452124531245412455124561245712458124591246012461124621246312464124651246612467124681246912470124711247212473124741247512476124771247812479124801248112482124831248412485124861248712488124891249012491124921249312494124951249612497124981249912500125011250212503125041250512506125071250812509125101251112512125131251412515125161251712518125191252012521125221252312524125251252612527125281252912530125311253212533125341253512536125371253812539125401254112542125431254412545125461254712548125491255012551125521255312554125551255612557125581255912560125611256212563125641256512566125671256812569125701257112572125731257412575125761257712578125791258012581125821258312584125851258612587125881258912590125911259212593125941259512596125971259812599126001260112602126031260412605126061260712608126091261012611126121261312614126151261612617126181261912620126211262212623126241262512626126271262812629126301263112632126331263412635126361263712638126391264012641126421264312644126451264612647126481264912650126511265212653126541265512656126571265812659126601266112662126631266412665126661266712668126691267012671126721267312674126751267612677126781267912680126811268212683126841268512686126871268812689126901269112692126931269412695126961269712698126991270012701127021270312704127051270612707127081270912710127111271212713127141271512716127171271812719127201272112722127231272412725127261272712728127291273012731127321273312734127351273612737127381273912740127411274212743127441274512746127471274812749127501275112752127531275412755127561275712758127591276012761127621276312764127651276612767127681276912770127711277212773127741277512776127771277812779127801278112782127831278412785127861278712788127891279012791127921279312794127951279612797127981279912800128011280212803128041280512806128071280812809128101281112812128131281412815128161281712818128191282012821128221282312824128251282612827128281282912830128311283212833128341283512836128371283812839128401284112842128431284412845128461284712848128491285012851128521285312854128551285612857128581285912860128611286212863128641286512866128671286812869128701287112872128731287412875128761287712878128791288012881128821288312884128851288612887128881288912890128911289212893128941289512896128971289812899129001290112902129031290412905129061290712908129091291012911129121291312914129151291612917129181291912920129211292212923129241292512926129271292812929129301293112932129331293412935129361293712938129391294012941129421294312944129451294612947129481294912950129511295212953129541295512956129571295812959129601296112962129631296412965129661296712968129691297012971129721297312974129751297612977129781297912980129811298212983129841298512986129871298812989129901299112992129931299412995129961299712998129991300013001130021300313004130051300613007130081300913010130111301213013130141301513016130171301813019130201302113022130231302413025130261302713028130291303013031130321303313034130351303613037130381303913040130411304213043130441304513046130471304813049130501305113052130531305413055130561305713058130591306013061130621306313064130651306613067130681306913070130711307213073130741307513076130771307813079130801308113082130831308413085130861308713088130891309013091130921309313094130951309613097130981309913100131011310213103131041310513106131071310813109131101311113112131131311413115131161311713118131191312013121131221312313124131251312613127131281312913130131311313213133131341313513136131371313813139131401314113142131431314413145131461314713148131491315013151131521315313154131551315613157131581315913160131611316213163131641316513166131671316813169131701317113172131731317413175131761317713178131791318013181131821318313184131851318613187131881318913190131911319213193131941319513196131971319813199132001320113202132031320413205132061320713208132091321013211132121321313214132151321613217132181321913220132211322213223132241322513226132271322813229132301323113232132331323413235132361323713238132391324013241132421324313244132451324613247132481324913250132511325213253132541325513256132571325813259132601326113262132631326413265132661326713268132691327013271132721327313274132751327613277132781327913280132811328213283132841328513286132871328813289132901329113292132931329413295132961329713298132991330013301133021330313304133051330613307133081330913310133111331213313133141331513316133171331813319133201332113322133231332413325133261332713328133291333013331133321333313334133351333613337133381333913340133411334213343133441334513346133471334813349133501335113352133531335413355133561335713358133591336013361133621336313364133651336613367133681336913370133711337213373133741337513376133771337813379133801338113382133831338413385133861338713388133891339013391133921339313394133951339613397133981339913400134011340213403134041340513406134071340813409134101341113412134131341413415134161341713418134191342013421134221342313424134251342613427134281342913430134311343213433134341343513436134371343813439134401344113442134431344413445134461344713448134491345013451134521345313454134551345613457134581345913460134611346213463134641346513466134671346813469134701347113472134731347413475134761347713478134791348013481134821348313484134851348613487134881348913490134911349213493134941349513496134971349813499135001350113502135031350413505135061350713508135091351013511135121351313514135151351613517135181351913520135211352213523135241352513526135271352813529135301353113532135331353413535135361353713538135391354013541135421354313544135451354613547135481354913550135511355213553135541355513556135571355813559135601356113562135631356413565135661356713568135691357013571135721357313574135751357613577135781357913580135811358213583135841358513586135871358813589135901359113592135931359413595135961359713598135991360013601136021360313604136051360613607136081360913610136111361213613136141361513616136171361813619136201362113622136231362413625136261362713628136291363013631136321363313634136351363613637136381363913640136411364213643136441364513646136471364813649136501365113652136531365413655136561365713658136591366013661136621366313664136651366613667136681366913670136711367213673136741367513676136771367813679136801368113682136831368413685136861368713688136891369013691136921369313694136951369613697136981369913700137011370213703137041370513706137071370813709137101371113712137131371413715137161371713718137191372013721137221372313724137251372613727137281372913730137311373213733137341373513736137371373813739137401374113742137431374413745137461374713748137491375013751137521375313754137551375613757137581375913760137611376213763137641376513766137671376813769137701377113772137731377413775137761377713778137791378013781137821378313784137851378613787137881378913790137911379213793137941379513796137971379813799138001380113802138031380413805138061380713808138091381013811138121381313814138151381613817138181381913820138211382213823138241382513826138271382813829138301383113832138331383413835138361383713838138391384013841138421384313844138451384613847138481384913850138511385213853138541385513856138571385813859138601386113862138631386413865138661386713868138691387013871138721387313874138751387613877138781387913880138811388213883138841388513886138871388813889138901389113892138931389413895138961389713898138991390013901139021390313904139051390613907139081390913910139111391213913139141391513916139171391813919139201392113922139231392413925139261392713928139291393013931139321393313934139351393613937139381393913940139411394213943139441394513946139471394813949139501395113952139531395413955139561395713958139591396013961139621396313964139651396613967139681396913970139711397213973139741397513976139771397813979139801398113982139831398413985139861398713988139891399013991139921399313994139951399613997139981399914000140011400214003140041400514006140071400814009140101401114012140131401414015140161401714018140191402014021140221402314024140251402614027140281402914030140311403214033140341403514036140371403814039140401404114042140431404414045140461404714048140491405014051140521405314054140551405614057140581405914060140611406214063140641406514066140671406814069140701407114072140731407414075140761407714078140791408014081140821408314084140851408614087140881408914090140911409214093140941409514096140971409814099141001410114102141031410414105141061410714108141091411014111141121411314114141151411614117141181411914120141211412214123141241412514126141271412814129141301413114132141331413414135141361413714138141391414014141141421414314144141451414614147141481414914150141511415214153141541415514156141571415814159141601416114162141631416414165141661416714168141691417014171141721417314174141751417614177141781417914180141811418214183141841418514186141871418814189141901419114192141931419414195141961419714198141991420014201142021420314204142051420614207142081420914210142111421214213142141421514216142171421814219142201422114222142231422414225142261422714228142291423014231142321423314234142351423614237142381423914240142411424214243142441424514246142471424814249142501425114252142531425414255142561425714258142591426014261142621426314264142651426614267142681426914270142711427214273142741427514276142771427814279142801428114282142831428414285142861428714288142891429014291142921429314294142951429614297142981429914300143011430214303143041430514306143071430814309143101431114312143131431414315143161431714318143191432014321143221432314324143251432614327143281432914330143311433214333143341433514336143371433814339143401434114342143431434414345143461434714348143491435014351143521435314354143551435614357143581435914360143611436214363143641436514366143671436814369143701437114372143731437414375143761437714378143791438014381143821438314384143851438614387143881438914390143911439214393143941439514396143971439814399144001440114402144031440414405144061440714408144091441014411144121441314414144151441614417144181441914420144211442214423144241442514426144271442814429144301443114432144331443414435144361443714438144391444014441144421444314444144451444614447144481444914450144511445214453144541445514456144571445814459144601446114462144631446414465144661446714468144691447014471144721447314474144751447614477144781447914480144811448214483144841448514486144871448814489144901449114492144931449414495144961449714498144991450014501145021450314504145051450614507145081450914510145111451214513145141451514516145171451814519145201452114522145231452414525145261452714528145291453014531145321453314534145351453614537145381453914540145411454214543145441454514546145471454814549145501455114552145531455414555145561455714558145591456014561145621456314564145651456614567145681456914570145711457214573145741457514576145771457814579145801458114582145831458414585145861458714588145891459014591145921459314594145951459614597145981459914600146011460214603146041460514606146071460814609146101461114612146131461414615146161461714618146191462014621146221462314624146251462614627146281462914630146311463214633146341463514636146371463814639146401464114642146431464414645146461464714648146491465014651146521465314654146551465614657146581465914660146611466214663146641466514666146671466814669146701467114672146731467414675146761467714678146791468014681146821468314684146851468614687146881468914690146911469214693146941469514696146971469814699147001470114702147031470414705147061470714708147091471014711147121471314714147151471614717147181471914720147211472214723147241472514726147271472814729147301473114732147331473414735147361473714738147391474014741147421474314744147451474614747147481474914750147511475214753147541475514756147571475814759147601476114762147631476414765147661476714768147691477014771147721477314774147751477614777147781477914780147811478214783147841478514786147871478814789147901479114792147931479414795147961479714798147991480014801148021480314804148051480614807148081480914810148111481214813148141481514816148171481814819148201482114822148231482414825148261482714828148291483014831148321483314834148351483614837148381483914840148411484214843148441484514846148471484814849148501485114852148531485414855148561485714858148591486014861148621486314864148651486614867148681486914870148711487214873148741487514876148771487814879148801488114882148831488414885148861488714888148891489014891148921489314894148951489614897148981489914900149011490214903149041490514906149071490814909149101491114912149131491414915149161491714918149191492014921149221492314924149251492614927149281492914930149311493214933149341493514936149371493814939149401494114942149431494414945149461494714948149491495014951149521495314954149551495614957149581495914960149611496214963149641496514966149671496814969149701497114972149731497414975149761497714978149791498014981149821498314984149851498614987149881498914990149911499214993149941499514996149971499814999150001500115002150031500415005150061500715008150091501015011150121501315014150151501615017150181501915020150211502215023150241502515026150271502815029150301503115032150331503415035150361503715038150391504015041150421504315044150451504615047150481504915050150511505215053150541505515056150571505815059150601506115062150631506415065150661506715068150691507015071150721507315074150751507615077150781507915080150811508215083150841508515086150871508815089150901509115092150931509415095150961509715098150991510015101151021510315104151051510615107151081510915110151111511215113151141511515116151171511815119151201512115122151231512415125151261512715128151291513015131151321513315134151351513615137151381513915140151411514215143151441514515146151471514815149151501515115152151531515415155151561515715158151591516015161151621516315164151651516615167151681516915170151711517215173151741517515176151771517815179151801518115182151831518415185151861518715188151891519015191151921519315194151951519615197151981519915200152011520215203152041520515206152071520815209152101521115212152131521415215152161521715218152191522015221152221522315224152251522615227152281522915230152311523215233152341523515236152371523815239152401524115242152431524415245152461524715248152491525015251152521525315254152551525615257152581525915260152611526215263152641526515266152671526815269152701527115272152731527415275152761527715278152791528015281152821528315284152851528615287152881528915290152911529215293152941529515296152971529815299153001530115302153031530415305153061530715308153091531015311153121531315314153151531615317153181531915320153211532215323153241532515326153271532815329153301533115332153331533415335153361533715338153391534015341153421534315344153451534615347153481534915350153511535215353153541535515356153571535815359153601536115362153631536415365153661536715368153691537015371153721537315374153751537615377153781537915380153811538215383153841538515386153871538815389153901539115392153931539415395153961539715398153991540015401154021540315404154051540615407154081540915410154111541215413154141541515416154171541815419154201542115422154231542415425154261542715428154291543015431154321543315434154351543615437154381543915440154411544215443154441544515446154471544815449154501545115452154531545415455154561545715458154591546015461154621546315464154651546615467154681546915470154711547215473154741547515476154771547815479154801548115482154831548415485154861548715488154891549015491154921549315494154951549615497154981549915500155011550215503155041550515506155071550815509155101551115512155131551415515155161551715518155191552015521155221552315524155251552615527155281552915530155311553215533155341553515536155371553815539155401554115542155431554415545155461554715548155491555015551155521555315554155551555615557155581555915560155611556215563155641556515566155671556815569155701557115572155731557415575155761557715578155791558015581155821558315584155851558615587155881558915590155911559215593155941559515596155971559815599156001560115602156031560415605156061560715608156091561015611156121561315614156151561615617156181561915620156211562215623156241562515626156271562815629156301563115632156331563415635156361563715638156391564015641156421564315644156451564615647156481564915650156511565215653156541565515656156571565815659156601566115662156631566415665156661566715668156691567015671156721567315674156751567615677156781567915680156811568215683156841568515686156871568815689156901569115692156931569415695156961569715698156991570015701157021570315704157051570615707157081570915710157111571215713157141571515716157171571815719157201572115722157231572415725157261572715728157291573015731157321573315734157351573615737157381573915740157411574215743157441574515746157471574815749157501575115752157531575415755157561575715758157591576015761157621576315764157651576615767157681576915770157711577215773157741577515776157771577815779157801578115782157831578415785157861578715788157891579015791157921579315794157951579615797157981579915800158011580215803158041580515806158071580815809158101581115812158131581415815158161581715818158191582015821158221582315824158251582615827158281582915830158311583215833158341583515836158371583815839158401584115842158431584415845158461584715848158491585015851158521585315854158551585615857158581585915860158611586215863158641586515866158671586815869158701587115872158731587415875158761587715878158791588015881158821588315884158851588615887158881588915890158911589215893158941589515896158971589815899159001590115902159031590415905159061590715908159091591015911159121591315914159151591615917159181591915920159211592215923159241592515926159271592815929159301593115932159331593415935159361593715938159391594015941159421594315944159451594615947159481594915950159511595215953159541595515956159571595815959159601596115962159631596415965159661596715968159691597015971159721597315974159751597615977159781597915980159811598215983159841598515986159871598815989159901599115992159931599415995159961599715998159991600016001160021600316004160051600616007160081600916010160111601216013160141601516016160171601816019160201602116022160231602416025160261602716028160291603016031160321603316034160351603616037160381603916040160411604216043160441604516046160471604816049160501605116052160531605416055160561605716058160591606016061160621606316064160651606616067160681606916070160711607216073160741607516076160771607816079160801608116082160831608416085160861608716088160891609016091160921609316094160951609616097160981609916100161011610216103161041610516106161071610816109161101611116112161131611416115161161611716118161191612016121161221612316124161251612616127161281612916130161311613216133161341613516136161371613816139161401614116142161431614416145161461614716148161491615016151161521615316154161551615616157161581615916160161611616216163161641616516166161671616816169161701617116172161731617416175161761617716178161791618016181161821618316184161851618616187161881618916190161911619216193161941619516196161971619816199162001620116202162031620416205162061620716208162091621016211162121621316214162151621616217162181621916220162211622216223162241622516226162271622816229162301623116232162331623416235162361623716238162391624016241162421624316244162451624616247162481624916250162511625216253162541625516256162571625816259162601626116262162631626416265162661626716268162691627016271162721627316274162751627616277162781627916280162811628216283162841628516286162871628816289162901629116292162931629416295162961629716298162991630016301163021630316304163051630616307163081630916310163111631216313163141631516316163171631816319163201632116322163231632416325163261632716328163291633016331163321633316334163351633616337163381633916340163411634216343163441634516346163471634816349163501635116352163531635416355163561635716358163591636016361163621636316364163651636616367163681636916370163711637216373163741637516376163771637816379163801638116382163831638416385163861638716388163891639016391163921639316394163951639616397163981639916400164011640216403164041640516406164071640816409164101641116412164131641416415164161641716418164191642016421164221642316424164251642616427164281642916430164311643216433164341643516436164371643816439164401644116442164431644416445164461644716448164491645016451164521645316454164551645616457164581645916460164611646216463164641646516466164671646816469164701647116472164731647416475164761647716478164791648016481164821648316484164851648616487164881648916490164911649216493164941649516496164971649816499165001650116502165031650416505165061650716508165091651016511165121651316514165151651616517165181651916520165211652216523165241652516526165271652816529165301653116532165331653416535165361653716538165391654016541165421654316544165451654616547165481654916550165511655216553165541655516556165571655816559165601656116562165631656416565165661656716568165691657016571165721657316574165751657616577165781657916580165811658216583165841658516586165871658816589165901659116592165931659416595165961659716598165991660016601166021660316604166051660616607166081660916610166111661216613166141661516616166171661816619166201662116622166231662416625166261662716628166291663016631166321663316634166351663616637166381663916640166411664216643166441664516646166471664816649166501665116652166531665416655166561665716658166591666016661166621666316664166651666616667166681666916670166711667216673166741667516676166771667816679166801668116682166831668416685166861668716688166891669016691166921669316694166951669616697166981669916700167011670216703167041670516706167071670816709167101671116712167131671416715167161671716718167191672016721167221672316724167251672616727167281672916730167311673216733167341673516736167371673816739167401674116742167431674416745167461674716748167491675016751167521675316754167551675616757167581675916760167611676216763167641676516766167671676816769167701677116772167731677416775167761677716778167791678016781167821678316784167851678616787167881678916790167911679216793167941679516796167971679816799168001680116802168031680416805168061680716808168091681016811168121681316814168151681616817168181681916820168211682216823168241682516826168271682816829168301683116832168331683416835168361683716838168391684016841168421684316844168451684616847168481684916850168511685216853168541685516856168571685816859168601686116862168631686416865168661686716868168691687016871168721687316874168751687616877168781687916880168811688216883168841688516886168871688816889168901689116892168931689416895168961689716898168991690016901169021690316904169051690616907169081690916910169111691216913169141691516916169171691816919169201692116922169231692416925169261692716928169291693016931169321693316934169351693616937169381693916940169411694216943169441694516946169471694816949169501695116952169531695416955169561695716958169591696016961169621696316964169651696616967169681696916970169711697216973169741697516976169771697816979169801698116982169831698416985169861698716988169891699016991169921699316994169951699616997169981699917000170011700217003170041700517006170071700817009170101701117012170131701417015170161701717018170191702017021170221702317024170251702617027170281702917030170311703217033170341703517036170371703817039170401704117042170431704417045170461704717048170491705017051170521705317054170551705617057170581705917060170611706217063170641706517066170671706817069170701707117072170731707417075170761707717078170791708017081170821708317084170851708617087170881708917090170911709217093170941709517096170971709817099171001710117102171031710417105171061710717108171091711017111171121711317114171151711617117171181711917120171211712217123171241712517126171271712817129171301713117132171331713417135171361713717138171391714017141171421714317144171451714617147171481714917150171511715217153171541715517156171571715817159171601716117162171631716417165171661716717168171691717017171171721717317174171751717617177171781717917180171811718217183171841718517186171871718817189171901719117192171931719417195171961719717198171991720017201172021720317204172051720617207172081720917210172111721217213172141721517216172171721817219172201722117222172231722417225172261722717228172291723017231172321723317234172351723617237172381723917240172411724217243172441724517246172471724817249172501725117252172531725417255172561725717258172591726017261172621726317264172651726617267172681726917270172711727217273172741727517276172771727817279172801728117282172831728417285172861728717288172891729017291172921729317294172951729617297172981729917300173011730217303173041730517306173071730817309173101731117312173131731417315173161731717318173191732017321173221732317324173251732617327173281732917330173311733217333173341733517336173371733817339173401734117342173431734417345173461734717348173491735017351173521735317354173551735617357173581735917360173611736217363173641736517366173671736817369173701737117372173731737417375173761737717378173791738017381173821738317384173851738617387173881738917390173911739217393173941739517396173971739817399174001740117402174031740417405174061740717408174091741017411174121741317414174151741617417174181741917420174211742217423174241742517426174271742817429174301743117432174331743417435174361743717438174391744017441174421744317444174451744617447174481744917450174511745217453174541745517456174571745817459174601746117462174631746417465174661746717468174691747017471174721747317474174751747617477174781747917480174811748217483174841748517486174871748817489174901749117492174931749417495174961749717498174991750017501175021750317504175051750617507175081750917510175111751217513175141751517516175171751817519175201752117522175231752417525175261752717528175291753017531175321753317534175351753617537175381753917540175411754217543175441754517546175471754817549175501755117552175531755417555175561755717558175591756017561175621756317564175651756617567175681756917570175711757217573175741757517576175771757817579175801758117582175831758417585175861758717588175891759017591175921759317594175951759617597175981759917600176011760217603176041760517606176071760817609176101761117612176131761417615176161761717618176191762017621176221762317624176251762617627176281762917630176311763217633176341763517636176371763817639176401764117642176431764417645176461764717648176491765017651176521765317654176551765617657176581765917660176611766217663176641766517666176671766817669176701767117672176731767417675176761767717678176791768017681176821768317684176851768617687176881768917690176911769217693176941769517696176971769817699177001770117702177031770417705177061770717708177091771017711177121771317714177151771617717177181771917720177211772217723177241772517726177271772817729177301773117732177331773417735177361773717738177391774017741177421774317744177451774617747177481774917750177511775217753177541775517756177571775817759177601776117762177631776417765177661776717768177691777017771177721777317774177751777617777177781777917780177811778217783177841778517786177871778817789177901779117792177931779417795177961779717798177991780017801178021780317804178051780617807178081780917810178111781217813178141781517816178171781817819178201782117822178231782417825178261782717828178291783017831178321783317834178351783617837178381783917840178411784217843178441784517846178471784817849178501785117852178531785417855178561785717858178591786017861178621786317864178651786617867178681786917870178711787217873178741787517876178771787817879178801788117882178831788417885178861788717888178891789017891178921789317894178951789617897178981789917900179011790217903179041790517906179071790817909179101791117912179131791417915179161791717918179191792017921179221792317924179251792617927179281792917930179311793217933179341793517936179371793817939179401794117942179431794417945179461794717948179491795017951179521795317954179551795617957179581795917960179611796217963179641796517966179671796817969179701797117972179731797417975179761797717978179791798017981179821798317984179851798617987179881798917990179911799217993179941799517996179971799817999180001800118002180031800418005180061800718008180091801018011180121801318014180151801618017180181801918020180211802218023180241802518026180271802818029180301803118032180331803418035180361803718038180391804018041180421804318044180451804618047180481804918050180511805218053180541805518056180571805818059180601806118062180631806418065180661806718068180691807018071180721807318074180751807618077180781807918080180811808218083180841808518086180871808818089180901809118092180931809418095180961809718098180991810018101181021810318104181051810618107181081810918110181111811218113181141811518116181171811818119181201812118122181231812418125181261812718128181291813018131181321813318134181351813618137181381813918140181411814218143181441814518146181471814818149181501815118152181531815418155181561815718158181591816018161181621816318164181651816618167181681816918170181711817218173181741817518176181771817818179181801818118182181831818418185181861818718188181891819018191181921819318194181951819618197181981819918200182011820218203182041820518206182071820818209182101821118212182131821418215182161821718218182191822018221182221822318224182251822618227182281822918230182311823218233182341823518236182371823818239182401824118242182431824418245182461824718248182491825018251182521825318254182551825618257182581825918260182611826218263182641826518266182671826818269182701827118272182731827418275182761827718278182791828018281182821828318284182851828618287182881828918290182911829218293182941829518296182971829818299183001830118302183031830418305183061830718308183091831018311183121831318314183151831618317183181831918320183211832218323183241832518326183271832818329183301833118332183331833418335183361833718338183391834018341183421834318344183451834618347183481834918350183511835218353183541835518356183571835818359183601836118362183631836418365183661836718368183691837018371183721837318374183751837618377183781837918380183811838218383183841838518386183871838818389183901839118392183931839418395183961839718398183991840018401184021840318404184051840618407184081840918410184111841218413184141841518416184171841818419184201842118422184231842418425184261842718428184291843018431184321843318434184351843618437184381843918440184411844218443184441844518446184471844818449184501845118452184531845418455184561845718458184591846018461184621846318464184651846618467184681846918470184711847218473184741847518476184771847818479184801848118482184831848418485184861848718488184891849018491184921849318494184951849618497184981849918500185011850218503185041850518506185071850818509185101851118512185131851418515185161851718518185191852018521185221852318524185251852618527185281852918530185311853218533185341853518536185371853818539185401854118542185431854418545185461854718548185491855018551185521855318554185551855618557185581855918560185611856218563185641856518566185671856818569185701857118572185731857418575185761857718578185791858018581185821858318584185851858618587185881858918590185911859218593185941859518596185971859818599186001860118602186031860418605186061860718608186091861018611186121861318614186151861618617186181861918620186211862218623186241862518626186271862818629186301863118632186331863418635186361863718638186391864018641186421864318644186451864618647186481864918650186511865218653186541865518656186571865818659186601866118662186631866418665186661866718668186691867018671186721867318674186751867618677186781867918680186811868218683186841868518686186871868818689186901869118692186931869418695186961869718698186991870018701187021870318704187051870618707187081870918710187111871218713187141871518716187171871818719187201872118722187231872418725187261872718728187291873018731187321873318734187351873618737187381873918740187411874218743187441874518746187471874818749187501875118752187531875418755187561875718758187591876018761187621876318764187651876618767187681876918770187711877218773187741877518776187771877818779187801878118782187831878418785187861878718788187891879018791187921879318794187951879618797187981879918800188011880218803188041880518806188071880818809188101881118812188131881418815188161881718818188191882018821188221882318824188251882618827188281882918830188311883218833188341883518836188371883818839188401884118842188431884418845188461884718848188491885018851188521885318854188551885618857188581885918860188611886218863188641886518866188671886818869188701887118872188731887418875188761887718878188791888018881188821888318884188851888618887188881888918890188911889218893188941889518896188971889818899189001890118902189031890418905189061890718908189091891018911189121891318914189151891618917189181891918920189211892218923189241892518926189271892818929189301893118932189331893418935189361893718938189391894018941189421894318944189451894618947189481894918950189511895218953189541895518956189571895818959189601896118962189631896418965189661896718968189691897018971189721897318974189751897618977189781897918980189811898218983189841898518986189871898818989189901899118992189931899418995189961899718998189991900019001190021900319004190051900619007190081900919010190111901219013190141901519016190171901819019190201902119022190231902419025190261902719028190291903019031190321903319034190351903619037190381903919040190411904219043190441904519046190471904819049190501905119052190531905419055190561905719058190591906019061190621906319064190651906619067190681906919070190711907219073190741907519076190771907819079190801908119082190831908419085190861908719088190891909019091190921909319094190951909619097190981909919100191011910219103191041910519106191071910819109191101911119112191131911419115191161911719118191191912019121191221912319124191251912619127191281912919130191311913219133191341913519136191371913819139191401914119142191431914419145191461914719148191491915019151191521915319154191551915619157191581915919160191611916219163191641916519166191671916819169191701917119172191731917419175191761917719178191791918019181191821918319184191851918619187191881918919190191911919219193191941919519196191971919819199192001920119202192031920419205192061920719208192091921019211192121921319214192151921619217192181921919220192211922219223192241922519226192271922819229192301923119232192331923419235192361923719238192391924019241192421924319244192451924619247192481924919250192511925219253192541925519256192571925819259192601926119262192631926419265192661926719268192691927019271192721927319274192751927619277192781927919280192811928219283192841928519286192871928819289192901929119292192931929419295192961929719298192991930019301193021930319304193051930619307193081930919310193111931219313193141931519316193171931819319193201932119322193231932419325193261932719328193291933019331193321933319334193351933619337193381933919340193411934219343193441934519346193471934819349193501935119352193531935419355193561935719358193591936019361193621936319364193651936619367193681936919370193711937219373193741937519376193771937819379193801938119382193831938419385193861938719388193891939019391193921939319394193951939619397193981939919400194011940219403194041940519406194071940819409194101941119412194131941419415194161941719418194191942019421194221942319424194251942619427194281942919430194311943219433194341943519436194371943819439194401944119442194431944419445194461944719448194491945019451194521945319454194551945619457194581945919460194611946219463194641946519466194671946819469194701947119472194731947419475194761947719478194791948019481194821948319484194851948619487194881948919490194911949219493194941949519496194971949819499195001950119502195031950419505195061950719508195091951019511195121951319514195151951619517195181951919520195211952219523195241952519526195271952819529195301953119532195331953419535195361953719538195391954019541195421954319544195451954619547195481954919550195511955219553195541955519556195571955819559195601956119562195631956419565195661956719568195691957019571195721957319574195751957619577195781957919580195811958219583195841958519586195871958819589195901959119592195931959419595195961959719598195991960019601196021960319604196051960619607196081960919610196111961219613196141961519616196171961819619196201962119622196231962419625196261962719628196291963019631196321963319634196351963619637196381963919640196411964219643196441964519646196471964819649196501965119652196531965419655196561965719658196591966019661196621966319664196651966619667196681966919670196711967219673196741967519676196771967819679196801968119682196831968419685196861968719688196891969019691196921969319694196951969619697196981969919700197011970219703197041970519706197071970819709197101971119712197131971419715197161971719718197191972019721197221972319724197251972619727197281972919730197311973219733197341973519736197371973819739197401974119742197431974419745197461974719748197491975019751197521975319754197551975619757197581975919760197611976219763197641976519766197671976819769197701977119772197731977419775197761977719778197791978019781197821978319784197851978619787197881978919790197911979219793197941979519796197971979819799198001980119802198031980419805198061980719808198091981019811198121981319814198151981619817198181981919820198211982219823198241982519826198271982819829198301983119832198331983419835198361983719838198391984019841198421984319844198451984619847198481984919850198511985219853198541985519856198571985819859198601986119862198631986419865198661986719868198691987019871198721987319874198751987619877198781987919880198811988219883198841988519886198871988819889198901989119892198931989419895198961989719898198991990019901199021990319904199051990619907199081990919910199111991219913199141991519916199171991819919199201992119922199231992419925199261992719928199291993019931199321993319934199351993619937199381993919940199411994219943199441994519946199471994819949199501995119952199531995419955199561995719958199591996019961199621996319964199651996619967199681996919970199711997219973199741997519976199771997819979199801998119982199831998419985199861998719988199891999019991199921999319994199951999619997199981999920000200012000220003200042000520006200072000820009200102001120012200132001420015200162001720018200192002020021200222002320024200252002620027200282002920030200312003220033200342003520036200372003820039200402004120042200432004420045200462004720048200492005020051200522005320054200552005620057200582005920060200612006220063200642006520066200672006820069200702007120072200732007420075200762007720078200792008020081200822008320084200852008620087200882008920090200912009220093200942009520096200972009820099201002010120102201032010420105201062010720108201092011020111201122011320114201152011620117201182011920120201212012220123201242012520126201272012820129201302013120132201332013420135201362013720138201392014020141201422014320144201452014620147201482014920150201512015220153201542015520156201572015820159201602016120162201632016420165201662016720168201692017020171201722017320174201752017620177201782017920180201812018220183201842018520186201872018820189201902019120192201932019420195201962019720198201992020020201202022020320204202052020620207202082020920210202112021220213202142021520216202172021820219202202022120222202232022420225202262022720228202292023020231202322023320234202352023620237202382023920240202412024220243202442024520246202472024820249202502025120252202532025420255202562025720258202592026020261202622026320264202652026620267202682026920270202712027220273202742027520276202772027820279202802028120282202832028420285202862028720288202892029020291202922029320294202952029620297202982029920300203012030220303203042030520306203072030820309203102031120312203132031420315203162031720318203192032020321203222032320324203252032620327203282032920330203312033220333203342033520336203372033820339203402034120342203432034420345203462034720348203492035020351203522035320354203552035620357203582035920360203612036220363203642036520366203672036820369203702037120372203732037420375203762037720378203792038020381203822038320384203852038620387203882038920390203912039220393203942039520396203972039820399204002040120402204032040420405204062040720408204092041020411204122041320414204152041620417204182041920420204212042220423204242042520426204272042820429204302043120432204332043420435204362043720438204392044020441204422044320444204452044620447204482044920450204512045220453204542045520456204572045820459204602046120462204632046420465204662046720468204692047020471204722047320474204752047620477204782047920480204812048220483204842048520486204872048820489204902049120492204932049420495204962049720498204992050020501205022050320504205052050620507205082050920510205112051220513205142051520516205172051820519205202052120522205232052420525205262052720528205292053020531205322053320534205352053620537205382053920540205412054220543205442054520546205472054820549205502055120552205532055420555205562055720558205592056020561205622056320564205652056620567205682056920570205712057220573205742057520576205772057820579205802058120582205832058420585205862058720588205892059020591205922059320594205952059620597205982059920600206012060220603206042060520606206072060820609206102061120612206132061420615206162061720618206192062020621206222062320624206252062620627206282062920630206312063220633206342063520636206372063820639206402064120642206432064420645206462064720648206492065020651206522065320654206552065620657206582065920660206612066220663206642066520666206672066820669206702067120672206732067420675206762067720678206792068020681206822068320684206852068620687206882068920690206912069220693206942069520696206972069820699207002070120702207032070420705207062070720708207092071020711207122071320714207152071620717207182071920720207212072220723207242072520726207272072820729207302073120732207332073420735207362073720738207392074020741207422074320744207452074620747207482074920750207512075220753207542075520756207572075820759207602076120762207632076420765207662076720768207692077020771207722077320774207752077620777207782077920780207812078220783207842078520786207872078820789207902079120792207932079420795207962079720798207992080020801208022080320804208052080620807208082080920810208112081220813208142081520816208172081820819208202082120822208232082420825208262082720828208292083020831208322083320834208352083620837208382083920840208412084220843208442084520846208472084820849208502085120852208532085420855208562085720858208592086020861208622086320864208652086620867208682086920870208712087220873208742087520876208772087820879208802088120882208832088420885208862088720888208892089020891208922089320894208952089620897208982089920900209012090220903209042090520906209072090820909209102091120912209132091420915209162091720918209192092020921209222092320924209252092620927209282092920930209312093220933209342093520936209372093820939209402094120942209432094420945209462094720948209492095020951209522095320954209552095620957209582095920960209612096220963209642096520966209672096820969209702097120972209732097420975209762097720978209792098020981209822098320984209852098620987209882098920990209912099220993209942099520996209972099820999210002100121002210032100421005210062100721008210092101021011210122101321014210152101621017210182101921020210212102221023210242102521026210272102821029210302103121032210332103421035210362103721038210392104021041210422104321044210452104621047210482104921050210512105221053210542105521056210572105821059210602106121062210632106421065210662106721068210692107021071210722107321074210752107621077210782107921080210812108221083210842108521086210872108821089210902109121092210932109421095210962109721098210992110021101211022110321104211052110621107211082110921110211112111221113211142111521116211172111821119211202112121122211232112421125211262112721128211292113021131211322113321134211352113621137211382113921140211412114221143211442114521146211472114821149211502115121152211532115421155211562115721158211592116021161211622116321164211652116621167211682116921170211712117221173211742117521176211772117821179211802118121182211832118421185211862118721188211892119021191211922119321194211952119621197211982119921200212012120221203212042120521206212072120821209212102121121212212132121421215212162121721218212192122021221212222122321224212252122621227212282122921230212312123221233212342123521236212372123821239212402124121242212432124421245212462124721248212492125021251212522125321254212552125621257212582125921260212612126221263212642126521266212672126821269212702127121272212732127421275212762127721278212792128021281212822128321284212852128621287212882128921290212912129221293212942129521296212972129821299213002130121302213032130421305213062130721308213092131021311213122131321314213152131621317213182131921320213212132221323213242132521326213272132821329213302133121332213332133421335213362133721338213392134021341213422134321344213452134621347213482134921350213512135221353213542135521356213572135821359213602136121362213632136421365213662136721368213692137021371213722137321374213752137621377213782137921380213812138221383213842138521386213872138821389213902139121392213932139421395213962139721398213992140021401214022140321404214052140621407214082140921410214112141221413214142141521416214172141821419214202142121422214232142421425214262142721428214292143021431214322143321434214352143621437214382143921440214412144221443214442144521446214472144821449214502145121452214532145421455214562145721458214592146021461214622146321464214652146621467214682146921470214712147221473214742147521476214772147821479214802148121482214832148421485214862148721488214892149021491214922149321494214952149621497214982149921500215012150221503215042150521506215072150821509215102151121512215132151421515215162151721518215192152021521215222152321524215252152621527215282152921530215312153221533215342153521536215372153821539215402154121542215432154421545215462154721548215492155021551215522155321554215552155621557215582155921560215612156221563215642156521566215672156821569215702157121572215732157421575215762157721578215792158021581215822158321584215852158621587215882158921590215912159221593215942159521596215972159821599216002160121602216032160421605216062160721608216092161021611216122161321614216152161621617216182161921620216212162221623216242162521626216272162821629216302163121632216332163421635216362163721638216392164021641216422164321644216452164621647216482164921650216512165221653216542165521656216572165821659216602166121662216632166421665216662166721668216692167021671216722167321674216752167621677216782167921680216812168221683216842168521686216872168821689216902169121692216932169421695216962169721698216992170021701217022170321704217052170621707217082170921710217112171221713217142171521716217172171821719217202172121722217232172421725217262172721728217292173021731217322173321734217352173621737217382173921740217412174221743217442174521746217472174821749217502175121752217532175421755217562175721758217592176021761217622176321764217652176621767217682176921770217712177221773217742177521776217772177821779217802178121782217832178421785217862178721788217892179021791217922179321794217952179621797217982179921800218012180221803218042180521806218072180821809218102181121812218132181421815218162181721818218192182021821218222182321824218252182621827218282182921830218312183221833218342183521836218372183821839218402184121842218432184421845218462184721848218492185021851218522185321854218552185621857218582185921860218612186221863218642186521866218672186821869218702187121872218732187421875218762187721878218792188021881218822188321884218852188621887218882188921890218912189221893218942189521896218972189821899219002190121902219032190421905219062190721908219092191021911219122191321914219152191621917219182191921920219212192221923219242192521926219272192821929219302193121932219332193421935219362193721938219392194021941219422194321944219452194621947219482194921950219512195221953219542195521956219572195821959219602196121962219632196421965219662196721968219692197021971219722197321974219752197621977219782197921980219812198221983219842198521986219872198821989219902199121992219932199421995219962199721998219992200022001220022200322004220052200622007220082200922010220112201222013220142201522016220172201822019220202202122022220232202422025220262202722028220292203022031220322203322034220352203622037220382203922040220412204222043220442204522046220472204822049220502205122052220532205422055220562205722058220592206022061220622206322064220652206622067220682206922070220712207222073220742207522076220772207822079220802208122082220832208422085220862208722088220892209022091220922209322094220952209622097220982209922100221012210222103221042210522106221072210822109221102211122112221132211422115221162211722118221192212022121221222212322124221252212622127221282212922130221312213222133221342213522136221372213822139221402214122142221432214422145221462214722148221492215022151221522215322154221552215622157221582215922160221612216222163221642216522166221672216822169221702217122172221732217422175221762217722178221792218022181221822218322184221852218622187221882218922190221912219222193221942219522196221972219822199222002220122202222032220422205222062220722208222092221022211222122221322214222152221622217222182221922220222212222222223222242222522226222272222822229222302223122232222332223422235222362223722238222392224022241222422224322244222452224622247222482224922250222512225222253222542225522256222572225822259222602226122262222632226422265222662226722268222692227022271222722227322274222752227622277222782227922280222812228222283222842228522286222872228822289222902229122292222932229422295222962229722298222992230022301223022230322304223052230622307223082230922310223112231222313223142231522316223172231822319223202232122322223232232422325223262232722328223292233022331223322233322334223352233622337223382233922340223412234222343223442234522346223472234822349223502235122352223532235422355223562235722358223592236022361223622236322364223652236622367223682236922370223712237222373223742237522376223772237822379223802238122382223832238422385223862238722388223892239022391223922239322394223952239622397223982239922400224012240222403224042240522406224072240822409224102241122412224132241422415224162241722418224192242022421224222242322424224252242622427224282242922430224312243222433224342243522436224372243822439224402244122442224432244422445224462244722448224492245022451224522245322454224552245622457224582245922460224612246222463224642246522466224672246822469224702247122472224732247422475224762247722478224792248022481224822248322484224852248622487224882248922490224912249222493224942249522496224972249822499225002250122502225032250422505225062250722508225092251022511225122251322514225152251622517225182251922520225212252222523225242252522526225272252822529225302253122532225332253422535225362253722538225392254022541225422254322544225452254622547225482254922550225512255222553225542255522556225572255822559225602256122562225632256422565225662256722568225692257022571225722257322574225752257622577225782257922580225812258222583225842258522586225872258822589225902259122592225932259422595225962259722598225992260022601226022260322604226052260622607226082260922610226112261222613226142261522616226172261822619226202262122622226232262422625226262262722628226292263022631226322263322634226352263622637226382263922640226412264222643226442264522646226472264822649226502265122652226532265422655226562265722658226592266022661226622266322664226652266622667226682266922670226712267222673226742267522676226772267822679226802268122682226832268422685226862268722688226892269022691226922269322694226952269622697226982269922700227012270222703227042270522706227072270822709227102271122712227132271422715227162271722718227192272022721227222272322724227252272622727227282272922730227312273222733227342273522736227372273822739227402274122742227432274422745227462274722748227492275022751227522275322754227552275622757227582275922760227612276222763227642276522766227672276822769227702277122772227732277422775227762277722778227792278022781227822278322784227852278622787227882278922790227912279222793227942279522796227972279822799228002280122802228032280422805228062280722808228092281022811228122281322814228152281622817228182281922820228212282222823228242282522826228272282822829228302283122832228332283422835228362283722838228392284022841228422284322844228452284622847228482284922850228512285222853228542285522856228572285822859228602286122862228632286422865228662286722868228692287022871228722287322874228752287622877228782287922880228812288222883228842288522886228872288822889228902289122892228932289422895228962289722898228992290022901229022290322904229052290622907229082290922910229112291222913229142291522916229172291822919229202292122922229232292422925229262292722928229292293022931229322293322934229352293622937229382293922940229412294222943229442294522946229472294822949229502295122952229532295422955229562295722958229592296022961229622296322964229652296622967229682296922970229712297222973229742297522976229772297822979229802298122982229832298422985229862298722988229892299022991229922299322994229952299622997229982299923000230012300223003230042300523006230072300823009230102301123012230132301423015230162301723018230192302023021230222302323024230252302623027230282302923030230312303223033230342303523036230372303823039230402304123042230432304423045230462304723048230492305023051230522305323054230552305623057230582305923060230612306223063230642306523066230672306823069230702307123072230732307423075230762307723078230792308023081230822308323084230852308623087230882308923090230912309223093230942309523096230972309823099231002310123102231032310423105231062310723108231092311023111231122311323114231152311623117231182311923120231212312223123231242312523126231272312823129231302313123132231332313423135231362313723138231392314023141231422314323144231452314623147231482314923150231512315223153231542315523156231572315823159231602316123162231632316423165231662316723168231692317023171231722317323174231752317623177231782317923180231812318223183231842318523186231872318823189231902319123192231932319423195231962319723198231992320023201232022320323204232052320623207232082320923210232112321223213232142321523216232172321823219232202322123222232232322423225232262322723228232292323023231232322323323234232352323623237232382323923240232412324223243232442324523246232472324823249232502325123252232532325423255232562325723258232592326023261232622326323264232652326623267232682326923270232712327223273232742327523276232772327823279232802328123282232832328423285232862328723288232892329023291232922329323294232952329623297232982329923300233012330223303233042330523306233072330823309233102331123312233132331423315233162331723318233192332023321233222332323324233252332623327233282332923330233312333223333233342333523336233372333823339233402334123342233432334423345233462334723348233492335023351233522335323354233552335623357233582335923360233612336223363233642336523366233672336823369233702337123372233732337423375233762337723378233792338023381233822338323384233852338623387233882338923390233912339223393233942339523396233972339823399234002340123402234032340423405234062340723408234092341023411234122341323414234152341623417234182341923420234212342223423234242342523426234272342823429234302343123432234332343423435234362343723438234392344023441234422344323444234452344623447234482344923450234512345223453234542345523456234572345823459234602346123462234632346423465234662346723468234692347023471234722347323474234752347623477234782347923480234812348223483234842348523486234872348823489234902349123492234932349423495234962349723498234992350023501235022350323504235052350623507235082350923510235112351223513235142351523516235172351823519235202352123522235232352423525235262352723528235292353023531235322353323534235352353623537235382353923540235412354223543235442354523546235472354823549235502355123552235532355423555235562355723558235592356023561235622356323564235652356623567235682356923570235712357223573235742357523576235772357823579235802358123582235832358423585235862358723588235892359023591235922359323594235952359623597235982359923600236012360223603236042360523606236072360823609236102361123612236132361423615236162361723618236192362023621236222362323624236252362623627236282362923630236312363223633236342363523636236372363823639236402364123642236432364423645236462364723648236492365023651236522365323654236552365623657236582365923660236612366223663236642366523666236672366823669236702367123672236732367423675236762367723678236792368023681236822368323684236852368623687236882368923690236912369223693236942369523696236972369823699237002370123702237032370423705237062370723708237092371023711237122371323714237152371623717237182371923720237212372223723237242372523726237272372823729237302373123732237332373423735237362373723738237392374023741237422374323744237452374623747237482374923750237512375223753237542375523756237572375823759237602376123762237632376423765237662376723768237692377023771237722377323774237752377623777237782377923780237812378223783237842378523786237872378823789237902379123792237932379423795237962379723798237992380023801238022380323804238052380623807238082380923810238112381223813238142381523816238172381823819238202382123822238232382423825238262382723828238292383023831238322383323834238352383623837238382383923840238412384223843238442384523846238472384823849238502385123852238532385423855238562385723858238592386023861238622386323864238652386623867238682386923870238712387223873238742387523876238772387823879238802388123882238832388423885238862388723888238892389023891238922389323894238952389623897238982389923900239012390223903239042390523906239072390823909239102391123912239132391423915239162391723918239192392023921239222392323924239252392623927239282392923930239312393223933239342393523936239372393823939239402394123942239432394423945239462394723948239492395023951239522395323954239552395623957239582395923960239612396223963239642396523966239672396823969239702397123972239732397423975239762397723978239792398023981239822398323984239852398623987239882398923990239912399223993239942399523996239972399823999240002400124002240032400424005240062400724008240092401024011240122401324014240152401624017240182401924020240212402224023240242402524026240272402824029240302403124032240332403424035240362403724038240392404024041240422404324044240452404624047240482404924050240512405224053240542405524056240572405824059240602406124062240632406424065240662406724068240692407024071240722407324074240752407624077240782407924080240812408224083240842408524086240872408824089240902409124092240932409424095240962409724098240992410024101241022410324104241052410624107241082410924110241112411224113241142411524116241172411824119241202412124122241232412424125241262412724128241292413024131241322413324134241352413624137241382413924140241412414224143241442414524146241472414824149241502415124152241532415424155241562415724158241592416024161241622416324164241652416624167241682416924170241712417224173241742417524176241772417824179241802418124182241832418424185241862418724188241892419024191241922419324194241952419624197241982419924200242012420224203242042420524206242072420824209242102421124212242132421424215242162421724218242192422024221242222422324224242252422624227242282422924230242312423224233242342423524236242372423824239242402424124242242432424424245242462424724248242492425024251242522425324254242552425624257242582425924260242612426224263242642426524266242672426824269242702427124272242732427424275242762427724278242792428024281242822428324284242852428624287242882428924290242912429224293242942429524296242972429824299243002430124302243032430424305243062430724308243092431024311243122431324314243152431624317243182431924320243212432224323243242432524326243272432824329243302433124332243332433424335243362433724338243392434024341243422434324344243452434624347243482434924350243512435224353243542435524356243572435824359243602436124362243632436424365243662436724368243692437024371243722437324374243752437624377243782437924380243812438224383243842438524386243872438824389243902439124392243932439424395243962439724398243992440024401244022440324404244052440624407244082440924410244112441224413244142441524416244172441824419244202442124422244232442424425244262442724428244292443024431244322443324434244352443624437244382443924440244412444224443244442444524446244472444824449244502445124452244532445424455244562445724458244592446024461244622446324464244652446624467244682446924470244712447224473244742447524476244772447824479244802448124482244832448424485244862448724488244892449024491244922449324494244952449624497244982449924500245012450224503245042450524506245072450824509245102451124512245132451424515245162451724518245192452024521245222452324524245252452624527245282452924530245312453224533245342453524536245372453824539245402454124542245432454424545245462454724548245492455024551245522455324554245552455624557245582455924560245612456224563245642456524566245672456824569245702457124572245732457424575245762457724578245792458024581245822458324584245852458624587245882458924590245912459224593245942459524596245972459824599246002460124602246032460424605246062460724608246092461024611246122461324614246152461624617246182461924620246212462224623246242462524626246272462824629246302463124632246332463424635246362463724638246392464024641246422464324644246452464624647246482464924650246512465224653246542465524656246572465824659246602466124662246632466424665246662466724668246692467024671246722467324674246752467624677246782467924680246812468224683246842468524686246872468824689246902469124692246932469424695246962469724698246992470024701247022470324704247052470624707247082470924710247112471224713247142471524716247172471824719247202472124722247232472424725247262472724728247292473024731247322473324734247352473624737247382473924740247412474224743247442474524746247472474824749247502475124752247532475424755247562475724758247592476024761247622476324764247652476624767247682476924770247712477224773247742477524776247772477824779247802478124782247832478424785247862478724788247892479024791247922479324794247952479624797247982479924800248012480224803248042480524806248072480824809248102481124812248132481424815248162481724818248192482024821248222482324824248252482624827248282482924830248312483224833248342483524836248372483824839248402484124842248432484424845248462484724848248492485024851248522485324854248552485624857248582485924860248612486224863248642486524866248672486824869248702487124872248732487424875248762487724878248792488024881248822488324884248852488624887248882488924890248912489224893248942489524896248972489824899249002490124902249032490424905249062490724908249092491024911249122491324914249152491624917249182491924920249212492224923249242492524926249272492824929249302493124932249332493424935249362493724938249392494024941249422494324944249452494624947249482494924950249512495224953249542495524956249572495824959249602496124962249632496424965249662496724968249692497024971249722497324974249752497624977249782497924980249812498224983249842498524986249872498824989249902499124992249932499424995249962499724998249992500025001250022500325004250052500625007250082500925010250112501225013250142501525016250172501825019250202502125022250232502425025250262502725028250292503025031250322503325034250352503625037250382503925040250412504225043250442504525046250472504825049250502505125052250532505425055250562505725058250592506025061250622506325064250652506625067250682506925070250712507225073250742507525076250772507825079250802508125082250832508425085250862508725088250892509025091250922509325094250952509625097250982509925100251012510225103251042510525106251072510825109251102511125112251132511425115251162511725118251192512025121251222512325124251252512625127251282512925130251312513225133251342513525136251372513825139251402514125142251432514425145251462514725148251492515025151251522515325154251552515625157251582515925160251612516225163251642516525166251672516825169251702517125172251732517425175251762517725178251792518025181251822518325184251852518625187251882518925190251912519225193251942519525196251972519825199252002520125202252032520425205252062520725208252092521025211252122521325214252152521625217252182521925220252212522225223252242522525226252272522825229252302523125232252332523425235252362523725238252392524025241252422524325244252452524625247252482524925250252512525225253252542525525256252572525825259252602526125262252632526425265252662526725268252692527025271252722527325274252752527625277252782527925280252812528225283252842528525286252872528825289252902529125292252932529425295252962529725298252992530025301253022530325304253052530625307253082530925310253112531225313253142531525316253172531825319253202532125322253232532425325253262532725328253292533025331253322533325334253352533625337253382533925340253412534225343253442534525346253472534825349253502535125352253532535425355253562535725358253592536025361253622536325364253652536625367253682536925370253712537225373253742537525376253772537825379253802538125382253832538425385253862538725388253892539025391253922539325394253952539625397253982539925400254012540225403254042540525406254072540825409254102541125412254132541425415254162541725418254192542025421254222542325424254252542625427254282542925430254312543225433254342543525436254372543825439254402544125442254432544425445254462544725448254492545025451254522545325454254552545625457254582545925460254612546225463254642546525466254672546825469254702547125472254732547425475254762547725478254792548025481254822548325484254852548625487254882548925490254912549225493254942549525496254972549825499255002550125502255032550425505255062550725508255092551025511255122551325514255152551625517255182551925520255212552225523255242552525526255272552825529255302553125532255332553425535255362553725538255392554025541255422554325544255452554625547255482554925550255512555225553255542555525556255572555825559255602556125562255632556425565255662556725568255692557025571255722557325574255752557625577255782557925580255812558225583255842558525586255872558825589255902559125592255932559425595255962559725598255992560025601256022560325604256052560625607256082560925610256112561225613256142561525616256172561825619256202562125622256232562425625256262562725628256292563025631256322563325634256352563625637256382563925640256412564225643256442564525646256472564825649256502565125652256532565425655256562565725658256592566025661256622566325664256652566625667256682566925670256712567225673256742567525676256772567825679256802568125682256832568425685256862568725688256892569025691256922569325694256952569625697256982569925700257012570225703257042570525706257072570825709257102571125712257132571425715257162571725718257192572025721257222572325724257252572625727257282572925730257312573225733257342573525736257372573825739257402574125742257432574425745257462574725748257492575025751257522575325754257552575625757257582575925760257612576225763257642576525766257672576825769257702577125772257732577425775257762577725778257792578025781257822578325784257852578625787257882578925790257912579225793257942579525796257972579825799258002580125802258032580425805258062580725808258092581025811258122581325814258152581625817258182581925820258212582225823258242582525826258272582825829258302583125832258332583425835258362583725838258392584025841258422584325844258452584625847258482584925850258512585225853258542585525856258572585825859258602586125862258632586425865258662586725868258692587025871258722587325874258752587625877258782587925880258812588225883258842588525886258872588825889258902589125892258932589425895258962589725898258992590025901259022590325904259052590625907259082590925910259112591225913259142591525916259172591825919259202592125922259232592425925259262592725928259292593025931259322593325934259352593625937259382593925940259412594225943259442594525946259472594825949259502595125952259532595425955259562595725958259592596025961259622596325964259652596625967259682596925970259712597225973259742597525976259772597825979259802598125982259832598425985259862598725988259892599025991259922599325994259952599625997259982599926000260012600226003260042600526006260072600826009260102601126012260132601426015260162601726018260192602026021260222602326024260252602626027260282602926030260312603226033260342603526036260372603826039260402604126042260432604426045260462604726048260492605026051260522605326054260552605626057260582605926060260612606226063260642606526066260672606826069260702607126072260732607426075260762607726078260792608026081260822608326084260852608626087260882608926090260912609226093260942609526096260972609826099261002610126102261032610426105261062610726108261092611026111261122611326114261152611626117261182611926120261212612226123261242612526126261272612826129261302613126132261332613426135261362613726138261392614026141261422614326144261452614626147261482614926150261512615226153261542615526156261572615826159261602616126162261632616426165261662616726168261692617026171261722617326174261752617626177261782617926180261812618226183261842618526186261872618826189261902619126192261932619426195261962619726198261992620026201262022620326204262052620626207262082620926210262112621226213262142621526216262172621826219262202622126222262232622426225262262622726228262292623026231262322623326234262352623626237262382623926240262412624226243262442624526246262472624826249262502625126252262532625426255262562625726258262592626026261262622626326264262652626626267262682626926270262712627226273262742627526276262772627826279262802628126282262832628426285262862628726288262892629026291262922629326294262952629626297262982629926300263012630226303263042630526306263072630826309263102631126312263132631426315263162631726318263192632026321263222632326324263252632626327263282632926330263312633226333263342633526336263372633826339263402634126342263432634426345263462634726348263492635026351263522635326354263552635626357263582635926360263612636226363263642636526366263672636826369263702637126372263732637426375263762637726378263792638026381263822638326384263852638626387263882638926390263912639226393263942639526396263972639826399264002640126402264032640426405264062640726408264092641026411264122641326414264152641626417264182641926420264212642226423264242642526426264272642826429264302643126432264332643426435264362643726438264392644026441264422644326444264452644626447264482644926450264512645226453264542645526456264572645826459264602646126462264632646426465264662646726468264692647026471264722647326474264752647626477264782647926480264812648226483264842648526486264872648826489264902649126492264932649426495264962649726498264992650026501265022650326504265052650626507265082650926510265112651226513265142651526516265172651826519265202652126522265232652426525265262652726528265292653026531265322653326534265352653626537265382653926540265412654226543265442654526546265472654826549265502655126552265532655426555265562655726558265592656026561265622656326564265652656626567265682656926570265712657226573265742657526576265772657826579265802658126582265832658426585265862658726588265892659026591265922659326594265952659626597265982659926600266012660226603266042660526606266072660826609266102661126612266132661426615266162661726618266192662026621266222662326624266252662626627266282662926630266312663226633266342663526636266372663826639266402664126642266432664426645266462664726648266492665026651266522665326654266552665626657266582665926660266612666226663266642666526666266672666826669266702667126672266732667426675266762667726678266792668026681266822668326684266852668626687266882668926690266912669226693266942669526696266972669826699267002670126702267032670426705267062670726708267092671026711267122671326714267152671626717267182671926720267212672226723267242672526726267272672826729267302673126732267332673426735267362673726738267392674026741267422674326744267452674626747267482674926750267512675226753267542675526756267572675826759267602676126762267632676426765267662676726768267692677026771267722677326774267752677626777267782677926780267812678226783267842678526786267872678826789267902679126792267932679426795267962679726798267992680026801268022680326804268052680626807268082680926810268112681226813268142681526816268172681826819268202682126822268232682426825268262682726828268292683026831268322683326834268352683626837268382683926840268412684226843268442684526846268472684826849268502685126852268532685426855268562685726858268592686026861268622686326864268652686626867268682686926870268712687226873268742687526876268772687826879268802688126882268832688426885268862688726888268892689026891268922689326894268952689626897268982689926900269012690226903269042690526906269072690826909269102691126912269132691426915269162691726918269192692026921269222692326924269252692626927269282692926930269312693226933269342693526936269372693826939269402694126942269432694426945269462694726948269492695026951269522695326954269552695626957269582695926960269612696226963269642696526966269672696826969269702697126972269732697426975269762697726978269792698026981269822698326984269852698626987269882698926990269912699226993269942699526996269972699826999270002700127002270032700427005270062700727008270092701027011270122701327014270152701627017270182701927020270212702227023270242702527026270272702827029270302703127032270332703427035270362703727038270392704027041270422704327044270452704627047270482704927050270512705227053270542705527056270572705827059270602706127062270632706427065270662706727068270692707027071270722707327074270752707627077270782707927080270812708227083270842708527086270872708827089270902709127092270932709427095270962709727098270992710027101271022710327104271052710627107271082710927110271112711227113271142711527116271172711827119271202712127122271232712427125271262712727128271292713027131271322713327134271352713627137271382713927140271412714227143271442714527146271472714827149271502715127152271532715427155271562715727158271592716027161271622716327164271652716627167271682716927170271712717227173271742717527176271772717827179271802718127182271832718427185271862718727188271892719027191271922719327194271952719627197271982719927200272012720227203272042720527206272072720827209272102721127212272132721427215272162721727218272192722027221272222722327224272252722627227272282722927230272312723227233272342723527236272372723827239272402724127242272432724427245272462724727248272492725027251272522725327254272552725627257272582725927260272612726227263272642726527266272672726827269272702727127272272732727427275272762727727278272792728027281272822728327284272852728627287272882728927290272912729227293272942729527296272972729827299273002730127302273032730427305273062730727308273092731027311273122731327314273152731627317273182731927320273212732227323273242732527326273272732827329273302733127332273332733427335273362733727338273392734027341273422734327344273452734627347273482734927350273512735227353273542735527356273572735827359273602736127362273632736427365273662736727368273692737027371273722737327374273752737627377273782737927380273812738227383273842738527386273872738827389273902739127392273932739427395273962739727398273992740027401274022740327404274052740627407274082740927410274112741227413274142741527416274172741827419274202742127422274232742427425274262742727428274292743027431274322743327434274352743627437274382743927440274412744227443274442744527446274472744827449274502745127452274532745427455274562745727458274592746027461274622746327464274652746627467274682746927470274712747227473274742747527476274772747827479274802748127482274832748427485274862748727488274892749027491274922749327494274952749627497274982749927500275012750227503275042750527506275072750827509275102751127512275132751427515275162751727518275192752027521275222752327524275252752627527275282752927530275312753227533275342753527536275372753827539275402754127542275432754427545275462754727548275492755027551275522755327554275552755627557275582755927560275612756227563275642756527566275672756827569275702757127572275732757427575275762757727578275792758027581275822758327584275852758627587275882758927590275912759227593275942759527596275972759827599276002760127602276032760427605276062760727608276092761027611276122761327614276152761627617276182761927620276212762227623276242762527626276272762827629276302763127632276332763427635276362763727638276392764027641276422764327644276452764627647276482764927650276512765227653276542765527656276572765827659276602766127662276632766427665276662766727668276692767027671276722767327674276752767627677276782767927680276812768227683276842768527686276872768827689276902769127692276932769427695276962769727698276992770027701277022770327704277052770627707277082770927710277112771227713277142771527716277172771827719277202772127722277232772427725277262772727728277292773027731277322773327734277352773627737277382773927740277412774227743277442774527746277472774827749277502775127752277532775427755277562775727758277592776027761277622776327764277652776627767277682776927770277712777227773277742777527776277772777827779277802778127782277832778427785277862778727788277892779027791277922779327794277952779627797277982779927800278012780227803278042780527806278072780827809278102781127812278132781427815278162781727818278192782027821278222782327824278252782627827278282782927830278312783227833278342783527836278372783827839278402784127842278432784427845278462784727848278492785027851278522785327854278552785627857278582785927860278612786227863278642786527866278672786827869278702787127872278732787427875278762787727878278792788027881278822788327884278852788627887278882788927890278912789227893278942789527896278972789827899279002790127902279032790427905279062790727908279092791027911279122791327914279152791627917279182791927920279212792227923279242792527926279272792827929279302793127932279332793427935279362793727938279392794027941279422794327944279452794627947279482794927950279512795227953279542795527956279572795827959279602796127962279632796427965279662796727968279692797027971279722797327974279752797627977279782797927980279812798227983279842798527986279872798827989279902799127992279932799427995279962799727998279992800028001280022800328004280052800628007280082800928010280112801228013280142801528016280172801828019280202802128022280232802428025280262802728028280292803028031280322803328034280352803628037280382803928040280412804228043280442804528046280472804828049280502805128052280532805428055280562805728058280592806028061280622806328064280652806628067280682806928070280712807228073280742807528076280772807828079280802808128082280832808428085280862808728088280892809028091280922809328094280952809628097280982809928100281012810228103281042810528106281072810828109281102811128112281132811428115281162811728118281192812028121281222812328124281252812628127281282812928130281312813228133281342813528136281372813828139281402814128142281432814428145281462814728148281492815028151281522815328154281552815628157281582815928160281612816228163281642816528166281672816828169281702817128172281732817428175281762817728178281792818028181281822818328184281852818628187281882818928190281912819228193281942819528196281972819828199282002820128202282032820428205282062820728208282092821028211282122821328214282152821628217282182821928220282212822228223282242822528226282272822828229282302823128232282332823428235282362823728238282392824028241282422824328244282452824628247282482824928250282512825228253282542825528256282572825828259282602826128262282632826428265282662826728268282692827028271282722827328274282752827628277282782827928280282812828228283282842828528286282872828828289282902829128292282932829428295282962829728298282992830028301283022830328304283052830628307283082830928310283112831228313283142831528316283172831828319283202832128322283232832428325283262832728328283292833028331283322833328334283352833628337283382833928340283412834228343283442834528346283472834828349283502835128352283532835428355283562835728358283592836028361283622836328364283652836628367283682836928370283712837228373283742837528376283772837828379283802838128382283832838428385283862838728388283892839028391283922839328394283952839628397283982839928400284012840228403284042840528406284072840828409284102841128412284132841428415284162841728418284192842028421284222842328424284252842628427284282842928430284312843228433284342843528436284372843828439284402844128442284432844428445284462844728448284492845028451284522845328454284552845628457284582845928460284612846228463284642846528466284672846828469284702847128472284732847428475284762847728478284792848028481284822848328484284852848628487284882848928490284912849228493284942849528496284972849828499285002850128502285032850428505285062850728508285092851028511285122851328514285152851628517285182851928520285212852228523285242852528526285272852828529285302853128532285332853428535285362853728538285392854028541285422854328544285452854628547285482854928550285512855228553285542855528556285572855828559285602856128562285632856428565285662856728568285692857028571285722857328574285752857628577285782857928580285812858228583285842858528586285872858828589285902859128592285932859428595285962859728598285992860028601286022860328604286052860628607286082860928610286112861228613286142861528616286172861828619286202862128622286232862428625286262862728628286292863028631286322863328634286352863628637286382863928640286412864228643286442864528646286472864828649286502865128652286532865428655286562865728658286592866028661286622866328664286652866628667286682866928670286712867228673286742867528676286772867828679286802868128682286832868428685286862868728688286892869028691286922869328694286952869628697286982869928700287012870228703287042870528706287072870828709287102871128712287132871428715287162871728718287192872028721287222872328724287252872628727287282872928730287312873228733287342873528736287372873828739287402874128742287432874428745287462874728748287492875028751287522875328754287552875628757287582875928760287612876228763287642876528766287672876828769287702877128772287732877428775287762877728778287792878028781287822878328784287852878628787287882878928790287912879228793287942879528796287972879828799288002880128802288032880428805288062880728808288092881028811288122881328814288152881628817288182881928820288212882228823288242882528826288272882828829288302883128832288332883428835288362883728838288392884028841288422884328844288452884628847288482884928850288512885228853288542885528856288572885828859288602886128862288632886428865288662886728868288692887028871288722887328874288752887628877288782887928880288812888228883288842888528886288872888828889288902889128892288932889428895288962889728898288992890028901289022890328904289052890628907289082890928910289112891228913289142891528916289172891828919289202892128922289232892428925289262892728928289292893028931289322893328934289352893628937289382893928940289412894228943289442894528946289472894828949289502895128952289532895428955289562895728958289592896028961289622896328964289652896628967289682896928970289712897228973289742897528976289772897828979289802898128982289832898428985289862898728988289892899028991289922899328994289952899628997289982899929000290012900229003290042900529006290072900829009290102901129012290132901429015290162901729018290192902029021290222902329024290252902629027290282902929030290312903229033290342903529036290372903829039290402904129042290432904429045290462904729048290492905029051290522905329054290552905629057290582905929060290612906229063290642906529066290672906829069290702907129072290732907429075290762907729078290792908029081290822908329084290852908629087290882908929090290912909229093290942909529096290972909829099291002910129102291032910429105291062910729108291092911029111291122911329114291152911629117291182911929120291212912229123291242912529126291272912829129291302913129132291332913429135291362913729138291392914029141291422914329144291452914629147291482914929150291512915229153291542915529156291572915829159291602916129162291632916429165291662916729168291692917029171291722917329174291752917629177291782917929180291812918229183291842918529186291872918829189291902919129192291932919429195291962919729198291992920029201292022920329204292052920629207292082920929210292112921229213292142921529216292172921829219292202922129222292232922429225292262922729228292292923029231292322923329234292352923629237292382923929240292412924229243292442924529246292472924829249292502925129252292532925429255292562925729258292592926029261292622926329264292652926629267292682926929270292712927229273292742927529276292772927829279292802928129282292832928429285292862928729288292892929029291292922929329294292952929629297292982929929300293012930229303293042930529306293072930829309293102931129312293132931429315293162931729318293192932029321293222932329324293252932629327293282932929330293312933229333293342933529336293372933829339293402934129342293432934429345293462934729348293492935029351293522935329354293552935629357293582935929360293612936229363293642936529366293672936829369293702937129372293732937429375293762937729378293792938029381293822938329384293852938629387293882938929390293912939229393293942939529396293972939829399294002940129402294032940429405294062940729408294092941029411294122941329414294152941629417294182941929420294212942229423294242942529426294272942829429294302943129432294332943429435294362943729438294392944029441294422944329444294452944629447294482944929450294512945229453294542945529456294572945829459294602946129462294632946429465294662946729468294692947029471294722947329474294752947629477294782947929480294812948229483294842948529486294872948829489294902949129492294932949429495294962949729498294992950029501295022950329504295052950629507295082950929510295112951229513295142951529516295172951829519295202952129522295232952429525295262952729528295292953029531295322953329534295352953629537295382953929540295412954229543295442954529546295472954829549295502955129552295532955429555295562955729558295592956029561295622956329564295652956629567295682956929570295712957229573295742957529576295772957829579295802958129582295832958429585295862958729588295892959029591295922959329594295952959629597295982959929600296012960229603296042960529606296072960829609296102961129612296132961429615296162961729618296192962029621296222962329624296252962629627296282962929630296312963229633296342963529636296372963829639296402964129642296432964429645296462964729648296492965029651296522965329654296552965629657296582965929660296612966229663296642966529666296672966829669296702967129672296732967429675296762967729678296792968029681296822968329684296852968629687296882968929690296912969229693296942969529696296972969829699297002970129702297032970429705297062970729708297092971029711297122971329714297152971629717297182971929720297212972229723297242972529726297272972829729297302973129732297332973429735297362973729738297392974029741297422974329744297452974629747297482974929750297512975229753297542975529756297572975829759297602976129762297632976429765297662976729768297692977029771297722977329774297752977629777297782977929780297812978229783297842978529786297872978829789297902979129792297932979429795297962979729798297992980029801298022980329804298052980629807298082980929810298112981229813298142981529816298172981829819298202982129822298232982429825298262982729828298292983029831298322983329834298352983629837298382983929840298412984229843298442984529846298472984829849298502985129852298532985429855298562985729858298592986029861298622986329864298652986629867298682986929870298712987229873298742987529876298772987829879298802988129882298832988429885298862988729888298892989029891298922989329894298952989629897298982989929900299012990229903299042990529906299072990829909299102991129912299132991429915299162991729918299192992029921299222992329924299252992629927299282992929930299312993229933299342993529936299372993829939299402994129942299432994429945299462994729948299492995029951299522995329954299552995629957299582995929960299612996229963299642996529966299672996829969299702997129972299732997429975299762997729978299792998029981299822998329984299852998629987299882998929990299912999229993299942999529996299972999829999300003000130002300033000430005300063000730008300093001030011300123001330014300153001630017300183001930020300213002230023300243002530026300273002830029300303003130032300333003430035300363003730038300393004030041300423004330044300453004630047300483004930050300513005230053300543005530056300573005830059300603006130062300633006430065300663006730068300693007030071300723007330074300753007630077300783007930080300813008230083300843008530086300873008830089300903009130092300933009430095300963009730098300993010030101301023010330104301053010630107301083010930110301113011230113301143011530116301173011830119301203012130122301233012430125301263012730128301293013030131301323013330134301353013630137301383013930140301413014230143301443014530146301473014830149301503015130152301533015430155301563015730158301593016030161301623016330164301653016630167301683016930170301713017230173301743017530176301773017830179301803018130182301833018430185301863018730188301893019030191301923019330194301953019630197301983019930200302013020230203302043020530206302073020830209302103021130212302133021430215302163021730218302193022030221302223022330224302253022630227302283022930230302313023230233302343023530236302373023830239302403024130242302433024430245302463024730248302493025030251302523025330254302553025630257302583025930260302613026230263302643026530266302673026830269302703027130272302733027430275302763027730278302793028030281302823028330284302853028630287302883028930290302913029230293302943029530296302973029830299303003030130302303033030430305303063030730308303093031030311303123031330314303153031630317303183031930320303213032230323303243032530326303273032830329303303033130332303333033430335303363033730338303393034030341303423034330344303453034630347303483034930350303513035230353303543035530356303573035830359303603036130362303633036430365303663036730368303693037030371303723037330374303753037630377303783037930380303813038230383303843038530386303873038830389303903039130392303933039430395303963039730398303993040030401304023040330404304053040630407304083040930410304113041230413304143041530416304173041830419304203042130422304233042430425304263042730428304293043030431304323043330434304353043630437304383043930440304413044230443304443044530446304473044830449304503045130452304533045430455304563045730458304593046030461304623046330464304653046630467304683046930470304713047230473304743047530476304773047830479304803048130482304833048430485304863048730488304893049030491304923049330494304953049630497304983049930500305013050230503305043050530506305073050830509305103051130512305133051430515305163051730518305193052030521305223052330524305253052630527305283052930530305313053230533305343053530536305373053830539305403054130542305433054430545305463054730548305493055030551305523055330554305553055630557305583055930560305613056230563305643056530566305673056830569305703057130572305733057430575305763057730578305793058030581305823058330584305853058630587305883058930590305913059230593305943059530596305973059830599306003060130602306033060430605306063060730608306093061030611306123061330614306153061630617306183061930620306213062230623306243062530626306273062830629306303063130632306333063430635306363063730638306393064030641306423064330644306453064630647306483064930650306513065230653306543065530656306573065830659306603066130662306633066430665306663066730668306693067030671306723067330674306753067630677306783067930680306813068230683306843068530686306873068830689306903069130692306933069430695306963069730698306993070030701307023070330704307053070630707307083070930710307113071230713307143071530716307173071830719307203072130722307233072430725307263072730728307293073030731307323073330734307353073630737307383073930740307413074230743307443074530746307473074830749307503075130752307533075430755307563075730758307593076030761307623076330764307653076630767307683076930770307713077230773307743077530776307773077830779307803078130782307833078430785307863078730788307893079030791307923079330794307953079630797307983079930800308013080230803308043080530806308073080830809308103081130812308133081430815308163081730818308193082030821308223082330824308253082630827308283082930830308313083230833308343083530836308373083830839308403084130842308433084430845308463084730848308493085030851308523085330854308553085630857308583085930860308613086230863308643086530866308673086830869308703087130872308733087430875308763087730878308793088030881308823088330884308853088630887308883088930890308913089230893308943089530896308973089830899309003090130902309033090430905309063090730908309093091030911309123091330914309153091630917309183091930920309213092230923309243092530926309273092830929309303093130932309333093430935309363093730938309393094030941309423094330944309453094630947309483094930950309513095230953309543095530956309573095830959309603096130962309633096430965309663096730968309693097030971309723097330974309753097630977309783097930980309813098230983309843098530986309873098830989309903099130992309933099430995309963099730998309993100031001310023100331004310053100631007310083100931010310113101231013310143101531016310173101831019310203102131022310233102431025310263102731028310293103031031310323103331034310353103631037310383103931040310413104231043310443104531046310473104831049310503105131052310533105431055310563105731058310593106031061310623106331064310653106631067310683106931070310713107231073310743107531076310773107831079310803108131082310833108431085310863108731088310893109031091310923109331094310953109631097310983109931100311013110231103311043110531106311073110831109311103111131112311133111431115311163111731118311193112031121311223112331124311253112631127311283112931130311313113231133311343113531136311373113831139311403114131142311433114431145311463114731148311493115031151311523115331154311553115631157311583115931160311613116231163311643116531166311673116831169311703117131172311733117431175311763117731178311793118031181311823118331184311853118631187311883118931190311913119231193311943119531196311973119831199312003120131202312033120431205312063120731208312093121031211312123121331214312153121631217312183121931220312213122231223312243122531226312273122831229312303123131232312333123431235312363123731238312393124031241312423124331244312453124631247312483124931250312513125231253312543125531256312573125831259312603126131262312633126431265312663126731268312693127031271312723127331274312753127631277312783127931280312813128231283312843128531286312873128831289312903129131292312933129431295312963129731298312993130031301313023130331304313053130631307313083130931310313113131231313313143131531316313173131831319313203132131322313233132431325313263132731328313293133031331313323133331334313353133631337313383133931340313413134231343313443134531346313473134831349313503135131352313533135431355313563135731358313593136031361313623136331364313653136631367313683136931370313713137231373313743137531376313773137831379313803138131382313833138431385313863138731388313893139031391313923139331394313953139631397313983139931400314013140231403314043140531406314073140831409314103141131412314133141431415314163141731418314193142031421314223142331424314253142631427314283142931430314313143231433314343143531436314373143831439314403144131442314433144431445314463144731448314493145031451314523145331454314553145631457314583145931460314613146231463314643146531466314673146831469314703147131472314733147431475314763147731478314793148031481314823148331484314853148631487314883148931490314913149231493314943149531496314973149831499315003150131502315033150431505315063150731508315093151031511315123151331514315153151631517315183151931520315213152231523315243152531526315273152831529315303153131532315333153431535315363153731538315393154031541315423154331544315453154631547315483154931550315513155231553315543155531556315573155831559315603156131562315633156431565315663156731568315693157031571315723157331574315753157631577315783157931580315813158231583315843158531586315873158831589315903159131592315933159431595315963159731598315993160031601316023160331604316053160631607316083160931610316113161231613316143161531616316173161831619316203162131622316233162431625316263162731628316293163031631316323163331634316353163631637316383163931640316413164231643316443164531646316473164831649316503165131652316533165431655316563165731658316593166031661316623166331664316653166631667316683166931670316713167231673316743167531676316773167831679316803168131682316833168431685316863168731688316893169031691316923169331694316953169631697316983169931700317013170231703317043170531706317073170831709317103171131712317133171431715317163171731718317193172031721317223172331724317253172631727317283172931730317313173231733317343173531736317373173831739317403174131742317433174431745317463174731748317493175031751317523175331754317553175631757317583175931760317613176231763317643176531766317673176831769317703177131772317733177431775317763177731778317793178031781317823178331784317853178631787317883178931790317913179231793317943179531796317973179831799318003180131802318033180431805318063180731808318093181031811318123181331814318153181631817318183181931820318213182231823318243182531826318273182831829318303183131832318333183431835318363183731838318393184031841318423184331844318453184631847318483184931850318513185231853318543185531856318573185831859318603186131862318633186431865318663186731868318693187031871318723187331874318753187631877318783187931880318813188231883318843188531886318873188831889318903189131892318933189431895318963189731898318993190031901319023190331904319053190631907319083190931910319113191231913319143191531916319173191831919319203192131922319233192431925319263192731928319293193031931319323193331934319353193631937319383193931940319413194231943319443194531946319473194831949319503195131952319533195431955319563195731958319593196031961319623196331964319653196631967319683196931970319713197231973319743197531976319773197831979319803198131982319833198431985319863198731988319893199031991319923199331994319953199631997319983199932000320013200232003320043200532006320073200832009320103201132012320133201432015320163201732018320193202032021320223202332024320253202632027320283202932030320313203232033320343203532036320373203832039320403204132042320433204432045320463204732048320493205032051320523205332054320553205632057320583205932060320613206232063320643206532066320673206832069320703207132072320733207432075320763207732078320793208032081320823208332084320853208632087320883208932090320913209232093320943209532096320973209832099321003210132102321033210432105321063210732108321093211032111321123211332114321153211632117321183211932120321213212232123321243212532126321273212832129321303213132132321333213432135321363213732138321393214032141321423214332144321453214632147321483214932150321513215232153321543215532156321573215832159321603216132162321633216432165321663216732168321693217032171321723217332174321753217632177321783217932180321813218232183321843218532186321873218832189321903219132192321933219432195321963219732198321993220032201322023220332204322053220632207322083220932210322113221232213322143221532216322173221832219322203222132222322233222432225322263222732228322293223032231322323223332234322353223632237322383223932240322413224232243322443224532246322473224832249322503225132252322533225432255322563225732258322593226032261322623226332264322653226632267322683226932270322713227232273322743227532276322773227832279322803228132282322833228432285322863228732288322893229032291322923229332294322953229632297322983229932300323013230232303323043230532306323073230832309323103231132312323133231432315323163231732318323193232032321323223232332324323253232632327323283232932330323313233232333323343233532336323373233832339323403234132342323433234432345323463234732348323493235032351323523235332354323553235632357323583235932360323613236232363323643236532366323673236832369323703237132372323733237432375323763237732378323793238032381323823238332384323853238632387323883238932390323913239232393323943239532396323973239832399324003240132402324033240432405324063240732408324093241032411324123241332414324153241632417324183241932420324213242232423324243242532426324273242832429324303243132432324333243432435324363243732438324393244032441324423244332444324453244632447324483244932450324513245232453324543245532456324573245832459324603246132462324633246432465324663246732468324693247032471324723247332474324753247632477324783247932480324813248232483324843248532486324873248832489324903249132492324933249432495324963249732498324993250032501325023250332504325053250632507325083250932510325113251232513325143251532516325173251832519325203252132522325233252432525325263252732528325293253032531325323253332534325353253632537325383253932540325413254232543325443254532546325473254832549325503255132552325533255432555325563255732558325593256032561325623256332564325653256632567325683256932570325713257232573325743257532576325773257832579325803258132582325833258432585325863258732588325893259032591325923259332594325953259632597325983259932600326013260232603326043260532606326073260832609326103261132612326133261432615326163261732618326193262032621326223262332624326253262632627326283262932630326313263232633326343263532636326373263832639326403264132642326433264432645326463264732648326493265032651326523265332654326553265632657326583265932660326613266232663326643266532666326673266832669326703267132672326733267432675326763267732678326793268032681326823268332684326853268632687326883268932690326913269232693326943269532696326973269832699327003270132702327033270432705327063270732708327093271032711327123271332714327153271632717327183271932720327213272232723327243272532726327273272832729327303273132732327333273432735327363273732738327393274032741327423274332744327453274632747327483274932750327513275232753327543275532756327573275832759327603276132762327633276432765327663276732768327693277032771327723277332774327753277632777327783277932780327813278232783327843278532786327873278832789327903279132792327933279432795327963279732798327993280032801328023280332804328053280632807328083280932810328113281232813328143281532816328173281832819328203282132822328233282432825328263282732828328293283032831328323283332834328353283632837328383283932840328413284232843328443284532846328473284832849328503285132852328533285432855328563285732858328593286032861328623286332864328653286632867328683286932870328713287232873328743287532876328773287832879328803288132882328833288432885328863288732888328893289032891328923289332894328953289632897328983289932900329013290232903329043290532906329073290832909329103291132912329133291432915329163291732918329193292032921329223292332924329253292632927329283292932930329313293232933329343293532936329373293832939329403294132942329433294432945329463294732948329493295032951329523295332954329553295632957329583295932960329613296232963329643296532966329673296832969329703297132972329733297432975329763297732978329793298032981329823298332984329853298632987329883298932990329913299232993329943299532996329973299832999330003300133002330033300433005330063300733008330093301033011330123301333014330153301633017330183301933020330213302233023330243302533026330273302833029330303303133032330333303433035330363303733038330393304033041330423304333044330453304633047330483304933050330513305233053330543305533056330573305833059330603306133062330633306433065330663306733068330693307033071330723307333074330753307633077330783307933080330813308233083330843308533086330873308833089330903309133092330933309433095330963309733098330993310033101331023310333104331053310633107331083310933110331113311233113331143311533116331173311833119331203312133122331233312433125331263312733128331293313033131331323313333134331353313633137331383313933140331413314233143331443314533146331473314833149331503315133152331533315433155331563315733158331593316033161331623316333164331653316633167331683316933170331713317233173331743317533176331773317833179331803318133182331833318433185331863318733188331893319033191331923319333194331953319633197331983319933200332013320233203332043320533206332073320833209332103321133212332133321433215332163321733218332193322033221332223322333224332253322633227332283322933230332313323233233332343323533236332373323833239332403324133242332433324433245332463324733248332493325033251332523325333254332553325633257332583325933260332613326233263332643326533266332673326833269332703327133272332733327433275332763327733278332793328033281332823328333284332853328633287332883328933290332913329233293332943329533296332973329833299333003330133302333033330433305333063330733308333093331033311333123331333314333153331633317333183331933320333213332233323333243332533326333273332833329333303333133332333333333433335333363333733338333393334033341333423334333344333453334633347333483334933350333513335233353333543335533356333573335833359333603336133362333633336433365333663336733368333693337033371333723337333374333753337633377333783337933380333813338233383333843338533386333873338833389333903339133392333933339433395333963339733398333993340033401334023340333404334053340633407334083340933410334113341233413334143341533416334173341833419334203342133422334233342433425334263342733428334293343033431334323343333434334353343633437334383343933440334413344233443334443344533446334473344833449334503345133452334533345433455334563345733458334593346033461334623346333464334653346633467334683346933470334713347233473334743347533476334773347833479334803348133482334833348433485334863348733488334893349033491334923349333494334953349633497334983349933500335013350233503335043350533506335073350833509335103351133512335133351433515335163351733518335193352033521335223352333524335253352633527335283352933530335313353233533335343353533536335373353833539335403354133542335433354433545335463354733548335493355033551335523355333554335553355633557335583355933560335613356233563335643356533566335673356833569335703357133572335733357433575335763357733578335793358033581335823358333584335853358633587335883358933590335913359233593335943359533596335973359833599336003360133602336033360433605336063360733608336093361033611336123361333614336153361633617336183361933620336213362233623336243362533626336273362833629336303363133632336333363433635336363363733638336393364033641336423364333644336453364633647336483364933650336513365233653336543365533656336573365833659336603366133662336633366433665336663366733668336693367033671336723367333674336753367633677336783367933680336813368233683336843368533686336873368833689336903369133692336933369433695336963369733698336993370033701337023370333704337053370633707337083370933710337113371233713337143371533716337173371833719337203372133722337233372433725337263372733728337293373033731337323373333734337353373633737337383373933740337413374233743337443374533746337473374833749337503375133752337533375433755337563375733758337593376033761337623376333764337653376633767337683376933770337713377233773337743377533776337773377833779337803378133782337833378433785337863378733788337893379033791337923379333794337953379633797337983379933800338013380233803338043380533806338073380833809338103381133812338133381433815338163381733818338193382033821338223382333824338253382633827338283382933830338313383233833338343383533836338373383833839338403384133842338433384433845338463384733848338493385033851338523385333854338553385633857338583385933860338613386233863338643386533866338673386833869338703387133872338733387433875338763387733878338793388033881338823388333884338853388633887338883388933890338913389233893338943389533896338973389833899339003390133902339033390433905339063390733908339093391033911339123391333914339153391633917339183391933920339213392233923339243392533926339273392833929339303393133932339333393433935339363393733938339393394033941339423394333944339453394633947339483394933950339513395233953339543395533956339573395833959339603396133962339633396433965339663396733968339693397033971339723397333974339753397633977339783397933980339813398233983339843398533986339873398833989339903399133992339933399433995339963399733998339993400034001340023400334004340053400634007340083400934010340113401234013340143401534016340173401834019340203402134022340233402434025340263402734028340293403034031340323403334034340353403634037340383403934040340413404234043340443404534046340473404834049340503405134052340533405434055340563405734058340593406034061340623406334064340653406634067340683406934070340713407234073340743407534076340773407834079340803408134082340833408434085340863408734088340893409034091340923409334094340953409634097340983409934100341013410234103341043410534106341073410834109341103411134112341133411434115341163411734118341193412034121341223412334124341253412634127341283412934130341313413234133341343413534136341373413834139341403414134142341433414434145341463414734148341493415034151341523415334154341553415634157341583415934160341613416234163341643416534166341673416834169341703417134172341733417434175341763417734178341793418034181341823418334184341853418634187341883418934190341913419234193341943419534196341973419834199342003420134202342033420434205342063420734208342093421034211342123421334214342153421634217342183421934220342213422234223342243422534226342273422834229342303423134232342333423434235342363423734238342393424034241342423424334244342453424634247342483424934250342513425234253342543425534256342573425834259342603426134262342633426434265342663426734268342693427034271342723427334274342753427634277342783427934280342813428234283342843428534286342873428834289342903429134292342933429434295342963429734298342993430034301343023430334304343053430634307343083430934310343113431234313343143431534316343173431834319343203432134322343233432434325343263432734328343293433034331343323433334334343353433634337343383433934340343413434234343343443434534346343473434834349343503435134352343533435434355343563435734358343593436034361343623436334364343653436634367343683436934370343713437234373343743437534376343773437834379343803438134382343833438434385343863438734388343893439034391343923439334394343953439634397343983439934400344013440234403344043440534406344073440834409344103441134412344133441434415344163441734418344193442034421344223442334424344253442634427344283442934430344313443234433344343443534436344373443834439344403444134442344433444434445344463444734448344493445034451344523445334454344553445634457344583445934460344613446234463344643446534466344673446834469344703447134472344733447434475344763447734478344793448034481344823448334484344853448634487344883448934490344913449234493344943449534496344973449834499345003450134502345033450434505345063450734508345093451034511345123451334514345153451634517345183451934520345213452234523345243452534526345273452834529345303453134532345333453434535345363453734538345393454034541345423454334544345453454634547345483454934550345513455234553345543455534556345573455834559345603456134562345633456434565345663456734568345693457034571345723457334574345753457634577345783457934580345813458234583345843458534586345873458834589345903459134592345933459434595345963459734598345993460034601346023460334604346053460634607346083460934610346113461234613346143461534616346173461834619346203462134622346233462434625346263462734628346293463034631346323463334634346353463634637346383463934640346413464234643346443464534646346473464834649346503465134652346533465434655346563465734658346593466034661346623466334664346653466634667346683466934670346713467234673346743467534676346773467834679346803468134682346833468434685346863468734688346893469034691346923469334694346953469634697346983469934700347013470234703347043470534706347073470834709347103471134712347133471434715347163471734718347193472034721347223472334724347253472634727347283472934730347313473234733347343473534736347373473834739347403474134742347433474434745347463474734748347493475034751347523475334754347553475634757347583475934760347613476234763347643476534766347673476834769347703477134772347733477434775347763477734778347793478034781347823478334784347853478634787347883478934790347913479234793347943479534796347973479834799348003480134802348033480434805348063480734808348093481034811348123481334814348153481634817348183481934820348213482234823348243482534826348273482834829348303483134832348333483434835348363483734838348393484034841348423484334844348453484634847348483484934850348513485234853348543485534856348573485834859348603486134862348633486434865348663486734868348693487034871348723487334874348753487634877348783487934880348813488234883348843488534886348873488834889348903489134892348933489434895348963489734898348993490034901349023490334904349053490634907349083490934910349113491234913349143491534916349173491834919349203492134922349233492434925349263492734928349293493034931349323493334934349353493634937349383493934940349413494234943349443494534946349473494834949349503495134952349533495434955349563495734958349593496034961349623496334964349653496634967349683496934970349713497234973349743497534976349773497834979349803498134982349833498434985349863498734988349893499034991349923499334994349953499634997349983499935000350013500235003350043500535006350073500835009350103501135012350133501435015350163501735018350193502035021350223502335024350253502635027350283502935030350313503235033350343503535036350373503835039350403504135042350433504435045350463504735048350493505035051350523505335054350553505635057350583505935060350613506235063350643506535066350673506835069350703507135072350733507435075350763507735078350793508035081350823508335084350853508635087350883508935090350913509235093350943509535096350973509835099351003510135102351033510435105351063510735108351093511035111351123511335114351153511635117351183511935120351213512235123351243512535126351273512835129351303513135132351333513435135351363513735138351393514035141351423514335144351453514635147351483514935150351513515235153351543515535156351573515835159351603516135162351633516435165351663516735168351693517035171351723517335174351753517635177351783517935180351813518235183351843518535186351873518835189351903519135192351933519435195351963519735198351993520035201352023520335204352053520635207352083520935210352113521235213352143521535216352173521835219352203522135222352233522435225352263522735228352293523035231352323523335234352353523635237352383523935240352413524235243352443524535246352473524835249352503525135252352533525435255352563525735258352593526035261352623526335264352653526635267352683526935270352713527235273352743527535276352773527835279352803528135282352833528435285352863528735288352893529035291352923529335294352953529635297352983529935300353013530235303353043530535306353073530835309353103531135312353133531435315353163531735318353193532035321353223532335324353253532635327353283532935330353313533235333353343533535336353373533835339353403534135342353433534435345353463534735348353493535035351353523535335354353553535635357353583535935360353613536235363353643536535366353673536835369353703537135372353733537435375353763537735378353793538035381353823538335384353853538635387353883538935390353913539235393353943539535396353973539835399354003540135402354033540435405354063540735408354093541035411354123541335414354153541635417354183541935420354213542235423354243542535426354273542835429354303543135432354333543435435354363543735438354393544035441354423544335444354453544635447354483544935450354513545235453354543545535456354573545835459354603546135462354633546435465354663546735468354693547035471354723547335474354753547635477354783547935480354813548235483354843548535486354873548835489354903549135492354933549435495354963549735498354993550035501355023550335504355053550635507355083550935510355113551235513355143551535516355173551835519355203552135522355233552435525355263552735528355293553035531355323553335534355353553635537355383553935540355413554235543355443554535546355473554835549355503555135552355533555435555355563555735558355593556035561355623556335564355653556635567355683556935570355713557235573355743557535576355773557835579355803558135582355833558435585355863558735588355893559035591355923559335594355953559635597355983559935600356013560235603356043560535606356073560835609356103561135612356133561435615356163561735618356193562035621356223562335624356253562635627356283562935630356313563235633356343563535636356373563835639356403564135642356433564435645356463564735648356493565035651356523565335654356553565635657356583565935660356613566235663356643566535666356673566835669356703567135672356733567435675356763567735678356793568035681356823568335684356853568635687356883568935690356913569235693356943569535696356973569835699357003570135702357033570435705357063570735708357093571035711357123571335714357153571635717357183571935720357213572235723357243572535726357273572835729357303573135732357333573435735357363573735738357393574035741357423574335744357453574635747357483574935750357513575235753357543575535756357573575835759357603576135762357633576435765357663576735768357693577035771357723577335774357753577635777357783577935780357813578235783357843578535786357873578835789357903579135792357933579435795357963579735798357993580035801358023580335804358053580635807358083580935810358113581235813358143581535816358173581835819358203582135822358233582435825358263582735828358293583035831358323583335834358353583635837358383583935840358413584235843358443584535846358473584835849358503585135852358533585435855358563585735858358593586035861358623586335864358653586635867358683586935870358713587235873358743587535876358773587835879358803588135882358833588435885358863588735888358893589035891358923589335894358953589635897358983589935900359013590235903359043590535906359073590835909359103591135912359133591435915359163591735918359193592035921359223592335924359253592635927359283592935930359313593235933359343593535936359373593835939359403594135942359433594435945359463594735948359493595035951359523595335954359553595635957359583595935960359613596235963359643596535966359673596835969359703597135972359733597435975359763597735978359793598035981359823598335984359853598635987359883598935990359913599235993359943599535996359973599835999360003600136002360033600436005360063600736008360093601036011360123601336014360153601636017360183601936020360213602236023360243602536026360273602836029360303603136032360333603436035360363603736038360393604036041360423604336044360453604636047360483604936050360513605236053360543605536056360573605836059360603606136062360633606436065360663606736068360693607036071360723607336074360753607636077360783607936080360813608236083360843608536086360873608836089360903609136092360933609436095360963609736098360993610036101361023610336104361053610636107361083610936110361113611236113361143611536116361173611836119361203612136122361233612436125361263612736128361293613036131361323613336134361353613636137361383613936140361413614236143361443614536146361473614836149361503615136152361533615436155361563615736158361593616036161361623616336164361653616636167361683616936170361713617236173361743617536176361773617836179361803618136182361833618436185361863618736188361893619036191361923619336194 |
- \input texinfo
- @c -*-texinfo-*-
- @c %**start of header
- @setfilename guix.info
- @documentencoding UTF-8
- @settitle GNU Guix Reference Manual
- @c %**end of header
- @include version.texi
- @c Identifier of the OpenPGP key used to sign tarballs and such.
- @set OPENPGP-SIGNING-KEY-ID 27D586A4F8900854329FF09F1260E46482E63562
- @set OPENPGP-SIGNING-KEY-URL https://sv.gnu.org/people/viewgpg.php?user_id=127547
- @c Base URL for downloads.
- @set BASE-URL https://ftp.gnu.org/gnu/guix
- @c The official substitute server used by default.
- @set SUBSTITUTE-SERVER-1 ci.guix.gnu.org
- @set SUBSTITUTE-SERVER-2 bordeaux.guix.gnu.org
- @set SUBSTITUTE-URLS https://@value{SUBSTITUTE-SERVER-1} https://@value{SUBSTITUTE-SERVER-2}
- @copying
- Copyright @copyright{} 2012, 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, 2021 Chris Marusich@*
- Copyright @copyright{} 2016, 2017, 2018, 2019, 2020, 2021 Efraim Flashner@*
- Copyright @copyright{} 2016 John Darrington@*
- Copyright @copyright{} 2016, 2017 Nikita Gillmann@*
- Copyright @copyright{} 2016, 2017, 2018, 2019, 2020 Jan Nieuwenhuizen@*
- Copyright @copyright{} 2016, 2017, 2018, 2019, 2020, 2021 Julien Lepiller@*
- Copyright @copyright{} 2016 Alex ter Weele@*
- Copyright @copyright{} 2016, 2017, 2018, 2019, 2020, 2021 Christopher Baines@*
- Copyright @copyright{} 2017, 2018, 2019 Clément Lassieur@*
- Copyright @copyright{} 2017, 2018, 2020, 2021 Mathieu Othacehe@*
- Copyright @copyright{} 2017 Federico Beffa@*
- Copyright @copyright{} 2017, 2018 Carlo Zancanaro@*
- Copyright @copyright{} 2017 Thomas Danckaert@*
- Copyright @copyright{} 2017 humanitiesNerd@*
- Copyright @copyright{} 2017, 2021 Christine Lemmer-Webber@*
- Copyright @copyright{} 2017, 2018, 2019, 2020, 2021 Marius Bakke@*
- Copyright @copyright{} 2017, 2019, 2020 Hartmut Goebel@*
- Copyright @copyright{} 2017, 2019, 2020, 2021 Maxim Cournoyer@*
- Copyright @copyright{} 2017, 2018, 2019, 2020, 2021 Tobias Geerinckx-Rice@*
- Copyright @copyright{} 2017 George Clemmer@*
- Copyright @copyright{} 2017 Andy Wingo@*
- Copyright @copyright{} 2017, 2018, 2019, 2020 Arun Isaac@*
- Copyright @copyright{} 2017 nee@*
- Copyright @copyright{} 2018 Rutger Helling@*
- Copyright @copyright{} 2018, 2021 Oleg Pykhalov@*
- Copyright @copyright{} 2018 Mike Gerwitz@*
- Copyright @copyright{} 2018 Pierre-Antoine Rouby@*
- Copyright @copyright{} 2018, 2019 Gábor Boskovits@*
- Copyright @copyright{} 2018, 2019, 2020 Florian Pelz@*
- Copyright @copyright{} 2018 Laura Lazzati@*
- Copyright @copyright{} 2018 Alex Vong@*
- Copyright @copyright{} 2019 Josh Holland@*
- Copyright @copyright{} 2019, 2020 Diego Nicola Barbato@*
- Copyright @copyright{} 2019 Ivan Petkov@*
- Copyright @copyright{} 2019 Jakob L. Kreuze@*
- Copyright @copyright{} 2019 Kyle Andrews@*
- Copyright @copyright{} 2019 Alex Griffin@*
- Copyright @copyright{} 2019, 2020, 2021 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, 2021 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{} 2020 Edgar Vincent@*
- Copyright @copyright{} 2021 Maxime Devos@*
- Copyright @copyright{} 2021 B. Wilson@*
- Copyright @copyright{} 2021 Xinglu Chen@*
- Copyright @copyright{} 2021 Raghav Gururajan@*
- Copyright @copyright{} 2021 Domagoj Stolfa@*
- Copyright @copyright{} 2021 Hui Lu@*
- Copyright @copyright{} 2021 pukkamustard@*
- Copyright @copyright{} 2021 Alice Brenon@*
- Copyright @copyright{} 2021 Josselin Poiret@*
- 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} (@pxref{Translating Guix}).
- @menu
- * Introduction:: What is Guix about?
- * Installation:: Installing Guix.
- * System Installation:: Installing the whole operating system.
- * Getting Started:: Your first steps.
- * Package Management:: Package installation, upgrade, etc.
- * Channels:: Customizing the package collection.
- * Development:: Guix-aided software development.
- * Programming Interface:: Using Guix in Scheme.
- * Utilities:: Package management commands.
- * System Configuration:: Configuring the operating system.
- * 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 Servers:: One particular source of substitutes.
- * Substitute Server Authorization:: How to enable or disable substitutes.
- * Getting Substitutes from Other Servers:: Substitute diversity.
- * Substitute Authentication:: How Guix verifies substitutes.
- * Proxy Settings:: How to get substitutes via proxy.
- * Substitution Failure:: What happens when substitution fails.
- * On Trusting Binaries:: How can you trust that binary blob?
- Channels
- * Specifying Additional Channels:: Extending the package collection.
- * Using a Custom Guix Channel:: Using a customized Guix.
- * Replicating Guix:: Running the @emph{exact same} Guix.
- * Channel Authentication:: How Guix verifies what it fetches.
- * Channels with Substitutes:: Using channels with available substitutes.
- * Creating a Channel:: How to write your custom channel.
- * Package Modules in a Sub-directory:: Specifying the channel's package modules location.
- * Declaring Channel Dependencies:: How to depend on other channels.
- * Specifying Channel Authorizations:: Defining channel authors authorizations.
- * Primary URL:: Distinguishing mirror to original.
- * Writing Channel News:: Communicating information to channel's users.
- Development
- * Invoking guix 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 Packages
- * package Reference:: The package data type.
- * origin Reference:: The origin data type.
- Utilities
- * Invoking guix build:: Building packages from the command line.
- * Invoking guix edit:: Editing package definitions.
- * Invoking guix download:: Downloading a file and printing its hash.
- * Invoking guix hash:: Computing the cryptographic hash of a file.
- * Invoking guix import:: Importing package definitions.
- * Invoking guix refresh:: Updating package definitions.
- * Invoking guix style:: Styling package definitions.
- * Invoking guix lint:: Finding errors in package definitions.
- * Invoking guix size:: Profiling disk usage.
- * Invoking guix graph:: Visualizing the graph of packages.
- * Invoking guix publish:: Sharing substitutes.
- * Invoking guix challenge:: Challenging substitute servers.
- * Invoking guix copy:: Copying to and from a remote store.
- * Invoking guix container:: Process isolation.
- * Invoking guix weather:: Assessing substitute availability.
- * Invoking guix processes:: Listing client processes.
- Invoking @command{guix build}
- * Common Build Options:: Build options for most commands.
- * Package Transformation Options:: Creating variants of packages.
- * Additional Build Options:: Options specific to 'guix build'.
- * Debugging Build Failures:: Real life packaging experience.
- System Configuration
- * Using the Configuration System:: Customizing your GNU system.
- * operating-system Reference:: Detail of operating-system declarations.
- * File Systems:: Configuring file system mounts.
- * Mapped Devices:: Block device extra processing.
- * 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:: Cuirass and Laminar services.
- * Power Management Services:: Extending battery life.
- * Audio Services:: The MPD.
- * Virtualization Services:: Virtualization services.
- * Version Control Services:: Providing remote access to Git repositories.
- * Game Services:: Game servers.
- * PAM Mount Service:: Service to mount volumes when logging in.
- * Guix Services:: Services relating specifically to Guix.
- * Linux Services:: Services tied to the Linux kernel.
- * Hurd Services:: Services specific for a Hurd System.
- * Miscellaneous Services:: Other services.
- Defining Services
- * Service Composition:: The model for composing services.
- * Service Types and Services:: Types and services.
- * Service Reference:: API reference.
- * Shepherd Services:: A particular type of service.
- 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.
- @item powerpc64le-linux
- little-endian 64-bit Power ISA processors, Linux-Libre kernel. This
- includes POWER9 systems such as the
- @uref{https://www.fsf.org/news/talos-ii-mainboard-and-talos-ii-lite-mainboard-now-fsf-certified-to-respect-your-freedom,
- RYF Talos II mainboard}. This platform is available as a "technology
- preview": although it is supported, substitutes are not yet available
- from the build farm (@pxref{Substitutes}), and some packages may fail to
- build (@pxref{Tracking Bugs and Patches}). That said, the Guix
- community is actively working on improving this support, and now is a
- great time to try it and get involved!
- @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} and @code{powerpc64le-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-1}},
- @code{@value{SUBSTITUTE-SERVER-2}} or a mirror (@pxref{Substitutes}),
- authorize them:
- @example
- # guix archive --authorize < \
- ~root/.config/guix/current/share/guix/@value{SUBSTITUTE-SERVER-1}.pub
- # guix archive --authorize < \
- ~root/.config/guix/current/share/guix/@value{SUBSTITUTE-SERVER-2}.pub
- @end example
- @quotation Note
- If you do not enable substitutes, Guix will end up building
- @emph{everything} from source on your machine, making each installation
- and upgrade very expensive. @xref{On Trusting Binaries}, for a
- discussion of reasons why one might want do disable substitutes.
- @end quotation
- @item
- Each user may need to perform a few additional steps to make their Guix
- environment ready for use, @pxref{Application Setup}.
- @end enumerate
- Voilà, the installation is complete!
- You can confirm that Guix is working by installing a sample package into
- the root profile:
- @example
- # guix install hello
- @end example
- The binary installation tarball can be (re)produced and verified simply
- by running the following command in the Guix source tree:
- @example
- make guix-binary.@var{system}.tar.xz
- @end example
- @noindent
- ...@: which, in turn, runs:
- @example
- guix pack -s @var{system} --localstatedir \
- --profile-name=current-guix guix
- @end example
- @xref{Invoking guix pack}, for more info on this handy tool.
- @node Requirements
- @section Requirements
- This section lists requirements when building Guix from source. The
- build procedure for Guix is the same as for other GNU software, and is
- not covered here. Please see the files @file{README} and @file{INSTALL}
- in the Guix source tree for additional details.
- @cindex official website
- GNU Guix is available for download from its website at
- @url{https://www.gnu.org/software/guix/}.
- GNU Guix depends on the following packages:
- @itemize
- @item @url{https://gnu.org/software/guile/, GNU Guile}, version 3.0.x;
- @item @url{https://notabug.org/cwebber/guile-gcrypt, Guile-Gcrypt}, version
- 0.1.0 or later;
- @item
- @uref{https://gnutls.org/, GnuTLS}, specifically its Guile bindings
- (@pxref{Guile Preparations, how to install the GnuTLS bindings for
- Guile,, gnutls-guile, GnuTLS-Guile});
- @item
- @uref{https://notabug.org/guile-sqlite3/guile-sqlite3, Guile-SQLite3}, version 0.1.0
- or later;
- @item @uref{https://notabug.org/guile-zlib/guile-zlib, Guile-zlib},
- version 0.1.0 or later;
- @item @uref{https://notabug.org/guile-lzlib/guile-lzlib, Guile-lzlib};
- @item @uref{https://www.nongnu.org/guile-avahi/, Guile-Avahi};
- @item
- @uref{https://gitlab.com/guile-git/guile-git, Guile-Git}, version 0.5.0
- or later;
- @item @uref{https://savannah.nongnu.org/projects/guile-json/, Guile-JSON}
- 4.3.0 or later;
- @item @url{https://www.gnu.org/software/make/, GNU Make}.
- @end itemize
- The following dependencies are optional:
- @itemize
- @item
- @c Note: We need at least 0.13.0 for #:nodelay.
- Support for build offloading (@pxref{Daemon Offload Setup}) and
- @command{guix copy} (@pxref{Invoking guix copy}) depends on
- @uref{https://github.com/artyom-poptsov/guile-ssh, Guile-SSH},
- version 0.13.0 or later.
- @item
- @uref{https://notabug.org/guile-zstd/guile-zstd, Guile-zstd}, for zstd
- compression and decompression in @command{guix publish} and for
- substitutes (@pxref{Invoking guix publish}).
- @item
- @uref{https://ngyro.com/software/guile-semver.html, Guile-Semver} for
- the @code{crate} importer (@pxref{Invoking guix import}).
- @item
- @uref{https://www.nongnu.org/guile-lib/doc/ref/htmlprag/, Guile-Lib} for
- the @code{go} importer (@pxref{Invoking guix import}) and for some of
- the ``updaters'' (@pxref{Invoking guix refresh}).
- @item
- When @url{http://www.bzip.org, libbz2} is available,
- @command{guix-daemon} can use it to compress build logs.
- @end itemize
- Unless @option{--disable-daemon} was passed to @command{configure}, the
- following packages are also needed:
- @itemize
- @item @url{https://gnupg.org/, GNU libgcrypt};
- @item @url{https://sqlite.org, SQLite 3};
- @item @url{https://gcc.gnu.org, GCC's g++}, with support for the
- C++11 standard.
- @end itemize
- @cindex state directory
- When configuring Guix on a system that already has a Guix installation,
- be sure to specify the same state directory as the existing installation
- using the @option{--localstatedir} option of the @command{configure}
- script (@pxref{Directory Variables, @code{localstatedir},, standards,
- GNU Coding Standards}). Usually, this @var{localstatedir} option is
- set to the value @file{/var}. The @command{configure} script protects
- against unintended misconfiguration of @var{localstatedir} so you do not
- inadvertently corrupt your store (@pxref{The Store}).
- @node Running the Test Suite
- @section Running the Test Suite
- @cindex test suite
- After a successful @command{configure} and @code{make} run, it is a good
- idea to run the test suite. It can help catch issues with the setup or
- environment, or bugs in Guix itself---and really, reporting test
- failures is a good way to help improve the software. To run the test
- suite, type:
- @example
- make check
- @end example
- Test cases can run in parallel: you can use the @code{-j} option of
- GNU@tie{}make to speed things up. The first run may take a few minutes
- on a recent machine; subsequent runs will be faster because the store
- that is created for test purposes will already have various things in
- cache.
- It is also possible to run a subset of the tests by defining the
- @code{TESTS} makefile variable as in this example:
- @example
- make check TESTS="tests/store.scm tests/cpio.scm"
- @end example
- By default, tests results are displayed at a file level. In order to
- see the details of every individual test cases, it is possible to define
- the @code{SCM_LOG_DRIVER_FLAGS} makefile variable as in this example:
- @example
- make check TESTS="tests/base64.scm" SCM_LOG_DRIVER_FLAGS="--brief=no"
- @end example
- The underlying SRFI 64 custom Automake test driver used for the 'check'
- test suite (located at @file{build-aux/test-driver.scm}) also allows
- selecting which test cases to run at a finer level, via its
- @option{--select} and @option{--exclude} options. Here's an example, to
- run all the test cases from the @file{tests/packages.scm} test file
- whose names start with ``transaction-upgrade-entry'':
- @example
- export SCM_LOG_DRIVER_FLAGS="--select=^transaction-upgrade-entry"
- make check TESTS="tests/packages.scm"
- @end example
- Those wishing to inspect the results of failed tests directly from the
- command line can add the @option{--errors-only=yes} option to the
- @code{SCM_LOG_DRIVER_FLAGS} makefile variable and set the @code{VERBOSE}
- Automake makefile variable, as in:
- @example
- make check SCM_LOG_DRIVER_FLAGS="--brief=no --errors-only=yes" VERBOSE=1
- @end example
- The @option{--show-duration=yes} option can be used to print the
- duration of the individual test cases, when used in combination with
- @option{--brief=no}:
- @example
- make check SCM_LOG_DRIVER_FLAGS="--brief=no --show-duration=yes"
- @end example
- @xref{Parallel Test Harness,,,automake,GNU Automake} for more
- information about the Automake Parallel Test Harness.
- Upon failure, please email @email{bug-guix@@gnu.org} and attach the
- @file{test-suite.log} file. Please specify the Guix version being used
- as well as version numbers of the dependencies (@pxref{Requirements}) in
- your message.
- Guix also comes with a whole-system test suite that tests complete
- Guix System instances. It can only run on systems where
- Guix is already installed, using:
- @example
- make check-system
- @end example
- @noindent
- or, again, by defining @code{TESTS} to select a subset of tests to run:
- @example
- make check-system TESTS="basic mcron"
- @end example
- These system tests are defined in the @code{(gnu tests @dots{})}
- modules. They work by running the operating systems under test with
- lightweight instrumentation in a virtual machine (VM). They can be
- computationally intensive or rather cheap, depending on whether
- substitutes are available for their dependencies (@pxref{Substitutes}).
- Some of them require a lot of storage space to hold VM images.
- Again in case of test failures, please send @email{bug-guix@@gnu.org}
- all the details.
- @node Setting Up the Daemon
- @section Setting Up the Daemon
- @cindex daemon
- Operations such as building a package or running the garbage collector
- are all performed by a specialized process, the @dfn{build daemon}, on
- behalf of clients. Only the daemon may access the store and its
- associated database. Thus, any operation that manipulates the store
- goes through the daemon. For instance, command-line tools such as
- @command{guix package} and @command{guix build} communicate with the
- daemon (@i{via} remote procedure calls) to instruct it what to do.
- The following sections explain how to prepare the build daemon's
- environment. See also @ref{Substitutes}, for information on how to allow
- the daemon to download pre-built binaries.
- @menu
- * Build Environment Setup:: Preparing the isolated build environment.
- * Daemon Offload Setup:: Offloading builds to remote machines.
- * SELinux Support:: Using an SELinux policy for the daemon.
- @end menu
- @node Build Environment Setup
- @subsection Build Environment Setup
- @cindex build environment
- In a standard multi-user setup, Guix and its daemon---the
- @command{guix-daemon} program---are installed by the system
- administrator; @file{/gnu/store} is owned by @code{root} and
- @command{guix-daemon} runs as @code{root}. Unprivileged users may use
- Guix tools to build packages or otherwise access the store, and the
- daemon will do it on their behalf, ensuring that the store is kept in a
- consistent state, and allowing built packages to be shared among users.
- @cindex build users
- When @command{guix-daemon} runs as @code{root}, you may not want package
- build processes themselves to run as @code{root} too, for obvious
- security reasons. To avoid that, a special pool of @dfn{build users}
- should be created for use by build processes started by the daemon.
- These build users need not have a shell and a home directory: they will
- just be used when the daemon drops @code{root} privileges in build
- processes. Having several such users allows the daemon to launch
- distinct build processes under separate UIDs, which guarantees that they
- do not interfere with each other---an essential feature since builds are
- regarded as pure functions (@pxref{Introduction}).
- On a GNU/Linux system, a build user pool may be created like this (using
- Bash syntax and the @code{shadow} commands):
- @c See https://lists.gnu.org/archive/html/bug-guix/2013-01/msg00239.html
- @c for why `-G' is needed.
- @example
- # groupadd --system guixbuild
- # for i in $(seq -w 1 10);
- do
- useradd -g guixbuild -G guixbuild \
- -d /var/empty -s $(which nologin) \
- -c "Guix build user $i" --system \
- guixbuilder$i;
- done
- @end example
- @noindent
- The number of build users determines how many build jobs may run in
- parallel, as specified by the @option{--max-jobs} option
- (@pxref{Invoking guix-daemon, @option{--max-jobs}}). To use
- @command{guix system vm} and related commands, you may need to add the
- build users to the @code{kvm} group so they can access @file{/dev/kvm},
- using @code{-G guixbuild,kvm} instead of @code{-G guixbuild}
- (@pxref{Invoking guix system}).
- The @code{guix-daemon} program may then be run as @code{root} with the
- following command@footnote{If your machine uses the systemd init system,
- dropping the @file{@var{prefix}/lib/systemd/system/guix-daemon.service}
- file in @file{/etc/systemd/system} will ensure that
- @command{guix-daemon} is automatically started. Similarly, if your
- machine uses the Upstart init system, drop the
- @file{@var{prefix}/lib/upstart/system/guix-daemon.conf}
- file in @file{/etc/init}.}:
- @example
- # guix-daemon --build-users-group=guixbuild
- @end example
- @cindex chroot
- @noindent
- This way, the daemon starts build processes in a chroot, under one of
- the @code{guixbuilder} users. On GNU/Linux, by default, the chroot
- environment contains nothing but:
- @c Keep this list in sync with libstore/build.cc! -----------------------
- @itemize
- @item
- a minimal @code{/dev} directory, created mostly independently from the
- host @code{/dev}@footnote{``Mostly'', because while the set of files
- that appear in the chroot's @code{/dev} is fixed, most of these files
- can only be created if the host has them.};
- @item
- the @code{/proc} directory; it only shows the processes of the container
- since a separate PID name space is used;
- @item
- @file{/etc/passwd} with an entry for the current user and an entry for
- user @file{nobody};
- @item
- @file{/etc/group} with an entry for the user's group;
- @item
- @file{/etc/hosts} with an entry that maps @code{localhost} to
- @code{127.0.0.1};
- @item
- a writable @file{/tmp} directory.
- @end itemize
- 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 preferable to define socket rules for only this label.
- @item
- @code{guix gc} cannot access arbitrary links to profiles. By design,
- the file label of the destination of a symlink is independent of the
- file label of the link itself. Although all profiles under
- $localstatedir are labelled, the links to these profiles inherit the
- label of the directory they are in. For links in the user’s home
- directory this will be @code{user_home_t}. But for links from the root
- user’s home directory, or @file{/tmp}, or the HTTP server’s working
- directory, etc, this won’t work. @code{guix gc} would be prevented from
- reading and following these links.
- @item
- The daemon’s feature to listen for TCP connections might no longer work.
- This might require extra rules, because SELinux treats network sockets
- differently from files.
- @item
- Currently all files with a name matching the regular expression
- @code{/gnu/store/.+-(guix-.+|profile)/bin/guix-daemon} are assigned the
- label @code{guix_daemon_exec_t}; this means that @emph{any} file with
- that name in any profile would be permitted to run in the
- @code{guix_daemon_t} domain. This is not ideal. An attacker could
- build a package that provides this executable and convince a user to
- install and run it, which lifts it into the @code{guix_daemon_t} domain.
- At that point SELinux could not prevent it from accessing files that are
- allowed for processes in that domain.
- You will need to relabel the store directory after all upgrades to
- @file{guix-daemon}, such as after running @code{guix pull}. Assuming the
- store is in @file{/gnu}, you can do this with @code{restorecon -vR /gnu},
- or by other means provided by your operating system.
- We could generate a much more restrictive policy at installation time,
- so that only the @emph{exact} file name of the currently installed
- @code{guix-daemon} executable would be labelled with
- @code{guix_daemon_exec_t}, instead of using a broad regular expression.
- The downside is that root would have to install or upgrade the policy at
- installation time whenever the Guix package that provides the
- effectively running @code{guix-daemon} executable is upgraded.
- @end enumerate
- @node Invoking guix-daemon
- @section Invoking @command{guix-daemon}
- The @command{guix-daemon} program implements all the functionality to
- access the store. This includes launching build processes, running the
- garbage collector, querying the availability of a build result, etc. It
- is normally run as @code{root} like this:
- @example
- # guix-daemon --build-users-group=guixbuild
- @end example
- @noindent
- For details on how to set it up, @pxref{Setting Up the Daemon}.
- @cindex chroot
- @cindex container, build environment
- @cindex build environment
- @cindex reproducible builds
- By default, @command{guix-daemon} launches build processes under
- different UIDs, taken from the build group specified with
- @option{--build-users-group}. In addition, each build process is run in a
- chroot environment that only contains the subset of the store that the
- build process depends on, as specified by its derivation
- (@pxref{Programming Interface, derivation}), plus a set of specific
- system directories. By default, the latter contains @file{/dev} and
- @file{/dev/pts}. Furthermore, on GNU/Linux, the build environment is a
- @dfn{container}: in addition to having its own file system tree, it has
- a separate mount name space, its own PID name space, network name space,
- etc. This helps achieve reproducible builds (@pxref{Features}).
- When the daemon performs a build on behalf of the user, it creates a
- build directory under @file{/tmp} or under the directory specified by
- its @env{TMPDIR} environment variable. This directory is shared with
- the container for the duration of the build, though within the container,
- the build tree is always called @file{/tmp/guix-build-@var{name}.drv-0}.
- The build directory is automatically deleted upon completion, unless the
- build failed and the client specified @option{--keep-failed}
- (@pxref{Common Build Options, @option{--keep-failed}}).
- The daemon listens for connections and spawns one sub-process for each session
- started by a client (one of the @command{guix} sub-commands). The
- @command{guix processes} command allows you to get an overview of the activity
- on your system by viewing each of the active sessions and clients.
- @xref{Invoking guix processes}, for more information.
- The following command-line options are supported:
- @table @code
- @item --build-users-group=@var{group}
- Take users from @var{group} to run build processes (@pxref{Setting Up
- the Daemon, build users}).
- @item --no-substitutes
- @cindex substitutes
- Do not use substitutes for build products. That is, always build things
- locally instead of allowing downloads of pre-built binaries
- (@pxref{Substitutes}).
- When the daemon runs with @option{--no-substitutes}, clients can still
- explicitly enable substitution @i{via} the @code{set-build-options}
- remote procedure call (@pxref{The Store}).
- @anchor{daemon-substitute-urls}
- @item --substitute-urls=@var{urls}
- Consider @var{urls} the default whitespace-separated list of substitute
- source URLs. When this option is omitted,
- @indicateurl{@value{SUBSTITUTE-URLS}} is used.
- This means that substitutes may be downloaded from @var{urls}, as long
- as they are signed by a trusted signature (@pxref{Substitutes}).
- @xref{Getting Substitutes from Other Servers}, for more information on
- how to configure the daemon to get substitutes from other servers.
- @cindex offloading
- @item --no-offload
- Do not use offload builds to other machines (@pxref{Daemon Offload
- Setup}). That is, always build things locally instead of offloading
- builds to remote machines.
- @item --cache-failures
- Cache build failures. By default, only successful builds are cached.
- When this option is used, @command{guix gc --list-failures} can be used
- to query the set of store items marked as failed; @command{guix gc
- --clear-failures} removes store items from the set of cached failures.
- @xref{Invoking guix gc}.
- @item --cores=@var{n}
- @itemx -c @var{n}
- Use @var{n} CPU cores to build each derivation; @code{0} means as many
- as available.
- The default value is @code{0}, but it may be overridden by clients, such
- as the @option{--cores} option of @command{guix build} (@pxref{Invoking
- guix build}).
- The effect is to define the @env{NIX_BUILD_CORES} environment variable
- in the build process, which can then use it to exploit internal
- parallelism---for instance, by running @code{make -j$NIX_BUILD_CORES}.
- @item --max-jobs=@var{n}
- @itemx -M @var{n}
- Allow at most @var{n} build jobs in parallel. The default value is
- @code{1}. Setting it to @code{0} means that no builds will be performed
- locally; instead, the daemon will offload builds (@pxref{Daemon Offload
- Setup}), or simply fail.
- @item --max-silent-time=@var{seconds}
- When the build or substitution process remains silent for more than
- @var{seconds}, terminate it and report a build failure.
- The default value is @code{0}, which disables the timeout.
- The value specified here can be overridden by clients (@pxref{Common
- Build Options, @option{--max-silent-time}}).
- @item --timeout=@var{seconds}
- Likewise, when the build or substitution process lasts for more than
- @var{seconds}, terminate it and report a build failure.
- The default value is @code{0}, which disables the timeout.
- The value specified here can be overridden by clients (@pxref{Common
- Build Options, @option{--timeout}}).
- @item --rounds=@var{N}
- Build each derivation @var{n} times in a row, and raise an error if
- consecutive build results are not bit-for-bit identical. Note that this
- setting can be overridden by clients such as @command{guix build}
- (@pxref{Invoking guix build}).
- When used in conjunction with @option{--keep-failed}, the differing
- output is kept in the store, under @file{/gnu/store/@dots{}-check}.
- This makes it easy to look for differences between the two results.
- @item --debug
- Produce debugging output.
- This is useful to debug daemon start-up issues, but then it may be
- overridden by clients, for example the @option{--verbosity} option of
- @command{guix build} (@pxref{Invoking guix build}).
- @item --chroot-directory=@var{dir}
- Add @var{dir} to the build chroot.
- Doing this may change the result of build processes---for instance if
- they use optional dependencies found in @var{dir} when it is available,
- and not otherwise. For that reason, it is not recommended to do so.
- Instead, make sure that each derivation declares all the inputs that it
- needs.
- @item --disable-chroot
- Disable chroot builds.
- Using this option is not recommended since, again, it would allow build
- processes to gain access to undeclared dependencies. It is necessary,
- though, when @command{guix-daemon} is running under an unprivileged user
- account.
- @item --log-compression=@var{type}
- Compress build logs according to @var{type}, one of @code{gzip},
- @code{bzip2}, or @code{none}.
- Unless @option{--lose-logs} is used, all the build logs are kept in the
- @var{localstatedir}. To save space, the daemon automatically compresses
- them with 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{font-ghostscript}, @code{font-dejavu}, and
- @code{font-gnu-freefont}.
- @cindex @code{fc-cache}
- @cindex font cache
- Once you have installed or removed fonts, or when you notice an
- application that does not find fonts, you may need to install Fontconfig
- and to force an update of its font cache by running:
- @example
- guix install fontconfig
- fc-cache -rv
- @end example
- To display text written in Chinese languages, Japanese, or Korean in
- graphical applications, consider installing
- @code{font-adobe-source-han-sans} or @code{font-wqy-zenhei}. The former
- has multiple outputs, one per language family (@pxref{Packages with
- Multiple Outputs}). For instance, the following command installs fonts
- for Chinese languages:
- @example
- guix install font-adobe-source-han-sans:cn
- @end example
- @cindex @code{xterm}
- Older programs such as @command{xterm} do not use Fontconfig and instead
- rely on server-side font rendering. Such programs require to specify a
- full name of a font using XLFD (X Logical Font Description), like this:
- @example
- -*-dejavu sans-medium-r-normal-*-*-100-*-*-*-*-*-1
- @end example
- To be able to use such full names for the TrueType fonts installed in
- your Guix profile, you need to extend the font path of the X server:
- @c Note: 'xset' does not accept symlinks so the trick below arranges to
- @c get at the real directory. See <https://bugs.gnu.org/30655>.
- @example
- xset +fp $(dirname $(readlink -f ~/.guix-profile/share/fonts/truetype/fonts.dir))
- @end example
- @cindex @code{xlsfonts}
- After that, you can run @code{xlsfonts} (from @code{xlsfonts} package)
- to make sure your TrueType fonts are listed there.
- @subsection X.509 Certificates
- @cindex @code{nss-certs}
- The @code{nss-certs} package provides X.509 certificates, which allow
- programs to authenticate Web servers accessed over HTTPS.
- When using Guix on a foreign distro, you can install this package and
- define the relevant environment variables so that packages know where to
- look for certificates. @xref{X.509 Certificates}, for detailed
- information.
- @subsection Emacs Packages
- @cindex @code{emacs}
- When you install Emacs packages with Guix, the Elisp files are placed
- under the @file{share/emacs/site-lisp/} directory of the profile in
- which they are installed. The Elisp libraries are made available to
- Emacs through the @env{EMACSLOADPATH} environment variable, which is
- set when installing Emacs itself.
- Additionally, autoload definitions are automatically evaluated at the
- initialization of Emacs, by the Guix-specific
- @code{guix-emacs-autoload-packages} procedure. If, for some reason, you
- want to avoid auto-loading the Emacs packages installed with Guix, you
- can do so by running Emacs with the @option{--no-site-file} option
- (@pxref{Init File,,, emacs, The GNU Emacs Manual}).
- @node Upgrading Guix
- @section Upgrading Guix
- @cindex Upgrading Guix, on a foreign distro
- To upgrade Guix, run:
- @example
- guix pull
- @end example
- @xref{Invoking guix pull}, for more information.
- @cindex upgrading Guix for the root user, on a foreign distro
- @cindex upgrading the Guix daemon, on a foreign distro
- @cindex @command{guix pull} for the root user, on a foreign distro
- On a foreign distro, you can upgrade the build daemon by running:
- @example
- sudo -i guix pull
- @end example
- @noindent
- followed by (assuming your distro uses the systemd service management
- tool):
- @example
- systemctl restart guix-daemon.service
- @end example
- On Guix System, upgrading the daemon is achieved by reconfiguring the
- system (@pxref{Invoking guix system, @code{guix system reconfigure}}).
- @c TODO What else?
- @c *********************************************************************
- @node System Installation
- @chapter System Installation
- @cindex installing Guix System
- @cindex Guix System, installation
- This section explains how to install Guix System
- on a machine. Guix, as a package manager, can
- also be installed on top of a running GNU/Linux system,
- @pxref{Installation}.
- @ifinfo
- @quotation Note
- @c This paragraph is for people reading this from tty2 of the
- @c installation image.
- You are reading this documentation with an Info reader. For details on
- how to use it, hit the @key{RET} key (``return'' or ``enter'') on the
- link that follows: @pxref{Top, Info reader,, info-stnd, Stand-alone GNU
- Info}. Hit @kbd{l} afterwards to come back here.
- Alternatively, run @command{info info} in another tty to keep the manual
- available.
- @end quotation
- @end ifinfo
- @menu
- * Limitations:: What you can expect.
- * Hardware Considerations:: Supported hardware.
- * USB Stick and DVD Installation:: Preparing the installation medium.
- * Preparing for Installation:: Networking, partitioning, etc.
- * Guided Graphical Installation:: Easy graphical installation.
- * Manual Installation:: Manual installation for wizards.
- * After System Installation:: When installation succeeded.
- * Installing Guix in a VM:: Guix System playground.
- * Building the Installation Image:: How this comes to be.
- @end menu
- @node Limitations
- @section Limitations
- We consider Guix System to be ready for a wide range of ``desktop'' and server
- use cases. The reliability guarantees it provides---transactional upgrades
- and rollbacks, reproducibility---make it a solid foundation.
- Nevertheless, before you proceed with the installation, be aware of the
- following noteworthy limitations applicable to version @value{VERSION}:
- @itemize
- @item
- More and more system services are provided (@pxref{Services}), but some
- may be missing.
- @item
- GNOME, Xfce, LXDE, and Enlightenment are available (@pxref{Desktop Services}),
- as well as a number of X11 window managers. However, KDE is currently
- missing.
- @end itemize
- More than a disclaimer, this is an invitation to report issues (and success
- stories!), and to join us in improving it. @xref{Contributing}, for more
- info.
- @node Hardware Considerations
- @section Hardware Considerations
- @cindex hardware support on Guix System
- GNU@tie{}Guix focuses on respecting the user's computing freedom. It
- builds around the kernel Linux-libre, which means that only hardware for
- which free software drivers and firmware exist is supported. Nowadays,
- a wide range of off-the-shelf hardware is supported on
- GNU/Linux-libre---from keyboards to graphics cards to scanners and
- Ethernet controllers. Unfortunately, there are still areas where
- hardware vendors deny users control over their own computing, and such
- hardware is not supported on Guix System.
- @cindex WiFi, hardware support
- One of the main areas where free drivers or firmware are lacking is WiFi
- devices. WiFi devices known to work include those using Atheros chips
- (AR9271 and AR7010), which corresponds to the @code{ath9k} Linux-libre
- driver, and those using Broadcom/AirForce chips (BCM43xx with
- Wireless-Core Revision 5), which corresponds to the @code{b43-open}
- Linux-libre driver. Free firmware exists for both and is available
- out-of-the-box on Guix System, as part of @code{%base-firmware}
- (@pxref{operating-system Reference, @code{firmware}}).
- @cindex RYF, Respects Your Freedom
- The @uref{https://www.fsf.org/, Free Software Foundation} runs
- @uref{https://www.fsf.org/ryf, @dfn{Respects Your Freedom}} (RYF), a
- certification program for hardware products that respect your freedom
- and your privacy and ensure that you have control over your device. We
- encourage you to check the list of RYF-certified devices.
- Another useful resource is the @uref{https://www.h-node.org/, H-Node}
- web site. It contains a catalog of hardware devices with information
- about their support in GNU/Linux.
- @node USB Stick and DVD Installation
- @section USB Stick and DVD Installation
- An ISO-9660 installation image that can be written to a USB stick or
- burnt to a DVD can be downloaded from
- @indicateurl{@value{BASE-URL}/guix-system-install-@value{VERSION}.x86_64-linux.iso},
- where you can replace @code{x86_64-linux} with one of:
- @table @code
- @item x86_64-linux
- for a GNU/Linux system on Intel/AMD-compatible 64-bit CPUs;
- @item i686-linux
- for a 32-bit GNU/Linux system on Intel-compatible CPUs.
- @end table
- @c start duplication of authentication part from ``Binary Installation''
- Make sure to download the associated @file{.sig} file and to verify the
- authenticity of the image against it, along these lines:
- @example
- $ wget @value{BASE-URL}/guix-system-install-@value{VERSION}.x86_64-linux.iso.sig
- $ gpg --verify guix-system-install-@value{VERSION}.x86_64-linux.iso.sig
- @end example
- If that command fails because you do not have the required public key,
- then run this command to import it:
- @example
- $ wget @value{OPENPGP-SIGNING-KEY-URL} \
- -qO - | gpg --import -
- @end example
- @noindent
- and rerun the @code{gpg --verify} command.
- Take note that a warning like ``This key is not certified with a trusted
- signature!'' is normal.
- @c end duplication
- This image contains the tools necessary for an installation.
- It is meant to be copied @emph{as is} to a large-enough USB stick or DVD.
- @unnumberedsubsec Copying to a USB Stick
- Insert a USB stick of 1@tie{}GiB or more into your machine, and determine
- its device name. Assuming that the USB stick is known as @file{/dev/sdX},
- copy the image with:
- @example
- dd if=guix-system-install-@value{VERSION}.x86_64-linux.iso of=/dev/sdX status=progress
- sync
- @end example
- Access to @file{/dev/sdX} usually requires root privileges.
- @unnumberedsubsec Burning on a DVD
- Insert a blank DVD into your machine, and determine
- its device name. Assuming that the DVD drive is known as @file{/dev/srX},
- copy the image with:
- @example
- growisofs -dvd-compat -Z /dev/srX=guix-system-install-@value{VERSION}.x86_64-linux.iso
- @end example
- Access to @file{/dev/srX} usually requires root privileges.
- @unnumberedsubsec Booting
- Once this is done, you should be able to reboot the system and boot from
- the USB stick or DVD@. The latter usually requires you to get in the
- BIOS or UEFI boot menu, where you can choose to boot from the USB stick.
- In order to boot from Libreboot, switch to the command mode by pressing
- the @kbd{c} key and type @command{search_grub usb}.
- @xref{Installing Guix in a VM}, if, instead, you would like to install
- Guix System in a virtual machine (VM).
- @node Preparing for Installation
- @section Preparing for Installation
- Once you have booted, you can use the guided graphical installer, which makes
- it easy to get started (@pxref{Guided Graphical Installation}). Alternatively,
- if you are already familiar with GNU/Linux and if you want more control than
- what the graphical installer provides, you can choose the ``manual''
- installation process (@pxref{Manual Installation}).
- The graphical installer is available on TTY1. You can obtain root shells on
- TTYs 3 to 6 by hitting @kbd{ctrl-alt-f3}, @kbd{ctrl-alt-f4}, etc. TTY2 shows
- this documentation and you can reach it with @kbd{ctrl-alt-f2}. Documentation
- is browsable using the Info reader commands (@pxref{Top,,, info-stnd,
- Stand-alone GNU Info}). The installation system runs the GPM mouse daemon,
- which allows you to select text with the left mouse button and to paste it
- with the middle button.
- @quotation Note
- Installation requires access to the Internet so that any missing
- dependencies of your system configuration can be downloaded. See the
- ``Networking'' section below.
- @end quotation
- @node Guided Graphical Installation
- @section Guided Graphical Installation
- The graphical installer is a text-based user interface. It will guide you,
- with dialog boxes, through the steps needed to install GNU@tie{}Guix System.
- The first dialog boxes allow you to set up the system as you use it during the
- installation: you can choose the language, keyboard layout, and set up
- networking, which will be used during the installation. The image below shows
- the networking dialog.
- @image{images/installer-network,5in,, networking setup with the graphical installer}
- Later steps allow you to partition your hard disk, as shown in the image
- below, to choose whether or not to use encrypted file systems, to enter the
- host name and root password, and to create an additional account, among other
- things.
- @image{images/installer-partitions,5in,, partitioning with the graphical installer}
- Note that, at any time, the installer allows you to exit the current
- installation step and resume at a previous step, as show in the image below.
- @image{images/installer-resume,5in,, resuming the installation process}
- Once you're done, the installer produces an operating system configuration and
- displays it (@pxref{Using the Configuration System}). At that point you can
- hit ``OK'' and installation will proceed. On success, you can reboot into the
- new system and enjoy. @xref{After System Installation}, for what's next!
- @node Manual Installation
- @section Manual Installation
- This section describes how you would ``manually'' install GNU@tie{}Guix System
- on your machine. This option requires familiarity with GNU/Linux, with the
- shell, and with common administration tools. If you think this is not for
- you, consider using the guided graphical installer (@pxref{Guided Graphical
- Installation}).
- The installation system provides root shells on TTYs 3 to 6; press
- @kbd{ctrl-alt-f3}, @kbd{ctrl-alt-f4}, and so on to reach them. It includes
- many common tools needed to install the system. But it is also a full-blown
- Guix System, which means that you can install additional packages, should you
- need it, using @command{guix package} (@pxref{Invoking guix package}).
- @menu
- * Keyboard Layout and Networking and Partitioning:: Initial setup.
- * Proceeding with the Installation:: Installing.
- @end menu
- @node Keyboard Layout and Networking and Partitioning
- @subsection Keyboard Layout, Networking, and Partitioning
- Before you can install the system, you may want to adjust the keyboard layout,
- set up networking, and partition your target hard disk. This section will
- guide you through this.
- @subsubsection Keyboard Layout
- @cindex keyboard layout
- The installation image uses the US qwerty keyboard layout. If you want
- to change it, you can use the @command{loadkeys} command. For example,
- the following command selects the Dvorak keyboard layout:
- @example
- loadkeys dvorak
- @end example
- See the files under @file{/run/current-system/profile/share/keymaps} for
- a list of available keyboard layouts. Run @command{man loadkeys} for
- more information.
- @subsubsection Networking
- Run the following command to see what your network interfaces are called:
- @example
- ifconfig -a
- @end example
- @noindent
- @dots{} or, using the GNU/Linux-specific @command{ip} command:
- @example
- ip address
- @end example
- @c https://cgit.freedesktop.org/systemd/systemd/tree/src/udev/udev-builtin-net_id.c#n20
- Wired interfaces have a name starting with @samp{e}; for example, the
- interface corresponding to the first on-board Ethernet controller is
- called @samp{eno1}. Wireless interfaces have a name starting with
- @samp{w}, like @samp{w1p2s0}.
- @table @asis
- @item Wired connection
- To configure a wired network run the following command, substituting
- @var{interface} with the name of the wired interface you want to use.
- @example
- ifconfig @var{interface} up
- @end example
- @noindent
- @dots{} or, using the GNU/Linux-specific @command{ip} command:
- @example
- ip link set @var{interface} up
- @end example
- @item Wireless connection
- @cindex wireless
- @cindex WiFi
- To configure wireless networking, you can create a configuration file
- for the @command{wpa_supplicant} configuration tool (its location is not
- important) using one of the available text editors such as
- @command{nano}:
- @example
- nano wpa_supplicant.conf
- @end example
- As an example, the following stanza can go to this file and will work
- for many wireless networks, provided you give the actual SSID and
- passphrase for the network you are connecting to:
- @example
- network=@{
- ssid="@var{my-ssid}"
- key_mgmt=WPA-PSK
- psk="the network's secret passphrase"
- @}
- @end example
- Start the wireless service and run it in the background with the
- following command (substitute @var{interface} with the name of the
- network interface you want to use):
- @example
- wpa_supplicant -c wpa_supplicant.conf -i @var{interface} -B
- @end example
- Run @command{man wpa_supplicant} for more information.
- @end table
- @cindex DHCP
- At this point, you need to acquire an IP address. On a network where IP
- addresses are automatically assigned @i{via} DHCP, you can run:
- @example
- dhclient -v @var{interface}
- @end example
- Try to ping a server to see if networking is up and running:
- @example
- ping -c 3 gnu.org
- @end example
- Setting up network access is almost always a requirement because the
- image does not contain all the software and tools that may be needed.
- @cindex proxy, during system installation
- If you need HTTP and HTTPS access to go through a proxy, run the
- following command:
- @example
- herd set-http-proxy guix-daemon @var{URL}
- @end example
- @noindent
- where @var{URL} is the proxy URL, for example
- @code{http://example.org:8118}.
- @cindex installing over SSH
- If you want to, you can continue the installation remotely by starting
- an SSH server:
- @example
- herd start ssh-daemon
- @end example
- Make sure to either set a password with @command{passwd}, or configure
- OpenSSH public key authentication before logging in.
- @subsubsection Disk Partitioning
- Unless this has already been done, the next step is to partition, and
- then format the target partition(s).
- The installation image includes several partitioning tools, including
- Parted (@pxref{Overview,,, parted, GNU Parted User Manual}),
- @command{fdisk}, and @command{cfdisk}. Run it and set up your disk with
- the partition layout you want:
- @example
- cfdisk
- @end example
- If your disk uses the GUID Partition Table (GPT) format and you plan to
- install BIOS-based GRUB (which is the default), make sure a BIOS Boot
- Partition is available (@pxref{BIOS installation,,, grub, GNU GRUB
- manual}).
- @cindex EFI, installation
- @cindex UEFI, installation
- @cindex ESP, EFI system partition
- If you instead wish to use EFI-based GRUB, a FAT32 @dfn{EFI System Partition}
- (ESP) is required. This partition can be mounted at @file{/boot/efi} for
- instance and must have the @code{esp} flag set. E.g., for @command{parted}:
- @example
- parted /dev/sda set 1 esp on
- @end example
- @quotation Note
- @vindex grub-bootloader
- @vindex grub-efi-bootloader
- Unsure whether to use EFI- or BIOS-based GRUB? If the directory
- @file{/sys/firmware/efi} exists in the installation image, then you should
- probably perform an EFI installation, using @code{grub-efi-bootloader}.
- Otherwise you should use the BIOS-based GRUB, known as
- @code{grub-bootloader}. @xref{Bootloader Configuration}, for more info on
- bootloaders.
- @end quotation
- Once you are done partitioning the target hard disk drive, you have to
- create a file system on the relevant partition(s)@footnote{Currently
- Guix System only supports ext4, btrfs, JFS, 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 mg (an Emacs clone), and
- nvi (a clone of the original BSD @command{vi} editor).
- We strongly recommend storing that file on the target root file system, say,
- as @file{/mnt/etc/config.scm}. Failing to do that, you will have lost your
- configuration file once you have rebooted into the newly-installed system.
- @xref{Using the Configuration System}, for an overview of the
- configuration file. The example configurations discussed in that
- section are available under @file{/etc/configuration} in the
- installation image. Thus, to get started with a system configuration
- providing a graphical display server (a ``desktop'' system), you can run
- something along these lines:
- @example
- # mkdir /mnt/etc
- # cp /etc/configuration/desktop.scm /mnt/etc/config.scm
- # nano /mnt/etc/config.scm
- @end example
- You should pay attention to what your configuration file contains, and
- in particular:
- @itemize
- @item
- Make sure the @code{bootloader-configuration} form refers to the targets
- you want to install GRUB on. It should mention @code{grub-bootloader}
- if you are installing GRUB in the legacy way, or
- @code{grub-efi-bootloader} for newer UEFI systems. For legacy systems,
- the @code{targets} field contain the names of the devices, like
- @code{(list "/dev/sda")}; for UEFI systems it names the paths to mounted
- EFI partitions, like @code{(list "/boot/efi")}; do make sure the paths
- are currently mounted and a @code{file-system} entry is specified in
- your configuration.
- @item
- Be sure that your file system labels match the value of their respective
- @code{device} fields in your @code{file-system} configuration, assuming
- your @code{file-system} configuration uses the @code{file-system-label}
- procedure in its @code{device} field.
- @item
- If there are encrypted or RAID partitions, make sure to add a
- @code{mapped-devices} field to describe them (@pxref{Mapped Devices}).
- @end itemize
- Once you are done preparing the configuration file, the new system must
- be initialized (remember that the target root file system is mounted
- under @file{/mnt}):
- @example
- guix system init /mnt/etc/config.scm /mnt
- @end example
- @noindent
- This copies all the necessary files and installs GRUB on
- @file{/dev/sdX}, unless you pass the @option{--no-bootloader} option. For
- more information, @pxref{Invoking guix system}. This command may trigger
- downloads or builds of missing packages, which can take some time.
- Once that command has completed---and hopefully succeeded!---you can run
- @command{reboot} and boot into the new system. The @code{root} password
- in the new system is initially empty; other users' passwords need to be
- initialized by running the @command{passwd} command as @code{root},
- unless your configuration specifies otherwise
- (@pxref{user-account-password, user account passwords}).
- @xref{After System Installation}, for what's next!
- @node After System Installation
- @section After System Installation
- Success, you've now booted into Guix System! From then on, you can update the
- system whenever you want by running, say:
- @example
- guix pull
- sudo guix system reconfigure /etc/config.scm
- @end example
- @noindent
- This builds a new system generation with the latest packages and services
- (@pxref{Invoking guix system}). We recommend doing that regularly so that
- your system includes the latest security updates (@pxref{Security Updates}).
- @c See <https://lists.gnu.org/archive/html/guix-devel/2019-01/msg00268.html>.
- @quotation Note
- @cindex sudo vs. @command{guix pull}
- Note that @command{sudo guix} runs your user's @command{guix} command and
- @emph{not} root's, because @command{sudo} leaves @env{PATH} unchanged. To
- explicitly run root's @command{guix}, type @command{sudo -i guix @dots{}}.
- The difference matters here, because @command{guix pull} updates
- the @command{guix} command and package definitions only for the user it is run
- as. This means that if you choose to use @command{guix system reconfigure} in
- root's login shell, you'll need to @command{guix pull} separately.
- @end quotation
- Now, @pxref{Getting Started}, and
- join us on @code{#guix} on the Libera Chat IRC network or on
- @email{guix-devel@@gnu.org} to share your experience!
- @node Installing Guix in a VM
- @section Installing Guix in a Virtual Machine
- @cindex virtual machine, Guix System installation
- @cindex virtual private server (VPS)
- @cindex VPS (virtual private server)
- If you'd like to install Guix System in a virtual machine (VM) or on a
- virtual private server (VPS) rather than on your beloved machine, this
- section is for you.
- To boot a @uref{https://qemu.org/,QEMU} VM for installing Guix System in a
- disk image, follow these steps:
- @enumerate
- @item
- First, retrieve and decompress the Guix system installation image as
- described previously (@pxref{USB Stick and DVD Installation}).
- @item
- Create a disk image that will hold the installed system. To make a
- qcow2-formatted disk image, use the @command{qemu-img} command:
- @example
- qemu-img create -f qcow2 guix-system.img 50G
- @end example
- The resulting file will be much smaller than 50 GB (typically less than
- 1 MB), but it will grow as the virtualized storage device is filled up.
- @item
- Boot the USB installation image in an VM:
- @example
- qemu-system-x86_64 -m 1024 -smp 1 -enable-kvm \
- -nic user,model=virtio-net-pci -boot menu=on,order=d \
- -drive file=guix-system.img \
- -drive media=cdrom,file=guix-system-install-@value{VERSION}.@var{system}.iso
- @end example
- @code{-enable-kvm} is optional, but significantly improves performance,
- @pxref{Running Guix in a VM}.
- @item
- You're now root in the VM, proceed with the installation process.
- @xref{Preparing for Installation}, and follow the instructions.
- @end enumerate
- Once installation is complete, you can boot the system that's on your
- @file{guix-system.img} image. @xref{Running Guix in a VM}, for how to do
- that.
- @node Building the Installation Image
- @section Building the Installation Image
- @cindex installation image
- The installation image described above was built using the @command{guix
- system} command, specifically:
- @example
- guix system image -t iso9660 gnu/system/install.scm
- @end example
- Have a look at @file{gnu/system/install.scm} in the source tree,
- and see also @ref{Invoking guix system} for more information
- about the installation image.
- @section Building the Installation Image for ARM Boards
- Many ARM boards require a specific variant of the
- @uref{https://www.denx.de/wiki/U-Boot/, U-Boot} bootloader.
- If you build a disk image and the bootloader is not available otherwise
- (on another boot drive etc), it's advisable to build an image that
- includes the bootloader, specifically:
- @example
- guix system image --system=armhf-linux -e '((@@ (gnu system install) os-with-u-boot) (@@ (gnu system install) installation-os) "A20-OLinuXino-Lime2")'
- @end example
- @code{A20-OLinuXino-Lime2} is the name of the board. If you specify an invalid
- board, a list of possible boards will be printed.
- @c *********************************************************************
- @node Getting Started
- @chapter Getting Started
- Presumably, you've reached this section because either you have
- installed Guix on top of another distribution (@pxref{Installation}), or
- you've installed the standalone Guix System (@pxref{System
- Installation}). It's time for you to get started using Guix and this
- section aims to help you do that and give you a feel of what it's like.
- Guix is about installing software, so probably the first thing you'll
- want to do is to actually look for software. Let's say you're looking
- for a text editor, you can run:
- @example
- guix search text editor
- @end example
- This command shows you a number of matching @dfn{packages}, each time
- showing the package's name, version, a description, and additional info.
- Once you've found out the one you want to use, let's say Emacs (ah ha!),
- you can go ahead and install it (run this command as a regular user,
- @emph{no need for root privileges}!):
- @example
- guix install emacs
- @end example
- @cindex profile
- You've installed your first package, congrats! The package is now
- visible in your default @dfn{profile}, @file{$HOME/.guix-profile}---a
- profile is a directory containing installed packages.
- In the process, you've
- probably noticed that Guix downloaded pre-built binaries; or, if you
- explicitly chose to @emph{not} use pre-built binaries, then probably
- Guix is still building software (@pxref{Substitutes}, for more info).
- Unless you're using Guix System, the @command{guix install} command must
- have printed this hint:
- @example
- hint: Consider setting the necessary environment variables by running:
- GUIX_PROFILE="$HOME/.guix-profile"
- . "$GUIX_PROFILE/etc/profile"
- Alternately, see `guix package --search-paths -p "$HOME/.guix-profile"'.
- @end example
- Indeed, you must now tell your shell where @command{emacs} and other
- programs installed with Guix are to be found. Pasting the two lines
- above will do just that: it will add
- @code{$HOME/.guix-profile/bin}---which is where the installed package
- is---to the @code{PATH} environment variable. You can paste these two
- lines in your shell so they take effect right away, but more importantly
- you should add them to @file{~/.bash_profile} (or equivalent file if you
- do not use Bash) so that environment variables are set next time you
- spawn a shell. You only need to do this once and other search paths
- environment variables will be taken care of similarly---e.g., if you
- eventually install @code{python} and Python libraries,
- @env{GUIX_PYTHONPATH} will be defined.
- You can go on installing packages at your will. To list installed
- packages, run:
- @example
- guix package --list-installed
- @end example
- To remove a package, you would unsurprisingly run @command{guix remove}.
- A distinguishing feature is the ability to @dfn{roll back} any operation
- you made---installation, removal, upgrade---by simply typing:
- @example
- guix package --roll-back
- @end example
- This is because each operation is in fact a @dfn{transaction} that
- creates a new @dfn{generation}. These generations and the difference
- between them can be displayed by running:
- @example
- guix package --list-generations
- @end example
- Now you know the basics of package management!
- @quotation Going further
- @xref{Package Management}, for more about package management. You may
- like @dfn{declarative} package management with @command{guix package
- --manifest}, managing separate @dfn{profiles} with @option{--profile},
- deleting old generations, collecting garbage, and other nifty features
- that will come in handy as you become more familiar with Guix. If you
- are a developer, @pxref{Development} for additional tools. And if
- you're curious, @pxref{Features}, to peek under the hood.
- @end quotation
- Once you've installed a set of packages, you will want to periodically
- @emph{upgrade} them to the latest and greatest version. To do that, you
- will first pull the latest revision of Guix and its package collection:
- @example
- guix pull
- @end example
- The end result is a new @command{guix} command, under
- @file{~/.config/guix/current/bin}. Unless you're on Guix System, the
- first time you run @command{guix pull}, be sure to follow the hint that
- the command prints and, similar to what we saw above, paste these two
- lines in your terminal and @file{.bash_profile}:
- @example
- GUIX_PROFILE="$HOME/.config/guix/current"
- . "$GUIX_PROFILE/etc/profile"
- @end example
- @noindent
- You must also instruct your shell to point to this new @command{guix}:
- @example
- hash guix
- @end example
- At this point, you're running a brand new Guix. You can thus go ahead
- and actually upgrade all the packages you previously installed:
- @example
- guix upgrade
- @end example
- As you run this command, you will see that binaries are downloaded (or
- perhaps some packages are built), and eventually you end up with the
- upgraded packages. Should one of these upgraded packages not be to your
- liking, remember you can always roll back!
- You can display the exact revision of Guix you're currently using by
- running:
- @example
- guix describe
- @end example
- The information it displays is @emph{all it takes to reproduce the exact
- same Guix}, be it at a different point in time or on a different
- machine.
- @quotation Going further
- @xref{Invoking guix pull}, for more information. @xref{Channels}, on
- how to specify additional @dfn{channels} to pull packages from, how to
- replicate Guix, and more. You may also find @command{time-machine}
- handy (@pxref{Invoking guix time-machine}).
- @end quotation
- If you installed Guix System, one of the first things you'll want to do
- is to upgrade your system. Once you've run @command{guix pull} to get
- the latest Guix, you can upgrade the system like this:
- @example
- sudo guix system reconfigure /etc/config.scm
- @end example
- Upon completion, the system runs the latest versions of its software
- packages. When you eventually reboot, you'll notice a sub-menu in the
- bootloader that reads ``Old system generations'': it's what allows you
- to boot @emph{an older generation of your system}, should the latest
- generation be ``broken'' or otherwise unsatisfying. Just like for
- packages, you can always @emph{roll back} to a previous generation
- @emph{of the whole system}:
- @example
- sudo guix system roll-back
- @end example
- There are many things you'll probably want to tweak on your system:
- adding new user accounts, adding new system services, fiddling with the
- configuration of those services, etc. The system configuration is
- @emph{entirely} described in the @file{/etc/config.scm} file.
- @xref{Using the Configuration System}, to learn how to change it.
- Now you know enough to get started!
- @quotation Resources
- The rest of this manual provides a reference for all things Guix. Here
- are some additional resources you may find useful:
- @itemize
- @item
- @xref{Top,,, guix-cookbook, The GNU Guix Cookbook}, for a list of
- ``how-to'' style of recipes for a variety of applications.
- @item
- The @uref{https://guix.gnu.org/guix-refcard.pdf, GNU Guix Reference
- Card} lists in two pages most of the commands and options you'll ever
- need.
- @item
- The web site contains @uref{https://guix.gnu.org/en/videos/,
- instructional videos} covering topics such as everyday use of Guix, how
- to get help, and how to become a contributor.
- @item
- @xref{Documentation}, to learn how to access documentation on your
- computer.
- @end itemize
- We hope you will enjoy Guix as much as the community enjoys building it!
- @end quotation
- @c *********************************************************************
- @node Package Management
- @chapter Package Management
- @cindex packages
- The purpose of GNU Guix is to allow users to easily install, upgrade, and
- remove software packages, without having to know about their build
- procedures or dependencies. Guix also goes beyond this obvious set of
- features.
- This chapter describes the main features of Guix, as well as the
- package management tools it provides. Along with the command-line
- interface described below (@pxref{Invoking guix package, @code{guix
- package}}), you may also use the Emacs-Guix interface (@pxref{Top,,,
- emacs-guix, The Emacs-Guix Reference Manual}), after installing
- @code{emacs-guix} package (run @kbd{M-x guix-help} command to start
- with it):
- @example
- guix install emacs-guix
- @end example
- @menu
- * Features:: How Guix will make your life brighter.
- * Invoking guix package:: Package installation, removal, etc.
- * Substitutes:: Downloading pre-built binaries.
- * Packages with Multiple Outputs:: Single source package, multiple outputs.
- * Invoking guix gc:: Running the garbage collector.
- * Invoking guix pull:: Fetching the latest Guix and distribution.
- * Invoking guix time-machine:: Running an older revision of Guix.
- * Inferiors:: Interacting with another revision of Guix.
- * Invoking guix describe:: Display information about your Guix revision.
- * Invoking guix archive:: Exporting and importing store files.
- @end menu
- @node Features
- @section Features
- Here we assume you've already made your first steps with Guix
- (@pxref{Getting Started}) and would like to get an overview about what's
- going on under the hood.
- When using Guix, each package ends up in the @dfn{package store}, in its
- own directory---something that resembles
- @file{/gnu/store/xxx-package-1.2}, where @code{xxx} is a base32 string.
- Instead of referring to these directories, users have their own
- @dfn{profile}, which points to the packages that they actually want to
- use. These profiles are stored within each user's home directory, at
- @code{$HOME/.guix-profile}.
- For example, @code{alice} installs GCC 4.7.2. As a result,
- @file{/home/alice/.guix-profile/bin/gcc} points to
- @file{/gnu/store/@dots{}-gcc-4.7.2/bin/gcc}. Now, on the same machine,
- @code{bob} had already installed GCC 4.8.0. The profile of @code{bob}
- simply continues to point to
- @file{/gnu/store/@dots{}-gcc-4.8.0/bin/gcc}---i.e., both versions of GCC
- coexist on the same system without any interference.
- The @command{guix package} command is the central tool to manage
- packages (@pxref{Invoking guix package}). It operates on the per-user
- profiles, and can be used @emph{with normal user privileges}.
- @cindex transactions
- The command provides the obvious install, remove, and upgrade
- operations. Each invocation is actually a @emph{transaction}: either
- the specified operation succeeds, or nothing happens. Thus, if the
- @command{guix package} process is terminated during the transaction,
- or if a power outage occurs during the transaction, then the user's
- profile remains in its previous state, and remains usable.
- In addition, any package transaction may be @emph{rolled back}. So, if,
- for example, an upgrade installs a new version of a package that turns
- out to have a serious bug, users may roll back to the previous instance
- of their profile, which was known to work well. Similarly, the global
- system configuration on Guix is subject to
- transactional upgrades and roll-back
- (@pxref{Using the Configuration System}).
- All packages in the package store may be @emph{garbage-collected}.
- Guix can determine which packages are still referenced by user
- profiles, and remove those that are provably no longer referenced
- (@pxref{Invoking guix gc}). Users may also explicitly remove old
- generations of their profile so that the packages they refer to can be
- collected.
- @cindex reproducibility
- @cindex reproducible builds
- Guix takes a @dfn{purely functional} approach to package
- management, as described in the introduction (@pxref{Introduction}).
- Each @file{/gnu/store} package directory name contains a hash of all the
- inputs that were used to build that package---compiler, libraries, build
- scripts, etc. This direct correspondence allows users to make sure a
- given package installation matches the current state of their
- distribution. It also helps maximize @dfn{build reproducibility}:
- thanks to the isolated build environments that are used, a given build
- is likely to yield bit-identical files when performed on different
- machines (@pxref{Invoking guix-daemon, container}).
- @cindex substitutes
- This foundation allows Guix to support @dfn{transparent binary/source
- deployment}. When a pre-built binary for a @file{/gnu/store} item is
- available from an external source---a @dfn{substitute}, Guix just
- downloads it and unpacks it;
- otherwise, it builds the package from source, locally
- (@pxref{Substitutes}). Because build results are usually bit-for-bit
- reproducible, users do not have to trust servers that provide
- substitutes: they can force a local build and @emph{challenge} providers
- (@pxref{Invoking guix challenge}).
- Control over the build environment is a feature that is also useful for
- developers. The @command{guix 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
- @cindex profile
- The @command{guix package} command is the tool that allows users to
- install, upgrade, and remove packages, as well as rolling back to
- previous configurations. These operations work on a user
- @dfn{profile}---a directory of installed packages. Each user has a
- default profile in @file{$HOME/.guix-profile}.
- The command operates only on the user's own profile,
- and works with normal user privileges (@pxref{Features}). Its syntax
- is:
- @example
- guix package @var{options}
- @end example
- @cindex transactions
- Primarily, @var{options} specifies the operations to be performed during
- the transaction. Upon completion, a new profile is created, but
- previous @dfn{generations} of the profile remain available, should the user
- want to roll back.
- For example, to remove @code{lua} and install @code{guile} and
- @code{guile-cairo} in a single transaction:
- @example
- guix package -r lua -i guile guile-cairo
- @end example
- @cindex aliases, for @command{guix package}
- For your convenience, we also provide the following aliases:
- @itemize
- @item
- @command{guix search} is an alias for @command{guix package -s},
- @item
- @command{guix install} is an alias for @command{guix package -i},
- @item
- @command{guix remove} is an alias for @command{guix package -r},
- @item
- @command{guix upgrade} is an alias for @command{guix package -u},
- @item
- and @command{guix show} is an alias for @command{guix package --show=}.
- @end itemize
- These aliases are less expressive than @command{guix package} and provide
- fewer options, so in some cases you'll probably want to use @command{guix
- package} directly.
- @command{guix package} also supports a @dfn{declarative approach}
- whereby the user specifies the exact set of packages to be available and
- passes it @i{via} the @option{--manifest} option
- (@pxref{profile-manifest, @option{--manifest}}).
- @cindex profile
- For each user, a symlink to the user's default profile is automatically
- created in @file{$HOME/.guix-profile}. This symlink always points to the
- current generation of the user's default profile. Thus, users can add
- @file{$HOME/.guix-profile/bin} to their @env{PATH} environment
- variable, and so on.
- @cindex search paths
- If you are not using Guix System, consider adding the
- following lines to your @file{~/.bash_profile} (@pxref{Bash Startup
- Files,,, bash, The GNU Bash Reference Manual}) so that newly-spawned
- shells get all the right environment variable definitions:
- @example
- GUIX_PROFILE="$HOME/.guix-profile" ; \
- source "$GUIX_PROFILE/etc/profile"
- @end example
- In a multi-user setup, user profiles are stored in a place registered as
- a @dfn{garbage-collector root}, which @file{$HOME/.guix-profile} points
- to (@pxref{Invoking guix gc}). That directory is normally
- @code{@var{localstatedir}/guix/profiles/per-user/@var{user}}, where
- @var{localstatedir} is the value passed to @code{configure} as
- @option{--localstatedir}, and @var{user} is the user name. The
- @file{per-user} directory is created when @command{guix-daemon} is
- started, and the @var{user} sub-directory is created by @command{guix
- package}.
- The @var{options} can be among the following:
- @table @code
- @item --install=@var{package} @dots{}
- @itemx -i @var{package} @dots{}
- Install the specified @var{package}s.
- Each @var{package} may specify either a simple package name, such as
- @code{guile}, or a package name followed by an at-sign and version number,
- such as @code{guile@@1.8.8} or simply @code{guile@@1.8} (in the latter
- case, the newest version prefixed by @code{1.8} is selected).
- If no version number is specified, the
- newest available version will be selected. In addition, @var{package}
- may contain a colon, followed by the name of one of the outputs of the
- package, as in @code{gcc:doc} or @code{binutils@@2.22:lib}
- (@pxref{Packages with Multiple Outputs}). Packages with a corresponding
- name (and optionally version) are searched for among the GNU
- distribution modules (@pxref{Package Modules}).
- @cindex propagated inputs
- Sometimes packages have @dfn{propagated inputs}: these are dependencies
- that automatically get installed along with the required package
- (@pxref{package-propagated-inputs, @code{propagated-inputs} in
- @code{package} objects}, for information about propagated inputs in
- package definitions).
- @anchor{package-cmd-propagated-inputs}
- An example is the GNU MPC library: its C header files refer to those of
- the GNU MPFR library, which in turn refer to those of the GMP library.
- Thus, when installing MPC, the MPFR and GMP libraries also get installed
- in the profile; removing MPC also removes MPFR and GMP---unless they had
- also been explicitly installed by the user.
- Besides, packages sometimes rely on the definition of environment
- variables for their search paths (see explanation of
- @option{--search-paths} below). Any missing or possibly incorrect
- environment variable definitions are reported here.
- @item --install-from-expression=@var{exp}
- @itemx -e @var{exp}
- Install the package @var{exp} evaluates to.
- @var{exp} must be a Scheme expression that evaluates to a
- @code{<package>} object. This option is notably useful to disambiguate
- between same-named variants of a package, with expressions such as
- @code{(@@ (gnu packages base) guile-final)}.
- Note that this option installs the first output of the specified
- package, which may be insufficient when needing a specific output of a
- multiple-output package.
- @item --install-from-file=@var{file}
- @itemx -f @var{file}
- Install the package that the code within @var{file} evaluates to.
- As an example, @var{file} might contain a definition like this
- (@pxref{Defining Packages}):
- @lisp
- @include package-hello.scm
- @end lisp
- Developers may find it useful to include such a @file{guix.scm} file
- in the root of their project source tree that can be used to test
- development snapshots and create reproducible development environments
- (@pxref{Invoking guix 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.
- @cindex profile, choosing
- @item --profile=@var{profile}
- @itemx -p @var{profile}
- Use @var{profile} instead of the user's default profile.
- @var{profile} must be the name of a file that will be created upon
- completion. Concretely, @var{profile} will be a mere symbolic link
- (``symlink'') pointing to the actual profile where packages are
- installed:
- @example
- $ guix install hello -p ~/code/my-profile
- @dots{}
- $ ~/code/my-profile/bin/hello
- Hello, world!
- @end example
- All it takes to get rid of the profile is to remove this symlink and its
- siblings that point to specific generations:
- @example
- $ rm ~/code/my-profile ~/code/my-profile-*-link
- @end example
- @item --list-profiles
- List all the user's profiles:
- @example
- $ guix package --list-profiles
- /home/charlie/.guix-profile
- /home/charlie/code/my-profile
- /home/charlie/code/devel-profile
- /home/charlie/tmp/test
- @end example
- When running as root, list all the profiles of all the users.
- @cindex collisions, in a profile
- @cindex colliding packages in profiles
- @cindex profile collisions
- @item --allow-collisions
- Allow colliding packages in the new profile. Use at your own risk!
- By default, @command{guix package} reports as an error @dfn{collisions}
- in the profile. Collisions happen when two or more different versions
- or variants of a given package end up in the profile.
- @item --bootstrap
- Use the bootstrap Guile to build the profile. This option is only
- useful to distribution developers.
- @end table
- In addition to these actions, @command{guix package} supports the
- following options to query the current state of a profile, or the
- availability of packages:
- @table @option
- @item --search=@var{regexp}
- @itemx -s @var{regexp}
- @anchor{guix-search}
- @cindex searching for packages
- List the available packages whose name, synopsis, or description matches
- @var{regexp} (in a case-insensitive fashion), sorted by relevance.
- Print all the metadata of matching packages in
- @code{recutils} format (@pxref{Top, GNU recutils databases,, recutils,
- GNU recutils manual}).
- This allows specific fields to be extracted using the @command{recsel}
- command, for instance:
- @example
- $ guix package -s malloc | recsel -p name,version,relevance
- name: jemalloc
- version: 4.5.0
- relevance: 6
- name: glibc
- version: 2.25
- relevance: 1
- name: libgc
- version: 7.6.0
- relevance: 1
- @end example
- Similarly, to show the name of all the packages available under the
- terms of the GNU@tie{}LGPL version 3:
- @example
- $ guix package -s "" | recsel -p name -e 'license ~ "LGPL 3"'
- name: elfutils
- name: gmp
- @dots{}
- @end example
- It is also possible to refine search results using several @code{-s} flags to
- @command{guix package}, or several arguments to @command{guix search}. For
- example, the following command returns a list of board games (this time using
- the @command{guix search} alias):
- @example
- $ guix search '\<board\>' game | recsel -p name
- name: gnubg
- @dots{}
- @end example
- If we were to omit @code{-s game}, we would also get software packages
- that deal with printed circuit boards; removing the angle brackets
- around @code{board} would further add packages that have to do with
- keyboards.
- And now for a more elaborate example. The following command searches
- for cryptographic libraries, filters out Haskell, Perl, Python, and Ruby
- libraries, and prints the name and synopsis of the matching packages:
- @example
- $ guix search crypto library | \
- recsel -e '! (name ~ "^(ghc|perl|python|ruby)")' -p name,synopsis
- @end example
- @noindent
- @xref{Selection Expressions,,, recutils, GNU recutils manual}, for more
- information on @dfn{selection expressions} for @code{recsel -e}.
- @item --show=@var{package}
- Show details about @var{package}, taken from the list of available packages, in
- @code{recutils} format (@pxref{Top, GNU recutils databases,, recutils, GNU
- recutils manual}).
- @example
- $ guix package --show=guile | recsel -p name,version
- name: guile
- version: 3.0.5
- name: guile
- version: 3.0.2
- name: guile
- version: 2.2.7
- @dots{}
- @end example
- You may also specify the full name of a package to only get details about a
- specific version of it (this time using the @command{guix show} alias):
- @example
- $ guix show guile@@3.0.5 | recsel -p name,version
- name: guile
- version: 3.0.5
- @end example
- @item --list-installed[=@var{regexp}]
- @itemx -I [@var{regexp}]
- List the currently installed packages in the specified profile, with the
- most recently installed packages shown last. When @var{regexp} is
- specified, list only installed packages whose name matches @var{regexp}.
- For each installed package, print the following items, separated by
- tabs: the package name, its version string, the part of the package that
- is installed (for instance, @code{out} for the default output,
- @code{include} for its headers, etc.), and the path of this package in
- the store.
- @item --list-available[=@var{regexp}]
- @itemx -A [@var{regexp}]
- List packages currently available in the distribution for this system
- (@pxref{GNU Distribution}). When @var{regexp} is specified, list only
- available packages whose name matches @var{regexp}.
- For each package, print the following items separated by tabs: its name,
- its version string, the parts of the package (@pxref{Packages with
- Multiple Outputs}), and the source location of its definition.
- @item --list-generations[=@var{pattern}]
- @itemx -l [@var{pattern}]
- @cindex generations
- Return a list of generations along with their creation dates; for each
- generation, show the installed packages, with the most recently
- installed packages shown last. Note that the zeroth generation is never
- shown.
- For each installed package, print the following items, separated by
- tabs: the name of a package, its version string, the part of the package
- that is installed (@pxref{Packages with Multiple Outputs}), and the
- location of this package in the store.
- When @var{pattern} is used, the command returns only matching
- generations. Valid patterns include:
- @itemize
- @item @emph{Integers and comma-separated integers}. Both patterns denote
- generation numbers. For instance, @option{--list-generations=1} returns
- the first one.
- And @option{--list-generations=1,8,2} outputs three generations in the
- specified order. Neither spaces nor trailing commas are allowed.
- @item @emph{Ranges}. @option{--list-generations=2..9} prints the
- specified generations and everything in between. Note that the start of
- a range must be smaller than its end.
- It is also possible to omit the endpoint. For example,
- @option{--list-generations=2..}, returns all generations starting from the
- second one.
- @item @emph{Durations}. You can also get the last @emph{N}@tie{}days, weeks,
- or months by passing an integer along with the first letter of the
- duration. For example, @option{--list-generations=20d} lists generations
- that are up to 20 days old.
- @end itemize
- @item --delete-generations[=@var{pattern}]
- @itemx -d [@var{pattern}]
- When @var{pattern} is omitted, delete all generations except the current
- one.
- This command accepts the same patterns as @option{--list-generations}.
- When @var{pattern} is specified, delete the matching generations. When
- @var{pattern} specifies a duration, generations @emph{older} than the
- specified duration match. For instance, @option{--delete-generations=1m}
- deletes generations that are more than one month old.
- If the current generation matches, it is @emph{not} deleted. Also, the
- zeroth generation is never deleted.
- Note that deleting generations prevents rolling back to them.
- Consequently, this command must be used with care.
- @cindex manifest, exporting
- @anchor{export-manifest}
- @item --export-manifest
- Write to standard output a manifest suitable for @option{--manifest}
- corresponding to the chosen profile(s).
- This option is meant to help you migrate from the ``imperative''
- operating mode---running @command{guix install}, @command{guix upgrade},
- etc.---to the declarative mode that @option{--manifest} offers.
- Be aware that the resulting manifest @emph{approximates} what your
- profile actually contains; for instance, depending on how your profile
- was created, it can refer to packages or package versions that are not
- exactly what you specified.
- Keep in mind that a manifest is purely symbolic: it only contains
- package names and possibly versions, and their meaning varies over time.
- If you wish to ``pin'' channels to the revisions that were used to build
- the profile(s), see @option{--export-channels} below.
- @cindex pinning, channel revisions of a profile
- @item --export-channels
- Write to standard output the list of channels used by the chosen
- profile(s), in a format suitable for @command{guix pull --channels} or
- @command{guix time-machine --channels} (@pxref{Channels}).
- Together with @option{--export-manifest}, this option provides
- information allowing you to replicate the current profile
- (@pxref{Replicating Guix}).
- However, note that the output of this command @emph{approximates} what
- was actually used to build this profile. In particular, a single
- profile might have been built from several different revisions of the
- same channel. In that case, @option{--export-manifest} chooses the last
- one and writes the list of other revisions in a comment. If you really
- need to pick packages from different channel revisions, you can use
- inferiors in your manifest to do so (@pxref{Inferiors}).
- Together with @option{--export-manifest}, this is a good starting point
- if you are willing to migrate from the ``imperative'' model to the fully
- declarative model consisting of a manifest file along with a channels
- file pinning the exact channel revision(s) you want.
- @end table
- Finally, since @command{guix package} may actually start build
- processes, it supports all the common build options (@pxref{Common Build
- Options}). It also supports package transformation options, such as
- @option{--with-source}, and preserves them across upgrades
- (@pxref{Package Transformation Options}).
- @node Substitutes
- @section Substitutes
- @cindex substitutes
- @cindex pre-built binaries
- Guix supports transparent source/binary deployment, which means that it
- can either build things locally, or download pre-built items from a
- server, or both. We call these pre-built items @dfn{substitutes}---they
- are substitutes for local build results. In many cases, downloading a
- substitute is much faster than building things locally.
- Substitutes can be anything resulting from a derivation build
- (@pxref{Derivations}). Of course, in the common case, they are
- pre-built package binaries, but source tarballs, for instance, which
- also result from derivation builds, can be available as substitutes.
- @menu
- * Official Substitute Servers:: One particular source of substitutes.
- * Substitute Server Authorization:: How to enable or disable substitutes.
- * Getting Substitutes from Other Servers:: Substitute diversity.
- * Substitute Authentication:: How Guix verifies substitutes.
- * Proxy Settings:: How to get substitutes via proxy.
- * Substitution Failure:: What happens when substitution fails.
- * On Trusting Binaries:: How can you trust that binary blob?
- @end menu
- @node Official Substitute Servers
- @subsection Official Substitute Servers
- @cindex build farm
- @code{@value{SUBSTITUTE-SERVER-1}} and
- @code{@value{SUBSTITUTE-SERVER-2}} are both front-ends to official build
- farms that build packages from Guix continuously for some architectures,
- and make them available as substitutes. These are the default source of
- substitutes; which can be overridden by passing the
- @option{--substitute-urls} option either to @command{guix-daemon}
- (@pxref{daemon-substitute-urls,, @code{guix-daemon --substitute-urls}})
- or to client tools such as @command{guix package}
- (@pxref{client-substitute-urls,, client @option{--substitute-urls}
- option}).
- Substitute URLs can be either HTTP or HTTPS.
- HTTPS is recommended because communications are encrypted; conversely,
- using HTTP makes all communications visible to an eavesdropper, who
- could use the information gathered to determine, for instance, whether
- your system has unpatched security vulnerabilities.
- Substitutes from the official build farms are enabled by default when
- using Guix System (@pxref{GNU Distribution}). However,
- they are disabled by default when using Guix on a foreign distribution,
- unless you have explicitly enabled them via one of the recommended
- installation steps (@pxref{Installation}). The following paragraphs
- describe how to enable or disable substitutes for the official build
- farm; the same procedure can also be used to enable substitutes for any
- other substitute server.
- @node Substitute Server Authorization
- @subsection Substitute Server Authorization
- @cindex security
- @cindex substitutes, authorization thereof
- @cindex access control list (ACL), for substitutes
- @cindex ACL (access control list), for substitutes
- To allow Guix to download substitutes from @code{@value{SUBSTITUTE-SERVER-1}}, @code{@value{SUBSTITUTE-SERVER-2}} or a mirror, you
- must add the relevant public key to the access control list (ACL) of archive
- imports, using the @command{guix archive} command (@pxref{Invoking guix
- archive}). Doing so implies that you trust the substitute server to not
- be compromised and to serve genuine substitutes.
- @quotation Note
- If you are using Guix System, you can skip this section: Guix System
- authorizes substitutes from @code{@value{SUBSTITUTE-SERVER-1}} and
- @code{@value{SUBSTITUTE-SERVER-2}} by default.
- @end quotation
- The public keys for each of the project maintained substitute servers
- are installed along with Guix, in @code{@var{prefix}/share/guix/}, where
- @var{prefix} is the installation prefix of Guix. If you installed Guix
- from source, make sure you checked the GPG signature of
- @file{guix-@value{VERSION}.tar.gz}, which contains this public key file.
- Then, you can run something like this:
- @example
- # guix archive --authorize < @var{prefix}/share/guix/@value{SUBSTITUTE-SERVER-1}.pub
- # guix archive --authorize < @var{prefix}/share/guix/@value{SUBSTITUTE-SERVER-2}.pub
- @end example
- Once this is in place, the output of a command like @code{guix build}
- should change from something like:
- @example
- $ guix build emacs --dry-run
- The following derivations would be built:
- /gnu/store/yr7bnx8xwcayd6j95r2clmkdl1qh688w-emacs-24.3.drv
- /gnu/store/x8qsh1hlhgjx6cwsjyvybnfv2i37z23w-dbus-1.6.4.tar.gz.drv
- /gnu/store/1ixwp12fl950d15h2cj11c73733jay0z-alsa-lib-1.0.27.1.tar.bz2.drv
- /gnu/store/nlma1pw0p603fpfiqy7kn4zm105r5dmw-util-linux-2.21.drv
- @dots{}
- @end example
- @noindent
- to something like:
- @example
- $ guix build emacs --dry-run
- 112.3 MB would be downloaded:
- /gnu/store/pk3n22lbq6ydamyymqkkz7i69wiwjiwi-emacs-24.3
- /gnu/store/2ygn4ncnhrpr61rssa6z0d9x22si0va3-libjpeg-8d
- /gnu/store/71yz6lgx4dazma9dwn2mcjxaah9w77jq-cairo-1.12.16
- /gnu/store/7zdhgp0n1518lvfn8mb96sxqfmvqrl7v-libxrender-0.9.7
- @dots{}
- @end example
- @noindent
- The text changed from ``The following derivations would be built'' to
- ``112.3 MB would be downloaded''. This indicates that substitutes from
- the configured substitute servers are usable and will be downloaded,
- when possible, for future builds.
- @cindex substitutes, how to disable
- The substitute mechanism can be disabled globally by running
- @code{guix-daemon} with @option{--no-substitutes} (@pxref{Invoking
- guix-daemon}). It can also be disabled temporarily by passing the
- @option{--no-substitutes} option to @command{guix package},
- @command{guix build}, and other command-line tools.
- @node Getting Substitutes from Other Servers
- @subsection Getting Substitutes from Other Servers
- @cindex substitute servers, adding more
- Guix can look up and fetch substitutes from several servers. This is
- useful when you are using packages from additional channels for which
- the official server does not have substitutes but another server
- provides them. Another situation where this is useful is when you would
- prefer to download from your organization's substitute server, resorting
- to the official server only as a fallback or dismissing it altogether.
- You can give Guix a list of substitute server URLs and it will check
- them in the specified order. You also need to explicitly authorize the
- public keys of substitute servers to instruct Guix to accept the
- substitutes they sign.
- On Guix System, this is achieved by modifying the configuration of the
- @code{guix} service. Since the @code{guix} service is part of the
- default lists of services, @code{%base-services} and
- @code{%desktop-services}, you can use @code{modify-services} to change
- its configuration and add the URLs and substitute keys that you want
- (@pxref{Service Reference, @code{modify-services}}).
- As an example, suppose you want to fetch substitutes from
- @code{guix.example.org} and to authorize the signing key of that server,
- in addition to the default @code{@value{SUBSTITUTE-SERVER-1}} and
- @code{@value{SUBSTITUTE-SERVER-2}}. The resulting operating system
- configuration will look something like:
- @lisp
- (operating-system
- ;; @dots{}
- (services
- ;; Assume we're starting from '%desktop-services'. Replace it
- ;; with the list of services you're actually using.
- (modify-services %desktop-services
- (guix-service-type config =>
- (guix-configuration
- (inherit config)
- (substitute-urls
- (append (list "https://guix.example.org")
- %default-substitute-urls))
- (authorized-keys
- (append (list (local-file "./key.pub"))
- %default-authorized-guix-keys)))))))
- @end lisp
- This assumes that the file @file{key.pub} contains the signing key of
- @code{guix.example.org}. With this change in place in your operating
- system configuration file (say @file{/etc/config.scm}), you can
- reconfigure and restart the @code{guix-daemon} service or reboot so the
- changes take effect:
- @example
- $ sudo guix system reconfigure /etc/config.scm
- $ sudo herd restart guix-daemon
- @end example
- If you're running Guix on a ``foreign distro'', you would instead take
- the following steps to get substitutes from additional servers:
- @enumerate
- @item
- Edit the service configuration file for @code{guix-daemon}; when using
- systemd, this is normally
- @file{/etc/systemd/system/guix-daemon.service}. Add the
- @option{--substitute-urls} option on the @command{guix-daemon} command
- line and list the URLs of interest (@pxref{daemon-substitute-urls,
- @code{guix-daemon --substitute-urls}}):
- @example
- @dots{} --substitute-urls='https://guix.example.org @value{SUBSTITUTE-URLS}'
- @end example
- @item
- Restart the daemon. For systemd, it goes like this:
- @example
- systemctl daemon-reload
- systemctl restart guix-daemon.service
- @end example
- @item
- Authorize the key of the new server (@pxref{Invoking guix archive}):
- @example
- guix archive --authorize < key.pub
- @end example
- Again this assumes @file{key.pub} contains the public key that
- @code{guix.example.org} uses to sign substitutes.
- @end enumerate
- Now you're all set! Substitutes will be preferably taken from
- @code{https://guix.example.org}, using
- @code{@value{SUBSTITUTE-SERVER-1}} then
- @code{@value{SUBSTITUTE-SERVER-2}} as fallback options. Of course you
- can list as many substitute servers as you like, with the caveat that
- substitute lookup can be slowed down if too many servers need to be
- contacted.
- Note that there are also situations where one may want to add the URL of
- a substitute server @emph{without} authorizing its key.
- @xref{Substitute Authentication}, to understand this fine point.
- @node Substitute Authentication
- @subsection Substitute Authentication
- @cindex digital signatures
- Guix detects and raises an error when attempting to use a substitute
- that has been tampered with. Likewise, it ignores substitutes that are
- not signed, or that are not signed by one of the keys listed in the ACL.
- There is one exception though: if an unauthorized server provides
- substitutes that are @emph{bit-for-bit identical} to those provided by
- an authorized server, then the unauthorized server becomes eligible for
- downloads. For example, assume we have chosen two substitute servers
- with this option:
- @example
- --substitute-urls="https://a.example.org https://b.example.org"
- @end example
- @noindent
- @cindex reproducible builds
- If the ACL contains only the key for @samp{b.example.org}, and if
- @samp{a.example.org} happens to serve the @emph{exact same} substitutes,
- then Guix will download substitutes from @samp{a.example.org} because it
- comes first in the list and can be considered a mirror of
- @samp{b.example.org}. In practice, independent build machines usually
- produce the same binaries, thanks to bit-reproducible builds (see
- below).
- When using HTTPS, the server's X.509 certificate is @emph{not} validated
- (in other words, the server is not authenticated), contrary to what
- HTTPS clients such as Web browsers usually do. This is because Guix
- authenticates substitute information itself, as explained above, which
- is what we care about (whereas X.509 certificates are about
- authenticating bindings between domain names and public keys).
- @node Proxy Settings
- @subsection Proxy Settings
- @vindex http_proxy
- @vindex https_proxy
- Substitutes are downloaded over HTTP or HTTPS@. The @env{http_proxy} and
- @env{https_proxy} environment variables can be set in the environment of
- @command{guix-daemon} and are honored for downloads of substitutes.
- Note that the value of those environment variables in the environment
- where @command{guix build}, @command{guix package}, and other client
- commands are run has @emph{absolutely no effect}.
- @node Substitution Failure
- @subsection Substitution Failure
- Even when a substitute for a derivation is available, sometimes the
- substitution attempt will fail. This can happen for a variety of
- reasons: the substitute server might be offline, the substitute may
- recently have been deleted, the connection might have been interrupted,
- etc.
- When substitutes are enabled and a substitute for a derivation is
- available, but the substitution attempt fails, Guix will attempt to
- build the derivation locally depending on whether or not
- @option{--fallback} was given (@pxref{fallback-option,, common build
- option @option{--fallback}}). Specifically, if @option{--fallback} was
- omitted, then no local build will be performed, and the derivation is
- considered to have failed. However, if @option{--fallback} was given,
- then Guix will attempt to build the derivation locally, and the success
- or failure of the derivation depends on the success or failure of the
- local build. Note that when substitutes are disabled or no substitute
- is available for the derivation in question, a local build will
- @emph{always} be performed, regardless of whether or not
- @option{--fallback} was given.
- To get an idea of how many substitutes are available right now, you can
- try running the @command{guix weather} command (@pxref{Invoking guix
- weather}). This command provides statistics on the substitutes provided
- by a server.
- @node On Trusting Binaries
- @subsection On Trusting Binaries
- @cindex trust, of pre-built binaries
- Today, each individual's control over their own computing is at the
- mercy of institutions, corporations, and groups with enough power and
- determination to subvert the computing infrastructure and exploit its
- weaknesses. While using substitutes can be convenient, we encourage
- users to also build on their own, or even run their own build farm, such
- that the project run substitute servers are less of an interesting
- target. One way to help is by publishing the software you build using
- @command{guix publish} so that others have one more choice of server to
- download substitutes from (@pxref{Invoking guix publish}).
- Guix has the foundations to maximize build reproducibility
- (@pxref{Features}). In most cases, independent builds of a given
- package or derivation should yield bit-identical results. Thus, through
- a diverse set of independent package builds, we can strengthen the
- integrity of our systems. The @command{guix challenge} command aims to
- help users assess substitute servers, and to assist developers in
- finding out about non-deterministic package builds (@pxref{Invoking guix
- challenge}). Similarly, the @option{--check} option of @command{guix
- build} allows users to check whether previously-installed substitutes
- are genuine by rebuilding them locally (@pxref{build-check,
- @command{guix build --check}}).
- In the future, we want Guix to have support to publish and retrieve
- binaries to/from other users, in a peer-to-peer fashion. If you would
- like to discuss this project, join us on @email{guix-devel@@gnu.org}.
- @node Packages with Multiple Outputs
- @section Packages with Multiple Outputs
- @cindex multiple-output packages
- @cindex package outputs
- @cindex outputs
- Often, packages defined in Guix have a single @dfn{output}---i.e., the
- source package leads to exactly one directory in the store. When running
- @command{guix install glibc}, one installs the default output of the
- GNU libc package; the default output is called @code{out}, but its name
- can be omitted as shown in this command. In this particular case, the
- default output of @code{glibc} contains all the C header files, shared
- libraries, static libraries, Info documentation, and other supporting
- files.
- Sometimes it is more appropriate to separate the various types of files
- produced from a single source package into separate outputs. For
- instance, the GLib C library (used by GTK+ and related packages)
- installs more than 20 MiB of reference documentation as HTML pages.
- To save space for users who do not need it, the documentation goes to a
- separate output, called @code{doc}. To install the main GLib output,
- which contains everything but the documentation, one would run:
- @example
- guix install glib
- @end example
- @cindex documentation
- The command to install its documentation is:
- @example
- guix install glib:doc
- @end example
- Some packages install programs with different ``dependency footprints''.
- For instance, the WordNet package installs both command-line tools and
- graphical user interfaces (GUIs). The former depend solely on the C
- library, whereas the latter depend on Tcl/Tk and the underlying X
- libraries. In this case, we leave the command-line tools in the default
- output, whereas the GUIs are in a separate output. This allows users
- who do not need the GUIs to save space. The @command{guix size} command
- can help find out about such situations (@pxref{Invoking guix size}).
- @command{guix graph} can also be helpful (@pxref{Invoking guix graph}).
- There are several such multiple-output packages in the GNU distribution.
- Other conventional output names include @code{lib} for libraries and
- possibly header files, @code{bin} for stand-alone programs, and
- @code{debug} for debugging information (@pxref{Installing Debugging
- Files}). The outputs of a packages are listed in the third column of
- the output of @command{guix package --list-available} (@pxref{Invoking
- guix package}).
- @node Invoking guix gc
- @section Invoking @command{guix gc}
- @cindex garbage collector
- @cindex disk space
- Packages that are installed, but not used, may be @dfn{garbage-collected}.
- The @command{guix gc} command allows users to explicitly run the garbage
- collector to reclaim space from the @file{/gnu/store} directory. It is
- the @emph{only} way to remove files from @file{/gnu/store}---removing
- files or directories manually may break it beyond repair!
- @cindex GC roots
- @cindex garbage collector roots
- The garbage collector has a set of known @dfn{roots}: any file under
- @file{/gnu/store} reachable from a root is considered @dfn{live} and
- cannot be deleted; any other file is considered @dfn{dead} and may be
- deleted. The set of garbage collector roots (``GC roots'' for short)
- includes default user profiles; by default, the symlinks under
- @file{/var/guix/gcroots} represent these GC roots. New GC roots can be
- added with @command{guix build --root}, for example (@pxref{Invoking
- guix build}). The @command{guix gc --list-roots} command lists them.
- Prior to running @code{guix gc --collect-garbage} to make space, it is
- often useful to remove old generations from user profiles; that way, old
- package builds referenced by those generations can be reclaimed. This
- is achieved by running @code{guix package --delete-generations}
- (@pxref{Invoking guix package}).
- Our recommendation is to run a garbage collection periodically, or when
- you are short on disk space. For instance, to guarantee that at least
- 5@tie{}GB are available on your disk, simply run:
- @example
- guix gc -F 5G
- @end example
- It is perfectly safe to run as a non-interactive periodic job
- (@pxref{Scheduled Job Execution}, for how to set up such a job).
- Running @command{guix gc} with no arguments will collect as
- much garbage as it can, but that is often inconvenient: you may find
- yourself having to rebuild or re-download software that is ``dead'' from
- the GC viewpoint but that is necessary to build other pieces of
- software---e.g., the compiler tool chain.
- The @command{guix gc} command has three modes of operation: it can be
- used to garbage-collect any dead files (the default), to delete specific
- files (the @option{--delete} option), to print garbage-collector
- information, or for more advanced queries. The garbage collection
- options are as follows:
- @table @code
- @item --collect-garbage[=@var{min}]
- @itemx -C [@var{min}]
- Collect garbage---i.e., unreachable @file{/gnu/store} files and
- sub-directories. This is the default operation when no option is
- specified.
- When @var{min} is given, stop once @var{min} bytes have been collected.
- @var{min} may be a number of bytes, or it may include a unit as a
- suffix, such as @code{MiB} for mebibytes and @code{GB} for gigabytes
- (@pxref{Block size, size specifications,, coreutils, GNU Coreutils}).
- When @var{min} is omitted, collect all the garbage.
- @item --free-space=@var{free}
- @itemx -F @var{free}
- Collect garbage until @var{free} space is available under
- @file{/gnu/store}, if possible; @var{free} denotes storage space, such
- as @code{500MiB}, as described above.
- When @var{free} or more is already available in @file{/gnu/store}, do
- nothing and exit immediately.
- @item --delete-generations[=@var{duration}]
- @itemx -d [@var{duration}]
- Before starting the garbage collection process, delete all the generations
- older than @var{duration}, for all the user profiles; when run as root, this
- applies to all the profiles @emph{of all the users}.
- For example, this command deletes all the generations of all your profiles
- that are older than 2 months (except generations that are current), and then
- proceeds to free space until at least 10 GiB are available:
- @example
- guix gc -d 2m -F 10G
- @end example
- @item --delete
- @itemx -D
- Attempt to delete all the store files and directories specified as
- arguments. This fails if some of the files are not in the store, or if
- they are still live.
- @item --list-failures
- List store items corresponding to cached build failures.
- This prints nothing unless the daemon was started with
- @option{--cache-failures} (@pxref{Invoking guix-daemon,
- @option{--cache-failures}}).
- @item --list-roots
- List the GC roots owned by the user; when run as root, list @emph{all} the GC
- roots.
- @item --list-busy
- List store items in use by currently running processes. These store
- items are effectively considered GC roots: they cannot be deleted.
- @item --clear-failures
- Remove the specified store items from the failed-build cache.
- Again, this option only makes sense when the daemon is started with
- @option{--cache-failures}. Otherwise, it does nothing.
- @item --list-dead
- Show the list of dead files and directories still present in the
- store---i.e., files and directories no longer reachable from any root.
- @item --list-live
- Show the list of live store files and directories.
- @end table
- In addition, the references among existing store files can be queried:
- @table @code
- @item --references
- @itemx --referrers
- @cindex package dependencies
- List the references (respectively, the referrers) of store files given
- as arguments.
- @item --requisites
- @itemx -R
- @cindex closure
- List the requisites of the store files passed as arguments. Requisites
- include the store files themselves, their references, and the references
- of these, recursively. In other words, the returned list is the
- @dfn{transitive closure} of the store files.
- @xref{Invoking guix size}, for a tool to profile the size of the closure
- of an element. @xref{Invoking guix graph}, for a tool to visualize
- the graph of references.
- @item --derivers
- @cindex derivation
- Return the derivation(s) leading to the given store items
- (@pxref{Derivations}).
- For example, this command:
- @example
- guix gc --derivers $(guix package -I ^emacs$ | cut -f4)
- @end example
- @noindent
- returns the @file{.drv} file(s) leading to the @code{emacs} package
- installed in your profile.
- Note that there may be zero matching @file{.drv} files, for instance
- because these files have been garbage-collected. There can also be more
- than one matching @file{.drv} due to fixed-output derivations.
- @end table
- Lastly, the following options allow you to check the integrity of the
- store and to control disk usage.
- @table @option
- @item --verify[=@var{options}]
- @cindex integrity, of the store
- @cindex integrity checking
- Verify the integrity of the store.
- By default, make sure that all the store items marked as valid in the
- database of the daemon actually exist in @file{/gnu/store}.
- When provided, @var{options} must be a comma-separated list containing one
- or more of @code{contents} and @code{repair}.
- When passing @option{--verify=contents}, the daemon computes the
- content hash of each store item and compares it against its hash in the
- database. Hash mismatches are reported as data corruptions. Because it
- traverses @emph{all the files in the store}, this command can take a
- long time, especially on systems with a slow disk drive.
- @cindex repairing the store
- @cindex corruption, recovering from
- Using @option{--verify=repair} or @option{--verify=contents,repair}
- causes the daemon to try to repair corrupt store items by fetching
- substitutes for them (@pxref{Substitutes}). Because repairing is not
- atomic, and thus potentially dangerous, it is available only to the
- system administrator. A lightweight alternative, when you know exactly
- which items in the store are corrupt, is @command{guix build --repair}
- (@pxref{Invoking guix build}).
- @item --optimize
- @cindex deduplication
- Optimize the store by hard-linking identical files---this is
- @dfn{deduplication}.
- The daemon performs deduplication after each successful build or archive
- import, unless it was started with @option{--disable-deduplication}
- (@pxref{Invoking guix-daemon, @option{--disable-deduplication}}). Thus,
- this option is primarily useful when the daemon was running with
- @option{--disable-deduplication}.
- @end table
- @node Invoking guix pull
- @section Invoking @command{guix pull}
- @cindex upgrading Guix
- @cindex updating Guix
- @cindex @command{guix pull}
- @cindex pull
- @cindex security, @command{guix pull}
- @cindex authenticity, of code obtained with @command{guix pull}
- Packages are installed or upgraded to the latest version available in
- the distribution currently available on your local machine. To update
- that distribution, along with the Guix tools, you must run @command{guix
- pull}: the command downloads the latest Guix source code and package
- descriptions, and deploys it. Source code is downloaded from a
- @uref{https://git-scm.com, Git} repository, by default the official
- GNU@tie{}Guix repository, though this can be customized. @command{guix
- pull} ensures that the code it downloads is @emph{authentic} by
- verifying that commits are signed by Guix developers.
- Specifically, @command{guix pull} downloads code from the @dfn{channels}
- (@pxref{Channels}) specified by one of the followings, in this order:
- @enumerate
- @item
- the @option{--channels} option;
- @item
- the user's @file{~/.config/guix/channels.scm} file;
- @item
- the system-wide @file{/etc/guix/channels.scm} file;
- @item
- the built-in default channels specified in the @code{%default-channels}
- variable.
- @end enumerate
- On completion, @command{guix package} will use packages and package
- versions from this just-retrieved copy of Guix. Not only that, but all
- the Guix commands and Scheme modules will also be taken from that latest
- version. New @command{guix} sub-commands added by the update also
- become available.
- Any user can update their Guix copy using @command{guix pull}, and the
- effect is limited to the user who ran @command{guix pull}. For
- instance, when user @code{root} runs @command{guix pull}, this has no
- effect on the version of Guix that user @code{alice} sees, and vice
- versa.
- The result of running @command{guix pull} is a @dfn{profile} available
- under @file{~/.config/guix/current} containing the latest Guix. Thus,
- make sure to add it to the beginning of your search path so that you use
- the latest version, and similarly for the Info manual
- (@pxref{Documentation}):
- @example
- export PATH="$HOME/.config/guix/current/bin:$PATH"
- export INFOPATH="$HOME/.config/guix/current/share/info:$INFOPATH"
- @end example
- The @option{--list-generations} or @option{-l} option lists past generations
- produced by @command{guix pull}, along with details about their provenance:
- @example
- $ guix pull -l
- Generation 1 Jun 10 2018 00:18:18
- guix 65956ad
- repository URL: https://git.savannah.gnu.org/git/guix.git
- branch: origin/master
- commit: 65956ad3526ba09e1f7a40722c96c6ef7c0936fe
- Generation 2 Jun 11 2018 11:02:49
- guix e0cc7f6
- repository URL: https://git.savannah.gnu.org/git/guix.git
- branch: origin/master
- commit: e0cc7f669bec22c37481dd03a7941c7d11a64f1d
- 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 used in manifests (@pxref{Invoking guix package, the
- @option{--manifest} option of @command{guix package}}). Thus you can insert
- an inferior package pretty much anywhere you would insert a regular package:
- in manifests, in the @code{packages} field of your @code{operating-system}
- declaration, and so on.
- @node Invoking guix describe
- @section Invoking @command{guix describe}
- @cindex reproducibility
- @cindex replicating Guix
- Often you may want to answer questions like: ``Which revision of Guix am I
- using?'' or ``Which channels am I using?'' This is useful information in many
- situations: if you want to @emph{replicate} an environment on a different
- machine or user account, if you want to report a bug or to determine what
- change in the channels you are using caused it, or if you want to record your
- system state for reproducibility purposes. The @command{guix describe}
- command answers these questions.
- When run from a @command{guix pull}ed @command{guix}, @command{guix describe}
- displays the channel(s) that it was built from, including their repository URL
- and commit IDs (@pxref{Channels}):
- @example
- $ guix describe
- Generation 10 Sep 03 2018 17:32:44 (current)
- guix e0fa68c
- repository URL: https://git.savannah.gnu.org/git/guix.git
- branch: master
- commit: e0fa68c7718fffd33d81af415279d6ddb518f727
- @end example
- If you're familiar with the Git version control system, this is similar in
- spirit to @command{git describe}; the output is also similar to that of
- @command{guix pull --list-generations}, but limited to the current generation
- (@pxref{Invoking guix pull, the @option{--list-generations} option}). Because
- the Git commit ID shown above unambiguously refers to a snapshot of Guix, this
- information is all it takes to describe the revision of Guix you're using, and
- also to replicate it.
- To make it easier to replicate Guix, @command{guix describe} can also be asked
- to return a list of channels instead of the human-readable description above:
- @example
- $ guix describe -f channels
- (list (channel
- (name 'guix)
- (url "https://git.savannah.gnu.org/git/guix.git")
- (commit
- "e0fa68c7718fffd33d81af415279d6ddb518f727")
- (introduction
- (make-channel-introduction
- "9edb3f66fd807b096b48283debdcddccfea34bad"
- (openpgp-fingerprint
- "BBB0 2DDF 2CEA F6A8 0D1D E643 A2A0 6DF2 A33A 54FA")))))
- @end example
- @noindent
- You can save this to a file and feed it to @command{guix pull -C} on some
- other machine or at a later point in time, which will instantiate @emph{this
- exact Guix revision} (@pxref{Invoking guix pull, the @option{-C} option}).
- From there on, since you're able to deploy the same revision of Guix, you can
- just as well @emph{replicate a complete software environment}. We humbly
- think that this is @emph{awesome}, and we hope you'll like it too!
- The details of the options supported by @command{guix describe} are as
- follows:
- @table @code
- @item --format=@var{format}
- @itemx -f @var{format}
- Produce output in the specified @var{format}, one of:
- @table @code
- @item human
- produce human-readable output;
- @item channels
- produce a list of channel specifications that can be passed to @command{guix
- pull -C} or installed as @file{~/.config/guix/channels.scm} (@pxref{Invoking
- guix pull});
- @item channels-sans-intro
- like @code{channels}, but omit the @code{introduction} field; use it to
- produce a channel specification suitable for Guix version 1.1.0 or
- earlier---the @code{introduction} field has to do with channel
- authentication (@pxref{Channels, Channel Authentication}) and is not
- supported by these older versions;
- @item json
- @cindex JSON
- produce a list of channel specifications in JSON format;
- @item recutils
- produce a list of channel specifications in Recutils format.
- @end table
- @item --list-formats
- Display available formats for @option{--format} option.
- @item --profile=@var{profile}
- @itemx -p @var{profile}
- Display information about @var{profile}.
- @end table
- @node Invoking guix archive
- @section Invoking @command{guix archive}
- @cindex @command{guix archive}
- @cindex archive
- The @command{guix archive} command allows users to @dfn{export} files
- from the store into a single archive, and to later @dfn{import} them on
- a machine that runs Guix.
- In particular, it allows store files to be transferred from one machine
- to the store on another machine.
- @quotation Note
- If you're looking for a way to produce archives in a format suitable for
- tools other than Guix, @pxref{Invoking guix pack}.
- @end quotation
- @cindex exporting store items
- To export store files as an archive to standard output, run:
- @example
- guix archive --export @var{options} @var{specifications}...
- @end example
- @var{specifications} may be either store file names or package
- specifications, as for @command{guix package} (@pxref{Invoking guix
- package}). For instance, the following command creates an archive
- containing the @code{gui} output of the @code{git} package and the main
- output of @code{emacs}:
- @example
- guix archive --export git:gui /gnu/store/...-emacs-24.3 > great.nar
- @end example
- If the specified packages are not built yet, @command{guix archive}
- automatically builds them. The build process may be controlled with the
- common build options (@pxref{Common Build Options}).
- To transfer the @code{emacs} package to a machine connected over SSH,
- one would run:
- @example
- guix archive --export -r emacs | ssh the-machine guix archive --import
- @end example
- @noindent
- Similarly, a complete user profile may be transferred from one machine
- to another like this:
- @example
- guix archive --export -r $(readlink -f ~/.guix-profile) | \
- ssh the-machine guix archive --import
- @end example
- @noindent
- However, note that, in both examples, all of @code{emacs} and the
- profile as well as all of their dependencies are transferred (due to
- @option{-r}), regardless of what is already available in the store on
- the target machine. The @option{--missing} option can help figure out
- which items are missing from the target store. The @command{guix copy}
- command simplifies and optimizes this whole process, so this is probably
- what you should use in this case (@pxref{Invoking guix copy}).
- @cindex nar, archive format
- @cindex normalized archive (nar)
- @cindex nar bundle, archive format
- Each store item is written in the @dfn{normalized archive} or @dfn{nar}
- format (described below), and the output of @command{guix archive
- --export} (and input of @command{guix archive --import}) is a @dfn{nar
- bundle}.
- The nar format is
- comparable in spirit to `tar', but with differences
- that make it more appropriate for our purposes. First, rather than
- recording all Unix metadata for each file, the nar format only mentions
- the file type (regular, directory, or symbolic link); Unix permissions
- and owner/group are dismissed. Second, the order in which directory
- entries are stored always follows the order of file names according to
- the C locale collation order. This makes archive production fully
- deterministic.
- That nar bundle format is essentially the concatenation of zero or more
- nars along with metadata for each store item it contains: its file name,
- references, corresponding derivation, and a digital signature.
- When exporting, the daemon digitally signs the contents of the archive,
- and that digital signature is appended. When importing, the daemon
- verifies the signature and rejects the import in case of an invalid
- signature or if the signing key is not authorized.
- @c FIXME: Add xref to daemon doc about signatures.
- The main options are:
- @table @code
- @item --export
- Export the specified store files or packages (see below). Write the
- resulting archive to the standard output.
- Dependencies are @emph{not} included in the output, unless
- @option{--recursive} is passed.
- @item -r
- @itemx --recursive
- When combined with @option{--export}, this instructs @command{guix archive}
- to include dependencies of the given items in the archive. Thus, the
- resulting archive is self-contained: it contains the closure of the
- exported store items.
- @item --import
- Read an archive from the standard input, and import the files listed
- therein into the store. Abort if the archive has an invalid digital
- signature, or if it is signed by a public key not among the authorized
- keys (see @option{--authorize} below).
- @item --missing
- Read a list of store file names from the standard input, one per line,
- and write on the standard output the subset of these files missing from
- the store.
- @item --generate-key[=@var{parameters}]
- @cindex signing, archives
- Generate a new key pair for the daemon. This is a prerequisite before
- archives can be exported with @option{--export}. This
- operation is usually instantaneous but it can take time if the system's
- entropy pool needs to be refilled. On Guix System,
- @code{guix-service-type} takes care of generating this key pair the
- first boot.
- The generated key pair is typically stored under @file{/etc/guix}, in
- @file{signing-key.pub} (public key) and @file{signing-key.sec} (private
- key, which must be kept secret). When @var{parameters} is omitted,
- an ECDSA key using the Ed25519 curve is generated, or, for Libgcrypt
- versions before 1.6.0, it is a 4096-bit RSA key.
- Alternatively, @var{parameters} can specify
- @code{genkey} parameters suitable for Libgcrypt (@pxref{General
- public-key related Functions, @code{gcry_pk_genkey},, gcrypt, The
- Libgcrypt Reference Manual}).
- @item --authorize
- @cindex authorizing, archives
- Authorize imports signed by the public key passed on standard input.
- The public key must be in ``s-expression advanced format''---i.e., the
- same format as the @file{signing-key.pub} file.
- The list of authorized keys is kept in the human-editable file
- @file{/etc/guix/acl}. The file contains
- @url{https://people.csail.mit.edu/rivest/Sexp.txt, ``advanced-format
- s-expressions''} and is structured as an access-control list in the
- @url{https://theworld.com/~cme/spki.txt, Simple Public-Key Infrastructure
- (SPKI)}.
- @item --extract=@var{directory}
- @itemx -x @var{directory}
- Read a single-item archive as served by substitute servers
- (@pxref{Substitutes}) and extract it to @var{directory}. This is a
- low-level operation needed in only very narrow use cases; see below.
- For example, the following command extracts the substitute for Emacs
- served by @code{@value{SUBSTITUTE-SERVER-1}} to @file{/tmp/emacs}:
- @example
- $ wget -O - \
- https://@value{SUBSTITUTE-SERVER-1}/nar/gzip/@dots{}-emacs-24.5 \
- | gunzip | guix archive -x /tmp/emacs
- @end example
- Single-item archives are different from multiple-item archives produced
- by @command{guix archive --export}; they contain a single store item,
- and they do @emph{not} embed a signature. Thus this operation does
- @emph{no} signature verification and its output should be considered
- unsafe.
- The primary purpose of this operation is to facilitate inspection of
- archive contents coming from possibly untrusted substitute servers
- (@pxref{Invoking guix challenge}).
- @item --list
- @itemx -t
- Read a single-item archive as served by substitute servers
- (@pxref{Substitutes}) and print the list of files it contains, as in
- this example:
- @example
- $ wget -O - \
- https://@value{SUBSTITUTE-SERVER-1}/nar/lzip/@dots{}-emacs-26.3 \
- | lzip -d | guix archive -t
- @end example
- @end table
- @c *********************************************************************
- @node Channels
- @chapter Channels
- @cindex channels
- @cindex @file{channels.scm}, configuration file
- @cindex configuration file for channels
- @cindex @command{guix pull}, configuration file
- @cindex configuration of @command{guix pull}
- Guix and its package collection are updated by running @command{guix pull}
- (@pxref{Invoking guix pull}). By default @command{guix pull} downloads and
- deploys Guix itself from the official GNU@tie{}Guix repository. This can be
- customized by defining @dfn{channels} in the
- @file{~/.config/guix/channels.scm} file. A channel specifies a URL and branch
- of a Git repository to be deployed, and @command{guix pull} can be instructed
- to pull from one or more channels. In other words, channels can be used
- to @emph{customize} and to @emph{extend} Guix, as we will see below.
- Guix is able to take into account security concerns and deal with authenticated
- updates.
- @menu
- * Specifying Additional Channels:: Extending the package collection.
- * Using a Custom Guix Channel:: Using a customized Guix.
- * Replicating Guix:: Running the @emph{exact same} Guix.
- * Channel Authentication:: How Guix verifies what it fetches.
- * Channels with Substitutes:: Using channels with available substitutes.
- * Creating a Channel:: How to write your custom channel.
- * Package Modules in a Sub-directory:: Specifying the channel's package modules location.
- * Declaring Channel Dependencies:: How to depend on other channels.
- * Specifying Channel Authorizations:: Defining channel authors authorizations.
- * Primary URL:: Distinguishing mirror to original.
- * Writing Channel News:: Communicating information to channel's users.
- @end menu
- @node Specifying Additional Channels
- @section Specifying Additional Channels
- @cindex extending the package collection (channels)
- @cindex variant packages (channels)
- You can specify @emph{additional channels} to pull from. To use a channel, write
- @code{~/.config/guix/channels.scm} to instruct @command{guix pull} to pull from it
- @emph{in addition} to the default Guix channel(s):
- @vindex %default-channels
- @lisp
- ;; Add variant packages to those Guix provides.
- (cons (channel
- (name 'variant-packages)
- (url "https://example.org/variant-packages.git"))
- %default-channels)
- @end lisp
- @noindent
- Note that the snippet above is (as always!)@: Scheme code; we use @code{cons} to
- add a channel the list of channels that the variable @code{%default-channels}
- is bound to (@pxref{Pairs, @code{cons} and lists,, guile, GNU Guile Reference
- Manual}). With this file in place, @command{guix pull} builds not only Guix
- but also the package modules from your own repository. The result in
- @file{~/.config/guix/current} is the union of Guix with your own package
- modules:
- @example
- $ guix pull --list-generations
- @dots{}
- Generation 19 Aug 27 2018 16:20:48
- guix d894ab8
- repository URL: https://git.savannah.gnu.org/git/guix.git
- branch: master
- commit: d894ab8e9bfabcefa6c49d9ba2e834dd5a73a300
- variant-packages dd3df5e
- repository URL: https://example.org/variant-packages.git
- branch: master
- commit: dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb
- 11 new packages: variant-gimp, variant-emacs-with-cool-features, @dots{}
- 4 packages upgraded: emacs-racket-mode@@0.0.2-2.1b78827, @dots{}
- @end example
- @noindent
- The output of @command{guix pull} above shows that Generation@tie{}19 includes
- both Guix and packages from the @code{variant-personal-packages} channel. Among
- the new and upgraded packages that are listed, some like @code{variant-gimp} and
- @code{variant-emacs-with-cool-features} might come from
- @code{variant-packages}, while others come from the Guix default channel.
- @node Using a Custom Guix Channel
- @section Using a Custom Guix Channel
- The channel called @code{guix} specifies where Guix itself---its command-line
- tools as well as its package collection---should be downloaded. For instance,
- suppose you want to update from another copy of the Guix repository at
- @code{example.org}, and specifically the @code{super-hacks} branch, you can
- write in @code{~/.config/guix/channels.scm} this specification:
- @lisp
- ;; Tell 'guix pull' to use another repo.
- (list (channel
- (name 'guix)
- (url "https://example.org/another-guix.git")
- (branch "super-hacks")))
- @end lisp
- @noindent
- From there on, @command{guix pull} will fetch code from the @code{super-hacks}
- branch of the repository at @code{example.org}. The authentication concern is
- addressed below ((@pxref{Channel Authentication}).
- @node Replicating Guix
- @section Replicating Guix
- @cindex pinning, channels
- @cindex replicating Guix
- @cindex reproducibility, of Guix
- The @command{guix pull --list-generations} output above shows precisely which
- commits were used to build this instance of Guix. We can thus replicate it,
- say, on another machine, by providing a channel specification in
- @file{~/.config/guix/channels.scm} that is ``pinned'' to these commits:
- @lisp
- ;; Deploy specific commits of my channels of interest.
- (list (channel
- (name 'guix)
- (url "https://git.savannah.gnu.org/git/guix.git")
- (commit "6298c3ffd9654d3231a6f25390b056483e8f407c"))
- (channel
- (name 'variant-packages)
- (url "https://example.org/variant-packages.git")
- (commit "dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb")))
- @end lisp
- The @command{guix describe --format=channels} command can even generate this
- list of channels directly (@pxref{Invoking guix describe}). The resulting
- file can be used with the -C options of @command{guix pull}
- (@pxref{Invoking guix pull}) or @command{guix time-machine}
- (@pxref{Invoking guix time-machine}).
- At this point the two machines run the @emph{exact same Guix}, with access to
- the @emph{exact same packages}. The output of @command{guix build gimp} on
- one machine will be exactly the same, bit for bit, as the output of the same
- command on the other machine. It also means both machines have access to all
- the source code of Guix and, transitively, to all the source code of every
- package it defines.
- This gives you super powers, allowing you to track the provenance of binary
- artifacts with very fine grain, and to reproduce software environments at
- will---some sort of ``meta reproducibility'' capabilities, if you will.
- @xref{Inferiors}, for another way to take advantage of these super powers.
- @node Channel Authentication
- @section Channel Authentication
- @anchor{channel-authentication}
- @cindex authentication, of channel code
- The @command{guix pull} and @command{guix time-machine} commands
- @dfn{authenticate} the code retrieved from channels: they make sure each
- commit that is fetched is signed by an authorized developer. The goal
- is to protect from unauthorized modifications to the channel that would
- lead users to run malicious code.
- As a user, you must provide a @dfn{channel introduction} in your
- channels file so that Guix knows how to authenticate its first commit.
- A channel specification, including its introduction, looks something
- along these lines:
- @lisp
- (channel
- (name 'some-channel)
- (url "https://example.org/some-channel.git")
- (introduction
- (make-channel-introduction
- "6f0d8cc0d88abb59c324b2990bfee2876016bb86"
- (openpgp-fingerprint
- "CABB A931 C0FF EEC6 900D 0CFB 090B 1199 3D9A EBB5"))))
- @end lisp
- The specification above shows the name and URL of the channel. The call
- to @code{make-channel-introduction} above specifies that authentication
- of this channel starts at commit @code{6f0d8cc@dots{}}, which is signed
- by the OpenPGP key with fingerprint @code{CABB A931@dots{}}.
- For the main channel, called @code{guix}, you automatically get that
- information from your Guix installation. For other channels, include
- the channel introduction provided by the channel authors in your
- @file{channels.scm} file. Make sure you retrieve the channel
- introduction from a trusted source since that is the root of your trust.
- If you're curious about the authentication mechanics, read on!
- @node Channels with Substitutes
- @section Channels with Substitutes
- When running @command{guix pull}, Guix will first compile the
- definitions of every available package. This is an expensive operation
- for which substitutes (@pxref{Substitutes}) may be available. The
- following snippet in @file{channels.scm} will ensure that @command{guix
- pull} uses the latest commit with available substitutes for the package
- definitions: this is done by querying the continuous integration
- server at @url{https://ci.guix.gnu.org}.
- @lisp
- (use-modules (guix ci))
- (list (channel-with-substitutes-available
- %default-guix-channel
- "https://ci.guix.gnu.org"))
- @end lisp
- Note that this does not mean that all the packages that you will
- install after running @command{guix pull} will have available
- substitutes. It only ensures that @command{guix pull} will not try to
- compile package definitions. This is particularly useful when using
- machines with limited resources.
- @node Creating a Channel
- @section Creating a Channel
- @cindex personal packages (channels)
- @cindex channels, for personal packages
- Let's say you have a bunch of custom package variants or personal packages
- that you think would make little sense to contribute to the Guix project, but
- would like to have these packages transparently available to you at the
- command line. You would first write modules containing those package
- definitions (@pxref{Package Modules}), maintain them in a Git repository, and
- then you and anyone else can use it as an additional channel to get packages
- from. Neat, no?
- @c What follows stems from discussions at
- @c <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=22629#134> as well as
- @c earlier discussions on guix-devel@gnu.org.
- @quotation Warning
- Before you, dear user, shout---``woow this is @emph{soooo coool}!''---and
- publish your personal channel to the world, we would like to share a few words
- of caution:
- @itemize
- @item
- Before publishing a channel, please consider contributing your package
- definitions to Guix proper (@pxref{Contributing}). Guix as a project is open
- to free software of all sorts, and packages in Guix proper are readily
- available to all Guix users and benefit from the project's quality assurance
- process.
- @item
- When you maintain package definitions outside Guix, we, Guix developers,
- consider that @emph{the compatibility burden is on you}. Remember that
- package modules and package definitions are just Scheme code that uses various
- programming interfaces (APIs). We want to remain free to change these APIs to
- keep improving Guix, possibly in ways that break your channel. We never
- change APIs gratuitously, but we will @emph{not} commit to freezing APIs
- either.
- @item
- Corollary: if you're using an external channel and that channel breaks, please
- @emph{report the issue to the channel authors}, not to the Guix project.
- @end itemize
- You've been warned! Having said this, we believe external channels are a
- practical way to exert your freedom to augment Guix' package collection and to
- share your improvements, which are basic tenets of
- @uref{https://www.gnu.org/philosophy/free-sw.html, free software}. Please
- email us at @email{guix-devel@@gnu.org} if you'd like to discuss this.
- @end quotation
- To create a channel, create a Git repository containing your own package
- modules and make it available. The repository can contain anything, but a
- useful channel will contain Guile modules that export packages. Once you
- start using a channel, Guix will behave as if the root directory of that
- channel's Git repository has been added to the Guile load path (@pxref{Load
- Paths,,, guile, GNU Guile Reference Manual}). For example, if your channel
- contains a file at @file{my-packages/my-tools.scm} that defines a Guile
- module, then the module will be available under the name @code{(my-packages
- my-tools)}, and you will be able to use it like any other module
- (@pxref{Modules,,, guile, GNU Guile Reference Manual}).
- As a channel author, consider bundling authentication material with your
- channel so that users can authenticate it. @xref{Channel
- Authentication}, and @ref{Specifying Channel Authorizations}, for info
- on how to do it.
- @node Package Modules in a Sub-directory
- @section Package Modules in a Sub-directory
- @cindex subdirectory, channels
- As a channel author, you may want to keep your channel modules in a
- sub-directory. If your modules are in the sub-directory @file{guix}, you must
- add a meta-data file @file{.guix-channel} that contains:
- @lisp
- (channel
- (version 0)
- (directory "guix"))
- @end lisp
- @node Declaring Channel Dependencies
- @section Declaring Channel Dependencies
- @cindex dependencies, channels
- @cindex meta-data, channels
- Channel authors may decide to augment a package collection provided by other
- channels. They can declare their channel to be dependent on other channels in
- a meta-data file @file{.guix-channel}, which is to be placed in the root of
- the channel repository.
- The meta-data file should contain a simple S-expression like this:
- @lisp
- (channel
- (version 0)
- (dependencies
- (channel
- (name some-collection)
- (url "https://example.org/first-collection.git")
- ;; The 'introduction' bit below is optional: you would
- ;; provide it for dependencies that can be authenticated.
- (introduction
- (channel-introduction
- (version 0)
- (commit "a8883b58dc82e167c96506cf05095f37c2c2c6cd")
- (signer "CABB A931 C0FF EEC6 900D 0CFB 090B 1199 3D9A EBB5"))))
- (channel
- (name some-other-collection)
- (url "https://example.org/second-collection.git")
- (branch "testing"))))
- @end lisp
- In the above example this channel is declared to depend on two other channels,
- which will both be fetched automatically. The modules provided by the channel
- will be compiled in an environment where the modules of all these declared
- channels are available.
- For the sake of reliability and maintainability, you should avoid dependencies
- on channels that you don't control, and you should aim to keep the number of
- dependencies to a minimum.
- @node Specifying Channel Authorizations
- @section Specifying Channel Authorizations
- @cindex channel authorizations
- @anchor{channel-authorizations}
- As we saw above, Guix ensures the source code it pulls from channels
- comes from authorized developers. As a channel author, you need to
- specify the list of authorized developers in the
- @file{.guix-authorizations} file in the channel's Git repository. The
- authentication rule is simple: each commit must be signed by a key
- listed in the @file{.guix-authorizations} file of its parent
- commit(s)@footnote{Git commits form a @dfn{directed acyclic graph}
- (DAG). Each commit can have zero or more parents; ``regular'' commits
- have one parent and merge commits have two parent commits. Read
- @uref{https://eagain.net/articles/git-for-computer-scientists/, @i{Git
- for Computer Scientists}} for a great overview.} The
- @file{.guix-authorizations} file looks like this:
- @lisp
- ;; Example '.guix-authorizations' file.
- (authorizations
- (version 0) ;current file format version
- (("AD17 A21E F8AE D8F1 CC02 DBD9 F8AE D8F1 765C 61E3"
- (name "alice"))
- ("2A39 3FFF 68F4 EF7A 3D29 12AF 68F4 EF7A 22FB B2D5"
- (name "bob"))
- ("CABB A931 C0FF EEC6 900D 0CFB 090B 1199 3D9A EBB5"
- (name "charlie"))))
- @end lisp
- Each fingerprint is followed by optional key/value pairs, as in the
- example above. Currently these key/value pairs are ignored.
- This authentication rule creates a chicken-and-egg issue: how do we
- authenticate the first commit? Related to that: how do we deal with
- channels whose repository history contains unsigned commits and lack
- @file{.guix-authorizations}? And how do we fork existing channels?
- @cindex channel introduction
- Channel introductions answer these questions by describing the first
- commit of a channel that should be authenticated. The first time a
- channel is fetched with @command{guix pull} or @command{guix
- time-machine}, the command looks up the introductory commit and verifies
- that it is signed by the specified OpenPGP key. From then on, it
- authenticates commits according to the rule above.
- Additionally, your channel must provide all the OpenPGP keys that were
- ever mentioned in @file{.guix-authorizations}, stored as @file{.key}
- files, which can be either binary or ``ASCII-armored''. By default,
- those @file{.key} files are searched for in the branch named
- @code{keyring} but you can specify a different branch name in
- @code{.guix-channel} like so:
- @lisp
- (channel
- (version 0)
- (keyring-reference "my-keyring-branch"))
- @end lisp
- To summarize, as the author of a channel, there are three things you have
- to do to allow users to authenticate your code:
- @enumerate
- @item
- Export the OpenPGP keys of past and present committers with @command{gpg
- --export} and store them in @file{.key} files, by default in a branch
- named @code{keyring} (we recommend making it an @dfn{orphan branch}).
- @item
- Introduce an initial @file{.guix-authorizations} in the channel's
- repository. Do that in a signed commit (@pxref{Commit Access}, for
- information on how to sign Git commits.)
- @item
- Advertise the channel introduction, for instance on your channel's web
- page. The channel introduction, as we saw above, is the commit/key
- pair---i.e., the commit that introduced @file{.guix-authorizations}, and
- the fingerprint of the OpenPGP used to sign it.
- @end enumerate
- Before pushing to your public Git repository, you can run @command{guix
- git-authenticate} to verify that you did sign all the commits you are
- about to push with an authorized key:
- @example
- guix git authenticate @var{commit} @var{signer}
- @end example
- @noindent
- where @var{commit} and @var{signer} are your channel introduction.
- @xref{Invoking guix git authenticate}, for details.
- Publishing a signed channel requires discipline: any mistake, such as an
- unsigned commit or a commit signed by an unauthorized key, will prevent
- users from pulling from your channel---well, that's the whole point of
- authentication! Pay attention to merges in particular: merge commits
- are considered authentic if and only if they are signed by a key present
- in the @file{.guix-authorizations} file of @emph{both} branches.
- @node Primary URL
- @section Primary URL
- @cindex primary URL, channels
- Channel authors can indicate the primary URL of their channel's Git
- repository in the @file{.guix-channel} file, like so:
- @lisp
- (channel
- (version 0)
- (url "https://example.org/guix.git"))
- @end lisp
- This allows @command{guix pull} to determine whether it is pulling code
- from a mirror of the channel; when that is the case, it warns the user
- that the mirror might be stale and displays the primary URL@. That way,
- users cannot be tricked into fetching code from a stale mirror that does
- not receive security updates.
- This feature only makes sense for authenticated repositories, such as
- the official @code{guix} channel, for which @command{guix pull} ensures
- the code it fetches is authentic.
- @node Writing Channel News
- @section Writing Channel News
- @cindex news, for channels
- Channel authors may occasionally want to communicate to their users
- information about important changes in the channel. You'd send them all
- an email, but that's not convenient.
- Instead, channels can provide a @dfn{news file}; when the channel users
- run @command{guix pull}, that news file is automatically read and
- @command{guix pull --news} can display the announcements that correspond
- to the new commits that have been pulled, if any.
- To do that, channel authors must first declare the name of the news file
- in their @file{.guix-channel} file:
- @lisp
- (channel
- (version 0)
- (news-file "etc/news.txt"))
- @end lisp
- The news file itself, @file{etc/news.txt} in this example, must look
- something like this:
- @lisp
- (channel-news
- (version 0)
- (entry (tag "the-bug-fix")
- (title (en "Fixed terrible bug")
- (fr "Oh la la"))
- (body (en "@@emph@{Good news@}! It's fixed!")
- (eo "Certe ĝi pli bone funkcias nun!")))
- (entry (commit "bdcabe815cd28144a2d2b4bc3c5057b051fa9906")
- (title (en "Added a great package")
- (ca "Què vol dir guix?"))
- (body (en "Don't miss the @@code@{hello@} package!"))))
- @end lisp
- While the news file is using the Scheme syntax, avoid naming it with a
- @file{.scm} extension or else it will get picked up when building the
- channel and yield an error since it is not a valid module.
- Alternatively, you can move the channel module to a subdirectory and
- store the news file in another directory.
- The file consists of a list of @dfn{news entries}. Each entry is
- associated with a commit or tag: it describes changes made in this
- commit, possibly in preceding commits as well. Users see entries only
- the first time they obtain the commit the entry refers to.
- The @code{title} field should be a one-line summary while @code{body}
- can be arbitrarily long, and both can contain Texinfo markup
- (@pxref{Overview,,, texinfo, GNU Texinfo}). Both the title and body are
- a list of language tag/message tuples, which allows @command{guix pull}
- to display news in the language that corresponds to the user's locale.
- If you want to translate news using a gettext-based workflow, you can
- extract translatable strings with @command{xgettext} (@pxref{xgettext
- Invocation,,, gettext, GNU Gettext Utilities}). For example, assuming
- you write news entries in English first, the command below creates a PO
- file containing the strings to translate:
- @example
- xgettext -o news.po -l scheme -ken etc/news.txt
- @end example
- To sum up, yes, you could use your channel as a blog. But beware, this
- is @emph{not quite} what your users might expect.
- @c *********************************************************************
- @node Development
- @chapter Development
- @cindex software development
- If you are a software developer, Guix provides tools that you should find
- helpful---independently of the language you're developing in. This is what
- this chapter is about.
- The @command{guix 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{}3 and
- NumPy:
- @example
- guix environment --ad-hoc python-numpy python -- python3
- @end example
- Furthermore, one might want the dependencies of a package and also some
- additional packages that are not build-time or runtime dependencies, but
- are useful when developing nonetheless. Because of this, the
- @option{--ad-hoc} flag is positional. Packages appearing before
- @option{--ad-hoc} are interpreted as packages whose dependencies will be
- added to the environment. Packages appearing after are interpreted as
- packages that will be added to the environment directly. For example,
- the following command creates a Guix development environment that
- additionally includes Git and strace:
- @example
- guix environment --pure guix --ad-hoc git strace
- @end example
- @cindex container
- Sometimes it is desirable to isolate the environment as much as
- possible, for maximal purity and reproducibility. In particular, when
- using Guix on a host distro that is not Guix System, it is desirable to
- prevent access to @file{/usr/bin} and other system-wide resources from
- the development environment. For example, the following command spawns
- a Guile REPL in a ``container'' where only the store and the current
- working directory are mounted:
- @example
- guix environment --ad-hoc --container guile -- guile
- @end example
- @quotation Note
- The @option{--container} option requires Linux-libre 3.19 or newer.
- @end quotation
- @cindex certificates
- Another typical use case for containers is to run security-sensitive
- applications such as a web browser. To run Eolie, we must expose and
- share some files and directories; we include @code{nss-certs} and expose
- @file{/etc/ssl/certs/} for HTTPS authentication; finally we preserve the
- @env{DISPLAY} environment variable since containerized graphical
- applications won't display without it.
- @example
- guix environment --preserve='^DISPLAY$' --container --network \
- --expose=/etc/machine-id \
- --expose=/etc/ssl/certs/ \
- --share=$HOME/.local/share/eolie/=$HOME/.local/share/eolie/ \
- --ad-hoc eolie nss-certs dbus -- eolie
- @end example
- The available options are summarized below.
- @table @code
- @item --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 emacs-geiser
- @dots{}
- /gnu/store/@dots{}-pack.tar.gz
- @end example
- The result here is a tarball containing a @file{/gnu/store} directory
- with all the relevant packages. The resulting tarball contains a
- @dfn{profile} with the three packages of interest; the profile is the
- same as would be created by @command{guix package -i}. It is this
- mechanism that is used to create Guix's own standalone binary tarball
- (@pxref{Binary Installation}).
- Users of this pack would have to run
- @file{/gnu/store/@dots{}-profile/bin/guile} to run Guile, which you may
- find inconvenient. To work around it, you can create, say, a
- @file{/opt/gnu/bin} symlink to the profile:
- @example
- guix pack -S /opt/gnu/bin=bin guile emacs emacs-geiser
- @end example
- @noindent
- That way, users can happily type @file{/opt/gnu/bin/guile} and enjoy.
- @cindex relocatable binaries, with @command{guix pack}
- What if the recipient of your pack does not have root privileges on
- their machine, and thus cannot unpack it in the root file system? In
- that case, you will want to use the @option{--relocatable} option (see
- below). This option produces @dfn{relocatable binaries}, meaning they
- they can be placed anywhere in the file system hierarchy: in the example
- above, users can unpack your tarball in their home directory and
- directly run @file{./opt/gnu/bin/guile}.
- @cindex Docker, build an image with guix pack
- Alternatively, you can produce a pack in the Docker image format using
- the following command:
- @example
- guix pack -f docker -S /bin=bin guile guile-readline
- @end example
- @noindent
- The result is a tarball that can be passed to the @command{docker load}
- command, followed by @code{docker run}:
- @example
- docker load < @var{file}
- docker run -ti guile-guile-readline /bin/guile
- @end example
- @noindent
- where @var{file} is the image returned by @var{guix pack}, and
- @code{guile-guile-readline} is its ``image tag''. See the
- @uref{https://docs.docker.com/engine/reference/commandline/load/, Docker
- documentation} for more information.
- @cindex Singularity, build an image with guix pack
- @cindex SquashFS, build an image with guix pack
- Yet another option is to produce a SquashFS image with the following
- command:
- @example
- guix pack -f squashfs bash guile emacs emacs-geiser
- @end example
- @noindent
- The result is a SquashFS file system image that can either be mounted or
- directly be used as a file system container image with the
- @uref{https://www.sylabs.io/docs/, Singularity container execution
- environment}, using commands like @command{singularity shell} or
- @command{singularity exec}.
- Several command-line options allow you to customize your pack:
- @table @code
- @item --format=@var{format}
- @itemx -f @var{format}
- Produce a pack in the given @var{format}.
- The available formats are:
- @table @code
- @item tarball
- This is the default format. It produces a tarball containing all the
- specified binaries and symlinks.
- @item docker
- This produces a tarball that follows the
- @uref{https://github.com/docker/docker/blob/master/image/spec/v1.2.md,
- Docker Image Specification}. The ``repository name'' as it appears in
- the output of the @command{docker images} command is computed from
- package names passed on the command line or in the manifest file.
- @item squashfs
- This produces a SquashFS image containing all the specified binaries and
- symlinks, as well as empty mount points for virtual file systems like
- procfs.
- @quotation Note
- Singularity @emph{requires} you to provide @file{/bin/sh} in the image.
- For that reason, @command{guix pack -f squashfs} always implies @code{-S
- /bin=bin}. Thus, your @command{guix pack} invocation must always start
- with something like:
- @example
- guix pack -f squashfs bash @dots{}
- @end example
- If you forget the @code{bash} (or similar) package, @command{singularity
- run} and @command{singularity exec} will fail with an unhelpful ``no
- such file or directory'' message.
- @end quotation
- @item deb
- This produces a Debian archive (a package with the @samp{.deb} file
- extension) containing all the specified binaries and symbolic links,
- that can be installed on top of any dpkg-based GNU(/Linux) distribution.
- Advanced options can be revealed via the @option{--help-deb-format}
- option. They allow embedding control files for more fine-grained
- control, such as activating specific triggers or providing a maintainer
- configure script to run arbitrary setup code upon installation.
- @example
- guix pack -f deb -C xz -S /usr/bin/hello=bin/hello hello
- @end example
- @quotation Note
- Because archives produced with @command{guix pack} contain a collection
- of store items and because each @command{dpkg} package must not have
- conflicting files, in practice that means you likely won't be able to
- install more than one such archive on a given system.
- @end quotation
- @quotation Warning
- @command{dpkg} will assume ownership of any files contained in the pack
- that it does @emph{not} know about. It is unwise to install
- Guix-produced @samp{.deb} files on a system where @file{/gnu/store} is
- shared by other software, such as a Guix installation or other, non-deb
- packs.
- @end quotation
- @end table
- @cindex relocatable binaries
- @item --relocatable
- @itemx -R
- Produce @dfn{relocatable binaries}---i.e., binaries that can be placed
- anywhere in the file system hierarchy and run from there.
- When this option is passed once, the resulting binaries require support for
- @dfn{user namespaces} in the kernel Linux; when passed
- @emph{twice}@footnote{Here's a trick to memorize it: @code{-RR}, which adds
- PRoot support, can be thought of as the abbreviation of ``Really
- Relocatable''. Neat, isn't it?}, relocatable binaries fall to back to
- other techniques if user namespaces are unavailable, and essentially
- work anywhere---see below for the implications.
- For example, if you create a pack containing Bash with:
- @example
- guix pack -RR -S /mybin=bin bash
- @end example
- @noindent
- ...@: you can copy that pack to a machine that lacks Guix, and from your
- home directory as a normal user, run:
- @example
- tar xf pack.tar.gz
- ./mybin/sh
- @end example
- @noindent
- In that shell, if you type @code{ls /gnu/store}, you'll notice that
- @file{/gnu/store} shows up and contains all the dependencies of
- @code{bash}, even though the machine actually lacks @file{/gnu/store}
- altogether! That is probably the simplest way to deploy Guix-built
- software on a non-Guix machine.
- @quotation Note
- By default, relocatable binaries rely on the @dfn{user namespace} feature of
- the kernel Linux, which allows unprivileged users to mount or change root.
- Old versions of Linux did not support it, and some GNU/Linux distributions
- turn it off.
- To produce relocatable binaries that work even in the absence of user
- namespaces, pass @option{--relocatable} or @option{-R} @emph{twice}. In that
- case, binaries will try user namespace support and fall back to another
- @dfn{execution engine} if user namespaces are not supported. The
- following execution engines are supported:
- @table @code
- @item default
- Try user namespaces and fall back to PRoot if user namespaces are not
- supported (see below).
- @item performance
- Try user namespaces and fall back to Fakechroot if user namespaces are
- not supported (see below).
- @item userns
- Run the program through user namespaces and abort if they are not
- supported.
- @item proot
- Run through PRoot. The @uref{https://proot-me.github.io/, PRoot} program
- provides the necessary
- support for file system virtualization. It achieves that by using the
- @code{ptrace} system call on the running program. This approach has the
- advantage to work without requiring special kernel support, but it incurs
- run-time overhead every time a system call is made.
- @item fakechroot
- Run through Fakechroot. @uref{https://github.com/dex4er/fakechroot/,
- Fakechroot} virtualizes file system accesses by intercepting calls to C
- library functions such as @code{open}, @code{stat}, @code{exec}, and so
- on. Unlike PRoot, it incurs very little overhead. However, it does not
- always work: for example, some file system accesses made from within the
- C library are not intercepted, and file system accesses made @i{via}
- direct syscalls are not intercepted either, leading to erratic behavior.
- @end table
- @vindex GUIX_EXECUTION_ENGINE
- When running a wrapped program, you can explicitly request one of the
- execution engines listed above by setting the
- @env{GUIX_EXECUTION_ENGINE} environment variable accordingly.
- @end quotation
- @cindex entry point, for Docker images
- @item --entry-point=@var{command}
- Use @var{command} as the @dfn{entry point} of the resulting pack, if the pack
- format supports it---currently @code{docker} and @code{squashfs} (Singularity)
- support it. @var{command} must be relative to the profile contained in the
- pack.
- The entry point specifies the command that tools like @code{docker run} or
- @code{singularity run} automatically start by default. For example, you can
- do:
- @example
- guix pack -f docker --entry-point=bin/guile guile
- @end example
- The resulting pack can easily be loaded and @code{docker run} with no extra
- arguments will spawn @code{bin/guile}:
- @example
- docker load -i pack.tar.gz
- docker run @var{image-id}
- @end example
- @item --expression=@var{expr}
- @itemx -e @var{expr}
- Consider the package @var{expr} evaluates to.
- This has the same purpose as the same-named option in @command{guix
- build} (@pxref{Additional Build Options, @option{--expression} in
- @command{guix build}}).
- @item --manifest=@var{file}
- @itemx -m @var{file}
- Use the packages contained in the manifest object returned by the Scheme
- code in @var{file}. This option can be repeated several times, in which
- case the manifests are concatenated.
- This has a similar purpose as the same-named option in @command{guix
- package} (@pxref{profile-manifest, @option{--manifest}}) and uses the
- same manifest files. It allows you to define a collection of packages
- once and use it both for creating profiles and for creating archives
- for use on machines that do not have Guix installed. Note that you can
- specify @emph{either} a manifest file @emph{or} a list of packages,
- but not both.
- @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
- @end menu
- @node Package Modules
- @section Package Modules
- From a programming viewpoint, the package definitions of the
- GNU distribution are provided by Guile modules in the @code{(gnu packages
- @dots{})} name space@footnote{Note that packages under the @code{(gnu
- packages @dots{})} module name space are not necessarily ``GNU
- packages''. This module naming scheme follows the usual Guile module
- naming convention: @code{gnu} means that these modules are distributed
- as part of the GNU system, and @code{packages} identifies modules that
- define packages.} (@pxref{Modules, Guile modules,, guile, GNU Guile
- Reference Manual}). For instance, the @code{(gnu packages emacs)}
- module exports a variable named @code{emacs}, which is bound to a
- @code{<package>} object (@pxref{Defining Packages}).
- The @code{(gnu packages @dots{})} module name space is
- automatically scanned for packages by the command-line tools. For
- instance, when running @code{guix install emacs}, all the @code{(gnu
- packages @dots{})} modules are scanned until one that exports a package
- object whose name is @code{emacs} is found. This package search
- facility is implemented in the @code{(gnu packages)} module.
- @cindex customization, of packages
- @cindex package module search path
- Users can store package definitions in modules with different
- names---e.g., @code{(my-packages emacs)}@footnote{Note that the file
- name and module name must match. For instance, the @code{(my-packages
- emacs)} module must be stored in a @file{my-packages/emacs.scm} file
- relative to the load path specified with @option{--load-path} or
- @env{GUIX_PACKAGE_PATH}. @xref{Modules and the File System,,,
- guile, GNU Guile Reference Manual}, for details.}. There are two ways to make
- these package definitions visible to the user interfaces:
- @enumerate
- @item
- By adding the directory containing your package modules to the search path
- with the @code{-L} flag of @command{guix package} and other commands
- (@pxref{Common Build Options}), or by setting the @env{GUIX_PACKAGE_PATH}
- environment variable described below.
- @item
- By defining a @dfn{channel} and configuring @command{guix pull} so that it
- pulls from it. A channel is essentially a Git repository containing package
- modules. @xref{Channels}, for more information on how to define and use
- channels.
- @end enumerate
- @env{GUIX_PACKAGE_PATH} works similarly to other search path variables:
- @defvr {Environment Variable} GUIX_PACKAGE_PATH
- This is a colon-separated list of directories to search for additional
- package modules. Directories listed in this variable take precedence
- over the own modules of the distribution.
- @end defvr
- The distribution is fully @dfn{bootstrapped} and @dfn{self-contained}:
- each package is built based solely on other packages in the
- distribution. The root of this dependency graph is a small set of
- @dfn{bootstrap binaries}, provided by the @code{(gnu packages
- bootstrap)} module. For more information on bootstrapping,
- @pxref{Bootstrapping}.
- @node Defining Packages
- @section Defining Packages
- The high-level interface to package definitions is implemented in the
- @code{(guix packages)} and @code{(guix build-system)} modules. As an
- example, the package definition, or @dfn{recipe}, for the GNU Hello
- package looks like this:
- @lisp
- (define-module (gnu packages hello)
- #:use-module (guix packages)
- #:use-module (guix download)
- #:use-module (guix build-system gnu)
- #:use-module (guix licenses)
- #:use-module (gnu packages gawk))
- (define-public hello
- (package
- (name "hello")
- (version "2.10")
- (source (origin
- (method url-fetch)
- (uri (string-append "mirror://gnu/hello/hello-" version
- ".tar.gz"))
- (sha256
- (base32
- "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i"))))
- (build-system gnu-build-system)
- (arguments '(#:configure-flags '("--enable-silent-rules")))
- (inputs (list gawk))
- (synopsis "Hello, GNU world: An example GNU package")
- (description "Guess what GNU Hello prints!")
- (home-page "https://www.gnu.org/software/hello/")
- (license gpl3+)))
- @end lisp
- @noindent
- Without being a Scheme expert, the reader may have guessed the meaning
- of the various fields here. This expression binds the variable
- @code{hello} to a @code{<package>} object, which is essentially a record
- (@pxref{SRFI-9, Scheme records,, guile, GNU Guile Reference Manual}).
- This package object can be inspected using procedures found in the
- @code{(guix packages)} module; for instance, @code{(package-name hello)}
- returns---surprise!---@code{"hello"}.
- With luck, you may be able to import part or all of the definition of
- the package you are interested in from another repository, using the
- @code{guix import} command (@pxref{Invoking guix import}).
- In the example above, @code{hello} is defined in a module of its own,
- @code{(gnu packages hello)}. Technically, this is not strictly
- necessary, but it is convenient to do so: all the packages defined in
- modules under @code{(gnu packages @dots{})} are automatically known to
- the command-line tools (@pxref{Package Modules}).
- There are a few points worth noting in the above package definition:
- @itemize
- @item
- The @code{source} field of the package is an @code{<origin>} object
- (@pxref{origin Reference}, for the complete reference).
- Here, the @code{url-fetch} method from @code{(guix download)} is used,
- meaning that the source is a file to be downloaded over FTP or HTTP.
- The @code{mirror://gnu} prefix instructs @code{url-fetch} to use one of
- the GNU mirrors defined in @code{(guix download)}.
- The @code{sha256} field specifies the expected SHA256 hash of the file
- being downloaded. It is mandatory, and allows Guix to check the
- integrity of the file. The @code{(base32 @dots{})} form introduces the
- base32 representation of the hash. You can obtain this information with
- @code{guix download} (@pxref{Invoking guix download}) and @code{guix
- hash} (@pxref{Invoking guix hash}).
- @cindex patches
- When needed, the @code{origin} form can also have a @code{patches} field
- listing patches to be applied, and a @code{snippet} field giving a
- Scheme expression to modify the source code.
- @item
- @cindex GNU Build System
- The @code{build-system} field specifies the procedure to build the
- package (@pxref{Build Systems}). Here, @code{gnu-build-system}
- represents the familiar GNU Build System, where packages may be
- configured, built, and installed with the usual @code{./configure &&
- make && make check && make install} command sequence.
- When you start packaging non-trivial software, you may need tools to
- manipulate those build phases, manipulate files, and so on. @xref{Build
- Utilities}, for more on this.
- @item
- The @code{arguments} field specifies options for the build system
- (@pxref{Build Systems}). Here it is interpreted by
- @code{gnu-build-system} as a request run @file{configure} with the
- @option{--enable-silent-rules} flag.
- @cindex quote
- @cindex quoting
- @findex '
- @findex quote
- 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 add
- an input, a reference to 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. @xref{Version Numbers}, for
- guidelines.
- @item @code{source}
- An object telling how the source code for the package should be
- acquired. Most of the time, this is an @code{origin} object, which
- denotes a file fetched from the Internet (@pxref{origin Reference}). It
- can also be any other ``file-like'' object such as a @code{local-file},
- which denotes a file from the local file system (@pxref{G-Expressions,
- @code{local-file}}).
- @item @code{build-system}
- The build system that should be used to build the package (@pxref{Build
- Systems}).
- @item @code{arguments} (default: @code{'()})
- The arguments that should be passed to the build system. This is a
- list, typically containing sequential keyword-value pairs.
- @item @code{inputs} (default: @code{'()})
- @itemx @code{native-inputs} (default: @code{'()})
- @itemx @code{propagated-inputs} (default: @code{'()})
- @cindex inputs, of packages
- These fields list dependencies of the package. Each element of these
- lists is either a package, origin, or other ``file-like object''
- (@pxref{G-Expressions}); to specify the output of that file-like object
- that should be used, pass a two-element list where the second element is
- the output (@pxref{Packages with Multiple Outputs}, for more on package
- outputs). For example, the list below specifies three inputs:
- @lisp
- (list libffi libunistring
- `(,glib "bin")) ;the "bin" output of GLib
- @end lisp
- In the example above, the @code{"out"} output of @code{libffi} and
- @code{libunistring} is used.
- @quotation Compatibility Note
- Until version 1.3.0, input lists were a list of tuples,
- where each tuple has a label for the input (a string) as its
- first element, a package, origin, or derivation as its second element,
- and optionally the name of the output thereof that should be used, which
- defaults to @code{"out"}. For example, the list below is equivalent to
- the one above, but using the @dfn{old input style}:
- @lisp
- ;; Old input style (deprecated).
- `(("libffi" ,libffi)
- ("libunistring" ,libunistring)
- ("glib:bin" ,glib "bin")) ;the "bin" output of GLib
- @end lisp
- This style is now deprecated; it is still supported but support will be
- removed in a future version. It should not be used for new package
- definitions. @xref{Invoking guix style}, on how to migrate to the new
- style.
- @end quotation
- @cindex cross compilation, package dependencies
- The distinction between @code{native-inputs} and @code{inputs} is
- necessary when considering cross-compilation. When cross-compiling,
- dependencies listed in @code{inputs} are built for the @emph{target}
- architecture; conversely, dependencies listed in @code{native-inputs}
- are built for the architecture of the @emph{build} machine.
- @code{native-inputs} is typically used to list tools needed at
- build time, but not at run time, such as Autoconf, Automake, pkg-config,
- Gettext, or Bison. @command{guix lint} can report likely mistakes in
- this area (@pxref{Invoking guix lint}).
- @anchor{package-propagated-inputs}
- Lastly, @code{propagated-inputs} is similar to @code{inputs}, but the
- specified packages will be automatically installed to profiles
- (@pxref{Features, the role of profiles in Guix}) alongside the package
- they belong to (@pxref{package-cmd-propagated-inputs, @command{guix
- package}}, for information on how @command{guix package} deals with
- propagated inputs).
- For example this is necessary when packaging a C/C++ library that needs
- headers of another library to compile, or when a pkg-config file refers
- to another one @i{via} its @code{Requires} field.
- Another example where @code{propagated-inputs} is useful is for languages
- that lack a facility to record the run-time search path akin to the
- @code{RUNPATH} of ELF files; this includes Guile, Python, Perl, and
- more. When packaging libraries written in those languages, ensure they
- can find library code they depend on at run time by listing run-time
- dependencies in @code{propagated-inputs} rather than @code{inputs}.
- @item @code{outputs} (default: @code{'("out")})
- The list of output names of the package. @xref{Packages with Multiple
- Outputs}, for typical uses of additional outputs.
- @item @code{native-search-paths} (default: @code{'()})
- @itemx @code{search-paths} (default: @code{'()})
- A list of @code{search-path-specification} objects describing
- search-path environment variables honored by the package.
- @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)
- (list this-package)
- '())))
- @end lisp
- It is an error to refer to @code{this-package} outside a package definition.
- @end deffn
- The following helper procedures are provided to help deal with package
- inputs.
- @deffn {Scheme Procedure} lookup-package-input @var{package} @var{name}
- @deffnx {Scheme Procedure} lookup-package-native-input @var{package} @var{name}
- @deffnx {Scheme Procedure} lookup-package-propagated-input @var{package} @var{name}
- @deffnx {Scheme Procedure} lookup-package-direct-input @var{package} @var{name}
- Look up @var{name} among @var{package}'s inputs (or native, propagated,
- or direct inputs). Return it if found, @code{#f} otherwise.
- @var{name} is the name of a package depended on. Here's how you might
- use it:
- @lisp
- (use-modules (guix packages) (gnu packages base))
- (lookup-package-direct-input coreutils "gmp")
- @result{} #<package gmp@@6.2.1 @dots{}>
- @end lisp
- In this example we obtain the @code{gmp} package that is among the
- direct inputs of @code{coreutils}.
- @end deffn
- Because packages are regular Scheme objects that capture a complete
- dependency graph and associated build procedures, it is often useful to
- write procedures that take a package and return a modified version
- thereof according to some parameters. Below are a few examples.
- @cindex tool chain, choosing a package's tool chain
- @deffn {Scheme Procedure} package-with-c-toolchain @var{package} @var{toolchain}
- Return a variant of @var{package} that uses @var{toolchain} instead of
- the default GNU C/C++ toolchain. @var{toolchain} must be a list of
- inputs (label/package tuples) providing equivalent functionality, such
- as the @code{gcc-toolchain} package.
- The example below returns a variant of the @code{hello} package built
- with GCC@tie{}10.x and the rest of the GNU tool chain (Binutils and the
- GNU C Library) instead of the default tool chain:
- @lisp
- (let ((toolchain (specification->package "gcc-toolchain@@10")))
- (package-with-c-toolchain hello `(("toolchain" ,toolchain))))
- @end lisp
- The build tool chain is part of the @dfn{implicit inputs} of
- packages---it's usually not listed as part of the various ``inputs''
- fields and is instead pulled in by the build system. Consequently, this
- procedure works by changing the build system of @var{package} so that it
- pulls in @var{toolchain} instead of the defaults. @ref{Build Systems},
- for more on build systems.
- @end deffn
- @node origin Reference
- @subsection @code{origin} Reference
- This section documents @dfn{origins}. An @code{origin} declaration
- specifies data that must be ``produced''---downloaded, usually---and
- whose content hash is known in advance. Origins are primarily used to
- represent the source code of packages (@pxref{Defining Packages}). For
- that reason, the @code{origin} form allows you to declare patches to
- apply to the original source code as well as code snippets to modify it.
- @deftp {Data Type} origin
- This is the data type representing a source code origin.
- @table @asis
- @item @code{uri}
- An object containing the URI of the source. The object type depends on
- the @code{method} (see below). For example, when using the
- @var{url-fetch} method of @code{(guix download)}, the valid @code{uri}
- values are: a URL represented as a string, or a list thereof.
- @cindex fixed-output derivations, for download
- @item @code{method}
- A monadic procedure that handles the given URI@. The procedure must
- accept at least three arguments: the value of the @code{uri} field and
- the hash algorithm and hash value specified by the @code{hash} field.
- It must return a store item or a derivation in the store monad
- (@pxref{The Store Monad}); most methods return a fixed-output derivation
- (@pxref{Derivations}).
- Commonly used methods include @code{url-fetch}, which fetches data from
- a URL, and @code{git-fetch}, which fetches data from a Git repository
- (see below).
- @item @code{sha256}
- A bytevector containing the SHA-256 hash of the source. This is
- equivalent to providing a @code{content-hash} SHA256 object in the
- @code{hash} field described below.
- @item @code{hash}
- The @code{content-hash} object of the source---see below for how to use
- @code{content-hash}.
- You can obtain this information using @code{guix download}
- (@pxref{Invoking guix download}) or @code{guix hash} (@pxref{Invoking
- guix hash}).
- @item @code{file-name} (default: @code{#f})
- The file name under which the source code should be saved. When this is
- @code{#f}, a sensible default value will be used in most cases. In case
- the source is fetched from a URL, the file name from the URL will be
- used. For version control checkouts, it is recommended to provide the
- file name explicitly because the default is not very descriptive.
- @item @code{patches} (default: @code{'()})
- A list of file names, origins, or file-like objects (@pxref{G-Expressions,
- file-like objects}) pointing to patches to be applied to the source.
- This list of patches must be unconditional. In particular, it cannot
- depend on the value of @code{%current-system} or
- @code{%current-target-system}.
- @item @code{snippet} (default: @code{#f})
- A G-expression (@pxref{G-Expressions}) or S-expression that will be run
- in the source directory. This is a convenient way to modify the source,
- sometimes more convenient than a patch.
- @item @code{patch-flags} (default: @code{'("-p1")})
- A list of command-line flags that should be passed to the @code{patch}
- command.
- @item @code{patch-inputs} (default: @code{#f})
- Input packages or derivations to the patching process. When this is
- @code{#f}, the usual set of inputs necessary for patching are provided,
- such as GNU@tie{}Patch.
- @item @code{modules} (default: @code{'()})
- A list of Guile modules that should be loaded during the patching
- process and while running the code in the @code{snippet} field.
- @item @code{patch-guile} (default: @code{#f})
- The Guile package that should be used in the patching process. When
- this is @code{#f}, a sensible default is used.
- @end table
- @end deftp
- @deftp {Data Type} content-hash @var{value} [@var{algorithm}]
- Construct a content hash object for the given @var{algorithm}, and with
- @var{value} as its hash value. When @var{algorithm} is omitted, assume
- it is @code{sha256}.
- @var{value} can be a literal string, in which case it is base32-decoded,
- or it can be a bytevector.
- The following forms are all equivalent:
- @lisp
- (content-hash "05zxkyz9bv3j9h0xyid1rhvh3klhsmrpkf3bcs6frvlgyr2gwilj")
- (content-hash "05zxkyz9bv3j9h0xyid1rhvh3klhsmrpkf3bcs6frvlgyr2gwilj"
- sha256)
- (content-hash (base32
- "05zxkyz9bv3j9h0xyid1rhvh3klhsmrpkf3bcs6frvlgyr2gwilj"))
- (content-hash (base64 "kkb+RPaP7uyMZmu4eXPVkM4BN8yhRd8BTHLslb6f/Rc=")
- sha256)
- @end lisp
- Technically, @code{content-hash} is currently implemented as a macro.
- It performs sanity checks at macro-expansion time, when possible, such
- as ensuring that @var{value} has the right size for @var{algorithm}.
- @end deftp
- As we have seen above, how exactly the data an origin refers to is
- retrieved is determined by its @code{method} field. The @code{(guix
- download)} module provides the most common method, @code{url-fetch},
- described below.
- @deffn {Scheme Procedure} url-fetch @var{url} @var{hash-algo} @var{hash} @
- [name] [#:executable? #f]
- Return a fixed-output derivation that fetches data from @var{url} (a
- string, or a list of strings denoting alternate URLs), which is expected
- to have hash @var{hash} of type @var{hash-algo} (a symbol). By default,
- the file name is the base name of URL; optionally, @var{name} can
- specify a different file name. When @var{executable?} is true, make the
- downloaded file executable.
- When one of the URL starts with @code{mirror://}, then its host part is
- interpreted as the name of a mirror scheme, taken from @file{%mirror-file}.
- Alternatively, when URL starts with @code{file://}, return the
- corresponding file name in the store.
- @end deffn
- Likewise, the @code{(guix git-download)} module defines the
- @code{git-fetch} origin method, which fetches data from a Git version
- control repository, and the @code{git-reference} data type to describe
- the repository and revision to fetch.
- @deffn {Scheme Procedure} git-fetch @var{ref} @var{hash-algo} @var{hash}
- Return a fixed-output derivation that fetches @var{ref}, a
- @code{<git-reference>} object. The output is expected to have recursive
- hash @var{hash} of type @var{hash-algo} (a symbol). Use @var{name} as
- the file name, or a generic name if @code{#f}.
- @end deffn
- @deftp {Data Type} git-reference
- This data type represents a Git reference for @code{git-fetch} to
- retrieve.
- @table @asis
- @item @code{url}
- The URL of the Git repository to clone.
- @item @code{commit}
- This string denotes either the commit to fetch (a hexadecimal string),
- or the tag to fetch. You can also use a ``short'' commit ID or a
- @command{git describe} style identifier such as
- @code{v1.0.1-10-g58d7909c97}.
- @item @code{recursive?} (default: @code{#f})
- This Boolean indicates whether to recursively fetch Git sub-modules.
- @end table
- The example below denotes the @code{v2.10} tag of the GNU@tie{}Hello
- repository:
- @lisp
- (git-reference
- (url "https://git.savannah.gnu.org/git/hello.git")
- (commit "v2.10"))
- @end lisp
- This is equivalent to the reference below, which explicitly names the
- commit:
- @lisp
- (git-reference
- (url "https://git.savannah.gnu.org/git/hello.git")
- (commit "dc7dc56a00e48fe6f231a58f6537139fe2908fb9"))
- @end lisp
- @end deftp
- For Mercurial repositories, the module @code{(guix hg-download)} defines
- the @code{hg-fetch} origin method and @code{hg-reference} data type for
- support of the Mercurial version control system.
- @deffn {Scheme Procedure} hg-fetch @var{ref} @var{hash-algo} @var{hash} @
- [name]
- Return a fixed-output derivation that fetches @var{ref}, a
- @code{<hg-reference>} object. The output is expected to have recursive
- hash @var{hash} of type @var{hash-algo} (a symbol). Use @var{name} as
- the file name, or a generic name if @code{#false}.
- @end deffn
- @node Defining Package Variants
- @section Defining Package Variants
- @cindex customizing packages
- @cindex variants, of packages
- One of the nice things with Guix is that, given a package definition,
- you can easily @emph{derive} variants of that package---for a different
- upstream version, with different dependencies, different compilation
- options, and so on. Some of these custom packages can be defined
- straight from the command line (@pxref{Package Transformation Options}).
- This section describes how to define package variants in code. This can
- be useful in ``manifests'' (@pxref{profile-manifest,
- @option{--manifest}}) and in your own package collection
- (@pxref{Creating a Channel}), among others!
- @cindex inherit, for package definitions
- As discussed earlier, packages are first-class objects in the Scheme
- language. The @code{(guix packages)} module provides the @code{package}
- construct to define new package objects (@pxref{package Reference}).
- The easiest way to define a package variant is using the @code{inherit}
- keyword together with @code{package}. This allows you to inherit from a
- package definition while overriding the fields you want.
- For example, given the @code{hello} variable, which contains a
- definition for the current version of GNU@tie{}Hello, here's how you
- would define a variant for version 2.2 (released in 2006, it's
- vintage!):
- @lisp
- (use-modules (gnu packages base)) ;for 'hello'
- (define hello-2.2
- (package
- (inherit hello)
- (version "2.2")
- (source (origin
- (method url-fetch)
- (uri (string-append "mirror://gnu/hello/hello-" version
- ".tar.gz"))
- (sha256
- (base32
- "0lappv4slgb5spyqbh6yl5r013zv72yqg2pcl30mginf3wdqd8k9"))))))
- @end lisp
- The example above corresponds to what the @option{--with-source} package
- transformation option does. Essentially @code{hello-2.2} preserves all
- the fields of @code{hello}, except @code{version} and @code{source},
- which it overrides. Note that the original @code{hello} variable is
- still there, in the @code{(gnu packages base)} module, unchanged. When
- you define a custom package like this, you are really @emph{adding} a
- new package definition; the original one remains available.
- You can just as well define variants with a different set of
- dependencies than the original package. For example, the default
- @code{gdb} package depends on @code{guile}, but since that is an
- optional dependency, you can define a variant that removes that
- dependency like so:
- @lisp
- (use-modules (gnu packages gdb)) ;for 'gdb'
- (define gdb-sans-guile
- (package
- (inherit gdb)
- (inputs (modify-inputs (package-inputs gdb)
- (delete "guile")))))
- @end lisp
- The @code{modify-inputs} form above removes the @code{"guile"} package
- from the @code{inputs} field of @code{gdb}. The @code{modify-inputs}
- macro is a helper that can prove useful anytime you want to remove, add,
- or replace package inputs.
- @deffn {Scheme Syntax} modify-inputs @var{inputs} @var{clauses}
- Modify the given package inputs, as returned by @code{package-inputs} & co.,
- according to the given clauses. The example below removes the GMP and ACL
- inputs of Coreutils and adds libcap to the back of the input list:
- @lisp
- (modify-inputs (package-inputs coreutils)
- (delete "gmp" "acl")
- (append libcap))
- @end lisp
- The example below replaces the @code{guile} package from the inputs of
- @code{guile-redis} with @code{guile-2.2}:
- @lisp
- (modify-inputs (package-inputs guile-redis)
- (replace "guile" guile-2.2))
- @end lisp
- The last type of clause is @code{prepend}, to add inputs to the front of
- the list.
- @end deffn
- In some cases, you may find it useful to write functions
- (``procedures'', in Scheme parlance) that return a package based on some
- parameters. For example, consider the @code{luasocket} library for the
- Lua programming language. We want to create @code{luasocket} packages
- for major versions of Lua. One way to do that is to define a procedure
- that takes a Lua package and returns a @code{luasocket} package that
- depends on it:
- @lisp
- (define (make-lua-socket name lua)
- ;; Return a luasocket package built with LUA.
- (package
- (name name)
- (version "3.0")
- ;; several fields omitted
- (inputs (list lua))
- (synopsis "Socket library for Lua")))
- (define-public lua5.1-socket
- (make-lua-socket "lua5.1-socket" lua-5.1))
- (define-public lua5.2-socket
- (make-lua-socket "lua5.2-socket" lua-5.2))
- @end lisp
- Here we have defined packages @code{lua5.1-socket} and
- @code{lua5.2-socket} by calling @code{make-lua-socket} with different
- arguments. @xref{Procedures,,, guile, GNU Guile Reference Manual}, for
- more info on procedures. Having top-level public definitions for these
- two packages means that they can be referred to from the command line
- (@pxref{Package Modules}).
- @cindex package transformations
- These are pretty simple package variants. As a convenience, the
- @code{(guix transformations)} module provides a high-level interface
- that directly maps to the more sophisticated package transformation
- options (@pxref{Package Transformation Options}):
- @deffn {Scheme Procedure} options->transformation @var{opts}
- Return a procedure that, when passed an object to build (package,
- derivation, etc.), applies the transformations specified by @var{opts} and returns
- the resulting objects. @var{opts} must be a list of symbol/string pairs such as:
- @lisp
- ((with-branch . "guile-gcrypt=master")
- (without-tests . "libgcrypt"))
- @end lisp
- Each symbol names a transformation and the corresponding string is an argument
- to that transformation.
- @end deffn
- For instance, a manifest equivalent to this command:
- @example
- guix build guix \
- --with-branch=guile-gcrypt=master \
- --with-debug-info=zlib
- @end example
- @noindent
- ... would look like this:
- @lisp
- (use-modules (guix transformations))
- (define transform
- ;; The package transformation procedure.
- (options->transformation
- '((with-branch . "guile-gcrypt=master")
- (with-debug-info . "zlib"))))
- (packages->manifest
- (list (transform (specification->package "guix"))))
- @end lisp
- @cindex input rewriting
- @cindex dependency graph rewriting
- The @code{options->transformation} procedure is convenient, but it's
- perhaps also not as flexible as you may like. How is it implemented?
- The astute reader probably noticed that most package transformation
- options go beyond the superficial changes shown in the first examples of
- this section: they involve @dfn{input rewriting}, whereby the dependency
- graph of a package is rewritten by replacing specific inputs by others.
- Dependency graph rewriting, for the purposes of swapping packages in the
- graph, is what the @code{package-input-rewriting} procedure in
- @code{(guix packages)} implements.
- @deffn {Scheme Procedure} package-input-rewriting @var{replacements} @
- [@var{rewrite-name}] [#:deep? #t]
- Return a procedure that, when passed a package, replaces its direct and
- indirect dependencies, including implicit inputs when @var{deep?} is
- true, according to @var{replacements}. @var{replacements} is a list of
- package pairs; the first element of each pair is the package to replace,
- and the second one is the replacement.
- Optionally, @var{rewrite-name} is a one-argument procedure that takes
- the name of a package and returns its new name after rewrite.
- @end deffn
- @noindent
- Consider this example:
- @lisp
- (define libressl-instead-of-openssl
- ;; This is a procedure to replace OPENSSL by LIBRESSL,
- ;; recursively.
- (package-input-rewriting `((,openssl . ,libressl))))
- (define git-with-libressl
- (libressl-instead-of-openssl git))
- @end lisp
- @noindent
- Here we first define a rewriting procedure that replaces @var{openssl}
- with @var{libressl}. Then we use it to define a @dfn{variant} of the
- @var{git} package that uses @var{libressl} instead of @var{openssl}.
- This is exactly what the @option{--with-input} command-line option does
- (@pxref{Package Transformation Options, @option{--with-input}}).
- The following variant of @code{package-input-rewriting} can match packages to
- be replaced by name rather than by identity.
- @deffn {Scheme Procedure} package-input-rewriting/spec @var{replacements} [#:deep? #t]
- Return a procedure that, given a package, applies the given
- @var{replacements} to all the package graph, including implicit inputs
- unless @var{deep?} is false. @var{replacements} is a list of
- spec/procedures pair; each spec is a package specification such as
- @code{"gcc"} or @code{"guile@@2"}, and each procedure takes a matching
- package and returns a replacement for that package.
- @end deffn
- The example above could be rewritten this way:
- @lisp
- (define libressl-instead-of-openssl
- ;; Replace all the packages called "openssl" with LibreSSL.
- (package-input-rewriting/spec `(("openssl" . ,(const libressl)))))
- @end lisp
- The key difference here is that, this time, packages are matched by spec and
- not by identity. In other words, any package in the graph that is called
- @code{openssl} will be replaced.
- A more generic procedure to rewrite a package dependency graph is
- @code{package-mapping}: it supports arbitrary changes to nodes in the
- graph.
- @deffn {Scheme Procedure} package-mapping @var{proc} [@var{cut?}] [#:deep? #f]
- Return a procedure that, given a package, applies @var{proc} to all the packages
- depended on and returns the resulting package. The procedure stops recursion
- when @var{cut?} returns true for a given package. When @var{deep?} is true, @var{proc} is
- applied to implicit inputs as well.
- @end deffn
- @node Build Systems
- @section Build Systems
- @cindex build system
- Each package definition specifies a @dfn{build system} and arguments for
- that build system (@pxref{Defining Packages}). This @code{build-system}
- field represents the build procedure of the package, as well as implicit
- dependencies of that build procedure.
- Build systems are @code{<build-system>} objects. The interface to
- create and manipulate them is provided by the @code{(guix build-system)}
- module, and actual build systems are exported by specific modules.
- @cindex bag (low-level package representation)
- Under the hood, build systems first compile package objects to
- @dfn{bags}. A @dfn{bag} is like a package, but with less
- ornamentation---in other words, a bag is a lower-level representation of
- a package, which includes all the inputs of that package, including some
- that were implicitly added by the build system. This intermediate
- representation is then compiled to a derivation (@pxref{Derivations}).
- The @code{package-with-c-toolchain} is an example of a way to change the
- implicit inputs that a package's build system pulls in (@pxref{package
- Reference, @code{package-with-c-toolchain}}).
- Build systems accept an optional list of @dfn{arguments}. In package
- definitions, these are passed @i{via} the @code{arguments} field
- (@pxref{Defining Packages}). They are typically keyword arguments
- (@pxref{Optional Arguments, keyword arguments in Guile,, guile, GNU
- Guile Reference Manual}). The value of these arguments is usually
- evaluated in the @dfn{build stratum}---i.e., by a Guile process launched
- by the daemon (@pxref{Derivations}).
- The main build system is @code{gnu-build-system}, which implements the
- standard build procedure for GNU and many other packages. It
- is provided by the @code{(guix build-system gnu)} module.
- @defvr {Scheme Variable} gnu-build-system
- @code{gnu-build-system} represents the GNU Build System, and variants
- thereof (@pxref{Configuration, configuration and makefile conventions,,
- standards, GNU Coding Standards}).
- @cindex build phases
- In a nutshell, packages using it are configured, built, and installed with
- the usual @code{./configure && make && make check && make install}
- command sequence. In practice, a few additional steps are often needed.
- All these steps are split up in separate @dfn{phases}.
- @xref{Build Phases}, for more info on build phases and ways to customize
- them.
- In addition, this build system ensures that the ``standard'' environment
- for GNU packages is available. This includes tools such as GCC, libc,
- Coreutils, Bash, Make, Diffutils, grep, and sed (see the @code{(guix
- build-system gnu)} module for a complete list). We call these the
- @dfn{implicit inputs} of a package, because package definitions do not
- have to mention them.
- This build system supports a number of keyword arguments, which can be
- passed @i{via} the @code{arguments} field of a package. Here are some
- of the main parameters:
- @table @code
- @item #:phases
- This argument specifies build-side code that evaluates to an alist of
- build phases. @xref{Build Phases}, for more information.
- @item #:configure-flags
- This is a list of flags (strings) passed to the @command{configure}
- script. @xref{Defining Packages}, for an example.
- @item #:make-flags
- This list of strings contains flags passed as arguments to
- @command{make} invocations in the @code{build}, @code{check}, and
- @code{install} phases.
- @item #:out-of-source?
- This Boolean, @code{#f} by default, indicates whether to run builds in a
- build directory separate from the source tree.
- When it is true, the @code{configure} phase creates a separate build
- directory, changes to that directory, and runs the @code{configure}
- script from there. This is useful for packages that require it, such as
- @code{glibc}.
- @item #:tests?
- This Boolean, @code{#t} by default, indicates whether the @code{check}
- phase should run the package's test suite.
- @item #:test-target
- This string, @code{"check"} by default, gives the name of the makefile
- target used by the @code{check} phase.
- @item #:parallel-build?
- @itemx #:parallel-tests?
- These Boolean values specify whether to build, respectively run the test
- suite, in parallel, with the @code{-j} flag of @command{make}. When
- they are true, @code{make} is passed @code{-j@var{n}}, where @var{n} is
- the number specified as the @option{--cores} option of
- @command{guix-daemon} or that of the @command{guix} client command
- (@pxref{Common Build Options, @option{--cores}}).
- @cindex RUNPATH, validation
- @item #:validate-runpath?
- This Boolean, @code{#t} by default, determines whether to ``validate''
- the @code{RUNPATH} of ELF binaries (@code{.so} shared libraries as well
- as executables) previously installed by the @code{install} phase.
- This validation step consists in making sure that all the shared
- libraries needed by an ELF binary, which are listed as
- @code{DT_NEEDED} entries in its @code{PT_DYNAMIC} segment, appear in the
- @code{DT_RUNPATH} entry of that binary. In other words, it ensures that
- running or using those binaries will not result in a ``file not found''
- error at run time. @xref{Options, @option{-rpath},, ld, The GNU
- Linker}, for more information on @code{RUNPATH}.
- @item #:substitutable?
- This Boolean, @code{#t} by default, tells whether the package outputs
- should be substitutable---i.e., whether users should be able to obtain
- substitutes for them instead of building locally (@pxref{Substitutes}).
- @item #:allowed-references
- @itemx #:disallowed-references
- When true, these arguments must be a list of dependencies that must not
- appear among the references of the build results. If, upon build
- completion, some of these references are retained, the build process
- fails.
- This is useful to ensure that a package does not erroneously keep a
- reference to some of it build-time inputs, in cases where doing so
- would, for example, unnecessarily increase its size (@pxref{Invoking
- guix size}).
- @end table
- Most other build systems support these keyword arguments.
- @end defvr
- Other @code{<build-system>} objects are defined to support other
- conventions and tools used by free software packages. They inherit most
- of @code{gnu-build-system}, and differ mainly in the set of inputs
- implicitly added to the build process, and in the list of phases
- executed. Some of these build systems are listed below.
- @defvr {Scheme Variable} ant-build-system
- This variable is exported by @code{(guix build-system ant)}. It
- implements the build procedure for Java packages that can be built with
- @url{https://ant.apache.org/, Ant build tool}.
- It adds both @code{ant} and the @dfn{Java Development Kit} (JDK) as
- provided by the @code{icedtea} package to the set of inputs. Different
- packages can be specified with the @code{#:ant} and @code{#:jdk}
- parameters, respectively.
- When the original package does not provide a suitable Ant build file,
- the parameter @code{#:jar-name} can be used to generate a minimal Ant
- build file @file{build.xml} with tasks to build the specified jar
- archive. In this case the parameter @code{#:source-dir} can be used to
- specify the source sub-directory, defaulting to ``src''.
- The @code{#:main-class} parameter can be used with the minimal ant
- buildfile to specify the main class of the resulting jar. This makes the
- jar file executable. The @code{#:test-include} parameter can be used to
- specify the list of junit tests to run. It defaults to
- @code{(list "**/*Test.java")}. The @code{#:test-exclude} can be used to
- disable some tests. It defaults to @code{(list "**/Abstract*.java")},
- because abstract classes cannot be run as tests.
- The parameter @code{#:build-target} can be used to specify the Ant task
- that should be run during the @code{build} phase. By default the
- ``jar'' task will be run.
- @end defvr
- @defvr {Scheme Variable} android-ndk-build-system
- @cindex Android distribution
- @cindex Android NDK build system
- This variable is exported by @code{(guix build-system android-ndk)}. It
- implements a build procedure for Android NDK (native development kit)
- packages using a Guix-specific build process.
- The build system assumes that packages install their public interface
- (header) files to the subdirectory @file{include} of the @code{out} output and
- their libraries to the subdirectory @file{lib} the @code{out} output.
- It's also assumed that the union of all the dependencies of a package
- has no conflicting files.
- For the time being, cross-compilation is not supported - so right now
- the libraries and header files are assumed to be host tools.
- @end defvr
- @defvr {Scheme Variable} asdf-build-system/source
- @defvrx {Scheme Variable} asdf-build-system/sbcl
- @defvrx {Scheme Variable} asdf-build-system/ecl
- These variables, exported by @code{(guix build-system asdf)}, implement
- build procedures for Common Lisp packages using
- @url{https://common-lisp.net/project/asdf/, ``ASDF''}. ASDF is a system
- definition facility for Common Lisp programs and libraries.
- The @code{asdf-build-system/source} system installs the packages in
- source form, and can be loaded using any common lisp implementation, via
- ASDF@. The others, such as @code{asdf-build-system/sbcl}, install binary
- systems in the format which a particular implementation understands.
- These build systems can also be used to produce executable programs, or
- lisp images which contain a set of packages pre-loaded.
- The build system uses naming conventions. For binary packages, the
- package name should be prefixed with the lisp implementation, such as
- @code{sbcl-} for @code{asdf-build-system/sbcl}.
- Additionally, the corresponding source package should be labeled using
- the same convention as python packages (see @ref{Python Modules}), using
- the @code{cl-} prefix.
- In order to create executable programs and images, the build-side
- procedures @code{build-program} and @code{build-image} can be used.
- They should be called in a build phase after the
- @code{create-asdf-configuration} phase, so that the system which was
- just built can be used within the resulting image. @code{build-program}
- requires a list of Common Lisp expressions to be passed as the
- @code{#:entry-program} argument.
- By default, all the @file{.asd} files present in the sources are read to
- find system definitions. The @code{#:asd-files} parameter can be used
- to specify the list of @file{.asd} files to read. Furthermore, if the
- package defines a system for its tests in a separate file, it will be
- loaded before the tests are run if it is specified by the
- @code{#:test-asd-file} parameter. If it is not set, the files
- @code{<system>-tests.asd}, @code{<system>-test.asd}, @code{tests.asd},
- and @code{test.asd} will be tried if they exist.
- If for some reason the package must be named in a different way than the
- naming conventions suggest, or if several systems must be compiled, the
- @code{#:asd-systems} parameter can be used to specify the list of system
- names.
- @end defvr
- @defvr {Scheme Variable} cargo-build-system
- @cindex Rust programming language
- @cindex Cargo (Rust build system)
- This variable is exported by @code{(guix build-system cargo)}. It
- supports builds of packages using Cargo, the build tool of the
- @uref{https://www.rust-lang.org, Rust programming language}.
- It adds @code{rustc} and @code{cargo} to the set of inputs.
- A different Rust package can be specified with the @code{#:rust} parameter.
- Regular cargo dependencies should be added to the package definition similarly
- to other packages; those needed only at build time to native-inputs, others to
- inputs. If you need to add source-only crates then you should add them to via
- the @code{#:cargo-inputs} parameter as a list of name and spec pairs, where the
- spec can be a package or a source definition. Note that the spec must
- evaluate to a path to a gzipped tarball which includes a @code{Cargo.toml}
- file at its root, or it will be ignored. Similarly, cargo dev-dependencies
- should be added to the package definition via the
- @code{#:cargo-development-inputs} parameter.
- In its @code{configure} phase, this build system will make any source inputs
- specified in the @code{#:cargo-inputs} and @code{#:cargo-development-inputs}
- parameters available to cargo. It will also remove an included
- @code{Cargo.lock} file to be recreated by @code{cargo} during the
- @code{build} phase. The @code{package} phase will run @code{cargo package}
- to create a source crate for future use. The @code{install} phase installs
- the binaries defined by the crate. Unless @code{install-source? #f} is
- defined it will also install a source crate repository of itself and unpacked
- sources, to ease in future hacking on rust packages.
- @end defvr
- @defvr {Scheme Variable} chicken-build-system
- This variable is exported by @code{(guix build-system chicken)}. It
- builds @uref{https://call-cc.org/, CHICKEN Scheme} modules, also called
- ``eggs'' or ``extensions''. CHICKEN generates C source code, which then
- gets compiled by a C compiler, in this case GCC.
- This build system adds @code{chicken} to the package inputs, as well as
- the packages of @code{gnu-build-system}.
- The build system can't (yet) deduce the egg's name automatically, so just like
- with @code{go-build-system} and its @code{#:import-path}, you should define
- @code{#:egg-name} in the package's @code{arguments} field.
- For example, if you are packaging the @code{srfi-1} egg:
- @lisp
- (arguments '(#:egg-name "srfi-1"))
- @end lisp
- Egg dependencies must be defined in @code{propagated-inputs}, not @code{inputs}
- because CHICKEN doesn't embed absolute references in compiled eggs.
- Test dependencies should go to @code{native-inputs}, as usual.
- @end defvr
- @defvr {Scheme Variable} copy-build-system
- This variable is exported by @code{(guix build-system copy)}. It
- supports builds of simple packages that don't require much compiling,
- mostly just moving files around.
- It adds much of the @code{gnu-build-system} packages to the set of
- inputs. Because of this, the @code{copy-build-system} does not require
- all the boilerplate code often needed for the
- @code{trivial-build-system}.
- To further simplify the file installation process, an
- @code{#:install-plan} argument is exposed to let the packager specify
- which files go where. The install plan is a list of @code{(@var{source}
- @var{target} [@var{filters}])}. @var{filters} are optional.
- @itemize
- @item When @var{source} matches a file or directory without trailing slash, install it to @var{target}.
- @itemize
- @item If @var{target} has a trailing slash, install @var{source} basename beneath @var{target}.
- @item Otherwise install @var{source} as @var{target}.
- @end itemize
- @item When @var{source} is a directory with a trailing slash, or when @var{filters} are used,
- the trailing slash of @var{target} is implied with the same meaning
- as above.
- @itemize
- @item Without @var{filters}, install the full @var{source} @emph{content} to @var{target}.
- @item With @var{filters} among @code{#:include}, @code{#:include-regexp}, @code{#:exclude},
- @code{#:exclude-regexp}, only select files are installed depending on
- the filters. Each filters is specified by a list of strings.
- @itemize
- @item With @code{#:include}, install all the files which the path suffix matches
- at least one of the elements in the given list.
- @item With @code{#:include-regexp}, install all the files which the
- subpaths match at least one of the regular expressions in the given
- list.
- @item The @code{#:exclude} and @code{#:exclude-regexp} filters
- are the complement of their inclusion counterpart. Without @code{#:include} flags,
- install all files but those matching the exclusion filters.
- If both inclusions and exclusions are specified, the exclusions are done
- on top of the inclusions.
- @end itemize
- @end itemize
- In all cases, the paths relative to @var{source} are preserved within
- @var{target}.
- @end itemize
- Examples:
- @itemize
- @item @code{("foo/bar" "share/my-app/")}: Install @file{bar} to @file{share/my-app/bar}.
- @item @code{("foo/bar" "share/my-app/baz")}: Install @file{bar} to @file{share/my-app/baz}.
- @item @code{("foo/" "share/my-app")}: Install the content of @file{foo} inside @file{share/my-app},
- e.g., install @file{foo/sub/file} to @file{share/my-app/sub/file}.
- @item @code{("foo/" "share/my-app" #:include ("sub/file"))}: Install only @file{foo/sub/file} to
- @file{share/my-app/sub/file}.
- @item @code{("foo/sub" "share/my-app" #:include ("file"))}: Install @file{foo/sub/file} to
- @file{share/my-app/file}.
- @end itemize
- @end defvr
- @cindex Clojure (programming language)
- @cindex simple Clojure build system
- @defvr {Scheme Variable} clojure-build-system
- This variable is exported by @code{(guix build-system clojure)}. It implements
- a simple build procedure for @uref{https://clojure.org/, Clojure} packages
- using plain old @code{compile} in Clojure. Cross-compilation is not supported
- yet.
- It adds @code{clojure}, @code{icedtea} and @code{zip} to the set of inputs.
- Different packages can be specified with the @code{#:clojure}, @code{#:jdk} and
- @code{#:zip} parameters, respectively.
- A list of source directories, test directories and jar names can be specified
- with the @code{#:source-dirs}, @code{#:test-dirs} and @code{#:jar-names}
- parameters, respectively. Compile directory and main class can be specified
- with the @code{#:compile-dir} and @code{#:main-class} parameters, respectively.
- Other parameters are documented below.
- This build system is an extension of @code{ant-build-system}, but with the
- following phases changed:
- @table @code
- @item build
- This phase calls @code{compile} in Clojure to compile source files and runs
- @command{jar} to create jars from both source files and compiled files
- according to the include list and exclude list specified in
- @code{#:aot-include} and @code{#:aot-exclude}, respectively. The exclude list
- has priority over the include list. These lists consist of symbols
- representing Clojure libraries or the special keyword @code{#:all} representing
- all Clojure libraries found under the source directories. The parameter
- @code{#:omit-source?} decides if source should be included into the jars.
- @item check
- This phase runs tests according to the include list and exclude list specified
- in @code{#:test-include} and @code{#:test-exclude}, respectively. Their
- meanings are analogous to that of @code{#:aot-include} and
- @code{#:aot-exclude}, except that the special keyword @code{#:all} now
- stands for all Clojure libraries found under the test directories. The
- parameter @code{#:tests?} decides if tests should be run.
- @item install
- This phase installs all jars built previously.
- @end table
- Apart from the above, this build system also contains an additional phase:
- @table @code
- @item install-doc
- This phase installs all top-level files with base name matching
- @code{%doc-regex}. A different regex can be specified with the
- @code{#:doc-regex} parameter. All files (recursively) inside the documentation
- directories specified in @code{#:doc-dirs} are installed as well.
- @end table
- @end defvr
- @defvr {Scheme Variable} cmake-build-system
- This variable is exported by @code{(guix build-system cmake)}. It
- implements the build procedure for packages using the
- @url{https://www.cmake.org, CMake build tool}.
- It automatically adds the @code{cmake} package to the set of inputs.
- Which package is used can be specified with the @code{#:cmake}
- parameter.
- The @code{#:configure-flags} parameter is taken as a list of flags
- passed to the @command{cmake} command. The @code{#:build-type}
- parameter specifies in abstract terms the flags passed to the compiler;
- it defaults to @code{"RelWithDebInfo"} (short for ``release mode with
- debugging information''), which roughly means that code is compiled with
- @code{-O2 -g}, as is the case for Autoconf-based packages by default.
- @end defvr
- @defvr {Scheme Variable} dune-build-system
- This variable is exported by @code{(guix build-system dune)}. It
- supports builds of packages using @uref{https://dune.build/, Dune}, a build
- tool for the OCaml programming language. It is implemented as an extension
- of the @code{ocaml-build-system} which is described below. As such, the
- @code{#:ocaml} and @code{#:findlib} parameters can be passed to this build
- system.
- It automatically adds the @code{dune} package to the set of inputs.
- Which package is used can be specified with the @code{#:dune}
- parameter.
- There is no @code{configure} phase because dune packages typically don't
- need to be configured. The @code{#:build-flags} parameter is taken as a
- list of flags passed to the @code{dune} command during the build.
- The @code{#:jbuild?} parameter can be passed to use the @code{jbuild}
- command instead of the more recent @code{dune} command while building
- a package. Its default value is @code{#f}.
- The @code{#:package} parameter can be passed to specify a package name, which
- is useful when a package contains multiple packages and you want to build
- only one of them. This is equivalent to passing the @code{-p} argument to
- @code{dune}.
- @end defvr
- @defvr {Scheme Variable} go-build-system
- This variable is exported by @code{(guix build-system go)}. It
- implements a build procedure for Go packages using the standard
- @url{https://golang.org/cmd/go/#hdr-Compile_packages_and_dependencies,
- Go build mechanisms}.
- The user is expected to provide a value for the key @code{#:import-path}
- and, in some cases, @code{#:unpack-path}. The
- @url{https://golang.org/doc/code.html#ImportPaths, import path}
- corresponds to the file system path expected by the package's build
- scripts and any referring packages, and provides a unique way to
- refer to a Go package. It is typically based on a combination of the
- package source code's remote URI and file system hierarchy structure. In
- some cases, you will need to unpack the package's source code to a
- different directory structure than the one indicated by the import path,
- and @code{#:unpack-path} should be used in such cases.
- Packages that provide Go libraries should install their source code into
- the built output. The key @code{#:install-source?}, which defaults to
- @code{#t}, controls whether or not the source code is installed. It can
- be set to @code{#f} for packages that only provide executable files.
- Packages can be cross-built, and if a specific architecture or operating
- system is desired then the keywords @code{#:goarch} and @code{#:goos}
- can be used to force the package to be built for that architecture and
- operating system. The combinations known to Go can be found
- @url{"https://golang.org/doc/install/source#environment", in their
- documentation}.
- @end defvr
- @defvr {Scheme Variable} glib-or-gtk-build-system
- This variable is exported by @code{(guix build-system glib-or-gtk)}. It
- is intended for use with packages making use of GLib or GTK+.
- This build system adds the following two phases to the ones defined by
- @code{gnu-build-system}:
- @table @code
- @item glib-or-gtk-wrap
- The phase @code{glib-or-gtk-wrap} ensures that programs in
- @file{bin/} are able to find GLib ``schemas'' and
- @uref{https://developer.gnome.org/gtk3/stable/gtk-running.html, GTK+
- modules}. This is achieved by wrapping the programs in launch scripts
- that appropriately set the @env{XDG_DATA_DIRS} and @env{GTK_PATH}
- environment variables.
- It is possible to exclude specific package outputs from that wrapping
- process by listing their names in the
- @code{#:glib-or-gtk-wrap-excluded-outputs} parameter. This is useful
- when an output is known not to contain any GLib or GTK+ binaries, and
- where wrapping would gratuitously add a dependency of that output on
- GLib and GTK+.
- @item glib-or-gtk-compile-schemas
- The phase @code{glib-or-gtk-compile-schemas} makes sure that all
- @uref{https://developer.gnome.org/gio/stable/glib-compile-schemas.html,
- GSettings schemas} of GLib are compiled. Compilation is performed by the
- @command{glib-compile-schemas} program. It is provided by the package
- @code{glib:bin} which is automatically imported by the build system.
- The @code{glib} package providing @command{glib-compile-schemas} can be
- specified with the @code{#:glib} parameter.
- @end table
- Both phases are executed after the @code{install} phase.
- @end defvr
- @defvr {Scheme Variable} guile-build-system
- This build system is for Guile packages that consist exclusively of Scheme
- code and that are so lean that they don't even have a makefile, let alone a
- @file{configure} script. It compiles Scheme code using @command{guild
- compile} (@pxref{Compilation,,, guile, GNU Guile Reference Manual}) and
- installs the @file{.scm} and @file{.go} files in the right place. It also
- installs documentation.
- This build system supports cross-compilation by using the
- @option{--target} option of @samp{guild compile}.
- Packages built with @code{guile-build-system} must provide a Guile package in
- their @code{native-inputs} field.
- @end defvr
- @defvr {Scheme Variable} julia-build-system
- This variable is exported by @code{(guix build-system julia)}. It
- implements the build procedure used by @uref{https://julialang.org/,
- julia} packages, which essentially is similar to running @samp{julia -e
- 'using Pkg; Pkg.add(package)'} in an environment where
- @env{JULIA_LOAD_PATH} contains the paths to all Julia package inputs.
- Tests are run by calling @code{/test/runtests.jl}.
- The Julia package name is read from the file @file{Project.toml}. This
- value can be overridden by passing the argument @code{#:julia-package-name}
- (which must be correctly capitalized).
- Julia packages usually manage their binary dependencies via
- @code{JLLWrappers.jl}, a Julia package that creates a module (named
- after the wrapped library followed by @code{_jll.jl}.
- To add the binary path @code{_jll.jl} packages, you need to patch the
- files under @file{src/wrappers/}, replacing the call to the macro
- @code{JLLWrappers.@@generate_wrapper_header}, adding as a second
- argument containing the store path the binary.
- As an example, in the MbedTLS Julia package, we add a build phase
- (@pxref{Build Phases}) to insert the absolute file name of the wrapped
- MbedTLS package:
- @lisp
- (add-after 'unpack 'override-binary-path
- (lambda* (#:key inputs #:allow-other-keys)
- (for-each (lambda (wrapper)
- (substitute* wrapper
- (("generate_wrapper_header.*")
- (string-append
- "generate_wrapper_header(\"MbedTLS\", \""
- (assoc-ref inputs "mbedtls-apache") "\")\n"))))
- ;; There's a Julia file for each platform, override them all.
- (find-files "src/wrappers/" "\\.jl$"))))
- @end lisp
- Some older packages that aren't using @file{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, its 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} minetest-mod-build-system
- This variable is exported by @code{(guix build-system minetest)}. It
- implements a build procedure for @uref{https://www.minetest.net, Minetest}
- mods, which consists of copying Lua code, images and other resources to
- the location Minetest searches for mods. The build system also minimises
- PNG images and verifies that Minetest can load the mod without errors.
- @end defvr
- @defvr {Scheme Variable} minify-build-system
- This variable is exported by @code{(guix build-system minify)}. It
- implements a minification procedure for simple JavaScript packages.
- It adds @code{uglify-js} to the set of inputs and uses it to compress
- all JavaScript files in the @file{src} directory. A different minifier
- package can be specified with the @code{#:uglify-js} parameter, but it
- is expected that the package writes the minified code to the standard
- output.
- When the input JavaScript files are not all located in the @file{src}
- directory, the parameter @code{#:javascript-files} can be used to
- specify a list of file names to feed to the minifier.
- @end defvr
- @defvr {Scheme Variable} ocaml-build-system
- This variable is exported by @code{(guix build-system ocaml)}. It implements
- a build procedure for @uref{https://ocaml.org, OCaml} packages, which consists
- of choosing the correct set of commands to run for each package. OCaml
- packages can expect many different commands to be run. This build system will
- try some of them.
- When the package has a @file{setup.ml} file present at the top-level, it will
- run @code{ocaml setup.ml -configure}, @code{ocaml setup.ml -build} and
- @code{ocaml setup.ml -install}. The build system will assume that this file
- was generated by @uref{http://oasis.forge.ocamlcore.org/, OASIS} and will take
- care of setting the prefix and enabling tests if they are not disabled. You
- can pass configure and build flags with the @code{#:configure-flags} and
- @code{#:build-flags}. The @code{#:test-flags} key can be passed to change the
- set of flags used to enable tests. The @code{#:use-make?} key can be used to
- bypass this system in the build and install phases.
- When the package has a @file{configure} file, it is assumed that it is a
- hand-made configure script that requires a different argument format than
- in the @code{gnu-build-system}. You can add more flags with the
- @code{#:configure-flags} key.
- When the package has a @file{Makefile} file (or @code{#:use-make?} is
- @code{#t}), it will be used and more flags can be passed to the build and
- install phases with the @code{#:make-flags} key.
- Finally, some packages do not have these files and use a somewhat standard
- location for its build system. In that case, the build system will run
- @code{ocaml pkg/pkg.ml} or @code{ocaml pkg/build.ml} and take care of
- providing the path to the required findlib module. Additional flags can
- be passed via the @code{#:build-flags} key. Install is taken care of by
- @command{opam-installer}. In this case, the @code{opam} package must
- be added to the @code{native-inputs} field of the package definition.
- Note that most OCaml packages assume they will be installed in the same
- directory as OCaml, which is not what we want in guix. In particular, they
- will install @file{.so} files in their module's directory, which is usually
- fine because it is in the OCaml compiler directory. In guix though, these
- libraries cannot be found and we use @env{CAML_LD_LIBRARY_PATH}. This
- variable points to @file{lib/ocaml/site-lib/stubslibs} and this is where
- @file{.so} libraries should be installed.
- @end defvr
- @defvr {Scheme Variable} python-build-system
- This variable is exported by @code{(guix build-system python)}. It
- implements the more or less standard build procedure used by Python
- packages, which consists in running @code{python setup.py build} and
- then @code{python setup.py install --prefix=/gnu/store/@dots{}}.
- For packages that install stand-alone Python programs under @code{bin/},
- it takes care of wrapping these programs so that their
- @env{GUIX_PYTHONPATH} environment variable points to all the Python
- libraries they depend on.
- Which Python package is used to perform the build can be specified with
- the @code{#:python} parameter. This is a useful way to force a package
- to be built for a specific version of the Python interpreter, which
- might be necessary if the package is only compatible with a single
- interpreter version.
- By default guix calls @code{setup.py} under control of
- @code{setuptools}, much like @command{pip} does. Some packages are not
- compatible with setuptools (and pip), thus you can disable this by
- setting the @code{#:use-setuptools?} parameter to @code{#f}.
- If a @code{"python"} output is available, the package is installed into it
- instead of the default @code{"out"} output. This is useful for packages that
- include a Python package as only a part of the software, and thus want to
- combine the phases of @code{python-build-system} with another build system.
- Python bindings are a common usecase.
- @end defvr
- @defvr {Scheme Variable} perl-build-system
- This variable is exported by @code{(guix build-system perl)}. It
- implements the standard build procedure for Perl packages, which either
- consists in running @code{perl Build.PL --prefix=/gnu/store/@dots{}},
- followed by @code{Build} and @code{Build install}; or in running
- @code{perl Makefile.PL PREFIX=/gnu/store/@dots{}}, followed by
- @code{make} and @code{make install}, depending on which of
- @code{Build.PL} or @code{Makefile.PL} is present in the package
- distribution. Preference is given to the former if both @code{Build.PL}
- and @code{Makefile.PL} exist in the package distribution. This
- preference can be reversed by specifying @code{#t} for the
- @code{#:make-maker?} parameter.
- The initial @code{perl Makefile.PL} or @code{perl Build.PL} invocation
- passes flags specified by the @code{#:make-maker-flags} or
- @code{#:module-build-flags} parameter, respectively.
- Which Perl package is used can be specified with @code{#:perl}.
- @end defvr
- @defvr {Scheme Variable} renpy-build-system
- This variable is exported by @code{(guix build-system renpy)}. It implements
- the more or less standard build procedure used by Ren'py games, which consists
- of loading @code{#:game} once, thereby creating bytecode for it.
- It further creates a wrapper script in @code{bin/} and a desktop entry in
- @code{share/applications}, both of which can be used to launch the game.
- Which Ren'py package is used can be specified with @code{#:renpy}.
- Games can also be installed in outputs other than ``out'' by using
- @code{#:output}.
- @end defvr
- @defvr {Scheme Variable} qt-build-system
- This variable is exported by @code{(guix build-system qt)}. It
- is intended for use with applications using Qt or KDE.
- This build system adds the following two phases to the ones defined by
- @code{cmake-build-system}:
- @table @code
- @item check-setup
- The phase @code{check-setup} prepares the environment for running
- the checks as commonly used by Qt test programs.
- For now this only sets some environment variables:
- @code{QT_QPA_PLATFORM=offscreen},
- @code{DBUS_FATAL_WARNINGS=0} and
- @code{CTEST_OUTPUT_ON_FAILURE=1}.
- This phase is added before the @code{check} phase.
- It's a separate phase to ease adjusting if necessary.
- @item qt-wrap
- The phase @code{qt-wrap}
- searches for Qt5 plugin paths, QML paths and some XDG in the inputs
- and output. In case some path is found, all programs in the output's
- @file{bin/}, @file{sbin/}, @file{libexec/} and @file{lib/libexec/} directories
- are wrapped in scripts defining the necessary environment variables.
- It is possible to exclude specific package outputs from that wrapping process
- by listing their names in the @code{#:qt-wrap-excluded-outputs} parameter.
- This is useful when an output is known not to contain any Qt binaries, and
- where wrapping would gratuitously add a dependency of that output on Qt, KDE,
- or such.
- This phase is added after the @code{install} phase.
- @end table
- @end defvr
- @defvr {Scheme Variable} r-build-system
- This variable is exported by @code{(guix build-system r)}. It
- implements the build procedure used by @uref{https://r-project.org, R}
- packages, which essentially is little more than running @samp{R CMD
- INSTALL --library=/gnu/store/@dots{}} in an environment where
- @env{R_LIBS_SITE} contains the paths to all R package inputs. Tests are
- run after installation using the R function
- @code{tools::testInstalledPackage}.
- @end defvr
- @defvr {Scheme Variable} rakudo-build-system
- This variable is exported by @code{(guix build-system rakudo)}. It
- implements the build procedure used by @uref{https://rakudo.org/,
- Rakudo} for @uref{https://perl6.org/, Perl6} packages. It installs the
- package to @code{/gnu/store/@dots{}/NAME-VERSION/share/perl6} and
- installs the binaries, library files and the resources, as well as wrap
- the files under the @code{bin/} directory. Tests can be skipped by
- passing @code{#f} to the @code{tests?} parameter.
- Which rakudo package is used can be specified with @code{rakudo}.
- Which perl6-tap-harness package used for the tests can be specified with
- @code{#:prove6} or removed by passing @code{#f} to the
- @code{with-prove6?} parameter.
- Which perl6-zef package used for tests and installing can be specified
- with @code{#:zef} or removed by passing @code{#f} to the
- @code{with-zef?} parameter.
- @end defvr
- @defvr {Scheme Variable} texlive-build-system
- This variable is exported by @code{(guix build-system texlive)}. It is
- used to build TeX packages in batch mode with a specified engine. The
- build system sets the @env{TEXINPUTS} variable to find all TeX source
- files in the inputs.
- By default it runs @code{luatex} on all files ending on @code{ins}. A
- different engine and format can be specified with the
- @code{#:tex-format} argument. Different build targets can be specified
- with the @code{#:build-targets} argument, which expects a list of file
- names. The build system adds only @code{texlive-bin} and
- @code{texlive-latex-base} (both from @code{(gnu packages tex}) to the
- inputs. Both can be overridden with the arguments @code{#:texlive-bin}
- and @code{#:texlive-latex-base}, respectively.
- The @code{#:tex-directory} parameter tells the build system where to
- install the built files under the texmf tree.
- @end defvr
- @defvr {Scheme Variable} ruby-build-system
- This variable is exported by @code{(guix build-system ruby)}. It
- implements the RubyGems build procedure used by Ruby packages, which
- involves running @code{gem build} followed by @code{gem install}.
- The @code{source} field of a package that uses this build system
- typically references a gem archive, since this is the format that Ruby
- developers use when releasing their software. The build system unpacks
- the gem archive, potentially patches the source, runs the test suite,
- repackages the gem, and installs it. Additionally, directories and
- tarballs may be referenced to allow building unreleased gems from Git or
- a traditional source release tarball.
- Which Ruby package is used can be specified with the @code{#:ruby}
- parameter. A list of additional flags to be passed to the @command{gem}
- command can be specified with the @code{#:gem-flags} parameter.
- @end defvr
- @defvr {Scheme Variable} waf-build-system
- This variable is exported by @code{(guix build-system waf)}. It
- implements a build procedure around the @code{waf} script. The common
- phases---@code{configure}, @code{build}, and @code{install}---are
- implemented by passing their names as arguments to the @code{waf}
- script.
- The @code{waf} script is executed by the Python interpreter. Which
- Python package is used to run the script can be specified with the
- @code{#:python} parameter.
- @end defvr
- @defvr {Scheme Variable} scons-build-system
- This variable is exported by @code{(guix build-system scons)}. It
- implements the build procedure used by the SCons software construction
- tool. This build system runs @code{scons} to build the package,
- @code{scons test} to run tests, and then @code{scons install} to install
- the package.
- Additional flags to be passed to @code{scons} can be specified with the
- @code{#:scons-flags} parameter. The default build and install targets
- can be overridden with @code{#:build-targets} and
- @code{#:install-targets} respectively. The version of Python used to
- run SCons can be specified by selecting the appropriate SCons package
- with the @code{#:scons} parameter.
- @end defvr
- @defvr {Scheme Variable} haskell-build-system
- This variable is exported by @code{(guix build-system haskell)}. It
- implements the Cabal build procedure used by Haskell packages, which
- involves running @code{runhaskell Setup.hs configure
- --prefix=/gnu/store/@dots{}} and @code{runhaskell Setup.hs build}.
- Instead of installing the package by running @code{runhaskell Setup.hs
- install}, to avoid trying to register libraries in the read-only
- compiler store directory, the build system uses @code{runhaskell
- Setup.hs copy}, followed by @code{runhaskell Setup.hs register}. In
- addition, the build system generates the package documentation by
- running @code{runhaskell Setup.hs haddock}, unless @code{#:haddock? #f}
- is passed. Optional Haddock parameters can be passed with the help of
- the @code{#:haddock-flags} parameter. If the file @code{Setup.hs} is
- not found, the build system looks for @code{Setup.lhs} instead.
- Which Haskell compiler is used can be specified with the @code{#:haskell}
- parameter which defaults to @code{ghc}.
- @end defvr
- @defvr {Scheme Variable} dub-build-system
- This variable is exported by @code{(guix build-system dub)}. It
- implements the Dub build procedure used by D packages, which
- involves running @code{dub build} and @code{dub run}.
- Installation is done by copying the files manually.
- Which D compiler is used can be specified with the @code{#:ldc}
- parameter which defaults to @code{ldc}.
- @end defvr
- @anchor{emacs-build-system}
- @defvr {Scheme Variable} emacs-build-system
- This variable is exported by @code{(guix build-system emacs)}. It
- implements an installation procedure similar to the packaging system
- of Emacs itself (@pxref{Packages,,, emacs, The GNU Emacs Manual}).
- It first creates the @code{@code{package}-autoloads.el} file, then it
- byte compiles all Emacs Lisp files. Differently from the Emacs
- packaging system, the Info documentation files are moved to the standard
- documentation directory and the @file{dir} file is deleted. The Elisp
- package files are installed directly under @file{share/emacs/site-lisp}.
- @end defvr
- @defvr {Scheme Variable} font-build-system
- This variable is exported by @code{(guix build-system font)}. It
- implements an installation procedure for font packages where upstream
- provides pre-compiled TrueType, OpenType, etc.@: font files that merely
- need to be copied into place. It copies font files to standard
- locations in the output directory.
- @end defvr
- @defvr {Scheme Variable} meson-build-system
- This variable is exported by @code{(guix build-system meson)}. It
- implements the build procedure for packages that use
- @url{https://mesonbuild.com, Meson} as their build system.
- It adds both Meson and @uref{https://ninja-build.org/, Ninja} to the set
- of inputs, and they can be changed with the parameters @code{#:meson}
- and @code{#:ninja} if needed.
- This build system is an extension of @code{gnu-build-system}, but with the
- following phases changed to some specific for Meson:
- @table @code
- @item configure
- The phase runs @code{meson} with the flags specified in
- @code{#:configure-flags}. The flag @option{--buildtype} is always set to
- @code{debugoptimized} unless something else is specified in
- @code{#:build-type}.
- @item build
- The phase runs @code{ninja} to build the package in parallel by default, but
- this can be changed with @code{#:parallel-build?}.
- @item check
- The phase runs @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}, such as test dependencies, that aren't actually required
- for the program to run.
- @item glib-or-gtk-wrap
- This phase is the phase provided by @code{glib-or-gtk-build-system}, and it
- is not enabled by default. It can be enabled with @code{#:glib-or-gtk?}.
- @item glib-or-gtk-compile-schemas
- This phase is the phase provided by @code{glib-or-gtk-build-system}, and it
- is not enabled by default. It can be enabled with @code{#:glib-or-gtk?}.
- @end table
- @end defvr
- @defvr {Scheme Variable} linux-module-build-system
- @code{linux-module-build-system} allows building Linux kernel modules.
- @cindex build phases
- This build system is an extension of @code{gnu-build-system}, but with the
- following phases changed:
- @table @code
- @item configure
- This phase configures the environment so that the Linux kernel's Makefile
- can be used to build the external kernel module.
- @item build
- This phase uses the Linux kernel's Makefile in order to build the external
- kernel module.
- @item install
- This phase uses the Linux kernel's Makefile in order to install the external
- kernel module.
- @end table
- It is possible and useful to specify the Linux kernel to use for building
- the module (in the @code{arguments} form of a package using the
- @code{linux-module-build-system}, use the key @code{#:linux} to specify it).
- @end defvr
- @defvr {Scheme Variable} node-build-system
- This variable is exported by @code{(guix build-system node)}. It
- implements the build procedure used by @uref{https://nodejs.org,
- Node.js}, which implements an approximation of the @code{npm install}
- command, followed by an @code{npm test} command.
- Which Node.js package is used to interpret the @code{npm} commands can
- be specified with the @code{#:node} parameter which defaults to
- @code{node}.
- @end defvr
- Lastly, for packages that do not need anything as sophisticated, a
- ``trivial'' build system is provided. It is trivial in the sense that
- it provides basically no support: it does not pull any implicit inputs,
- and does not have a notion of build phases.
- @defvr {Scheme Variable} trivial-build-system
- This variable is exported by @code{(guix build-system trivial)}.
- This build system requires a @code{#:builder} argument. This argument
- must be a Scheme expression that builds the package output(s)---as
- with @code{build-expression->derivation} (@pxref{Derivations,
- @code{build-expression->derivation}}).
- @end defvr
- @node Build Phases
- @section Build Phases
- @cindex build phases, for packages
- Almost all package build systems implement a notion @dfn{build phases}:
- a sequence of actions that the build system executes, when you build the
- package, leading to the installed byproducts in the store. A notable
- exception is the ``bare-bones'' @code{trivial-build-system}
- (@pxref{Build Systems}).
- As discussed in the previous section, those build systems provide a
- standard list of phases. For @code{gnu-build-system}, the main build
- phases are the following:
- @table @code
- @item unpack
- Unpack the source tarball, and change the current directory to the
- extracted source tree. If the source is actually a directory, copy it
- to the build tree, and enter that directory.
- @item patch-source-shebangs
- Patch shebangs encountered in source files so they refer to the right
- store file names. For instance, this changes @code{#!/bin/sh} to
- @code{#!/gnu/store/@dots{}-bash-4.3/bin/sh}.
- @item configure
- Run the @file{configure} script with a number of default options, such
- as @option{--prefix=/gnu/store/@dots{}}, as well as the options specified
- by the @code{#:configure-flags} argument.
- @item build
- Run @code{make} with the list of flags specified with
- @code{#:make-flags}. If the @code{#:parallel-build?} argument is true
- (the default), build with @code{make -j}.
- @item check
- Run @code{make check}, or some other target specified with
- @code{#:test-target}, unless @code{#:tests? #f} is passed. If the
- @code{#:parallel-tests?} argument is true (the default), run @code{make
- check -j}.
- @item install
- Run @code{make install} with the flags listed in @code{#:make-flags}.
- @item patch-shebangs
- Patch shebangs on the installed executable files.
- @item strip
- Strip debugging symbols from ELF files (unless @code{#:strip-binaries?}
- is false), copying them to the @code{debug} output when available
- (@pxref{Installing Debugging Files}).
- @end table
- Other build systems have similar phases, with some variations. For
- example, @code{cmake-build-system} has same-named phases but its
- @code{configure} phases runs @code{cmake} instead of @code{./configure}.
- Others, such as @code{python-build-system}, have a wholly different list
- of standard phases. All this code runs on the @dfn{build side}: it is
- evaluated when you actually build the package, in a dedicated build
- process spawned by the build daemon (@pxref{Invoking guix-daemon}).
- Build phases are represented as association lists or ``alists''
- (@pxref{Association Lists,,, guile, GNU Guile Reference Manual}) where
- each key is a symbol for the name of the phase and the associated value
- is a procedure that accepts an arbitrary number of arguments. By
- convention, those procedures receive information about the build in the
- form of @dfn{keyword parameters}, which they can use or ignore.
- @vindex %standard-phases
- For example, here is how @code{(guix build gnu-build-system)} defines
- @code{%standard-phases}, the variable holding its alist of build
- phases@footnote{We present a simplified view of those build phases, but
- do take a look at @code{(guix build gnu-build-system)} to see all the
- details!}:
- @lisp
- ;; The build phases of 'gnu-build-system'.
- (define* (unpack #:key source #:allow-other-keys)
- ;; Extract the source tarball.
- (invoke "tar" "xvf" source))
- (define* (configure #:key outputs #:allow-other-keys)
- ;; Run the 'configure' script. Install to output "out".
- (let ((out (assoc-ref outputs "out")))
- (invoke "./configure"
- (string-append "--prefix=" out))))
- (define* (build #:allow-other-keys)
- ;; Compile.
- (invoke "make"))
- (define* (check #:key (test-target "check") (tests? #true)
- #:allow-other-keys)
- ;; Run the test suite.
- (if tests?
- (invoke "make" test-target)
- (display "test suite not run\n")))
- (define* (install #:allow-other-keys)
- ;; Install files to the prefix 'configure' specified.
- (invoke "make" "install"))
- (define %standard-phases
- ;; The list of standard phases (quite a few are omitted
- ;; for brevity). Each element is a symbol/procedure pair.
- (list (cons 'unpack unpack)
- (cons 'configure configure)
- (cons 'build build)
- (cons 'check check)
- (cons 'install install)))
- @end lisp
- This shows how @code{%standard-phases} is defined as a list of
- symbol/procedure pairs (@pxref{Pairs,,, guile, GNU Guile Reference
- Manual}). The first pair associates the @code{unpack} procedure with
- the @code{unpack} symbol---a name; the second pair defines the
- @code{configure} phase similarly, and so on. When building a package
- that uses @code{gnu-build-system} with its default list of phases, those
- phases are executed sequentially. You can see the name of each phase
- started and completed in the build log of packages that you build.
- Let's now look at the procedures themselves. Each one is defined with
- @code{define*}: @code{#:key} lists keyword parameters the procedure
- accepts, possibly with a default value, and @code{#:allow-other-keys}
- specifies that other keyword parameters are ignored (@pxref{Optional
- Arguments,,, guile, GNU Guile Reference Manual}).
- The @code{unpack} procedure honors the @code{source} parameter, which
- the build system uses to pass the file name of the source tarball (or
- version control checkout), and it ignores other parameters. The
- @code{configure} phase only cares about the @code{outputs} parameter, an
- alist mapping package output names to their store file name
- (@pxref{Packages with Multiple Outputs}). It extracts the file name of
- for @code{out}, the default output, and passes it to
- @command{./configure} as the installation prefix, meaning that
- @command{make install} will eventually copy all the files in that
- directory (@pxref{Configuration, configuration and makefile
- conventions,, standards, GNU Coding Standards}). @code{build} and
- @code{install} ignore all their arguments. @code{check} honors the
- @code{test-target} argument, which specifies the name of the Makefile
- target to run tests; it prints a message and skips tests when
- @code{tests?} is false.
- @cindex build phases, customizing
- The list of phases used for a particular package can be changed with the
- @code{#:phases} parameter of the build system. Changing the set of
- build phases boils down to building a new alist of phases based on the
- @code{%standard-phases} alist described above. This can be done with
- standard alist procedures such as @code{alist-delete} (@pxref{SRFI-1
- Association Lists,,, guile, GNU Guile Reference Manual}); however, it is
- more convenient to do so with @code{modify-phases} (@pxref{Build
- Utilities, @code{modify-phases}}).
- Here is an example of a package definition that removes the
- @code{configure} phase of @code{%standard-phases} and inserts a new
- phase before the @code{build} phase, called
- @code{set-prefix-in-makefile}:
- @lisp
- (define-public example
- (package
- (name "example")
- ;; other fields omitted
- (build-system gnu-build-system)
- (arguments
- '(#:phases (modify-phases %standard-phases
- (delete 'configure)
- (add-before 'build 'set-prefix-in-makefile
- (lambda* (#:key outputs #:allow-other-keys)
- ;; Modify the makefile so that its
- ;; 'PREFIX' variable points to "out".
- (let ((out (assoc-ref outputs "out")))
- (substitute* "Makefile"
- (("PREFIX =.*")
- (string-append "PREFIX = "
- out "\n")))
- #true))))))))
- @end lisp
- The new phase that is inserted is written as an anonymous procedure,
- introduced with @code{lambda*}; it honors the @code{outputs} parameter
- we have seen before. @xref{Build Utilities}, for more about the helpers
- used by this phase, and for more examples of @code{modify-phases}.
- @cindex code staging
- @cindex staging, of code
- Keep in mind that build phases are code evaluated at the time the
- package is actually built. This explains why the whole
- @code{modify-phases} expression above is quoted (it comes after the
- @code{'} or apostrophe): it is @dfn{staged} for later execution.
- @xref{G-Expressions}, for an explanation of code staging and the
- @dfn{code strata} involved.
- @node Build Utilities
- @section Build Utilities
- As soon as you start writing non-trivial package definitions
- (@pxref{Defining Packages}) or other build actions
- (@pxref{G-Expressions}), you will likely start looking for helpers for
- ``shell-like'' actions---creating directories, copying and deleting
- files recursively, manipulating build phases, and so on. The
- @code{(guix build utils)} module provides such utility procedures.
- Most build systems load @code{(guix build utils)} (@pxref{Build
- Systems}). Thus, when writing custom build phases for your package
- definitions, you can usually assume those procedures are in scope.
- When writing G-expressions, you can import @code{(guix build utils)} on
- the ``build side'' using @code{with-imported-modules} and then put it in
- scope with the @code{use-modules} form (@pxref{Using Guile Modules,,,
- guile, GNU Guile Reference Manual}):
- @lisp
- (with-imported-modules '((guix build utils)) ;import it
- (computed-file "empty-tree"
- #~(begin
- ;; Put it in scope.
- (use-modules (guix build utils))
- ;; Happily use its 'mkdir-p' procedure.
- (mkdir-p (string-append #$output "/a/b/c")))))
- @end lisp
- The remainder of this section is the reference for most of the utility
- procedures provided by @code{(guix build utils)}.
- @c TODO Document what's missing.
- @subsection Dealing with Store File Names
- This section documents procedures that deal with store file names.
- @deffn {Scheme Procedure} %store-directory
- Return the directory name of the store.
- @end deffn
- @deffn {Scheme Procedure} store-file-name? @var{file}
- Return true if @var{file} is in the store.
- @end deffn
- @deffn {Scheme Procedure} strip-store-file-name @var{file}
- Strip the @file{/gnu/store} and hash from @var{file}, a store file name.
- The result is typically a @code{"@var{package}-@var{version}"} string.
- @end deffn
- @deffn {Scheme Procedure} package-name->name+version @var{name}
- Given @var{name}, a package name like @code{"foo-0.9.1b"}, return two
- values: @code{"foo"} and @code{"0.9.1b"}. When the version part is
- unavailable, @var{name} and @code{#f} are returned. The first hyphen
- followed by a digit is considered to introduce the version part.
- @end deffn
- @subsection File Types
- The procedures below deal with files and file types.
- @deffn {Scheme Procedure} directory-exists? @var{dir}
- Return @code{#t} if @var{dir} exists and is a directory.
- @end deffn
- @deffn {Scheme Procedure} executable-file? @var{file}
- Return @code{#t} if @var{file} exists and is executable.
- @end deffn
- @deffn {Scheme Procedure} symbolic-link? @var{file}
- Return @code{#t} if @var{file} is a symbolic link (aka. a ``symlink'').
- @end deffn
- @deffn {Scheme Procedure} elf-file? @var{file}
- @deffnx {Scheme Procedure} ar-file? @var{file}
- @deffnx {Scheme Procedure} gzip-file? @var{file}
- Return @code{#t} if @var{file} is, respectively, an ELF file, an
- @code{ar} archive (such as a @file{.a} static library), or a gzip file.
- @end deffn
- @deffn {Scheme Procedure} reset-gzip-timestamp @var{file} [#:keep-mtime? #t]
- If @var{file} is a gzip file, reset its embedded timestamp (as with
- @command{gzip --no-name}) and return true. Otherwise return @code{#f}.
- When @var{keep-mtime?} is true, preserve @var{file}'s modification time.
- @end deffn
- @subsection File Manipulation
- The following procedures and macros help create, modify, and delete
- files. They provide functionality comparable to common shell utilities
- such as @command{mkdir -p}, @command{cp -r}, @command{rm -r}, and
- @command{sed}. They complement Guile's extensive, but low-level, file
- system interface (@pxref{POSIX,,, guile, GNU Guile Reference Manual}).
- @deffn {Scheme Syntax} with-directory-excursion @var{directory} @var{body}@dots{}
- Run @var{body} with @var{directory} as the process's current directory.
- Essentially, this macro changes the current directory to @var{directory}
- before evaluating @var{body}, using @code{chdir} (@pxref{Processes,,,
- guile, GNU Guile Reference Manual}). It changes back to the initial
- directory when the dynamic extent of @var{body} is left, be it @i{via}
- normal procedure return or @i{via} a non-local exit such as an
- exception.
- @end deffn
- @deffn {Scheme Procedure} mkdir-p @var{dir}
- Create directory @var{dir} and all its ancestors.
- @end deffn
- @deffn {Scheme Procedure} install-file @var{file} @var{directory}
- Create @var{directory} if it does not exist and copy @var{file} in there
- under the same name.
- @end deffn
- @deffn {Scheme Procedure} make-file-writable @var{file}
- Make @var{file} writable for its owner.
- @end deffn
- @deffn {Scheme Procedure} copy-recursively @var{source} @var{destination} @
- [#:log (current-output-port)] [#:follow-symlinks? #f] @
- [#:copy-file copy-file] [#:keep-mtime? #f] [#:keep-permissions? #t]
- Copy @var{source} directory to @var{destination}. Follow symlinks if
- @var{follow-symlinks?} is true; otherwise, just preserve them. Call
- @var{copy-file} to copy regular files. When @var{keep-mtime?} is true,
- keep the modification time of the files in @var{source} on those of
- @var{destination}. When @var{keep-permissions?} is true, preserve file
- permissions. Write verbose output to the @var{log} port.
- @end deffn
- @deffn {Scheme Procedure} delete-file-recursively @var{dir} @
- [#:follow-mounts? #f]
- Delete @var{dir} recursively, like @command{rm -rf}, without following
- symlinks. Don't follow mount points either, unless @var{follow-mounts?}
- is true. Report but ignore errors.
- @end deffn
- @deffn {Scheme Syntax} substitute* @var{file} @
- ((@var{regexp} @var{match-var}@dots{}) @var{body}@dots{}) @dots{}
- Substitute @var{regexp} in @var{file} by the string returned by
- @var{body}. @var{body} is evaluated with each @var{match-var} bound to
- the corresponding positional regexp sub-expression. For example:
- @lisp
- (substitute* file
- (("hello")
- "good morning\n")
- (("foo([a-z]+)bar(.*)$" all letters end)
- (string-append "baz" 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
- @deffn {Scheme Procedure} search-input-file @var{inputs} @var{name}
- @deffnx {Scheme Procedure} search-input-directory @var{inputs} @var{name}
- Return the complete file name for @var{name} as found in @var{inputs};
- @code{search-input-file} searches for a regular file and
- @code{search-input-directory} searches for a directory. If @var{name}
- could not be found, an exception is raised.
- Here, @var{inputs} must be an association list like @code{inputs} and
- @code{native-inputs} as available to build phases (@pxref{Build
- Phases}).
- @end deffn
- Here is a (simplified) example of how @code{search-input-file} is used
- in a build phase of the @code{wireguard-tools} package:
- @lisp
- (add-after 'install 'wrap-wg-quick
- (lambda* (#:key inputs outputs #:allow-other-keys)
- (let ((coreutils (string-append (assoc-ref inputs "coreutils")
- "/bin")))
- (wrap-program (search-input-file outputs "bin/wg-quick")
- #:sh (search-input-file inputs "bin/bash")
- `("PATH" ":" prefix ,(list coreutils))))))
- @end lisp
- @subsection 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
- @deffn {Procedure} gexp->approximate-sexp @var{gexp}
- Sometimes, it may be useful to convert a G-exp into a S-exp. For
- example, some linters (@pxref{Invoking guix lint}) peek into the build
- phases of a package to detect potential problems. This conversion can
- be achieved with this procedure. However, some information can be lost
- in the process. More specifically, lowerable objects will be silently
- replaced with some arbitrary object -- currently the list
- @code{(*approximate*)}, but this may change.
- @end deffn
- @node Invoking guix repl
- @section Invoking @command{guix repl}
- @cindex REPL, read-eval-print loop, script
- The @command{guix repl} command makes it easier to program Guix in Guile
- by launching a Guile @dfn{read-eval-print loop} (REPL) for interactive
- programming (@pxref{Using Guile Interactively,,, guile,
- GNU Guile Reference Manual}), or by running Guile scripts
- (@pxref{Running Guile Scripts,,, guile,
- GNU Guile Reference Manual}).
- Compared to just launching the @command{guile}
- command, @command{guix repl} guarantees that all the Guix modules and all its
- dependencies are available in the search path.
- The general syntax is:
- @example
- guix repl @var{options} [@var{file} @var{args}]
- @end example
- When a @var{file} argument is provided, @var{file} is
- executed as a Guile scripts:
- @example
- guix repl my-script.scm
- @end example
- To pass arguments to the script, use @code{--} to prevent them from
- being interpreted as arguments to @command{guix repl} itself:
- @example
- guix repl -- my-script.scm --input=foo.txt
- @end example
- To make a script executable directly from the shell, using the guix
- executable that is on the user's search path, add the following two
- lines at the top of the script:
- @example
- @code{#!/usr/bin/env -S guix repl --}
- @code{!#}
- @end example
- Without a file name argument, a Guile REPL is started:
- @example
- $ guix repl
- scheme@@(guile-user)> ,use (gnu packages base)
- scheme@@(guile-user)> coreutils
- $1 = #<package coreutils@@8.29 gnu/packages/base.scm:327 3e28300>
- @end example
- @cindex inferiors
- In addition, @command{guix repl} implements a simple machine-readable REPL
- protocol for use by @code{(guix inferior)}, a facility to interact with
- @dfn{inferiors}, separate processes running a potentially different revision
- of Guix.
- The available options are as follows:
- @table @code
- @item --type=@var{type}
- @itemx -t @var{type}
- Start a REPL of the given @var{TYPE}, which can be one of the following:
- @table @code
- @item guile
- This is default, and it spawns a standard full-featured Guile REPL.
- @item machine
- Spawn a REPL that uses the machine-readable protocol. This is the protocol
- that the @code{(guix inferior)} module speaks.
- @end table
- @item --listen=@var{endpoint}
- By default, @command{guix repl} reads from standard input and writes to
- standard output. When this option is passed, it will instead listen for
- connections on @var{endpoint}. Here are examples of valid options:
- @table @code
- @item --listen=tcp:37146
- Accept connections on localhost on port 37146.
- @item --listen=unix:/tmp/socket
- Accept connections on the Unix-domain socket @file{/tmp/socket}.
- @end table
- @item --load-path=@var{directory}
- @itemx -L @var{directory}
- Add @var{directory} to the front of the package module search path
- (@pxref{Package Modules}).
- This allows users to define their own packages and make them visible to
- the script or REPL.
- @item -q
- Inhibit loading of the @file{~/.guile} file. By default, that
- configuration file is loaded when spawning a @code{guile} REPL.
- @end table
- @c *********************************************************************
- @node Utilities
- @chapter Utilities
- This section describes Guix command-line utilities. Some of them are
- primarily targeted at developers and users who write new package
- definitions, while others are more generally useful. They complement
- the Scheme programming interface of Guix in a convenient way.
- @menu
- * Invoking guix build:: Building packages from the command line.
- * Invoking guix edit:: Editing package definitions.
- * Invoking guix download:: Downloading a file and printing its hash.
- * Invoking guix hash:: Computing the cryptographic hash of a file.
- * Invoking guix import:: Importing package definitions.
- * Invoking guix refresh:: Updating package definitions.
- * Invoking guix style:: Styling package definitions.
- * Invoking guix lint:: Finding errors in package definitions.
- * Invoking guix size:: Profiling disk usage.
- * Invoking guix graph:: Visualizing the graph of packages.
- * Invoking guix publish:: Sharing substitutes.
- * Invoking guix challenge:: Challenging substitute servers.
- * Invoking guix copy:: Copying to and from a remote store.
- * Invoking guix container:: Process isolation.
- * Invoking guix weather:: Assessing substitute availability.
- * Invoking guix processes:: Listing client processes.
- @end menu
- @node Invoking guix build
- @section Invoking @command{guix build}
- @cindex package building
- @cindex @command{guix build}
- The @command{guix build} command builds packages or derivations and
- their dependencies, and prints the resulting store paths. Note that it
- does not modify the user's profile---this is the job of the
- @command{guix package} command (@pxref{Invoking guix package}). Thus,
- it is mainly useful for distribution developers.
- The general syntax is:
- @example
- guix build @var{options} @var{package-or-derivation}@dots{}
- @end example
- As an example, the following command builds the latest versions of Emacs
- and of Guile, displays their build logs, and finally displays the
- resulting directories:
- @example
- guix build emacs guile
- @end example
- Similarly, the following command builds all the available packages:
- @example
- guix build --quiet --keep-going \
- $(guix package -A | awk '@{ print $1 "@@" $2 @}')
- @end example
- @var{package-or-derivation} may be either the name of a package found in
- the software distribution such as @code{coreutils} or
- @code{coreutils@@8.20}, or a derivation such as
- @file{/gnu/store/@dots{}-coreutils-8.19.drv}. In the former case, a
- package with the corresponding name (and optionally version) is searched
- for among the GNU distribution modules (@pxref{Package Modules}).
- Alternatively, the @option{--expression} option may be used to specify a
- Scheme expression that evaluates to a package; this is useful when
- disambiguating among several same-named packages or package variants is
- needed.
- There may be zero or more @var{options}. The available options are
- described in the subsections below.
- @menu
- * Common Build Options:: Build options for most commands.
- * Package Transformation Options:: Creating variants of packages.
- * Additional Build Options:: Options specific to 'guix build'.
- * Debugging Build Failures:: Real life packaging experience.
- @end menu
- @node Common Build Options
- @subsection Common Build Options
- A number of options that control the build process are common to
- @command{guix build} and other commands that can spawn builds, such as
- @command{guix package} or @command{guix archive}. These are the
- following:
- @table @code
- @item --load-path=@var{directory}
- @itemx -L @var{directory}
- Add @var{directory} to the front of the package module search path
- (@pxref{Package Modules}).
- This allows users to define their own packages and make them visible to
- the command-line tools.
- @item --keep-failed
- @itemx -K
- Keep the build tree of failed builds. Thus, if a build fails, its build
- tree is kept under @file{/tmp}, in a directory whose name is shown at
- the end of the build log. This is useful when debugging build issues.
- @xref{Debugging Build Failures}, for tips and tricks on how to debug
- build issues.
- This option implies @option{--no-offload}, and it has no effect when
- connecting to a remote daemon with a @code{guix://} URI (@pxref{The
- Store, the @env{GUIX_DAEMON_SOCKET} variable}).
- @item --keep-going
- @itemx -k
- Keep going when some of the derivations fail to build; return only once
- all the builds have either completed or failed.
- The default behavior is to stop as soon as one of the specified
- derivations has failed.
- @item --dry-run
- @itemx -n
- Do not build the derivations.
- @anchor{fallback-option}
- @item --fallback
- When substituting a pre-built binary fails, fall back to building
- packages locally (@pxref{Substitution Failure}).
- @item --substitute-urls=@var{urls}
- @anchor{client-substitute-urls}
- Consider @var{urls} the whitespace-separated list of substitute source
- URLs, overriding the default list of URLs of @command{guix-daemon}
- (@pxref{daemon-substitute-urls,, @command{guix-daemon} URLs}).
- This means that substitutes may be downloaded from @var{urls}, provided
- they are signed by a key authorized by the system administrator
- (@pxref{Substitutes}).
- When @var{urls} is the empty string, substitutes are effectively
- disabled.
- @item --no-substitutes
- Do not use substitutes for build products. That is, always build things
- locally instead of allowing downloads of pre-built binaries
- (@pxref{Substitutes}).
- @item --no-grafts
- Do not ``graft'' packages. In practice, this means that package updates
- available as grafts are not applied. @xref{Security Updates}, for more
- information on grafts.
- @item --rounds=@var{n}
- Build each derivation @var{n} times in a row, and raise an error if
- consecutive build results are not bit-for-bit identical.
- This is a useful way to detect non-deterministic builds processes.
- Non-deterministic build processes are a problem because they make it
- practically impossible for users to @emph{verify} whether third-party
- binaries are genuine. @xref{Invoking guix challenge}, for more.
- When used in conjunction with @option{--keep-failed}, the differing
- output is kept in the store, under @file{/gnu/store/@dots{}-check}.
- This makes it easy to look for differences between the two results.
- @item --no-offload
- Do not use offload builds to other machines (@pxref{Daemon Offload
- Setup}). That is, always build things locally instead of offloading
- builds to remote machines.
- @item --max-silent-time=@var{seconds}
- When the build or substitution process remains silent for more than
- @var{seconds}, terminate it and report a build failure.
- By default, the daemon's setting is honored (@pxref{Invoking
- guix-daemon, @option{--max-silent-time}}).
- @item --timeout=@var{seconds}
- Likewise, when the build or substitution process lasts for more than
- @var{seconds}, terminate it and report a build failure.
- By default, the daemon's setting is honored (@pxref{Invoking
- guix-daemon, @option{--timeout}}).
- @c Note: This option is actually not part of %standard-build-options but
- @c most programs honor it.
- @cindex verbosity, of the command-line tools
- @cindex build logs, verbosity
- @item -v @var{level}
- @itemx --verbosity=@var{level}
- Use the given verbosity @var{level}, an integer. Choosing 0 means that
- no output is produced, 1 is for quiet output; 2 is similar to 1 but it
- additionally displays download URLs; 3 shows all the build log output on
- standard error.
- @item --cores=@var{n}
- @itemx -c @var{n}
- Allow the use of up to @var{n} CPU cores for the build. The special
- value @code{0} means to use as many CPU cores as available.
- @item --max-jobs=@var{n}
- @itemx -M @var{n}
- Allow at most @var{n} build jobs in parallel. @xref{Invoking
- guix-daemon, @option{--max-jobs}}, for details about this option and the
- equivalent @command{guix-daemon} option.
- @item --debug=@var{level}
- Produce debugging output coming from the build daemon. @var{level} must be an
- integer between 0 and 5; higher means more verbose output. Setting a level of
- 4 or more may be helpful when debugging setup issues with the build daemon.
- @end table
- Behind the scenes, @command{guix build} is essentially an interface to
- the @code{package-derivation} procedure of the @code{(guix packages)}
- module, and to the @code{build-derivations} procedure of the @code{(guix
- derivations)} module.
- In addition to options explicitly passed on the command line,
- @command{guix build} and other @command{guix} commands that support
- building honor the @env{GUIX_BUILD_OPTIONS} environment variable.
- @defvr {Environment Variable} GUIX_BUILD_OPTIONS
- Users can define this variable to a list of command line options that
- will automatically be used by @command{guix build} and other
- @command{guix} commands that can perform builds, as in the example
- below:
- @example
- $ export GUIX_BUILD_OPTIONS="--no-substitutes -c 2 -L /foo/bar"
- @end example
- These options are parsed independently, and the result is appended to
- the parsed command-line options.
- @end defvr
- @node Package Transformation Options
- @subsection Package Transformation Options
- @cindex package variants
- Another set of command-line options supported by @command{guix build}
- and also @command{guix package} are @dfn{package transformation
- options}. These are options that make it possible to define @dfn{package
- variants}---for instance, packages built from different source code.
- This is a convenient way to create customized packages on the fly
- without having to type in the definitions of package variants
- (@pxref{Defining Packages}).
- Package transformation options are preserved across upgrades:
- @command{guix upgrade} attempts to apply transformation options
- initially used when creating the profile to the upgraded packages.
- The available options are listed below. Most commands support them and
- also support a @option{--help-transform} option that lists all the
- available options and a synopsis (these options are not shown in the
- @option{--help} output for brevity).
- @table @code
- @item --with-source=@var{source}
- @itemx --with-source=@var{package}=@var{source}
- @itemx --with-source=@var{package}@@@var{version}=@var{source}
- Use @var{source} as the source of @var{package}, and @var{version} as
- its version number.
- @var{source} must be a file name or a URL, as for @command{guix
- download} (@pxref{Invoking guix download}).
- When @var{package} is omitted,
- it is taken to be the package name specified on the
- command line that matches the base of @var{source}---e.g.,
- if @var{source} is @code{/src/guile-2.0.10.tar.gz}, the corresponding
- package is @code{guile}.
- Likewise, when @var{version} is omitted, the version string is inferred from
- @var{source}; in the previous example, it is @code{2.0.10}.
- This option allows users to try out versions of packages other than the
- one provided by the distribution. The example below downloads
- @file{ed-1.7.tar.gz} from a GNU mirror and uses that as the source for
- the @code{ed} package:
- @example
- guix build ed --with-source=mirror://gnu/ed/ed-1.7.tar.gz
- @end example
- As a developer, @option{--with-source} makes it easy to test release
- candidates:
- @example
- guix build guile --with-source=../guile-2.0.9.219-e1bb7.tar.xz
- @end example
- @dots{} or to build from a checkout in a pristine environment:
- @example
- $ git clone git://git.sv.gnu.org/guix.git
- $ guix build guix --with-source=guix@@1.0=./guix
- @end example
- @item --with-input=@var{package}=@var{replacement}
- Replace dependency on @var{package} by a dependency on
- @var{replacement}. @var{package} must be a package name, and
- @var{replacement} must be a package specification such as @code{guile}
- or @code{guile@@1.8}.
- For instance, the following command builds Guix, but replaces its
- dependency on the current stable version of Guile with a dependency on
- the legacy version of Guile, @code{guile@@2.0}:
- @example
- guix build --with-input=guile=guile@@2.0 guix
- @end example
- This is a recursive, deep replacement. So in this example, both
- @code{guix} and its dependency @code{guile-json} (which also depends on
- @code{guile}) get rebuilt against @code{guile@@2.0}.
- This is implemented using the @code{package-input-rewriting} Scheme
- procedure (@pxref{Defining Packages, @code{package-input-rewriting}}).
- @item --with-graft=@var{package}=@var{replacement}
- This is similar to @option{--with-input} but with an important difference:
- instead of rebuilding the whole dependency chain, @var{replacement} is
- built and then @dfn{grafted} onto the binaries that were initially
- referring to @var{package}. @xref{Security Updates}, for more
- information on grafts.
- For example, the command below grafts version 3.5.4 of GnuTLS onto Wget
- and all its dependencies, replacing references to the version of GnuTLS
- they currently refer to:
- @example
- guix build --with-graft=gnutls=gnutls@@3.5.4 wget
- @end example
- This has the advantage of being much faster than rebuilding everything.
- But there is a caveat: it works if and only if @var{package} and
- @var{replacement} are strictly compatible---for example, if they provide
- a library, the application binary interface (ABI) of those libraries
- must be compatible. If @var{replacement} is somehow incompatible with
- @var{package}, then the resulting package may be unusable. Use with
- care!
- @cindex debugging info, rebuilding
- @item --with-debug-info=@var{package}
- Build @var{package} in a way that preserves its debugging info and graft
- it onto packages that depend on it. This is useful if @var{package}
- does not already provide debugging info as a @code{debug} output
- (@pxref{Installing Debugging Files}).
- For example, suppose you're experiencing a crash in Inkscape and would
- like to see what's up in GLib, a library deep down in Inkscape's
- dependency graph. GLib lacks a @code{debug} output, so debugging is
- tough. Fortunately, you rebuild GLib with debugging info and tack it on
- Inkscape:
- @example
- guix install inkscape --with-debug-info=glib
- @end example
- Only GLib needs to be recompiled so this takes a reasonable amount of
- time. @xref{Installing Debugging Files}, for more info.
- @quotation Note
- Under the hood, this option works by passing the @samp{#:strip-binaries?
- #f} to the build system of the package of interest (@pxref{Build
- Systems}). Most build systems support that option but some do not. In
- that case, an error is raised.
- Likewise, if a C/C++ package is built without @code{-g} (which is rarely
- the case), debugging info will remain unavailable even when
- @code{#:strip-binaries?} is false.
- @end quotation
- @cindex tool chain, changing the build tool chain of a package
- @item --with-c-toolchain=@var{package}=@var{toolchain}
- This option changes the compilation of @var{package} and everything that
- depends on it so that they get built with @var{toolchain} instead of the
- default GNU tool chain for C/C++.
- Consider this example:
- @example
- guix build octave-cli \
- --with-c-toolchain=fftw=gcc-toolchain@@10 \
- --with-c-toolchain=fftwf=gcc-toolchain@@10
- @end example
- The command above builds a variant of the @code{fftw} and @code{fftwf}
- packages using version 10 of @code{gcc-toolchain} instead of the default
- tool chain, and then builds a variant of the GNU@tie{}Octave
- command-line interface using them. GNU@tie{}Octave itself is also built
- with @code{gcc-toolchain@@10}.
- This other example builds the Hardware Locality (@code{hwloc}) library
- and its dependents up to @code{intel-mpi-benchmarks} with the Clang C
- compiler:
- @example
- guix build --with-c-toolchain=hwloc=clang-toolchain \
- intel-mpi-benchmarks
- @end example
- @quotation Note
- There can be application binary interface (ABI) incompatibilities among
- tool chains. This is particularly true of the C++ standard library and
- run-time support libraries such as that of OpenMP@. By rebuilding all
- dependents with the same tool chain, @option{--with-c-toolchain} minimizes
- the risks of incompatibility but cannot entirely eliminate them. Choose
- @var{package} wisely.
- @end quotation
- @item --with-git-url=@var{package}=@var{url}
- @cindex Git, using the latest commit
- @cindex latest commit, building
- Build @var{package} from the latest commit of the @code{master} branch of the
- Git repository at @var{url}. Git sub-modules of the repository are fetched,
- recursively.
- For example, the following command builds the NumPy Python library against the
- latest commit of the master branch of Python itself:
- @example
- guix build python-numpy \
- --with-git-url=python=https://github.com/python/cpython
- @end example
- This option can also be combined with @option{--with-branch} or
- @option{--with-commit} (see below).
- @cindex continuous integration
- Obviously, since it uses the latest commit of the given branch, the result of
- such a command varies over time. Nevertheless it is a convenient way to
- rebuild entire software stacks against the latest commit of one or more
- packages. This is particularly useful in the context of continuous
- integration (CI).
- Checkouts are kept in a cache under @file{~/.cache/guix/checkouts} to speed up
- consecutive accesses to the same repository. You may want to clean it up once
- in a while to save disk space.
- @item --with-branch=@var{package}=@var{branch}
- Build @var{package} from the latest commit of @var{branch}. If the
- @code{source} field of @var{package} is an origin with the @code{git-fetch}
- method (@pxref{origin Reference}) or a @code{git-checkout} object, the
- repository URL is taken from that @code{source}. Otherwise you have to use
- @option{--with-git-url} to specify the URL of the Git repository.
- For instance, the following command builds @code{guile-sqlite3} from the
- latest commit of its @code{master} branch, and then builds @code{guix} (which
- depends on it) and @code{cuirass} (which depends on @code{guix}) against this
- specific @code{guile-sqlite3} build:
- @example
- guix build --with-branch=guile-sqlite3=master cuirass
- @end example
- @item --with-commit=@var{package}=@var{commit}
- This is similar to @option{--with-branch}, except that it builds from
- @var{commit} rather than the tip of a branch. @var{commit} must be a valid
- Git commit SHA1 identifier, a tag, or a @command{git describe} style
- identifier such as @code{1.0-3-gabc123}.
- @item --with-patch=@var{package}=@var{file}
- Add @var{file} to the list of patches applied to @var{package}, where
- @var{package} is a spec such as @code{python@@3.8} or @code{glibc}.
- @var{file} must contain a patch; it is applied with the flags specified
- in the @code{origin} of @var{package} (@pxref{origin Reference}), which
- by default includes @code{-p1} (@pxref{patch Directories,,, diffutils,
- Comparing and Merging Files}).
- As an example, the command below rebuilds Coreutils with the GNU C
- Library (glibc) patched with the given patch:
- @example
- guix build coreutils --with-patch=glibc=./glibc-frob.patch
- @end example
- In this example, glibc itself as well as everything that leads to
- Coreutils in the dependency graph is rebuilt.
- @cindex upstream, latest version
- @item --with-latest=@var{package}
- So you like living on the bleeding edge? This option is for you! It
- replaces occurrences of @var{package} in the dependency graph with its
- latest upstream version, as reported by @command{guix refresh}
- (@pxref{Invoking guix refresh}).
- It does so by determining the latest upstream release of @var{package}
- (if possible), downloading it, and authenticating it @emph{if} it comes
- with an OpenPGP signature.
- As an example, the command below builds Guix against the latest version
- of Guile-JSON:
- @example
- guix build guix --with-latest=guile-json
- @end example
- There are limitations. First, in cases where the tool cannot or does
- not know how to authenticate source code, you are at risk of running
- malicious code; a warning is emitted in this case. Second, this option
- simply changes the source used in the existing package definitions,
- which is not always sufficient: there might be additional dependencies
- that need to be added, patches to apply, and more generally the quality
- assurance work that Guix developers normally do will be missing.
- You've been warned! In all the other cases, it's a snappy way to stay
- on top. We encourage you to submit patches updating the actual package
- definitions once you have successfully tested an upgrade
- (@pxref{Contributing}).
- @cindex test suite, skipping
- @item --without-tests=@var{package}
- Build @var{package} without running its tests. This can be useful in
- situations where you want to skip the lengthy test suite of a
- intermediate package, or if a package's test suite fails in a
- non-deterministic fashion. It should be used with care because running
- the test suite is a good way to ensure a package is working as intended.
- Turning off tests leads to a different store item. Consequently, when
- using this option, anything that depends on @var{package} must be
- rebuilt, as in this example:
- @example
- guix install --without-tests=python python-notebook
- @end example
- The command above installs @code{python-notebook} on top of
- @code{python} built without running its test suite. To do so, it also
- rebuilds everything that depends on @code{python}, including
- @code{python-notebook} itself.
- Internally, @option{--without-tests} relies on changing the
- @code{#:tests?} option of a package's @code{check} phase (@pxref{Build
- Systems}). Note that some packages use a customized @code{check} phase
- that does not respect a @code{#:tests? #f} setting. Therefore,
- @option{--without-tests} has no effect on these packages.
- @end table
- Wondering how to achieve the same effect using Scheme code, for example
- in your manifest, or how to write your own package transformation?
- @xref{Defining Package Variants}, for an overview of the programming
- interfaces available.
- @node Additional Build Options
- @subsection Additional Build Options
- The command-line options presented below are specific to @command{guix
- build}.
- @table @code
- @item --quiet
- @itemx -q
- Build quietly, without displaying the build log; this is equivalent to
- @option{--verbosity=0}. Upon completion, the build log is kept in @file{/var}
- (or similar) and can always be retrieved using the @option{--log-file} option.
- @item --file=@var{file}
- @itemx -f @var{file}
- Build the package, derivation, or other file-like object that the code within
- @var{file} evaluates to (@pxref{G-Expressions, file-like objects}).
- As an example, @var{file} might contain a package definition like this
- (@pxref{Defining Packages}):
- @lisp
- @include package-hello.scm
- @end lisp
- The @var{file} may also contain a JSON representation of one or more
- package definitions. Running @code{guix build -f} on @file{hello.json}
- with the following contents would result in building the packages
- @code{myhello} and @code{greeter}:
- @example
- @verbatiminclude package-hello.json
- @end example
- @item --manifest=@var{manifest}
- @itemx -m @var{manifest}
- Build all packages listed in the given @var{manifest}
- (@pxref{profile-manifest, @option{--manifest}}).
- @item --expression=@var{expr}
- @itemx -e @var{expr}
- Build the package or derivation @var{expr} evaluates to.
- For example, @var{expr} may be @code{(@@ (gnu packages guile)
- guile-1.8)}, which unambiguously designates this specific variant of
- version 1.8 of Guile.
- Alternatively, @var{expr} may be a G-expression, in which case it is used
- as a build program passed to @code{gexp->derivation}
- (@pxref{G-Expressions}).
- Lastly, @var{expr} may refer to a zero-argument monadic procedure
- (@pxref{The Store Monad}). The procedure must return a derivation as a
- monadic value, which is then passed through @code{run-with-store}.
- @item --source
- @itemx -S
- Build the source derivations of the packages, rather than the packages
- themselves.
- For instance, @code{guix build -S gcc} returns something like
- @file{/gnu/store/@dots{}-gcc-4.7.2.tar.bz2}, which is the GCC
- source tarball.
- The returned source tarball is the result of applying any patches and
- code snippets specified in the package @code{origin} (@pxref{Defining
- Packages}).
- @cindex source, verification
- As with other derivations, the result of building a source derivation
- can be verified using the @option{--check} option (@pxref{build-check}).
- This is useful to validate that a (potentially already built or
- substituted, thus cached) package source matches against its declared
- hash.
- Note that @command{guix build -S} compiles the sources only of the
- specified packages. They do not include the sources of statically
- linked dependencies and by themselves are insufficient for reproducing
- the packages.
- @item --sources
- Fetch and return the source of @var{package-or-derivation} and all their
- dependencies, recursively. This is a handy way to obtain a local copy
- of all the source code needed to build @var{packages}, allowing you to
- eventually build them even without network access. It is an extension
- of the @option{--source} option and can accept one of the following
- optional argument values:
- @table @code
- @item package
- This value causes the @option{--sources} option to behave in the same way
- as the @option{--source} option.
- @item all
- Build the source derivations of all packages, including any source that
- might be listed as @code{inputs}. This is the default value.
- @example
- $ guix build --sources tzdata
- The following derivations will be built:
- /gnu/store/@dots{}-tzdata2015b.tar.gz.drv
- /gnu/store/@dots{}-tzcode2015b.tar.gz.drv
- @end example
- @item transitive
- Build the source derivations of all packages, as well of all transitive
- inputs to the packages. This can be used e.g.@: to
- prefetch package source for later offline building.
- @example
- $ guix build --sources=transitive tzdata
- The following derivations will be built:
- /gnu/store/@dots{}-tzcode2015b.tar.gz.drv
- /gnu/store/@dots{}-findutils-4.4.2.tar.xz.drv
- /gnu/store/@dots{}-grep-2.21.tar.xz.drv
- /gnu/store/@dots{}-coreutils-8.23.tar.xz.drv
- /gnu/store/@dots{}-make-4.1.tar.xz.drv
- /gnu/store/@dots{}-bash-4.3.tar.xz.drv
- @dots{}
- @end example
- @end table
- @item --system=@var{system}
- @itemx -s @var{system}
- Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of
- the system type of the build host. The @command{guix build} command allows
- you to repeat this option several times, in which case it builds for all the
- specified systems; other commands ignore extraneous @option{-s} options.
- @quotation Note
- The @option{--system} flag is for @emph{native} compilation and must not
- be confused with cross-compilation. See @option{--target} below for
- information on cross-compilation.
- @end quotation
- An example use of this is on Linux-based systems, which can emulate
- different personalities. For instance, passing
- @option{--system=i686-linux} on an @code{x86_64-linux} system or
- @option{--system=armhf-linux} on an @code{aarch64-linux} system allows
- you to build packages in a complete 32-bit environment.
- @quotation Note
- Building for an @code{armhf-linux} system is unconditionally enabled on
- @code{aarch64-linux} machines, although certain aarch64 chipsets do not
- allow for this functionality, notably the ThunderX.
- @end quotation
- Similarly, when transparent emulation with QEMU and @code{binfmt_misc}
- is enabled (@pxref{Virtualization Services,
- @code{qemu-binfmt-service-type}}), you can build for any system for
- which a QEMU @code{binfmt_misc} handler is installed.
- Builds for a system other than that of the machine you are using can
- also be offloaded to a remote machine of the right architecture.
- @xref{Daemon Offload Setup}, for more information on offloading.
- @item --target=@var{triplet}
- @cindex cross-compilation
- Cross-build for @var{triplet}, which must be a valid GNU triplet, such
- as @code{"aarch64-linux-gnu"} (@pxref{Specifying Target Triplets, GNU
- configuration triplets,, autoconf, Autoconf}).
- @anchor{build-check}
- @item --check
- @cindex determinism, checking
- @cindex reproducibility, checking
- Rebuild @var{package-or-derivation}, which are already available in the
- store, and raise an error if the build results are not bit-for-bit
- identical.
- This mechanism allows you to check whether previously installed
- substitutes are genuine (@pxref{Substitutes}), or whether the build result
- of a package is deterministic. @xref{Invoking guix challenge}, for more
- background information and tools.
- When used in conjunction with @option{--keep-failed}, the differing
- output is kept in the store, under @file{/gnu/store/@dots{}-check}.
- This makes it easy to look for differences between the two results.
- @item --repair
- @cindex repairing store items
- @cindex corruption, recovering from
- Attempt to repair the specified store items, if they are corrupt, by
- re-downloading or rebuilding them.
- This operation is not atomic and thus restricted to @code{root}.
- @item --derivations
- @itemx -d
- Return the derivation paths, not the output paths, of the given
- packages.
- @item --root=@var{file}
- @itemx -r @var{file}
- @cindex GC roots, adding
- @cindex garbage collector roots, adding
- Make @var{file} a symlink to the result, and register it as a garbage
- collector root.
- Consequently, the results of this @command{guix build} invocation are
- protected from garbage collection until @var{file} is removed. When
- that option is omitted, build results are eligible for garbage
- collection as soon as the build completes. @xref{Invoking guix gc}, for
- more on GC roots.
- @item --log-file
- @cindex build logs, access
- Return the build log file names or URLs for the given
- @var{package-or-derivation}, or raise an error if build logs are
- missing.
- This works regardless of how packages or derivations are specified. For
- instance, the following invocations are equivalent:
- @example
- guix build --log-file $(guix build -d guile)
- guix build --log-file $(guix build guile)
- guix build --log-file guile
- guix build --log-file -e '(@@ (gnu packages guile) guile-2.0)'
- @end example
- If a log is unavailable locally, and unless @option{--no-substitutes} is
- passed, the command looks for a corresponding log on one of the
- substitute servers (as specified with @option{--substitute-urls}).
- So for instance, imagine you want to see the build log of GDB on MIPS,
- but you are actually on an @code{x86_64} machine:
- @example
- $ guix build --log-file gdb -s aarch64-linux
- https://@value{SUBSTITUTE-SERVER-1}/log/@dots{}-gdb-7.10
- @end example
- You can freely access a huge library of build logs!
- @end table
- @node Debugging Build Failures
- @subsection Debugging Build Failures
- @cindex build failures, debugging
- When defining a new package (@pxref{Defining Packages}), you will
- probably find yourself spending some time debugging and tweaking the
- build until it succeeds. To do that, you need to operate the build
- commands yourself in an environment as close as possible to the one the
- build daemon uses.
- To that end, the first thing to do is to use the @option{--keep-failed}
- or @option{-K} option of @command{guix build}, which will keep the
- failed build tree in @file{/tmp} or whatever directory you specified as
- @env{TMPDIR} (@pxref{Common Build Options, @option{--keep-failed}}).
- From there on, you can @command{cd} to the failed build tree and source
- the @file{environment-variables} file, which contains all the
- environment variable definitions that were in place when the build
- failed. So let's say you're debugging a build failure in package
- @code{foo}; a typical session would look like this:
- @example
- $ guix build foo -K
- @dots{} @i{build fails}
- $ cd /tmp/guix-build-foo.drv-0
- $ source ./environment-variables
- $ cd foo-1.2
- @end example
- Now, you can invoke commands as if you were the daemon (almost) and
- troubleshoot your build process.
- Sometimes it happens that, for example, a package's tests pass when you
- run them manually but they fail when the daemon runs them. This can
- happen because the daemon runs builds in containers where, unlike in our
- environment above, network access is missing, @file{/bin/sh} does not
- exist, etc. (@pxref{Build Environment Setup}).
- In such cases, you may need to run inspect the build process from within
- a container similar to the one the build daemon creates:
- @example
- $ guix build -K foo
- @dots{}
- $ cd /tmp/guix-build-foo.drv-0
- $ guix 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 minetest
- @cindex minetest
- @cindex ContentDB
- Import metadata from @uref{https://content.minetest.net, ContentDB}.
- Information is taken from the JSON-formatted metadata provided through
- @uref{https://content.minetest.net/help/api/, ContentDB's API} and
- includes most relevant information, including dependencies. There are
- some caveats, however. The license information is often incomplete.
- The commit hash is sometimes missing. The descriptions are in the
- Markdown format, but Guix uses Texinfo instead. Texture packs and
- subgames are unsupported.
- The command below imports metadata for the Mesecons mod by Jeija:
- @example
- guix import minetest Jeija/mesecons
- @end example
- The author name can also be left out:
- @example
- guix import minetest mesecons
- @end example
- @table @code
- @item --recursive
- @itemx -r
- Traverse the dependency graph of the given upstream package recursively
- and generate package expressions for all those packages that are not yet
- in Guix.
- @end table
- @item cpan
- @cindex CPAN
- Import metadata from @uref{https://www.metacpan.org/, MetaCPAN}.
- Information is taken from the JSON-formatted metadata provided through
- @uref{https://fastapi.metacpan.org/, MetaCPAN's API} and includes most
- relevant information, such as module dependencies. License information
- should be checked closely. If Perl is available in the store, then the
- @code{corelist} utility will be used to filter core modules out of the
- list of dependencies.
- The command command below imports metadata for the Acme::Boolean Perl
- module:
- @example
- guix import cpan Acme::Boolean
- @end example
- @item cran
- @cindex CRAN
- @cindex Bioconductor
- Import metadata from @uref{https://cran.r-project.org/, CRAN}, the
- central repository for the @uref{https://r-project.org, GNU@tie{}R
- statistical and graphical environment}.
- Information is extracted from the @file{DESCRIPTION} file of the package.
- The command command below imports metadata for the Cairo R package:
- @example
- guix import cran Cairo
- @end example
- 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 hackage
- @cindex hackage
- Import metadata from the Haskell community's central package archive
- @uref{https://hackage.haskell.org/, Hackage}. Information is taken from
- Cabal files and includes all the relevant information, including package
- dependencies.
- Specific command-line options are:
- @table @code
- @item --stdin
- @itemx -s
- Read a Cabal file from standard input.
- @item --no-test-dependencies
- @itemx -t
- Do not include dependencies required only by the test suites.
- @item --cabal-environment=@var{alist}
- @itemx -e @var{alist}
- @var{alist} is a Scheme alist defining the environment in which the
- Cabal conditionals are evaluated. The accepted keys are: @code{os},
- @code{arch}, @code{impl} and a string representing the name of a flag.
- The value associated with a flag has to be either the symbol
- @code{true} or @code{false}. The value associated with other keys
- has to conform to the Cabal file format definition. The default value
- associated with the keys @code{os}, @code{arch} and @code{impl} is
- @samp{linux}, @samp{x86_64} and @samp{ghc}, respectively.
- @item --recursive
- @itemx -r
- Traverse the dependency graph of the given upstream package recursively
- and generate package expressions for all those packages that are not yet
- in Guix.
- @end table
- The command below imports metadata for the latest version of the
- HTTP Haskell package without including test dependencies and
- specifying the value of the flag @samp{network-uri} as @code{false}:
- @example
- guix import hackage -t -e "'((\"network-uri\" . false))" HTTP
- @end example
- A specific package version may optionally be specified by following the
- package name by an at-sign and a version number as in the following example:
- @example
- guix import hackage mtl@@2.1.3.1
- @end example
- @item stackage
- @cindex stackage
- The @code{stackage} importer is a wrapper around the @code{hackage} one.
- It takes a package name, looks up the package version included in a
- long-term support (LTS) @uref{https://www.stackage.org, Stackage}
- release and uses the @code{hackage} importer to retrieve its metadata.
- Note that it is up to you to select an LTS release compatible with the
- GHC compiler used by Guix.
- Specific command-line options are:
- @table @code
- @item --no-test-dependencies
- @itemx -t
- Do not include dependencies required only by the test suites.
- @item --lts-version=@var{version}
- @itemx -l @var{version}
- @var{version} is the desired LTS release version. If omitted the latest
- release is used.
- @item --recursive
- @itemx -r
- Traverse the dependency graph of the given upstream package recursively
- and generate package expressions for all those packages that are not yet
- in Guix.
- @end table
- The command below imports metadata for the HTTP Haskell package
- included in the LTS Stackage release version 7.18:
- @example
- guix import stackage --lts-version=7.18 HTTP
- @end example
- @item elpa
- @cindex elpa
- Import metadata from an Emacs Lisp Package Archive (ELPA) package
- repository (@pxref{Packages,,, emacs, The GNU Emacs Manual}).
- Specific command-line options are:
- @table @code
- @item --archive=@var{repo}
- @itemx -a @var{repo}
- @var{repo} identifies the archive repository from which to retrieve the
- information. Currently the supported repositories and their identifiers
- are:
- @itemize -
- @item
- @uref{https://elpa.gnu.org/packages, GNU}, selected by the @code{gnu}
- identifier. This is the default.
- Packages from @code{elpa.gnu.org} are signed with one of the keys
- contained in the GnuPG keyring at
- @file{share/emacs/25.1/etc/package-keyring.gpg} (or similar) in the
- @code{emacs} package (@pxref{Package Installation, ELPA package
- signatures,, emacs, The GNU Emacs Manual}).
- @item
- @uref{https://elpa.nongnu.org/nongnu/, NonGNU}, selected by the
- @code{nongnu} identifier.
- @item
- @uref{https://stable.melpa.org/packages, MELPA-Stable}, selected by the
- @code{melpa-stable} identifier.
- @item
- @uref{https://melpa.org/packages, MELPA}, selected by the @code{melpa}
- identifier.
- @end itemize
- @item --recursive
- @itemx -r
- Traverse the dependency graph of the given upstream package recursively
- and generate package expressions for all those packages that are not yet
- in Guix.
- @end table
- @item crate
- @cindex crate
- Import metadata from the crates.io Rust package repository
- @uref{https://crates.io, crates.io}, as in this example:
- @example
- guix import crate blake2-rfc
- @end example
- The crate importer also allows you to specify a version string:
- @example
- guix import crate constant-time-eq@@0.1.0
- @end example
- Additional options include:
- @table @code
- @item --recursive
- @itemx -r
- Traverse the dependency graph of the given upstream package recursively
- and generate package expressions for all those packages that are not yet
- in Guix.
- @end table
- @item opam
- @cindex OPAM
- @cindex OCaml
- Import metadata from the @uref{https://opam.ocaml.org/, OPAM} package
- repository used by the OCaml community.
- Additional options include:
- @table @code
- @item --recursive
- @itemx -r
- Traverse the dependency graph of the given upstream package recursively
- and generate package expressions for all those packages that are not yet
- in Guix.
- @item --repo
- By default, packages are searched in the official OPAM repository. This
- option, which can be used more than once, lets you add other repositories
- which will be searched for packages. It accepts as valid arguments:
- @itemize
- @item the name of a known repository - can be one of @code{opam},
- @code{coq} (equivalent to @code{coq-released}),
- @code{coq-core-dev}, @code{coq-extra-dev} or @code{grew}.
- @item the URL of a repository as expected by the
- @code{opam repository add} command (for instance, the URL equivalent
- of the above @code{opam} name would be
- @uref{https://opam.ocaml.org}).
- @item the path to a local copy of a repository (a directory containing a
- @file{packages/} sub-directory).
- @end itemize
- Repositories are assumed to be passed to this option by order of
- preference. The additional repositories will not replace the default
- @code{opam} repository, which is always kept as a fallback.
- Also, please note that versions are not compared accross repositories.
- The first repository (from left to right) that has at least one version
- of a given package will prevail over any others, and the version
- imported will be the latest one found @emph{in this repository only}.
- @end table
- @item go
- @cindex go
- Import metadata for a Go module using
- @uref{https://proxy.golang.org, proxy.golang.org}.
- @example
- guix import go gopkg.in/yaml.v2
- @end example
- It is possible to use a package specification with a @code{@@VERSION}
- suffix to import a specific version.
- Additional options include:
- @table @code
- @item --recursive
- @itemx -r
- Traverse the dependency graph of the given upstream package recursively
- and generate package expressions for all those packages that are not yet
- in Guix.
- @item --pin-versions
- When using this option, the importer preserves the exact versions of the
- Go modules dependencies instead of using their latest available
- versions. This can be useful when attempting to import packages that
- recursively depend on former versions of themselves to build. When
- using this mode, the symbol of the package is made by appending the
- version to its name, so that multiple versions of the same package can
- coexist.
- @end table
- @item egg
- @cindex egg
- Import metadata for @uref{https://wiki.call-cc.org/eggs, CHICKEN eggs}.
- The information is taken from @file{PACKAGE.egg} files found in the
- @uref{git://code.call-cc.org/eggs-5-latest, eggs-5-latest} Git
- repository. However, it does not provide all the information that we
- need, there is no ``description'' field, and the licenses used are not
- always precise (BSD is often used instead of BSD-N).
- @example
- guix import egg sourcehut
- @end example
- Additional options include:
- @table @code
- @item --recursive
- @itemx -r
- Traverse the dependency graph of the given upstream package recursively
- and generate package expressions for all those packages that are not yet
- in Guix.
- @end table
- @end table
- The structure of the @command{guix import} code is modular. It would be
- useful to have more importers for other package formats, and your help
- is welcome here (@pxref{Contributing}).
- @node Invoking guix refresh
- @section Invoking @command{guix refresh}
- @cindex @command {guix refresh}
- The primary audience of the @command{guix refresh} command is packagers.
- As a user, you may be interested in the @option{--with-latest} option,
- which can bring you package update superpowers built upon @command{guix
- refresh} (@pxref{Package Transformation Options,
- @option{--with-latest}}). By default, @command{guix refresh} reports
- any packages provided by the distribution that are outdated compared to
- the latest upstream version, like this:
- @example
- $ guix refresh
- gnu/packages/gettext.scm:29:13: gettext would be upgraded from 0.18.1.1 to 0.18.2.1
- gnu/packages/glib.scm:77:12: glib would be upgraded from 2.34.3 to 2.37.0
- @end example
- Alternatively, one can specify packages to consider, in which case a
- warning is emitted for packages that lack an updater:
- @example
- $ guix refresh coreutils guile guile-ssh
- gnu/packages/ssh.scm:205:2: warning: no updater for guile-ssh
- gnu/packages/guile.scm:136:12: guile would be upgraded from 2.0.12 to 2.0.13
- @end example
- @command{guix refresh} browses the upstream repository of each package and determines
- the highest version number of the releases therein. The command
- knows how to update specific types of packages: GNU packages, ELPA
- packages, etc.---see the documentation for @option{--type} below. There
- are many packages, though, for which it lacks a method to determine
- whether a new upstream release is available. However, the mechanism is
- extensible, so feel free to get in touch with us to add a new method!
- @table @code
- @item --recursive
- Consider the packages specified, and all the packages upon which they depend.
- @example
- $ guix refresh --recursive coreutils
- gnu/packages/acl.scm:40:13: acl would be upgraded from 2.2.53 to 2.3.1
- gnu/packages/m4.scm:30:12: 1.4.18 is already the latest version of m4
- gnu/packages/xml.scm:68:2: warning: no updater for expat
- gnu/packages/multiprecision.scm:40:12: 6.1.2 is already the latest version of gmp
- @dots{}
- @end example
- @end table
- Sometimes the upstream name differs from the package name used in Guix,
- and @command{guix refresh} needs a little help. Most updaters honor the
- @code{upstream-name} property in package definitions, which can be used
- to that effect:
- @lisp
- (define-public network-manager
- (package
- (name "network-manager")
- ;; @dots{}
- (properties '((upstream-name . "NetworkManager")))))
- @end lisp
- When passed @option{--update}, it modifies distribution source files to
- update the version numbers and source tarball hashes of those package
- recipes (@pxref{Defining Packages}). This is achieved by downloading
- each package's latest source tarball and its associated OpenPGP
- signature, authenticating the downloaded tarball against its signature
- using @command{gpgv}, and finally computing its hash---note that GnuPG must be
- installed and in @code{$PATH}; run @code{guix install gnupg} if needed.
- When the public
- key used to sign the tarball is missing from the user's keyring, an
- attempt is made to automatically retrieve it from a public key server;
- when this is successful, the key is added to the user's keyring; otherwise,
- @command{guix refresh} reports an error.
- The following options are supported:
- @table @code
- @item --expression=@var{expr}
- @itemx -e @var{expr}
- Consider the package @var{expr} evaluates to.
- This is useful to precisely refer to a package, as in this example:
- @example
- guix refresh -l -e '(@@@@ (gnu packages commencement) glibc-final)'
- @end example
- This command lists the dependents of the ``final'' libc (essentially all
- the packages).
- @item --update
- @itemx -u
- Update distribution source files (package recipes) in place. This is
- usually run from a checkout of the Guix source tree (@pxref{Running
- Guix Before It Is Installed}):
- @example
- $ ./pre-inst-env guix refresh -s non-core -u
- @end example
- @xref{Defining Packages}, for more information on package definitions.
- @item --select=[@var{subset}]
- @itemx -s @var{subset}
- Select all the packages in @var{subset}, one of @code{core} or
- @code{non-core}.
- The @code{core} subset refers to all the packages at the core of the
- distribution---i.e., packages that are used to build ``everything
- else''. This includes GCC, libc, Binutils, Bash, etc. Usually,
- changing one of these packages in the distribution entails a rebuild of
- all the others. Thus, such updates are an inconvenience to users in
- terms of build time or bandwidth used to achieve the upgrade.
- The @code{non-core} subset refers to the remaining packages. It is
- typically useful in cases where an update of the core packages would be
- inconvenient.
- @item --manifest=@var{file}
- @itemx -m @var{file}
- Select all the packages from the manifest in @var{file}. This is useful to
- check if any packages of the user manifest can be updated.
- @item --type=@var{updater}
- @itemx -t @var{updater}
- Select only packages handled by @var{updater} (may be a comma-separated
- list of updaters). Currently, @var{updater} may be one of:
- @table @code
- @item gnu
- the updater for GNU packages;
- @item savannah
- the updater for packages hosted at @uref{https://savannah.gnu.org, Savannah};
- @item sourceforge
- the updater for packages hosted at @uref{https://sourceforge.net, SourceForge};
- @item gnome
- the updater for GNOME packages;
- @item kde
- the updater for KDE packages;
- @item xorg
- the updater for X.org packages;
- @item kernel.org
- the updater for packages hosted on kernel.org;
- @item egg
- the updater for @uref{https://wiki.call-cc.org/eggs/, Egg} packages;
- @item elpa
- the updater for @uref{https://elpa.gnu.org/, ELPA} packages;
- @item cran
- the updater for @uref{https://cran.r-project.org/, CRAN} packages;
- @item bioconductor
- the updater for @uref{https://www.bioconductor.org/, Bioconductor} R packages;
- @item cpan
- the updater for @uref{https://www.cpan.org/, CPAN} packages;
- @item pypi
- the updater for @uref{https://pypi.python.org, PyPI} packages.
- @item gem
- the updater for @uref{https://rubygems.org, RubyGems} packages.
- @item github
- the updater for @uref{https://github.com, GitHub} packages.
- @item hackage
- the updater for @uref{https://hackage.haskell.org, Hackage} packages.
- @item stackage
- the updater for @uref{https://www.stackage.org, Stackage} packages.
- @item crate
- the updater for @uref{https://crates.io, Crates} packages.
- @item launchpad
- the updater for @uref{https://launchpad.net, Launchpad} packages.
- @item generic-html
- a generic updater that crawls the HTML page where the source tarball of
- the package is hosted, when applicable.
- @end table
- For instance, the following command only checks for updates of Emacs
- packages hosted at @code{elpa.gnu.org} and for updates of CRAN packages:
- @example
- $ guix refresh --type=elpa,cran
- gnu/packages/statistics.scm:819:13: r-testthat would be upgraded from 0.10.0 to 0.11.0
- gnu/packages/emacs.scm:856:13: emacs-auctex would be upgraded from 11.88.6 to 11.88.9
- @end example
- @item --list-updaters
- @itemx -L
- List available updaters and exit (see @option{--type} above).
- For each updater, display the fraction of packages it covers; at the
- end, display the fraction of packages covered by all these updaters.
- @end table
- In addition, @command{guix refresh} can be passed one or more package
- names, as in this example:
- @example
- $ ./pre-inst-env guix refresh -u emacs idutils gcc@@4.8
- @end example
- @noindent
- The command above specifically updates the @code{emacs} and
- @code{idutils} packages. The @option{--select} option would have no
- effect in this case. You might also want to update definitions that
- correspond to the packages installed in your profile:
- @example
- $ ./pre-inst-env guix refresh -u \
- $(guix package --list-installed | cut -f1)
- @end example
- When considering whether to upgrade a package, it is sometimes
- convenient to know which packages would be affected by the upgrade and
- should be checked for compatibility. For this the following option may
- be used when passing @command{guix refresh} one or more package names:
- @table @code
- @item --list-dependent
- @itemx -l
- List top-level dependent packages that would need to be rebuilt as a
- result of upgrading one or more packages.
- @xref{Invoking guix graph, the @code{reverse-package} type of
- @command{guix graph}}, for information on how to visualize the list of
- dependents of a package.
- @end table
- Be aware that the @option{--list-dependent} option only
- @emph{approximates} the rebuilds that would be required as a result of
- an upgrade. More rebuilds might be required under some circumstances.
- @example
- $ guix refresh --list-dependent flex
- Building the following 120 packages would ensure 213 dependent packages are rebuilt:
- hop@@2.4.0 emacs-geiser@@0.13 notmuch@@0.18 mu@@0.9.9.5 cflow@@1.4 idutils@@4.6 @dots{}
- @end example
- The command above lists a set of packages that could be built to check
- for compatibility with an upgraded @code{flex} package.
- @table @code
- @item --list-transitive
- List all the packages which one or more packages depend upon.
- @example
- $ guix refresh --list-transitive flex
- flex@@2.6.4 depends on the following 25 packages: perl@@5.28.0 help2man@@1.47.6
- bison@@3.0.5 indent@@2.2.10 tar@@1.30 gzip@@1.9 bzip2@@1.0.6 xz@@5.2.4 file@@5.33 @dots{}
- @end example
- @end table
- The command above lists a set of packages which, when changed, would cause
- @code{flex} to be rebuilt.
- The following options can be used to customize GnuPG operation:
- @table @code
- @item --gpg=@var{command}
- Use @var{command} as the GnuPG 2.x command. @var{command} is searched
- for in @code{$PATH}.
- @item --keyring=@var{file}
- Use @var{file} as the keyring for upstream keys. @var{file} must be in the
- @dfn{keybox format}. Keybox files usually have a name ending in @file{.kbx}
- and the GNU@tie{}Privacy Guard (GPG) can manipulate these files
- (@pxref{kbxutil, @command{kbxutil},, gnupg, Using the GNU Privacy Guard}, for
- information on a tool to manipulate keybox files).
- When this option is omitted, @command{guix refresh} uses
- @file{~/.config/guix/upstream/trustedkeys.kbx} as the keyring for upstream
- signing keys. OpenPGP signatures are checked against keys from this keyring;
- missing keys are downloaded to this keyring as well (see
- @option{--key-download} below).
- You can export keys from your default GPG keyring into a keybox file using
- commands like this one:
- @example
- gpg --export rms@@gnu.org | kbxutil --import-openpgp >> mykeyring.kbx
- @end example
- Likewise, you can fetch keys to a specific keybox file like this:
- @example
- gpg --no-default-keyring --keyring mykeyring.kbx \
- --recv-keys @value{OPENPGP-SIGNING-KEY-ID}
- @end example
- @xref{GPG Configuration Options, @option{--keyring},, gnupg, Using the GNU
- Privacy Guard}, for more information on GPG's @option{--keyring} option.
- @item --key-download=@var{policy}
- Handle missing OpenPGP keys according to @var{policy}, which may be one
- of:
- @table @code
- @item always
- Always download missing OpenPGP keys from the key server, and add them
- to the user's GnuPG keyring.
- @item never
- Never try to download missing OpenPGP keys. Instead just bail out.
- @item interactive
- When a package signed with an unknown OpenPGP key is encountered, ask
- the user whether to download it or not. This is the default behavior.
- @end table
- @item --key-server=@var{host}
- Use @var{host} as the OpenPGP key server when importing a public key.
- @item --load-path=@var{directory}
- Add @var{directory} to the front of the package module search path
- (@pxref{Package Modules}).
- This allows users to define their own packages and make them visible to
- the command-line tools.
- @end table
- The @code{github} updater uses the
- @uref{https://developer.github.com/v3/, GitHub API} to query for new
- releases. When used repeatedly e.g.@: when refreshing all packages,
- GitHub will eventually refuse to answer any further API requests. By
- default 60 API requests per hour are allowed, and a full refresh on all
- GitHub packages in Guix requires more than this. Authentication with
- GitHub through the use of an API token alleviates these limits. To use
- an API token, set the environment variable @env{GUIX_GITHUB_TOKEN} to a
- token procured from @uref{https://github.com/settings/tokens} or
- otherwise.
- @node Invoking guix style
- @section Invoking @command{guix style}
- The @command{guix style} command helps packagers style their package
- definitions according to the latest fashionable trends. The command
- currently focuses on one aspect: the style of package inputs. It may
- eventually be extended to handle other stylistic matters.
- The way package inputs are written is going through a transition
- (@pxref{package Reference}, for more on package inputs). Until version
- 1.3.0, package inputs were written using the ``old style'', where each
- input was given an explicit label, most of the time the package name:
- @lisp
- (package
- ;; @dots{}
- ;; The "old style" (deprecated).
- (inputs `(("libunistring" ,libunistring)
- ("libffi" ,libffi))))
- @end lisp
- Today, the old style is deprecated and the preferred style looks like
- this:
- @lisp
- (package
- ;; @dots{}
- ;; The "new style".
- (inputs (list libunistring libffi)))
- @end lisp
- Likewise, uses of @code{alist-delete} and friends to manipulate inputs
- is now deprecated in favor of @code{modify-inputs} (@pxref{Defining
- Package Variants}, for more info on @code{modify-inputs}).
- In the vast majority of cases, this is a purely mechanical change on the
- surface syntax that does not even incur a package rebuild. Running
- @command{guix style} can do that for you, whether you're working on
- packages in Guix proper or in an external channel.
- The general syntax is:
- @example
- guix style [@var{options}] @var{package}@dots{}
- @end example
- This causes @command{guix style} to analyze and rewrite the definition
- of @var{package}@dots{}. It does so in a conservative way: preserving
- comments and bailing out if it cannot make sense of the code that
- appears in an inputs field. The available options are listed below.
- @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}).
- @item --expression=@var{expr}
- @itemx -e @var{expr}
- Style the package @var{expr} evaluates to.
- For example, running:
- @example
- guix style -e '(@@ (gnu packages gcc) gcc-5)'
- @end example
- styles the @code{gcc-5} package definition.
- @item --input-simplification=@var{policy}
- Specify the package input simplification policy for cases where an input
- label does not match the corresponding package name. @var{policy} may
- be one of the following:
- @table @code
- @item silent
- Simplify inputs only when the change is ``silent'', meaning that the
- package does not need to be rebuilt (its derivation is unchanged).
- @item safe
- Simplify inputs only when that is ``safe'' to do: the package might need
- to be rebuilt, but the change is known to have no observable effect.
- @item always
- Simplify inputs even when input labels do not match package names, and
- even if that might have an observable effect.
- @end table
- The default is @code{silent}, meaning that input simplifications do not
- trigger any package rebuild.
- @end table
- @node Invoking guix lint
- @section Invoking @command{guix lint}
- @cindex @command{guix lint}
- @cindex package, checking for errors
- The @command{guix lint} command is meant to help package developers avoid
- common errors and use a consistent style. It runs a number of checks on
- a given set of packages in order to find common mistakes in their
- definitions. Available @dfn{checkers} include (see
- @option{--list-checkers} for a complete list):
- @table @code
- @item synopsis
- @itemx description
- Validate certain typographical and stylistic rules about package
- descriptions and synopses.
- @item inputs-should-be-native
- Identify inputs that should most likely be native inputs.
- @item source
- @itemx home-page
- @itemx mirror-url
- @itemx github-url
- @itemx source-file-name
- Probe @code{home-page} and @code{source} URLs and report those that are
- invalid. Suggest a @code{mirror://} URL when applicable. If the
- @code{source} URL redirects to a GitHub URL, recommend usage of the GitHub
- URL@. Check that the source file name is meaningful, e.g.@: is not just a
- version number or ``git-checkout'', without a declared @code{file-name}
- (@pxref{origin Reference}).
- @item source-unstable-tarball
- Parse the @code{source} URL to determine if a tarball from GitHub is
- autogenerated or if it is a release tarball. Unfortunately GitHub's
- autogenerated tarballs are sometimes regenerated.
- @item derivation
- Check that the derivation of the given packages can be successfully
- computed for all the supported systems (@pxref{Derivations}).
- @item profile-collisions
- Check whether installing the given packages in a profile would lead to
- collisions. Collisions occur when several packages with the same name
- but a different version or a different store file name are propagated.
- @xref{package Reference, @code{propagated-inputs}}, for more information
- on propagated inputs.
- @item archival
- @cindex Software Heritage, source code archive
- @cindex archival of source code, Software Heritage
- Checks whether the package's source code is archived at
- @uref{https://www.softwareheritage.org, Software Heritage}.
- When the source code that is not archived comes from a version-control system
- (VCS)---e.g., it's obtained with @code{git-fetch}, send Software Heritage a
- ``save'' request so that it eventually archives it. This ensures that the
- source will remain available in the long term, and that Guix can fall back to
- Software Heritage should the source code disappear from its original host.
- The status of recent ``save'' requests can be
- @uref{https://archive.softwareheritage.org/save/#requests, viewed on-line}.
- When source code is a tarball obtained with @code{url-fetch}, simply print a
- message when it is not archived. As of this writing, Software Heritage does
- not allow requests to save arbitrary tarballs; we are working on ways to
- ensure that non-VCS source code is also archived.
- Software Heritage
- @uref{https://archive.softwareheritage.org/api/#rate-limiting, limits the
- request rate per IP address}. When the limit is reached, @command{guix lint}
- prints a message and the @code{archival} checker stops doing anything until
- that limit has been reset.
- @item cve
- @cindex security vulnerabilities
- @cindex CVE, Common Vulnerabilities and Exposures
- Report known vulnerabilities found in the Common Vulnerabilities and
- Exposures (CVE) databases of the current and past year
- @uref{https://nvd.nist.gov/vuln/data-feeds, published by the US
- NIST}.
- To view information about a particular vulnerability, visit pages such as:
- @itemize
- @item
- @indicateurl{https://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-YYYY-ABCD}
- @item
- @indicateurl{https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-YYYY-ABCD}
- @end itemize
- @noindent
- where @code{CVE-YYYY-ABCD} is the CVE identifier---e.g.,
- @code{CVE-2015-7554}.
- Package developers can specify in package recipes the
- @uref{https://nvd.nist.gov/products/cpe,Common Platform Enumeration (CPE)}
- name and version of the package when they differ from the name or version
- that Guix uses, as in this example:
- @lisp
- (package
- (name "grub")
- ;; @dots{}
- ;; CPE calls this package "grub2".
- (properties '((cpe-name . "grub2")
- (cpe-version . "2.3"))))
- @end lisp
- @c See <https://www.openwall.com/lists/oss-security/2017/03/15/3>.
- Some entries in the CVE database do not specify which version of a
- package they apply to, and would thus ``stick around'' forever. Package
- developers who found CVE alerts and verified they can be ignored can
- declare them as in this example:
- @lisp
- (package
- (name "t1lib")
- ;; @dots{}
- ;; These CVEs no longer apply and can be safely ignored.
- (properties `((lint-hidden-cve . ("CVE-2011-0433"
- "CVE-2011-1553"
- "CVE-2011-1554"
- "CVE-2011-5244")))))
- @end lisp
- @item formatting
- Warn about obvious source code formatting issues: trailing white space,
- use of tabulations, etc.
- @item input-labels
- Report old-style input labels that do not match the name of the
- corresponding package. This aims to help migrate from the ``old input
- style''. @xref{package Reference}, for more information on package
- inputs and input styles. @xref{Invoking guix style}, on how to migrate
- to the new style.
- @end table
- The general syntax is:
- @example
- guix lint @var{options} @var{package}@dots{}
- @end example
- If no package is given on the command line, then all packages are checked.
- The @var{options} may be zero or more of the following:
- @table @code
- @item --list-checkers
- @itemx -l
- List and describe all the available checkers that will be run on packages
- and exit.
- @item --checkers
- @itemx -c
- Only enable the checkers specified in a comma-separated list using the
- names returned by @option{--list-checkers}.
- @item --exclude
- @itemx -x
- Only disable the checkers specified in a comma-separated list using the
- names returned by @option{--list-checkers}.
- @item --no-network
- @itemx -n
- Only enable the checkers that do not depend on Internet access.
- @item --load-path=@var{directory}
- @itemx -L @var{directory}
- Add @var{directory} to the front of the package module search path
- (@pxref{Package Modules}).
- This allows users to define their own packages and make them visible to
- the command-line tools.
- @end table
- @node Invoking guix size
- @section Invoking @command{guix size}
- @cindex size
- @cindex package size
- @cindex closure
- @cindex @command{guix size}
- The @command{guix size} command helps package developers profile the
- disk usage of packages. It is easy to overlook the impact of an
- additional dependency added to a package, or the impact of using a
- single output for a package that could easily be split (@pxref{Packages
- with Multiple Outputs}). Such are the typical issues that
- @command{guix size} can highlight.
- The command can be passed one or more package specifications
- such as @code{gcc@@4.8}
- or @code{guile:debug}, or a file name in the store. Consider this
- example:
- @example
- $ guix size coreutils
- store item total self
- /gnu/store/@dots{}-gcc-5.5.0-lib 60.4 30.1 38.1%
- /gnu/store/@dots{}-glibc-2.27 30.3 28.8 36.6%
- /gnu/store/@dots{}-coreutils-8.28 78.9 15.0 19.0%
- /gnu/store/@dots{}-gmp-6.1.2 63.1 2.7 3.4%
- /gnu/store/@dots{}-bash-static-4.4.12 1.5 1.5 1.9%
- /gnu/store/@dots{}-acl-2.2.52 61.1 0.4 0.5%
- /gnu/store/@dots{}-attr-2.4.47 60.6 0.2 0.3%
- /gnu/store/@dots{}-libcap-2.25 60.5 0.2 0.2%
- total: 78.9 MiB
- @end example
- @cindex closure
- The store items listed here constitute the @dfn{transitive closure} of
- Coreutils---i.e., Coreutils and all its dependencies, recursively---as
- would be returned by:
- @example
- $ guix gc -R /gnu/store/@dots{}-coreutils-8.23
- @end example
- Here the output shows three columns next to store items. The first column,
- labeled ``total'', shows the size in mebibytes (MiB) of the closure of
- the store item---that is, its own size plus the size of all its
- dependencies. The next column, labeled ``self'', shows the size of the
- item itself. The last column shows the ratio of the size of the item
- itself to the space occupied by all the items listed here.
- In this example, we see that the closure of Coreutils weighs in at
- 79@tie{}MiB, most of which is taken by libc and GCC's run-time support
- libraries. (That libc and GCC's libraries represent a large fraction of
- the closure is not a problem @i{per se} because they are always available
- on the system anyway.)
- Since the command also accepts store file names, assessing the size of
- a build result is straightforward:
- @example
- guix size $(guix system build config.scm)
- @end example
- When the package(s) passed to @command{guix size} are available in the
- store@footnote{More precisely, @command{guix size} looks for the
- @emph{ungrafted} variant of the given package(s), as returned by
- @code{guix build @var{package} --no-grafts}. @xref{Security Updates},
- for information on grafts.}, @command{guix size} queries the daemon to determine its
- dependencies, and measures its size in the store, similar to @command{du
- -ms --apparent-size} (@pxref{du invocation,,, coreutils, GNU
- Coreutils}).
- When the given packages are @emph{not} in the store, @command{guix size}
- reports information based on the available substitutes
- (@pxref{Substitutes}). This makes it possible it to profile disk usage of
- store items that are not even on disk, only available remotely.
- You can also specify several package names:
- @example
- $ guix size coreutils grep sed bash
- store item total self
- /gnu/store/@dots{}-coreutils-8.24 77.8 13.8 13.4%
- /gnu/store/@dots{}-grep-2.22 73.1 0.8 0.8%
- /gnu/store/@dots{}-bash-4.3.42 72.3 4.7 4.6%
- /gnu/store/@dots{}-readline-6.3 67.6 1.2 1.2%
- @dots{}
- total: 102.3 MiB
- @end example
- @noindent
- In this example we see that the combination of the four packages takes
- 102.3@tie{}MiB in total, which is much less than the sum of each closure
- since they have a lot of dependencies in common.
- When looking at the profile returned by @command{guix size}, you may
- find yourself wondering why a given package shows up in the profile at
- all. To understand it, you can use @command{guix graph --path -t
- references} to display the shortest path between the two packages
- (@pxref{Invoking guix graph}).
- The available options are:
- @table @option
- @item --substitute-urls=@var{urls}
- Use substitute information from @var{urls}.
- @xref{client-substitute-urls, the same option for @code{guix build}}.
- @item --sort=@var{key}
- Sort lines according to @var{key}, one of the following options:
- @table @code
- @item self
- the size of each item (the default);
- @item closure
- the total size of the item's closure.
- @end table
- @item --map-file=@var{file}
- Write a graphical map of disk usage in PNG format to @var{file}.
- For the example above, the map looks like this:
- @image{images/coreutils-size-map,5in,, map of Coreutils disk usage
- produced by @command{guix size}}
- This option requires that
- @uref{https://wingolog.org/software/guile-charting/, Guile-Charting} be
- installed and visible in Guile's module search path. When that is not
- the case, @command{guix size} fails as it tries to load it.
- @item --system=@var{system}
- @itemx -s @var{system}
- Consider packages for @var{system}---e.g., @code{x86_64-linux}.
- @item --load-path=@var{directory}
- @itemx -L @var{directory}
- Add @var{directory} to the front of the package module search path
- (@pxref{Package Modules}).
- This allows users to define their own packages and make them visible to
- the command-line tools.
- @end table
- @node Invoking guix graph
- @section Invoking @command{guix graph}
- @cindex DAG
- @cindex @command{guix graph}
- @cindex package dependencies
- Packages and their dependencies form a @dfn{graph}, specifically a
- directed acyclic graph (DAG). It can quickly become difficult to have a
- mental model of the package DAG, so the @command{guix graph} command
- provides a visual representation of the DAG@. By default,
- @command{guix graph} emits a DAG representation in the input format of
- @uref{https://www.graphviz.org/, Graphviz}, so its output can be passed
- directly to the @command{dot} command of Graphviz. It can also emit an
- HTML page with embedded JavaScript code to display a ``chord diagram''
- in a Web browser, using the @uref{https://d3js.org/, d3.js} library, or
- emit Cypher queries to construct a graph in a graph database supporting
- the @uref{https://www.opencypher.org/, openCypher} query language. With
- @option{--path}, it simply displays the shortest path between two
- packages. The general syntax is:
- @example
- guix graph @var{options} @var{package}@dots{}
- @end example
- For example, the following command generates a PDF file representing the
- package DAG for the GNU@tie{}Core Utilities, showing its build-time
- dependencies:
- @example
- guix graph coreutils | dot -Tpdf > dag.pdf
- @end example
- The output looks like this:
- @image{images/coreutils-graph,2in,,Dependency graph of the GNU Coreutils}
- Nice little graph, no?
- You may find it more pleasant to navigate the graph interactively with
- @command{xdot} (from the @code{xdot} package):
- @example
- guix graph coreutils | xdot -
- @end example
- But there is more than one graph! The one above is concise: it is the
- graph of package objects, omitting implicit inputs such as GCC, libc,
- grep, etc. It is often useful to have such a concise graph, but
- sometimes one may want to see more details. @command{guix graph} supports
- several types of graphs, allowing you to choose the level of detail:
- @table @code
- @item package
- This is the default type used in the example above. It shows the DAG of
- package objects, excluding implicit dependencies. It is concise, but
- filters out many details.
- @item reverse-package
- This shows the @emph{reverse} DAG of packages. For example:
- @example
- guix graph --type=reverse-package ocaml
- @end example
- ...@: yields the graph of packages that @emph{explicitly} depend on OCaml (if
- you are also interested in cases where OCaml is an implicit dependency, see
- @code{reverse-bag} below).
- Note that for core packages this can yield huge graphs. If all you want
- is to know the number of packages that depend on a given package, use
- @command{guix refresh --list-dependent} (@pxref{Invoking guix refresh,
- @option{--list-dependent}}).
- @item bag-emerged
- This is the package DAG, @emph{including} implicit inputs.
- For instance, the following command:
- @example
- guix graph --type=bag-emerged coreutils
- @end example
- ...@: yields this bigger graph:
- @image{images/coreutils-bag-graph,,5in,Detailed dependency graph of the GNU Coreutils}
- At the bottom of the graph, we see all the implicit inputs of
- @var{gnu-build-system} (@pxref{Build Systems, @code{gnu-build-system}}).
- Now, note that the dependencies of these implicit inputs---that is, the
- @dfn{bootstrap dependencies} (@pxref{Bootstrapping})---are not shown
- here, for conciseness.
- @item bag
- Similar to @code{bag-emerged}, but this time including all the bootstrap
- dependencies.
- @item bag-with-origins
- Similar to @code{bag}, but also showing origins and their dependencies.
- @item reverse-bag
- This shows the @emph{reverse} DAG of packages. Unlike @code{reverse-package},
- it also takes implicit dependencies into account. For example:
- @example
- guix graph -t reverse-bag dune
- @end example
- @noindent
- ...@: yields the graph of all packages that depend on Dune, directly or
- indirectly. Since Dune is an @emph{implicit} dependency of many packages
- @i{via} @code{dune-build-system}, this shows a large number of packages,
- whereas @code{reverse-package} would show very few if any.
- @item derivation
- This is the most detailed representation: It shows the DAG of
- derivations (@pxref{Derivations}) and plain store items. Compared to
- the above representation, many additional nodes are visible, including
- build scripts, patches, Guile modules, etc.
- For this type of graph, it is also possible to pass a @file{.drv} file
- name instead of a package name, as in:
- @example
- guix graph -t derivation $(guix system build -d my-config.scm)
- @end example
- @item module
- This is the graph of @dfn{package modules} (@pxref{Package Modules}).
- For example, the following command shows the graph for the package
- module that defines the @code{guile} package:
- @example
- guix graph -t module guile | xdot -
- @end example
- @end table
- All the types above correspond to @emph{build-time dependencies}. The
- following graph type represents the @emph{run-time dependencies}:
- @table @code
- @item references
- This is the graph of @dfn{references} of a package output, as returned
- by @command{guix gc --references} (@pxref{Invoking guix gc}).
- If the given package output is not available in the store, @command{guix
- graph} attempts to obtain dependency information from substitutes.
- Here you can also pass a store file name instead of a package name. For
- example, the command below produces the reference graph of your profile
- (which can be big!):
- @example
- guix graph -t references $(readlink -f ~/.guix-profile)
- @end example
- @item referrers
- This is the graph of the @dfn{referrers} of a store item, as returned by
- @command{guix gc --referrers} (@pxref{Invoking guix gc}).
- This relies exclusively on local information from your store. For
- instance, let us suppose that the current Inkscape is available in 10
- profiles on your machine; @command{guix graph -t referrers inkscape}
- will show a graph rooted at Inkscape and with those 10 profiles linked
- to it.
- It can help determine what is preventing a store item from being garbage
- collected.
- @end table
- @cindex shortest path, between packages
- Often, the graph of the package you are interested in does not fit on
- your screen, and anyway all you want to know is @emph{why} that package
- actually depends on some seemingly unrelated package. The
- @option{--path} option instructs @command{guix graph} to display the
- shortest path between two packages (or derivations, or store items,
- etc.):
- @example
- $ guix graph --path emacs libunistring
- emacs@@26.3
- mailutils@@3.9
- libunistring@@0.9.10
- $ guix graph --path -t derivation emacs libunistring
- /gnu/store/@dots{}-emacs-26.3.drv
- /gnu/store/@dots{}-mailutils-3.9.drv
- /gnu/store/@dots{}-libunistring-0.9.10.drv
- $ guix graph --path -t references emacs libunistring
- /gnu/store/@dots{}-emacs-26.3
- /gnu/store/@dots{}-libidn2-2.2.0
- /gnu/store/@dots{}-libunistring-0.9.10
- @end example
- The available options are the following:
- @table @option
- @item --type=@var{type}
- @itemx -t @var{type}
- Produce a graph output of @var{type}, where @var{type} must be one of
- the values listed above.
- @item --list-types
- List the supported graph types.
- @item --backend=@var{backend}
- @itemx -b @var{backend}
- Produce a graph using the selected @var{backend}.
- @item --list-backends
- List the supported graph backends.
- Currently, the available backends are Graphviz and d3.js.
- @item --path
- Display the shortest path between two nodes of the type specified by
- @option{--type}. The example below shows the shortest path between
- @code{libreoffice} and @code{llvm} according to the references of
- @code{libreoffice}:
- @example
- $ guix graph --path -t references libreoffice llvm
- /gnu/store/@dots{}-libreoffice-6.4.2.2
- /gnu/store/@dots{}-libepoxy-1.5.4
- /gnu/store/@dots{}-mesa-19.3.4
- /gnu/store/@dots{}-llvm-9.0.1
- @end example
- @item --expression=@var{expr}
- @itemx -e @var{expr}
- Consider the package @var{expr} evaluates to.
- This is useful to precisely refer to a package, as in this example:
- @example
- guix graph -e '(@@@@ (gnu packages commencement) gnu-make-final)'
- @end example
- @item --system=@var{system}
- @itemx -s @var{system}
- Display the graph for @var{system}---e.g., @code{i686-linux}.
- The package dependency graph is largely architecture-independent, but there
- are some architecture-dependent bits that this option allows you to visualize.
- @item --load-path=@var{directory}
- @itemx -L @var{directory}
- Add @var{directory} to the front of the package module search path
- (@pxref{Package Modules}).
- This allows users to define their own packages and make them visible to
- the command-line tools.
- @end table
- On top of that, @command{guix graph} supports all the usual package
- transformation options (@pxref{Package Transformation Options}). This
- makes it easy to view the effect of a graph-rewriting transformation
- such as @option{--with-input}. For example, the command below outputs
- the graph of @code{git} once @code{openssl} has been replaced by
- @code{libressl} everywhere in the graph:
- @example
- guix graph git --with-input=openssl=libressl
- @end example
- So many possibilities, so much fun!
- @node Invoking guix publish
- @section Invoking @command{guix publish}
- @cindex @command{guix publish}
- The purpose of @command{guix publish} is to enable users to easily share
- their store with others, who can then use it as a substitute server
- (@pxref{Substitutes}).
- When @command{guix publish} runs, it spawns an HTTP server which allows
- anyone with network access to obtain substitutes from it. This means
- that any machine running Guix can also act as if it were a build farm,
- since the HTTP interface is compatible with Cuirass, the software behind
- the @code{@value{SUBSTITUTE-SERVER-1}} build farm.
- For security, each substitute is signed, allowing recipients to check
- their authenticity and integrity (@pxref{Substitutes}). Because
- @command{guix publish} uses the signing key of the system, which is only
- readable by the system administrator, it must be started as root; the
- @option{--user} option makes it drop root privileges early on.
- The signing key pair must be generated before @command{guix publish} is
- launched, using @command{guix archive --generate-key} (@pxref{Invoking
- guix archive}).
- When the @option{--advertise} option is passed, the server advertises
- its availability on the local network using multicast DNS (mDNS) and DNS
- service discovery (DNS-SD), currently @i{via} Guile-Avahi (@pxref{Top,,,
- guile-avahi, Using Avahi in Guile Scheme Programs}).
- The general syntax is:
- @example
- guix publish @var{options}@dots{}
- @end example
- Running @command{guix publish} without any additional arguments will
- spawn an HTTP server on port 8080:
- @example
- guix publish
- @end example
- Once a publishing server has been authorized, the daemon may download
- substitutes from it. @xref{Getting Substitutes from Other Servers}.
- By default, @command{guix publish} compresses archives on the fly as it
- serves them. This ``on-the-fly'' mode is convenient in that it requires
- no setup and is immediately available. However, when serving lots of
- clients, we recommend using the @option{--cache} option, which enables
- caching of the archives before they are sent to clients---see below for
- details. The @command{guix weather} command provides a handy way to
- check what a server provides (@pxref{Invoking guix weather}).
- As a bonus, @command{guix publish} also serves as a content-addressed
- mirror for source files referenced in @code{origin} records
- (@pxref{origin Reference}). For instance, assuming @command{guix
- publish} is running on @code{example.org}, the following URL returns the
- raw @file{hello-2.10.tar.gz} file with the given SHA256 hash
- (represented in @code{nix-base32} format, @pxref{Invoking guix hash}):
- @example
- http://example.org/file/hello-2.10.tar.gz/sha256/0ssi1@dots{}ndq1i
- @end example
- Obviously, these URLs only work for files that are in the store; in
- other cases, they return 404 (``Not Found'').
- @cindex build logs, publication
- Build logs are available from @code{/log} URLs like:
- @example
- http://example.org/log/gwspk@dots{}-guile-2.2.3
- @end example
- @noindent
- When @command{guix-daemon} is configured to save compressed build logs,
- as is the case by default (@pxref{Invoking guix-daemon}), @code{/log}
- URLs return the compressed log as-is, with an appropriate
- @code{Content-Type} and/or @code{Content-Encoding} header. We recommend
- running @command{guix-daemon} with @option{--log-compression=gzip} since
- Web browsers can automatically decompress it, which is not the case with
- Bzip2 compression.
- The following options are available:
- @table @code
- @item --port=@var{port}
- @itemx -p @var{port}
- Listen for HTTP requests on @var{port}.
- @item --listen=@var{host}
- Listen on the network interface for @var{host}. The default is to
- accept connections from any interface.
- @item --user=@var{user}
- @itemx -u @var{user}
- Change privileges to @var{user} as soon as possible---i.e., once the
- server socket is open and the signing key has been read.
- @item --compression[=@var{method}[:@var{level}]]
- @itemx -C [@var{method}[:@var{level}]]
- Compress data using the given @var{method} and @var{level}. @var{method} is
- one of @code{lzip}, @code{zstd}, and @code{gzip}; when @var{method} is
- omitted, @code{gzip} is used.
- When @var{level} is zero, disable compression. The range 1 to 9 corresponds
- to different compression levels: 1 is the fastest, and 9 is the best
- (CPU-intensive). The default is 3.
- Usually, @code{lzip} compresses noticeably better than @code{gzip} for a
- small increase in CPU usage; see
- @uref{https://nongnu.org/lzip/lzip_benchmark.html,benchmarks on the lzip
- Web page}. However, @code{lzip} achieves low decompression throughput
- (on the order of 50@tie{}MiB/s on modern hardware), which can be a
- bottleneck for someone who downloads over a fast network connection.
- The compression ratio of @code{zstd} is between that of @code{lzip} and
- that of @code{gzip}; its main advantage is a
- @uref{https://facebook.github.io/zstd/,high decompression speed}.
- Unless @option{--cache} is used, compression occurs on the fly and
- the compressed streams are not
- cached. Thus, to reduce load on the machine that runs @command{guix
- publish}, it may be a good idea to choose a low compression level, to
- run @command{guix publish} behind a caching proxy, or to use
- @option{--cache}. Using @option{--cache} has the advantage that it
- allows @command{guix publish} to add @code{Content-Length} HTTP header
- to its responses.
- This option can be repeated, in which case every substitute gets compressed
- using all the selected methods, and all of them are advertised. This is
- useful when users may not support all the compression methods: they can select
- the one they support.
- @item --cache=@var{directory}
- @itemx -c @var{directory}
- Cache archives and meta-data (@code{.narinfo} URLs) to @var{directory}
- and only serve archives that are in cache.
- When this option is omitted, archives and meta-data are created
- on-the-fly. This can reduce the available bandwidth, especially when
- compression is enabled, since this may become CPU-bound. Another
- drawback of the default mode is that the length of archives is not known
- in advance, so @command{guix publish} does not add a
- @code{Content-Length} HTTP header to its responses, which in turn
- prevents clients from knowing the amount of data being downloaded.
- Conversely, when @option{--cache} is used, the first request for a store
- item (@i{via} a @code{.narinfo} URL) triggers a
- background process to @dfn{bake} the archive---computing its
- @code{.narinfo} and compressing the archive, if needed. Once the
- archive is cached in @var{directory}, subsequent requests succeed and
- are served directly from the cache, which guarantees that clients get
- the best possible bandwidth.
- That first @code{.narinfo} request nonetheless returns 200, provided the
- requested store item is ``small enough'', below the cache bypass
- threshold---see @option{--cache-bypass-threshold} below. That way,
- clients do not have to wait until the archive is baked. For larger
- store items, the first @code{.narinfo} request returns 404, meaning that
- clients have to wait until the archive is baked.
- The ``baking'' process is performed by worker threads. By default, one
- thread per CPU core is created, but this can be customized. See
- @option{--workers} below.
- When @option{--ttl} is used, cached entries are automatically deleted
- when they have expired.
- @item --workers=@var{N}
- When @option{--cache} is used, request the allocation of @var{N} worker
- threads to ``bake'' archives.
- @item --ttl=@var{ttl}
- Produce @code{Cache-Control} HTTP headers that advertise a time-to-live
- (TTL) of @var{ttl}. @var{ttl} must denote a duration: @code{5d} means 5
- days, @code{1m} means 1 month, and so on.
- This allows the user's Guix to keep substitute information in cache for
- @var{ttl}. However, note that @code{guix publish} does not itself
- guarantee that the store items it provides will indeed remain available
- for as long as @var{ttl}.
- Additionally, when @option{--cache} is used, cached entries that have
- not been accessed for @var{ttl} and that no longer have a corresponding
- item in the store, may be deleted.
- @item --negative-ttl=@var{ttl}
- Similarly produce @code{Cache-Control} HTTP headers to advertise the
- time-to-live (TTL) of @emph{negative} lookups---missing store items, for
- which the HTTP 404 code is returned. By default, no negative TTL is
- advertised.
- This parameter can help adjust server load and substitute latency by
- instructing cooperating clients to be more or less patient when a store
- item is missing.
- @item --cache-bypass-threshold=@var{size}
- When used in conjunction with @option{--cache}, store items smaller than
- @var{size} are immediately available, even when they are not yet in
- cache. @var{size} is a size in bytes, or it can be suffixed by @code{M}
- for megabytes and so on. The default is @code{10M}.
- ``Cache bypass'' allows you to reduce the publication delay for clients
- at the expense of possibly additional I/O and CPU use on the server
- side: depending on the client access patterns, those store items can end
- up being baked several times until a copy is available in cache.
- Increasing the threshold may be useful for sites that have few users, or
- to guarantee that users get substitutes even for store items that are
- not popular.
- @item --nar-path=@var{path}
- Use @var{path} as the prefix for the URLs of ``nar'' files
- (@pxref{Invoking guix archive, normalized archives}).
- By default, nars are served at a URL such as
- @code{/nar/gzip/@dots{}-coreutils-8.25}. This option allows you to
- change the @code{/nar} part to @var{path}.
- @item --public-key=@var{file}
- @itemx --private-key=@var{file}
- Use the specific @var{file}s as the public/private key pair used to sign
- the store items being published.
- The files must correspond to the same key pair (the private key is used
- for signing and the public key is merely advertised in the signature
- metadata). They must contain keys in the canonical s-expression format
- as produced by @command{guix archive --generate-key} (@pxref{Invoking
- guix archive}). By default, @file{/etc/guix/signing-key.pub} and
- @file{/etc/guix/signing-key.sec} are used.
- @item --repl[=@var{port}]
- @itemx -r [@var{port}]
- Spawn a Guile REPL server (@pxref{REPL Servers,,, guile, GNU Guile
- Reference Manual}) on @var{port} (37146 by default). This is used
- primarily for debugging a running @command{guix publish} server.
- @end table
- Enabling @command{guix publish} on Guix System is a one-liner: just
- instantiate a @code{guix-publish-service-type} service in the @code{services} field
- of the @code{operating-system} declaration (@pxref{guix-publish-service-type,
- @code{guix-publish-service-type}}).
- If you are instead running Guix on a ``foreign distro'', follow these
- instructions:
- @itemize
- @item
- If your host distro uses the systemd init system:
- @example
- # ln -s ~root/.guix-profile/lib/systemd/system/guix-publish.service \
- /etc/systemd/system/
- # systemctl start guix-publish && systemctl enable guix-publish
- @end example
- @item
- If your host distro uses the Upstart init system:
- @example
- # ln -s ~root/.guix-profile/lib/upstart/system/guix-publish.conf /etc/init/
- # start guix-publish
- @end example
- @item
- Otherwise, proceed similarly with your distro's init system.
- @end itemize
- @node Invoking guix challenge
- @section Invoking @command{guix challenge}
- @cindex reproducible builds
- @cindex verifiable builds
- @cindex @command{guix challenge}
- @cindex challenge
- Do the binaries provided by this server really correspond to the source
- code it claims to build? Is a package build process deterministic?
- These are the questions the @command{guix challenge} command attempts to
- answer.
- The former is obviously an important question: Before using a substitute
- server (@pxref{Substitutes}), one had better @emph{verify} that it
- provides the right binaries, and thus @emph{challenge} it. The latter
- is what enables the former: If package builds are deterministic, then
- independent builds of the package should yield the exact same result,
- bit for bit; if a server provides a binary different from the one
- obtained locally, it may be either corrupt or malicious.
- We know that the hash that shows up in @file{/gnu/store} file names is
- the hash of all the inputs of the process that built the file or
- directory---compilers, libraries, build scripts,
- etc. (@pxref{Introduction}). Assuming deterministic build processes,
- one store file name should map to exactly one build output.
- @command{guix challenge} checks whether there is, indeed, a single
- mapping by comparing the build outputs of several independent builds of
- any given store item.
- The command output looks like this:
- @smallexample
- $ guix challenge --substitute-urls="https://@value{SUBSTITUTE-SERVER-1} https://guix.example.org"
- updating list of substitutes from 'https://@value{SUBSTITUTE-SERVER-1}'... 100.0%
- updating list of substitutes from 'https://guix.example.org'... 100.0%
- /gnu/store/@dots{}-openssl-1.0.2d contents differ:
- local hash: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q
- https://@value{SUBSTITUTE-SERVER-1}/nar/@dots{}-openssl-1.0.2d: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q
- https://guix.example.org/nar/@dots{}-openssl-1.0.2d: 1zy4fmaaqcnjrzzajkdn3f5gmjk754b43qkq47llbyak9z0qjyim
- differing files:
- /lib/libcrypto.so.1.1
- /lib/libssl.so.1.1
- /gnu/store/@dots{}-git-2.5.0 contents differ:
- local hash: 00p3bmryhjxrhpn2gxs2fy0a15lnip05l97205pgbk5ra395hyha
- https://@value{SUBSTITUTE-SERVER-1}/nar/@dots{}-git-2.5.0: 069nb85bv4d4a6slrwjdy8v1cn4cwspm3kdbmyb81d6zckj3nq9f
- https://guix.example.org/nar/@dots{}-git-2.5.0: 0mdqa9w1p6cmli6976v4wi0sw9r4p5prkj7lzfd1877wk11c9c73
- differing file:
- /libexec/git-core/git-fsck
- /gnu/store/@dots{}-pius-2.1.1 contents differ:
- local hash: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax
- https://@value{SUBSTITUTE-SERVER-1}/nar/@dots{}-pius-2.1.1: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax
- https://guix.example.org/nar/@dots{}-pius-2.1.1: 1cy25x1a4fzq5rk0pmvc8xhwyffnqz95h2bpvqsz2mpvlbccy0gs
- differing file:
- /share/man/man1/pius.1.gz
- @dots{}
- 6,406 store items were analyzed:
- - 4,749 (74.1%) were identical
- - 525 (8.2%) differed
- - 1,132 (17.7%) were inconclusive
- @end smallexample
- @noindent
- In this example, @command{guix challenge} first scans the store to
- determine the set of locally-built derivations---as opposed to store
- items that were downloaded from a substitute server---and then queries
- all the substitute servers. It then reports those store items for which
- the servers obtained a result different from the local build.
- @cindex non-determinism, in package builds
- As an example, @code{guix.example.org} always gets a different answer.
- Conversely, @code{@value{SUBSTITUTE-SERVER-1}} agrees with local builds, except in the
- case of Git. This might indicate that the build process of Git is
- non-deterministic, meaning that its output varies as a function of
- various things that Guix does not fully control, in spite of building
- packages in isolated environments (@pxref{Features}). Most common
- sources of non-determinism include the addition of timestamps in build
- results, the inclusion of random numbers, and directory listings sorted
- by inode number. See @uref{https://reproducible-builds.org/docs/}, for
- more information.
- To find out what is wrong with this Git binary, the easiest approach is
- to run:
- @example
- guix challenge git \
- --diff=diffoscope \
- --substitute-urls="https://@value{SUBSTITUTE-SERVER-1} https://guix.example.org"
- @end example
- This automatically invokes @command{diffoscope}, which displays detailed
- information about files that differ.
- Alternatively, we can do something along these lines (@pxref{Invoking guix
- archive}):
- @example
- $ wget -q -O - https://@value{SUBSTITUTE-SERVER-1}/nar/lzip/@dots{}-git-2.5.0 \
- | lzip -d | guix archive -x /tmp/git
- $ diff -ur --no-dereference /gnu/store/@dots{}-git.2.5.0 /tmp/git
- @end example
- This command shows the difference between the files resulting from the
- local build, and the files resulting from the build on
- @code{@value{SUBSTITUTE-SERVER-1}} (@pxref{Overview, Comparing and Merging Files,,
- diffutils, Comparing and Merging Files}). The @command{diff} command
- works great for text files. When binary files differ, a better option
- is @uref{https://diffoscope.org/, Diffoscope}, a tool that helps
- visualize differences for all kinds of files.
- Once you have done that work, you can tell whether the differences are due
- to a non-deterministic build process or to a malicious server. We try
- hard to remove sources of non-determinism in packages to make it easier
- to verify substitutes, but of course, this is a process that
- involves not just Guix, but a large part of the free software community.
- In the meantime, @command{guix challenge} is one tool to help address
- the problem.
- If you are writing packages for Guix, you are encouraged to check
- whether @code{@value{SUBSTITUTE-SERVER-1}} and other substitute servers obtain the
- same build result as you did with:
- @example
- $ guix challenge @var{package}
- @end example
- @noindent
- where @var{package} is a package specification such as
- @code{guile@@2.0} or @code{glibc:debug}.
- The general syntax is:
- @example
- guix challenge @var{options} [@var{packages}@dots{}]
- @end example
- When a difference is found between the hash of a locally-built item and
- that of a server-provided substitute, or among substitutes provided by
- different servers, the command displays it as in the example above and
- its exit code is 2 (other non-zero exit codes denote other kinds of
- errors).
- The one option that matters is:
- @table @code
- @item --substitute-urls=@var{urls}
- Consider @var{urls} the whitespace-separated list of substitute source
- URLs to compare to.
- @item --diff=@var{mode}
- Upon mismatches, show differences according to @var{mode}, one of:
- @table @asis
- @item @code{simple} (the default)
- Show the list of files that differ.
- @item @code{diffoscope}
- @itemx @var{command}
- Invoke @uref{https://diffoscope.org/, Diffoscope}, passing it
- two directories whose contents do not match.
- When @var{command} is an absolute file name, run @var{command} instead
- of Diffoscope.
- @item @code{none}
- Do not show further details about the differences.
- @end table
- Thus, unless @option{--diff=none} is passed, @command{guix challenge}
- downloads the store items from the given substitute servers so that it
- can compare them.
- @item --verbose
- @itemx -v
- Show details about matches (identical contents) in addition to
- information about mismatches.
- @end table
- @node Invoking guix copy
- @section Invoking @command{guix copy}
- @cindex copy, of store items, over SSH
- @cindex SSH, copy of store items
- @cindex sharing store items across machines
- @cindex transferring store items across machines
- The @command{guix copy} command copies items from the store of one
- machine to that of another machine over a secure shell (SSH)
- connection@footnote{This command is available only when Guile-SSH was
- found. @xref{Requirements}, for details.}. For example, the following
- command copies the @code{coreutils} package, the user's profile, and all
- their dependencies over to @var{host}, logged in as @var{user}:
- @example
- guix copy --to=@var{user}@@@var{host} \
- coreutils $(readlink -f ~/.guix-profile)
- @end example
- If some of the items to be copied are already present on @var{host},
- they are not actually sent.
- The command below retrieves @code{libreoffice} and @code{gimp} from
- @var{host}, assuming they are available there:
- @example
- guix copy --from=@var{host} libreoffice gimp
- @end example
- The SSH connection is established using the Guile-SSH client, which is
- compatible with OpenSSH: it honors @file{~/.ssh/known_hosts} and
- @file{~/.ssh/config}, and uses the SSH agent for authentication.
- The key used to sign items that are sent must be accepted by the remote
- machine. Likewise, the key used by the remote machine to sign items you
- are retrieving must be in @file{/etc/guix/acl} so it is accepted by your
- own daemon. @xref{Invoking guix archive}, for more information about
- store item authentication.
- The general syntax is:
- @example
- guix copy [--to=@var{spec}|--from=@var{spec}] @var{items}@dots{}
- @end example
- You must always specify one of the following options:
- @table @code
- @item --to=@var{spec}
- @itemx --from=@var{spec}
- Specify the host to send to or receive from. @var{spec} must be an SSH
- spec such as @code{example.org}, @code{charlie@@example.org}, or
- @code{charlie@@example.org:2222}.
- @end table
- The @var{items} can be either package names, such as @code{gimp}, or
- store items, such as @file{/gnu/store/@dots{}-idutils-4.6}.
- When specifying the name of a package to send, it is first built if
- needed, unless @option{--dry-run} was specified. Common build options
- are supported (@pxref{Common Build Options}).
- @node Invoking guix container
- @section Invoking @command{guix container}
- @cindex container
- @cindex @command{guix container}
- @quotation Note
- As of version @value{VERSION}, this tool is experimental. The interface
- is subject to radical change in the future.
- @end quotation
- The purpose of @command{guix container} is to manipulate processes
- running within an isolated environment, commonly known as a
- ``container'', typically created by the @command{guix 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-URLS} -c 10
- computing 8,983 package derivations for x86_64-linux...
- looking for 9,343 store items on @value{SUBSTITUTE-URLS}...
- updating substitutes from '@value{SUBSTITUTE-URLS}'... 100.0%
- @value{SUBSTITUTE-URLS}
- 64.7% substitutes available (6,047 out of 9,343)
- @dots{}
- 2502 packages are missing from '@value{SUBSTITUTE-URLS}' for 'x86_64-linux', among which:
- 58 kcoreaddons@@5.49.0 /gnu/store/@dots{}-kcoreaddons-5.49.0
- 46 qgpgme@@1.11.1 /gnu/store/@dots{}-qgpgme-1.11.1
- 37 perl-http-cookiejar@@0.008 /gnu/store/@dots{}-perl-http-cookiejar-0.008
- @dots{}
- @end example
- What this example shows is that @code{kcoreaddons} and presumably the 58
- packages that depend on it have no substitutes at
- @code{@value{SUBSTITUTE-SERVER-1}}; likewise for @code{qgpgme} and the 46
- packages that depend on it.
- If you are a Guix developer, or if you are taking care of this build farm,
- you'll probably want to have a closer look at these packages: they may simply
- fail to build.
- @item --display-missing
- Display the list of store items for which substitutes are missing.
- @end table
- @node Invoking guix processes
- @section Invoking @command{guix processes}
- The @command{guix processes} command can be useful to developers and system
- administrators, especially on multi-user machines and on build farms: it lists
- the current sessions (connections to the daemon), as well as information about
- the processes involved@footnote{Remote sessions, when @command{guix-daemon} is
- started with @option{--listen} specifying a TCP endpoint, are @emph{not}
- listed.}. Here's an example of the information it returns:
- @example
- $ sudo guix processes
- SessionPID: 19002
- ClientPID: 19090
- ClientCommand: guix 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)
- (targets '("/boot/efi")))
- @end lisp
- @xref{Bootloader Configuration}, for more information on the available
- configuration options.
- @unnumberedsubsec Globally-Visible Packages
- @vindex %base-packages
- The @code{packages} field lists packages that will be globally visible
- on the system, for all user accounts---i.e., in every user's @env{PATH}
- environment variable---in addition to the per-user profiles
- (@pxref{Invoking guix package}). The @code{%base-packages} variable
- provides all the tools one would expect for basic user and administrator
- tasks---including the GNU Core Utilities, the GNU Networking Utilities,
- the @command{mg} lightweight text editor, @command{find}, @command{grep},
- etc. The example above adds GNU@tie{}Screen to those,
- taken from the @code{(gnu packages screen)}
- module (@pxref{Package Modules}). The
- @code{(list package output)} syntax can be used to add a specific output
- of a package:
- @lisp
- (use-modules (gnu packages))
- (use-modules (gnu packages dns))
- (operating-system
- ;; ...
- (packages (cons (list isc-bind "utils")
- %base-packages)))
- @end lisp
- @findex specification->package
- Referring to packages by variable name, like @code{isc-bind} above, has
- the advantage of being unambiguous; it also allows typos and such to be
- diagnosed right away as ``unbound variables''. The downside is that one
- needs to know which module defines which package, and to augment the
- @code{use-package-modules} line accordingly. To avoid that, one can use
- the @code{specification->package} procedure of the @code{(gnu packages)}
- module, which returns the best package for a given name or name and
- version:
- @lisp
- (use-modules (gnu packages))
- (operating-system
- ;; ...
- (packages (append (map specification->package
- '("tcpdump" "htop" "gnupg@@2.0"))
- %base-packages)))
- @end lisp
- @unnumberedsubsec System Services
- @cindex services
- @vindex %base-services
- The @code{services} field lists @dfn{system services} to be made
- available when the system starts (@pxref{Services}).
- The @code{operating-system} declaration above specifies that, in
- addition to the basic services, we want the OpenSSH secure shell
- daemon listening on port 2222 (@pxref{Networking Services,
- @code{openssh-service-type}}). Under the hood,
- @code{openssh-service-type} arranges so that @command{sshd} is started with the
- right command-line options, possibly with supporting configuration files
- generated as needed (@pxref{Defining Services}).
- @cindex customization, of services
- @findex modify-services
- Occasionally, instead of using the base services as is, you will want to
- customize them. To do this, use @code{modify-services} (@pxref{Service
- Reference, @code{modify-services}}) to modify the list.
- @anchor{auto-login to TTY} For example, suppose you want to modify
- @code{guix-daemon} and Mingetty (the console log-in) in the
- @code{%base-services} list (@pxref{Base Services,
- @code{%base-services}}). To do that, you can write the following in
- your operating system declaration:
- @lisp
- (define %my-services
- ;; My very own list of services.
- (modify-services %base-services
- (guix-service-type config =>
- (guix-configuration
- (inherit config)
- ;; Fetch substitutes from example.org.
- (substitute-urls
- (list "https://example.org/guix"
- "https://ci.guix.gnu.org"))))
- (mingetty-service-type config =>
- (mingetty-configuration
- (inherit config)
- ;; 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
- (@pxref{Auto-Login to a Specific TTY, see the cookbook for how to
- auto-login one user to a specific TTY,, guix-cookbook, GNU Guix Cookbook})).
- Observe how this is accomplished: first, we arrange for the original
- configuration to be bound to the identifier @code{config} in the
- @var{body}, and then we write the @var{body} so that it evaluates to the
- desired configuration. In particular, notice how we use @code{inherit}
- to create a new configuration which has the same values as the old
- configuration, but with a few modifications.
- @cindex encrypted disk
- The configuration for a typical ``desktop'' usage, with an encrypted
- root partition, the X11 display
- server, GNOME and Xfce (users can choose which of these desktop
- environments to use at the log-in screen by pressing @kbd{F1}), network
- management, power management, and more, would look like this:
- @lisp
- @include os-config-desktop.texi
- @end lisp
- A graphical system with a choice of lightweight window managers
- instead of full-blown desktop environments would look like this:
- @lisp
- @include os-config-lightweight-desktop.texi
- @end lisp
- This example refers to the @file{/boot/efi} file system by its UUID,
- @code{1234-ABCD}. Replace this UUID with the right UUID on your system,
- as returned by the @command{blkid} command.
- @xref{Desktop Services}, for the exact list of services provided by
- @code{%desktop-services}. @xref{X.509 Certificates}, for background
- information about the @code{nss-certs} package that is used here.
- Again, @code{%desktop-services} is just a list of service objects. If
- you want to remove services from there, you can do so using the
- procedures for list filtering (@pxref{SRFI-1 Filtering and
- Partitioning,,, guile, GNU Guile Reference Manual}). For instance, the
- following expression returns a list that contains all the services in
- @code{%desktop-services} minus the Avahi service:
- @lisp
- (remove (lambda (service)
- (eq? (service-kind service) avahi-service-type))
- %desktop-services)
- @end lisp
- Alternatively, the @code{modify-services} macro can be used:
- @lisp
- (modify-services %desktop-services
- (delete avahi-service-type))
- @end lisp
- @unnumberedsubsec Instantiating the System
- Assuming the @code{operating-system} declaration
- is stored in the @file{my-system-config.scm}
- file, the @command{guix system reconfigure my-system-config.scm} command
- instantiates that configuration, and makes it the default GRUB boot
- entry (@pxref{Invoking guix system}).
- The normal way to change the system configuration is by updating this
- file and re-running @command{guix system reconfigure}. One should never
- have to touch files in @file{/etc} or to run commands that modify the
- system state such as @command{useradd} or @command{grub-install}. In
- fact, you must avoid that since that would not only void your warranty
- but also prevent you from rolling back to previous versions of your
- system, should you ever need to.
- @cindex roll-back, of the operating system
- Speaking of roll-back, each time you run @command{guix system
- reconfigure}, a new @dfn{generation} of the system is created---without
- modifying or deleting previous generations. Old system generations get
- an entry in the bootloader boot menu, allowing you to boot them in case
- something went wrong with the latest generation. Reassuring, no? The
- @command{guix system list-generations} command lists the system
- generations available on disk. It is also possible to roll back the
- system via the commands @command{guix system roll-back} and
- @command{guix system switch-generation}.
- Although the @command{guix system reconfigure} command will not modify
- previous generations, you must take care when the current generation is not
- the latest (e.g., after invoking @command{guix system roll-back}), since
- the operation might overwrite a later generation (@pxref{Invoking guix
- system}).
- @unnumberedsubsec The Programming Interface
- At the Scheme level, the bulk of an @code{operating-system} declaration
- is instantiated with the following monadic procedure (@pxref{The Store
- Monad}):
- @deffn {Monadic Procedure} operating-system-derivation os
- Return a derivation that builds @var{os}, an @code{operating-system}
- object (@pxref{Derivations}).
- The output of the derivation is a single directory that refers to all
- the packages, configuration files, and other supporting files needed to
- instantiate @var{os}.
- @end deffn
- This procedure is provided by the @code{(gnu system)} module. Along
- with @code{(gnu services)} (@pxref{Services}), this module contains the
- guts of Guix System. Make sure to visit it!
- @node operating-system Reference
- @section @code{operating-system} Reference
- This section summarizes all the options available in
- @code{operating-system} declarations (@pxref{Using the Configuration
- System}).
- @deftp {Data Type} operating-system
- This is the data type representing an operating system configuration.
- By that, we mean all the global system configuration, not per-user
- configuration (@pxref{Using the Configuration System}).
- @table @asis
- @item @code{kernel} (default: @code{linux-libre})
- The package object of the operating system kernel to
- use@footnote{Currently only the Linux-libre kernel is fully supported.
- Using GNU@tie{}mach with the GNU@tie{}Hurd is experimental and only
- available when building a virtual machine disk image.}.
- @cindex hurd
- @item @code{hurd} (default: @code{#f})
- The package object of the Hurd to be started by the kernel. When this
- field is set, produce a GNU/Hurd operating system. In that case,
- @code{kernel} must also be set to the @code{gnumach} package---the
- microkernel the Hurd runs on.
- @quotation Warning
- This feature is experimental and only supported for disk images.
- @end quotation
- @item @code{kernel-loadable-modules} (default: '())
- A list of objects (usually packages) to collect loadable kernel modules
- from--e.g. @code{(list ddcci-driver-linux)}.
- @item @code{kernel-arguments} (default: @code{%default-kernel-arguments})
- List of strings or gexps representing additional arguments to pass on
- the command-line of the kernel---e.g., @code{("console=ttyS0")}.
- @item @code{bootloader}
- The system bootloader configuration object. @xref{Bootloader Configuration}.
- @item @code{label}
- This is the label (a string) as it appears in the bootloader's menu entry.
- The default label includes the kernel name and version.
- @item @code{keyboard-layout} (default: @code{#f})
- This field specifies the keyboard layout to use in the console. It can be
- either @code{#f}, in which case the default keyboard layout is used (usually
- US English), or a @code{<keyboard-layout>} record. @xref{Keyboard Layout},
- for more information.
- This keyboard layout is in effect as soon as the kernel has booted. For
- instance, it is the keyboard layout in effect when you type a passphrase if
- your root file system is on a @code{luks-device-mapping} mapped device
- (@pxref{Mapped Devices}).
- @quotation Note
- This does @emph{not} specify the keyboard layout used by the bootloader, nor
- that used by the graphical display server. @xref{Bootloader Configuration},
- for information on how to specify the bootloader's keyboard layout. @xref{X
- Window}, for information on how to specify the keyboard layout used by the X
- Window System.
- @end quotation
- @item @code{initrd-modules} (default: @code{%base-initrd-modules})
- @cindex initrd
- @cindex initial RAM disk
- The list of Linux kernel modules that need to be available in the
- initial RAM disk. @xref{Initial RAM Disk}.
- @item @code{initrd} (default: @code{base-initrd})
- A procedure that returns an initial RAM disk for the Linux
- kernel. This field is provided to support low-level customization and
- should rarely be needed for casual use. @xref{Initial RAM Disk}.
- @item @code{firmware} (default: @code{%base-firmware})
- @cindex firmware
- List of firmware packages loadable by the operating system kernel.
- The default includes firmware needed for Atheros- and Broadcom-based
- WiFi devices (Linux-libre modules @code{ath9k} and @code{b43-open},
- respectively). @xref{Hardware Considerations}, for more info on
- supported hardware.
- @item @code{host-name}
- The host name.
- @item @code{hosts-file}
- @cindex hosts file
- A file-like object (@pxref{G-Expressions, file-like objects}) for use as
- @file{/etc/hosts} (@pxref{Host Names,,, libc, The GNU C Library
- Reference Manual}). The default is a file with entries for
- @code{localhost} and @var{host-name}.
- @item @code{mapped-devices} (default: @code{'()})
- A list of mapped devices. @xref{Mapped Devices}.
- @item @code{file-systems}
- A list of file systems. @xref{File Systems}.
- @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 @code{<setuid-program>}. @xref{Setuid Programs}, for more
- information.
- @item @code{sudoers-file} (default: @code{%sudoers-specification})
- @cindex sudoers file
- The contents of the @file{/etc/sudoers} file as a file-like object
- (@pxref{G-Expressions, @code{local-file} and @code{plain-file}}).
- This file specifies which users can use the @command{sudo} command, what
- they are allowed to do, and what privileges they may gain. The default
- is that only @code{root} and members of the @code{wheel} group may use
- @code{sudo}.
- @end table
- @deffn {Scheme Syntax} this-operating-system
- When used in the @emph{lexical scope} of an operating system field definition,
- this identifier resolves to the operating system being defined.
- The example below shows how to refer to the operating system being defined in
- the definition of the @code{label} field:
- @lisp
- (use-modules (gnu) (guix))
- (operating-system
- ;; ...
- (label (package-full-name
- (operating-system-kernel this-operating-system))))
- @end lisp
- It is an error to refer to @code{this-operating-system} outside an operating
- system definition.
- @end deffn
- @end deftp
- @node File Systems
- @section File Systems
- The list of file systems to be mounted is specified in the
- @code{file-systems} field of the operating system declaration
- (@pxref{Using the Configuration System}). Each file system is declared
- using the @code{file-system} form, like this:
- @lisp
- (file-system
- (mount-point "/home")
- (device "/dev/sda3")
- (type "ext4"))
- @end lisp
- As usual, some of the fields are mandatory---those shown in the example
- above---while others can be omitted. These are described below.
- @deftp {Data Type} file-system
- Objects of this type represent file systems to be mounted. They
- contain the following members:
- @table @asis
- @item @code{type}
- This is a string specifying the type of the file system---e.g.,
- @code{"ext4"}.
- @item @code{mount-point}
- This designates the place where the file system is to be mounted.
- @item @code{device}
- This names the ``source'' of the file system. It can be one of three
- things: a file system label, a file system UUID, or the name of a
- @file{/dev} node. Labels and UUIDs offer a way to refer to file
- systems without having to hard-code their actual device
- name@footnote{Note that, while it is tempting to use
- @file{/dev/disk/by-uuid} and similar device names to achieve the same
- result, this is not recommended: These special device nodes are created
- by the udev daemon and may be unavailable at the time the device is
- mounted.}.
- @findex file-system-label
- File system labels are created using the @code{file-system-label}
- procedure, UUIDs are created using @code{uuid}, and @file{/dev} node are
- plain strings. Here's an example of a file system referred to by its
- label, as shown by the @command{e2label} command:
- @lisp
- (file-system
- (mount-point "/home")
- (type "ext4")
- (device (file-system-label "my-home")))
- @end lisp
- @findex uuid
- UUIDs are converted from their string representation (as shown by the
- @command{tune2fs -l} command) using the @code{uuid} form@footnote{The
- @code{uuid} form expects 16-byte UUIDs as defined in
- @uref{https://tools.ietf.org/html/rfc4122, RFC@tie{}4122}. This is the
- form of UUID used by the ext2 family of file systems and others, but it
- is different from ``UUIDs'' found in FAT file systems, for instance.},
- like this:
- @lisp
- (file-system
- (mount-point "/home")
- (type "ext4")
- (device (uuid "4dab5feb-d176-45de-b287-9b0a6e4c01cb")))
- @end lisp
- When the source of a file system is a mapped device (@pxref{Mapped
- Devices}), its @code{device} field @emph{must} refer to the mapped
- device name---e.g., @file{"/dev/mapper/root-partition"}.
- This is required so that
- the system knows that mounting the file system depends on having the
- corresponding device mapping established.
- @item @code{flags} (default: @code{'()})
- This is a list of symbols denoting mount flags. Recognized flags
- include @code{read-only}, @code{bind-mount}, @code{no-dev} (disallow
- access to special files), @code{no-suid} (ignore setuid and setgid
- bits), @code{no-atime} (do not update file access times),
- @code{strict-atime} (update file access time), @code{lazy-time} (only
- update time on the in-memory version of the file inode), and
- @code{no-exec} (disallow program execution).
- @xref{Mount-Unmount-Remount,,, libc, The GNU C Library Reference
- Manual}, for more information on these flags.
- @item @code{options} (default: @code{#f})
- This is either @code{#f}, or a string denoting mount options passed to
- the file system driver. @xref{Mount-Unmount-Remount,,, libc, The GNU C
- Library Reference Manual}, for details and run @command{man 8 mount} for
- options for various file systems. Note that the
- @code{file-system-options->alist} and @code{alist->file-system-options}
- procedures from @code{(gnu system file-systems)} can be used to convert
- file system options given as an association list to the string
- representation, and vice-versa.
- @item @code{mount?} (default: @code{#t})
- This value indicates whether to automatically mount the file system when
- the system is brought up. When set to @code{#f}, the file system gets
- an entry in @file{/etc/fstab} (read by the @command{mount} command) but
- is not automatically mounted.
- @item @code{needed-for-boot?} (default: @code{#f})
- This Boolean value indicates whether the file system is needed when
- booting. If that is true, then the file system is mounted when the
- initial RAM disk (initrd) is loaded. This is always the case, for
- instance, for the root file system.
- @item @code{check?} (default: @code{#t})
- This Boolean indicates whether the file system 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)
- (targets '("/boot/efi"))
- (keyboard-layout keyboard-layout))) ;for GRUB
- (services (cons (set-xorg-configuration
- (xorg-configuration ;for Xorg
- (keyboard-layout keyboard-layout)))
- %desktop-services)))
- @end lisp
- In the example above, for GRUB and for Xorg, we just refer to the
- @code{keyboard-layout} field defined above, but we could just as well refer to
- a different layout. The @code{set-xorg-configuration} procedure communicates
- the desired Xorg configuration to the graphical log-in manager, by default
- GDM.
- We've discussed how to specify the @emph{default} keyboard layout of your
- system when it starts, but you can also adjust it at run time:
- @itemize
- @item
- If you're using GNOME, its settings panel has a ``Region & Language'' entry
- where you can select one or more keyboard layouts.
- @item
- Under Xorg, the @command{setxkbmap} command (from the same-named package)
- allows you to change the current layout. For example, this is how you would
- change the layout to US Dvorak:
- @example
- setxkbmap us dvorak
- @end example
- @item
- The @code{loadkeys} command changes the keyboard layout in effect in the Linux
- console. However, note that @code{loadkeys} does @emph{not} use the XKB
- keyboard layout categorization described above. The command below loads the
- French bépo layout:
- @example
- loadkeys fr-bepo
- @end example
- @end itemize
- @node Locales
- @section Locales
- @cindex locale
- A @dfn{locale} defines cultural conventions for a particular language
- and region of the world (@pxref{Locales,,, libc, The GNU C Library
- Reference Manual}). Each locale has a name that typically has the form
- @code{@var{language}_@var{territory}.@var{codeset}}---e.g.,
- @code{fr_LU.utf8} designates the locale for the French language, with
- cultural conventions from Luxembourg, and using the UTF-8 encoding.
- @cindex locale definition
- Usually, you will want to specify the default locale for the machine
- using the @code{locale} field of the @code{operating-system} declaration
- (@pxref{operating-system Reference, @code{locale}}).
- The selected locale is automatically added to the @dfn{locale
- definitions} known to the system if needed, with its codeset inferred
- from its name---e.g., @code{bo_CN.utf8} will be assumed to use the
- @code{UTF-8} codeset. Additional locale definitions can be specified in
- the @code{locale-definitions} slot of @code{operating-system}---this is
- useful, for instance, if the codeset could not be inferred from the
- locale name. The default set of locale definitions includes some widely
- used locales, but not all the available locales, in order to save space.
- For instance, to add the North Frisian locale for Germany, the value of
- that field may be:
- @lisp
- (cons (locale-definition
- (name "fy_DE.utf8") (source "fy_DE"))
- %default-locale-definitions)
- @end lisp
- Likewise, to save space, one might want @code{locale-definitions} to
- list only the locales that are actually used, as in:
- @lisp
- (list (locale-definition
- (name "ja_JP.eucjp") (source "ja_JP")
- (charset "EUC-JP")))
- @end lisp
- @vindex LOCPATH
- The compiled locale definitions are available at
- @file{/run/current-system/locale/X.Y}, where @code{X.Y} is the libc
- version, which is the default location where the GNU@tie{}libc provided
- by Guix looks for locale data. This can be overridden using the
- @env{LOCPATH} environment variable (@pxref{locales-and-locpath,
- @env{LOCPATH} and locale packages}).
- The @code{locale-definition} form is provided by the @code{(gnu system
- locale)} module. Details are given below.
- @deftp {Data Type} locale-definition
- This is the data type of a locale definition.
- @table @asis
- @item @code{name}
- The name of the locale. @xref{Locale Names,,, libc, The GNU C Library
- Reference Manual}, for more information on locale names.
- @item @code{source}
- The name of the source for that locale. This is typically the
- @code{@var{language}_@var{territory}} part of the locale name.
- @item @code{charset} (default: @code{"UTF-8"})
- The ``character set'' or ``code set'' for that locale,
- @uref{https://www.iana.org/assignments/character-sets, as defined by
- IANA}.
- @end table
- @end deftp
- @defvr {Scheme Variable} %default-locale-definitions
- A list of commonly used UTF-8 locales, used as the default
- value of the @code{locale-definitions} field of @code{operating-system}
- declarations.
- @cindex locale name
- @cindex normalized codeset in locale names
- These locale definitions use the @dfn{normalized codeset} for the part
- that follows the dot in the name (@pxref{Using gettextized software,
- normalized codeset,, libc, The GNU C Library Reference Manual}). So for
- instance it has @code{uk_UA.utf8} but @emph{not}, say,
- @code{uk_UA.UTF-8}.
- @end defvr
- @subsection Locale Data Compatibility Considerations
- @cindex incompatibility, of locale data
- @code{operating-system} declarations provide a @code{locale-libcs} field
- to specify the GNU@tie{}libc packages that are used to compile locale
- declarations (@pxref{operating-system Reference}). ``Why would I
- care?'', you may ask. Well, it turns out that the binary format of
- locale data is occasionally incompatible from one libc version to
- another.
- @c See <https://sourceware.org/ml/libc-alpha/2015-09/msg00575.html>
- @c and <https://lists.gnu.org/archive/html/guix-devel/2015-08/msg00737.html>.
- For instance, a program linked against libc version 2.21 is unable to
- read locale data produced with libc 2.22; worse, that program
- @emph{aborts} instead of simply ignoring the incompatible locale
- data@footnote{Versions 2.23 and later of GNU@tie{}libc will simply skip
- the incompatible locale data, which is already an improvement.}.
- Similarly, a program linked against libc 2.22 can read most, but not
- all, of the locale data from libc 2.21 (specifically, @env{LC_COLLATE}
- data is incompatible); thus calls to @code{setlocale} may fail, but
- programs will not abort.
- The ``problem'' with Guix is that users have a lot of freedom: They can
- choose whether and when to upgrade software in their profiles, and might
- be using a libc version different from the one the system administrator
- used to build the system-wide locale data.
- Fortunately, unprivileged users can also install their own locale data
- and define @env{GUIX_LOCPATH} accordingly (@pxref{locales-and-locpath,
- @env{GUIX_LOCPATH} and locale packages}).
- Still, it is best if the system-wide locale data at
- @file{/run/current-system/locale} is built for all the libc versions
- actually in use on the system, so that all the programs can access
- it---this is especially crucial on a multi-user system. To do that, the
- administrator can specify several libc packages in the
- @code{locale-libcs} field of @code{operating-system}:
- @lisp
- (use-package-modules base)
- (operating-system
- ;; @dots{}
- (locale-libcs (list glibc-2.21 (canonical-package glibc))))
- @end lisp
- This example would lead to a system containing locale definitions for
- both libc 2.21 and the current version of libc in
- @file{/run/current-system/locale}.
- @node Services
- @section Services
- @cindex system services
- An important part of preparing an @code{operating-system} declaration is
- listing @dfn{system services} and their configuration (@pxref{Using the
- Configuration System}). System services are typically daemons launched
- when the system boots, or other actions needed at that time---e.g.,
- configuring network access.
- Guix has a broad definition of ``service'' (@pxref{Service
- Composition}), but many services are managed by the GNU@tie{}Shepherd
- (@pxref{Shepherd Services}). On a running system, the @command{herd}
- command allows you to list the available services, show their status,
- start and stop them, or do other specific operations (@pxref{Jump
- Start,,, shepherd, The GNU Shepherd Manual}). For example:
- @example
- # herd status
- @end example
- The above command, run as @code{root}, lists the currently defined
- services. The @command{herd doc} command shows a synopsis of the given
- service and its associated actions:
- @example
- # herd doc nscd
- Run libc's name service cache daemon (nscd).
- # herd doc nscd action invalidate
- invalidate: Invalidate the given cache--e.g., 'hosts' for host name lookups.
- @end example
- The @command{start}, @command{stop}, and @command{restart} sub-commands
- have the effect you would expect. For instance, the commands below stop
- the nscd service and restart the Xorg display server:
- @example
- # herd stop nscd
- Service nscd has been stopped.
- # herd restart xorg-server
- Service xorg-server has been stopped.
- Service xorg-server has been started.
- @end example
- The following sections document the available services, starting with
- the core services, that may be used in an @code{operating-system}
- declaration.
- @menu
- * Base Services:: Essential system services.
- * Scheduled Job Execution:: The mcron service.
- * Log Rotation:: The rottlog service.
- * Networking 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:: Cuirass and Laminar services.
- * Power Management Services:: Extending battery life.
- * Audio Services:: The MPD.
- * Virtualization Services:: Virtualization services.
- * Version Control Services:: Providing remote access to Git repositories.
- * Game Services:: Game servers.
- * PAM Mount Service:: Service to mount volumes when logging in.
- * Guix Services:: Services relating specifically to Guix.
- * Linux Services:: Services tied to the Linux kernel.
- * Hurd Services:: Services specific for a Hurd System.
- * Miscellaneous Services:: Other services.
- @end menu
- @node Base Services
- @subsection Base Services
- The @code{(gnu services base)} module provides definitions for the basic
- services that one expects from the system. The services exported by
- this module are listed below.
- @defvr {Scheme Variable} %base-services
- This variable contains a list of basic services (@pxref{Service Types
- and Services}, for more information on service objects) one would
- expect from the system: a login service (mingetty) on each tty, syslogd,
- the libc name service cache daemon (nscd), the udev device manager, and
- more.
- This is the default value of the @code{services} field of
- @code{operating-system} declarations. Usually, when customizing a
- system, you will want to append services to @code{%base-services}, like
- this:
- @lisp
- (append (list (service avahi-service-type)
- (service openssh-service-type))
- %base-services)
- @end lisp
- @end defvr
- @defvr {Scheme Variable} special-files-service-type
- This is the service that sets up ``special files'' such as
- @file{/bin/sh}; an instance of it is part of @code{%base-services}.
- The value associated with @code{special-files-service-type} services
- must be a list of tuples where the first element is the ``special file''
- and the second element is its target. By default it is:
- @cindex @file{/bin/sh}
- @cindex @file{sh}, in @file{/bin}
- @lisp
- `(("/bin/sh" ,(file-append bash "/bin/sh")))
- @end lisp
- @cindex @file{/usr/bin/env}
- @cindex @file{env}, in @file{/usr/bin}
- If you want to add, say, @code{/usr/bin/env} to your system, you can
- change it to:
- @lisp
- `(("/bin/sh" ,(file-append bash "/bin/sh"))
- ("/usr/bin/env" ,(file-append coreutils "/bin/env")))
- @end lisp
- Since this is part of @code{%base-services}, you can use
- @code{modify-services} to customize the set of special files
- (@pxref{Service Reference, @code{modify-services}}). But the simple way
- to add a special file is @i{via} the @code{extra-special-file} procedure
- (see below).
- @end defvr
- @deffn {Scheme Procedure} extra-special-file @var{file} @var{target}
- Use @var{target} as the ``special file'' @var{file}.
- For example, adding the following lines to the @code{services} field of
- your operating system declaration leads to a @file{/usr/bin/env}
- symlink:
- @lisp
- (extra-special-file "/usr/bin/env"
- (file-append coreutils "/bin/env"))
- @end lisp
- @end deffn
- @deffn {Scheme Procedure} host-name-service @var{name}
- Return a service that sets the host name to @var{name}.
- @end deffn
- @defvr {Scheme Variable} console-font-service-type
- Install the given fonts on the specified ttys (fonts are per
- virtual console on the kernel Linux). The value of this service is a list of
- tty/font pairs. The font can be the name of a font provided by the @code{kbd}
- package or any valid argument to @command{setfont}, as in this example:
- @lisp
- `(("tty1" . "LatGrkCyr-8x16")
- ("tty2" . ,(file-append
- font-tamzen
- "/share/kbd/consolefonts/TamzenForPowerline10x20.psf"))
- ("tty3" . ,(file-append
- font-terminus
- "/share/consolefonts/ter-132n"))) ; for HDPI
- @end lisp
- @end defvr
- @deffn {Scheme Procedure} login-service @var{config}
- Return a service to run login according to @var{config}, a
- @code{<login-configuration>} object, which specifies the message of the day,
- among other things.
- @end deffn
- @deftp {Data Type} login-configuration
- This is the data type representing the configuration of login.
- @table @asis
- @item @code{motd}
- @cindex message of the day
- A file-like object containing the ``message of the day''.
- @item @code{allow-empty-passwords?} (default: @code{#t})
- Allow empty passwords by default so that first-time users can log in when
- the 'root' account has just been created.
- @end table
- @end deftp
- @deffn {Scheme Procedure} mingetty-service @var{config}
- Return a service to run mingetty according to @var{config}, a
- @code{<mingetty-configuration>} object, which specifies the tty to run, among
- other things.
- @end deffn
- @deftp {Data Type} mingetty-configuration
- This is the data type representing the configuration of Mingetty, which
- provides the default implementation of virtual console log-in.
- @table @asis
- @item @code{tty}
- The name of the console this Mingetty runs on---e.g., @code{"tty1"}.
- @item @code{auto-login} (default: @code{#f})
- When true, this field must be a string denoting the user name under
- which the system automatically logs in. When it is @code{#f}, a
- user name and password must be entered to log in.
- @item @code{login-program} (default: @code{#f})
- This must be either @code{#f}, in which case the default log-in program
- is used (@command{login} from the Shadow tool suite), or a gexp denoting
- the name of the log-in program.
- @item @code{login-pause?} (default: @code{#f})
- When set to @code{#t} in conjunction with @var{auto-login}, the user
- will have to press a key before the log-in shell is launched.
- @item @code{clear-on-logout?} (default: @code{#t})
- When set to @code{#t}, the screen will be cleared after logout.
- @item @code{mingetty} (default: @var{mingetty})
- The Mingetty package to use.
- @end table
- @end deftp
- @deffn {Scheme Procedure} agetty-service @var{config}
- Return a service to run agetty according to @var{config}, an
- @code{<agetty-configuration>} object, which specifies the tty to run,
- among other things.
- @end deffn
- @deftp {Data Type} agetty-configuration
- This is the data type representing the configuration of agetty, which
- implements virtual and serial console log-in. See the @code{agetty(8)}
- man page for more information.
- @table @asis
- @item @code{tty}
- The name of the console this agetty runs on, as a string---e.g.,
- @code{"ttyS0"}. This argument is optional, it will default to
- a reasonable default serial port used by the kernel Linux.
- For this, if there is a value for an option @code{agetty.tty} in the kernel
- command line, agetty will extract the device name of the serial port
- from it and use that.
- If not and if there is a value for an option @code{console} with a tty in
- the Linux command line, agetty will extract the device name of the
- serial port from it and use that.
- In both cases, agetty will leave the other serial device settings
- (baud rate etc.)@: alone---in the hope that Linux pinned them to the
- correct values.
- @item @code{baud-rate} (default: @code{#f})
- A string containing a comma-separated list of one or more baud rates, in
- descending order.
- @item @code{term} (default: @code{#f})
- A string containing the value used for the @env{TERM} environment
- variable.
- @item @code{eight-bits?} (default: @code{#f})
- When @code{#t}, the tty is assumed to be 8-bit clean, and parity detection is
- disabled.
- @item @code{auto-login} (default: @code{#f})
- When passed a login name, as a string, the specified user will be logged
- in automatically without prompting for their login name or password.
- @item @code{no-reset?} (default: @code{#f})
- When @code{#t}, don't reset terminal cflags (control modes).
- @item @code{host} (default: @code{#f})
- This accepts a string containing the ``login_host'', which will be written
- into the @file{/var/run/utmpx} file.
- @item @code{remote?} (default: @code{#f})
- When set to @code{#t} in conjunction with @var{host}, this will add an
- @code{-r} fakehost option to the command line of the login program
- specified in @var{login-program}.
- @item @code{flow-control?} (default: @code{#f})
- When set to @code{#t}, enable hardware (RTS/CTS) flow control.
- @item @code{no-issue?} (default: @code{#f})
- When set to @code{#t}, the contents of the @file{/etc/issue} file will
- not be displayed before presenting the login prompt.
- @item @code{init-string} (default: @code{#f})
- This accepts a string that will be sent to the tty or modem before
- sending anything else. It can be used to initialize a modem.
- @item @code{no-clear?} (default: @code{#f})
- When set to @code{#t}, agetty will not clear the screen before showing
- the login prompt.
- @item @code{login-program} (default: (file-append shadow "/bin/login"))
- This must be either a gexp denoting the name of a log-in program, or
- unset, in which case the default value is the @command{login} from the
- Shadow tool suite.
- @item @code{local-line} (default: @code{#f})
- Control the CLOCAL line flag. This accepts one of three symbols as
- arguments, @code{'auto}, @code{'always}, or @code{'never}. If @code{#f},
- the default value chosen by agetty is @code{'auto}.
- @item @code{extract-baud?} (default: @code{#f})
- When set to @code{#t}, instruct agetty to try to extract the baud rate
- from the status messages produced by certain types of modems.
- @item @code{skip-login?} (default: @code{#f})
- When set to @code{#t}, do not prompt the user for a login name. This
- can be used with @var{login-program} field to use non-standard login
- systems.
- @item @code{no-newline?} (default: @code{#f})
- When set to @code{#t}, do not print a newline before printing the
- @file{/etc/issue} file.
- @c Is this dangerous only when used with login-program, or always?
- @item @code{login-options} (default: @code{#f})
- This option accepts a string containing options that are passed to the
- login program. When used with the @var{login-program}, be aware that a
- malicious user could try to enter a login name containing embedded
- options that could be parsed by the login program.
- @item @code{login-pause} (default: @code{#f})
- When set to @code{#t}, wait for any key before showing the login prompt.
- This can be used in conjunction with @var{auto-login} to save memory by
- lazily spawning shells.
- @item @code{chroot} (default: @code{#f})
- Change root to the specified directory. This option accepts a directory
- path as a string.
- @item @code{hangup?} (default: @code{#f})
- Use the Linux system call @code{vhangup} to do a virtual hangup of the
- specified terminal.
- @item @code{keep-baud?} (default: @code{#f})
- When set to @code{#t}, try to keep the existing baud rate. The baud
- rates from @var{baud-rate} are used when agetty receives a @key{BREAK}
- character.
- @item @code{timeout} (default: @code{#f})
- When set to an integer value, terminate if no user name could be read
- within @var{timeout} seconds.
- @item @code{detect-case?} (default: @code{#f})
- When set to @code{#t}, turn on support for detecting an uppercase-only
- terminal. This setting will detect a login name containing only
- uppercase letters as indicating an uppercase-only terminal and turn on
- some upper-to-lower case conversions. Note that this will not support
- Unicode characters.
- @item @code{wait-cr?} (default: @code{#f})
- When set to @code{#t}, wait for the user or modem to send a
- carriage-return or linefeed character before displaying
- @file{/etc/issue} or login prompt. This is typically used with the
- @var{init-string} option.
- @item @code{no-hints?} (default: @code{#f})
- When set to @code{#t}, do not print hints about Num, Caps, and Scroll
- locks.
- @item @code{no-hostname?} (default: @code{#f})
- By default, the hostname is printed. When this option is set to
- @code{#t}, no hostname will be shown at all.
- @item @code{long-hostname?} (default: @code{#f})
- By default, the hostname is only printed until the first dot. When this
- option is set to @code{#t}, the fully qualified hostname by
- @code{gethostname} or @code{getaddrinfo} is shown.
- @item @code{erase-characters} (default: @code{#f})
- This option accepts a string of additional characters that should be
- interpreted as backspace when the user types their login name.
- @item @code{kill-characters} (default: @code{#f})
- This option accepts a string that should be interpreted to mean ``ignore
- all previous characters'' (also called a ``kill'' character) when the user
- types their login name.
- @item @code{chdir} (default: @code{#f})
- This option accepts, as a string, a directory path that will be changed
- to before login.
- @item @code{delay} (default: @code{#f})
- This options accepts, as an integer, the number of seconds to sleep
- before opening the tty and displaying the login prompt.
- @item @code{nice} (default: @code{#f})
- This option accepts, as an integer, the nice value with which to run the
- @command{login} program.
- @item @code{extra-options} (default: @code{'()})
- This option provides an ``escape hatch'' for the user to provide arbitrary
- command-line arguments to @command{agetty} as a list of strings.
- @end table
- @end deftp
- @deffn {Scheme Procedure} kmscon-service-type @var{config}
- Return a service to run @uref{https://www.freedesktop.org/wiki/Software/kmscon,kmscon}
- according to @var{config}, a @code{<kmscon-configuration>} object, which
- specifies the tty to run, among other things.
- @end deffn
- @deftp {Data Type} kmscon-configuration
- This is the data type representing the configuration of Kmscon, which
- implements virtual console log-in.
- @table @asis
- @item @code{virtual-terminal}
- The name of the console this Kmscon runs on---e.g., @code{"tty1"}.
- @item @code{login-program} (default: @code{#~(string-append #$shadow "/bin/login")})
- A gexp denoting the name of the log-in program. The default log-in program is
- @command{login} from the Shadow tool suite.
- @item @code{login-arguments} (default: @code{'("-p")})
- A list of arguments to pass to @command{login}.
- @item @code{auto-login} (default: @code{#f})
- When passed a login name, as a string, the specified user will be logged
- in automatically without prompting for their login name or password.
- @item @code{hardware-acceleration?} (default: #f)
- Whether to use hardware acceleration.
- @item @code{font-engine} (default: @code{"pango"})
- Font engine used in Kmscon.
- @item @code{font-size} (default: @code{12})
- Font size used in Kmscon.
- @item @code{keyboard-layout} (default: @code{#f})
- If this is @code{#f}, Kmscon uses the default keyboard layout---usually US
- English (``qwerty'') for a 105-key PC keyboard.
- Otherwise this must be a @code{keyboard-layout} object specifying the
- keyboard layout. @xref{Keyboard Layout}, for more information on how to
- specify the keyboard layout.
- @item @code{kmscon} (default: @var{kmscon})
- The Kmscon package to use.
- @end table
- @end deftp
- @cindex name service cache daemon
- @cindex nscd
- @deffn {Scheme Procedure} nscd-service [@var{config}] [#:glibc glibc] @
- [#:name-services '()]
- Return a service that runs the libc name service cache daemon (nscd) with the
- given @var{config}---an @code{<nscd-configuration>} object. @xref{Name
- Service Switch}, for an example.
- For convenience, the Shepherd service for nscd provides the following actions:
- @table @code
- @item invalidate
- @cindex cache invalidation, nscd
- @cindex nscd, cache invalidation
- This invalidate the given cache. For instance, running:
- @example
- herd invalidate nscd hosts
- @end example
- @noindent
- invalidates the host name lookup cache of nscd.
- @item statistics
- Running @command{herd statistics nscd} displays information about nscd usage
- and caches.
- @end table
- @end deffn
- @defvr {Scheme Variable} %nscd-default-configuration
- This is the default @code{<nscd-configuration>} value (see below) used
- by @code{nscd-service}. It uses the caches defined by
- @code{%nscd-default-caches}; see below.
- @end defvr
- @deftp {Data Type} nscd-configuration
- This is the data type representing the name service cache daemon (nscd)
- configuration.
- @table @asis
- @item @code{name-services} (default: @code{'()})
- List of packages denoting @dfn{name services} that must be visible to
- the nscd---e.g., @code{(list @var{nss-mdns})}.
- @item @code{glibc} (default: @var{glibc})
- Package object denoting the GNU C Library providing the @command{nscd}
- command.
- @item @code{log-file} (default: @code{"/var/log/nscd.log"})
- Name of the nscd log file. This is where debugging output goes when
- @code{debug-level} is strictly positive.
- @item @code{debug-level} (default: @code{0})
- Integer denoting the debugging levels. Higher numbers mean that more
- debugging output is logged.
- @item @code{caches} (default: @code{%nscd-default-caches})
- List of @code{<nscd-cache>} objects denoting things to be cached; see
- below.
- @end table
- @end deftp
- @deftp {Data Type} nscd-cache
- Data type representing a cache database of nscd and its parameters.
- @table @asis
- @item @code{database}
- This is a symbol representing the name of the database to be cached.
- Valid values are @code{passwd}, @code{group}, @code{hosts}, and
- @code{services}, which designate the corresponding NSS database
- (@pxref{NSS Basics,,, libc, The GNU C Library Reference Manual}).
- @item @code{positive-time-to-live}
- @itemx @code{negative-time-to-live} (default: @code{20})
- A number representing the number of seconds during which a positive or
- negative lookup result remains in cache.
- @item @code{check-files?} (default: @code{#t})
- Whether to check for updates of the files corresponding to
- @var{database}.
- For instance, when @var{database} is @code{hosts}, setting this flag
- instructs nscd to check for updates in @file{/etc/hosts} and to take
- them into account.
- @item @code{persistent?} (default: @code{#t})
- Whether the cache should be stored persistently on disk.
- @item @code{shared?} (default: @code{#t})
- Whether the cache should be shared among users.
- @item @code{max-database-size} (default: 32@tie{}MiB)
- Maximum size in bytes of the database cache.
- @c XXX: 'suggested-size' and 'auto-propagate?' seem to be expert
- @c settings, so leave them out.
- @end table
- @end deftp
- @defvr {Scheme Variable} %nscd-default-caches
- List of @code{<nscd-cache>} objects used by default by
- @code{nscd-configuration} (see above).
- It enables persistent and aggressive caching of service and host name
- lookups. The latter provides better host name lookup performance,
- resilience in the face of unreliable name servers, and also better
- privacy---often the result of host name lookups is in local cache, so
- external name servers do not even need to be queried.
- @end defvr
- @anchor{syslog-configuration-type}
- @cindex syslog
- @cindex logging
- @deftp {Data Type} syslog-configuration
- This data type represents the configuration of the syslog daemon.
- @table @asis
- @item @code{syslogd} (default: @code{#~(string-append #$inetutils "/libexec/syslogd")})
- The syslog daemon to use.
- @item @code{config-file} (default: @code{%default-syslog.conf})
- The syslog configuration file to use.
- @end table
- @end deftp
- @anchor{syslog-service}
- @cindex syslog
- @deffn {Scheme Procedure} syslog-service @var{config}
- Return a service that runs a syslog daemon according to @var{config}.
- @xref{syslogd invocation,,, inetutils, GNU Inetutils}, for more
- information on the configuration file syntax.
- @end deffn
- @defvr {Scheme Variable} guix-service-type
- This is the type of the service that runs the build daemon,
- @command{guix-daemon} (@pxref{Invoking guix-daemon}). Its value must be a
- @code{guix-configuration} record as described below.
- @end defvr
- @anchor{guix-configuration-type}
- @deftp {Data Type} guix-configuration
- This data type represents the configuration of the Guix build daemon.
- @xref{Invoking guix-daemon}, for more information.
- @table @asis
- @item @code{guix} (default: @var{guix})
- The Guix package to use.
- @item @code{build-group} (default: @code{"guixbuild"})
- Name of the group for build user accounts.
- @item @code{build-accounts} (default: @code{10})
- Number of build user accounts to create.
- @item @code{authorize-key?} (default: @code{#t})
- @cindex substitutes, authorization thereof
- Whether to authorize the substitute keys listed in
- @code{authorized-keys}---by default that of
- @code{@value{SUBSTITUTE-SERVER-1}} and
- @code{@value{SUBSTITUTE-SERVER-2}}
- (@pxref{Substitutes}).
- When @code{authorize-key?} is true, @file{/etc/guix/acl} cannot be
- changed by invoking @command{guix archive --authorize}. You must
- instead adjust @code{guix-configuration} as you wish and reconfigure the
- system. This ensures that your operating system configuration file is
- self-contained.
- @quotation Note
- When booting or reconfiguring to a system where @code{authorize-key?}
- is true, the existing @file{/etc/guix/acl} file is backed up as
- @file{/etc/guix/acl.bak} if it was determined to be a manually modified
- file. This is to facilitate migration from earlier versions, which
- allowed for in-place modifications to @file{/etc/guix/acl}.
- @end quotation
- @vindex %default-authorized-guix-keys
- @item @code{authorized-keys} (default: @code{%default-authorized-guix-keys})
- The list of authorized key files for archive imports, as a list of
- string-valued gexps (@pxref{Invoking guix archive}). By default, it
- contains that of @code{@value{SUBSTITUTE-SERVER-1}} and
- @code{@value{SUBSTITUTE-SERVER-2}} (@pxref{Substitutes}). See
- @code{substitute-urls} below for an example on how to change it.
- @item @code{use-substitutes?} (default: @code{#t})
- Whether to use substitutes.
- @item @code{substitute-urls} (default: @code{%default-substitute-urls})
- The list of URLs where to look for substitutes by default.
- Suppose you would like to fetch substitutes from @code{guix.example.org}
- in addition to @code{@value{SUBSTITUTE-SERVER-1}}. You will need to do
- two things: (1) add @code{guix.example.org} to @code{substitute-urls},
- and (2) authorize its signing key, having done appropriate checks
- (@pxref{Substitute Server Authorization}). The configuration below does
- exactly that:
- @lisp
- (guix-configuration
- (substitute-urls
- (append (list "https://guix.example.org")
- %default-substitute-urls))
- (authorized-keys
- (append (list (local-file "./guix.example.org-key.pub"))
- %default-authorized-guix-keys)))
- @end lisp
- This example assumes that the file @file{./guix.example.org-key.pub}
- contains the public key that @code{guix.example.org} uses to sign
- substitutes.
- @item @code{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) ("zstd" 3))})
- This is a list of compression method/level tuple used when compressing
- substitutes. For example, to compress all substitutes with @emph{both} lzip
- at level 7 and gzip at level 9, write:
- @lisp
- '(("lzip" 7) ("gzip" 9))
- @end lisp
- Level 9 achieves the best compression ratio at the expense of increased CPU
- usage, whereas level 1 achieves fast compression. @xref{Invoking guix
- publish}, for more information on the available compression methods and
- the tradeoffs involved.
- An empty list disables compression altogether.
- @item @code{nar-path} (default: @code{"nar"})
- The URL path at which ``nars'' can be fetched. @xref{Invoking guix
- publish, @option{--nar-path}}, for details.
- @item @code{cache} (default: @code{#f})
- When it is @code{#f}, disable caching and instead generate archives on
- demand. Otherwise, this should be the name of a directory---e.g.,
- @code{"/var/cache/guix/publish"}---where @command{guix publish} caches
- archives and meta-data ready to be sent. @xref{Invoking guix publish,
- @option{--cache}}, for more information on the tradeoffs involved.
- @item @code{workers} (default: @code{#f})
- When it is an integer, this is the number of worker threads used for
- caching; when @code{#f}, the number of processors is used.
- @xref{Invoking guix publish, @option{--workers}}, for more information.
- @item @code{cache-bypass-threshold} (default: 10 MiB)
- When @code{cache} is true, this is the maximum size in bytes of a store
- item for which @command{guix publish} may bypass its cache in case of a
- cache miss. @xref{Invoking guix publish,
- @option{--cache-bypass-threshold}}, for more information.
- @item @code{ttl} (default: @code{#f})
- When it is an integer, this denotes the @dfn{time-to-live} in seconds
- of the published archives. @xref{Invoking guix publish, @option{--ttl}},
- for more information.
- @end table
- @end deftp
- @anchor{rngd-service}
- @deffn {Scheme Procedure} rngd-service [#:rng-tools @var{rng-tools}] @
- [#:device "/dev/hwrng"]
- Return a service that runs the @command{rngd} program from @var{rng-tools}
- to add @var{device} to the kernel's entropy pool. The service will fail if
- @var{device} does not exist.
- @end deffn
- @anchor{pam-limits-service}
- @cindex session limits
- @cindex ulimit
- @cindex priority
- @cindex realtime
- @cindex jackd
- @cindex nofile
- @cindex open file descriptors
- @deffn {Scheme Procedure} pam-limits-service [#:limits @code{'()}]
- Return a service that installs a configuration file for the
- @uref{http://linux-pam.org/Linux-PAM-html/sag-pam_limits.html,
- @code{pam_limits} module}. The procedure optionally takes a list of
- @code{pam-limits-entry} values, which can be used to specify
- @code{ulimit} limits and @code{nice} priority limits to user sessions.
- The following limits definition sets two hard and soft limits for all
- login sessions of users in the @code{realtime} group:
- @lisp
- (pam-limits-service
- (list
- (pam-limits-entry "@@realtime" 'both 'rtprio 99)
- (pam-limits-entry "@@realtime" 'both 'memlock 'unlimited)))
- @end lisp
- The first entry increases the maximum realtime priority for
- non-privileged processes; the second entry lifts any restriction of the
- maximum address space that can be locked in memory. These settings are
- commonly used for real-time audio systems.
- Another useful example is raising the maximum number of open file
- descriptors that can be used:
- @lisp
- (pam-limits-service
- (list
- (pam-limits-entry "*" 'both 'nofile 100000)))
- @end lisp
- In the above example, the asterisk means the limit should apply to any
- user. It is important to ensure the chosen value doesn't exceed the
- maximum system value visible in the @file{/proc/sys/fs/file-max} file,
- else the users would be prevented from login in. For more information
- about the Pluggable Authentication Module (PAM) limits, refer to the
- @samp{pam_limits} man page from the @code{linux-pam} package.
- @end deffn
- @node Scheduled Job Execution
- @subsection Scheduled Job Execution
- @cindex cron
- @cindex mcron
- @cindex scheduling jobs
- The @code{(gnu services mcron)} module provides an interface to
- GNU@tie{}mcron, a daemon to run jobs at scheduled times (@pxref{Top,,,
- mcron, GNU@tie{}mcron}). GNU@tie{}mcron is similar to the traditional
- Unix @command{cron} daemon; the main difference is that it is
- implemented in Guile Scheme, which provides a lot of flexibility when
- specifying the scheduling of jobs and their actions.
- The example below defines an operating system that runs the
- @command{updatedb} (@pxref{Invoking updatedb,,, find, Finding Files})
- and the @command{guix gc} commands (@pxref{Invoking guix gc}) daily, as
- well as the @command{mkid} command on behalf of an unprivileged user
- (@pxref{mkid invocation,,, idutils, ID Database Utilities}). It uses
- gexps to introduce job definitions that are passed to mcron
- (@pxref{G-Expressions}).
- @lisp
- (use-modules (guix) (gnu) (gnu services mcron))
- (use-package-modules base idutils)
- (define updatedb-job
- ;; Run 'updatedb' at 3AM every day. Here we write the
- ;; job's action as a Scheme procedure.
- #~(job '(next-hour '(3))
- (lambda ()
- (execl (string-append #$findutils "/bin/updatedb")
- "updatedb"
- "--prunepaths=/tmp /var/tmp /gnu/store"))
- "updatedb"))
- (define garbage-collector-job
- ;; Collect garbage 5 minutes after midnight every day.
- ;; The job's action is a shell command.
- #~(job "5 0 * * *" ;Vixie cron syntax
- "guix gc -F 1G"))
- (define idutils-job
- ;; Update the index database as user "charlie" at 12:15PM
- ;; and 19:15PM. This runs from the user's home directory.
- #~(job '(next-minute-from (next-hour '(12 19)) '(15))
- (string-append #$idutils "/bin/mkid src")
- #:user "charlie"))
- (operating-system
- ;; @dots{}
- ;; %BASE-SERVICES already includes an instance of
- ;; 'mcron-service-type', which we extend with additional
- ;; jobs using 'simple-service'.
- (services (cons (simple-service 'my-cron-jobs
- mcron-service-type
- (list garbage-collector-job
- updatedb-job
- idutils-job))
- %base-services)))
- @end lisp
- @quotation Tip
- When providing the action of a job specification as a procedure, you
- should provide an explicit name for the job via the optional 3rd
- argument as done in the @code{updatedb-job} example above. Otherwise,
- the job would appear as ``Lambda function'' in the output of
- @command{herd schedule mcron}, which is not nearly descriptive enough!
- @end quotation
- For more complex jobs defined in Scheme where you need control over the top
- level, for instance to introduce a @code{use-modules} form, you can move your
- code to a separate program using the @code{program-file} procedure of the
- @code{(guix gexp)} module (@pxref{G-Expressions}). The example below
- illustrates that.
- @lisp
- (define %battery-alert-job
- ;; Beep when the battery percentage falls below %MIN-LEVEL.
- #~(job
- '(next-minute (range 0 60 1))
- #$(program-file
- "battery-alert.scm"
- (with-imported-modules (source-module-closure
- '((guix build utils)))
- #~(begin
- (use-modules (guix build utils)
- (ice-9 popen)
- (ice-9 regex)
- (ice-9 textual-ports)
- (srfi srfi-2))
- (define %min-level 20)
- (setenv "LC_ALL" "C") ;ensure English output
- (and-let* ((input-pipe (open-pipe*
- OPEN_READ
- #$(file-append acpi "/bin/acpi")))
- (output (get-string-all input-pipe))
- (m (string-match "Discharging, ([0-9]+)%" output))
- (level (string->number (match:substring m 1)))
- ((< level %min-level)))
- (format #t "warning: Battery level is low (~a%)~%" level)
- (invoke #$(file-append beep "/bin/beep") "-r5")))))))
- @end lisp
- @xref{Guile Syntax, mcron job specifications,, mcron, GNU@tie{}mcron},
- for more information on mcron job specifications. Below is the
- reference of the mcron service.
- On a running system, you can use the @code{schedule} action of the service to
- visualize the mcron jobs that will be executed next:
- @example
- # herd schedule mcron
- @end example
- @noindent
- The example above lists the next five tasks that will be executed, but you can
- also specify the number of tasks to display:
- @example
- # herd schedule mcron 10
- @end example
- @defvr {Scheme Variable} mcron-service-type
- This is the type of the @code{mcron} service, whose value is an
- @code{mcron-configuration} object.
- This service type can be the target of a service extension that provides
- 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 -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT
- -A INPUT -p tcp --dport 22 -j ACCEPT
- -A INPUT -j REJECT --reject-with icmp-port-unreachable
- COMMIT
- "))
- (ipv6-rules (plain-file "ip6tables.rules" "*filter
- :INPUT ACCEPT
- :FORWARD ACCEPT
- :OUTPUT ACCEPT
- -A INPUT -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT
- -A INPUT -p tcp --dport 22 -j ACCEPT
- -A INPUT -j REJECT --reject-with icmp6-port-unreachable
- COMMIT
- "))))
- @end lisp
- @end defvr
- @deftp {Data Type} iptables-configuration
- The data type representing the configuration of iptables.
- @table @asis
- @item @code{iptables} (default: @code{iptables})
- The iptables package that provides @code{iptables-restore} and
- @code{ip6tables-restore}.
- @item @code{ipv4-rules} (default: @code{%iptables-accept-all-rules})
- The iptables rules to use. It will be passed to @code{iptables-restore}.
- This may be any ``file-like'' object (@pxref{G-Expressions, file-like
- objects}).
- @item @code{ipv6-rules} (default: @code{%iptables-accept-all-rules})
- The ip6tables rules to use. It will be passed to @code{ip6tables-restore}.
- This may be any ``file-like'' object (@pxref{G-Expressions, file-like
- objects}).
- @end table
- @end deftp
- @cindex nftables
- @defvr {Scheme Variable} nftables-service-type
- This is the service type to set up a nftables configuration. nftables is a
- netfilter project that aims to replace the existing iptables, ip6tables,
- arptables and ebtables framework. It provides a new packet filtering
- framework, a new user-space utility @command{nft}, and a compatibility layer
- for iptables. This service comes with a default ruleset
- @code{%default-nftables-ruleset} that rejecting all incoming connections
- except those to the ssh port 22. To use it, simply write:
- @lisp
- (service nftables-service-type)
- @end lisp
- @end defvr
- @deftp {Data Type} nftables-configuration
- The data type representing the configuration of nftables.
- @table @asis
- @item @code{package} (default: @code{nftables})
- The nftables package that provides @command{nft}.
- @item @code{ruleset} (default: @code{%default-nftables-ruleset})
- The nftables ruleset to use. This may be any ``file-like'' object
- (@pxref{G-Expressions, file-like objects}).
- @end table
- @end deftp
- @cindex NTP (Network Time Protocol), service
- @cindex ntpd, service for the Network Time Protocol daemon
- @cindex real time clock
- @defvr {Scheme Variable} ntp-service-type
- This is the type of the service running the @uref{https://www.ntp.org,
- Network Time Protocol (NTP)} daemon, @command{ntpd}. The daemon will keep the
- system clock synchronized with that of the specified NTP servers.
- The value of this service is an @code{ntpd-configuration} object, as described
- below.
- @end defvr
- @deftp {Data Type} ntp-configuration
- This is the data type for the NTP service configuration.
- @table @asis
- @item @code{servers} (default: @code{%ntp-servers})
- This is the list of servers (@code{<ntp-server>} records) with which
- @command{ntpd} will be synchronized. See the @code{ntp-server} data type
- definition below.
- @item @code{allow-large-adjustment?} (default: @code{#t})
- This determines whether @command{ntpd} is allowed to make an initial
- adjustment of more than 1,000 seconds.
- @item @code{ntp} (default: @code{ntp})
- The NTP package to use.
- @end table
- @end deftp
- @defvr {Scheme Variable} %ntp-servers
- List of host names used as the default NTP servers. These are servers of the
- @uref{https://www.ntppool.org/en/, NTP Pool Project}.
- @end defvr
- @deftp {Data Type} ntp-server
- The data type representing the configuration of a NTP server.
- @table @asis
- @item @code{type} (default: @code{'server})
- The type of the NTP server, given as a symbol. One of @code{'pool},
- @code{'server}, @code{'peer}, @code{'broadcast} or @code{'manycastclient}.
- @item @code{address}
- The address of the server, as a string.
- @item @code{options}
- NTPD options to use with that specific server, given as a list of option names
- and/or of option names and values tuples. The following example define a server
- to use with the options @option{iburst} and @option{prefer}, as well as
- @option{version} 3 and a @option{maxpoll} time of 16 seconds.
- @example
- (ntp-server
- (type 'server)
- (address "some.ntp.server.org")
- (options `(iburst (version 3) (maxpoll 16) prefer))))
- @end example
- @end table
- @end deftp
- @cindex OpenNTPD
- @deffn {Scheme Procedure} openntpd-service-type
- Run the @command{ntpd}, the Network Time Protocol (NTP) daemon, as implemented
- by @uref{http://www.openntpd.org, OpenNTPD}. The daemon will keep the system
- clock synchronized with that of the given servers.
- @lisp
- (service
- openntpd-service-type
- (openntpd-configuration
- (listen-on '("127.0.0.1" "::1"))
- (sensor '("udcf0 correction 70000"))
- (constraint-from '("www.gnu.org"))
- (constraints-from '("https://www.google.com/"))))
- @end lisp
- @end deffn
- @defvr {Scheme Variable} %openntpd-servers
- This variable is a list of the server addresses defined in
- @code{%ntp-servers}.
- @end defvr
- @deftp {Data Type} openntpd-configuration
- @table @asis
- @item @code{openntpd} (default: @code{(file-append openntpd "/sbin/ntpd")})
- The openntpd executable to use.
- @item @code{listen-on} (default: @code{'("127.0.0.1" "::1")})
- A list of local IP addresses or hostnames the ntpd daemon should listen on.
- @item @code{query-from} (default: @code{'()})
- A list of local IP address the ntpd daemon should use for outgoing queries.
- @item @code{sensor} (default: @code{'()})
- Specify a list of timedelta sensor devices ntpd should use. @code{ntpd}
- will listen to each sensor that actually exists and ignore non-existent ones.
- See @uref{https://man.openbsd.org/ntpd.conf, upstream documentation} for more
- information.
- @item @code{server} (default: @code{'()})
- Specify a list of IP addresses or hostnames of NTP servers to synchronize to.
- @item @code{servers} (default: @code{%openntp-servers})
- Specify a list of IP addresses or hostnames of NTP pools to synchronize to.
- @item @code{constraint-from} (default: @code{'()})
- @code{ntpd} can be configured to query the ‘Date’ from trusted HTTPS servers via TLS.
- This time information is not used for precision but acts as an authenticated
- constraint, thereby reducing the impact of unauthenticated NTP
- man-in-the-middle attacks.
- Specify a list of URLs, IP addresses or hostnames of HTTPS servers to provide
- a constraint.
- @item @code{constraints-from} (default: @code{'()})
- As with constraint from, specify a list of URLs, IP addresses or hostnames of
- HTTPS servers to provide a constraint. Should the hostname resolve to multiple
- IP addresses, @code{ntpd} will calculate a median constraint from all of them.
- @end table
- @end deftp
- @cindex inetd
- @deffn {Scheme variable} inetd-service-type
- This service runs the @command{inetd} (@pxref{inetd invocation,,,
- inetutils, GNU Inetutils}) daemon. @command{inetd} listens for
- connections on internet sockets, and lazily starts the specified server
- program when a connection is made on one of these sockets.
- The value of this service is an @code{inetd-configuration} object. The
- following example configures the @command{inetd} daemon to provide the
- built-in @command{echo} service, as well as an smtp service which
- forwards smtp traffic over ssh to a server @code{smtp-server} behind a
- gateway @code{hostname}:
- @lisp
- (service
- inetd-service-type
- (inetd-configuration
- (entries (list
- (inetd-entry
- (name "echo")
- (socket-type 'stream)
- (protocol "tcp")
- (wait? #f)
- (user "root"))
- (inetd-entry
- (node "127.0.0.1")
- (name "smtp")
- (socket-type 'stream)
- (protocol "tcp")
- (wait? #f)
- (user "root")
- (program (file-append openssh "/bin/ssh"))
- (arguments
- '("ssh" "-qT" "-i" "/path/to/ssh_key"
- "-W" "smtp-server:25" "user@@hostname")))))))
- @end lisp
- See below for more details about @code{inetd-configuration}.
- @end deffn
- @deftp {Data Type} inetd-configuration
- Data type representing the configuration of @command{inetd}.
- @table @asis
- @item @code{program} (default: @code{(file-append inetutils "/libexec/inetd")})
- The @command{inetd} executable to use.
- @item @code{entries} (default: @code{'()})
- A list of @command{inetd} service entries. Each entry should be created
- by the @code{inetd-entry} constructor.
- @end table
- @end deftp
- @deftp {Data Type} inetd-entry
- Data type representing an entry in the @command{inetd} configuration.
- Each entry corresponds to a socket where @command{inetd} will listen for
- requests.
- @table @asis
- @item @code{node} (default: @code{#f})
- Optional string, a comma-separated list of local addresses
- @command{inetd} should use when listening for this service.
- @xref{Configuration file,,, inetutils, GNU Inetutils} for a complete
- description of all options.
- @item @code{name}
- A string, the name must correspond to an entry in @code{/etc/services}.
- @item @code{socket-type}
- One of @code{'stream}, @code{'dgram}, @code{'raw}, @code{'rdm} or
- @code{'seqpacket}.
- @item @code{protocol}
- A string, must correspond to an entry in @code{/etc/protocols}.
- @item @code{wait?} (default: @code{#t})
- Whether @command{inetd} should wait for the server to exit before
- listening to new service requests.
- @item @code{user}
- A string containing the user (and, optionally, group) name of the user
- as whom the server should run. The group name can be specified in a
- suffix, separated by a colon or period, i.e.@: @code{"user"},
- @code{"user:group"} or @code{"user.group"}.
- @item @code{program} (default: @code{"internal"})
- The server program which will serve the requests, or @code{"internal"}
- if @command{inetd} should use a built-in service.
- @item @code{arguments} (default: @code{'()})
- A list strings or file-like objects, which are the server program's
- arguments, starting with the zeroth argument, i.e.@: the name of the
- program itself. For @command{inetd}'s internal services, this entry
- must be @code{'()} or @code{'("internal")}.
- @end table
- @xref{Configuration file,,, inetutils, GNU Inetutils} for a more
- detailed discussion of each configuration field.
- @end deftp
- @cindex opendht, distributed hash table network service
- @cindex dhtproxy, for use with jami
- @defvr {Scheme Variable} opendht-service-type
- This is the type of the service running a @uref{https://opendht.net,
- OpenDHT} node, @command{dhtnode}. The daemon can be used to host your
- own proxy service to the distributed hash table (DHT), for example to
- connect to with Jami, among other applications.
- @quotation Important
- When using the OpenDHT proxy server, the IP addresses it ``sees'' from
- the clients should be addresses reachable from other peers. In practice
- this means that a publicly reachable address is best suited for a proxy
- server, outside of your private network. For example, hosting the proxy
- server on a IPv4 private local network and exposing it via port
- forwarding could work for external peers, but peers local to the proxy
- would have their private addresses shared with the external peers,
- leading to connectivity problems.
- @end quotation
- The value of this service is a @code{opendht-configuration} object, as
- described below.
- @end defvr
- @deftp {Data Type} opendht-configuration
- This is the data type for the OpenDHT service configuration.
- @c The fields documentation has been auto-generated using the
- @c configuration->documentation procedure from
- @c (gnu services configuration).
- Available @code{opendht-configuration} fields are:
- @deftypevr {@code{opendht-configuration} parameter} package opendht
- The @code{opendht} package to use.
- @end deftypevr
- @deftypevr {@code{opendht-configuration} parameter} boolean peer-discovery?
- Whether to enable the multicast local peer discovery mechanism.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{opendht-configuration} parameter} boolean enable-logging?
- Whether to enable logging messages to syslog. It is disabled by default
- as it is rather verbose.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{opendht-configuration} parameter} boolean debug?
- Whether to enable debug-level logging messages. This has no effect if
- logging is disabled.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{opendht-configuration} parameter} maybe-string bootstrap-host
- The node host name that is used to make the first connection to the
- network. A specific port value can be provided by appending the
- @code{:PORT} suffix. By default, it uses the Jami bootstrap nodes, but
- any host can be specified here. It's also possible to disable
- bootsrapping by setting this to the @code{'disabled} symbol.
- Defaults to @samp{"bootstrap.jami.net:4222"}.
- @end deftypevr
- @deftypevr {@code{opendht-configuration} parameter} maybe-number port
- The UDP port to bind to. When set to @code{'disabled}, an available
- port is automatically selected.
- Defaults to @samp{4222}.
- @end deftypevr
- @deftypevr {@code{opendht-configuration} parameter} maybe-number proxy-server-port
- Spawn a proxy server listening on the specified port.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{opendht-configuration} parameter} maybe-number proxy-server-port-tls
- Spawn a proxy server listening to TLS connections on the specified port.
- Defaults to @samp{disabled}.
- @end deftypevr
- @end deftp
- @cindex Tor
- @defvr {Scheme Variable} tor-service-type
- This is the type for a service that runs the @uref{https://torproject.org,
- Tor} anonymous networking daemon. The service is configured using a
- @code{<tor-configuration>} record. By default, the Tor daemon runs as the
- @code{tor} unprivileged user, which is a member of the @code{tor} group.
- @end defvr
- @deftp {Data Type} tor-configuration
- @table @asis
- @item @code{tor} (default: @code{tor})
- The package that provides the Tor daemon. This package is expected to provide
- the daemon at @file{bin/tor} relative to its output directory. The default
- package is the @uref{https://www.torproject.org, Tor Project's}
- implementation.
- @item @code{config-file} (default: @code{(plain-file "empty" "")})
- The configuration file to use. It will be appended to a default configuration
- file, and the final configuration file will be passed to @code{tor} via its
- @code{-f} option. This may be any ``file-like'' object (@pxref{G-Expressions,
- file-like objects}). See @code{man tor} for details on the configuration file
- syntax.
- @item @code{hidden-services} (default: @code{'()})
- The list of @code{<hidden-service>} records to use. For any hidden service
- you include in this list, appropriate configuration to enable the hidden
- service will be automatically added to the default configuration file. You
- may conveniently create @code{<hidden-service>} records using the
- @code{tor-hidden-service} procedure described below.
- @item @code{socks-socket-type} (default: @code{'tcp})
- The default socket type that Tor should use for its SOCKS socket. This must
- be either @code{'tcp} or @code{'unix}. If it is @code{'tcp}, then by default
- Tor will listen on TCP port 9050 on the loopback interface (i.e., localhost).
- If it is @code{'unix}, then Tor will listen on the UNIX domain socket
- @file{/var/run/tor/socks-sock}, which will be made writable by members of the
- @code{tor} group.
- If you want to customize the SOCKS socket in more detail, leave
- @code{socks-socket-type} at its default value of @code{'tcp} and use
- @code{config-file} to override the default by providing your own
- @code{SocksPort} option.
- @item @code{control-socket?} (default: @code{#f})
- Whether or not to provide a ``control socket'' by which Tor can be
- controlled to, for instance, dynamically instantiate tor onion services.
- If @code{#t}, Tor will listen for control commands on the UNIX domain socket
- @file{/var/run/tor/control-sock}, which will be made writable by members of the
- @code{tor} group.
- @end table
- @end deftp
- @cindex hidden service
- @deffn {Scheme Procedure} tor-hidden-service @var{name} @var{mapping}
- Define a new Tor @dfn{hidden service} called @var{name} and implementing
- @var{mapping}. @var{mapping} is a list of port/host tuples, such as:
- @example
- '((22 "127.0.0.1:22")
- (80 "127.0.0.1:8080"))
- @end example
- In this example, port 22 of the hidden service is mapped to local port 22, and
- port 80 is mapped to local port 8080.
- This creates a @file{/var/lib/tor/hidden-services/@var{name}} directory, where
- the @file{hostname} file contains the @code{.onion} host name for the hidden
- service.
- See @uref{https://www.torproject.org/docs/tor-hidden-service.html.en, the Tor
- project's documentation} for more information.
- @end deffn
- The @code{(gnu services rsync)} module provides the following services:
- You might want an rsync daemon if you have files that you want available
- so anyone (or just yourself) can download existing files or upload new
- files.
- @deffn {Scheme Variable} rsync-service-type
- This is the service type for the @uref{https://rsync.samba.org, rsync} daemon,
- The value for this service type is a
- @command{rsync-configuration} record as in this example:
- @lisp
- (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 logging flags, see
- @uref{https://docs.syncthing.net/users/syncthing.html#cmdoption-logflags, Syncthing documentation logflags}.
- @item @code{user} (default: @var{#f})
- The user as which the Syncthing service is to be run.
- This assumes that the specified user exists.
- @item @code{group} (default: @var{"users"})
- The group as which the Syncthing service is to be run.
- This assumes that the specified group exists.
- @item @code{home} (default: @var{#f})
- Common configuration and data directory. The default configuration
- directory is @file{$HOME} of the specified Syncthing @code{user}.
- @end table
- @end deftp
- @end deffn
- Furthermore, @code{(gnu services ssh)} provides the following services.
- @cindex SSH
- @cindex SSH server
- @deffn {Scheme Procedure} lsh-service [#:host-key "/etc/lsh/host-key"] @
- [#:daemonic? #t] [#:interfaces '()] [#:port-number 22] @
- [#:allow-empty-passwords? #f] [#:root-login? #f] @
- [#:syslog-output? #t] [#:x11-forwarding? #t] @
- [#:tcp/ip-forwarding? #t] [#:password-authentication? #t] @
- [#:public-key-authentication? #t] [#:initialize? #t]
- Run the @command{lshd} program from @var{lsh} to listen on port @var{port-number}.
- @var{host-key} must designate a file containing the host key, and readable
- only by root.
- When @var{daemonic?} is true, @command{lshd} will detach from the
- controlling terminal and log its output to syslogd, unless one sets
- @var{syslog-output?} to false. Obviously, it also makes lsh-service
- depend on existence of syslogd service. When @var{pid-file?} is true,
- @command{lshd} writes its PID to the file called @var{pid-file}.
- When @var{initialize?} is true, automatically create the seed and host key
- upon service activation if they do not exist yet. This may take long and
- require interaction.
- When @var{initialize?} is false, it is up to the user to initialize the
- randomness generator (@pxref{lsh-make-seed,,, lsh, LSH Manual}), and to create
- a key pair with the private key stored in file @var{host-key} (@pxref{lshd
- basics,,, lsh, LSH Manual}).
- When @var{interfaces} is empty, lshd listens for connections on all the
- network interfaces; otherwise, @var{interfaces} must be a list of host names
- or addresses.
- @var{allow-empty-passwords?} specifies whether to accept log-ins with empty
- passwords, and @var{root-login?} specifies whether to accept log-ins as
- root.
- The other options should be self-descriptive.
- @end deffn
- @cindex SSH
- @cindex SSH server
- @deffn {Scheme Variable} openssh-service-type
- This is the type for the @uref{http://www.openssh.org, OpenSSH} secure
- shell daemon, @command{sshd}. Its value must be an
- @code{openssh-configuration} record as in this example:
- @lisp
- (service openssh-service-type
- (openssh-configuration
- (x11-forwarding? #t)
- (permit-root-login 'prohibit-password)
- (authorized-keys
- `(("alice" ,(local-file "alice.pub"))
- ("bob" ,(local-file "bob.pub"))))))
- @end lisp
- See below for details about @code{openssh-configuration}.
- This service can be extended with extra authorized keys, as in this
- example:
- @lisp
- (service-extension openssh-service-type
- (const `(("charlie"
- ,(local-file "charlie.pub")))))
- @end lisp
- @end deffn
- @deftp {Data Type} openssh-configuration
- This is the configuration record for OpenSSH's @command{sshd}.
- @table @asis
- @item @code{openssh} (default @var{openssh})
- The Openssh package to use.
- @item @code{pid-file} (default: @code{"/var/run/sshd.pid"})
- Name of the file where @command{sshd} writes its PID.
- @item @code{port-number} (default: @code{22})
- TCP port on which @command{sshd} listens for incoming connections.
- @item @code{permit-root-login} (default: @code{#f})
- This field determines whether and when to allow logins as root. If
- @code{#f}, root logins are disallowed; if @code{#t}, they are allowed.
- If it's the symbol @code{'prohibit-password}, then root logins are
- permitted but not with password-based authentication.
- @item @code{allow-empty-passwords?} (default: @code{#f})
- When true, users with empty passwords may log in. When false, they may
- not.
- @item @code{password-authentication?} (default: @code{#t})
- When true, users may log in with their password. When false, they have
- other authentication methods.
- @item @code{public-key-authentication?} (default: @code{#t})
- When true, users may log in using public key authentication. When
- false, users have to use other authentication method.
- Authorized public keys are stored in @file{~/.ssh/authorized_keys}.
- This is used only by protocol version 2.
- @item @code{x11-forwarding?} (default: @code{#f})
- When true, forwarding of X11 graphical client connections is
- enabled---in other words, @command{ssh} options @option{-X} and
- @option{-Y} will work.
- @item @code{allow-agent-forwarding?} (default: @code{#t})
- Whether to allow agent forwarding.
- @item @code{allow-tcp-forwarding?} (default: @code{#t})
- Whether to allow TCP forwarding.
- @item @code{gateway-ports?} (default: @code{#f})
- Whether to allow gateway ports.
- @item @code{challenge-response-authentication?} (default: @code{#f})
- Specifies whether challenge response authentication is allowed (e.g.@: via
- PAM).
- @item @code{use-pam?} (default: @code{#t})
- Enables the Pluggable Authentication Module interface. If set to
- @code{#t}, this will enable PAM authentication using
- @code{challenge-response-authentication?} and
- @code{password-authentication?}, in addition to PAM account and session
- module processing for all authentication types.
- Because PAM challenge response authentication usually serves an
- equivalent role to password authentication, you should disable either
- @code{challenge-response-authentication?} or
- @code{password-authentication?}.
- @item @code{print-last-log?} (default: @code{#t})
- Specifies whether @command{sshd} should print the date and time of the
- last user login when a user logs in interactively.
- @item @code{subsystems} (default: @code{'(("sftp" "internal-sftp"))})
- Configures external subsystems (e.g.@: file transfer daemon).
- This is a list of two-element lists, each of which containing the
- subsystem name and a command (with optional arguments) to execute upon
- subsystem request.
- The command @command{internal-sftp} implements an in-process SFTP
- server. Alternatively, one can specify the @command{sftp-server} command:
- @lisp
- (service openssh-service-type
- (openssh-configuration
- (subsystems
- `(("sftp" ,(file-append openssh "/libexec/sftp-server"))))))
- @end lisp
- @item @code{accepted-environment} (default: @code{'()})
- List of strings describing which environment variables may be exported.
- Each string gets on its own line. See the @code{AcceptEnv} option in
- @code{man sshd_config}.
- This example allows ssh-clients to export the @env{COLORTERM} variable.
- It is set by terminal emulators, which support colors. You can use it in
- your shell's resource file to enable colors for the prompt and commands
- if this variable is set.
- @lisp
- (service openssh-service-type
- (openssh-configuration
- (accepted-environment '("COLORTERM"))))
- @end lisp
- @item @code{authorized-keys} (default: @code{'()})
- @cindex authorized keys, SSH
- @cindex SSH authorized keys
- This is the list of authorized keys. Each element of the list is a user
- name followed by one or more file-like objects that represent SSH public
- keys. For example:
- @lisp
- (openssh-configuration
- (authorized-keys
- `(("rekado" ,(local-file "rekado.pub"))
- ("chris" ,(local-file "chris.pub"))
- ("root" ,(local-file "rekado.pub") ,(local-file "chris.pub")))))
- @end lisp
- @noindent
- registers the specified public keys for user accounts @code{rekado},
- @code{chris}, and @code{root}.
- Additional authorized keys can be specified @i{via}
- @code{service-extension}.
- Note that this does @emph{not} interfere with the use of
- @file{~/.ssh/authorized_keys}.
- @item @code{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 IPFS
- @defvr {Scheme Variable} ipfs-service-type
- The service type for connecting to the @uref{https://ipfs.io,IPFS network},
- a global, versioned, peer-to-peer file system. Pass it a
- @code{ipfs-configuration} to change the ports used for the gateway and API.
- Here's an example configuration, using some non-standard ports:
- @lisp
- (service ipfs-service-type
- (ipfs-configuration
- (gateway "/ip4/127.0.0.1/tcp/8880")
- (api "/ip4/127.0.0.1/tcp/8881")))
- @end lisp
- @end defvr
- @deftp {Data Type} ipfs-configuration
- Data type representing the configuration of IPFS.
- @table @asis
- @item @code{package} (default: @code{go-ipfs})
- Package object of IPFS.
- @item @code{gateway} (default: @code{"/ip4/127.0.0.1/tcp/8082"})
- Address of the gateway, in ‘multiaddress’ format.
- @item @code{api} (default: @code{"/ip4/127.0.0.1/tcp/5001"})
- Address of the API endpoint, in ‘multiaddress’ format.
- @end table
- @end deftp
- @cindex keepalived
- @deffn {Scheme Variable} keepalived-service-type
- This is the type for the @uref{https://www.keepalived.org/, Keepalived}
- routing software, @command{keepalived}. Its value must be an
- @code{keepalived-configuration} record as in this example for master
- machine:
- @lisp
- (service keepalived-service-type
- (keepalived-configuration
- (config-file (local-file "keepalived-master.conf"))))
- @end lisp
- where @file{keepalived-master.conf}:
- @example
- vrrp_instance my-group @{
- state MASTER
- interface enp9s0
- virtual_router_id 100
- priority 100
- unicast_peer @{ 10.0.0.2 @}
- virtual_ipaddress @{
- 10.0.0.4/24
- @}
- @}
- @end example
- and for backup machine:
- @lisp
- (service keepalived-service-type
- (keepalived-configuration
- (config-file (local-file "keepalived-backup.conf"))))
- @end lisp
- where @file{keepalived-backup.conf}:
- @example
- vrrp_instance my-group @{
- state BACKUP
- interface enp9s0
- virtual_router_id 100
- priority 99
- unicast_peer @{ 10.0.0.3 @}
- virtual_ipaddress @{
- 10.0.0.4/24
- @}
- @}
- @end example
- @end deffn
- @node Unattended Upgrades
- @subsection Unattended Upgrades
- @cindex unattended upgrades
- @cindex upgrades, unattended
- Guix provides a service to perform @emph{unattended upgrades}:
- periodically, the system automatically reconfigures itself from the
- latest Guix. Guix System has several properties that make unattended
- upgrades safe:
- @itemize
- @item
- upgrades are transactional (either the upgrade succeeds or it fails, but
- you cannot end up with an ``in-between'' system state);
- @item
- the upgrade log is kept---you can view it with @command{guix system
- list-generations}---and you can roll back to any previous generation,
- should the upgraded system fail to behave as intended;
- @item
- channel code is authenticated so you know you can only run genuine code
- (@pxref{Channels});
- @item
- @command{guix system reconfigure} prevents downgrades, which makes it
- immune to @dfn{downgrade attacks}.
- @end itemize
- To set up unattended upgrades, add an instance of
- @code{unattended-upgrade-service-type} like the one below to the list of
- your operating system services:
- @lisp
- (service unattended-upgrade-service-type)
- @end lisp
- The defaults above set up weekly upgrades: every Sunday at midnight.
- You do not need to provide the operating system configuration file: it
- uses @file{/run/current-system/configuration.scm}, which ensures it
- always uses your latest configuration---@pxref{provenance-service-type},
- for more information about this file.
- There are several things that can be configured, in particular the
- periodicity and services (daemons) to be restarted upon completion.
- When the upgrade is successful, the service takes care of deleting
- system generations older that some threshold, as per @command{guix
- system delete-generations}. See the reference below for details.
- To ensure that upgrades are actually happening, you can run
- @command{guix system describe}. To investigate upgrade failures, visit
- the unattended upgrade log file (see below).
- @defvr {Scheme Variable} unattended-upgrade-service-type
- This is the service type for unattended upgrades. It sets up an mcron
- job (@pxref{Scheduled Job Execution}) that runs @command{guix system
- reconfigure} from the latest version of the specified channels.
- Its value must be a @code{unattended-upgrade-configuration} record (see
- below).
- @end defvr
- @deftp {Data Type} unattended-upgrade-configuration
- This data type represents the configuration of the unattended upgrade
- service. The following fields are available:
- @table @asis
- @item @code{schedule} (default: @code{"30 01 * * 0"})
- This is the schedule of upgrades, expressed as a gexp containing an
- mcron job schedule (@pxref{Guile Syntax, mcron job specifications,,
- mcron, GNU@tie{}mcron}).
- @item @code{channels} (default: @code{#~%default-channels})
- This gexp specifies the channels to use for the upgrade
- (@pxref{Channels}). By default, the tip of the official @code{guix}
- channel is used.
- @item @code{operating-system-file} (default: @code{"/run/current-system/configuration.scm"})
- This field specifies the operating system configuration file to use.
- The default is to reuse the config file of the current configuration.
- There are cases, though, where referring to
- @file{/run/current-system/configuration.scm} is not enough, for instance
- because that file refers to extra files (SSH public keys, extra
- configuration files, etc.) @i{via} @code{local-file} and similar
- constructs. For those cases, we recommend something along these lines:
- @lisp
- (unattended-upgrade-configuration
- (operating-system-file
- (file-append (local-file "." "config-dir" #:recursive? #t)
- "/config.scm")))
- @end lisp
- The effect here is to import all of the current directory into the
- store, and to refer to @file{config.scm} within that directory.
- Therefore, uses of @code{local-file} within @file{config.scm} will work
- as expected. @xref{G-Expressions}, for information about
- @code{local-file} and @code{file-append}.
- @item @code{services-to-restart} (default: @code{'(mcron)})
- This field specifies the Shepherd services to restart when the upgrade
- completes.
- Those services are restarted right away upon completion, as with
- @command{herd restart}, which ensures that the latest version is
- running---remember that by default @command{guix system reconfigure}
- only restarts services that are not currently running, which is
- conservative: it minimizes disruption but leaves outdated services
- running.
- Use @command{herd status} to find out candidates for restarting.
- @xref{Services}, for general information about services. Common
- services to restart would include @code{ntpd} and @code{ssh-daemon}.
- By default, the @code{mcron} service is restarted. This ensures that
- the latest version of the unattended upgrade job will be used next time.
- @item @code{system-expiration} (default: @code{(* 3 30 24 3600)})
- This is the expiration time in seconds for system generations. System
- generations older that this amount of time are deleted with
- @command{guix system delete-generations} when an upgrade completes.
- @quotation Note
- The unattended upgrade service does not run the garbage collector. You
- will probably want to set up your own mcron job to run @command{guix gc}
- periodically.
- @end quotation
- @item @code{maximum-duration} (default: @code{3600})
- Maximum duration in seconds for the upgrade; past that time, the upgrade
- aborts.
- This is primarily useful to ensure the upgrade does not end up
- rebuilding or re-downloading ``the world''.
- @item @code{log-file} (default: @code{"/var/log/unattended-upgrade.log"})
- File where unattended upgrades are logged.
- @end table
- @end deftp
- @node X Window
- @subsection X Window
- @cindex X11
- @cindex X Window System
- @cindex login manager
- Support for the X Window graphical display system---specifically
- Xorg---is provided by the @code{(gnu services xorg)} module. Note that
- there is no @code{xorg-service} procedure. Instead, the X server is
- started by the @dfn{login manager}, by default the GNOME Display Manager (GDM).
- @cindex GDM
- @cindex GNOME, login manager
- GDM of course allows users to log in into window managers and desktop
- environments other than GNOME; for those using GNOME, GDM is required for
- features such as automatic screen locking.
- @cindex window manager
- To use X11, you must install at least one @dfn{window manager}---for
- example the @code{windowmaker} or @code{openbox} packages---preferably
- by adding it to the @code{packages} field of your operating system
- definition (@pxref{operating-system Reference, system-wide packages}).
- @anchor{wayland-gdm}
- GDM also supports Wayland: it can itself use Wayland instead of X11 for
- its user interface, and it can also start Wayland sessions. The former is
- required for the latter, to enable, set @code{wayland?} to @code{#t} in
- @code{gdm-configuration}.
- @defvr {Scheme Variable} gdm-service-type
- This is the type for the @uref{https://wiki.gnome.org/Projects/GDM/, GNOME
- Desktop Manager} (GDM), a program that manages graphical display servers and
- handles graphical user logins. Its value must be a @code{gdm-configuration}
- (see below).
- @cindex session types
- GDM looks for @dfn{session types} described by the @file{.desktop} files in
- @file{/run/current-system/profile/share/xsessions} (for X11 sessions) and
- @file{/run/current-system/profile/share/wayland-sessions} (for Wayland
- sessions) and allows users to choose a session from the log-in screen.
- Packages such as @code{gnome}, @code{xfce}, @code{i3} and @code{sway} provide
- @file{.desktop} files; adding them to the system-wide set of packages
- automatically makes them available at the log-in screen.
- In addition, @file{~/.xsession} files are honored. When available,
- @file{~/.xsession} must be an executable that starts a window manager
- and/or other X clients.
- @end defvr
- @deftp {Data Type} gdm-configuration
- @table @asis
- @item @code{auto-login?} (default: @code{#f})
- @itemx @code{default-user} (default: @code{#f})
- When @code{auto-login?} is false, GDM presents a log-in screen.
- When @code{auto-login?} is true, GDM logs in directly as
- @code{default-user}.
- @item @code{debug?} (default: @code{#f})
- When true, GDM writes debug messages to its log.
- @item @code{gnome-shell-assets} (default: ...)
- List of GNOME Shell assets needed by GDM: icon theme, fonts, etc.
- @item @code{xorg-configuration} (default: @code{(xorg-configuration)})
- Configuration of the Xorg graphical server.
- @item @code{xsession} (default: @code{(xinitrc)})
- Script to run before starting a X session.
- @item @code{dbus-daemon} (default: @code{dbus-daemon-wrapper})
- File name of the @code{dbus-daemon} executable.
- @item @code{gdm} (default: @code{gdm})
- The GDM package to use.
- @item @code{wayland?} (default: @code{#f})
- When true, enables Wayland in GDM, necessary to use Wayland sessions.
- @item @code{wayland-session} (default: @code{gdm-wayland-session-wrapper})
- The Wayland session wrapper to use, needed to setup the
- environment.
- @end table
- @end deftp
- @defvr {Scheme Variable} slim-service-type
- This is the type for the SLiM graphical login manager for X11.
- Like GDM, SLiM looks for session types described by @file{.desktop} files and
- allows users to choose a session from the log-in screen using @kbd{F1}. It
- also honors @file{~/.xsession} files.
- Unlike GDM, SLiM does not spawn the user session on a different VT after
- logging in, which means that you can only start one graphical session. If you
- want to be able to run multiple graphical sessions at the same time you have
- to add multiple SLiM services to your system services. The following example
- shows how to replace the default GDM service with two SLiM services on tty7
- and tty8.
- @lisp
- (use-modules (gnu services)
- (gnu services desktop)
- (gnu services xorg)
- (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")))
- (modify-services %desktop-services
- (delete gdm-service-type)))))
- @end lisp
- @end defvr
- @deftp {Data Type} slim-configuration
- Data type representing the configuration of @code{slim-service-type}.
- @table @asis
- @item @code{allow-empty-passwords?} (default: @code{#t})
- Whether to allow logins with empty passwords.
- @item @code{gnupg?} (default: @code{#f})
- If enabled, @code{pam-gnupg} will attempt to automatically unlock the
- user's GPG keys with the login password via @code{gpg-agent}. The
- keygrips of all keys to be unlocked should be written to
- @file{~/.pam-gnupg}, and can be queried with @code{gpg -K
- --with-keygrip}. Presetting passphrases must be enabled by adding
- @code{allow-preset-passphrase} in @file{~/.gnupg/gpg-agent.conf}.
- @item @code{auto-login?} (default: @code{#f})
- @itemx @code{default-user} (default: @code{""})
- When @code{auto-login?} is false, SLiM presents a log-in screen.
- When @code{auto-login?} is true, SLiM logs in directly as
- @code{default-user}.
- @item @code{theme} (default: @code{%default-slim-theme})
- @itemx @code{theme-name} (default: @code{%default-slim-theme-name})
- The graphical theme to use and its name.
- @item @code{auto-login-session} (default: @code{#f})
- If true, this must be the name of the executable to start as the default
- session---e.g., @code{(file-append windowmaker "/bin/windowmaker")}.
- If false, a session described by one of the available @file{.desktop}
- files in @code{/run/current-system/profile} and @code{~/.guix-profile}
- will be used.
- @quotation Note
- You must install at least one window manager in the system profile or in
- your user profile. Failing to do that, if @code{auto-login-session} is
- false, you will be unable to log in.
- @end quotation
- @item @code{xorg-configuration} (default @code{(xorg-configuration)})
- Configuration of the Xorg graphical server.
- @item @code{display} (default @code{":0"})
- The display on which to start the Xorg graphical server.
- @item @code{vt} (default @code{"vt7"})
- The VT on which to start the Xorg graphical server.
- @item @code{xauth} (default: @code{xauth})
- The XAuth package to use.
- @item @code{shepherd} (default: @code{shepherd})
- The Shepherd package used when invoking @command{halt} and
- @command{reboot}.
- @item @code{sessreg} (default: @code{sessreg})
- The sessreg package used in order to register the session.
- @item @code{slim} (default: @code{slim})
- The SLiM package to use.
- @end table
- @end deftp
- @defvr {Scheme Variable} %default-theme
- @defvrx {Scheme Variable} %default-theme-name
- The default SLiM theme and its name.
- @end defvr
- @deftp {Data Type} sddm-configuration
- This is the data type representing the SDDM service configuration.
- @table @asis
- @item @code{display-server} (default: "x11")
- Select display server to use for the greeter. Valid values are
- @samp{"x11"} or @samp{"wayland"}.
- @item @code{numlock} (default: "on")
- Valid values are @samp{"on"}, @samp{"off"} or @samp{"none"}.
- @item @code{halt-command} (default @code{#~(string-apppend #$shepherd "/sbin/halt")})
- Command to run when halting.
- @item @code{reboot-command} (default @code{#~(string-append #$shepherd "/sbin/reboot")})
- Command to run when rebooting.
- @item @code{theme} (default "maldives")
- Theme to use. Default themes provided by SDDM are @samp{"elarun"},
- @samp{"maldives"} or @samp{"maya"}.
- @item @code{themes-directory} (default "/run/current-system/profile/share/sddm/themes")
- Directory to look for themes.
- @item @code{faces-directory} (default "/run/current-system/profile/share/sddm/faces")
- Directory to look for faces.
- @item @code{default-path} (default "/run/current-system/profile/bin")
- Default PATH to use.
- @item @code{minimum-uid} (default: 1000)
- Minimum UID displayed in SDDM and allowed for log-in.
- @item @code{maximum-uid} (default: 2000)
- Maximum UID to display in SDDM.
- @item @code{remember-last-user?} (default #t)
- Remember last user.
- @item @code{remember-last-session?} (default #t)
- Remember last session.
- @item @code{hide-users} (default "")
- Usernames to hide from SDDM greeter.
- @item @code{hide-shells} (default @code{#~(string-append #$shadow "/sbin/nologin")})
- Users with shells listed will be hidden from the SDDM greeter.
- @item @code{session-command} (default @code{#~(string-append #$sddm "/share/sddm/scripts/wayland-session")})
- Script to run before starting a wayland session.
- @item @code{sessions-directory} (default "/run/current-system/profile/share/wayland-sessions")
- Directory to look for desktop files starting wayland sessions.
- @item @code{xorg-configuration} (default @code{(xorg-configuration)})
- Configuration of the Xorg graphical server.
- @item @code{xauth-path} (default @code{#~(string-append #$xauth "/bin/xauth")})
- Path to xauth.
- @item @code{xephyr-path} (default @code{#~(string-append #$xorg-server "/bin/Xephyr")})
- Path to Xephyr.
- @item @code{xdisplay-start} (default @code{#~(string-append #$sddm "/share/sddm/scripts/Xsetup")})
- Script to run after starting xorg-server.
- @item @code{xdisplay-stop} (default @code{#~(string-append #$sddm "/share/sddm/scripts/Xstop")})
- Script to run before stopping xorg-server.
- @item @code{xsession-command} (default: @code{xinitrc})
- Script to run before starting a X session.
- @item @code{xsessions-directory} (default: "/run/current-system/profile/share/xsessions")
- Directory to look for desktop files starting X sessions.
- @item @code{minimum-vt} (default: 7)
- Minimum VT to use.
- @item @code{auto-login-user} (default "")
- User to use for auto-login.
- @item @code{auto-login-session} (default "")
- Desktop file to use for auto-login.
- @item @code{relogin?} (default #f)
- Relogin after logout.
- @end table
- @end deftp
- @cindex login manager
- @cindex X11 login
- @defvr {Scheme Variable} sddm-service-type
- This is the type of the service to run the
- @uref{https://github.com/sddm/sddm,SDDM display manager}. Its value
- must be a @code{sddm-configuration} record (see below).
- Here's an example use:
- @lisp
- (service sddm-service-type
- (sddm-configuration
- (auto-login-user "alice")
- (auto-login-session "xfce.desktop")))
- @end lisp
- @end defvr
- @deftp {Data Type} sddm-configuration
- This data type represents the configuration of the SDDM login manager.
- The available fields are:
- @table @asis
- @item @code{sddm} (default: @code{sddm})
- The SDDM package to use.
- @item @code{display-server} (default: @code{"x11"})
- This must be either @code{"x11"} or @code{"wayland"}.
- @c FIXME: Add more fields.
- @item @code{auto-login-user} (default: @code{""})
- If non-empty, this is the user account under which to log in
- automatically.
- @item @code{auto-login-session} (default: @code{""})
- If non-empty, this is the @file{.desktop} file name to use as the
- auto-login session.
- @end table
- @end deftp
- @cindex Xorg, configuration
- @deftp {Data Type} xorg-configuration
- This data type represents the configuration of the Xorg graphical display
- server. Note that there is no Xorg service; instead, the X server is started
- by a ``display manager'' such as GDM, SDDM, and SLiM@. Thus, the configuration
- of these display managers aggregates an @code{xorg-configuration} record.
- @table @asis
- @item @code{modules} (default: @code{%default-xorg-modules})
- This is a list of @dfn{module packages} loaded by the Xorg
- server---e.g., @code{xf86-video-vesa}, @code{xf86-input-keyboard}, and so on.
- @item @code{fonts} (default: @code{%default-xorg-fonts})
- This is a list of font directories to add to the server's @dfn{font path}.
- @item @code{drivers} (default: @code{'()})
- This must be either the empty list, in which case Xorg chooses a graphics
- driver automatically, or a list of driver names that will be tried in this
- order---e.g., @code{("modesetting" "vesa")}.
- @item @code{resolutions} (default: @code{'()})
- When @code{resolutions} is the empty list, Xorg chooses an appropriate screen
- resolution. Otherwise, it must be a list of resolutions---e.g., @code{((1024
- 768) (640 480))}.
- @cindex keyboard layout, for Xorg
- @cindex keymap, for Xorg
- @item @code{keyboard-layout} (default: @code{#f})
- If this is @code{#f}, Xorg uses the default keyboard layout---usually US
- English (``qwerty'') for a 105-key PC keyboard.
- Otherwise this must be a @code{keyboard-layout} object specifying the keyboard
- layout in use when Xorg is running. @xref{Keyboard Layout}, for more
- information on how to specify the keyboard layout.
- @item @code{extra-config} (default: @code{'()})
- This is a list of strings or objects appended to the configuration file. It
- is used to pass extra text to be added verbatim to the configuration file.
- @item @code{server} (default: @code{xorg-server})
- This is the package providing the Xorg server.
- @item @code{server-arguments} (default: @code{%default-xorg-server-arguments})
- This is the list of command-line arguments to pass to the X server. The
- default is @code{-nolisten tcp}.
- @end table
- @end deftp
- @deffn {Scheme Procedure} set-xorg-configuration @var{config} @
- [@var{login-manager-service-type}]
- Tell the log-in manager (of type @var{login-manager-service-type}) to use
- @var{config}, an @code{<xorg-configuration>} record.
- Since the Xorg configuration is embedded in the log-in manager's
- configuration---e.g., @code{gdm-configuration}---this procedure provides a
- shorthand to set the Xorg configuration.
- @end deffn
- @deffn {Scheme Procedure} xorg-start-command [@var{config}]
- Return a @code{startx} script in which the modules, fonts, etc. specified
- in @var{config}, are available. The result should be used in place of
- @code{startx}.
- Usually the X server is started by a login manager.
- @end deffn
- @deffn {Scheme Procedure} screen-locker-service @var{package} [@var{program}]
- Add @var{package}, a package for a screen locker or screen saver whose
- command is @var{program}, to the set of setuid programs and add a PAM entry
- for it. For example:
- @lisp
- (screen-locker-service xlockmore "xlock")
- @end lisp
- makes the good ol' XlockMore usable.
- @end deffn
- @node Printing Services
- @subsection Printing Services
- @cindex printer support with CUPS
- The @code{(gnu services cups)} module provides a Guix service definition
- for the CUPS printing service. To add printer support to a Guix
- system, add a @code{cups-service} to the operating system definition:
- @deffn {Scheme Variable} cups-service-type
- The service type for the CUPS print server. Its value should be a valid
- CUPS configuration (see below). To use the default settings, simply
- write:
- @lisp
- (service cups-service-type)
- @end lisp
- @end deffn
- The CUPS configuration controls the basic things about your CUPS
- installation: what interfaces it listens on, what to do if a print job
- fails, how much logging to do, and so on. To actually add a printer,
- you have to visit the @url{http://localhost:631} URL, or use a tool such
- as GNOME's printer configuration services. By default, configuring a
- CUPS service will generate a self-signed certificate if needed, for
- secure connections to the print server.
- Suppose you want to enable the Web interface of CUPS and also add
- support for Epson printers @i{via} the @code{epson-inkjet-printer-escpr}
- package and for HP printers @i{via} the @code{hplip-minimal} package.
- You can do that directly, like this (you need to use the
- @code{(gnu packages cups)} module):
- @lisp
- (service cups-service-type
- (cups-configuration
- (web-interface? #t)
- (extensions
- (list cups-filters epson-inkjet-printer-escpr hplip-minimal))))
- @end lisp
- Note: If you wish to use the Qt5 based GUI which comes with the hplip
- package then it is suggested that you install the @code{hplip} package,
- either in your OS configuration file or as your user.
- The available configuration parameters follow. Each parameter
- definition is preceded by its type; for example, @samp{string-list foo}
- indicates that the @code{foo} parameter should be specified as a list of
- strings. There is also a way to specify the configuration as a string,
- if you have an old @code{cupsd.conf} file that you want to port over
- from some other system; see the end for more details.
- @c The following documentation was initially generated by
- @c (generate-documentation) in (gnu services cups). Manually maintained
- @c documentation is better, so we shouldn't hesitate to edit below as
- @c needed. However if the change you want to make to this documentation
- @c can be done in an automated way, it's probably easier to change
- @c (generate-documentation) than to make it below and have to deal with
- @c the churn as CUPS updates.
- Available @code{cups-configuration} fields are:
- @deftypevr {@code{cups-configuration} parameter} package cups
- The CUPS package.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} package-list extensions (default: @code{(list brlaser cups-filters epson-inkjet-printer-escpr foomatic-filters hplip-minimal splix)})
- Drivers and other extensions to the CUPS package.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} files-configuration files-configuration
- Configuration of where to write logs, what directories to use for print
- spools, and related privileged configuration parameters.
- Available @code{files-configuration} fields are:
- @deftypevr {@code{files-configuration} parameter} log-location access-log
- Defines the access log filename. Specifying a blank filename disables
- access log generation. The value @code{stderr} causes log entries to be
- sent to the standard error file when the scheduler is running in the
- foreground, or to the system log daemon when run in the background. The
- value @code{syslog} causes log entries to be sent to the system log
- daemon. The server name may be included in filenames using the string
- @code{%s}, as in @code{/var/log/cups/%s-access_log}.
- Defaults to @samp{"/var/log/cups/access_log"}.
- @end deftypevr
- @deftypevr {@code{files-configuration} parameter} file-name cache-dir
- Where CUPS should cache data.
- Defaults to @samp{"/var/cache/cups"}.
- @end deftypevr
- @deftypevr {@code{files-configuration} parameter} string config-file-perm
- Specifies the permissions for all configuration files that the scheduler
- writes.
- Note that the permissions for the printers.conf file are currently
- masked to only allow access from the scheduler user (typically root).
- This is done because printer device URIs sometimes contain sensitive
- authentication information that should not be generally known on the
- system. There is no way to disable this security feature.
- Defaults to @samp{"0640"}.
- @end deftypevr
- @deftypevr {@code{files-configuration} parameter} log-location error-log
- Defines the error log filename. Specifying a blank filename disables
- error log generation. The value @code{stderr} causes log entries to be
- sent to the standard error file when the scheduler is running in the
- foreground, or to the system log daemon when run in the background. The
- value @code{syslog} causes log entries to be sent to the system log
- daemon. The server name may be included in filenames using the string
- @code{%s}, as in @code{/var/log/cups/%s-error_log}.
- Defaults to @samp{"/var/log/cups/error_log"}.
- @end deftypevr
- @deftypevr {@code{files-configuration} parameter} string fatal-errors
- Specifies which errors are fatal, causing the scheduler to exit. The
- kind strings are:
- @table @code
- @item none
- No errors are fatal.
- @item all
- All of the errors below are fatal.
- @item browse
- Browsing initialization errors are fatal, for example failed connections
- to the DNS-SD daemon.
- @item config
- Configuration file syntax errors are fatal.
- @item listen
- Listen or Port errors are fatal, except for IPv6 failures on the
- loopback or @code{any} addresses.
- @item log
- Log file creation or write errors are fatal.
- @item permissions
- Bad startup file permissions are fatal, for example shared TLS
- certificate and key files with world-read permissions.
- @end table
- Defaults to @samp{"all -browse"}.
- @end deftypevr
- @deftypevr {@code{files-configuration} parameter} boolean file-device?
- Specifies whether the file pseudo-device can be used for new printer
- queues. The URI @uref{file:///dev/null} is always allowed.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{files-configuration} parameter} string group
- Specifies the group name or ID that will be used when executing external
- programs.
- Defaults to @samp{"lp"}.
- @end deftypevr
- @deftypevr {@code{files-configuration} parameter} string log-file-group
- Specifies the group name or ID that will be used for log files.
- Defaults to @samp{"lpadmin"}.
- @end deftypevr
- @deftypevr {@code{files-configuration} parameter} string log-file-perm
- Specifies the permissions for all log files that the scheduler writes.
- Defaults to @samp{"0644"}.
- @end deftypevr
- @deftypevr {@code{files-configuration} parameter} log-location page-log
- Defines the page log filename. Specifying a blank filename disables
- page log generation. The value @code{stderr} causes log entries to be
- sent to the standard error file when the scheduler is running in the
- foreground, or to the system log daemon when run in the background. The
- value @code{syslog} causes log entries to be sent to the system log
- daemon. The server name may be included in filenames using the string
- @code{%s}, as in @code{/var/log/cups/%s-page_log}.
- Defaults to @samp{"/var/log/cups/page_log"}.
- @end deftypevr
- @deftypevr {@code{files-configuration} parameter} string remote-root
- Specifies the username that is associated with unauthenticated accesses
- by clients claiming to be the root user. The default is @code{remroot}.
- Defaults to @samp{"remroot"}.
- @end deftypevr
- @deftypevr {@code{files-configuration} parameter} file-name request-root
- Specifies the directory that contains print jobs and other HTTP request
- data.
- Defaults to @samp{"/var/spool/cups"}.
- @end deftypevr
- @deftypevr {@code{files-configuration} parameter} sandboxing sandboxing
- Specifies the level of security sandboxing that is applied to print
- filters, backends, and other child processes of the scheduler; either
- @code{relaxed} or @code{strict}. This directive is currently only
- used/supported on macOS.
- Defaults to @samp{strict}.
- @end deftypevr
- @deftypevr {@code{files-configuration} parameter} file-name server-keychain
- Specifies the location of TLS certificates and private keys. CUPS will
- look for public and private keys in this directory: @file{.crt} files
- for PEM-encoded certificates and corresponding @file{.key} files for
- PEM-encoded private keys.
- Defaults to @samp{"/etc/cups/ssl"}.
- @end deftypevr
- @deftypevr {@code{files-configuration} parameter} file-name server-root
- Specifies the directory containing the server configuration files.
- Defaults to @samp{"/etc/cups"}.
- @end deftypevr
- @deftypevr {@code{files-configuration} parameter} boolean sync-on-close?
- Specifies whether the scheduler calls fsync(2) after writing
- configuration or state files.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{files-configuration} parameter} space-separated-string-list system-group
- Specifies the group(s) to use for @code{@@SYSTEM} group authentication.
- @end deftypevr
- @deftypevr {@code{files-configuration} parameter} file-name temp-dir
- Specifies the directory where temporary files are stored.
- Defaults to @samp{"/var/spool/cups/tmp"}.
- @end deftypevr
- @deftypevr {@code{files-configuration} parameter} string user
- Specifies the user name or ID that is used when running external
- programs.
- Defaults to @samp{"lp"}.
- @end deftypevr
- @deftypevr {@code{files-configuration} parameter} string set-env
- Set the specified environment variable to be passed to child processes.
- Defaults to @samp{"variable value"}.
- @end deftypevr
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} access-log-level access-log-level
- Specifies the logging level for the AccessLog file. The @code{config}
- level logs when printers and classes are added, deleted, or modified and
- when configuration files are accessed or updated. The @code{actions}
- level logs when print jobs are submitted, held, released, modified, or
- canceled, and any of the conditions for @code{config}. The @code{all}
- level logs all requests.
- Defaults to @samp{actions}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} boolean auto-purge-jobs?
- Specifies whether to purge job history data automatically when it is no
- longer required for quotas.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} comma-separated-string-list browse-dns-sd-sub-types
- Specifies a list of DNS-SD sub-types to advertise for each shared printer.
- For example, @samp{"_cups" "_print"} will tell network clients that both
- CUPS sharing and IPP Everywhere are supported.
- Defaults to @samp{"_cups"}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} browse-local-protocols browse-local-protocols
- Specifies which protocols to use for local printer sharing.
- Defaults to @samp{dnssd}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} boolean browse-web-if?
- Specifies whether the CUPS web interface is advertised.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} boolean browsing?
- Specifies whether shared printers are advertised.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} string classification
- Specifies the security classification of the server. Any valid banner
- name can be used, including @samp{"classified"}, @samp{"confidential"},
- @samp{"secret"}, @samp{"topsecret"}, and @samp{"unclassified"}, or the
- banner can be omitted to disable secure printing functions.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} boolean classify-override?
- Specifies whether users may override the classification (cover page) of
- individual print jobs using the @code{job-sheets} option.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} default-auth-type default-auth-type
- Specifies the default type of authentication to use.
- Defaults to @samp{Basic}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} default-encryption default-encryption
- Specifies whether encryption will be used for authenticated requests.
- Defaults to @samp{Required}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} string default-language
- Specifies the default language to use for text and web content.
- Defaults to @samp{"en"}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} string default-paper-size
- Specifies the default paper size for new print queues. @samp{"Auto"}
- uses a locale-specific default, while @samp{"None"} specifies there is
- no default paper size. Specific size names are typically
- @samp{"Letter"} or @samp{"A4"}.
- Defaults to @samp{"Auto"}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} string default-policy
- Specifies the default access policy to use.
- Defaults to @samp{"default"}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} boolean default-shared?
- Specifies whether local printers are shared by default.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} non-negative-integer dirty-clean-interval
- Specifies the delay for updating of configuration and state files, in
- seconds. A value of 0 causes the update to happen as soon as possible,
- typically within a few milliseconds.
- Defaults to @samp{30}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} error-policy error-policy
- Specifies what to do when an error occurs. Possible values are
- @code{abort-job}, which will discard the failed print job;
- @code{retry-job}, which will retry the job at a later time;
- @code{retry-current-job}, which retries the failed job immediately; and
- @code{stop-printer}, which stops the printer.
- Defaults to @samp{stop-printer}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} non-negative-integer filter-limit
- Specifies the maximum cost of filters that are run concurrently, which
- can be used to minimize disk, memory, and CPU resource problems. A
- limit of 0 disables filter limiting. An average print to a
- non-PostScript printer needs a filter limit of about 200. A PostScript
- printer needs about half that (100). Setting the limit below these
- thresholds will effectively limit the scheduler to printing a single job
- at any time.
- Defaults to @samp{0}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} non-negative-integer filter-nice
- Specifies the scheduling priority of filters that are run to print a
- job. The nice value ranges from 0, the highest priority, to 19, the
- lowest priority.
- Defaults to @samp{0}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} host-name-lookups host-name-lookups
- Specifies whether to do reverse lookups on connecting clients. The
- @code{double} setting causes @code{cupsd} to verify that the hostname
- resolved from the address matches one of the addresses returned for that
- hostname. Double lookups also prevent clients with unregistered
- addresses from connecting to your server. Only set this option to
- @code{#t} or @code{double} if absolutely required.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} non-negative-integer job-kill-delay
- Specifies the number of seconds to wait before killing the filters and
- backend associated with a canceled or held job.
- Defaults to @samp{30}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} non-negative-integer job-retry-interval
- Specifies the interval between retries of jobs in seconds. This is
- typically used for fax queues but can also be used with normal print
- queues whose error policy is @code{retry-job} or
- @code{retry-current-job}.
- Defaults to @samp{30}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} non-negative-integer job-retry-limit
- Specifies the number of retries that are done for jobs. This is
- typically used for fax queues but can also be used with normal print
- queues whose error policy is @code{retry-job} or
- @code{retry-current-job}.
- Defaults to @samp{5}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} boolean keep-alive?
- Specifies whether to support HTTP keep-alive connections.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} non-negative-integer limit-request-body
- Specifies the maximum size of print files, IPP requests, and HTML form
- data. A limit of 0 disables the limit check.
- Defaults to @samp{0}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} multiline-string-list listen
- Listens on the specified interfaces for connections. Valid values are
- of the form @var{address}:@var{port}, where @var{address} is either an
- IPv6 address enclosed in brackets, an IPv4 address, or @code{*} to
- indicate all addresses. Values can also be file names of local UNIX
- domain sockets. The Listen directive is similar to the Port directive
- but allows you to restrict access to specific interfaces or networks.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} non-negative-integer listen-back-log
- Specifies the number of pending connections that will be allowed. This
- normally only affects very busy servers that have reached the MaxClients
- limit, but can also be triggered by large numbers of simultaneous
- connections. When the limit is reached, the operating system will
- refuse additional connections until the scheduler can accept the pending
- ones.
- Defaults to @samp{128}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} location-access-control-list location-access-controls
- Specifies a set of additional access controls.
- Available @code{location-access-controls} fields are:
- @deftypevr {@code{location-access-controls} parameter} file-name path
- Specifies the URI path to which the access control applies.
- @end deftypevr
- @deftypevr {@code{location-access-controls} parameter} access-control-list access-controls
- Access controls for all access to this path, in the same format as the
- @code{access-controls} of @code{operation-access-control}.
- Defaults to @samp{()}.
- @end deftypevr
- @deftypevr {@code{location-access-controls} parameter} method-access-control-list method-access-controls
- Access controls for method-specific access to this path.
- Defaults to @samp{()}.
- Available @code{method-access-controls} fields are:
- @deftypevr {@code{method-access-controls} parameter} boolean reverse?
- If @code{#t}, apply access controls to all methods except the listed
- methods. Otherwise apply to only the listed methods.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{method-access-controls} parameter} method-list methods
- Methods to which this access control applies.
- Defaults to @samp{()}.
- @end deftypevr
- @deftypevr {@code{method-access-controls} parameter} access-control-list access-controls
- Access control directives, as a list of strings. Each string should be
- one directive, such as @samp{"Order allow,deny"}.
- Defaults to @samp{()}.
- @end deftypevr
- @end deftypevr
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} non-negative-integer log-debug-history
- Specifies the number of debugging messages that are retained for logging
- if an error occurs in a print job. Debug messages are logged regardless
- of the LogLevel setting.
- Defaults to @samp{100}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} log-level log-level
- Specifies the level of logging for the ErrorLog file. The value
- @code{none} stops all logging while @code{debug2} logs everything.
- Defaults to @samp{info}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} log-time-format log-time-format
- Specifies the format of the date and time in the log files. The value
- @code{standard} logs whole seconds while @code{usecs} logs microseconds.
- Defaults to @samp{standard}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} non-negative-integer max-clients
- Specifies the maximum number of simultaneous clients that are allowed by
- the scheduler.
- Defaults to @samp{100}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} non-negative-integer max-clients-per-host
- Specifies the maximum number of simultaneous clients that are allowed
- from a single address.
- Defaults to @samp{100}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} non-negative-integer max-copies
- Specifies the maximum number of copies that a user can print of each
- job.
- Defaults to @samp{9999}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} non-negative-integer max-hold-time
- Specifies the maximum time a job may remain in the @code{indefinite}
- hold state before it is canceled. A value of 0 disables cancellation of
- held jobs.
- Defaults to @samp{0}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} non-negative-integer max-jobs
- Specifies the maximum number of simultaneous jobs that are allowed. Set
- to 0 to allow an unlimited number of jobs.
- Defaults to @samp{500}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} non-negative-integer max-jobs-per-printer
- Specifies the maximum number of simultaneous jobs that are allowed per
- printer. A value of 0 allows up to MaxJobs jobs per printer.
- Defaults to @samp{0}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} non-negative-integer max-jobs-per-user
- Specifies the maximum number of simultaneous jobs that are allowed per
- user. A value of 0 allows up to MaxJobs jobs per user.
- Defaults to @samp{0}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} non-negative-integer max-job-time
- Specifies the maximum time a job may take to print before it is
- canceled, in seconds. Set to 0 to disable cancellation of ``stuck'' jobs.
- Defaults to @samp{10800}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} non-negative-integer max-log-size
- Specifies the maximum size of the log files before they are rotated, in
- bytes. The value 0 disables log rotation.
- Defaults to @samp{1048576}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} non-negative-integer multiple-operation-timeout
- Specifies the maximum amount of time to allow between files in a
- multiple file print job, in seconds.
- Defaults to @samp{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-configuration},
- which is reified into the @code{cups-files.conf(5)} file. Other
- possible elements of the access list include specific user names, and
- @code{@@@var{group}} to indicate members of a specific group. The
- access list may also be simply @code{all} or @code{default}.
- Defaults to @samp{"@@OWNER @@SYSTEM"}.
- @end deftypevr
- @deftypevr {@code{policy-configuration} parameter} string job-private-values
- Specifies the list of job values to make private, or @code{all},
- @code{default}, or @code{none}.
- Defaults to @samp{"job-name job-originating-host-name
- job-originating-user-name phone"}.
- @end deftypevr
- @deftypevr {@code{policy-configuration} parameter} string subscription-private-access
- Specifies an access list for a subscription's private values.
- @code{@@ACL} maps to the printer's requesting-user-name-allowed or
- requesting-user-name-denied values. @code{@@OWNER} maps to the job's
- owner. @code{@@SYSTEM} maps to the groups listed for the
- @code{system-group} field of the @code{files-configuration},
- which is reified into the @code{cups-files.conf(5)} file. Other
- possible elements of the access list include specific user names, and
- @code{@@@var{group}} to indicate members of a specific group. The
- access list may also be simply @code{all} or @code{default}.
- Defaults to @samp{"@@OWNER @@SYSTEM"}.
- @end deftypevr
- @deftypevr {@code{policy-configuration} parameter} string subscription-private-values
- Specifies the list of job values to make private, or @code{all},
- @code{default}, or @code{none}.
- Defaults to @samp{"notify-events notify-pull-method notify-recipient-uri
- notify-subscriber-user-name notify-user-data"}.
- @end deftypevr
- @deftypevr {@code{policy-configuration} parameter} operation-access-control-list access-controls
- Access control by IPP operation.
- Defaults to @samp{()}.
- @end deftypevr
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} boolean-or-non-negative-integer preserve-job-files
- Specifies whether job files (documents) are preserved after a job is
- printed. If a numeric value is specified, job files are preserved for
- the indicated number of seconds after printing. Otherwise a boolean
- value applies indefinitely.
- Defaults to @samp{86400}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} boolean-or-non-negative-integer preserve-job-history
- Specifies whether the job history is preserved after a job is printed.
- If a numeric value is specified, the job history is preserved for the
- indicated number of seconds after printing. If @code{#t}, the job
- history is preserved until the MaxJobs limit is reached.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} non-negative-integer reload-timeout
- Specifies the amount of time to wait for job completion before
- restarting the scheduler.
- Defaults to @samp{30}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} string rip-cache
- Specifies the maximum amount of memory to use when converting documents
- into bitmaps for a printer.
- Defaults to @samp{"128m"}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} string server-admin
- Specifies the email address of the server administrator.
- Defaults to @samp{"root@@localhost.localdomain"}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} host-name-list-or-* server-alias
- The ServerAlias directive is used for HTTP Host header validation when
- clients connect to the scheduler from external interfaces. Using the
- special name @code{*} can expose your system to known browser-based DNS
- rebinding attacks, even when accessing sites through a firewall. If the
- auto-discovery of alternate names does not work, we recommend listing
- each alternate name with a ServerAlias directive instead of using
- @code{*}.
- Defaults to @samp{*}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} string server-name
- Specifies the fully-qualified host name of the server.
- Defaults to @samp{"localhost"}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} server-tokens server-tokens
- Specifies what information is included in the Server header of HTTP
- responses. @code{None} disables the Server header. @code{ProductOnly}
- reports @code{CUPS}. @code{Major} reports @code{CUPS 2}. @code{Minor}
- reports @code{CUPS 2.0}. @code{Minimal} reports @code{CUPS 2.0.0}.
- @code{OS} reports @code{CUPS 2.0.0 (@var{uname})} where @var{uname} is
- the output of the @code{uname} command. @code{Full} reports @code{CUPS
- 2.0.0 (@var{uname}) IPP/2.0}.
- Defaults to @samp{Minimal}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} multiline-string-list ssl-listen
- Listens on the specified interfaces for encrypted connections. Valid
- values are of the form @var{address}:@var{port}, where @var{address} is
- either an IPv6 address enclosed in brackets, an IPv4 address, or
- @code{*} to indicate all addresses.
- Defaults to @samp{()}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} ssl-options ssl-options
- Sets encryption options. By default, CUPS only supports encryption
- using TLS v1.0 or higher using known secure cipher suites. Security is
- reduced when @code{Allow} options are used, and enhanced when @code{Deny}
- options are used. The @code{AllowRC4} option enables the 128-bit RC4 cipher
- suites, which are required for some older clients. The @code{AllowSSL3} option
- enables SSL v3.0, which is required for some older clients that do not support
- TLS v1.0. The @code{DenyCBC} option disables all CBC cipher suites. The
- @code{DenyTLS1.0} option disables TLS v1.0 support - this sets the minimum
- protocol version to TLS v1.1.
- Defaults to @samp{()}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} boolean strict-conformance?
- Specifies whether the scheduler requires clients to strictly adhere to
- the IPP specifications.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} non-negative-integer timeout
- Specifies the HTTP request timeout, in seconds.
- Defaults to @samp{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 enable Wayland support in GDM
- (@pxref{wayland-gdm}). Another solution is to use the
- @code{sddm-service} instead of GDM as the graphical login manager.
- You should then select the ``GNOME (Wayland)'' session in SDDM@.
- Alternatively you can also try starting GNOME on Wayland manually from a
- TTY with the command ``XDG_SESSION_TYPE=wayland exec dbus-run-session
- gnome-session``. Currently only GNOME has support for Wayland.
- @defvr {Scheme Variable} gnome-desktop-service-type
- This is the type of the service that adds the @uref{https://www.gnome.org,
- GNOME} desktop environment. Its value is a @code{gnome-desktop-configuration}
- object (see below).
- This service adds the @code{gnome} package to the system profile, and extends
- polkit with the actions from @code{gnome-settings-daemon}.
- @end defvr
- @deftp {Data Type} gnome-desktop-configuration
- Configuration record for the GNOME desktop environment.
- @table @asis
- @item @code{gnome} (default: @code{gnome})
- The GNOME package to use.
- @end table
- @end deftp
- @defvr {Scheme Variable} xfce-desktop-service-type
- This is the type of a service to run the @uref{Xfce, https://xfce.org/}
- desktop environment. Its value is an @code{xfce-desktop-configuration} object
- (see below).
- This service adds the @code{xfce} package to the system profile, and
- extends polkit with the ability for @code{thunar} to manipulate the file
- system as root from within a user session, after the user has authenticated
- with the administrator's password.
- Note that @code{xfce4-panel} and its plugin packages should be installed in
- the same profile to ensure compatibility. When using this service, you should
- add extra plugins (@code{xfce4-whiskermenu-plugin},
- @code{xfce4-weather-plugin}, etc.) to the @code{packages} field of your
- @code{operating-system}.
- @end defvr
- @deftp {Data Type} xfce-desktop-configuration
- Configuration record for the Xfce desktop environment.
- @table @asis
- @item @code{xfce} (default: @code{xfce})
- The Xfce package to use.
- @end table
- @end deftp
- @deffn {Scheme Variable} mate-desktop-service-type
- This is the type of the service that runs the @uref{https://mate-desktop.org/,
- MATE desktop environment}. Its value is a @code{mate-desktop-configuration}
- object (see below).
- This service adds the @code{mate} package to the system
- profile, and extends polkit with the actions from
- @code{mate-settings-daemon}.
- @end deffn
- @deftp {Data Type} mate-desktop-configuration
- Configuration record for the MATE desktop environment.
- @table @asis
- @item @code{mate} (default: @code{mate})
- The MATE package to use.
- @end table
- @end deftp
- @deffn {Scheme Variable} lxqt-desktop-service-type
- This is the type of the service that runs the @uref{https://lxqt-project.org,
- LXQt desktop environment}. Its value is a @code{lxqt-desktop-configuration}
- object (see below).
- This service adds the @code{lxqt} package to the system
- profile.
- @end deffn
- @deftp {Data Type} lxqt-desktop-configuration
- Configuration record for the LXQt desktop environment.
- @table @asis
- @item @code{lxqt} (default: @code{lxqt})
- The LXQT package to use.
- @end table
- @end deftp
- @deffn {Scheme Variable} enlightenment-desktop-service-type
- Return a service that adds the @code{enlightenment} package to the system
- profile, and extends dbus with actions from @code{efl}.
- @end deffn
- @deftp {Data Type} enlightenment-desktop-service-configuration
- @table @asis
- @item @code{enlightenment} (default: @code{enlightenment})
- The enlightenment package to use.
- @end table
- @end deftp
- Because the GNOME, Xfce and MATE desktop services pull in so many packages,
- the default @code{%desktop-services} variable doesn't include any of
- them by default. To add GNOME, Xfce or MATE, just @code{cons} them onto
- @code{%desktop-services} in the @code{services} field of your
- @code{operating-system}:
- @lisp
- (use-modules (gnu))
- (use-service-modules desktop)
- (operating-system
- ...
- ;; cons* adds items to the list given as its last argument.
- (services (cons* (service gnome-desktop-service-type)
- (service xfce-desktop-service)
- %desktop-services))
- ...)
- @end lisp
- These desktop environments will then be available as options in the
- graphical login window.
- The actual service definitions included in @code{%desktop-services} and
- provided by @code{(gnu services dbus)} and @code{(gnu services desktop)}
- are described below.
- @deffn {Scheme Procedure} dbus-service [#:dbus @var{dbus}] [#:services '()]
- Return a service that runs the ``system bus'', using @var{dbus}, with
- support for @var{services}.
- @uref{https://dbus.freedesktop.org/, D-Bus} is an inter-process communication
- facility. Its system bus is used to allow system services to communicate
- and to be notified of system-wide events.
- @var{services} must be a list of packages that provide an
- @file{etc/dbus-1/system.d} directory containing additional D-Bus configuration
- and policy files. For example, to allow avahi-daemon to use the system bus,
- @var{services} must be equal to @code{(list avahi)}.
- @end deffn
- @deffn {Scheme Procedure} elogind-service [#:config @var{config}]
- Return a service that runs the @code{elogind} login and
- seat management daemon. @uref{https://github.com/elogind/elogind,
- Elogind} exposes a D-Bus interface that can be used to know which users
- are logged in, know what kind of sessions they have open, suspend the
- system, inhibit system suspend, reboot the system, and other tasks.
- Elogind handles most system-level power events for a computer, for
- example suspending the system when a lid is closed, or shutting it down
- when the power button is pressed.
- The @var{config} keyword argument specifies the configuration for
- elogind, and should be the result of an @code{(elogind-configuration
- (@var{parameter} @var{value})...)} invocation. Available parameters and
- their default values are:
- @table @code
- @item kill-user-processes?
- @code{#f}
- @item kill-only-users
- @code{()}
- @item kill-exclude-users
- @code{("root")}
- @item inhibit-delay-max-seconds
- @code{5}
- @item handle-power-key
- @code{poweroff}
- @item handle-suspend-key
- @code{suspend}
- @item handle-hibernate-key
- @code{hibernate}
- @item handle-lid-switch
- @code{suspend}
- @item handle-lid-switch-docked
- @code{ignore}
- @item handle-lid-switch-external-power
- @code{ignore}
- @item power-key-ignore-inhibited?
- @code{#f}
- @item suspend-key-ignore-inhibited?
- @code{#f}
- @item hibernate-key-ignore-inhibited?
- @code{#f}
- @item lid-switch-ignore-inhibited?
- @code{#t}
- @item holdoff-timeout-seconds
- @code{30}
- @item idle-action
- @code{ignore}
- @item idle-action-seconds
- @code{(* 30 60)}
- @item runtime-directory-size-percent
- @code{10}
- @item runtime-directory-size
- @code{#f}
- @item remove-ipc?
- @code{#t}
- @item suspend-state
- @code{("mem" "standby" "freeze")}
- @item suspend-mode
- @code{()}
- @item hibernate-state
- @code{("disk")}
- @item hibernate-mode
- @code{("platform" "shutdown")}
- @item hybrid-sleep-state
- @code{("disk")}
- @item hybrid-sleep-mode
- @code{("suspend" "platform" "shutdown")}
- @end table
- @end deffn
- @deffn {Scheme Procedure} accountsservice-service @
- [#:accountsservice @var{accountsservice}]
- Return a service that runs AccountsService, a system service that can
- list available accounts, change their passwords, and so on.
- AccountsService integrates with PolicyKit to enable unprivileged users
- to acquire the capability to modify their system configuration.
- @uref{https://www.freedesktop.org/wiki/Software/AccountsService/, the
- accountsservice web site} for more information.
- The @var{accountsservice} keyword argument is the @code{accountsservice}
- package to expose as a service.
- @end deffn
- @deffn {Scheme Procedure} polkit-service @
- [#:polkit @var{polkit}]
- Return a service that runs the
- @uref{https://www.freedesktop.org/wiki/Software/polkit/, Polkit privilege
- management service}, which allows system administrators to grant access to
- privileged operations in a structured way. By querying the Polkit service, a
- privileged system component can know when it should grant additional
- capabilities to ordinary users. For example, an ordinary user can be granted
- the capability to suspend the system if the user is logged in locally.
- @end deffn
- @defvr {Scheme Variable} polkit-wheel-service
- Service that adds the @code{wheel} group as admins to the Polkit
- service. This makes it so that users in the @code{wheel} group are queried
- for their own passwords when performing administrative actions instead of
- @code{root}'s, similar to the behaviour used by @code{sudo}.
- @end defvr
- @defvr {Scheme Variable} upower-service-type
- Service that runs @uref{https://upower.freedesktop.org/, @command{upowerd}}, a
- system-wide monitor for power consumption and battery levels, with the given
- configuration settings.
- It implements the @code{org.freedesktop.UPower} D-Bus interface, and is
- notably used by GNOME.
- @end defvr
- @deftp {Data Type} upower-configuration
- Data type representation the configuration for UPower.
- @table @asis
- @item @code{upower} (default: @var{upower})
- Package to use for @code{upower}.
- @item @code{watts-up-pro?} (default: @code{#f})
- Enable the Watts Up Pro device.
- @item @code{poll-batteries?} (default: @code{#t})
- Enable polling the kernel for battery level changes.
- @item @code{ignore-lid?} (default: @code{#f})
- Ignore the lid state, this can be useful if it's incorrect on a device.
- @item @code{use-percentage-for-policy?} (default: @code{#f})
- Whether battery percentage based policy should be used. The default is to use
- the time left, change to @code{#t} to use the percentage.
- @item @code{percentage-low} (default: @code{10})
- When @code{use-percentage-for-policy?} is @code{#t}, this sets the percentage
- at which the battery is considered low.
- @item @code{percentage-critical} (default: @code{3})
- When @code{use-percentage-for-policy?} is @code{#t}, this sets the percentage
- at which the battery is considered critical.
- @item @code{percentage-action} (default: @code{2})
- When @code{use-percentage-for-policy?} is @code{#t}, this sets the percentage
- at which action will be taken.
- @item @code{time-low} (default: @code{1200})
- When @code{use-time-for-policy?} is @code{#f}, this sets the time remaining in
- seconds at which the battery is considered low.
- @item @code{time-critical} (default: @code{300})
- When @code{use-time-for-policy?} is @code{#f}, this sets the time remaining in
- seconds at which the battery is considered critical.
- @item @code{time-action} (default: @code{120})
- When @code{use-time-for-policy?} is @code{#f}, this sets the time remaining in
- seconds at which action will be taken.
- @item @code{critical-power-action} (default: @code{'hybrid-sleep})
- The action taken when @code{percentage-action} or @code{time-action} is
- reached (depending on the configuration of @code{use-percentage-for-policy?}).
- Possible values are:
- @itemize @bullet
- @item
- @code{'power-off}
- @item
- @code{'hibernate}
- @item
- @code{'hybrid-sleep}.
- @end itemize
- @end table
- @end deftp
- @deffn {Scheme Procedure} udisks-service [#:udisks @var{udisks}]
- Return a service for @uref{https://udisks.freedesktop.org/docs/latest/,
- UDisks}, a @dfn{disk management} daemon that provides user interfaces
- with notifications and ways to mount/unmount disks. Programs that talk
- to UDisks include the @command{udisksctl} command, part of UDisks, and
- GNOME Disks. Note that Udisks relies on the @command{mount} command, so
- it will only be able to use the file-system utilities installed in the
- system profile. For example if you want to be able to mount NTFS
- file-systems in read and write fashion, you'll need to have
- @code{ntfs-3g} installed system-wide.
- @end deffn
- @deffn {Scheme Variable} colord-service-type
- This is the type of the service that runs @command{colord}, a system
- service with a D-Bus
- interface to manage the color profiles of input and output devices such as
- screens and scanners. It is notably used by the GNOME Color Manager graphical
- tool. See @uref{https://www.freedesktop.org/software/colord/, the colord web
- site} for more information.
- @end deffn
- @cindex scanner access
- @defvr {Scheme Variable} sane-service-type
- This service provides access to scanners @i{via}
- @uref{http://www.sane-project.org, SANE} by installing the necessary
- udev rules. It is included in @code{%desktop-services} (@pxref{Desktop
- Services}) and relies by default on @code{sane-backends-minimal} package
- (see below) for hardware support.
- @end defvr
- @defvr {Scheme Variable} sane-backends-minimal
- The default package which the @code{sane-service-type} installs. It
- supports many recent scanners.
- @end defvr
- @defvr {Scheme Variable} sane-backends
- This package includes support for all scanners that
- @code{sane-backends-minimal} supports, plus older Hewlett-Packard
- scanners supported by @code{hplip} package. In order to use this on
- a system which relies on @code{%desktop-services}, you may use
- @code{modify-services} (@pxref{Service Reference,
- @code{modify-services}}) as illustrated below:
- @lisp
- (use-modules (gnu))
- (use-service-modules
- @dots{}
- desktop)
- (use-package-modules
- @dots{}
- scanner)
- (define %my-desktop-services
- ;; List of desktop services that supports a broader range of scanners.
- (modify-services %desktop-services
- (sane-service-type _ => sane-backends)))
- (operating-system
- @dots{}
- (services %my-desktop-services)
- @end lisp
- @end defvr
- @deffn {Scheme Procedure} geoclue-application name [#:allowed? #t] [#:system? #f] [#:users '()]
- Return a configuration allowing an application to access GeoClue
- location data. @var{name} is the Desktop ID of the application, without
- the @code{.desktop} part. If @var{allowed?} is true, the application
- will have access to location information by default. The boolean
- @var{system?} value indicates whether an application is a system component
- or not. Finally @var{users} is a list of UIDs of all users for which
- this application is allowed location info access. An empty users list
- means that all users are allowed.
- @end deffn
- @defvr {Scheme Variable} %standard-geoclue-applications
- The standard list of well-known GeoClue application configurations,
- granting authority to the GNOME date-and-time utility to ask for the
- current location in order to set the time zone, and allowing the
- IceCat and Epiphany web browsers to request location information.
- IceCat and Epiphany both query the user before allowing a web page to
- know the user's location.
- @end defvr
- @deffn {Scheme Procedure} geoclue-service [#:colord @var{colord}] @
- [#:whitelist '()] @
- [#:wifi-geolocation-url "https://location.services.mozilla.com/v1/geolocate?key=geoclue"] @
- [#:submit-data? #f]
- [#:wifi-submission-url "https://location.services.mozilla.com/v1/submit?key=geoclue"] @
- [#:submission-nick "geoclue"] @
- [#:applications %standard-geoclue-applications]
- Return a service that runs the GeoClue location service. This service
- provides a D-Bus interface to allow applications to request access to a
- user's physical location, and optionally to add information to online
- location databases. See
- @uref{https://wiki.freedesktop.org/www/Software/GeoClue/, the GeoClue
- web site} for more information.
- @end deffn
- @deffn {Scheme Procedure} bluetooth-service [#:bluez @var{bluez}] @
- [@w{#:auto-enable? #f}]
- Return a service that runs the @command{bluetoothd} daemon, which
- manages all the Bluetooth devices and provides a number of D-Bus
- interfaces. When AUTO-ENABLE? is true, the bluetooth controller is
- powered automatically at boot, which can be useful when using a
- bluetooth keyboard or mouse.
- Users need to be in the @code{lp} group to access the D-Bus service.
- @end deffn
- @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{""} PostgreSQL does not listen on any Unix-domain sockets, in
- which case only TCP/IP sockets can be used to connect to the server.
- By default, the @code{#false} value means the PostgreSQL default value
- will be used, which is currently @samp{/tmp}.
- @item @code{extra-config} (default: @code{'()})
- List of additional keys and values to include in the PostgreSQL config
- file. Each entry in the list should be a list where the first element
- is the key, and the remaining elements are the values.
- The values can be numbers, booleans or strings and will be mapped to
- PostgreSQL parameters types @code{Boolean}, @code{String},
- @code{Numeric}, @code{Numeric with Unit} and @code{Enumerated} described
- @uref{https://www.postgresql.org/docs/current/config-setting.html,
- here}.
- @end table
- @end deftp
- @deffn {Scheme Variable} postgresql-role-service-type
- This service allows to create PostgreSQL roles and databases after
- PostgreSQL service start. Here is an example of its use.
- @lisp
- (service postgresql-role-service-type
- (postgresql-role-configuration
- (roles
- (list (postgresql-role
- (name "test")
- (create-database? #t))))))
- @end lisp
- This service can be extended with extra roles, as in this
- example:
- @lisp
- (service-extension postgresql-role-service-type
- (const (postgresql-role
- (name "alice")
- (create-database? #t))))
- @end lisp
- @end deffn
- @deftp {Data Type} postgresql-role
- PostgreSQL manages database access permissions using the concept of
- roles. A role can be thought of as either a database user, or a group
- of database users, depending on how the role is set up. Roles can own
- database objects (for example, tables) and can assign privileges on
- those objects to other roles to control who has access to which objects.
- @table @asis
- @item @code{name}
- The role name.
- @item @code{permissions} (default: @code{'(createdb login)})
- The role permissions list. Supported permissions are @code{bypassrls},
- @code{createdb}, @code{createrole}, @code{login}, @code{replication} and
- @code{superuser}.
- @item @code{create-database?} (default: @code{#f})
- Whether to create a database with the same name as the role.
- @end table
- @end deftp
- @deftp {Data Type} postgresql-role-configuration
- Data type representing the configuration of
- @var{postgresql-role-service-type}.
- @table @asis
- @item @code{host} (default: @code{"/var/run/postgresql"})
- The PostgreSQL host to connect to.
- @item @code{log} (default: @code{"/var/log/postgresql_roles.log"})
- File name of the log file.
- @item @code{roles} (default: @code{'()})
- The initial PostgreSQL roles to create.
- @end table
- @end deftp
- @subsubheading MariaDB/MySQL
- @defvr {Scheme Variable} mysql-service-type
- This is the service type for a MySQL or MariaDB database server. Its value
- is a @code{mysql-configuration} object that specifies which package to use,
- as well as various settings for the @command{mysqld} daemon.
- @end defvr
- @deftp {Data Type} mysql-configuration
- Data type representing the configuration of @var{mysql-service-type}.
- @table @asis
- @item @code{mysql} (default: @var{mariadb})
- Package object of the MySQL database server, can be either @var{mariadb}
- or @var{mysql}.
- For MySQL, a temporary root password will be displayed at activation time.
- For MariaDB, the root password is empty.
- @item @code{bind-address} (default: @code{"127.0.0.1"})
- The IP on which to listen for network connections. Use @code{"0.0.0.0"}
- to bind to all available network interfaces.
- @item @code{port} (default: @code{3306})
- TCP port on which the database server listens for incoming connections.
- @item @code{socket} (default: @code{"/run/mysqld/mysqld.sock"})
- Socket file to use for local (non-network) connections.
- @item @code{extra-content} (default: @code{""})
- Additional settings for the @file{my.cnf} configuration file.
- @item @code{extra-environment} (default: @code{#~'()})
- List of environment variables passed to the @command{mysqld} process.
- @item @code{auto-upgrade?} (default: @code{#t})
- Whether to automatically run @command{mysql_upgrade} after starting the
- service. This is necessary to upgrade the @dfn{system schema} after
- ``major'' updates (such as switching from MariaDB 10.4 to 10.5), but can
- be disabled if you would rather do that manually.
- @end table
- @end deftp
- @subsubheading Memcached
- @defvr {Scheme Variable} memcached-service-type
- This is the service type for the @uref{https://memcached.org/,
- Memcached} service, which provides a distributed in memory cache. The
- value for the service type is a @code{memcached-configuration} object.
- @end defvr
- @lisp
- (service memcached-service-type)
- @end lisp
- @deftp {Data Type} memcached-configuration
- Data type representing the configuration of memcached.
- @table @asis
- @item @code{memcached} (default: @code{memcached})
- The Memcached package to use.
- @item @code{interfaces} (default: @code{'("0.0.0.0")})
- Network interfaces on which to listen.
- @item @code{tcp-port} (default: @code{11211})
- Port on which to accept connections.
- @item @code{udp-port} (default: @code{11211})
- Port on which to accept UDP connections on, a value of 0 will disable
- listening on a UDP socket.
- @item @code{additional-options} (default: @code{'()})
- Additional command line options to pass to @code{memcached}.
- @end table
- @end deftp
- @subsubheading Redis
- @defvr {Scheme Variable} redis-service-type
- This is the service type for the @uref{https://redis.io/, Redis}
- key/value store, whose value is a @code{redis-configuration} object.
- @end defvr
- @deftp {Data Type} redis-configuration
- Data type representing the configuration of redis.
- @table @asis
- @item @code{redis} (default: @code{redis})
- The Redis package to use.
- @item @code{bind} (default: @code{"127.0.0.1"})
- Network interface on which to listen.
- @item @code{port} (default: @code{6379})
- Port on which to accept connections on, a value of 0 will disable
- listening on a TCP socket.
- @item @code{working-directory} (default: @code{"/var/lib/redis"})
- Directory in which to store the database and related files.
- @end table
- @end deftp
- @node Mail Services
- @subsection Mail Services
- @cindex mail
- @cindex email
- The @code{(gnu services mail)} module provides Guix service definitions
- for email services: IMAP, POP3, and LMTP servers, as well as mail
- transport agents (MTAs). Lots of acronyms! These services are detailed
- in the subsections below.
- @subsubheading Dovecot Service
- @deffn {Scheme Procedure} dovecot-service [#:config (dovecot-configuration)]
- Return a service that runs the Dovecot IMAP/POP3/LMTP mail server.
- @end deffn
- By default, Dovecot does not need much configuration; the default
- configuration object created by @code{(dovecot-configuration)} will
- suffice if your mail is delivered to @code{~/Maildir}. A self-signed
- certificate will be generated for TLS-protected connections, though
- Dovecot will also listen on cleartext ports by default. There are a
- number of options, though, which mail administrators might need to change,
- and as is the case with other services, Guix allows the system
- administrator to specify these parameters via a uniform Scheme interface.
- For example, to specify that mail is located at @code{maildir~/.mail},
- one would instantiate the Dovecot service like this:
- @lisp
- (dovecot-service #:config
- (dovecot-configuration
- (mail-location "maildir:~/.mail")))
- @end lisp
- The available configuration parameters follow. Each parameter
- definition is preceded by its type; for example, @samp{string-list foo}
- indicates that the @code{foo} parameter should be specified as a list of
- strings. There is also a way to specify the configuration as a string,
- if you have an old @code{dovecot.conf} file that you want to port over
- from some other system; see the end for more details.
- @c The following documentation was initially generated by
- @c (generate-documentation) in (gnu services mail). Manually maintained
- @c documentation is better, so we shouldn't hesitate to edit below as
- @c needed. However if the change you want to make to this documentation
- @c can be done in an automated way, it's probably easier to change
- @c (generate-documentation) than to make it below and have to deal with
- @c the churn as dovecot updates.
- Available @code{dovecot-configuration} fields are:
- @deftypevr {@code{dovecot-configuration} parameter} package dovecot
- The dovecot package.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} comma-separated-string-list listen
- A list of IPs or hosts where to listen for connections. @samp{*}
- listens on all IPv4 interfaces, @samp{::} listens on all IPv6
- interfaces. If you want to specify non-default ports or anything more
- complex, customize the address and port fields of the
- @samp{inet-listener} of the specific services you are interested in.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} protocol-configuration-list protocols
- List of protocols we want to serve. Available protocols include
- @samp{imap}, @samp{pop3}, and @samp{lmtp}.
- Available @code{protocol-configuration} fields are:
- @deftypevr {@code{protocol-configuration} parameter} string name
- The name of the protocol.
- @end deftypevr
- @deftypevr {@code{protocol-configuration} parameter} string auth-socket-path
- UNIX socket path to the master authentication server to find users.
- This is used by imap (for shared users) and lda.
- It defaults to @samp{"/var/run/dovecot/auth-userdb"}.
- @end deftypevr
- @deftypevr {@code{protocol-configuration} parameter} boolean imap-metadata?
- Whether to enable the @code{IMAP METADATA} extension as defined in
- @uref{https://tools.ietf.org/html/rfc5464,RFC@tie{}5464}, which provides
- a means for clients to set and retrieve per-mailbox, per-user metadata
- and annotations over IMAP.
- If this is @samp{#t}, you must also specify a dictionary @i{via} the
- @code{mail-attribute-dict} setting.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{protocol-configuration} parameter} space-separated-string-list managesieve-notify-capabilities
- Which NOTIFY capabilities to report to clients that first connect to
- the ManageSieve service, before authentication. These may differ from the
- capabilities offered to authenticated users. If this field is left empty,
- report what the Sieve interpreter supports by default.
- Defaults to @samp{()}.
- @end deftypevr
- @deftypevr {@code{protocol-configuration} parameter} space-separated-string-list managesieve-sieve-capability
- Which SIEVE capabilities to report to clients that first connect to
- the ManageSieve service, before authentication. These may differ from the
- capabilities offered to authenticated users. If this field is left empty,
- report what the Sieve interpreter supports by default.
- Defaults to @samp{()}.
- @end deftypevr
- @deftypevr {@code{protocol-configuration} parameter} space-separated-string-list mail-plugins
- Space separated list of plugins to load.
- @end deftypevr
- @deftypevr {@code{protocol-configuration} parameter} non-negative-integer mail-max-userip-connections
- Maximum number of IMAP connections allowed for a user from each IP
- address. NOTE: The username is compared case-sensitively.
- Defaults to @samp{10}.
- @end deftypevr
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} service-configuration-list services
- List of services to enable. Available services include @samp{imap},
- @samp{imap-login}, @samp{pop3}, @samp{pop3-login}, @samp{auth}, and
- @samp{lmtp}.
- Available @code{service-configuration} fields are:
- @deftypevr {@code{service-configuration} parameter} string kind
- The service kind. Valid values include @code{director},
- @code{imap-login}, @code{pop3-login}, @code{lmtp}, @code{imap},
- @code{pop3}, @code{auth}, @code{auth-worker}, @code{dict},
- @code{tcpwrap}, @code{quota-warning}, or anything else.
- @end deftypevr
- @deftypevr {@code{service-configuration} parameter} listener-configuration-list listeners
- Listeners for the service. A listener is either a
- @code{unix-listener-configuration}, a @code{fifo-listener-configuration}, or
- an @code{inet-listener-configuration}.
- Defaults to @samp{()}.
- Available @code{unix-listener-configuration} fields are:
- @deftypevr {@code{unix-listener-configuration} parameter} string path
- Path to the file, relative to @code{base-dir} field. This is also used as
- the section name.
- @end deftypevr
- @deftypevr {@code{unix-listener-configuration} parameter} string mode
- The access mode for the socket.
- Defaults to @samp{"0600"}.
- @end deftypevr
- @deftypevr {@code{unix-listener-configuration} parameter} string user
- The user to own the socket.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{unix-listener-configuration} parameter} string group
- The group to own the socket.
- Defaults to @samp{""}.
- @end deftypevr
- Available @code{fifo-listener-configuration} fields are:
- @deftypevr {@code{fifo-listener-configuration} parameter} string path
- Path to the file, relative to @code{base-dir} field. This is also used as
- the section name.
- @end deftypevr
- @deftypevr {@code{fifo-listener-configuration} parameter} string mode
- The access mode for the socket.
- Defaults to @samp{"0600"}.
- @end deftypevr
- @deftypevr {@code{fifo-listener-configuration} parameter} string user
- The user to own the socket.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{fifo-listener-configuration} parameter} string group
- The group to own the socket.
- Defaults to @samp{""}.
- @end deftypevr
- Available @code{inet-listener-configuration} fields are:
- @deftypevr {@code{inet-listener-configuration} parameter} string protocol
- The protocol to listen for.
- @end deftypevr
- @deftypevr {@code{inet-listener-configuration} parameter} string address
- The address on which to listen, or empty for all addresses.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{inet-listener-configuration} parameter} non-negative-integer port
- The port on which to listen.
- @end deftypevr
- @deftypevr {@code{inet-listener-configuration} parameter} boolean ssl?
- Whether to use SSL for this service; @samp{yes}, @samp{no}, or
- @samp{required}.
- Defaults to @samp{#t}.
- @end deftypevr
- @end deftypevr
- @deftypevr {@code{service-configuration} parameter} non-negative-integer client-limit
- Maximum number of simultaneous client connections per process. Once
- this number of connections is received, the next incoming connection
- will prompt Dovecot to spawn another process. If set to 0,
- @code{default-client-limit} is used instead.
- Defaults to @samp{0}.
- @end deftypevr
- @deftypevr {@code{service-configuration} parameter} non-negative-integer service-count
- Number of connections to handle before starting a new process.
- Typically the only useful values are 0 (unlimited) or 1. 1 is more
- secure, but 0 is faster. <doc/wiki/LoginProcess.txt>.
- Defaults to @samp{1}.
- @end deftypevr
- @deftypevr {@code{service-configuration} parameter} non-negative-integer process-limit
- Maximum number of processes that can exist for this service. If set to
- 0, @code{default-process-limit} is used instead.
- Defaults to @samp{0}.
- @end deftypevr
- @deftypevr {@code{service-configuration} parameter} non-negative-integer process-min-avail
- Number of processes to always keep waiting for more connections.
- Defaults to @samp{0}.
- @end deftypevr
- @deftypevr {@code{service-configuration} parameter} non-negative-integer vsz-limit
- If you set @samp{service-count 0}, you probably need to grow
- this.
- Defaults to @samp{256000000}.
- @end deftypevr
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} dict-configuration dict
- Dict configuration, as created by the @code{dict-configuration}
- constructor.
- Available @code{dict-configuration} fields are:
- @deftypevr {@code{dict-configuration} parameter} free-form-fields entries
- A list of key-value pairs that this dict should hold.
- Defaults to @samp{()}.
- @end deftypevr
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} passdb-configuration-list passdbs
- A list of passdb configurations, each one created by the
- @code{passdb-configuration} constructor.
- Available @code{passdb-configuration} fields are:
- @deftypevr {@code{passdb-configuration} parameter} string driver
- The driver that the passdb should use. Valid values include
- @samp{pam}, @samp{passwd}, @samp{shadow}, @samp{bsdauth}, and
- @samp{static}.
- Defaults to @samp{"pam"}.
- @end deftypevr
- @deftypevr {@code{passdb-configuration} parameter} space-separated-string-list args
- Space separated list of arguments to the passdb driver.
- Defaults to @samp{""}.
- @end deftypevr
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} userdb-configuration-list userdbs
- List of userdb configurations, each one created by the
- @code{userdb-configuration} constructor.
- Available @code{userdb-configuration} fields are:
- @deftypevr {@code{userdb-configuration} parameter} string driver
- The driver that the userdb should use. Valid values include
- @samp{passwd} and @samp{static}.
- Defaults to @samp{"passwd"}.
- @end deftypevr
- @deftypevr {@code{userdb-configuration} parameter} space-separated-string-list args
- Space separated list of arguments to the userdb driver.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{userdb-configuration} parameter} free-form-args override-fields
- Override fields from passwd.
- Defaults to @samp{()}.
- @end deftypevr
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} plugin-configuration plugin-configuration
- Plug-in configuration, created by the @code{plugin-configuration}
- constructor.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} list-of-namespace-configuration namespaces
- List of namespaces. Each item in the list is created by the
- @code{namespace-configuration} constructor.
- Available @code{namespace-configuration} fields are:
- @deftypevr {@code{namespace-configuration} parameter} string name
- Name for this namespace.
- @end deftypevr
- @deftypevr {@code{namespace-configuration} parameter} string type
- Namespace type: @samp{private}, @samp{shared} or @samp{public}.
- Defaults to @samp{"private"}.
- @end deftypevr
- @deftypevr {@code{namespace-configuration} parameter} string separator
- Hierarchy separator to use. You should use the same separator for
- all namespaces or some clients get confused. @samp{/} is usually a good
- one. The default however depends on the underlying mail storage
- format.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{namespace-configuration} parameter} string prefix
- Prefix required to access this namespace. This needs to be
- different for all namespaces. For example @samp{Public/}.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{namespace-configuration} parameter} string location
- Physical location of the mailbox. This is in the same format as
- mail_location, which is also the default for it.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{namespace-configuration} parameter} boolean inbox?
- There can be only one INBOX, and this setting defines which
- namespace has it.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{namespace-configuration} parameter} boolean hidden?
- If namespace is hidden, it's not advertised to clients via NAMESPACE
- extension. You'll most likely also want to set @samp{list? #f}. This is mostly
- useful when converting from another server with different namespaces
- which you want to deprecate but still keep working. For example you can
- create hidden namespaces with prefixes @samp{~/mail/}, @samp{~%u/mail/}
- and @samp{mail/}.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{namespace-configuration} parameter} boolean list?
- Show the mailboxes under this namespace with the LIST command. This
- makes the namespace visible for clients that do not support the NAMESPACE
- extension. The special @code{children} value lists child mailboxes, but
- hides the namespace prefix.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{namespace-configuration} parameter} boolean subscriptions?
- Namespace handles its own subscriptions. If set to @code{#f}, the
- parent namespace handles them. The empty prefix should always have this
- as @code{#t}).
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{namespace-configuration} parameter} mailbox-configuration-list mailboxes
- List of predefined mailboxes in this namespace.
- Defaults to @samp{()}.
- Available @code{mailbox-configuration} fields are:
- @deftypevr {@code{mailbox-configuration} parameter} string name
- Name for this mailbox.
- @end deftypevr
- @deftypevr {@code{mailbox-configuration} parameter} string auto
- @samp{create} will automatically create this mailbox.
- @samp{subscribe} will both create and subscribe to the mailbox.
- Defaults to @samp{"no"}.
- @end deftypevr
- @deftypevr {@code{mailbox-configuration} parameter} space-separated-string-list special-use
- List of IMAP @code{SPECIAL-USE} attributes as specified by RFC 6154.
- Valid values are @code{\All}, @code{\Archive}, @code{\Drafts},
- @code{\Flagged}, @code{\Junk}, @code{\Sent}, and @code{\Trash}.
- Defaults to @samp{()}.
- @end deftypevr
- @end deftypevr
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} file-name base-dir
- Base directory where to store runtime data.
- Defaults to @samp{"/var/run/dovecot/"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string login-greeting
- Greeting message for clients.
- Defaults to @samp{"Dovecot ready."}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list login-trusted-networks
- List of trusted network ranges. Connections from these IPs are
- allowed to override their IP addresses and ports (for logging and for
- authentication checks). @samp{disable-plaintext-auth} is also ignored
- for these networks. Typically you would specify your IMAP proxy servers
- here.
- Defaults to @samp{()}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list login-access-sockets
- List of login access check sockets (e.g.@: tcpwrap).
- Defaults to @samp{()}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean verbose-proctitle?
- Show more verbose process titles (in ps). Currently shows user name
- and IP address. Useful for seeing who is actually using the IMAP
- processes (e.g.@: shared mailboxes or if the same uid is used for multiple
- accounts).
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean shutdown-clients?
- Should all processes be killed when Dovecot master process shuts down.
- Setting this to @code{#f} means that Dovecot can be upgraded without
- forcing existing client connections to close (although that could also
- be a problem if the upgrade is e.g.@: due to a security fix).
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer doveadm-worker-count
- If non-zero, run mail commands via this many connections to doveadm
- server, instead of running them directly in the same process.
- Defaults to @samp{0}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string doveadm-socket-path
- UNIX socket or host:port used for connecting to doveadm server.
- Defaults to @samp{"doveadm-server"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list import-environment
- List of environment variables that are preserved on Dovecot startup
- and passed down to all of its child processes. You can also give
- key=value pairs to always set specific settings.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean disable-plaintext-auth?
- Disable LOGIN command and all other plaintext authentications unless
- SSL/TLS is used (LOGINDISABLED capability). Note that if the remote IP
- matches the local IP (i.e.@: you're connecting from the same computer),
- the connection is considered secure and plaintext authentication is
- allowed. See also ssl=required setting.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer auth-cache-size
- Authentication cache size (e.g.@: @samp{#e10e6}). 0 means it's disabled.
- Note that bsdauth, PAM and vpopmail require @samp{cache-key} to be set
- for caching to be used.
- Defaults to @samp{0}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string auth-cache-ttl
- Time to live for cached data. After TTL expires the cached record
- is no longer used, *except* if the main database lookup returns internal
- failure. We also try to handle password changes automatically: If
- user's previous authentication was successful, but this one wasn't, the
- cache isn't used. For now this works only with plaintext
- authentication.
- Defaults to @samp{"1 hour"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string auth-cache-negative-ttl
- TTL for negative hits (user not found, password mismatch).
- 0 disables caching them completely.
- Defaults to @samp{"1 hour"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list auth-realms
- List of realms for SASL authentication mechanisms that need them.
- You can leave it empty if you don't want to support multiple realms.
- Many clients simply use the first one listed here, so keep the default
- realm first.
- Defaults to @samp{()}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string auth-default-realm
- Default realm/domain to use if none was specified. This is used for
- both SASL realms and appending @@domain to username in plaintext
- logins.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string auth-username-chars
- List of allowed characters in username. If the user-given username
- contains a character not listed in here, the login automatically fails.
- This is just an extra check to make sure user can't exploit any
- potential quote escaping vulnerabilities with SQL/LDAP databases. If
- you want to allow all characters, set this value to empty.
- Defaults to @samp{"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ01234567890.-_@@"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string auth-username-translation
- Username character translations before it's looked up from
- databases. The value contains series of from -> to characters. For
- example @samp{#@@/@@} means that @samp{#} and @samp{/} characters are
- translated to @samp{@@}.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string auth-username-format
- Username formatting before it's looked up from databases. You can
- use the standard variables here, e.g.@: %Lu would lowercase the username,
- %n would drop away the domain if it was given, or @samp{%n-AT-%d} would
- change the @samp{@@} into @samp{-AT-}. This translation is done after
- @samp{auth-username-translation} changes.
- Defaults to @samp{"%Lu"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string auth-master-user-separator
- If you want to allow master users to log in by specifying the master
- username within the normal username string (i.e.@: not using SASL
- mechanism's support for it), you can specify the separator character
- here. The format is then <username><separator><master username>.
- UW-IMAP uses @samp{*} as the separator, so that could be a good
- choice.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string auth-anonymous-username
- Username to use for users logging in with ANONYMOUS SASL
- mechanism.
- Defaults to @samp{"anonymous"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer auth-worker-max-count
- Maximum number of dovecot-auth worker processes. They're used to
- execute blocking passdb and userdb queries (e.g.@: MySQL and PAM).
- They're automatically created and destroyed as needed.
- Defaults to @samp{30}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string auth-gssapi-hostname
- Host name to use in GSSAPI principal names. The default is to use
- the name returned by gethostname(). Use @samp{$ALL} (with quotes) to
- allow all keytab entries.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string auth-krb5-keytab
- Kerberos keytab to use for the GSSAPI mechanism. Will use the
- system default (usually @file{/etc/krb5.keytab}) if not specified. You may
- need to change the auth service to run as root to be able to read this
- file.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean auth-use-winbind?
- Do NTLM and GSS-SPNEGO authentication using Samba's winbind daemon
- and @samp{ntlm-auth} helper.
- <doc/wiki/Authentication/Mechanisms/Winbind.txt>.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} file-name auth-winbind-helper-path
- Path for Samba's @samp{ntlm-auth} helper binary.
- Defaults to @samp{"/usr/bin/ntlm_auth"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string auth-failure-delay
- Time to delay before replying to failed authentications.
- Defaults to @samp{"2 secs"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean auth-ssl-require-client-cert?
- Require a valid SSL client certificate or the authentication
- fails.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean auth-ssl-username-from-cert?
- Take the username from client's SSL certificate, using
- @code{X509_NAME_get_text_by_NID()} which returns the subject's DN's
- CommonName.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list auth-mechanisms
- List of wanted authentication mechanisms. Supported mechanisms are:
- @samp{plain}, @samp{login}, @samp{digest-md5}, @samp{cram-md5},
- @samp{ntlm}, @samp{rpa}, @samp{apop}, @samp{anonymous}, @samp{gssapi},
- @samp{otp}, @samp{skey}, and @samp{gss-spnego}. NOTE: See also
- @samp{disable-plaintext-auth} setting.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list director-servers
- List of IPs or hostnames to all director servers, including ourself.
- Ports can be specified as ip:port. The default port is the same as what
- director service's @samp{inet-listener} is using.
- Defaults to @samp{()}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list director-mail-servers
- List of IPs or hostnames to all backend mail servers. Ranges are
- allowed too, like 10.0.0.10-10.0.0.30.
- Defaults to @samp{()}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string director-user-expire
- How long to redirect users to a specific server after it no longer
- has any connections.
- Defaults to @samp{"15 min"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string director-username-hash
- How the username is translated before being hashed. Useful values
- include %Ln if user can log in with or without @@domain, %Ld if mailboxes
- are shared within domain.
- Defaults to @samp{"%Lu"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string log-path
- Log file to use for error messages. @samp{syslog} logs to syslog,
- @samp{/dev/stderr} logs to stderr.
- Defaults to @samp{"syslog"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string info-log-path
- Log file to use for informational messages. Defaults to
- @samp{log-path}.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string debug-log-path
- Log file to use for debug messages. Defaults to
- @samp{info-log-path}.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string syslog-facility
- Syslog facility to use if you're logging to syslog. Usually if you
- don't want to use @samp{mail}, you'll use local0..local7. Also other
- standard facilities are supported.
- Defaults to @samp{"mail"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean auth-verbose?
- Log unsuccessful authentication attempts and the reasons why they
- failed.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string auth-verbose-passwords
- In case of password mismatches, log the attempted password. Valid
- values are no, plain and sha1. sha1 can be useful for detecting brute
- force password attempts vs. user simply trying the same password over
- and over again. You can also truncate the value to n chars by appending
- ":n" (e.g.@: sha1:6).
- Defaults to @samp{"no"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean auth-debug?
- Even more verbose logging for debugging purposes. Shows for example
- SQL queries.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean auth-debug-passwords?
- In case of password mismatches, log the passwords and used scheme so
- the problem can be debugged. Enabling this also enables
- @samp{auth-debug}.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean mail-debug?
- Enable mail process debugging. This can help you figure out why
- Dovecot isn't finding your mails.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean verbose-ssl?
- Show protocol level SSL errors.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string log-timestamp
- Prefix for each line written to log file. % codes are in
- strftime(3) format.
- Defaults to @samp{"\"%b %d %H:%M:%S \""}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list login-log-format-elements
- List of elements we want to log. The elements which have a
- non-empty variable value are joined together to form a comma-separated
- string.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string login-log-format
- Login log format. %s contains @samp{login-log-format-elements}
- string, %$ contains the data we want to log.
- Defaults to @samp{"%$: %s"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string mail-log-prefix
- Log prefix for mail processes. See doc/wiki/Variables.txt for list
- of possible variables you can use.
- Defaults to @samp{"\"%s(%u)<%@{pid@}><%@{session@}>: \""}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string deliver-log-format
- Format to use for logging mail deliveries. You can use variables:
- @table @code
- @item %$
- Delivery status message (e.g.@: @samp{saved to INBOX})
- @item %m
- Message-ID
- @item %s
- Subject
- @item %f
- From address
- @item %p
- Physical size
- @item %w
- Virtual size.
- @end table
- Defaults to @samp{"msgid=%m: %$"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string mail-location
- Location for users' mailboxes. The default is empty, which means
- that Dovecot tries to find the mailboxes automatically. This won't work
- if the user doesn't yet have any mail, so you should explicitly tell
- Dovecot the full location.
- If you're using mbox, giving a path to the INBOX
- file (e.g.@: @file{/var/mail/%u}) isn't enough. You'll also need to tell Dovecot
- where the other mailboxes are kept. This is called the @emph{root mail
- directory}, and it must be the first path given in the
- @samp{mail-location} setting.
- There are a few special variables you can use, e.g.:
- @table @samp
- @item %u
- username
- @item %n
- user part in user@@domain, same as %u if there's no domain
- @item %d
- domain part in user@@domain, empty if there's no domain
- @item %h
- home director
- @end table
- See doc/wiki/Variables.txt for full list. Some examples:
- @table @samp
- @item maildir:~/Maildir
- @item mbox:~/mail:INBOX=/var/mail/%u
- @item mbox:/var/mail/%d/%1n/%n:INDEX=/var/indexes/%d/%1n/%
- @end table
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string mail-uid
- System user and group used to access mails. If you use multiple,
- userdb can override these by returning uid or gid fields. You can use
- either numbers or names. <doc/wiki/UserIds.txt>.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string mail-gid
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string mail-privileged-group
- Group to enable temporarily for privileged operations. Currently
- this is used only with INBOX when either its initial creation or
- dotlocking fails. Typically this is set to @samp{"mail"} to give access to
- @file{/var/mail}.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string mail-access-groups
- Grant access to these supplementary groups for mail processes.
- Typically these are used to set up access to shared mailboxes. Note
- that it may be dangerous to set these if users can create symlinks
- (e.g.@: if @samp{mail} group is set here, @code{ln -s /var/mail ~/mail/var}
- could allow a user to delete others' mailboxes, or @code{ln -s
- /secret/shared/box ~/mail/mybox} would allow reading it). Defaults to
- @samp{""}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string mail-attribute-dict
- The location of a dictionary used to store @code{IMAP METADATA}
- as defined by @uref{https://tools.ietf.org/html/rfc5464, RFC@tie{}5464}.
- The IMAP METADATA commands are available only if the ``imap''
- protocol configuration's @code{imap-metadata?} field is @samp{#t}.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean mail-full-filesystem-access?
- Allow full file system access to clients. There's no access checks
- other than what the operating system does for the active UID/GID@. It
- works with both maildir and mboxes, allowing you to prefix mailboxes
- names with e.g.@: @file{/path/} or @file{~user/}.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean mmap-disable?
- Don't use @code{mmap()} at all. This is required if you store indexes to
- shared file systems (NFS or clustered file system).
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean dotlock-use-excl?
- Rely on @samp{O_EXCL} to work when creating dotlock files. NFS
- supports @samp{O_EXCL} since version 3, so this should be safe to use
- nowadays by default.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string mail-fsync
- When to use fsync() or fdatasync() calls:
- @table @code
- @item optimized
- Whenever necessary to avoid losing important data
- @item always
- Useful with e.g.@: NFS when @code{write()}s are delayed
- @item never
- Never use it (best performance, but crashes can lose data).
- @end table
- Defaults to @samp{"optimized"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean mail-nfs-storage?
- Mail storage exists in NFS@. Set this to yes to make Dovecot flush
- NFS caches whenever needed. If you're using only a single mail server
- this isn't needed.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean mail-nfs-index?
- Mail index files also exist in NFS@. Setting this to yes requires
- @samp{mmap-disable? #t} and @samp{fsync-disable? #f}.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string lock-method
- Locking method for index files. Alternatives are fcntl, flock and
- dotlock. Dotlocking uses some tricks which may create more disk I/O
- than other locking methods. NFS users: flock doesn't work, remember to
- change @samp{mmap-disable}.
- Defaults to @samp{"fcntl"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} file-name mail-temp-dir
- Directory in which LDA/LMTP temporarily stores incoming mails >128
- kB.
- Defaults to @samp{"/tmp"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer first-valid-uid
- Valid UID range for users. This is mostly to make sure that users can't
- log in as daemons or other system users. Note that denying root logins is
- hardcoded to dovecot binary and can't be done even if @samp{first-valid-uid}
- is set to 0.
- Defaults to @samp{500}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer last-valid-uid
- Defaults to @samp{0}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer first-valid-gid
- Valid GID range for users. Users having non-valid GID as primary group ID
- aren't allowed to log in. If user belongs to supplementary groups with
- non-valid GIDs, those groups are not set.
- Defaults to @samp{1}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer last-valid-gid
- Defaults to @samp{0}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mail-max-keyword-length
- Maximum allowed length for mail keyword name. It's only forced when
- trying to create new keywords.
- Defaults to @samp{50}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} colon-separated-file-name-list valid-chroot-dirs
- List of directories under which chrooting is allowed for mail
- processes (i.e.@: @file{/var/mail} will allow chrooting to @file{/var/mail/foo/bar}
- too). This setting doesn't affect @samp{login-chroot}
- @samp{mail-chroot} or auth chroot settings. If this setting is empty,
- @samp{/./} in home dirs are ignored. WARNING: Never add directories here
- which local users can modify, that may lead to root exploit. Usually
- this should be done only if you don't allow shell access for users.
- <doc/wiki/Chrooting.txt>.
- Defaults to @samp{()}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string mail-chroot
- Default chroot directory for mail processes. This can be overridden
- for specific users in user database by giving @samp{/./} in user's home
- directory (e.g.@: @samp{/home/./user} chroots into @file{/home}). Note that usually
- there is no real need to do chrooting, Dovecot doesn't allow users to
- access files outside their mail directory anyway. If your home
- directories are prefixed with the chroot directory, append @samp{/.} to
- @samp{mail-chroot}. <doc/wiki/Chrooting.txt>.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} file-name auth-socket-path
- UNIX socket path to master authentication server to find users.
- This is used by imap (for shared users) and lda.
- Defaults to @samp{"/var/run/dovecot/auth-userdb"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} file-name mail-plugin-dir
- Directory where to look up mail plugins.
- Defaults to @samp{"/usr/lib/dovecot"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list mail-plugins
- List of plugins to load for all services. Plugins specific to IMAP,
- LDA, etc.@: are added to this list in their own .conf files.
- Defaults to @samp{()}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mail-cache-min-mail-count
- The minimum number of mails in a mailbox before updates are done to
- cache file. This allows optimizing Dovecot's behavior to do less disk
- writes at the cost of more disk reads.
- Defaults to @samp{0}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string mailbox-idle-check-interval
- When IDLE command is running, mailbox is checked once in a while to
- see if there are any new mails or other changes. This setting defines
- the minimum time to wait between those checks. Dovecot can also use
- dnotify, inotify and kqueue to find out immediately when changes
- occur.
- Defaults to @samp{"30 secs"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean mail-save-crlf?
- Save mails with CR+LF instead of plain LF@. This makes sending those
- mails take less CPU, especially with sendfile() syscall with Linux and
- FreeBSD@. But it also creates a bit more disk I/O which may just make it
- slower. Also note that if other software reads the mboxes/maildirs,
- they may handle the extra CRs wrong and cause problems.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean maildir-stat-dirs?
- By default LIST command returns all entries in maildir beginning
- with a dot. Enabling this option makes Dovecot return only entries
- which are directories. This is done by stat()ing each entry, so it
- causes more disk I/O.
- (For systems setting struct @samp{dirent->d_type} this check is free
- and it's done always regardless of this setting).
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean maildir-copy-with-hardlinks?
- When copying a message, do it with hard links whenever possible.
- This makes the performance much better, and it's unlikely to have any
- side effects.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean maildir-very-dirty-syncs?
- Assume Dovecot is the only MUA accessing Maildir: Scan cur/
- directory only when its mtime changes unexpectedly or when we can't find
- the mail otherwise.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list mbox-read-locks
- Which locking methods to use for locking mbox. There are four
- available:
- @table @code
- @item dotlock
- Create <mailbox>.lock file. This is the oldest and most NFS-safe
- solution. If you want to use /var/mail/ like directory, the users will
- need write access to that directory.
- @item dotlock-try
- Same as dotlock, but if it fails because of permissions or because there
- isn't enough disk space, just skip it.
- @item fcntl
- Use this if possible. Works with NFS too if lockd is used.
- @item flock
- May not exist in all systems. Doesn't work with NFS.
- @item lockf
- May not exist in all systems. Doesn't work with NFS.
- @end table
- You can use multiple locking methods; if you do the order they're declared
- in is important to avoid deadlocks if other MTAs/MUAs are using multiple
- locking methods as well. Some operating systems don't allow using some of
- them simultaneously.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list mbox-write-locks
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string mbox-lock-timeout
- Maximum time to wait for lock (all of them) before aborting.
- Defaults to @samp{"5 mins"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string mbox-dotlock-change-timeout
- If dotlock exists but the mailbox isn't modified in any way,
- override the lock file after this much time.
- Defaults to @samp{"2 mins"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean mbox-dirty-syncs?
- When mbox changes unexpectedly we have to fully read it to find out
- what changed. If the mbox is large this can take a long time. Since
- the change is usually just a newly appended mail, it'd be faster to
- simply read the new mails. If this setting is enabled, Dovecot does
- this but still safely fallbacks to re-reading the whole mbox file
- whenever something in mbox isn't how it's expected to be. The only real
- downside to this setting is that if some other MUA changes message
- flags, Dovecot doesn't notice it immediately. Note that a full sync is
- done with SELECT, EXAMINE, EXPUNGE and CHECK commands.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean mbox-very-dirty-syncs?
- Like @samp{mbox-dirty-syncs}, but don't do full syncs even with SELECT,
- EXAMINE, EXPUNGE or CHECK commands. If this is set,
- @samp{mbox-dirty-syncs} is ignored.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean mbox-lazy-writes?
- Delay writing mbox headers until doing a full write sync (EXPUNGE
- and CHECK commands and when closing the mailbox). This is especially
- useful for POP3 where clients often delete all mails. The downside is
- that our changes aren't immediately visible to other MUAs.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mbox-min-index-size
- If mbox size is smaller than this (e.g.@: 100k), don't write index
- files. If an index file already exists it's still read, just not
- updated.
- Defaults to @samp{0}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mdbox-rotate-size
- Maximum dbox file size until it's rotated.
- Defaults to @samp{10000000}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string mdbox-rotate-interval
- Maximum dbox file age until it's rotated. Typically in days. Day
- begins from midnight, so 1d = today, 2d = yesterday, etc. 0 = check
- disabled.
- Defaults to @samp{"1d"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean mdbox-preallocate-space?
- When creating new mdbox files, immediately preallocate their size to
- @samp{mdbox-rotate-size}. This setting currently works only in Linux
- with some file systems (ext4, xfs).
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string mail-attachment-dir
- sdbox and mdbox support saving mail attachments to external files,
- which also allows single instance storage for them. Other backends
- don't support this for now.
- WARNING: This feature hasn't been tested much yet. Use at your own risk.
- Directory root where to store mail attachments. Disabled, if empty.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mail-attachment-min-size
- Attachments smaller than this aren't saved externally. It's also
- possible to write a plugin to disable saving specific attachments
- externally.
- Defaults to @samp{128000}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string mail-attachment-fs
- File system backend to use for saving attachments:
- @table @code
- @item posix
- No SiS done by Dovecot (but this might help FS's own deduplication)
- @item sis posix
- SiS with immediate byte-by-byte comparison during saving
- @item sis-queue posix
- SiS with delayed comparison and deduplication.
- @end table
- Defaults to @samp{"sis posix"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string mail-attachment-hash
- Hash format to use in attachment filenames. You can add any text and
- variables: @code{%@{md4@}}, @code{%@{md5@}}, @code{%@{sha1@}},
- @code{%@{sha256@}}, @code{%@{sha512@}}, @code{%@{size@}}. Variables can be
- truncated, e.g.@: @code{%@{sha256:80@}} returns only first 80 bits.
- Defaults to @samp{"%@{sha1@}"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer default-process-limit
- Defaults to @samp{100}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer default-client-limit
- Defaults to @samp{1000}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer default-vsz-limit
- Default VSZ (virtual memory size) limit for service processes.
- This is mainly intended to catch and kill processes that leak memory
- before they eat up everything.
- Defaults to @samp{256000000}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string default-login-user
- Login user is internally used by login processes. This is the most
- untrusted user in Dovecot system. It shouldn't have access to anything
- at all.
- Defaults to @samp{"dovenull"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string default-internal-user
- Internal user is used by unprivileged processes. It should be
- separate from login user, so that login processes can't disturb other
- processes.
- Defaults to @samp{"dovecot"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string ssl?
- SSL/TLS support: yes, no, required. <doc/wiki/SSL.txt>.
- Defaults to @samp{"required"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string ssl-cert
- PEM encoded X.509 SSL/TLS certificate (public key).
- Defaults to @samp{"</etc/dovecot/default.pem"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string ssl-key
- PEM encoded SSL/TLS private key. The key is opened before
- dropping root privileges, so keep the key file unreadable by anyone but
- root.
- Defaults to @samp{"</etc/dovecot/private/default.pem"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string ssl-key-password
- If key file is password protected, give the password here.
- Alternatively give it when starting dovecot with -p parameter. Since
- this file is often world-readable, you may want to place this setting
- instead to a different.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string ssl-ca
- PEM encoded trusted certificate authority. Set this only if you
- intend to use @samp{ssl-verify-client-cert? #t}. The file should
- contain the CA certificate(s) followed by the matching
- CRL(s). (e.g.@: @samp{ssl-ca </etc/ssl/certs/ca.pem}).
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean ssl-require-crl?
- Require that CRL check succeeds for client certificates.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean ssl-verify-client-cert?
- Request client to send a certificate. If you also want to require
- it, set @samp{auth-ssl-require-client-cert? #t} in auth section.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string ssl-cert-username-field
- Which field from certificate to use for username. commonName and
- x500UniqueIdentifier are the usual choices. You'll also need to set
- @samp{auth-ssl-username-from-cert? #t}.
- Defaults to @samp{"commonName"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string ssl-min-protocol
- Minimum SSL protocol version to accept.
- Defaults to @samp{"TLSv1"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string ssl-cipher-list
- SSL ciphers to use.
- Defaults to @samp{"ALL:!kRSA:!SRP:!kDHd:!DSS:!aNULL:!eNULL:!EXPORT:!DES:!3DES:!MD5:!PSK:!RC4:!ADH:!LOW@@STRENGTH"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string ssl-crypto-device
- SSL crypto device to use, for valid values run "openssl engine".
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string postmaster-address
- Address to use when sending rejection mails.
- %d expands to recipient domain.
- Defaults to @samp{"postmaster@@%d"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string hostname
- Hostname to use in various parts of sent mails (e.g.@: in Message-Id)
- and in LMTP replies. Default is the system's real hostname@@domain.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean quota-full-tempfail?
- If user is over quota, return with temporary failure instead of
- bouncing the mail.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} file-name sendmail-path
- Binary to use for sending mails.
- Defaults to @samp{"/usr/sbin/sendmail"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string submission-host
- If non-empty, send mails via this SMTP host[:port] instead of
- sendmail.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string rejection-subject
- Subject: header to use for rejection mails. You can use the same
- variables as for @samp{rejection-reason} below.
- Defaults to @samp{"Rejected: %s"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string rejection-reason
- Human readable error message for rejection mails. You can use
- variables:
- @table @code
- @item %n
- CRLF
- @item %r
- reason
- @item %s
- original subject
- @item %t
- recipient
- @end table
- Defaults to @samp{"Your message to <%t> was automatically rejected:%n%r"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string recipient-delimiter
- Delimiter character between local-part and detail in email
- address.
- Defaults to @samp{"+"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string lda-original-recipient-header
- Header where the original recipient address (SMTP's RCPT TO:
- address) is taken from if not available elsewhere. With dovecot-lda -a
- parameter overrides this. A commonly used header for this is
- X-Original-To.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean lda-mailbox-autocreate?
- Should saving a mail to a nonexistent mailbox automatically create
- it?.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} boolean lda-mailbox-autosubscribe?
- Should automatically created mailboxes be also automatically
- subscribed?.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer imap-max-line-length
- Maximum IMAP command line length. Some clients generate very long
- command lines with huge mailboxes, so you may need to raise this if you
- get "Too long argument" or "IMAP command line too large" errors
- often.
- Defaults to @samp{64000}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string imap-logout-format
- IMAP logout format string:
- @table @code
- @item %i
- total number of bytes read from client
- @item %o
- total number of bytes sent to client.
- @end table
- See @file{doc/wiki/Variables.txt} for a list of all the variables you can use.
- Defaults to @samp{"in=%i out=%o deleted=%@{deleted@} expunged=%@{expunged@} trashed=%@{trashed@} hdr_count=%@{fetch_hdr_count@} hdr_bytes=%@{fetch_hdr_bytes@} body_count=%@{fetch_body_count@} body_bytes=%@{fetch_body_bytes@}"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string imap-capability
- Override the IMAP CAPABILITY response. If the value begins with '+',
- add the given capabilities on top of the defaults (e.g.@: +XFOO XBAR).
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string imap-idle-notify-interval
- How long to wait between "OK Still here" notifications when client
- is IDLEing.
- Defaults to @samp{"2 mins"}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string imap-id-send
- ID field names and values to send to clients. Using * as the value
- makes Dovecot use the default value. The following fields have default
- values currently: name, version, os, os-version, support-url,
- support-email.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string imap-id-log
- ID fields sent by client to log. * means everything.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list imap-client-workarounds
- Workarounds for various client bugs:
- @table @code
- @item delay-newmail
- Send EXISTS/RECENT new mail notifications only when replying to NOOP and
- CHECK commands. Some clients ignore them otherwise, for example OSX
- Mail (<v2.1). Outlook Express breaks more badly though, without this it
- may show user "Message no longer in server" errors. Note that OE6
- still breaks even with this workaround if synchronization is set to
- "Headers Only".
- @item tb-extra-mailbox-sep
- Thunderbird gets somehow confused with LAYOUT=fs (mbox and dbox) and
- adds extra @samp{/} suffixes to mailbox names. This option causes Dovecot to
- ignore the extra @samp{/} instead of treating it as invalid mailbox name.
- @item tb-lsub-flags
- Show \Noselect flags for LSUB replies with LAYOUT=fs (e.g.@: mbox).
- This makes Thunderbird realize they aren't selectable and show them
- greyed out, instead of only later giving "not selectable" popup error.
- @end table
- Defaults to @samp{()}.
- @end deftypevr
- @deftypevr {@code{dovecot-configuration} parameter} string imap-urlauth-host
- Host allowed in URLAUTH URLs sent by client. "*" allows all.
- Defaults to @samp{""}.
- @end deftypevr
- Whew! Lots of configuration options. The nice thing about it though is
- that Guix has a complete interface to Dovecot's configuration
- language. This allows not only a nice way to declare configurations,
- but also offers reflective capabilities as well: users can write code to
- inspect and transform configurations from within Scheme.
- However, it could be that you just want to get a @code{dovecot.conf} up
- and running. In that case, you can pass an
- @code{opaque-dovecot-configuration} as the @code{#:config} parameter to
- @code{dovecot-service}. As its name indicates, an opaque configuration
- does not have easy reflective capabilities.
- Available @code{opaque-dovecot-configuration} fields are:
- @deftypevr {@code{opaque-dovecot-configuration} parameter} package dovecot
- The dovecot package.
- @end deftypevr
- @deftypevr {@code{opaque-dovecot-configuration} parameter} string string
- The contents of the @code{dovecot.conf}, as a string.
- @end deftypevr
- For example, if your @code{dovecot.conf} is just the empty string, you
- could instantiate a dovecot service like this:
- @lisp
- (dovecot-service #:config
- (opaque-dovecot-configuration
- (string "")))
- @end lisp
- @subsubheading OpenSMTPD Service
- @deffn {Scheme Variable} opensmtpd-service-type
- This is the type of the @uref{https://www.opensmtpd.org, OpenSMTPD}
- service, whose value should be an @code{opensmtpd-configuration} object
- as in this example:
- @lisp
- (service opensmtpd-service-type
- (opensmtpd-configuration
- (config-file (local-file "./my-smtpd.conf"))))
- @end lisp
- @end deffn
- @deftp {Data Type} opensmtpd-configuration
- Data type representing the configuration of opensmtpd.
- @table @asis
- @item @code{package} (default: @var{opensmtpd})
- Package object of the OpenSMTPD SMTP server.
- @item @code{config-file} (default: @code{%default-opensmtpd-file})
- File-like object of the OpenSMTPD configuration file to use. By default
- it listens on the loopback network interface, and allows for mail from
- users and daemons on the local machine, as well as permitting email to
- remote servers. Run @command{man smtpd.conf} for more information.
- @end table
- @end deftp
- @subsubheading Exim Service
- @cindex mail transfer agent (MTA)
- @cindex MTA (mail transfer agent)
- @cindex SMTP
- @deffn {Scheme Variable} exim-service-type
- This is the type of the @uref{https://exim.org, Exim} mail transfer
- agent (MTA), whose value should be an @code{exim-configuration} object
- as in this example:
- @lisp
- (service exim-service-type
- (exim-configuration
- (config-file (local-file "./my-exim.conf"))))
- @end lisp
- @end deffn
- In order to use an @code{exim-service-type} service you must also have a
- @code{mail-aliases-service-type} service present in your
- @code{operating-system} (even if it has no aliases).
- @deftp {Data Type} exim-configuration
- Data type representing the configuration of exim.
- @table @asis
- @item @code{package} (default: @var{exim})
- Package object of the Exim server.
- @item @code{config-file} (default: @code{#f})
- File-like object of the Exim configuration file to use. If its value is
- @code{#f} then use the default configuration file from the package
- provided in @code{package}. The resulting configuration file is loaded
- after setting the @code{exim_user} and @code{exim_group} configuration
- variables.
- @end table
- @end deftp
- @subsubheading Getmail service
- @cindex IMAP
- @cindex POP
- @deffn {Scheme Variable} getmail-service-type
- This is the type of the @uref{http://pyropus.ca/software/getmail/, Getmail}
- mail retriever, whose value should be an @code{getmail-configuration}.
- @end deffn
- Available @code{getmail-configuration} fields are:
- @deftypevr {@code{getmail-configuration} parameter} symbol name
- A symbol to identify the getmail service.
- Defaults to @samp{"unset"}.
- @end deftypevr
- @deftypevr {@code{getmail-configuration} parameter} package package
- The getmail package to use.
- @end deftypevr
- @deftypevr {@code{getmail-configuration} parameter} string user
- The user to run getmail as.
- Defaults to @samp{"getmail"}.
- @end deftypevr
- @deftypevr {@code{getmail-configuration} parameter} string group
- The group to run getmail as.
- Defaults to @samp{"getmail"}.
- @end deftypevr
- @deftypevr {@code{getmail-configuration} parameter} string directory
- The getmail directory to use.
- Defaults to @samp{"/var/lib/getmail/default"}.
- @end deftypevr
- @deftypevr {@code{getmail-configuration} parameter} getmail-configuration-file rcfile
- The getmail configuration file to use.
- Available @code{getmail-configuration-file} fields are:
- @deftypevr {@code{getmail-configuration-file} parameter} getmail-retriever-configuration retriever
- What mail account to retrieve mail from, and how to access that account.
- Available @code{getmail-retriever-configuration} fields are:
- @deftypevr {@code{getmail-retriever-configuration} parameter} string type
- The type of mail retriever to use. Valid values include @samp{passwd}
- and @samp{static}.
- Defaults to @samp{"SimpleIMAPSSLRetriever"}.
- @end deftypevr
- @deftypevr {@code{getmail-retriever-configuration} parameter} string server
- Username to login to the mail server with.
- Defaults to @samp{unset}.
- @end deftypevr
- @deftypevr {@code{getmail-retriever-configuration} parameter} string username
- Username to login to the mail server with.
- Defaults to @samp{unset}.
- @end deftypevr
- @deftypevr {@code{getmail-retriever-configuration} parameter} non-negative-integer port
- Port number to connect to.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{getmail-retriever-configuration} parameter} string password
- Override fields from passwd.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{getmail-retriever-configuration} parameter} list password-command
- Override fields from passwd.
- Defaults to @samp{()}.
- @end deftypevr
- @deftypevr {@code{getmail-retriever-configuration} parameter} string keyfile
- PEM-formatted key file to use for the TLS negotiation.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{getmail-retriever-configuration} parameter} string certfile
- PEM-formatted certificate file to use for the TLS negotiation.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{getmail-retriever-configuration} parameter} string ca-certs
- CA certificates to use.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{getmail-retriever-configuration} parameter} parameter-alist extra-parameters
- Extra retriever parameters.
- Defaults to @samp{()}.
- @end deftypevr
- @end deftypevr
- @deftypevr {@code{getmail-configuration-file} parameter} getmail-destination-configuration destination
- What to do with retrieved messages.
- Available @code{getmail-destination-configuration} fields are:
- @deftypevr {@code{getmail-destination-configuration} parameter} string type
- The type of mail destination. Valid values include @samp{Maildir},
- @samp{Mboxrd} and @samp{MDA_external}.
- Defaults to @samp{unset}.
- @end deftypevr
- @deftypevr {@code{getmail-destination-configuration} parameter} string-or-filelike path
- The path option for the mail destination. The behaviour depends on the
- chosen type.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{getmail-destination-configuration} parameter} parameter-alist extra-parameters
- Extra destination parameters
- Defaults to @samp{()}.
- @end deftypevr
- @end deftypevr
- @deftypevr {@code{getmail-configuration-file} parameter} getmail-options-configuration options
- Configure getmail.
- Available @code{getmail-options-configuration} fields are:
- @deftypevr {@code{getmail-options-configuration} parameter} non-negative-integer verbose
- If set to @samp{0}, getmail will only print warnings and errors. A
- value of @samp{1} means that messages will be printed about retrieving
- and deleting messages. If set to @samp{2}, getmail will print messages
- about each of its actions.
- Defaults to @samp{1}.
- @end deftypevr
- @deftypevr {@code{getmail-options-configuration} parameter} boolean read-all
- If true, getmail will retrieve all available messages. Otherwise it
- will only retrieve messages it hasn't seen previously.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{getmail-options-configuration} parameter} boolean delete
- If set to true, messages will be deleted from the server after
- retrieving and successfully delivering them. Otherwise, messages will
- be left on the server.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{getmail-options-configuration} parameter} non-negative-integer delete-after
- Getmail will delete messages this number of days after seeing them, if
- they have been delivered. This means messages will be left on the
- server this number of days after delivering them. A value of @samp{0}
- disabled this feature.
- Defaults to @samp{0}.
- @end deftypevr
- @deftypevr {@code{getmail-options-configuration} parameter} non-negative-integer delete-bigger-than
- Delete messages larger than this of bytes after retrieving them, even if
- the delete and delete-after options are disabled. A value of @samp{0}
- disables this feature.
- Defaults to @samp{0}.
- @end deftypevr
- @deftypevr {@code{getmail-options-configuration} parameter} non-negative-integer max-bytes-per-session
- Retrieve messages totalling up to this number of bytes before closing
- the session with the server. A value of @samp{0} disables this feature.
- Defaults to @samp{0}.
- @end deftypevr
- @deftypevr {@code{getmail-options-configuration} parameter} non-negative-integer max-message-size
- Don't retrieve messages larger than this number of bytes. A value of
- @samp{0} disables this feature.
- Defaults to @samp{0}.
- @end deftypevr
- @deftypevr {@code{getmail-options-configuration} parameter} boolean delivered-to
- If true, getmail will add a Delivered-To header to messages.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{getmail-options-configuration} parameter} boolean received
- If set, getmail adds a Received header to the messages.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{getmail-options-configuration} parameter} string message-log
- Getmail will record a log of its actions to the named file. A value of
- @samp{""} disables this feature.
- Defaults to @samp{""}.
- @end deftypevr
- @deftypevr {@code{getmail-options-configuration} parameter} boolean message-log-syslog
- If true, getmail will record a log of its actions using the system
- logger.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{getmail-options-configuration} parameter} boolean message-log-verbose
- If true, getmail will log information about messages not retrieved and
- the reason for not retrieving them, as well as starting and ending
- information lines.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{getmail-options-configuration} parameter} parameter-alist extra-parameters
- Extra options to include.
- Defaults to @samp{()}.
- @end deftypevr
- @end deftypevr
- @end deftypevr
- @deftypevr {@code{getmail-configuration} parameter} list idle
- A list of mailboxes that getmail should wait on the server for new mail
- notifications. This depends on the server supporting the IDLE
- extension.
- Defaults to @samp{()}.
- @end deftypevr
- @deftypevr {@code{getmail-configuration} parameter} list environment-variables
- Environment variables to set for getmail.
- Defaults to @samp{()}.
- @end deftypevr
- @subsubheading Mail Aliases Service
- @cindex email aliases
- @cindex aliases, for email addresses
- @deffn {Scheme Variable} mail-aliases-service-type
- This is the type of the service which provides @code{/etc/aliases},
- specifying how to deliver mail to users on this system.
- @lisp
- (service mail-aliases-service-type
- '(("postmaster" "bob")
- ("bob" "bob@@example.com" "bob@@example2.com")))
- @end lisp
- @end deffn
- The configuration for a @code{mail-aliases-service-type} service is an
- association list denoting how to deliver mail that comes to this
- system. Each entry is of the form @code{(alias addresses ...)}, with
- @code{alias} specifying the local alias and @code{addresses} specifying
- where to deliver this user's mail.
- The aliases aren't required to exist as users on the local system. In
- the above example, there doesn't need to be a @code{postmaster} entry in
- the @code{operating-system}'s @code{user-accounts} in order to deliver
- the @code{postmaster} mail to @code{bob} (which subsequently would
- deliver mail to @code{bob@@example.com} and @code{bob@@example2.com}).
- @subsubheading GNU Mailutils IMAP4 Daemon
- @cindex GNU Mailutils IMAP4 Daemon
- @deffn {Scheme Variable} imap4d-service-type
- This is the type of the GNU Mailutils IMAP4 Daemon (@pxref{imap4d,,,
- mailutils, GNU Mailutils Manual}), whose value should be an
- @code{imap4d-configuration} object as in this example:
- @lisp
- (service imap4d-service-type
- (imap4d-configuration
- (config-file (local-file "imap4d.conf"))))
- @end lisp
- @end deffn
- @deftp {Data Type} imap4d-configuration
- Data type representing the configuration of @command{imap4d}.
- @table @asis
- @item @code{package} (default: @code{mailutils})
- The package that provides @command{imap4d}.
- @item @code{config-file} (default: @code{%default-imap4d-config-file})
- File-like object of the configuration file to use, by default it will listen
- on TCP port 143 of @code{localhost}. @xref{Conf-imap4d,,, mailutils, GNU
- Mailutils Manual}, for details.
- @end table
- @end deftp
- @subsubheading Radicale Service
- @cindex CalDAV
- @cindex CardDAV
- @deffn {Scheme Variable} radicale-service-type
- This is the type of the @uref{https://radicale.org, Radicale} CalDAV/CardDAV
- server whose value should be a @code{radicale-configuration}.
- @end deffn
- @deftp {Data Type} radicale-configuration
- Data type representing the configuration of @command{radicale}.
- @table @asis
- @item @code{package} (default: @code{radicale})
- The package that provides @command{radicale}.
- @item @code{config-file} (default: @code{%default-radicale-config-file})
- File-like object of the configuration file to use, by default it will listen
- on TCP port 5232 of @code{localhost} and use the @code{htpasswd} file at
- @file{/var/lib/radicale/users} with no (@code{plain}) encryption.
- @end table
- @end deftp
- @node Messaging Services
- @subsection Messaging Services
- @cindex messaging
- @cindex jabber
- @cindex XMPP
- The @code{(gnu services messaging)} module provides Guix service
- definitions for messaging services. Currently it provides the following
- services:
- @subsubheading Prosody Service
- @deffn {Scheme Variable} prosody-service-type
- This is the type for the @uref{https://prosody.im, Prosody XMPP
- communication server}. Its value must be a @code{prosody-configuration}
- record as in this example:
- @lisp
- (service prosody-service-type
- (prosody-configuration
- (modules-enabled (cons* "groups" "mam" %default-modules-enabled))
- (int-components
- (list
- (int-component-configuration
- (hostname "conference.example.net")
- (plugin "muc")
- (mod-muc (mod-muc-configuration)))))
- (virtualhosts
- (list
- (virtualhost-configuration
- (domain "example.net"))))))
- @end lisp
- See below for details about @code{prosody-configuration}.
- @end deffn
- By default, Prosody does not need much configuration. Only one
- @code{virtualhosts} field is needed: it specifies the domain you wish
- Prosody to serve.
- You can perform various sanity checks on the generated configuration
- with the @code{prosodyctl check} command.
- Prosodyctl will also help you to import certificates from the
- @code{letsencrypt} directory so that the @code{prosody} user can access
- them. See @url{https://prosody.im/doc/letsencrypt}.
- @example
- prosodyctl --root cert import /etc/letsencrypt/live
- @end example
- The available configuration parameters follow. Each parameter
- definition is preceded by its type; for example, @samp{string-list foo}
- indicates that the @code{foo} parameter should be specified as a list of
- strings. Types starting with @code{maybe-} denote parameters that won't
- show up in @code{prosody.cfg.lua} when their value is @code{'disabled}.
- There is also a way to specify the configuration as a string, if you
- have an old @code{prosody.cfg.lua} file that you want to port over from
- some other system; see the end for more details.
- The @code{file-object} type designates either a file-like object
- (@pxref{G-Expressions, file-like objects}) or a file name.
- @c The following documentation was initially generated by
- @c (generate-documentation) in (gnu services messaging). Manually maintained
- @c documentation is better, so we shouldn't hesitate to edit below as
- @c needed. However if the change you want to make to this documentation
- @c can be done in an automated way, it's probably easier to change
- @c (generate-documentation) than to make it below and have to deal with
- @c the churn as Prosody updates.
- Available @code{prosody-configuration} fields are:
- @deftypevr {@code{prosody-configuration} parameter} package prosody
- The Prosody package.
- @end deftypevr
- @deftypevr {@code{prosody-configuration} parameter} file-name data-path
- Location of the Prosody data storage directory. See
- @url{https://prosody.im/doc/configure}.
- Defaults to @samp{"/var/lib/prosody"}.
- @end deftypevr
- @deftypevr {@code{prosody-configuration} parameter} file-object-list plugin-paths
- Additional plugin directories. They are searched in all the specified
- paths in order. See @url{https://prosody.im/doc/plugins_directory}.
- Defaults to @samp{()}.
- @end deftypevr
- @deftypevr {@code{prosody-configuration} parameter} file-name certificates
- Every virtual host and component needs a certificate so that clients and
- servers can securely verify its identity. Prosody will automatically load
- certificates/keys from the directory specified here.
- Defaults to @samp{"/etc/prosody/certs"}.
- @end deftypevr
- @deftypevr {@code{prosody-configuration} parameter} string-list admins
- This is a list of accounts that are admins for the server. Note that you
- must create the accounts separately. See @url{https://prosody.im/doc/admins} and
- @url{https://prosody.im/doc/creating_accounts}.
- Example: @code{(admins '("user1@@example.com" "user2@@example.net"))}
- Defaults to @samp{()}.
- @end deftypevr
- @deftypevr {@code{prosody-configuration} parameter} boolean use-libevent?
- Enable use of libevent for better performance under high load. See
- @url{https://prosody.im/doc/libevent}.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{prosody-configuration} parameter} module-list modules-enabled
- This is the list of modules Prosody will load on startup. It looks for
- @code{mod_modulename.lua} in the plugins folder, so make sure that exists too.
- Documentation on modules can be found at:
- @url{https://prosody.im/doc/modules}.
- Defaults to @samp{("roster" "saslauth" "tls" "dialback" "disco" "carbons" "private" "blocklist" "vcard" "version" "uptime" "time" "ping" "pep" "register" "admin_adhoc")}.
- @end deftypevr
- @deftypevr {@code{prosody-configuration} parameter} string-list modules-disabled
- @samp{"offline"}, @samp{"c2s"} and @samp{"s2s"} are auto-loaded, but
- should you want to disable them then add them to this list.
- Defaults to @samp{()}.
- @end deftypevr
- @deftypevr {@code{prosody-configuration} parameter} file-object groups-file
- Path to a text file where the shared groups are defined. If this path is
- empty then @samp{mod_groups} does nothing. See
- @url{https://prosody.im/doc/modules/mod_groups}.
- Defaults to @samp{"/var/lib/prosody/sharedgroups.txt"}.
- @end deftypevr
- @deftypevr {@code{prosody-configuration} parameter} boolean allow-registration?
- Disable account creation by default, for security. See
- @url{https://prosody.im/doc/creating_accounts}.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{prosody-configuration} parameter} maybe-ssl-configuration ssl
- These are the SSL/TLS-related settings. Most of them are disabled so to
- use Prosody's defaults. If you do not completely understand these options, do
- not add them to your config, it is easy to lower the security of your server
- using them. See @url{https://prosody.im/doc/advanced_ssl_config}.
- Available @code{ssl-configuration} fields are:
- @deftypevr {@code{ssl-configuration} parameter} maybe-string protocol
- This determines what handshake to use.
- @end deftypevr
- @deftypevr {@code{ssl-configuration} parameter} maybe-file-name key
- Path to your private key file.
- @end deftypevr
- @deftypevr {@code{ssl-configuration} parameter} maybe-file-name certificate
- Path to your certificate file.
- @end deftypevr
- @deftypevr {@code{ssl-configuration} parameter} file-object capath
- Path to directory containing root certificates that you wish Prosody to
- trust when verifying the certificates of remote servers.
- Defaults to @samp{"/etc/ssl/certs"}.
- @end deftypevr
- @deftypevr {@code{ssl-configuration} parameter} maybe-file-object cafile
- Path to a file containing root certificates that you wish Prosody to trust.
- Similar to @code{capath} but with all certificates concatenated together.
- @end deftypevr
- @deftypevr {@code{ssl-configuration} parameter} maybe-string-list verify
- A list of verification options (these mostly map to OpenSSL's
- @code{set_verify()} flags).
- @end deftypevr
- @deftypevr {@code{ssl-configuration} parameter} maybe-string-list options
- A list of general options relating to SSL/TLS@. These map to OpenSSL's
- @code{set_options()}. For a full list of options available in LuaSec, see the
- LuaSec source.
- @end deftypevr
- @deftypevr {@code{ssl-configuration} parameter} maybe-non-negative-integer depth
- How long a chain of certificate authorities to check when looking for a
- trusted root certificate.
- @end deftypevr
- @deftypevr {@code{ssl-configuration} parameter} maybe-string ciphers
- An OpenSSL cipher string. This selects what ciphers Prosody will offer to
- clients, and in what order.
- @end deftypevr
- @deftypevr {@code{ssl-configuration} parameter} maybe-file-name dhparam
- A path to a file containing parameters for Diffie-Hellman key exchange. You
- can create such a file with:
- @code{openssl dhparam -out /etc/prosody/certs/dh-2048.pem 2048}
- @end deftypevr
- @deftypevr {@code{ssl-configuration} parameter} maybe-string curve
- Curve for Elliptic curve Diffie-Hellman. Prosody's default is
- @samp{"secp384r1"}.
- @end deftypevr
- @deftypevr {@code{ssl-configuration} parameter} maybe-string-list verifyext
- A list of ``extra'' verification options.
- @end deftypevr
- @deftypevr {@code{ssl-configuration} parameter} maybe-string password
- Password for encrypted private keys.
- @end deftypevr
- @end deftypevr
- @deftypevr {@code{prosody-configuration} parameter} boolean c2s-require-encryption?
- Whether to force all client-to-server connections to be encrypted or not.
- See @url{https://prosody.im/doc/modules/mod_tls}.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{prosody-configuration} parameter} string-list disable-sasl-mechanisms
- Set of mechanisms that will never be offered. See
- @url{https://prosody.im/doc/modules/mod_saslauth}.
- Defaults to @samp{("DIGEST-MD5")}.
- @end deftypevr
- @deftypevr {@code{prosody-configuration} parameter} boolean s2s-require-encryption?
- Whether to force all server-to-server connections to be encrypted or not.
- See @url{https://prosody.im/doc/modules/mod_tls}.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{prosody-configuration} parameter} boolean s2s-secure-auth?
- Whether to require encryption and certificate authentication. This
- provides ideal security, but requires servers you communicate with to support
- encryption AND present valid, trusted certificates. See
- @url{https://prosody.im/doc/s2s#security}.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{prosody-configuration} parameter} string-list s2s-insecure-domains
- Many servers don't support encryption or have invalid or self-signed
- certificates. You can list domains here that will not be required to
- authenticate using certificates. They will be authenticated using DNS@. See
- @url{https://prosody.im/doc/s2s#security}.
- Defaults to @samp{()}.
- @end deftypevr
- @deftypevr {@code{prosody-configuration} parameter} string-list s2s-secure-domains
- Even if you leave @code{s2s-secure-auth?} disabled, you can still require
- valid certificates for some domains by specifying a list here. See
- @url{https://prosody.im/doc/s2s#security}.
- Defaults to @samp{()}.
- @end deftypevr
- @deftypevr {@code{prosody-configuration} parameter} string authentication
- Select the authentication backend to use. The default provider stores
- passwords in plaintext and uses Prosody's configured data storage to store the
- authentication data. If you do not trust your server please see
- @url{https://prosody.im/doc/modules/mod_auth_internal_hashed} for information
- about using the hashed backend. See also
- @url{https://prosody.im/doc/authentication}
- Defaults to @samp{"internal_plain"}.
- @end deftypevr
- @deftypevr {@code{prosody-configuration} parameter} maybe-string log
- Set logging options. Advanced logging configuration is not yet supported
- by the Prosody service. See @url{https://prosody.im/doc/logging}.
- Defaults to @samp{"*syslog"}.
- @end deftypevr
- @deftypevr {@code{prosody-configuration} parameter} file-name pidfile
- File to write pid in. See @url{https://prosody.im/doc/modules/mod_posix}.
- Defaults to @samp{"/var/run/prosody/prosody.pid"}.
- @end deftypevr
- @deftypevr {@code{prosody-configuration} parameter} maybe-non-negative-integer http-max-content-size
- Maximum allowed size of the HTTP body (in bytes).
- @end deftypevr
- @deftypevr {@code{prosody-configuration} parameter} maybe-string http-external-url
- Some modules expose their own URL in various ways. This URL is built
- from the protocol, host and port used. If Prosody sits behind a proxy, the
- public URL will be @code{http-external-url} instead. See
- @url{https://prosody.im/doc/http#external_url}.
- @end deftypevr
- @deftypevr {@code{prosody-configuration} parameter} virtualhost-configuration-list virtualhosts
- A host in Prosody is a domain on which user accounts can be created. For
- example if you want your users to have addresses like
- @samp{"john.smith@@example.com"} then you need to add a host
- @samp{"example.com"}. All options in this list will apply only to this host.
- Note: the name @emph{virtual} host is used in configuration to avoid confusion with
- the actual physical host that Prosody is installed on. A single Prosody
- instance can serve many domains, each one defined as a VirtualHost entry in
- Prosody's configuration. Conversely a server that hosts a single domain would
- have just one VirtualHost entry.
- See @url{https://prosody.im/doc/configure#virtual_host_settings}.
- Available @code{virtualhost-configuration} fields are:
- all these @code{prosody-configuration} fields: @code{admins}, @code{use-libevent?}, @code{modules-enabled}, @code{modules-disabled}, @code{groups-file}, @code{allow-registration?}, @code{ssl}, @code{c2s-require-encryption?}, @code{disable-sasl-mechanisms}, @code{s2s-require-encryption?}, @code{s2s-secure-auth?}, @code{s2s-insecure-domains}, @code{s2s-secure-domains}, @code{authentication}, @code{log}, @code{http-max-content-size}, @code{http-external-url}, @code{raw-content}, plus:
- @deftypevr {@code{virtualhost-configuration} parameter} string domain
- Domain you wish Prosody to serve.
- @end deftypevr
- @end deftypevr
- @deftypevr {@code{prosody-configuration} parameter} int-component-configuration-list int-components
- Components are extra services on a server which are available to clients,
- usually on a subdomain of the main server (such as
- @samp{"mycomponent.example.com"}). Example components might be chatroom
- servers, user directories, or gateways to other protocols.
- Internal components are implemented with Prosody-specific plugins. To add an
- internal component, you simply fill the hostname field, and the plugin you wish
- to use for the component.
- See @url{https://prosody.im/doc/components}.
- Defaults to @samp{()}.
- Available @code{int-component-configuration} fields are:
- all these @code{prosody-configuration} fields: @code{admins}, @code{use-libevent?}, @code{modules-enabled}, @code{modules-disabled}, @code{groups-file}, @code{allow-registration?}, @code{ssl}, @code{c2s-require-encryption?}, @code{disable-sasl-mechanisms}, @code{s2s-require-encryption?}, @code{s2s-secure-auth?}, @code{s2s-insecure-domains}, @code{s2s-secure-domains}, @code{authentication}, @code{log}, @code{http-max-content-size}, @code{http-external-url}, @code{raw-content}, plus:
- @deftypevr {@code{int-component-configuration} parameter} string hostname
- Hostname of the component.
- @end deftypevr
- @deftypevr {@code{int-component-configuration} parameter} string plugin
- Plugin you wish to use for the component.
- @end deftypevr
- @deftypevr {@code{int-component-configuration} parameter} maybe-mod-muc-configuration mod-muc
- Multi-user chat (MUC) is Prosody's module for allowing you to create
- hosted chatrooms/conferences for XMPP users.
- General information on setting up and using multi-user chatrooms can be found
- in the ``Chatrooms'' documentation (@url{https://prosody.im/doc/chatrooms}),
- which you should read if you are new to XMPP chatrooms.
- See also @url{https://prosody.im/doc/modules/mod_muc}.
- Available @code{mod-muc-configuration} fields are:
- @deftypevr {@code{mod-muc-configuration} parameter} string name
- The name to return in service discovery responses.
- Defaults to @samp{"Prosody Chatrooms"}.
- @end deftypevr
- @deftypevr {@code{mod-muc-configuration} parameter} string-or-boolean restrict-room-creation
- If @samp{#t}, this will only allow admins to create new chatrooms.
- Otherwise anyone can create a room. The value @samp{"local"} restricts room
- creation to users on the service's parent domain. E.g.@: @samp{user@@example.com}
- can create rooms on @samp{rooms.example.com}. The value @samp{"admin"}
- restricts to service administrators only.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{mod-muc-configuration} parameter} non-negative-integer max-history-messages
- Maximum number of history messages that will be sent to the member that has
- just joined the room.
- Defaults to @samp{20}.
- @end deftypevr
- @end deftypevr
- @end deftypevr
- @deftypevr {@code{prosody-configuration} parameter} ext-component-configuration-list ext-components
- External components use XEP-0114, which most standalone components
- support. To add an external component, you simply fill the hostname field. See
- @url{https://prosody.im/doc/components}.
- Defaults to @samp{()}.
- Available @code{ext-component-configuration} fields are:
- all these @code{prosody-configuration} fields: @code{admins}, @code{use-libevent?}, @code{modules-enabled}, @code{modules-disabled}, @code{groups-file}, @code{allow-registration?}, @code{ssl}, @code{c2s-require-encryption?}, @code{disable-sasl-mechanisms}, @code{s2s-require-encryption?}, @code{s2s-secure-auth?}, @code{s2s-insecure-domains}, @code{s2s-secure-domains}, @code{authentication}, @code{log}, @code{http-max-content-size}, @code{http-external-url}, @code{raw-content}, plus:
- @deftypevr {@code{ext-component-configuration} parameter} string component-secret
- Password which the component will use to log in.
- @end deftypevr
- @deftypevr {@code{ext-component-configuration} parameter} string hostname
- Hostname of the component.
- @end deftypevr
- @end deftypevr
- @deftypevr {@code{prosody-configuration} parameter} non-negative-integer-list component-ports
- Port(s) Prosody listens on for component connections.
- Defaults to @samp{(5347)}.
- @end deftypevr
- @deftypevr {@code{prosody-configuration} parameter} string component-interface
- Interface Prosody listens on for component connections.
- Defaults to @samp{"127.0.0.1"}.
- @end deftypevr
- @deftypevr {@code{prosody-configuration} parameter} maybe-raw-content raw-content
- Raw content that will be added to the configuration file.
- @end deftypevr
- It could be that you just want to get a @code{prosody.cfg.lua}
- up and running. In that case, you can pass an
- @code{opaque-prosody-configuration} record as the value of
- @code{prosody-service-type}. As its name indicates, an opaque configuration
- does not have easy reflective capabilities.
- Available @code{opaque-prosody-configuration} fields are:
- @deftypevr {@code{opaque-prosody-configuration} parameter} package prosody
- The prosody package.
- @end deftypevr
- @deftypevr {@code{opaque-prosody-configuration} parameter} string prosody.cfg.lua
- The contents of the @code{prosody.cfg.lua} to use.
- @end deftypevr
- For example, if your @code{prosody.cfg.lua} is just the empty
- string, you could instantiate a prosody service like this:
- @lisp
- (service prosody-service-type
- (opaque-prosody-configuration
- (prosody.cfg.lua "")))
- @end lisp
- @c end of Prosody auto-generated documentation
- @subsubheading BitlBee Service
- @cindex IRC (Internet Relay Chat)
- @cindex IRC gateway
- @url{https://bitlbee.org,BitlBee} is a gateway that provides an IRC
- interface to a variety of messaging protocols such as XMPP.
- @defvr {Scheme Variable} bitlbee-service-type
- This is the service type for the @url{https://bitlbee.org,BitlBee} IRC
- gateway daemon. Its value is a @code{bitlbee-configuration} (see
- below).
- To have BitlBee listen on port 6667 on localhost, add this line to your
- services:
- @lisp
- (service bitlbee-service-type)
- @end lisp
- @end defvr
- @deftp {Data Type} bitlbee-configuration
- This is the configuration for BitlBee, with the following fields:
- @table @asis
- @item @code{interface} (default: @code{"127.0.0.1"})
- @itemx @code{port} (default: @code{6667})
- Listen on the network interface corresponding to the IP address
- specified in @var{interface}, on @var{port}.
- When @var{interface} is @code{127.0.0.1}, only local clients can
- connect; when it is @code{0.0.0.0}, connections can come from any
- networking interface.
- @item @code{bitlbee} (default: @code{bitlbee})
- The BitlBee package to use.
- @item @code{plugins} (default: @code{'()})
- List of plugin packages to use---e.g., @code{bitlbee-discord}.
- @item @code{extra-settings} (default: @code{""})
- Configuration snippet added as-is to the BitlBee configuration file.
- @end table
- @end deftp
- @subsubheading Quassel Service
- @cindex IRC (Internet Relay Chat)
- @url{https://quassel-irc.org/,Quassel} is a distributed IRC client,
- meaning that one or more clients can attach to and detach from the
- central core.
- @defvr {Scheme Variable} quassel-service-type
- This is the service type for the @url{https://quassel-irc.org/,Quassel}
- IRC backend daemon. Its value is a @code{quassel-configuration}
- (see below).
- @end defvr
- @deftp {Data Type} quassel-configuration
- This is the configuration for Quassel, with the following fields:
- @table @asis
- @item @code{quassel} (default: @code{quassel})
- The Quassel package to use.
- @item @code{interface} (default: @code{"::,0.0.0.0"})
- @item @code{port} (default: @code{4242})
- Listen on the network interface(s) corresponding to the IPv4 or IPv6
- interfaces specified in the comma delimited @var{interface}, on
- @var{port}.
- @item @code{loglevel} (default: @code{"Info"})
- The level of logging desired. Accepted values are Debug, Info, Warning
- and Error.
- @end table
- @end deftp
- @node Telephony Services
- @subsection Telephony Services
- @cindex telephony, services
- The @code{(gnu services telephony)} module contains Guix service
- definitions for telephony services. Currently it provides the following
- services:
- @subsubheading Jami
- @cindex jami, service
- This section describes how to configure a Jami server that can be used
- to host video (or audio) conferences, among other uses. The following
- example demonstrates how to specify Jami account archives (backups) to
- be provisioned automatically:
- @lisp
- (service jami-service-type
- (jami-configuration
- (accounts
- (list (jami-account
- (archive "/etc/jami/unencrypted-account-1.gz"))
- (jami-account
- (archive "/etc/jami/unencrypted-account-2.gz"))))))
- @end lisp
- When the accounts field is specified, the Jami account files of the
- service found under @file{/var/lib/jami} are recreated every time the
- service starts.
- Jami accounts and their corresponding backup archives can be generated
- using either the @code{jami-qt} or @code{jami-gnome} Jami clients. The
- accounts should not be password-protected, but it is wise to ensure
- their files are only readable by @samp{root}.
- The next example shows how to declare that only some contacts should be
- allowed to communicate with a given account:
- @lisp
- (service jami-service-type
- (jami-configuration
- (accounts
- (list (jami-account
- (archive "/etc/jami/unencrypted-account-1.gz")
- (peer-discovery? #t)
- (rendezvous-point? #t)
- (allowed-contacts
- '("1dbcb0f5f37324228235564b79f2b9737e9a008f"
- "2dbcb0f5f37324228235564b79f2b9737e9a008f")))))))
- @end lisp
- In this mode, only the declared @code{allowed-contacts} can initiate
- communication with the Jami account. This can be used, for example,
- with rendezvous point accounts to create a private video conferencing
- space.
- To put the system administrator in full control of the conferences
- hosted on their system, the Jami service supports the following actions:
- @example sh
- # herd doc jami list-actions
- (list-accounts
- list-account-details
- list-banned-contacts
- list-contacts
- list-moderators
- add-moderator
- ban-contact
- enable-account
- disable-account)
- @end example
- The above actions aim to provide the most valuable actions for
- moderation purposes, not to cover the whole Jami API. Users wanting to
- interact with the Jami daemon from Guile may be interested in
- experimenting with the @code{(gnu build jami-service)} module, which
- powers the above Shepherd actions.
- @c TODO: This should be auto-generated from the doc already defined on
- @c the shepherd-actions themselves in (gnu services telephony).
- The @code{add-moderator} and @code{ban-contact} actions accept a contact
- @emph{fingerprint} (40 characters long hash) as first argument and an
- account fingerprint or username as second argument:
- @example sh
- # herd add-moderator jami 1dbcb0f5f37324228235564b79f2b9737e9a008f \
- f3345f2775ddfe07a4b0d95daea111d15fbc1199
- # herd list-moderators jami
- Moderators for account f3345f2775ddfe07a4b0d95daea111d15fbc1199:
- - 1dbcb0f5f37324228235564b79f2b9737e9a008f
- @end example
- In the case of @code{ban-contact}, the second username argument is
- optional; when omitted, the account is banned from all Jami accounts:
- @example sh
- # herd ban-contact jami 1dbcb0f5f37324228235564b79f2b9737e9a008f
- # herd list-banned-contacts jami
- Banned contacts for account f3345f2775ddfe07a4b0d95daea111d15fbc1199:
- - 1dbcb0f5f37324228235564b79f2b9737e9a008f
- @end example
- Banned contacts are also stripped from their moderation privileges.
- The @code{disable-account} action allows to completely disconnect an
- account from the network, making it unreachable, while
- @code{enable-account} does the inverse. They accept a single account
- username or fingerprint as first argument:
- @example sh
- # herd disable-account jami f3345f2775ddfe07a4b0d95daea111d15fbc1199
- # herd list-accounts jami
- The following Jami accounts are available:
- - f3345f2775ddfe07a4b0d95daea111d15fbc1199 (dummy) [disabled]
- @end example
- The @code{list-account-details} action prints the detailed parameters of
- each accounts in the Recutils format, which means the @command{recsel}
- command can be used to select accounts of interest (@pxref{Selection
- Expressions,,,recutils, GNU recutils manual}). Note that period
- characters (@samp{.}) found in the account parameter keys are mapped to
- underscores (@samp{_}) in the output, to meet the requirements of the
- Recutils format. The following example shows how to print the account
- fingerprints for all accounts operating in the rendezvous point mode:
- @example sh
- # herd list-account-details jami | \
- recsel -p Account.username -e 'Account.rendezVous ~ "true"'
- Account_username: f3345f2775ddfe07a4b0d95daea111d15fbc1199
- @end example
- The remaining actions should be self-explanatory.
- The complete set of available configuration options is detailed below.
- @c TODO: Ideally, the following fragments would be auto-generated at
- @c build time, so that they needn't be manually duplicated.
- @c Auto-generated via (configuration->documentation 'jami-configuration)
- @deftp {Data Type} jami-configuration
- Available @code{jami-configuration} fields are:
- @table @asis
- @item @code{jamid} (default: @code{libring}) (type: package)
- The Jami daemon package to use.
- @item @code{dbus} (default: @code{dbus}) (type: package)
- The D-Bus package to use to start the required D-Bus session.
- @item @code{nss-certs} (default: @code{nss-certs}) (type: package)
- The nss-certs package to use to provide TLS certificates.
- @item @code{enable-logging?} (default: @code{#t}) (type: boolean)
- Whether to enable logging to syslog.
- @item @code{debug?} (default: @code{#f}) (type: boolean)
- Whether to enable debug level messages.
- @item @code{auto-answer?} (default: @code{#f}) (type: boolean)
- Whether to force automatic answer to incoming calls.
- @item @code{accounts} (default: @code{disabled}) (type: maybe-jami-account-list)
- A list of Jami accounts to be (re-)provisioned every time the Jami
- daemon service starts. When providing this field, the account
- directories under @file{/var/lib/jami/} are recreated every time the
- service starts, ensuring a consistent state.
- @end table
- @end deftp
- @c Auto-generated via (configuration->documentation 'jami-account)
- @deftp {Data Type} jami-account
- Available @code{jami-account} fields are:
- @table @asis
- @item @code{archive} (type: string-or-computed-file)
- The account archive (backup) file name of the account. This is used to
- provision the account when the service starts. The account archive
- should @emph{not} be encrypted. It is highly recommended to make it
- readable only to the @samp{root} user (i.e., not in the store), to guard
- against leaking the secret key material of the Jami account it contains.
- @item @code{allowed-contacts} (default: @code{disabled}) (type: maybe-account-fingerprint-list)
- The list of allowed contacts for the account, entered as their 40
- characters long fingerprint. Messages or calls from accounts not in
- that list will be rejected. When unspecified, the configuration of the
- account archive is used as-is with respect to contacts and public
- inbound calls/messaging allowance, which typically defaults to allow any
- contact to communicate with the account.
- @item @code{moderators} (default: @code{disabled}) (type: maybe-account-fingerprint-list)
- The list of contacts that should have moderation privileges (to ban,
- mute, etc. other users) in rendezvous conferences, entered as their 40
- characters long fingerprint. When unspecified, the configuration of the
- account archive is used as-is with respect to moderation, which
- typically defaults to allow anyone to moderate.
- @item @code{rendezvous-point?} (default: @code{disabled}) (type: maybe-boolean)
- Whether the account should operate in the rendezvous mode. In this
- mode, all the incoming audio/video calls are mixed into a conference.
- When left unspecified, the value from the account archive prevails.
- @item @code{peer-discovery?} (default: @code{disabled}) (type: maybe-boolean)
- Whether peer discovery should be enabled. Peer discovery is used to
- discover other OpenDHT nodes on the local network, which can be useful
- to maintain communication between devices on such network even when the
- connection to the the Internet has been lost. When left unspecified,
- the value from the account archive prevails.
- @item @code{bootstrap-hostnames} (default: @code{disabled}) (type: maybe-string-list)
- A list of hostnames or IPs pointing to OpenDHT nodes, that should be
- used to initially join the OpenDHT network. When left unspecified, the
- value from the account archive prevails.
- @item @code{name-server-uri} (default: @code{disabled}) (type: maybe-string)
- The URI of the name server to use, that can be used to retrieve the
- account fingerprint for a registered username.
- @end table
- @end deftp
- @subsubheading Murmur (VoIP server)
- @cindex Murmur (VoIP server)
- @cindex VoIP server
- This section describes how to set up and run a Murmur server. Murmur is
- the server of the @uref{https://mumble.info, Mumble} voice-over-IP
- (VoIP) suite.
- @deftp {Data Type} murmur-configuration
- The service type for the Murmur server. An example configuration can
- look like this:
- @lisp
- (service murmur-service-type
- (murmur-configuration
- (welcome-text
- "Welcome to this Mumble server running on Guix!")
- (cert-required? #t) ;disallow text password logins
- (ssl-cert "/etc/letsencrypt/live/mumble.example.com/fullchain.pem")
- (ssl-key "/etc/letsencrypt/live/mumble.example.com/privkey.pem")))
- @end lisp
- After reconfiguring your system, you can manually set the murmur @code{SuperUser}
- password with the command that is printed during the activation phase.
- It is recommended to register a normal Mumble user account
- and grant it admin or moderator rights.
- You can use the @code{mumble} client to
- login as new normal user, register yourself, and log out.
- For the next step login with the name @code{SuperUser} use
- the @code{SuperUser} password that you set previously,
- and grant your newly registered mumble user administrator or moderator
- rights and create some channels.
- Available @code{murmur-configuration} fields are:
- @table @asis
- @item @code{package} (default: @code{mumble})
- Package that contains @code{bin/murmurd}.
- @item @code{user} (default: @code{"murmur"})
- User who will run the Murmur server.
- @item @code{group} (default: @code{"murmur"})
- Group of the user who will run the murmur server.
- @item @code{port} (default: @code{64738})
- Port on which the server will listen.
- @item @code{welcome-text} (default: @code{""})
- Welcome text sent to clients when they connect.
- @item @code{server-password} (default: @code{""})
- Password the clients have to enter in order to connect.
- @item @code{max-users} (default: @code{100})
- Maximum of users that can be connected to the server at once.
- @item @code{max-user-bandwidth} (default: @code{#f})
- Maximum voice traffic a user can send per second.
- @item @code{database-file} (default: @code{"/var/lib/murmur/db.sqlite"})
- File name of the sqlite database.
- The service's user will become the owner of the directory.
- @item @code{log-file} (default: @code{"/var/log/murmur/murmur.log"})
- File name of the log file.
- The service's user will become the owner of the directory.
- @item @code{autoban-attempts} (default: @code{10})
- Maximum number of logins a user can make in @code{autoban-timeframe}
- without getting auto banned for @code{autoban-time}.
- @item @code{autoban-timeframe} (default: @code{120})
- Timeframe for autoban in seconds.
- @item @code{autoban-time} (default: @code{300})
- Amount of time in seconds for which a client gets banned
- when violating the autoban limits.
- @item @code{opus-threshold} (default: @code{100})
- Percentage of clients that need to support opus
- before switching over to opus audio codec.
- @item @code{channel-nesting-limit} (default: @code{10})
- How deep channels can be nested at maximum.
- @item @code{channelname-regex} (default: @code{#f})
- A string in form of a Qt regular expression that channel names must conform to.
- @item @code{username-regex} (default: @code{#f})
- A string in form of a Qt regular expression that user names must conform to.
- @item @code{text-message-length} (default: @code{5000})
- Maximum size in bytes that a user can send in one text chat message.
- @item @code{image-message-length} (default: @code{(* 128 1024)})
- Maximum size in bytes that a user can send in one image message.
- @item @code{cert-required?} (default: @code{#f})
- If it is set to @code{#t} clients that use weak password authentication
- will not be accepted. Users must have completed the certificate wizard to join.
- @item @code{remember-channel?} (default: @code{#f})
- Should murmur remember the last channel each user was in when they disconnected
- and put them into the remembered channel when they rejoin.
- @item @code{allow-html?} (default: @code{#f})
- Should html be allowed in text messages, user comments, and channel descriptions.
- @item @code{allow-ping?} (default: @code{#f})
- Setting to true exposes the current user count, the maximum user count, and
- the server's maximum bandwidth per client to unauthenticated users. In the
- Mumble client, this information is shown in the Connect dialog.
- Disabling this setting will prevent public listing of the server.
- @item @code{bonjour?} (default: @code{#f})
- Should the server advertise itself in the local network through the bonjour protocol.
- @item @code{send-version?} (default: @code{#f})
- Should the murmur server version be exposed in ping requests.
- @item @code{log-days} (default: @code{31})
- Murmur also stores logs in the database, which are accessible via RPC.
- The default is 31 days of months, but you can set this setting to 0 to keep logs forever,
- or -1 to disable logging to the database.
- @item @code{obfuscate-ips?} (default: @code{#t})
- Should logged ips be obfuscated to protect the privacy of users.
- @item @code{ssl-cert} (default: @code{#f})
- File name of the SSL/TLS certificate used for encrypted connections.
- @lisp
- (ssl-cert "/etc/letsencrypt/live/example.com/fullchain.pem")
- @end lisp
- @item @code{ssl-key} (default: @code{#f})
- Filepath to the ssl private key used for encrypted connections.
- @lisp
- (ssl-key "/etc/letsencrypt/live/example.com/privkey.pem")
- @end lisp
- @item @code{ssl-dh-params} (default: @code{#f})
- File name of a PEM-encoded file with Diffie-Hellman parameters
- for the SSL/TLS encryption. Alternatively you set it to
- @code{"@@ffdhe2048"}, @code{"@@ffdhe3072"}, @code{"@@ffdhe4096"}, @code{"@@ffdhe6144"}
- or @code{"@@ffdhe8192"} to use bundled parameters from RFC 7919.
- @item @code{ssl-ciphers} (default: @code{#f})
- The @code{ssl-ciphers} option chooses the cipher suites to make available for use
- in SSL/TLS.
- This option is specified using
- @uref{https://www.openssl.org/docs/apps/ciphers.html#CIPHER-LIST-FORMAT,
- OpenSSL cipher list notation}.
- It is recommended that you try your cipher string using 'openssl ciphers <string>'
- before setting it here, to get a feel for which cipher suites you will get.
- After setting this option, it is recommend that you inspect your Murmur log
- to ensure that Murmur is using the cipher suites that you expected it to.
- Note: Changing this option may impact the backwards compatibility of your
- Murmur server, and can remove the ability for older Mumble clients to be able
- to connect to it.
- @item @code{public-registration} (default: @code{#f})
- Must be a @code{<murmur-public-registration-configuration>} record or @code{#f}.
- You can optionally register your server in the public server list that the
- @code{mumble} client shows on startup.
- You cannot register your server if you have set a @code{server-password},
- or set @code{allow-ping} to @code{#f}.
- It might take a few hours until it shows up in the public list.
- @item @code{file} (default: @code{#f})
- Optional alternative override for this configuration.
- @end table
- @end deftp
- @deftp {Data Type} murmur-public-registration-configuration
- Configuration for public registration of a murmur service.
- @table @asis
- @item @code{name}
- This is a display name for your server. Not to be confused with the hostname.
- @item @code{password}
- A password to identify your registration.
- Subsequent updates will need the same password. Don't lose your password.
- @item @code{url}
- This should be a @code{http://} or @code{https://} link to your web
- site.
- @item @code{hostname} (default: @code{#f})
- By default your server will be listed by its IP address.
- If it is set your server will be linked by this host name instead.
- @end table
- @end deftp
- @node File-Sharing Services
- @subsection File-Sharing Services
- The @code{(gnu services file-sharing)} module provides services that
- assist with transferring files over peer-to-peer file-sharing networks.
- @subsubheading Transmission Daemon Service
- @uref{https://transmissionbt.com/, Transmission} is a flexible
- BitTorrent client that offers a variety of graphical and command-line
- interfaces. A @code{transmission-daemon-service-type} service provides
- Transmission's headless variant, @command{transmission-daemon}, as a
- system service, allowing users to share files via BitTorrent even when
- they are not logged in.
- @deffn {Scheme Variable} transmission-daemon-service-type
- The service type for the Transmission Daemon BitTorrent client. Its
- value must be a @code{transmission-daemon-configuration} object as in
- this example:
- @lisp
- (service transmission-daemon-service-type
- (transmission-daemon-configuration
- ;; Restrict access to the RPC ("control") interface
- (rpc-authentication-required? #t)
- (rpc-username "transmission")
- (rpc-password
- (transmission-password-hash
- "transmission" ; desired password
- "uKd1uMs9")) ; arbitrary salt value
- ;; Accept requests from this and other hosts on the
- ;; local network
- (rpc-whitelist-enabled? #t)
- (rpc-whitelist '("::1" "127.0.0.1" "192.168.0.*"))
- ;; Limit bandwidth use during work hours
- (alt-speed-down (* 1024 2)) ; 2 MB/s
- (alt-speed-up 512) ; 512 kB/s
- (alt-speed-time-enabled? #t)
- (alt-speed-time-day 'weekdays)
- (alt-speed-time-begin
- (+ (* 60 8) 30)) ; 8:30 am
- (alt-speed-time-end
- (+ (* 60 (+ 12 5)) 30)))) ; 5:30 pm
- @end lisp
- @end deffn
- Once the service is started, users can interact with the daemon through
- its Web interface (at @code{http://localhost:9091/}) or by using the
- @command{transmission-remote} command-line tool, available in the
- @code{transmission} package. (Emacs users may want to also consider the
- @code{emacs-transmission} package.) Both communicate with the daemon
- through its remote procedure call (RPC) interface, which by default is
- available to all users on the system; you may wish to change this by
- assigning values to the @code{rpc-authentication-required?},
- @code{rpc-username} and @code{rpc-password} settings, as shown in the
- example above and documented further below.
- The value for @code{rpc-password} must be a password hash of the type
- generated and used by Transmission clients. This can be copied verbatim
- from an existing @file{settings.json} file, if another Transmission
- client is already being used. Otherwise, the
- @code{transmission-password-hash} and @code{transmission-random-salt}
- procedures provided by this module can be used to obtain a suitable hash
- value.
- @deffn {Scheme Procedure} transmission-password-hash @var{password} @var{salt}
- Returns a string containing the result of hashing @var{password}
- together with @var{salt}, in the format recognized by Transmission
- clients for their @code{rpc-password} configuration setting.
- @var{salt} must be an eight-character string. The
- @code{transmission-random-salt} procedure can be used to generate a
- suitable salt value at random.
- @end deffn
- @deffn {Scheme Procedure} transmission-random-salt
- Returns a string containing a random, eight-character salt value of the
- type generated and used by Transmission clients, suitable for passing to
- the @code{transmission-password-hash} procedure.
- @end deffn
- These procedures are accessible from within a Guile REPL started with
- the @command{guix repl} command (@pxref{Invoking guix repl}). This is
- useful for obtaining a random salt value to provide as the second
- parameter to `transmission-password-hash`, as in this example session:
- @example
- $ guix repl
- scheme@@(guix-user)> ,use (gnu services file-sharing)
- scheme@@(guix-user)> (transmission-random-salt)
- $1 = "uKd1uMs9"
- @end example
- Alternatively, a complete password hash can generated in a single step:
- @example
- scheme@@(guix-user)> (transmission-password-hash "transmission"
- (transmission-random-salt))
- $2 = "@{c8bbc6d1740cd8dc819a6e25563b67812c1c19c9VtFPfdsX"
- @end example
- The resulting string can be used as-is for the value of
- @code{rpc-password}, allowing the password to be kept hidden even in the
- operating-system configuration.
- Torrent files downloaded by the daemon are directly accessible only to
- users in the ``transmission'' user group, who receive read-only access
- to the directory specified by the @code{download-dir} configuration
- setting (and also the directory specified by @code{incomplete-dir}, if
- @code{incomplete-dir-enabled?} is @code{#t}). Downloaded files can be
- moved to another directory or deleted altogether using
- @command{transmission-remote} with its @code{--move} and
- @code{--remove-and-delete} options.
- If the @code{watch-dir-enabled?} setting is set to @code{#t}, users in
- the ``transmission'' group are able also to place @file{.torrent} files
- in the directory specified by @code{watch-dir} to have the corresponding
- torrents added by the daemon. (The @code{trash-original-torrent-files?}
- setting controls whether the daemon deletes these files after processing
- them.)
- Some of the daemon's configuration settings can be changed temporarily
- by @command{transmission-remote} and similar tools. To undo these
- changes, use the service's @code{reload} action to have the daemon
- reload its settings from disk:
- @example
- # herd reload transmission-daemon
- @end example
- The full set of available configuration settings is defined by the
- @code{transmission-daemon-configuration} data type.
- @deftp {Data Type} transmission-daemon-configuration
- The data type representing configuration settings for Transmission
- Daemon. These correspond directly to the settings recognized by
- Transmission clients in their @file{settings.json} file.
- @end deftp
- @c The following documentation was initially generated by
- @c (generate-transmission-daemon-documentation) in (gnu services
- @c file-sharing). Manually maintained documentation is better, so we
- @c shouldn't hesitate to edit below as needed. However if the change
- @c you want to make to this documentation can be done in an automated
- @c way, it's probably easier to change (generate-documentation) than to
- @c make it below and have to deal with the churn as Transmission Daemon
- @c updates.
- @c %start of fragment
- Available @code{transmission-daemon-configuration} fields are:
- @deftypevr {@code{transmission-daemon-configuration} parameter} package transmission
- The Transmission package to use.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer stop-wait-period
- The period, in seconds, to wait when stopping the service for
- @command{transmission-daemon} to exit before killing its process. This
- allows the daemon time to complete its housekeeping and send a final
- update to trackers as it shuts down. On slow hosts, or hosts with a
- slow network connection, this value may need to be increased.
- Defaults to @samp{10}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} string download-dir
- The directory to which torrent files are downloaded.
- Defaults to @samp{"/var/lib/transmission-daemon/downloads"}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} boolean incomplete-dir-enabled?
- If @code{#t}, files will be held in @code{incomplete-dir} while their
- torrent is being downloaded, then moved to @code{download-dir} once the
- torrent is complete. Otherwise, files for all torrents (including those
- still being downloaded) will be placed in @code{download-dir}.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} maybe-string incomplete-dir
- The directory in which files from incompletely downloaded torrents will
- be held when @code{incomplete-dir-enabled?} is @code{#t}.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} umask umask
- The file mode creation mask used for downloaded files. (See the
- @command{umask} man page for more information.)
- Defaults to @samp{18}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} boolean rename-partial-files?
- When @code{#t}, ``.part'' is appended to the name of partially
- downloaded files.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} preallocation-mode preallocation
- The mode by which space should be preallocated for downloaded files, one
- of @code{none}, @code{fast} (or @code{sparse}) and @code{full}.
- Specifying @code{full} will minimize disk fragmentation at a cost to
- file-creation speed.
- Defaults to @samp{fast}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} boolean watch-dir-enabled?
- If @code{#t}, the directory specified by @code{watch-dir} will be
- watched for new @file{.torrent} files and the torrents they describe
- added automatically (and the original files removed, if
- @code{trash-original-torrent-files?} is @code{#t}).
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} maybe-string watch-dir
- The directory to be watched for @file{.torrent} files indicating new
- torrents to be added, when @code{watch-dir-enabled} is @code{#t}.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} boolean trash-original-torrent-files?
- When @code{#t}, @file{.torrent} files will be deleted from the watch
- directory once their torrent has been added (see
- @code{watch-directory-enabled?}).
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} boolean speed-limit-down-enabled?
- When @code{#t}, the daemon's download speed will be limited to the rate
- specified by @code{speed-limit-down}.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer speed-limit-down
- The default global-maximum download speed, in kilobytes per second.
- Defaults to @samp{100}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} boolean speed-limit-up-enabled?
- When @code{#t}, the daemon's upload speed will be limited to the rate
- specified by @code{speed-limit-up}.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer speed-limit-up
- The default global-maximum upload speed, in kilobytes per second.
- Defaults to @samp{100}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} boolean alt-speed-enabled?
- When @code{#t}, the alternate speed limits @code{alt-speed-down} and
- @code{alt-speed-up} are used (in place of @code{speed-limit-down} and
- @code{speed-limit-up}, if they are enabled) to constrain the daemon's
- bandwidth usage. This can be scheduled to occur automatically at
- certain times during the week; see @code{alt-speed-time-enabled?}.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer alt-speed-down
- The alternate global-maximum download speed, in kilobytes per second.
- Defaults to @samp{50}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer alt-speed-up
- The alternate global-maximum upload speed, in kilobytes per second.
- Defaults to @samp{50}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} boolean alt-speed-time-enabled?
- When @code{#t}, the alternate speed limits @code{alt-speed-down} and
- @code{alt-speed-up} will be enabled automatically during the periods
- specified by @code{alt-speed-time-day}, @code{alt-speed-time-begin} and
- @code{alt-time-speed-end}.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} day-list alt-speed-time-day
- The days of the week on which the alternate-speed schedule should be
- used, specified either as a list of days (@code{sunday}, @code{monday},
- and so on) or using one of the symbols @code{weekdays}, @code{weekends}
- or @code{all}.
- Defaults to @samp{all}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer alt-speed-time-begin
- The time of day at which to enable the alternate speed limits, expressed
- as a number of minutes since midnight.
- Defaults to @samp{540}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer alt-speed-time-end
- The time of day at which to disable the alternate speed limits,
- expressed as a number of minutes since midnight.
- Defaults to @samp{1020}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} string bind-address-ipv4
- The IP address at which to listen for peer connections, or ``0.0.0.0''
- to listen at all available IP addresses.
- Defaults to @samp{"0.0.0.0"}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} string bind-address-ipv6
- The IPv6 address at which to listen for peer connections, or ``::'' to
- listen at all available IPv6 addresses.
- Defaults to @samp{"::"}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} boolean peer-port-random-on-start?
- If @code{#t}, when the daemon starts it will select a port at random on
- which to listen for peer connections, from the range specified
- (inclusively) by @code{peer-port-random-low} and
- @code{peer-port-random-high}. Otherwise, it listens on the port
- specified by @code{peer-port}.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} port-number peer-port-random-low
- The lowest selectable port number when @code{peer-port-random-on-start?}
- is @code{#t}.
- Defaults to @samp{49152}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} port-number peer-port-random-high
- The highest selectable port number when @code{peer-port-random-on-start}
- is @code{#t}.
- Defaults to @samp{65535}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} port-number peer-port
- The port on which to listen for peer connections when
- @code{peer-port-random-on-start?} is @code{#f}.
- Defaults to @samp{51413}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} boolean port-forwarding-enabled?
- If @code{#t}, the daemon will attempt to configure port-forwarding on an
- upstream gateway automatically using @acronym{UPnP} and
- @acronym{NAT-PMP}.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} encryption-mode encryption
- The encryption preference for peer connections, one of
- @code{prefer-unencrypted-connections},
- @code{prefer-encrypted-connections} or
- @code{require-encrypted-connections}.
- Defaults to @samp{prefer-encrypted-connections}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} maybe-string peer-congestion-algorithm
- The TCP congestion-control algorithm to use for peer connections,
- specified using a string recognized by the operating system in calls to
- @code{setsockopt} (or set to @code{disabled}, in which case the
- operating-system default is used).
- Note that on GNU/Linux systems, the kernel must be configured to allow
- processes to use a congestion-control algorithm not in the default set;
- otherwise, it will deny these requests with ``Operation not permitted''.
- To see which algorithms are available on your system and which are
- currently permitted for use, look at the contents of the files
- @file{tcp_available_congestion_control} and
- @file{tcp_allowed_congestion_control} in the @file{/proc/sys/net/ipv4}
- directory.
- As an example, to have Transmission Daemon use
- @uref{http://www-ece.rice.edu/networks/TCP-LP/,the TCP Low Priority
- congestion-control algorithm}, you'll need to modify your kernel
- configuration to build in support for the algorithm, then update your
- operating-system configuration to allow its use by adding a
- @code{sysctl-service-type} service (or updating the existing one's
- configuration) with lines like the following:
- @lisp
- (service sysctl-service-type
- (sysctl-configuration
- (settings
- ("net.ipv4.tcp_allowed_congestion_control" .
- "reno cubic lp"))))
- @end lisp
- The Transmission Daemon configuration can then be updated with
- @lisp
- (peer-congestion-algorithm "lp")
- @end lisp
- and the system reconfigured to have the changes take effect.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} tcp-type-of-service peer-socket-tos
- The type of service to request in outgoing @acronym{TCP} packets, one of
- @code{default}, @code{low-cost}, @code{throughput}, @code{low-delay} and
- @code{reliability}.
- Defaults to @samp{default}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer peer-limit-global
- The global limit on the number of connected peers.
- Defaults to @samp{200}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer peer-limit-per-torrent
- The per-torrent limit on the number of connected peers.
- Defaults to @samp{50}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer upload-slots-per-torrent
- The maximum number of peers to which the daemon will upload data
- simultaneously for each torrent.
- Defaults to @samp{14}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer peer-id-ttl-hours
- The maximum lifespan, in hours, of the peer ID associated with each
- public torrent before it is regenerated.
- Defaults to @samp{6}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} boolean blocklist-enabled?
- When @code{#t}, the daemon will ignore peers mentioned in the blocklist
- it has most recently downloaded from @code{blocklist-url}.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} maybe-string blocklist-url
- The URL of a peer blocklist (in @acronym{P2P}-plaintext or eMule
- @file{.dat} format) to be periodically downloaded and applied when
- @code{blocklist-enabled?} is @code{#t}.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} boolean download-queue-enabled?
- If @code{#t}, the daemon will be limited to downloading at most
- @code{download-queue-size} non-stalled torrents simultaneously.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer download-queue-size
- The size of the daemon's download queue, which limits the number of
- non-stalled torrents it will download at any one time when
- @code{download-queue-enabled?} is @code{#t}.
- Defaults to @samp{5}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} boolean seed-queue-enabled?
- If @code{#t}, the daemon will be limited to seeding at most
- @code{seed-queue-size} non-stalled torrents simultaneously.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer seed-queue-size
- The size of the daemon's seed queue, which limits the number of
- non-stalled torrents it will seed at any one time when
- @code{seed-queue-enabled?} is @code{#t}.
- Defaults to @samp{10}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} boolean queue-stalled-enabled?
- When @code{#t}, the daemon will consider torrents for which it has not
- shared data in the past @code{queue-stalled-minutes} minutes to be
- stalled and not count them against its @code{download-queue-size} and
- @code{seed-queue-size} limits.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer queue-stalled-minutes
- The maximum period, in minutes, a torrent may be idle before it is
- considered to be stalled, when @code{queue-stalled-enabled?} is
- @code{#t}.
- Defaults to @samp{30}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} boolean ratio-limit-enabled?
- When @code{#t}, a torrent being seeded will automatically be paused once
- it reaches the ratio specified by @code{ratio-limit}.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-rational ratio-limit
- The ratio at which a torrent being seeded will be paused, when
- @code{ratio-limit-enabled?} is @code{#t}.
- Defaults to @samp{2.0}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} boolean idle-seeding-limit-enabled?
- When @code{#t}, a torrent being seeded will automatically be paused once
- it has been idle for @code{idle-seeding-limit} minutes.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer idle-seeding-limit
- The maximum period, in minutes, a torrent being seeded may be idle
- before it is paused, when @code{idle-seeding-limit-enabled?} is
- @code{#t}.
- Defaults to @samp{30}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} boolean dht-enabled?
- Enable @uref{http://bittorrent.org/beps/bep_0005.html,the distributed
- hash table (@acronym{DHT}) protocol}, which supports the use of
- trackerless torrents.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} boolean lpd-enabled?
- Enable @uref{https://en.wikipedia.org/wiki/Local_Peer_Discovery,local
- peer discovery} (@acronym{LPD}), which allows the discovery of peers on
- the local network and may reduce the amount of data sent over the public
- Internet.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} boolean pex-enabled?
- Enable @uref{https://en.wikipedia.org/wiki/Peer_exchange,peer exchange}
- (@acronym{PEX}), which reduces the daemon's reliance on external
- trackers and may improve its performance.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} boolean utp-enabled?
- Enable @uref{http://bittorrent.org/beps/bep_0029.html,the micro
- transport protocol} (@acronym{uTP}), which aims to reduce the impact of
- BitTorrent traffic on other users of the local network while maintaining
- full utilization of the available bandwidth.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} boolean rpc-enabled?
- If @code{#t}, enable the remote procedure call (@acronym{RPC})
- interface, which allows remote control of the daemon via its Web
- interface, the @command{transmission-remote} command-line client, and
- similar tools.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} string rpc-bind-address
- The IP address at which to listen for @acronym{RPC} connections, or
- ``0.0.0.0'' to listen at all available IP addresses.
- Defaults to @samp{"0.0.0.0"}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} port-number rpc-port
- The port on which to listen for @acronym{RPC} connections.
- Defaults to @samp{9091}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} string rpc-url
- The path prefix to use in the @acronym{RPC}-endpoint @acronym{URL}.
- Defaults to @samp{"/transmission/"}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} boolean rpc-authentication-required?
- When @code{#t}, clients must authenticate (see @code{rpc-username} and
- @code{rpc-password}) when using the @acronym{RPC} interface. Note this
- has the side effect of disabling host-name whitelisting (see
- @code{rpc-host-whitelist-enabled?}.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} maybe-string rpc-username
- The username required by clients to access the @acronym{RPC} interface
- when @code{rpc-authentication-required?} is @code{#t}.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} maybe-transmission-password-hash rpc-password
- The password required by clients to access the @acronym{RPC} interface
- when @code{rpc-authentication-required?} is @code{#t}. This must be
- specified using a password hash in the format recognized by Transmission
- clients, either copied from an existing @file{settings.json} file or
- generated using the @code{transmission-password-hash} procedure.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} boolean rpc-whitelist-enabled?
- When @code{#t}, @acronym{RPC} requests will be accepted only when they
- originate from an address specified in @code{rpc-whitelist}.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} string-list rpc-whitelist
- The list of IP and IPv6 addresses from which @acronym{RPC} requests will
- be accepted when @code{rpc-whitelist-enabled?} is @code{#t}. Wildcards
- may be specified using @samp{*}.
- Defaults to @samp{("127.0.0.1" "::1")}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} boolean rpc-host-whitelist-enabled?
- When @code{#t}, @acronym{RPC} requests will be accepted only when they
- are addressed to a host named in @code{rpc-host-whitelist}. Note that
- requests to ``localhost'' or ``localhost.'', or to a numeric address,
- are always accepted regardless of these settings.
- Note also this functionality is disabled when
- @code{rpc-authentication-required?} is @code{#t}.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} string-list rpc-host-whitelist
- The list of host names recognized by the @acronym{RPC} server when
- @code{rpc-host-whitelist-enabled?} is @code{#t}.
- Defaults to @samp{()}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} message-level message-level
- The minimum severity level of messages to be logged (to
- @file{/var/log/transmission.log}) by the daemon, one of @code{none} (no
- logging), @code{error}, @code{info} and @code{debug}.
- Defaults to @samp{info}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} boolean start-added-torrents?
- When @code{#t}, torrents are started as soon as they are added;
- otherwise, they are added in ``paused'' state.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} boolean script-torrent-done-enabled?
- When @code{#t}, the script specified by
- @code{script-torrent-done-filename} will be invoked each time a torrent
- completes.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} maybe-file-object script-torrent-done-filename
- A file name or file-like object specifying a script to run each time a
- torrent completes, when @code{script-torrent-done-enabled?} is
- @code{#t}.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} boolean scrape-paused-torrents-enabled?
- When @code{#t}, the daemon will scrape trackers for a torrent even when
- the torrent is paused.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer cache-size-mb
- The amount of memory, in megabytes, to allocate for the daemon's
- in-memory cache. A larger value may increase performance by reducing
- the frequency of disk I/O.
- Defaults to @samp{4}.
- @end deftypevr
- @deftypevr {@code{transmission-daemon-configuration} parameter} boolean prefetch-enabled?
- When @code{#t}, the daemon will try to improve I/O performance by
- hinting to the operating system which data is likely to be read next
- from disk to satisfy requests from peers.
- Defaults to @samp{#t}.
- @end deftypevr
- @c %end of fragment
- @node Monitoring Services
- @subsection Monitoring Services
- @subsubheading Tailon Service
- @uref{https://tailon.readthedocs.io/, Tailon} is a web application for
- viewing and searching log files.
- The following example will configure the service with default values.
- By default, Tailon can be accessed on port 8080 (@code{http://localhost:8080}).
- @lisp
- (service tailon-service-type)
- @end lisp
- The following example customises more of the Tailon configuration,
- adding @command{sed} to the list of allowed commands.
- @lisp
- (service tailon-service-type
- (tailon-configuration
- (config-file
- (tailon-configuration-file
- (allowed-commands '("tail" "grep" "awk" "sed"))))))
- @end lisp
- @deftp {Data Type} tailon-configuration
- Data type representing the configuration of Tailon.
- This type has the following parameters:
- @table @asis
- @item @code{config-file} (default: @code{(tailon-configuration-file)})
- The configuration file to use for Tailon. This can be set to a
- @dfn{tailon-configuration-file} record value, or any gexp
- (@pxref{G-Expressions}).
- For example, to instead use a local file, the @code{local-file} function
- can be used:
- @lisp
- (service tailon-service-type
- (tailon-configuration
- (config-file (local-file "./my-tailon.conf"))))
- @end lisp
- @item @code{package} (default: @code{tailon})
- The tailon package to use.
- @end table
- @end deftp
- @deftp {Data Type} tailon-configuration-file
- Data type representing the configuration options for Tailon.
- This type has the following parameters:
- @table @asis
- @item @code{files} (default: @code{(list "/var/log")})
- List of files to display. The list can include strings for a single file
- or directory, or a list, where the first item is the name of a
- subsection, and the remaining items are the files or directories in that
- subsection.
- @item @code{bind} (default: @code{"localhost:8080"})
- Address and port to which Tailon should bind on.
- @item @code{relative-root} (default: @code{#f})
- URL path to use for Tailon, set to @code{#f} to not use a path.
- @item @code{allow-transfers?} (default: @code{#t})
- Allow downloading the log files in the web interface.
- @item @code{follow-names?} (default: @code{#t})
- Allow tailing of not-yet existent files.
- @item @code{tail-lines} (default: @code{200})
- Number of lines to read initially from each file.
- @item @code{allowed-commands} (default: @code{(list "tail" "grep" "awk")})
- Commands to allow running. By default, @code{sed} is disabled.
- @item @code{debug?} (default: @code{#f})
- Set @code{debug?} to @code{#t} to show debug messages.
- @item @code{wrap-lines} (default: @code{#t})
- Initial line wrapping state in the web interface. Set to @code{#t} to
- initially wrap lines (the default), or to @code{#f} to initially not
- wrap lines.
- @item @code{http-auth} (default: @code{#f})
- HTTP authentication type to use. Set to @code{#f} to disable
- authentication (the default). Supported values are @code{"digest"} or
- @code{"basic"}.
- @item @code{users} (default: @code{#f})
- If HTTP authentication is enabled (see @code{http-auth}), access will be
- restricted to the credentials provided here. To configure users, use a
- list of pairs, where the first element of the pair is the username, and
- the 2nd element of the pair is the password.
- @lisp
- (tailon-configuration-file
- (http-auth "basic")
- (users '(("user1" . "password1")
- ("user2" . "password2"))))
- @end lisp
- @end table
- @end deftp
- @subsubheading Darkstat Service
- @cindex darkstat
- Darkstat is a packet sniffer that captures network traffic, calculates
- statistics about usage, and serves reports over HTTP.
- @defvar {Scheme Variable} darkstat-service-type
- This is the service type for the
- @uref{https://unix4lyfe.org/darkstat/, darkstat}
- service, its value must be a @code{darkstat-configuration} record as in
- this example:
- @lisp
- (service darkstat-service-type
- (darkstat-configuration
- (interface "eno1")))
- @end lisp
- @end defvar
- @deftp {Data Type} darkstat-configuration
- Data type representing the configuration of @command{darkstat}.
- @table @asis
- @item @code{package} (default: @code{darkstat})
- The darkstat package to use.
- @item @code{interface}
- Capture traffic on the specified network interface.
- @item @code{port} (default: @code{"667"})
- Bind the web interface to the specified port.
- @item @code{bind-address} (default: @code{"127.0.0.1"})
- Bind the web interface to the specified address.
- @item @code{base} (default: @code{"/"})
- Specify the path of the base URL@. This can be useful if
- @command{darkstat} is accessed via a reverse proxy.
- @end table
- @end deftp
- @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
- @anchor{NGINX}
- @subsubheading NGINX
- @deffn {Scheme Variable} nginx-service-type
- Service type for the @uref{https://nginx.org/,NGinx} web server. The
- value for this service type is a @code{<nginx-configuration>} record.
- A simple example configuration is given below.
- @lisp
- (service nginx-service-type
- (nginx-configuration
- (server-blocks
- (list (nginx-server-configuration
- (server-name '("www.example.com"))
- (root "/srv/http/www.example.com"))))))
- @end lisp
- In addition to adding server blocks to the service configuration
- directly, this service can be extended by other services to add server
- blocks, as in this example:
- @lisp
- (simple-service 'my-extra-server nginx-service-type
- (list (nginx-server-configuration
- (root "/srv/http/extra-website")
- (try-files (list "$uri" "$uri/index.html")))))
- @end lisp
- @end deffn
- At startup, @command{nginx} has not yet read its configuration file, so
- it uses a default file to log error messages. If it fails to load its
- configuration file, that is where error messages are logged. After the
- configuration file is loaded, the default error log file changes as per
- configuration. In our case, startup error messages can be found in
- @file{/var/run/nginx/logs/error.log}, and after configuration in
- @file{/var/log/nginx/error.log}. The second location can be changed
- with the @var{log-directory} configuration option.
- @deffn {Data Type} nginx-configuration
- This data type represents the configuration for NGinx. Some
- configuration can be done through this and the other provided record
- types, or alternatively, a config file can be provided.
- @table @asis
- @item @code{nginx} (default: @code{nginx})
- The nginx package to use.
- @item @code{log-directory} (default: @code{"/var/log/nginx"})
- The directory to which NGinx will write log files.
- @item @code{run-directory} (default: @code{"/var/run/nginx"})
- The directory in which NGinx will create a pid file, and write temporary
- files.
- @item @code{server-blocks} (default: @code{'()})
- A list of @dfn{server blocks} to create in the generated configuration
- file, the elements should be of type
- @code{<nginx-server-configuration>}.
- The following example would setup NGinx to serve @code{www.example.com}
- from the @code{/srv/http/www.example.com} directory, without using
- HTTPS.
- @lisp
- (service nginx-service-type
- (nginx-configuration
- (server-blocks
- (list (nginx-server-configuration
- (server-name '("www.example.com"))
- (root "/srv/http/www.example.com"))))))
- @end lisp
- @item @code{upstream-blocks} (default: @code{'()})
- A list of @dfn{upstream blocks} to create in the generated configuration
- file, the elements should be of type
- @code{<nginx-upstream-configuration>}.
- Configuring upstreams through the @code{upstream-blocks} can be useful
- when combined with @code{locations} in the
- @code{<nginx-server-configuration>} records. The following example
- creates a server configuration with one location configuration, that
- will proxy requests to a upstream configuration, which will handle
- requests with two servers.
- @lisp
- (service
- nginx-service-type
- (nginx-configuration
- (server-blocks
- (list (nginx-server-configuration
- (server-name '("www.example.com"))
- (root "/srv/http/www.example.com")
- (locations
- (list
- (nginx-location-configuration
- (uri "/path1")
- (body '("proxy_pass http://server-proxy;"))))))))
- (upstream-blocks
- (list (nginx-upstream-configuration
- (name "server-proxy")
- (servers (list "server1.example.com"
- "server2.example.com")))))))
- @end lisp
- @item @code{file} (default: @code{#f})
- If a configuration @var{file} is provided, this will be used, rather than
- generating a configuration file from the provided @code{log-directory},
- @code{run-directory}, @code{server-blocks} and @code{upstream-blocks}. For
- proper operation, these arguments should match what is in @var{file} to ensure
- that the directories are created when the service is activated.
- This can be useful if you have an existing configuration file, or it's
- not possible to do what is required through the other parts of the
- nginx-configuration record.
- @item @code{server-names-hash-bucket-size} (default: @code{#f})
- Bucket size for the server names hash tables, defaults to @code{#f} to
- use the size of the processors cache line.
- @item @code{server-names-hash-bucket-max-size} (default: @code{#f})
- Maximum bucket size for the server names hash tables.
- @item @code{modules} (default: @code{'()})
- List of nginx dynamic modules to load. This should be a list of file
- names of loadable modules, as in this example:
- @lisp
- (modules
- (list
- (file-append nginx-accept-language-module "\
- /etc/nginx/modules/ngx_http_accept_language_module.so")
- (file-append nginx-lua-module "\
- /etc/nginx/modules/ngx_http_lua_module.so")))
- @end lisp
- @item @code{lua-package-path} (default: @code{'()})
- List of nginx lua packages to load. This should be a list of package
- names of loadable lua modules, as in this example:
- @lisp
- (lua-package-path (list lua-resty-core
- lua-resty-lrucache
- lua-resty-signal
- lua-tablepool
- lua-resty-shell))
- @end lisp
- @item @code{lua-package-cpath} (default: @code{'()})
- List of nginx lua C packages to load. This should be a list of package
- names of loadable lua C modules, as in this example:
- @lisp
- (lua-package-cpath (list lua-resty-signal))
- @end lisp
- @item @code{global-directives} (default: @code{'((events . ()))})
- Association list of global directives for the top level of the nginx
- configuration. Values may themselves be association lists.
- @lisp
- (global-directives
- `((worker_processes . 16)
- (pcre_jit . on)
- (events . ((worker_connections . 1024)))))
- @end lisp
- @item @code{extra-content} (default: @code{""})
- Extra content for the @code{http} block. Should be string or a string
- valued G-expression.
- @end table
- @end deffn
- @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 its configured limits.
- @table @asis
- @item @code{max-children} (default: @code{5})
- Maximum of worker processes.
- @item @code{start-servers} (default: @code{2})
- How many worker processes should be started on start-up.
- @item @code{min-spare-servers} (default: @code{1})
- How many spare worker processes should be kept around at minimum.
- @item @code{max-spare-servers} (default: @code{3})
- How many spare worker processes should be kept around at maximum.
- @end table
- @end deftp
- @deftp {Data type} php-fpm-static-process-manager-configuration
- Data Type for the @code{static} php-fpm process manager. With the
- @code{static} process manager, an unchanging number of worker processes
- are created.
- @table @asis
- @item @code{max-children} (default: @code{5})
- Maximum of worker processes.
- @end table
- @end deftp
- @deftp {Data type} php-fpm-on-demand-process-manager-configuration
- Data Type for the @code{on-demand} php-fpm process manager. With the
- @code{on-demand} process manager, worker processes are only created as
- requests arrive.
- @table @asis
- @item @code{max-children} (default: @code{5})
- Maximum of worker processes.
- @item @code{process-idle-timeout} (default: @code{10})
- The time in seconds after which a process with no requests is killed.
- @end table
- @end deftp
- @deffn {Scheme Procedure} nginx-php-location @
- [#:nginx-package nginx] @
- [socket (string-append "/var/run/php" @
- (version-major (package-version php)) @
- "-fpm.sock")]
- A helper function to quickly add php to an @code{nginx-server-configuration}.
- @end deffn
- A simple services setup for nginx with php can look like this:
- @lisp
- (services (cons* (service dhcp-client-service-type)
- (service php-fpm-service-type)
- (service nginx-service-type
- (nginx-server-configuration
- (server-name '("example.com"))
- (root "/srv/http/")
- (locations
- (list (nginx-php-location)))
- (listen '("80"))
- (ssl-certificate #f)
- (ssl-certificate-key #f)))
- %base-services))
- @end lisp
- @cindex cat-avatar-generator
- The cat avatar generator is a simple service to demonstrate the use of php-fpm
- in @code{Nginx}. It is used to generate cat avatar from a seed, for instance
- the hash of a user's email address.
- @deffn {Scheme Procedure} cat-avatar-generator-service @
- [#:cache-dir "/var/cache/cat-avatar-generator"] @
- [#:package cat-avatar-generator] @
- [#:configuration (nginx-server-configuration)]
- Returns an nginx-server-configuration that inherits @code{configuration}. It
- extends the nginx configuration to add a server block that serves @code{package},
- a version of cat-avatar-generator. During execution, cat-avatar-generator will
- be able to use @code{cache-dir} as its cache directory.
- @end deffn
- A simple setup for cat-avatar-generator can look like this:
- @lisp
- (services (cons* (cat-avatar-generator-service
- #:configuration
- (nginx-server-configuration
- (server-name '("example.com"))))
- ...
- %base-services))
- @end lisp
- @subsubheading Hpcguix-web
- @cindex hpcguix-web
- The @uref{https://github.com/UMCUGenetics/hpcguix-web/, hpcguix-web}
- program is a customizable web interface to browse Guix packages,
- initially designed for users of high-performance computing (HPC)
- clusters.
- @defvr {Scheme Variable} hpcguix-web-service-type
- The service type for @code{hpcguix-web}.
- @end defvr
- @deftp {Data Type} hpcguix-web-configuration
- Data type for the hpcguix-web service configuration.
- @table @asis
- @item @code{specs}
- A gexp (@pxref{G-Expressions}) specifying the hpcguix-web service
- configuration. The main items available in this spec are:
- @table @asis
- @item @code{title-prefix} (default: @code{"hpcguix | "})
- The page title prefix.
- @item @code{guix-command} (default: @code{"guix"})
- The @command{guix} command.
- @item @code{package-filter-proc} (default: @code{(const #t)})
- A procedure specifying how to filter packages that are displayed.
- @item @code{package-page-extension-proc} (default: @code{(const '())})
- Extension package for @code{hpcguix-web}.
- @item @code{menu} (default: @code{'()})
- Additional entry in page @code{menu}.
- @item @code{channels} (default: @code{%default-channels})
- List of channels from which the package list is built (@pxref{Channels}).
- @item @code{package-list-expiration} (default: @code{(* 12 3600)})
- The expiration time, in seconds, after which the package list is rebuilt from
- the latest instances of the given channels.
- @end table
- See the hpcguix-web repository for a
- @uref{https://github.com/UMCUGenetics/hpcguix-web/blob/master/hpcweb-configuration.scm,
- complete example}.
- @item @code{package} (default: @code{hpcguix-web})
- The hpcguix-web package to use.
- @end table
- @end deftp
- A typical hpcguix-web service declaration looks like this:
- @lisp
- (service hpcguix-web-service-type
- (hpcguix-web-configuration
- (specs
- #~(define site-config
- (hpcweb-configuration
- (title-prefix "Guix-HPC - ")
- (menu '(("/about" "ABOUT"))))))))
- @end lisp
- @quotation Note
- The hpcguix-web service periodically updates the package list it publishes by
- pulling channels from Git. To that end, it needs to access X.509 certificates
- so that it can authenticate Git servers when communicating over HTTPS, and it
- assumes that @file{/etc/ssl/certs} contains those certificates.
- Thus, make sure to add @code{nss-certs} or another certificate package to the
- @code{packages} field of your configuration. @ref{X.509 Certificates}, for
- more information on X.509 certificates.
- @end quotation
- @subsubheading gmnisrv
- @cindex gmnisrv
- The @uref{https://git.sr.ht/~sircmpwn/gmnisrv, gmnisrv} program is a
- simple @uref{https://gemini.circumlunar.space/, Gemini} protocol server.
- @deffn {Scheme Variable} gmnisrv-service-type
- This is the type of the gmnisrv service, whose value should be a
- @code{gmnisrv-configuration} object, as in this example:
- @lisp
- (service gmnisrv-service-type
- (gmnisrv-configuration
- (config-file (local-file "./my-gmnisrv.ini"))))
- @end lisp
- @end deffn
- @deftp {Data Type} gmnisrv-configuration
- Data type representing the configuration of gmnisrv.
- @table @asis
- @item @code{package} (default: @var{gmnisrv})
- Package object of the gmnisrv server.
- @item @code{config-file} (default: @code{%default-gmnisrv-config-file})
- File-like object of the gmnisrv configuration file to use. The default
- configuration listens on port 1965 and serves files from
- @file{/srv/gemini}. Certificates are stored in
- @file{/var/lib/gemini/certs}. For more information, run @command{man
- gmnisrv} and @command{man gmnisrv.ini}.
- @end table
- @end deftp
- @subsubheading Agate
- @cindex agate
- The @uref{gemini://qwertqwefsday.eu/agate.gmi, Agate}
- (@uref{https://github.com/mbrubeck/agate, GitHub page over HTTPS})
- program is a simple @uref{https://gemini.circumlunar.space/, Gemini}
- protocol server written in Rust.
- @deffn {Scheme Variable} agate-service-type
- This is the type of the agate service, whose value should be an
- @code{agate-service-type} object, as in this example:
- @lisp
- (service agate-service-type
- (agate-configuration
- (content "/srv/gemini")
- (cert "/srv/cert.pem")
- (key "/srv/key.rsa")))
- @end lisp
- The example above represents the minimal tweaking necessary to get Agate
- up and running. Specifying the path to the certificate and key is
- always necessary, as the Gemini protocol requires TLS by default.
- To obtain a certificate and a key, you could, for example, use OpenSSL,
- running a command similar to the following example:
- @example
- openssl req -x509 -newkey rsa:4096 -keyout key.rsa -out cert.pem \
- -days 3650 -nodes -subj "/CN=example.com"
- @end example
- Of course, you'll have to replace @i{example.com} with your own domain
- name, and then point the Agate configuration towards the path of the
- generated key and certificate.
- @end deffn
- @deftp {Data Type} agate-configuration
- Data type representing the configuration of Agate.
- @table @asis
- @item @code{package} (default: @code{agate})
- The package object of the Agate server.
- @item @code{content} (default: @file{"/srv/gemini"})
- The directory from which Agate will serve files.
- @item @code{cert} (default: @code{#f})
- The path to the TLS certificate PEM file to be used for encrypted
- connections. Must be filled in with a value from the user.
- @item @code{key} (default: @code{#f})
- The path to the PKCS8 private key file to be used for encrypted
- connections. Must be filled in with a value from the user.
- @item @code{addr} (default: @code{'("0.0.0.0:1965" "[::]:1965")})
- A list of the addresses to listen on.
- @item @code{hostname} (default: @code{#f})
- The domain name of this Gemini server. Optional.
- @item @code{lang} (default: @code{#f})
- RFC 4646 language code(s) for text/gemini documents. Optional.
- @item @code{silent?} (default: @code{#f})
- Set to @code{#t} to disable logging output.
- @item @code{serve-secret?} (default: @code{#f})
- Set to @code{#t} to serve secret files (files/directories starting with
- a dot).
- @item @code{log-ip?} (default: @code{#t})
- Whether or not to output IP addresses when logging.
- @item @code{user} (default: @code{"agate"})
- Owner of the @code{agate} process.
- @item @code{group} (default: @code{"agate"})
- Owner's group of the @code{agate} process.
- @item @code{log-file} (default: @file{"/var/log/agate.log"})
- The file which should store the logging output of Agate.
- @end table
- @end deftp
- @node Certificate Services
- @subsection Certificate Services
- @cindex Web
- @cindex HTTP, HTTPS
- @cindex Let's Encrypt
- @cindex TLS certificates
- The @code{(gnu services certbot)} module provides a service to
- automatically obtain a valid TLS certificate from the Let's Encrypt
- certificate authority. These certificates can then be used to serve
- content securely over HTTPS or other TLS-based protocols, with the
- knowledge that the client will be able to verify the server's
- authenticity.
- @url{https://letsencrypt.org/, Let's Encrypt} provides the
- @code{certbot} tool to automate the certification process. This tool
- first securely generates a key on the server. It then makes a request
- to the Let's Encrypt certificate authority (CA) to sign the key. The CA
- checks that the request originates from the host in question by using a
- challenge-response protocol, requiring the server to provide its
- response over HTTP@. If that protocol completes successfully, the CA
- signs the key, resulting in a certificate. That certificate is valid
- for a limited period of time, and therefore to continue to provide TLS
- services, the server needs to periodically ask the CA to renew its
- signature.
- The certbot service automates this process: the initial key
- generation, the initial certification request to the Let's Encrypt
- service, the web server challenge/response integration, writing the
- certificate to disk, the automated periodic renewals, and the deployment
- tasks associated with the renewal (e.g.@: reloading services, copying keys
- with different permissions).
- Certbot is run twice a day, at a random minute within the hour. It
- won't do anything until your certificates are due for renewal or
- revoked, but running it regularly would give your service a chance of
- staying online in case a Let's Encrypt-initiated revocation happened for
- some reason.
- By using this service, you agree to the ACME Subscriber Agreement, which
- can be found there:
- @url{https://acme-v01.api.letsencrypt.org/directory}.
- @defvr {Scheme Variable} certbot-service-type
- A service type for the @code{certbot} Let's Encrypt client. Its value
- must be a @code{certbot-configuration} record as in this example:
- @lisp
- (define %nginx-deploy-hook
- (program-file
- "nginx-deploy-hook"
- #~(let ((pid (call-with-input-file "/var/run/nginx/pid" read)))
- (kill pid SIGHUP))))
- (service certbot-service-type
- (certbot-configuration
- (email "foo@@example.net")
- (certificates
- (list
- (certificate-configuration
- (domains '("example.net" "www.example.net"))
- (deploy-hook %nginx-deploy-hook))
- (certificate-configuration
- (domains '("bar.example.net")))))))
- @end lisp
- See below for details about @code{certbot-configuration}.
- @end defvr
- @deftp {Data Type} certbot-configuration
- Data type representing the configuration of the @code{certbot} service.
- This type has the following parameters:
- @table @asis
- @item @code{package} (default: @code{certbot})
- The certbot package to use.
- @item @code{webroot} (default: @code{/var/www})
- The directory from which to serve the Let's Encrypt challenge/response
- files.
- @item @code{certificates} (default: @code{()})
- A list of @code{certificates-configuration}s for which to generate
- certificates and request signatures. Each certificate has a @code{name}
- and several @code{domains}.
- @item @code{email} (default: @code{#f})
- Optional email address used for registration and recovery contact.
- Setting this is encouraged as it allows you to receive important
- notifications about the account and issued certificates.
- @item @code{server} (default: @code{#f})
- Optional URL of ACME server. Setting this overrides certbot's default,
- which is the Let's Encrypt server.
- @item @code{rsa-key-size} (default: @code{2048})
- Size of the RSA key.
- @item @code{default-location} (default: @i{see below})
- The default @code{nginx-location-configuration}. Because @code{certbot}
- needs to be able to serve challenges and responses, it needs to be able
- to run a web server. It does so by extending the @code{nginx} web
- service with an @code{nginx-server-configuration} listening on the
- @var{domains} on port 80, and which has a
- @code{nginx-location-configuration} for the @code{/.well-known/} URI
- path subspace used by Let's Encrypt. @xref{Web Services}, for more on
- these nginx configuration data types.
- Requests to other URL paths will be matched by the
- @code{default-location}, which if present is added to all
- @code{nginx-server-configuration}s.
- By default, the @code{default-location} will issue a redirect from
- @code{http://@var{domain}/...} to @code{https://@var{domain}/...}, leaving
- you to define what to serve on your site via @code{https}.
- Pass @code{#f} to not issue a default location.
- @end table
- @end deftp
- @deftp {Data Type} certificate-configuration
- Data type representing the configuration of a certificate.
- This type has the following parameters:
- @table @asis
- @item @code{name} (default: @i{see below})
- This name is used by Certbot for housekeeping and in file paths; it
- doesn't affect the content of the certificate itself. To see
- certificate names, run @code{certbot certificates}.
- Its default is the first provided domain.
- @item @code{domains} (default: @code{()})
- The first domain provided will be the subject CN of the certificate, and
- all domains will be Subject Alternative Names on the certificate.
- @item @code{challenge} (default: @code{#f})
- The challenge type that has to be run by certbot. If @code{#f} is specified,
- default to the HTTP challenge. If a value is specified, defaults to the
- manual plugin (see @code{authentication-hook}, @code{cleanup-hook} and
- the documentation at @url{https://certbot.eff.org/docs/using.html#hooks}),
- and gives Let's Encrypt permission to log the public IP address of the
- requesting machine.
- @item @code{csr} (default: @code{#f})
- File name of Certificate Signing Request (CSR) in DER or PEM format.
- If @code{#f} is specified, this argument will not be passed to certbot.
- If a value is specified, certbot will use it to obtain a certificate, instead of
- using a self-generated CSR.
- The domain-name(s) mentioned in @code{domains}, must be consistent with the
- domain-name(s) mentioned in CSR file.
- @item @code{authentication-hook} (default: @code{#f})
- Command to be run in a shell once for each certificate challenge to be
- answered. For this command, the shell variable @code{$CERTBOT_DOMAIN}
- will contain the domain being authenticated, @code{$CERTBOT_VALIDATION}
- contains the validation string and @code{$CERTBOT_TOKEN} contains the
- file name of the resource requested when performing an HTTP-01 challenge.
- @item @code{cleanup-hook} (default: @code{#f})
- Command to be run in a shell once for each certificate challenge that
- have been answered by the @code{auth-hook}. For this command, the shell
- variables available in the @code{auth-hook} script are still available, and
- additionally @code{$CERTBOT_AUTH_OUTPUT} will contain the standard output
- of the @code{auth-hook} script.
- @item @code{deploy-hook} (default: @code{#f})
- Command to be run in a shell once for each successfully issued
- certificate. For this command, the shell variable
- @code{$RENEWED_LINEAGE} will point to the config live subdirectory (for
- example, @samp{"/etc/letsencrypt/live/example.com"}) containing the new
- certificates and keys; the shell variable @code{$RENEWED_DOMAINS} will
- contain a space-delimited list of renewed certificate domains (for
- example, @samp{"example.com www.example.com"}.
- @end table
- @end deftp
- For each @code{certificate-configuration}, the certificate is saved to
- @code{/etc/letsencrypt/live/@var{name}/fullchain.pem} and the key is
- saved to @code{/etc/letsencrypt/live/@var{name}/privkey.pem}.
- @node DNS Services
- @subsection DNS Services
- @cindex DNS (domain name system)
- @cindex domain name system (DNS)
- The @code{(gnu services dns)} module provides services related to the
- @dfn{domain name system} (DNS). It provides a server service for hosting
- an @emph{authoritative} DNS server for multiple zones, slave or master.
- This service uses @uref{https://www.knot-dns.cz/, Knot DNS}. And also a
- caching and forwarding DNS server for the LAN, which uses
- @uref{http://www.thekelleys.org.uk/dnsmasq/doc.html, dnsmasq}.
- @subsubheading Knot Service
- An example configuration of an authoritative server for two zones, one master
- and one slave, is:
- @lisp
- (define-zone-entries example.org.zone
- ;; Name TTL Class Type Data
- ("@@" "" "IN" "A" "127.0.0.1")
- ("@@" "" "IN" "NS" "ns")
- ("ns" "" "IN" "A" "127.0.0.1"))
- (define master-zone
- (knot-zone-configuration
- (domain "example.org")
- (zone (zone-file
- (origin "example.org")
- (entries example.org.zone)))))
- (define slave-zone
- (knot-zone-configuration
- (domain "plop.org")
- (dnssec-policy "default")
- (master (list "plop-master"))))
- (define plop-master
- (knot-remote-configuration
- (id "plop-master")
- (address (list "208.76.58.171"))))
- (operating-system
- ;; ...
- (services (cons* (service knot-service-type
- (knot-configuration
- (remotes (list plop-master))
- (zones (list master-zone slave-zone))))
- ;; ...
- %base-services)))
- @end lisp
- @deffn {Scheme Variable} knot-service-type
- This is the type for the Knot DNS server.
- Knot DNS is an authoritative DNS server, meaning that it can serve multiple
- zones, that is to say domain names you would buy from a registrar. This server
- is not a resolver, meaning that it can only resolve names for which it is
- authoritative. This server can be configured to serve zones as a master server
- or a slave server as a per-zone basis. Slave zones will get their data from
- masters, and will serve it as an authoritative server. From the point of view
- of a resolver, there is no difference between master and slave.
- The following data types are used to configure the Knot DNS server:
- @end deffn
- @deftp {Data Type} knot-key-configuration
- Data type representing a key.
- This type has the following parameters:
- @table @asis
- @item @code{id} (default: @code{""})
- An identifier for other configuration fields to refer to this key. IDs must
- be unique and must not be empty.
- @item @code{algorithm} (default: @code{#f})
- The algorithm to use. Choose between @code{#f}, @code{'hmac-md5},
- @code{'hmac-sha1}, @code{'hmac-sha224}, @code{'hmac-sha256}, @code{'hmac-sha384}
- and @code{'hmac-sha512}.
- @item @code{secret} (default: @code{""})
- The secret key itself.
- @end table
- @end deftp
- @deftp {Data Type} knot-acl-configuration
- Data type representing an Access Control List (ACL) configuration.
- This type has the following parameters:
- @table @asis
- @item @code{id} (default: @code{""})
- An identifier for other configuration fields to refer to this key. IDs must be
- unique and must not be empty.
- @item @code{address} (default: @code{'()})
- An ordered list of IP addresses, network subnets, or network ranges represented
- with strings. The query must match one of them. Empty value means that
- address match is not required.
- @item @code{key} (default: @code{'()})
- An ordered list of references to keys represented with strings. The string
- must match a key ID defined in a @code{knot-key-configuration}. No key means
- that a key is not require to match that ACL.
- @item @code{action} (default: @code{'()})
- An ordered list of actions that are permitted or forbidden by this ACL@. Possible
- values are lists of zero or more elements from @code{'transfer}, @code{'notify}
- and @code{'update}.
- @item @code{deny?} (default: @code{#f})
- When true, the ACL defines restrictions. Listed actions are forbidden. When
- false, listed actions are allowed.
- @end table
- @end deftp
- @deftp {Data Type} zone-entry
- Data type representing a record entry in a zone file.
- This type has the following parameters:
- @table @asis
- @item @code{name} (default: @code{"@@"})
- The name of the record. @code{"@@"} refers to the origin of the zone. Names
- are relative to the origin of the zone. For example, in the @code{example.org}
- zone, @code{"ns.example.org"} actually refers to @code{ns.example.org.example.org}.
- Names ending with a dot are absolute, which means that @code{"ns.example.org."}
- refers to @code{ns.example.org}.
- @item @code{ttl} (default: @code{""})
- The Time-To-Live (TTL) of this record. If not set, the default TTL is used.
- @item @code{class} (default: @code{"IN"})
- The class of the record. Knot currently supports only @code{"IN"} and
- partially @code{"CH"}.
- @item @code{type} (default: @code{"A"})
- The type of the record. Common types include A (IPv4 address), AAAA (IPv6
- address), NS (Name Server) and MX (Mail eXchange). Many other types are
- defined.
- @item @code{data} (default: @code{""})
- The data contained in the record. For instance an IP address associated with
- an A record, or a domain name associated with an NS record. Remember that
- domain names are relative to the origin unless they end with a dot.
- @end table
- @end deftp
- @deftp {Data Type} zone-file
- Data type representing the content of a zone file.
- This type has the following parameters:
- @table @asis
- @item @code{entries} (default: @code{'()})
- The list of entries. The SOA record is taken care of, so you don't need to
- put it in the list of entries. This list should probably contain an entry
- for your primary authoritative DNS server. Other than using a list of entries
- directly, you can use @code{define-zone-entries} to define a object containing
- the list of entries more easily, that you can later pass to the @code{entries}
- field of the @code{zone-file}.
- @item @code{origin} (default: @code{""})
- The name of your zone. This parameter cannot be empty.
- @item @code{ns} (default: @code{"ns"})
- The domain of your primary authoritative DNS server. The name is relative to
- the origin, unless it ends with a dot. It is mandatory that this primary
- DNS server corresponds to an NS record in the zone and that it is associated
- to an IP address in the list of entries.
- @item @code{mail} (default: @code{"hostmaster"})
- An email address people can contact you at, as the owner of the zone. This
- is translated as @code{<mail>@@<origin>}.
- @item @code{serial} (default: @code{1})
- The serial number of the zone. As this is used to keep track of changes by
- both slaves and resolvers, it is mandatory that it @emph{never} decreases.
- Always increment it when you make a change in your zone.
- @item @code{refresh} (default: @code{(* 2 24 3600)})
- The frequency at which slaves will do a zone transfer. This value is a number
- of seconds. It can be computed by multiplications or with
- @code{(string->duration)}.
- @item @code{retry} (default: @code{(* 15 60)})
- The period after which a slave will retry to contact its master when it fails
- to do so a first time.
- @item @code{expiry} (default: @code{(* 14 24 3600)})
- Default TTL of records. Existing records are considered correct for at most
- this amount of time. After this period, resolvers will invalidate their cache
- and check again that it still exists.
- @item @code{nx} (default: @code{3600})
- Default TTL of inexistent records. This delay is usually short because you want
- your new domains to reach everyone quickly.
- @end table
- @end deftp
- @deftp {Data Type} knot-remote-configuration
- Data type representing a remote configuration.
- This type has the following parameters:
- @table @asis
- @item @code{id} (default: @code{""})
- An identifier for other configuration fields to refer to this remote. IDs must
- be unique and must not be empty.
- @item @code{address} (default: @code{'()})
- An ordered list of destination IP addresses. Addresses are tried in sequence.
- An optional port can be given with the @@ separator. For instance:
- @code{(list "1.2.3.4" "2.3.4.5@@53")}. Default port is 53.
- @item @code{via} (default: @code{'()})
- An ordered list of source IP addresses. An empty list will have Knot choose
- an appropriate source IP@. An optional port can be given with the @@ separator.
- The default is to choose at random.
- @item @code{key} (default: @code{#f})
- A reference to a key, that is a string containing the identifier of a key
- defined in a @code{knot-key-configuration} field.
- @end table
- @end deftp
- @deftp {Data Type} knot-keystore-configuration
- Data type representing a keystore to hold dnssec keys.
- This type has the following parameters:
- @table @asis
- @item @code{id} (default: @code{""})
- The id of the keystore. It must not be empty.
- @item @code{backend} (default: @code{'pem})
- The backend to store the keys in. Can be @code{'pem} or @code{'pkcs11}.
- @item @code{config} (default: @code{"/var/lib/knot/keys/keys"})
- The configuration string of the backend. An example for the PKCS#11 is:
- @code{"pkcs11:token=knot;pin-value=1234 /gnu/store/.../lib/pkcs11/libsofthsm2.so"}.
- For the pem backend, the string represents a path in the file system.
- @end table
- @end deftp
- @deftp {Data Type} knot-policy-configuration
- Data type representing a dnssec policy. Knot DNS is able to automatically
- sign your zones. It can either generate and manage your keys automatically or
- use keys that you generate.
- Dnssec is usually implemented using two keys: a Key Signing Key (KSK) that is
- used to sign the second, and a Zone Signing Key (ZSK) that is used to sign the
- zone. In order to be trusted, the KSK needs to be present in the parent zone
- (usually a top-level domain). If your registrar supports dnssec, you will
- have to send them your KSK's hash so they can add a DS record in their zone.
- This is not automated and need to be done each time you change your KSK.
- The policy also defines the lifetime of keys. Usually, ZSK can be changed
- easily and use weaker cryptographic functions (they use lower parameters) in
- order to sign records quickly, so they are changed often. The KSK however
- requires manual interaction with the registrar, so they are changed less often
- and use stronger parameters because they sign only one record.
- This type has the following parameters:
- @table @asis
- @item @code{id} (default: @code{""})
- The id of the policy. It must not be empty.
- @item @code{keystore} (default: @code{"default"})
- A reference to a keystore, that is a string containing the identifier of a
- keystore defined in a @code{knot-keystore-configuration} field. The
- @code{"default"} identifier means the default keystore (a kasp database that
- was setup by this service).
- @item @code{manual?} (default: @code{#f})
- Whether the key management is manual or automatic.
- @item @code{single-type-signing?} (default: @code{#f})
- When @code{#t}, use the Single-Type Signing Scheme.
- @item @code{algorithm} (default: @code{"ecdsap256sha256"})
- An algorithm of signing keys and issued signatures.
- @item @code{ksk-size} (default: @code{256})
- The length of the KSK@. Note that this value is correct for the default
- algorithm, but would be unsecure for other algorithms.
- @item @code{zsk-size} (default: @code{256})
- The length of the ZSK@. Note that this value is correct for the default
- algorithm, but would be unsecure for other algorithms.
- @item @code{dnskey-ttl} (default: @code{'default})
- The TTL value for DNSKEY records added into zone apex. The special
- @code{'default} value means same as the zone SOA TTL.
- @item @code{zsk-lifetime} (default: @code{(* 30 24 3600)})
- The period between ZSK publication and the next rollover initiation.
- @item @code{propagation-delay} (default: @code{(* 24 3600)})
- An extra delay added for each key rollover step. This value should be high
- enough to cover propagation of data from the master server to all slaves.
- @item @code{rrsig-lifetime} (default: @code{(* 14 24 3600)})
- A validity period of newly issued signatures.
- @item @code{rrsig-refresh} (default: @code{(* 7 24 3600)})
- A period how long before a signature expiration the signature will be refreshed.
- @item @code{nsec3?} (default: @code{#f})
- When @code{#t}, NSEC3 will be used instead of NSEC.
- @item @code{nsec3-iterations} (default: @code{5})
- The number of additional times the hashing is performed.
- @item @code{nsec3-salt-length} (default: @code{8})
- The length of a salt field in octets, which is appended to the original owner
- name before hashing.
- @item @code{nsec3-salt-lifetime} (default: @code{(* 30 24 3600)})
- The validity period of newly issued salt field.
- @end table
- @end deftp
- @deftp {Data Type} knot-zone-configuration
- Data type representing a zone served by Knot.
- This type has the following parameters:
- @table @asis
- @item @code{domain} (default: @code{""})
- The domain served by this configuration. It must not be empty.
- @item @code{file} (default: @code{""})
- The file where this zone is saved. This parameter is ignored by master zones.
- Empty means default location that depends on the domain name.
- @item @code{zone} (default: @code{(zone-file)})
- The content of the zone file. This parameter is ignored by slave zones. It
- must contain a zone-file record.
- @item @code{master} (default: @code{'()})
- A list of master remotes. When empty, this zone is a master. When set, this
- zone is a slave. This is a list of remotes identifiers.
- @item @code{ddns-master} (default: @code{#f})
- The main master. When empty, it defaults to the first master in the list of
- masters.
- @item @code{notify} (default: @code{'()})
- A list of slave remote identifiers.
- @item @code{acl} (default: @code{'()})
- A list of acl identifiers.
- @item @code{semantic-checks?} (default: @code{#f})
- When set, this adds more semantic checks to the zone.
- @item @code{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 Bitmask
- @defvr {Scheme Variable} bitmask-service-type
- A service type for the @uref{https://bitmask.net, Bitmask} VPN client. It makes
- the client available in the system and loads its polkit policy. Please note that
- the client expects an active polkit-agent, which is either run by your
- desktop-environment or should be run manually.
- @end defvr
- @subsubheading OpenVPN
- It provides a @emph{client} service for your machine to connect to a
- VPN, and a @emph{server} service for your machine to host a VPN@.
- @deffn {Scheme Procedure} openvpn-client-service @
- [#:config (openvpn-client-configuration)]
- Return a service that runs @command{openvpn}, a VPN daemon, as a client.
- @end deffn
- @deffn {Scheme Procedure} openvpn-server-service @
- [#:config (openvpn-server-configuration)]
- Return a service that runs @command{openvpn}, a VPN daemon, as a server.
- Both can be run simultaneously.
- @end deffn
- @c %automatically generated documentation
- Available @code{openvpn-client-configuration} fields are:
- @deftypevr {@code{openvpn-client-configuration} parameter} package openvpn
- The OpenVPN package.
- @end deftypevr
- @deftypevr {@code{openvpn-client-configuration} parameter} string pid-file
- The OpenVPN pid file.
- Defaults to @samp{"/var/run/openvpn/openvpn.pid"}.
- @end deftypevr
- @deftypevr {@code{openvpn-client-configuration} parameter} proto proto
- The protocol (UDP or TCP) used to open a channel between clients and
- servers.
- Defaults to @samp{udp}.
- @end deftypevr
- @deftypevr {@code{openvpn-client-configuration} parameter} dev dev
- The device type used to represent the VPN connection.
- Defaults to @samp{tun}.
- @end deftypevr
- If you do not have some of these files (eg.@: you use a username and
- password), you can disable any of the following three fields by setting
- it to @code{'disabled}.
- @deftypevr {@code{openvpn-client-configuration} parameter} maybe-string ca
- The certificate authority to check connections against.
- Defaults to @samp{"/etc/openvpn/ca.crt"}.
- @end deftypevr
- @deftypevr {@code{openvpn-client-configuration} parameter} maybe-string cert
- The certificate of the machine the daemon is running on. It should be
- signed by the authority given in @code{ca}.
- Defaults to @samp{"/etc/openvpn/client.crt"}.
- @end deftypevr
- @deftypevr {@code{openvpn-client-configuration} parameter} maybe-string key
- The key of the machine the daemon is running on. It must be the key whose
- certificate is @code{cert}.
- Defaults to @samp{"/etc/openvpn/client.key"}.
- @end deftypevr
- @deftypevr {@code{openvpn-client-configuration} parameter} boolean comp-lzo?
- Whether to use the lzo compression algorithm.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{openvpn-client-configuration} parameter} boolean persist-key?
- Don't re-read key files across SIGUSR1 or --ping-restart.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{openvpn-client-configuration} parameter} boolean persist-tun?
- Don't close and reopen TUN/TAP device or run up/down scripts across
- SIGUSR1 or --ping-restart restarts.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{openvpn-client-configuration} parameter} boolean fast-io?
- (Experimental) Optimize TUN/TAP/UDP I/O writes by avoiding a call to
- poll/epoll/select prior to the write operation.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{openvpn-client-configuration} parameter} number verbosity
- Verbosity level.
- Defaults to @samp{3}.
- @end deftypevr
- @deftypevr {@code{openvpn-client-configuration} parameter} tls-auth-client tls-auth
- Add an additional layer of HMAC authentication on top of the TLS control
- channel to protect against DoS attacks.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{openvpn-client-configuration} parameter} maybe-string auth-user-pass
- Authenticate with server using username/password. The option is a file
- containing username/password on 2 lines. Do not use a file-like object as it
- would be added to the store and readable by any user.
- Defaults to @samp{'disabled}.
- @end deftypevr
- @deftypevr {@code{openvpn-client-configuration} parameter} key-usage verify-key-usage?
- Whether to check the server certificate has server usage extension.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{openvpn-client-configuration} parameter} bind bind?
- Bind to a specific local port number.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{openvpn-client-configuration} parameter} resolv-retry resolv-retry?
- Retry resolving server address.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{openvpn-client-configuration} parameter} openvpn-remote-list remote
- A list of remote servers to connect to.
- Defaults to @samp{()}.
- Available @code{openvpn-remote-configuration} fields are:
- @deftypevr {@code{openvpn-remote-configuration} parameter} string name
- Server name.
- Defaults to @samp{"my-server"}.
- @end deftypevr
- @deftypevr {@code{openvpn-remote-configuration} parameter} number port
- Port number the server listens to.
- Defaults to @samp{1194}.
- @end deftypevr
- @end deftypevr
- @c %end of automatic openvpn-client documentation
- @c %automatically generated documentation
- Available @code{openvpn-server-configuration} fields are:
- @deftypevr {@code{openvpn-server-configuration} parameter} package openvpn
- The OpenVPN package.
- @end deftypevr
- @deftypevr {@code{openvpn-server-configuration} parameter} string pid-file
- The OpenVPN pid file.
- Defaults to @samp{"/var/run/openvpn/openvpn.pid"}.
- @end deftypevr
- @deftypevr {@code{openvpn-server-configuration} parameter} proto proto
- The protocol (UDP or TCP) used to open a channel between clients and
- servers.
- Defaults to @samp{udp}.
- @end deftypevr
- @deftypevr {@code{openvpn-server-configuration} parameter} dev dev
- The device type used to represent the VPN connection.
- Defaults to @samp{tun}.
- @end deftypevr
- If you do not have some of these files (eg.@: you use a username and
- password), you can disable any of the following three fields by setting
- it to @code{'disabled}.
- @deftypevr {@code{openvpn-server-configuration} parameter} maybe-string ca
- The certificate authority to check connections against.
- Defaults to @samp{"/etc/openvpn/ca.crt"}.
- @end deftypevr
- @deftypevr {@code{openvpn-server-configuration} parameter} maybe-string cert
- The certificate of the machine the daemon is running on. It should be
- signed by the authority given in @code{ca}.
- Defaults to @samp{"/etc/openvpn/client.crt"}.
- @end deftypevr
- @deftypevr {@code{openvpn-server-configuration} parameter} maybe-string key
- The key of the machine the daemon is running on. It must be the key whose
- certificate is @code{cert}.
- Defaults to @samp{"/etc/openvpn/client.key"}.
- @end deftypevr
- @deftypevr {@code{openvpn-server-configuration} parameter} boolean comp-lzo?
- Whether to use the lzo compression algorithm.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{openvpn-server-configuration} parameter} boolean persist-key?
- Don't re-read key files across SIGUSR1 or --ping-restart.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{openvpn-server-configuration} parameter} boolean persist-tun?
- Don't close and reopen TUN/TAP device or run up/down scripts across
- SIGUSR1 or --ping-restart restarts.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{openvpn-server-configuration} parameter} boolean fast-io?
- (Experimental) Optimize TUN/TAP/UDP I/O writes by avoiding a call to
- poll/epoll/select prior to the write operation.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{openvpn-server-configuration} parameter} number verbosity
- Verbosity level.
- Defaults to @samp{3}.
- @end deftypevr
- @deftypevr {@code{openvpn-server-configuration} parameter} tls-auth-server tls-auth
- Add an additional layer of HMAC authentication on top of the TLS control
- channel to protect against DoS attacks.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{openvpn-server-configuration} parameter} number port
- Specifies the port number on which the server listens.
- Defaults to @samp{1194}.
- @end deftypevr
- @deftypevr {@code{openvpn-server-configuration} parameter} ip-mask server
- An ip and mask specifying the subnet inside the virtual network.
- Defaults to @samp{"10.8.0.0 255.255.255.0"}.
- @end deftypevr
- @deftypevr {@code{openvpn-server-configuration} parameter} cidr6 server-ipv6
- A CIDR notation specifying the IPv6 subnet inside the virtual network.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{openvpn-server-configuration} parameter} string dh
- The Diffie-Hellman parameters file.
- Defaults to @samp{"/etc/openvpn/dh2048.pem"}.
- @end deftypevr
- @deftypevr {@code{openvpn-server-configuration} parameter} string ifconfig-pool-persist
- The file that records client IPs.
- Defaults to @samp{"/etc/openvpn/ipp.txt"}.
- @end deftypevr
- @deftypevr {@code{openvpn-server-configuration} parameter} gateway redirect-gateway?
- When true, the server will act as a gateway for its clients.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{openvpn-server-configuration} parameter} boolean client-to-client?
- When true, clients are allowed to talk to each other inside the VPN.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{openvpn-server-configuration} parameter} keepalive keepalive
- Causes ping-like messages to be sent back and forth over the link so
- that each side knows when the other side has gone down. @code{keepalive}
- requires a pair. The first element is the period of the ping sending,
- and the second element is the timeout before considering the other side
- down.
- @end deftypevr
- @deftypevr {@code{openvpn-server-configuration} parameter} number max-clients
- The maximum number of clients.
- Defaults to @samp{100}.
- @end deftypevr
- @deftypevr {@code{openvpn-server-configuration} parameter} string status
- The status file. This file shows a small report on current connection.
- It is truncated and rewritten every minute.
- Defaults to @samp{"/var/run/openvpn/status"}.
- @end deftypevr
- @deftypevr {@code{openvpn-server-configuration} parameter} openvpn-ccd-list client-config-dir
- The list of configuration for some clients.
- Defaults to @samp{()}.
- Available @code{openvpn-ccd-configuration} fields are:
- @deftypevr {@code{openvpn-ccd-configuration} parameter} string name
- Client name.
- Defaults to @samp{"client"}.
- @end deftypevr
- @deftypevr {@code{openvpn-ccd-configuration} parameter} ip-mask iroute
- Client own network
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{openvpn-ccd-configuration} parameter} ip-mask ifconfig-push
- Client VPN IP.
- Defaults to @samp{#f}.
- @end deftypevr
- @end deftypevr
- @c %end of automatic openvpn-server documentation
- @subheading strongSwan
- Currently, the strongSwan service only provides legacy-style configuration with
- @file{ipsec.conf} and @file{ipsec.secrets} files.
- @defvr {Scheme Variable} strongswan-service-type
- A service type for configuring strongSwan for IPsec @acronym{VPN,
- Virtual Private Networking}. Its value must be a
- @code{strongswan-configuration} record as in this example:
- @lisp
- (service strongswan-service-type
- (strongswan-configuration
- (ipsec-conf "/etc/ipsec.conf")
- (ipsec-secrets "/etc/ipsec.secrets")))
- @end lisp
- @end defvr
- @deftp {Data Type} strongswan-configuration
- Data type representing the configuration of the StrongSwan service.
- @table @asis
- @item @code{strongswan}
- The strongSwan package to use for this service.
- @item @code{ipsec-conf} (default: @code{#f})
- The file name of your @file{ipsec.conf}. If not @code{#f}, then this and
- @code{ipsec-secrets} must both be strings.
- @item @code{ipsec-secrets} (default @code{#f})
- The file name of your @file{ipsec.secrets}. If not @code{#f}, then this and
- @code{ipsec-conf} must both be strings.
- @end table
- @end deftp
- @subsubheading Wireguard
- @defvr {Scheme Variable} wireguard-service-type
- A service type for a Wireguard tunnel interface. Its value must be a
- @code{wireguard-configuration} record as in this example:
- @lisp
- (service wireguard-service-type
- (wireguard-configuration
- (peers
- (list
- (wireguard-peer
- (name "my-peer")
- (endpoint "my.wireguard.com:51820")
- (public-key "hzpKg9X1yqu1axN6iJp0mWf6BZGo8m1wteKwtTmDGF4=")
- (allowed-ips '("10.0.0.2/32")))))))
- @end lisp
- @end defvr
- @deftp {Data Type} wireguard-configuration
- Data type representing the configuration of the Wireguard service.
- @table @asis
- @item @code{wireguard}
- The wireguard package to use for this service.
- @item @code{interface} (default: @code{"wg0"})
- The interface name for the VPN.
- @item @code{addresses} (default: @code{'("10.0.0.1/32")})
- The IP addresses to be assigned to the above interface.
- @item @code{private-key} (default: @code{"/etc/wireguard/private.key"})
- The private key file for the interface. It is automatically generated if
- the file does not exist.
- @item @code{peers} (default: @code{'()})
- The authorized peers on this interface. This is a list of
- @var{wireguard-peer} records.
- @end table
- @end deftp
- @deftp {Data Type} wireguard-peer
- Data type representing a Wireguard peer attached to a given interface.
- @table @asis
- @item @code{name}
- The peer name.
- @item @code{endpoint} (default: @code{#f})
- The optional endpoint for the peer, such as
- @code{"demo.wireguard.com:51820"}.
- @item @code{public-key}
- The peer public-key represented as a base64 string.
- @item @code{allowed-ips}
- A list of IP addresses from which incoming traffic for this peer is
- allowed and to which incoming traffic for this peer is directed.
- @item @code{keep-alive} (default: @code{#f})
- An optional time interval in seconds. A packet will be sent to the
- server endpoint once per time interval. This helps receiving
- incoming connections from this peer when you are behind a NAT or
- a firewall.
- @end table
- @end deftp
- @node Network File System
- @subsection Network File System
- @cindex NFS
- The @code{(gnu services nfs)} module provides the following services,
- which are most commonly used in relation to mounting or exporting
- directory trees as @dfn{network file systems} (NFS).
- While it is possible to use the individual components that together make
- up a Network File System service, we recommended to configure an NFS
- server with the @code{nfs-service-type}.
- @subsubheading NFS Service
- @cindex NFS, server
- The NFS service takes care of setting up all NFS component services,
- kernel configuration file systems, and installs configuration files in
- the locations that NFS expects.
- @defvr {Scheme Variable} nfs-service-type
- A service type for a complete NFS server.
- @end defvr
- @deftp {Data Type} nfs-configuration
- This data type represents the configuration of the NFS service and all
- of its subsystems.
- It has the following parameters:
- @table @asis
- @item @code{nfs-utils} (default: @code{nfs-utils})
- The nfs-utils package to use.
- @item @code{nfs-versions} (default: @code{'("4.2" "4.1" "4.0")})
- If a list of string values is provided, the @command{rpc.nfsd} daemon
- will be limited to supporting the given versions of the NFS protocol.
- @item @code{exports} (default: @code{'()})
- This is a list of directories the NFS server should export. Each entry
- is a list consisting of two elements: a directory name and a string
- containing all options. This is an example in which the directory
- @file{/export} is served to all NFS clients as a read-only share:
- @lisp
- (nfs-configuration
- (exports
- '(("/export"
- "*(ro,insecure,no_subtree_check,crossmnt,fsid=0)"))))
- @end lisp
- @item @code{rpcmountd-port} (default: @code{#f})
- The network port that the @command{rpc.mountd} daemon should use.
- @item @code{rpcstatd-port} (default: @code{#f})
- The network port that the @command{rpc.statd} daemon should use.
- @item @code{rpcbind} (default: @code{rpcbind})
- The rpcbind package to use.
- @item @code{idmap-domain} (default: @code{"localdomain"})
- The local NFSv4 domain name.
- @item @code{nfsd-port} (default: @code{2049})
- The network port that the @command{nfsd} daemon should use.
- @item @code{nfsd-threads} (default: @code{8})
- The number of threads used by the @command{nfsd} daemon.
- @item @code{nfsd-tcp?} (default: @code{#t})
- Whether the @command{nfsd} daemon should listen on a TCP socket.
- @item @code{nfsd-udp?} (default: @code{#f})
- Whether the @command{nfsd} daemon should listen on a UDP socket.
- @item @code{pipefs-directory} (default: @code{"/var/lib/nfs/rpc_pipefs"})
- The directory where the pipefs file system is mounted.
- @item @code{debug} (default: @code{'()"})
- A list of subsystems for which debugging output should be enabled. This
- is a list of symbols. Any of these symbols are valid: @code{nfsd},
- @code{nfs}, @code{rpc}, @code{idmap}, @code{statd}, or @code{mountd}.
- @end table
- @end deftp
- If you don't need a complete NFS service or prefer to build it yourself
- you can use the individual component services that are documented below.
- @subsubheading RPC Bind Service
- @cindex rpcbind
- The RPC Bind service provides a facility to map program numbers into
- universal addresses.
- Many NFS related services use this facility. Hence it is automatically
- started when a dependent service starts.
- @defvr {Scheme Variable} rpcbind-service-type
- A service type for the RPC portmapper daemon.
- @end defvr
- @deftp {Data Type} rpcbind-configuration
- Data type representing the configuration of the RPC Bind Service.
- This type has the following parameters:
- @table @asis
- @item @code{rpcbind} (default: @code{rpcbind})
- The rpcbind package to use.
- @item @code{warm-start?} (default: @code{#t})
- If this parameter is @code{#t}, then the daemon will read a
- state file on startup thus reloading state information saved by a previous
- instance.
- @end table
- @end deftp
- @subsubheading Pipefs Pseudo File System
- @cindex pipefs
- @cindex rpc_pipefs
- The pipefs file system is used to transfer NFS related data
- between the kernel and user space programs.
- @defvr {Scheme Variable} pipefs-service-type
- A service type for the pipefs pseudo file system.
- @end defvr
- @deftp {Data Type} pipefs-configuration
- Data type representing the configuration of the pipefs pseudo file system service.
- This type has the following parameters:
- @table @asis
- @item @code{mount-point} (default: @code{"/var/lib/nfs/rpc_pipefs"})
- The directory to which the file system is to be attached.
- @end table
- @end deftp
- @subsubheading GSS Daemon Service
- @cindex GSSD
- @cindex GSS
- @cindex global security system
- The @dfn{global security system} (GSS) daemon provides strong security for RPC
- based protocols.
- Before exchanging RPC requests an RPC client must establish a security
- context. Typically this is done using the Kerberos command @command{kinit}
- or automatically at login time using PAM services (@pxref{Kerberos Services}).
- @defvr {Scheme Variable} gss-service-type
- A service type for the Global Security System (GSS) daemon.
- @end defvr
- @deftp {Data Type} gss-configuration
- Data type representing the configuration of the GSS daemon service.
- This type has the following parameters:
- @table @asis
- @item @code{nfs-utils} (default: @code{nfs-utils})
- The package in which the @command{rpc.gssd} command is to be found.
- @item @code{pipefs-directory} (default: @code{"/var/lib/nfs/rpc_pipefs"})
- The directory where the pipefs file system is mounted.
- @end table
- @end deftp
- @subsubheading IDMAP Daemon Service
- @cindex idmapd
- @cindex name mapper
- The idmap daemon service provides mapping between user IDs and user names.
- Typically it is required in order to access file systems mounted via NFSv4.
- @defvr {Scheme Variable} idmap-service-type
- A service type for the Identity Mapper (IDMAP) daemon.
- @end defvr
- @deftp {Data Type} idmap-configuration
- Data type representing the configuration of the IDMAP daemon service.
- This type has the following parameters:
- @table @asis
- @item @code{nfs-utils} (default: @code{nfs-utils})
- The package in which the @command{rpc.idmapd} command is to be found.
- @item @code{pipefs-directory} (default: @code{"/var/lib/nfs/rpc_pipefs"})
- The directory where the pipefs file system is mounted.
- @item @code{domain} (default: @code{#f})
- The local NFSv4 domain name.
- This must be a string or @code{#f}.
- If it is @code{#f} then the daemon will use the host's fully qualified domain name.
- @item @code{verbosity} (default: @code{0})
- The verbosity level of the daemon.
- @end table
- @end deftp
- @node Continuous Integration
- @subsection Continuous Integration
- @cindex continuous integration
- @uref{https://guix.gnu.org/cuirass/, Cuirass} is a continuous
- integration tool for Guix. It can be used both for development and for
- providing substitutes to others (@pxref{Substitutes}).
- The @code{(gnu services cuirass)} module provides the following service.
- @defvr {Scheme Procedure} cuirass-service-type
- The type of the Cuirass service. Its value must be a
- @code{cuirass-configuration} object, as described below.
- @end defvr
- To add build jobs, you have to set the @code{specifications} field of
- the configuration. For instance, the following example will build all
- the packages provided by the @code{my-channel} channel.
- @lisp
- (define %cuirass-specs
- #~(list (specification
- (name "my-channel")
- (build '(channels my-channel))
- (channels
- (cons (channel
- (name 'my-channel)
- (url "https://my-channel.git"))
- %default-channels)))))
- (service cuirass-service-type
- (cuirass-configuration
- (specifications %cuirass-specs)))
- @end lisp
- To build the @code{linux-libre} package defined by the default Guix
- channel, one can use the following configuration.
- @lisp
- (define %cuirass-specs
- #~(list (specification
- (name "my-linux")
- (build '(packages "linux-libre")))))
- (service cuirass-service-type
- (cuirass-configuration
- (specifications %cuirass-specs)))
- @end lisp
- The other configuration possibilities, as well as the specification
- record itself are described in the Cuirass manual
- (@pxref{Specifications,,, cuirass, Cuirass}).
- While information related to build jobs is located directly in the
- specifications, global settings for the @command{cuirass} process are
- accessible in other @code{cuirass-configuration} fields.
- @deftp {Data Type} cuirass-configuration
- Data type representing the configuration of Cuirass.
- @table @asis
- @item @code{cuirass} (default: @code{cuirass})
- The Cuirass package to use.
- @item @code{log-file} (default: @code{"/var/log/cuirass.log"})
- Location of the log file.
- @item @code{web-log-file} (default: @code{"/var/log/cuirass-web.log"})
- Location of the log file used by the web interface.
- @item @code{cache-directory} (default: @code{"/var/cache/cuirass"})
- Location of the repository cache.
- @item @code{user} (default: @code{"cuirass"})
- Owner of the @code{cuirass} process.
- @item @code{group} (default: @code{"cuirass"})
- Owner's group of the @code{cuirass} process.
- @item @code{interval} (default: @code{60})
- Number of seconds between the poll of the repositories followed by the
- Cuirass jobs.
- @item @code{parameters} (default: @code{#f})
- Read parameters from the given @var{parameters} file. The supported
- parameters are described here (@pxref{Parameters,,, cuirass, Cuirass}).
- @item @code{remote-server} (default: @code{#f})
- A @code{cuirass-remote-server-configuration} record to use the build
- remote mechanism or @code{#f} to use the default build mechanism.
- @item @code{database} (default: @code{"dbname=cuirass host=/var/run/postgresql"})
- Use @var{database} as the database containing the jobs and the past
- build results. Since Cuirass uses PostgreSQL as a database engine,
- @var{database} must be a string such as @code{"dbname=cuirass
- host=localhost"}.
- @item @code{port} (default: @code{8081})
- Port number used by the HTTP server.
- @item @code{host} (default: @code{"localhost"})
- Listen on the network interface for @var{host}. The default is to
- accept connections from localhost.
- @item @code{specifications} (default: @code{#~'()})
- A gexp (@pxref{G-Expressions}) that evaluates to a list of
- specifications records. The specification record is described in the
- Cuirass manual (@pxref{Specifications,,, cuirass, Cuirass}).
- @item @code{use-substitutes?} (default: @code{#f})
- This allows using substitutes to avoid building every dependencies of a job
- from source.
- @item @code{one-shot?} (default: @code{#f})
- Only evaluate specifications and build derivations once.
- @item @code{fallback?} (default: @code{#f})
- When substituting a pre-built binary fails, fall back to building
- packages locally.
- @item @code{extra-options} (default: @code{'()})
- Extra options to pass when running the Cuirass processes.
- @end table
- @end deftp
- @cindex remote build
- @subsubheading Cuirass remote building
- Cuirass supports two mechanisms to build derivations.
- @itemize
- @item Using the local Guix daemon.
- This is the default build mechanism. Once the build jobs are
- evaluated, they are sent to the local Guix daemon. Cuirass then
- listens to the Guix daemon output to detect the various build events.
- @item Using the remote build mechanism.
- The build jobs are not submitted to the local Guix daemon. Instead, a
- remote server dispatches build requests to the connect remote workers,
- according to the build priorities.
- @end itemize
- To enable this build mode a @code{cuirass-remote-server-configuration}
- record must be passed as @code{remote-server} argument of the
- @code{cuirass-configuration} record. The
- @code{cuirass-remote-server-configuration} record is described below.
- This build mode scales way better than the default build mode. This is
- the build mode that is used on the GNU Guix build farm at
- @url{https://ci.guix.gnu.org}. It should be preferred when using
- Cuirass to build large amount of packages.
- @deftp {Data Type} cuirass-remote-server-configuration
- Data type representing the configuration of the Cuirass remote-server.
- @table @asis
- @item @code{backend-port} (default: @code{5555})
- The TCP port for communicating with @code{remote-worker} processes
- using ZMQ. It defaults to @code{5555}.
- @item @code{log-port} (default: @code{5556})
- The TCP port of the log server. It defaults to @code{5556}.
- @item @code{publish-port} (default: @code{5557})
- The TCP port of the publish server. It defaults to @code{5557}.
- @item @code{log-file} (default: @code{"/var/log/cuirass-remote-server.log"})
- Location of the log file.
- @item @code{cache} (default: @code{"/var/cache/cuirass/remote"})
- Use @var{cache} directory to cache build log files.
- @item @code{trigger-url} (default: @code{#f})
- Once a substitute is successfully fetched, trigger substitute baking at
- @var{trigger-url}.
- @item @code{publish?} (default: @code{#t})
- If set to false, do not start a publish server and ignore the
- @code{publish-port} argument. This can be useful if there is already a
- standalone publish server standing next to the remote server.
- @item @code{public-key}
- @item @code{private-key}
- Use the specific @var{file}s as the public/private key pair used to sign
- the store items being published.
- @end table
- @end deftp
- At least one remote worker must also be started on any machine of the
- local network to actually perform the builds and report their status.
- @deftp {Data Type} cuirass-remote-worker-configuration
- Data type representing the configuration of the Cuirass remote-worker.
- @table @asis
- @item @code{cuirass} (default: @code{cuirass})
- The Cuirass package to use.
- @item @code{workers} (default: @code{1})
- Start @var{workers} parallel workers.
- @item @code{server} (default: @code{#f})
- Do not use Avahi discovery and connect to the given @code{server} IP
- address instead.
- @item @code{systems} (default: @code{(list (%current-system))})
- Only request builds for the given @var{systems}.
- @item @code{log-file} (default: @code{"/var/log/cuirass-remote-worker.log"})
- Location of the log file.
- @item @code{publish-port} (default: @code{5558})
- The TCP port of the publish server. It defaults to @code{5558}.
- @item @code{substitute-urls} (default: @code{%default-substitute-urls})
- The list of URLs where to look for substitutes by default.
- @item @code{public-key}
- @item @code{private-key}
- Use the specific @var{file}s as the public/private key pair used to sign
- the store items being published.
- @end table
- @end deftp
- @subsubheading Laminar
- @uref{https://laminar.ohwg.net/, Laminar} is a lightweight and modular
- Continuous Integration service. It doesn't have a configuration web UI
- instead uses version-controllable configuration files and scripts.
- Laminar encourages the use of existing tools such as bash and cron
- instead of reinventing them.
- @defvr {Scheme Procedure} laminar-service-type
- The type of the Laminar service. Its value must be a
- @code{laminar-configuration} object, as described below.
- All configuration values have defaults, a minimal configuration to get
- Laminar running is shown below. By default, the web interface is
- available on port 8080.
- @lisp
- (service laminar-service-type)
- @end lisp
- @end defvr
- @deftp {Data Type} laminar-configuration
- Data type representing the configuration of Laminar.
- @table @asis
- @item @code{laminar} (default: @code{laminar})
- The Laminar package to use.
- @item @code{home-directory} (default: @code{"/var/lib/laminar"})
- The directory for job configurations and run directories.
- @item @code{bind-http} (default: @code{"*:8080"})
- The interface/port or unix socket on which laminard should listen for
- incoming connections to the web frontend.
- @item @code{bind-rpc} (default: @code{"unix-abstract:laminar"})
- The interface/port or unix socket on which laminard should listen for
- incoming commands such as build triggers.
- @item @code{title} (default: @code{"Laminar"})
- The page title to show in the web frontend.
- @item @code{keep-rundirs} (default: @code{0})
- Set to an integer defining how many rundirs to keep per job. The
- lowest-numbered ones will be deleted. The default is 0, meaning all run
- dirs will be immediately deleted.
- @item @code{archive-url} (default: @code{#f})
- The web frontend served by laminard will use this URL to form links to
- artefacts archived jobs.
- @item @code{base-url} (default: @code{#f})
- Base URL to use for links to laminar itself.
- @end table
- @end deftp
- @node Power Management Services
- @subsection Power Management Services
- @cindex tlp
- @cindex power management with TLP
- @subsubheading TLP daemon
- The @code{(gnu services pm)} module provides a Guix service definition
- for the Linux power management tool TLP.
- TLP enables various powersaving modes in userspace and kernel.
- Contrary to @code{upower-service}, it is not a passive,
- monitoring tool, as it will apply custom settings each time a new power
- source is detected. More information can be found at
- @uref{https://linrunner.de/en/tlp/tlp.html, TLP home page}.
- @deffn {Scheme Variable} tlp-service-type
- The service type for the TLP tool. The default settings are optimised
- for battery life on most systems, but you can tweak them to your heart's
- content by adding a valid @code{tlp-configuration}:
- @lisp
- (service tlp-service-type
- (tlp-configuration
- (cpu-scaling-governor-on-ac (list "performance"))
- (sched-powersave-on-bat? #t)))
- @end lisp
- @end deffn
- Each parameter definition is preceded by its type; for example,
- @samp{boolean foo} indicates that the @code{foo} parameter
- should be specified as a boolean. Types starting with
- @code{maybe-} denote parameters that won't show up in TLP config file
- when their value is @code{'disabled}.
- @c The following documentation was initially generated by
- @c (generate-tlp-documentation) in (gnu services pm). Manually maintained
- @c documentation is better, so we shouldn't hesitate to edit below as
- @c needed. However if the change you want to make to this documentation
- @c can be done in an automated way, it's probably easier to change
- @c (generate-documentation) than to make it below and have to deal with
- @c the churn as TLP updates.
- Available @code{tlp-configuration} fields are:
- @deftypevr {@code{tlp-configuration} parameter} package tlp
- The TLP package.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} boolean tlp-enable?
- Set to true if you wish to enable TLP.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} string tlp-default-mode
- Default mode when no power supply can be detected. Alternatives are AC
- and BAT.
- Defaults to @samp{"AC"}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} non-negative-integer disk-idle-secs-on-ac
- Number of seconds Linux kernel has to wait after the disk goes idle,
- before syncing on AC.
- Defaults to @samp{0}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} non-negative-integer disk-idle-secs-on-bat
- Same as @code{disk-idle-ac} but on BAT mode.
- Defaults to @samp{2}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} non-negative-integer max-lost-work-secs-on-ac
- Dirty pages flushing periodicity, expressed in seconds.
- Defaults to @samp{15}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} non-negative-integer max-lost-work-secs-on-bat
- Same as @code{max-lost-work-secs-on-ac} but on BAT mode.
- Defaults to @samp{60}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list cpu-scaling-governor-on-ac
- CPU frequency scaling governor on AC mode. With intel_pstate driver,
- alternatives are powersave and performance. With acpi-cpufreq driver,
- alternatives are ondemand, powersave, performance and conservative.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list cpu-scaling-governor-on-bat
- Same as @code{cpu-scaling-governor-on-ac} but on BAT mode.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-scaling-min-freq-on-ac
- Set the min available frequency for the scaling governor on AC.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-scaling-max-freq-on-ac
- Set the max available frequency for the scaling governor on AC.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-scaling-min-freq-on-bat
- Set the min available frequency for the scaling governor on BAT.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-scaling-max-freq-on-bat
- Set the max available frequency for the scaling governor on BAT.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-min-perf-on-ac
- Limit the min P-state to control the power dissipation of the CPU, in AC
- mode. Values are stated as a percentage of the available performance.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-max-perf-on-ac
- Limit the max P-state to control the power dissipation of the CPU, in AC
- mode. Values are stated as a percentage of the available performance.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-min-perf-on-bat
- Same as @code{cpu-min-perf-on-ac} on BAT mode.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-max-perf-on-bat
- Same as @code{cpu-max-perf-on-ac} on BAT mode.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-boolean cpu-boost-on-ac?
- Enable CPU turbo boost feature on AC mode.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-boolean cpu-boost-on-bat?
- Same as @code{cpu-boost-on-ac?} on BAT mode.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} boolean sched-powersave-on-ac?
- Allow Linux kernel to minimize the number of CPU cores/hyper-threads
- used under light load conditions.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} boolean sched-powersave-on-bat?
- Same as @code{sched-powersave-on-ac?} but on BAT mode.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} boolean nmi-watchdog?
- Enable Linux kernel NMI watchdog.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-string phc-controls
- For Linux kernels with PHC patch applied, change CPU voltages. An
- example value would be @samp{"F:V F:V F:V F:V"}.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} string energy-perf-policy-on-ac
- Set CPU performance versus energy saving policy on AC@. Alternatives are
- performance, normal, powersave.
- Defaults to @samp{"performance"}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} string energy-perf-policy-on-bat
- Same as @code{energy-perf-policy-ac} but on BAT mode.
- Defaults to @samp{"powersave"}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} space-separated-string-list disks-devices
- Hard disk devices.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} space-separated-string-list disk-apm-level-on-ac
- Hard disk advanced power management level.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} space-separated-string-list disk-apm-level-on-bat
- Same as @code{disk-apm-bat} but on BAT mode.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list disk-spindown-timeout-on-ac
- Hard disk spin down timeout. One value has to be specified for each
- declared hard disk.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list disk-spindown-timeout-on-bat
- Same as @code{disk-spindown-timeout-on-ac} but on BAT mode.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list disk-iosched
- Select IO scheduler for disk devices. One value has to be specified for
- each declared hard disk. Example alternatives are cfq, deadline and
- noop.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} string sata-linkpwr-on-ac
- SATA aggressive link power management (ALPM) level. Alternatives are
- min_power, medium_power, max_performance.
- Defaults to @samp{"max_performance"}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} string sata-linkpwr-on-bat
- Same as @code{sata-linkpwr-ac} but on BAT mode.
- Defaults to @samp{"min_power"}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-string sata-linkpwr-blacklist
- Exclude specified SATA host devices for link power management.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-on-off-boolean ahci-runtime-pm-on-ac?
- Enable Runtime Power Management for AHCI controller and disks on AC
- mode.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-on-off-boolean ahci-runtime-pm-on-bat?
- Same as @code{ahci-runtime-pm-on-ac} on BAT mode.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} non-negative-integer ahci-runtime-pm-timeout
- Seconds of inactivity before disk is suspended.
- Defaults to @samp{15}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} string pcie-aspm-on-ac
- PCI Express Active State Power Management level. Alternatives are
- default, performance, powersave.
- Defaults to @samp{"performance"}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} string pcie-aspm-on-bat
- Same as @code{pcie-aspm-ac} but on BAT mode.
- Defaults to @samp{"powersave"}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} 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).
- For example, let's suppose you're on an x86_64 machine and you have this
- service:
- @lisp
- (service qemu-binfmt-service-type
- (qemu-binfmt-configuration
- (platforms (lookup-qemu-platforms "arm"))))
- @end lisp
- You can run:
- @example
- guix build -s armhf-linux inkscape
- @end example
- @noindent
- and it will build Inkscape for ARMv7 @emph{as if it were a native
- build}, transparently using QEMU to emulate the ARMv7 CPU@. Pretty handy
- if you'd like to test a package build for an architecture you don't have
- access to!
- @item @code{qemu} (default: @code{qemu})
- The QEMU package to use.
- @end table
- @end deftp
- @deffn {Scheme Procedure} lookup-qemu-platforms @var{platforms}@dots{}
- Return the list of QEMU platform objects corresponding to
- @var{platforms}@dots{}. @var{platforms} must be a list of strings
- corresponding to platform names, such as @code{"arm"}, @code{"sparc"},
- @code{"mips64el"}, and so on.
- @end deffn
- @deffn {Scheme Procedure} qemu-platform? @var{obj}
- Return true if @var{obj} is a platform object.
- @end deffn
- @deffn {Scheme Procedure} qemu-platform-name @var{platform}
- Return the name of @var{platform}---a string such as @code{"arm"}.
- @end deffn
- @subsubheading 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" (string-append
- "user,id=net0,"
- "hostfwd=tcp:127.0.0.1:@var{secrets-port}-:1004,"
- "hostfwd=tcp:127.0.0.1:@var{ssh-port}-:2222,"
- "hostfwd=tcp:127.0.0.1:@var{vnc-port}-:5900"))
- @end lisp
- with forwarded ports:
- @example
- @var{secrets-port}: @code{(+ 11004 (* 1000 @var{ID}))}
- @var{ssh-port}: @code{(+ 10022 (* 1000 @var{ID}))}
- @var{vnc-port}: @code{(+ 15900 (* 1000 @var{ID}))}
- @end example
- @item @code{secret-root} (default: @file{/etc/childhurd})
- The root directory with out-of-band secrets to be installed into the
- childhurd once it runs. Childhurds are volatile which means that on
- every startup, secrets such as the SSH host keys and Guix signing key
- are recreated.
- If the @file{/etc/childhurd} directory does not exist, the
- @code{secret-service} running in the Childhurd will be sent an empty
- list of secrets.
- By default, the service automatically populates @file{/etc/childhurd}
- with the following non-volatile secrets, unless they already exist:
- @example
- /etc/childhurd/etc/guix/acl
- /etc/childhurd/etc/guix/signing-key.pub
- /etc/childhurd/etc/guix/signing-key.sec
- /etc/childhurd/etc/ssh/ssh_host_ed25519_key
- /etc/childhurd/etc/ssh/ssh_host_ecdsa_key
- /etc/childhurd/etc/ssh/ssh_host_ed25519_key.pub
- /etc/childhurd/etc/ssh/ssh_host_ecdsa_key.pub
- @end example
- These files are automatically sent to the guest Hurd VM when it boots,
- including permissions.
- @cindex childhurd, offloading
- @cindex Hurd, offloading
- Having these files in place means that only a couple of things are
- missing to allow the host to offload @code{i586-gnu} builds to the
- childhurd:
- @enumerate
- @item
- Authorizing the childhurd's key on the host so that the host accepts
- build results coming from the childhurd, which can be done like so:
- @example
- guix archive --authorize < \
- /etc/childhurd/etc/guix/signing-key.pub
- @end example
- @item
- Adding the childhurd to @file{/etc/guix/machines.scm} (@pxref{Daemon
- Offload Setup}).
- @end enumerate
- We're working towards making that happen automatically---get in touch
- with us at @email{guix-devel@@gnu.org} to discuss it!
- @end table
- @end deftp
- Note that by default the VM image is volatile, i.e., once stopped the
- contents are lost. If you want a stateful image instead, override the
- configuration's @code{image} and @code{options} without
- the @code{--snapshot} flag using something along these lines:
- @lisp
- (service hurd-vm-service-type
- (hurd-vm-configuration
- (image (const "/out/of/store/writable/hurd.img"))
- (options '())))
- @end lisp
- @subsubheading Ganeti
- @cindex ganeti
- @quotation Note
- This service is considered experimental. Configuration options may be changed
- in a backwards-incompatible manner, and not all features have been thorougly
- tested. Users of this service are encouraged to share their experience at
- @email{guix-devel@@gnu.org}.
- @end quotation
- Ganeti is a virtual machine management system. It is designed to keep virtual
- machines running on a cluster of servers even in the event of hardware failures,
- and to make maintenance and recovery tasks easy. It consists of multiple
- services which are described later in this section. In addition to the Ganeti
- service, you will need the OpenSSH service (@pxref{Networking Services,
- @code{openssh-service-type}}), and update the @file{/etc/hosts} file
- (@pxref{operating-system Reference, @code{hosts-file}}) with the cluster name
- and address (or use a DNS server).
- All nodes participating in a Ganeti cluster should have the same Ganeti and
- @file{/etc/hosts} configuration. Here is an example configuration for a Ganeti
- cluster node that supports multiple storage backends, and installs the
- @code{debootstrap} and @code{guix} @dfn{OS providers}:
- @lisp
- (use-package-modules virtualization)
- (use-service-modules base ganeti networking ssh)
- (operating-system
- ;; @dots{}
- (host-name "node1")
- (hosts-file (plain-file "hosts" (format #f "
- 127.0.0.1 localhost
- ::1 localhost
- 192.168.1.200 ganeti.example.com
- 192.168.1.201 node1.example.com node1
- 192.168.1.202 node2.example.com node2
- ")))
- ;; Install QEMU so we can use KVM-based instances, and LVM, DRBD and Ceph
- ;; in order to use the "plain", "drbd" and "rbd" storage backends.
- (packages (append (map specification->package
- '("qemu" "lvm2" "drbd-utils" "ceph"
- ;; Add the debootstrap and guix OS providers.
- "ganeti-instance-guix" "ganeti-instance-debootstrap"))
- %base-packages))
- (services
- (append (list (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 'prohibit-password)))
- (service ganeti-service-type
- (ganeti-configuration
- ;; This list specifies allowed file system paths
- ;; for storing virtual machine images.
- (file-storage-paths '("/srv/ganeti/file-storage"))
- ;; This variable configures a single "variant" for
- ;; both Debootstrap and Guix that works with KVM.
- (os %default-ganeti-os))))
- %base-services)))
- @end lisp
- Users are advised to read the
- @url{http://docs.ganeti.org/ganeti/master/html/admin.html,Ganeti
- administrators guide} to learn about the various cluster options and
- day-to-day operations. There is also a
- @url{https://guix.gnu.org/blog/2020/running-a-ganeti-cluster-on-guix/,blog post}
- describing how to configure and initialize a small cluster.
- @defvr {Scheme Variable} ganeti-service-type
- This is a service type that includes all the various services that Ganeti
- nodes should run.
- Its value is a @code{ganeti-configuration} object that defines the package
- to use for CLI operations, as well as configuration for the various daemons.
- Allowed file storage paths and available guest operating systems are also
- configured through this data type.
- @end defvr
- @deftp {Data Type} ganeti-configuration
- The @code{ganeti} service takes the following configuration options:
- @table @asis
- @item @code{ganeti} (default: @code{ganeti})
- The @code{ganeti} package to use. It will be installed to the system profile
- and make @command{gnt-cluster}, @command{gnt-instance}, etc available. Note
- that the value specified here does not affect the other services as each refer
- to a specific @code{ganeti} package (see below).
- @item @code{noded-configuration} (default: @code{(ganeti-noded-configuration)})
- @itemx @code{confd-configuration} (default: @code{(ganeti-confd-configuration)})
- @itemx @code{wconfd-configuration} (default: @code{(ganeti-wconfd-configuration)})
- @itemx @code{luxid-configuration} (default: @code{(ganeti-luxid-configuration)})
- @itemx @code{rapi-configuration} (default: @code{(ganeti-rapi-configuration)})
- @itemx @code{kvmd-configuration} (default: @code{(ganeti-kvmd-configuration)})
- @itemx @code{mond-configuration} (default: @code{(ganeti-mond-configuration)})
- @itemx @code{metad-configuration} (default: @code{(ganeti-metad-configuration)})
- @itemx @code{watcher-configuration} (default: @code{(ganeti-watcher-configuration)})
- @itemx @code{cleaner-configuration} (default: @code{(ganeti-cleaner-configuration)})
- These options control the various daemons and cron jobs that are distributed
- with Ganeti. The possible values for these are described in detail below.
- To override a setting, you must use the configuration type for that service:
- @lisp
- (service ganeti-service-type
- (ganeti-configuration
- (rapi-configuration
- (ganeti-rapi-configuration
- (interface "eth1"))))
- (watcher-configuration
- (ganeti-watcher-configuration
- (rapi-ip "10.0.0.1"))))
- @end lisp
- @item @code{file-storage-paths} (default: @code{'()})
- List of allowed directories for file storage backend.
- @item @code{os} (default: @code{%default-ganeti-os})
- List of @code{<ganeti-os>} records.
- @end table
- In essence @code{ganeti-service-type} is shorthand for declaring each service
- individually:
- @lisp
- (service ganeti-noded-service-type)
- (service ganeti-confd-service-type)
- (service ganeti-wconfd-service-type)
- (service ganeti-luxid-service-type)
- (service ganeti-kvmd-service-type)
- (service ganeti-mond-service-type)
- (service ganeti-metad-service-type)
- (service ganeti-watcher-service-type)
- (service ganeti-cleaner-service-type)
- @end lisp
- Plus a service extension for @code{etc-service-type} that configures the file
- storage backend and OS variants.
- @end deftp
- @deftp {Data Type} ganeti-os
- This data type is suitable for passing to the @code{os} parameter of
- @code{ganeti-configuration}. It takes the following parameters:
- @table @asis
- @item @code{name}
- The name for this OS provider. It is only used to specify where the
- configuration ends up. Setting it to ``debootstrap'' will create
- @file{/etc/ganeti/instance-debootstrap}.
- @item @code{extension}
- The file extension for variants of this OS type. For example
- @file{.conf} or @file{.scm}.
- @item @code{variants} (default: @code{'()})
- List of @code{ganeti-os-variant} objects for this OS.
- @end table
- @end deftp
- @deftp {Data Type} ganeti-os-variant
- This is the data type for a Ganeti OS variant. It takes the following
- parameters:
- @table @asis
- @item @code{name}
- The name of this variant.
- @item @code{configuration}
- A configuration file for this variant.
- @end table
- @end deftp
- @defvr {Scheme Variable} %default-debootstrap-hooks
- This variable contains hooks to configure networking and the GRUB bootloader.
- @end defvr
- @defvr {Scheme Variable} %default-debootstrap-extra-pkgs
- This variable contains a list of packages suitable for a fully-virtualized guest.
- @end defvr
- @deftp {Data Type} debootstrap-configuration
- This data type creates configuration files suitable for the debootstrap OS provider.
- @table @asis
- @item @code{hooks} (default: @code{%default-debootstrap-hooks})
- When not @code{#f}, this must be a G-expression that specifies a directory with
- scripts that will run when the OS is installed. It can also be a list of
- @code{(name . file-like)} pairs. For example:
- @lisp
- `((99-hello-world . ,(plain-file "#!/bin/sh\necho Hello, World")))
- @end lisp
- That will create a directory with one executable named @code{99-hello-world}
- and run it every time this variant is installed. If set to @code{#f}, hooks
- in @file{/etc/ganeti/instance-debootstrap/hooks} will be used, if any.
- @item @code{proxy} (default: @code{#f})
- Optional HTTP proxy to use.
- @item @code{mirror} (default: @code{#f})
- The Debian mirror. Typically something like @code{http://ftp.no.debian.org/debian}.
- The default varies depending on the distribution.
- @item @code{arch} (default: @code{#f})
- The dpkg architecture. Set to @code{armhf} to debootstrap an ARMv7 instance
- on an AArch64 host. Default is to use the current system architecture.
- @item @code{suite} (default: @code{"stable"})
- When set, this must be a Debian distribution ``suite'' such as @code{buster}
- or @code{focal}. If set to @code{#f}, the default for the OS provider is used.
- @item @code{extra-pkgs} (default: @code{%default-debootstrap-extra-pkgs})
- List of extra packages that will get installed by dpkg in addition
- to the minimal system.
- @item @code{components} (default: @code{#f})
- When set, must be a list of Debian repository ``components''. For example
- @code{'("main" "contrib")}.
- @item @code{generate-cache?} (default: @code{#t})
- Whether to automatically cache the generated debootstrap archive.
- @item @code{clean-cache} (default: @code{14})
- Discard the cache after this amount of days. Use @code{#f} to never
- clear the cache.
- @item @code{partition-style} (default: @code{'msdos})
- The type of partition to create. When set, it must be one of
- @code{'msdos}, @code{'none} or a string.
- @item @code{partition-alignment} (default: @code{2048})
- Alignment of the partition in sectors.
- @end table
- @end deftp
- @deffn {Scheme Procedure} debootstrap-variant @var{name} @var{configuration}
- This is a helper procedure that creates a @code{ganeti-os-variant} record. It
- takes two parameters: a name and a @code{debootstrap-configuration} object.
- @end deffn
- @deffn {Scheme Procedure} debootstrap-os @var{variants}@dots{}
- This is a helper procedure that creates a @code{ganeti-os} record. It takes
- a list of variants created with @code{debootstrap-variant}.
- @end deffn
- @deffn {Scheme Procedure} guix-variant @var{name} @var{configuration}
- This is a helper procedure that creates a @code{ganeti-os-variant} record for
- use with the Guix OS provider. It takes a name and a G-expression that returns
- a ``file-like'' (@pxref{G-Expressions, file-like objects}) object containing a
- Guix System configuration.
- @end deffn
- @deffn {Scheme Procedure} guix-os @var{variants}@dots{}
- This is a helper procedure that creates a @code{ganeti-os} record. It
- takes a list of variants produced by @code{guix-variant}.
- @end deffn
- @defvr {Scheme Variable} %default-debootstrap-variants
- This is a convenience variable to make the debootstrap provider work
- ``out of the box'' without users having to declare variants manually. It
- contains a single debootstrap variant with the default configuration:
- @lisp
- (list (debootstrap-variant
- "default"
- (debootstrap-configuration)))
- @end lisp
- @end defvr
- @defvr {Scheme Variable} %default-guix-variants
- This is a convenience variable to make the Guix OS provider work without
- additional configuration. It creates a virtual machine that has an SSH
- server, a serial console, and authorizes the Ganeti hosts SSH keys.
- @lisp
- (list (guix-variant
- "default"
- (file-append ganeti-instance-guix
- "/share/doc/ganeti-instance-guix/examples/dynamic.scm")))
- @end lisp
- @end defvr
- Users can implement support for OS providers unbeknownst to Guix by extending
- the @code{ganeti-os} and @code{ganeti-os-variant} records appropriately.
- For example:
- @lisp
- (ganeti-os
- (name "custom")
- (extension ".conf")
- (variants
- (list (ganeti-os-variant
- (name "foo")
- (configuration (plain-file "bar" "this is fine"))))))
- @end lisp
- That creates @file{/etc/ganeti/instance-custom/variants/foo.conf} which points
- to a file in the store with contents @code{this is fine}. It also creates
- @file{/etc/ganeti/instance-custom/variants/variants.list} with contents @code{foo}.
- Obviously this may not work for all OS providers out there. If you find the
- interface limiting, please reach out to @email{guix-devel@@gnu.org}.
- The rest of this section documents the various services that are included by
- @code{ganeti-service-type}.
- @defvr {Scheme Variable} ganeti-noded-service-type
- @command{ganeti-noded} is the daemon responsible for node-specific functions
- within the Ganeti system. The value of this service must be a
- @code{ganeti-noded-configuration} object.
- @end defvr
- @deftp {Data Type} ganeti-noded-configuration
- This is the configuration for the @code{ganeti-noded} service.
- @table @asis
- @item @code{ganeti} (default: @code{ganeti})
- The @code{ganeti} package to use for this service.
- @item @code{port} (default: @code{1811})
- The TCP port on which the node daemon listens for network requests.
- @item @code{address} (default: @code{"0.0.0.0"})
- The network address that the daemon will bind to. The default address means
- bind to all available addresses.
- @item @code{interface} (default: @code{#f})
- When this is set, it must be a specific network interface (e.g.@: @code{eth0})
- that the daemon will bind to.
- @item @code{max-clients} (default: @code{20})
- This sets a limit on the maximum number of simultaneous client connections
- that the daemon will handle. Connections above this count are accepted, but
- no responses will be sent until enough connections have closed.
- @item @code{ssl?} (default: @code{#t})
- Whether to use SSL/TLS to encrypt network communications. The certificate
- is automatically provisioned by the cluster and can be rotated with
- @command{gnt-cluster renew-crypto}.
- @item @code{ssl-key} (default: @file{"/var/lib/ganeti/server.pem"})
- This can be used to provide a specific encryption key for TLS communications.
- @item @code{ssl-cert} (default: @file{"/var/lib/ganeti/server.pem"})
- This can be used to provide a specific certificate for TLS communications.
- @item @code{debug?} (default: @code{#f})
- When true, the daemon performs additional logging for debugging purposes.
- Note that this will leak encryption details to the log files, use with caution.
- @end table
- @end deftp
- @defvr {Scheme Variable} ganeti-confd-service-type
- @command{ganeti-confd} answers queries related to the configuration of a
- Ganeti cluster. The purpose of this daemon is to have a highly available
- and fast way to query cluster configuration values. It is automatically
- active on all @dfn{master candidates}. The value of this service must be a
- @code{ganeti-confd-configuration} object.
- @end defvr
- @deftp {Data Type} ganeti-confd-configuration
- This is the configuration for the @code{ganeti-confd} service.
- @table @asis
- @item @code{ganeti} (default: @code{ganeti})
- The @code{ganeti} package to use for this service.
- @item @code{port} (default: @code{1814})
- The UDP port on which to listen for network requests.
- @item @code{address} (default: @code{"0.0.0.0"})
- Network address that the daemon will bind to.
- @item @code{debug?} (default: @code{#f})
- When true, the daemon performs additional logging for debugging purposes.
- @end table
- @end deftp
- @defvr {Scheme Variable} ganeti-wconfd-service-type
- @command{ganeti-wconfd} is the daemon that has authoritative knowledge
- about the cluster configuration and is the only entity that can accept
- changes to it. All jobs that need to modify the configuration will do so
- by sending appropriate requests to this daemon. It only runs on the
- @dfn{master node} and will automatically disable itself on other nodes.
- The value of this service must be a
- @code{ganeti-wconfd-configuration} object.
- @end defvr
- @deftp {Data Type} ganeti-wconfd-configuration
- This is the configuration for the @code{ganeti-wconfd} service.
- @table @asis
- @item @code{ganeti} (default: @code{ganeti})
- The @code{ganeti} package to use for this service.
- @item @code{no-voting?} (default: @code{#f})
- The daemon will refuse to start if the majority of cluster nodes does not
- agree that it is running on the master node. Set to @code{#t} to start
- even if a quorum can not be reached (dangerous, use with caution).
- @item @code{debug?} (default: @code{#f})
- When true, the daemon performs additional logging for debugging purposes.
- @end table
- @end deftp
- @defvr {Scheme Variable} ganeti-luxid-service-type
- @command{ganeti-luxid} is a daemon used to answer queries related to the
- configuration and the current live state of a Ganeti cluster. Additionally,
- it is the authoritative daemon for the Ganeti job queue. Jobs can be
- submitted via this daemon and it schedules and starts them.
- It takes a @code{ganeti-luxid-configuration} object.
- @end defvr
- @deftp {Data Type} ganeti-luxid-configuration
- This is the configuration for the @code{ganeti-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{unsafe-pattern} (default: @code{#f})
- An optional Perl regular expression for catching unsafe configurations in
- the configuration file. See
- @uref{https://gitolite.com/gitolite/git-config.html#compensating-for-unsafe_patt,
- Gitolite's documentation} for more information.
- When the value is not @code{#f}, it should be a string containing a Perl
- regular expression, such as @samp{"[`~#\$\&()|;<>]"}, which is the default
- value used by gitolite. It rejects any special character in configuration
- that might be interpreted by a shell, which is useful when sharing the
- administration burden with other people that do not otherwise have shell
- access on the server.
- @item @code{git-config-keys} (default: @code{""})
- Gitolite allows you to set git config values using the @samp{config}
- keyword. This setting allows control over the config keys to accept.
- @item @code{roles} (default: @code{'(("READERS" . 1) ("WRITERS" . ))})
- Set the role names allowed to be used by users running the perms command.
- @item @code{enable} (default: @code{'("help" "desc" "info" "perms" "writable" "ssh-authkeys" "git-config" "daemon" "gitweb")})
- This setting controls the commands and features to enable within Gitolite.
- @end table
- @end deftp
- @subsubheading Gitile Service
- @cindex Gitile service
- @cindex Git, forge
- @uref{https://git.lepiller.eu/gitile, Gitile} is a Git forge for viewing
- public git repository contents from a web browser.
- Gitile works best in collaboration with Gitolite, and will serve the public
- repositories from Gitolite by default. The service should listen only on
- a local port, and a webserver should be configured to serve static resources.
- The gitile service provides an easy way to extend the Nginx service for
- that purpose (@pxref{NGINX}).
- The following example will configure Gitile to serve repositories from a
- custom location, with some default messages for the home page and the
- footers.
- @lisp
- (service gitile-service-type
- (gitile-configuration
- (repositories "/srv/git")
- (base-git-url "https://myweb.site/git")
- (index-title "My git repositories")
- (intro '((p "This is all my public work!")))
- (footer '((p "This is the end")))
- (nginx-server-block
- (nginx-server-configuration
- (ssl-certificate
- "/etc/letsencrypt/live/myweb.site/fullchain.pem")
- (ssl-certificate-key
- "/etc/letsencrypt/live/myweb.site/privkey.pem")
- (listen '("443 ssl http2" "[::]:443 ssl http2"))
- (locations
- (list
- ;; Allow for https anonymous fetch on /git/ urls.
- (git-http-nginx-location-configuration
- (git-http-configuration
- (uri-path "/git/")
- (git-root "/var/lib/gitolite/repositories")))))))))
- @end lisp
- In addition to the configuration record, you should configure your git
- repositories to contain some optional information. First, your public
- repositories need to contain the @file{git-daemon-export-ok} magic file
- that allows Git to export the repository. Gitile uses the presence of this
- file to detect public repositories it should make accessible. To do so with
- Gitolite for instance, modify your @file{conf/gitolite.conf} to include
- this in the repositories you want to make public:
- @example
- repo foo
- R = daemon
- @end example
- In addition, Gitile can read the repository configuration to display more
- infomation on the repository. Gitile uses the gitweb namespace for its
- configuration. As an example, you can use the following in your
- @file{conf/gitolite.conf}:
- @example
- repo foo
- R = daemon
- desc = A long description, optionally with <i>HTML</i>, shown on the index page
- config gitweb.name = The Foo Project
- config gitweb.synopsis = A short description, shown on the main page of the project
- @end example
- Do not forget to commit and push these changes once you are satisfied. You
- may need to change your gitolite configuration to allow the previous
- configuration options to be set. One way to do that is to add the
- following service definition:
- @lisp
- (service gitolite-service-type
- (gitolite-configuration
- (admin-pubkey (local-file "key.pub"))
- (rc-file
- (gitolite-rc-file
- (umask #o0027)
- ;; Allow to set any configuration key
- (git-config-keys ".*")
- ;; Allow any text as a valid configuration value
- (unsafe-patt "^$")))))
- @end lisp
- @deftp {Data Type} gitile-configuration
- Data type representing the configuration for @code{gitile-service-type}.
- @table @asis
- @item @code{package} (default: @var{gitile})
- Gitile package to use.
- @item @code{host} (default: @code{"localhost"})
- The host on which gitile is listening.
- @item @code{port} (default: @code{8080})
- The port on which gitile is listening.
- @item @code{database} (default: @code{"/var/lib/gitile/gitile-db.sql"})
- The location of the database.
- @item @code{repositories} (default: @code{"/var/lib/gitolite/repositories"})
- The location of the repositories. Note that only public repositories will
- be shown by Gitile. To make a repository public, add an empty
- @file{git-daemon-export-ok} file at the root of that repository.
- @item @code{base-git-url}
- The base git url that will be used to show clone commands.
- @item @code{index-title} (default: @code{"Index"})
- The page title for the index page that lists all the available repositories.
- @item @code{intro} (default: @code{'()})
- The intro content, as a list of sxml expressions. This is shown above the list
- of repositories, on the index page.
- @item @code{footer} (default: @code{'()})
- The footer content, as a list of sxml expressions. This is shown on every
- page served by Gitile.
- @item @code{nginx-server-block}
- An nginx server block that will be extended and used as a reverse proxy by
- Gitile to serve its pages, and as a normal web server to serve its assets.
- You can use this block to add more custom URLs to your domain, such as a
- @code{/git/} URL for anonymous clones, or serving any other files you would
- like to serve.
- @end table
- @end deftp
- @node Game Services
- @subsection Game Services
- @subsubheading The Battle for Wesnoth Service
- @cindex wesnothd
- @uref{https://wesnoth.org, The Battle for Wesnoth} is a fantasy, turn
- based tactical strategy game, with several single player campaigns, and
- multiplayer games (both networked and local).
- @defvar {Scheme Variable} wesnothd-service-type
- Service type for the wesnothd service. Its value must be a
- @code{wesnothd-configuration} object. To run wesnothd in the default
- configuration, instantiate it as:
- @lisp
- (service wesnothd-service-type)
- @end lisp
- @end defvar
- @deftp {Data Type} wesnothd-configuration
- Data type representing the configuration of @command{wesnothd}.
- @table @asis
- @item @code{package} (default: @code{wesnoth-server})
- The wesnoth server package to use.
- @item @code{port} (default: @code{15000})
- The port to bind the server to.
- @end table
- @end deftp
- @node PAM Mount Service
- @subsection PAM Mount Service
- @cindex pam-mount
- The @code{(gnu services pam-mount)} module provides a service allowing
- users to mount volumes when they log in. It should be able to mount any
- volume format supported by the system.
- @defvar {Scheme Variable} pam-mount-service-type
- Service type for PAM Mount support.
- @end defvar
- @deftp {Data Type} pam-mount-configuration
- Data type representing the configuration of PAM Mount.
- It takes the following parameters:
- @table @asis
- @item @code{rules}
- The configuration rules that will be used to generate
- @file{/etc/security/pam_mount.conf.xml}.
- The configuration rules are SXML elements (@pxref{SXML,,, guile, GNU
- Guile Reference Manual}), and the default ones don't mount anything for
- anyone at login:
- @lisp
- `((debug (@@ (enable "0")))
- (mntoptions (@@ (allow ,(string-join
- '("nosuid" "nodev" "loop"
- "encryption" "fsck" "nonempty"
- "allow_root" "allow_other")
- ","))))
- (mntoptions (@@ (require "nosuid,nodev")))
- (logout (@@ (wait "0")
- (hup "0")
- (term "no")
- (kill "no")))
- (mkmountpoint (@@ (enable "1")
- (remove "true"))))
- @end lisp
- Some @code{volume} elements must be added to automatically mount volumes
- at login. Here's an example allowing the user @code{alice} to mount her
- encrypted @env{HOME} directory and allowing the user @code{bob} to mount
- the partition where he stores his data:
- @lisp
- (define pam-mount-rules
- `((debug (@@ (enable "0")))
- (volume (@@ (user "alice")
- (fstype "crypt")
- (path "/dev/sda2")
- (mountpoint "/home/alice")))
- (volume (@@ (user "bob")
- (fstype "auto")
- (path "/dev/sdb3")
- (mountpoint "/home/bob/data")
- (options "defaults,autodefrag,compress")))
- (mntoptions (@@ (allow ,(string-join
- '("nosuid" "nodev" "loop"
- "encryption" "fsck" "nonempty"
- "allow_root" "allow_other")
- ","))))
- (mntoptions (@@ (require "nosuid,nodev")))
- (logout (@@ (wait "0")
- (hup "0")
- (term "no")
- (kill "no")))
- (mkmountpoint (@@ (enable "1")
- (remove "true")))))
- (service pam-mount-service-type
- (pam-mount-configuration
- (rules pam-mount-rules)))
- @end lisp
- The complete list of possible options can be found in the man page for
- @uref{http://pam-mount.sourceforge.net/pam_mount.conf.5.html, pam_mount.conf}.
- @end table
- @end deftp
- @node Guix Services
- @subsection Guix Services
- @subsubheading Guix Build Coordinator
- The @uref{https://git.cbaines.net/guix/build-coordinator/,Guix Build
- Coordinator} aids in distributing derivation builds among machines
- running an @dfn{agent}. The build daemon is still used to build the
- derivations, but the Guix Build Coordinator manages allocating builds
- and working with the results.
- @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{authentication}
- Record describing how this agent should authenticate with the
- coordinator. Possible record types are described below.
- @item @code{systems} (default: @code{#f})
- The systems for which this agent should fetch builds. The agent process
- will use the current system it's running on as the default.
- @item @code{max-parallel-builds} (default: @code{1})
- The number of builds to perform in parallel.
- @item @code{max-1min-load-average} (default: @code{#f})
- Load average value to look at when considering starting new builds, if
- the 1 minute load average exceeds this value, the agent will wait before
- starting new builds.
- This will be unspecified if the value is @code{#f}, and the agent will
- use the number of cores reported by the system as the max 1 minute load
- average.
- @item @code{derivation-substitute-urls} (default: @code{#f})
- URLs from which to attempt to fetch substitutes for derivations, if the
- derivations aren't already available.
- @item @code{non-derivation-substitute-urls} (default: @code{#f})
- URLs from which to attempt to fetch substitutes for build inputs, if the
- input store items aren't already available.
- @end table
- @end deftp
- @deftp {Data Type} guix-build-coordinator-agent-password-auth
- Data type representing an agent authenticating with a coordinator via a
- UUID and password.
- @table @asis
- @item @code{uuid}
- The UUID of the agent. This should be generated by the coordinator
- process, stored in the coordinator database, and used by the intended
- agent.
- @item @code{password}
- The password to use when connecting to the coordinator.
- @end table
- @end deftp
- @deftp {Data Type} guix-build-coordinator-agent-password-file-auth
- Data type representing an agent authenticating with a coordinator via a
- UUID and password read from a file.
- @table @asis
- @item @code{uuid}
- The UUID of the agent. This should be generated by the coordinator
- process, stored in the coordinator database, and used by the intended
- agent.
- @item @code{password-file}
- A file containing the password to use when connecting to the
- coordinator.
- @end table
- @end deftp
- @deftp {Data Type} guix-build-coordinator-agent-dynamic-auth
- Data type representing an agent authenticating with a coordinator via a
- dynamic auth token and agent name.
- @table @asis
- @item @code{agent-name}
- Name of an agent, this is used to match up to an existing entry in the
- database if there is one. When no existing entry is found, a new entry
- is automatically added.
- @item @code{token}
- Dynamic auth token, this is created and stored in the coordinator
- database, and is used by the agent to authenticate.
- @end table
- @end deftp
- @deftp {Data Type} guix-build-coordinator-agent-dynamic-auth-with-file
- Data type representing an agent authenticating with a coordinator via a
- dynamic auth token read from a file and agent name.
- @table @asis
- @item @code{agent-name}
- Name of an agent, this is used to match up to an existing entry in the
- database if there is one. When no existing entry is found, a new entry
- is automatically added.
- @item @code{token-file}
- File containing the dynamic auth token, this is created and stored in
- the coordinator database, and is used by the agent to authenticate.
- @end table
- @end deftp
- The Guix Build Coordinator package contains a script to query an
- instance of the Guix Data Service for derivations to build, and then
- submit builds for those derivations to the coordinator. The service
- type below assists in running this script. This is an additional tool
- that may be useful when building derivations contained within an
- instance of the Guix Data Service.
- @defvar {Scheme Variable} guix-build-coordinator-queue-builds-service-type
- Service type for the
- guix-build-coordinator-queue-builds-from-guix-data-service script. Its
- value must be a @code{guix-build-coordinator-queue-builds-configuration}
- object.
- @end defvar
- @deftp {Data Type} guix-build-coordinator-queue-builds-configuration
- Data type representing the options to the queue builds from guix data
- service script.
- @table @asis
- @item @code{package} (default: @code{guix-build-coordinator})
- The Guix Build Coordinator package to use.
- @item @code{user} (default: @code{"guix-build-coordinator-queue-builds"})
- The system user to run the service as.
- @item @code{coordinator} (default: @code{"http://localhost:8746"})
- The URI to use when connecting to the coordinator.
- @item @code{systems} (default: @code{#f})
- The systems for which to fetch derivations to build.
- @item @code{systems-and-targets} (default: @code{#f})
- An association list of system and target pairs for which to fetch
- derivations to build.
- @item @code{guix-data-service} (default: @code{"https://data.guix.gnu.org"})
- The Guix Data Service instance from which to query to find out about
- derivations to build.
- @item @code{processed-commits-file} (default: @code{"/var/cache/guix-build-coordinator-queue-builds/processed-commits"})
- A file to record which commits have been processed, to avoid needlessly
- processing them again if the service is restarted.
- @end table
- @end deftp
- @subsubheading Guix Data Service
- The @uref{http://data.guix.gnu.org,Guix Data Service} processes, stores
- and provides data about GNU Guix. This includes information about
- packages, derivations and lint warnings.
- The data is stored in a PostgreSQL database, and available through a web
- interface.
- @defvar {Scheme Variable} guix-data-service-type
- Service type for the Guix Data Service. Its value must be a
- @code{guix-data-service-configuration} object. The service optionally
- extends the getmail service, as the guix-commits mailing list is used to
- find out about changes in the Guix git repository.
- @end defvar
- @deftp {Data Type} guix-data-service-configuration
- Data type representing the configuration of the Guix Data Service.
- @table @asis
- @item @code{package} (default: @code{guix-data-service})
- The Guix Data Service package to use.
- @item @code{user} (default: @code{"guix-data-service"})
- The system user to run the service as.
- @item @code{group} (default: @code{"guix-data-service"})
- The system group to run the service as.
- @item @code{port} (default: @code{8765})
- The port to bind the web service to.
- @item @code{host} (default: @code{"127.0.0.1"})
- The host to bind the web service to.
- @item @code{getmail-idle-mailboxes} (default: @code{#f})
- If set, this is the list of mailboxes that the getmail service will be
- configured to listen to.
- @item @code{commits-getmail-retriever-configuration} (default: @code{#f})
- If set, this is the @code{getmail-retriever-configuration} object with
- which to configure getmail to fetch mail from the guix-commits mailing
- list.
- @item @code{extra-options} (default: @var{'()})
- Extra command line options for @code{guix-data-service}.
- @item @code{extra-process-jobs-options} (default: @var{'()})
- Extra command line options for @code{guix-data-service-process-jobs}.
- @end table
- @end deftp
- @node Linux Services
- @subsection Linux Services
- @cindex oom
- @cindex out of memory killer
- @cindex earlyoom
- @cindex early out of memory daemon
- @subsubheading Early OOM Service
- @uref{https://github.com/rfjakob/earlyoom,Early OOM}, also known as
- Earlyoom, is a minimalist out of memory (OOM) daemon that runs in user
- space and provides a more responsive and configurable alternative to the
- in-kernel OOM killer. It is useful to prevent the system from becoming
- unresponsive when it runs out of memory.
- @deffn {Scheme Variable} earlyoom-service-type
- The service type for running @command{earlyoom}, the Early OOM daemon.
- Its value must be a @code{earlyoom-configuration} object, described
- below. The service can be instantiated in its default configuration
- with:
- @lisp
- (service earlyoom-service-type)
- @end lisp
- @end deffn
- @deftp {Data Type} earlyoom-configuration
- This is the configuration record for the @code{earlyoom-service-type}.
- @table @asis
- @item @code{earlyoom} (default: @var{earlyoom})
- The Earlyoom package to use.
- @item @code{minimum-available-memory} (default: @code{10})
- The threshold for the minimum @emph{available} memory, in percentages.
- @item @code{minimum-free-swap} (default: @code{10})
- The threshold for the minimum free swap memory, in percentages.
- @item @code{prefer-regexp} (default: @code{#f})
- A regular expression (as a string) to match the names of the processes
- that should be preferably killed.
- @item @code{avoid-regexp} (default: @code{#f})
- A regular expression (as a string) to match the names of the processes
- that should @emph{not} be killed.
- @item @code{memory-report-interval} (default: @code{0})
- The interval in seconds at which a memory report is printed. It is
- disabled by default.
- @item @code{ignore-positive-oom-score-adj?} (default: @code{#f})
- A boolean indicating whether the positive adjustments set in
- @file{/proc/*/oom_score_adj} should be ignored.
- @item @code{show-debug-messages?} (default: @code{#f})
- A boolean indicating whether debug messages should be printed. The logs
- are saved at @file{/var/log/earlyoom.log}.
- @item @code{send-notification-command} (default: @code{#f})
- This can be used to provide a custom command used for sending
- notifications.
- @end table
- @end deftp
- @cindex modprobe
- @cindex kernel module loader
- @subsubheading Kernel Module Loader Service
- The kernel module loader service allows one to load loadable kernel
- modules at boot. This is especially useful for modules that don't
- autoload and need to be manually loaded, as is the case with
- @code{ddcci}.
- @deffn {Scheme Variable} kernel-module-loader-service-type
- The service type for loading loadable kernel modules at boot with
- @command{modprobe}. Its value must be a list of strings representing
- module names. For example loading the drivers provided by
- @code{ddcci-driver-linux}, in debugging mode by passing some module
- parameters, can be done as follow:
- @lisp
- (use-modules (gnu) (gnu services))
- (use-package-modules linux)
- (use-service-modules linux)
- (define ddcci-config
- (plain-file "ddcci.conf"
- "options ddcci dyndbg delay=120"))
- (operating-system
- ...
- (services (cons* (service kernel-module-loader-service-type
- '("ddcci" "ddcci_backlight"))
- (simple-service 'ddcci-config etc-service-type
- (list `("modprobe.d/ddcci.conf"
- ,ddcci-config)))
- %base-services))
- (kernel-loadable-modules (list ddcci-driver-linux)))
- @end lisp
- @end deffn
- @cindex rasdaemon
- @cindex Platform Reliability, Availability and Serviceability daemon
- @subsubheading Rasdaemon Service
- The Rasdaemon service provides a daemon which monitors platform
- @acronym{RAS, Reliability@comma{} Availability@comma{} and Serviceability} reports from
- Linux kernel trace events, logging them to syslogd.
- Reliability, Availability and Serviceability is a concept used on servers meant
- to measure their robustness.
- @strong{Relability} is the probability that a system will produce correct
- outputs:
- @itemize @bullet
- @item Generally measured as Mean Time Between Failures (MTBF), and
- @item Enhanced by features that help to avoid, detect and repair hardware
- faults
- @end itemize
- @strong{Availability} is the probability that a system is operational at a
- given time:
- @itemize @bullet
- @item Generally measured as a percentage of downtime per a period of time, and
- @item Often uses mechanisms to detect and correct hardware faults in runtime.
- @end itemize
- @strong{Serviceability} is the simplicity and speed with which a system can be
- repaired or maintained:
- @itemize @bullet
- @item Generally measured on Mean Time Between Repair (MTBR).
- @end itemize
- Among the monitoring measures, the most usual ones include:
- @itemize @bullet
- @item CPU – detect errors at instruction execution and at L1/L2/L3 caches;
- @item Memory – add error correction logic (ECC) to detect and correct errors;
- @item I/O – add CRC checksums for transferred data;
- @item Storage – RAID, journal file systems, checksums, Self-Monitoring,
- Analysis and Reporting Technology (SMART).
- @end itemize
- By monitoring the number of occurrences of error detections, it is possible to
- identify if the probability of hardware errors is increasing, and, on such
- case, do a preventive maintenance to replace a degraded component while those
- errors are correctable.
- For detailed information about the types of error events gathered and how to
- make sense of them, see the kernel administrator's guide at
- @url{https://www.kernel.org/doc/html/latest/admin-guide/ras.html}.
- @defvr {Scheme Variable} rasdaemon-service-type
- Service type for the @command{rasdaemon} service. It accepts a
- @code{rasdaemon-configuration} object. Instantiating like
- @lisp
- (service rasdaemon-service-type)
- @end lisp
- will load with a default configuration, which monitors all events and logs to
- syslogd.
- @end defvr
- @deftp {Data Type} rasdaemon-configuration
- The data type representing the configuration of @command{rasdaemon}.
- @table @asis
- @item @code{record?} (default: @code{#f})
- A boolean indicating whether to record the events in an SQLite database. This
- provides a more structured access to the information contained in the log file.
- The database location is hard-coded to @file{/var/lib/rasdaemon/ras-mc_event.db}.
- @end table
- @end deftp
- @cindex zram
- @cindex compressed swap
- @cindex Compressed RAM-based block devices
- @subsubheading Zram Device Service
- The Zram device service provides a compressed swap device in system
- memory. The Linux Kernel documentation has more information about
- @uref{https://www.kernel.org/doc/html/latest/admin-guide/blockdev/zram.html,zram}
- devices.
- @deffn {Scheme Variable} zram-device-service-type
- This service creates the zram block device, formats it as swap and
- enables it as a swap device. The service's value is a
- @code{zram-device-configuration} record.
- @deftp {Data Type} zram-device-configuration
- This is the data type representing the configuration for the zram-device
- service.
- @table @asis
- @item @code{size} (default @code{"1G"})
- This is the amount of space you wish to provide for the zram device. It
- accepts a string and can be a number of bytes or use a suffix, eg.:
- @code{"512M"} or @code{1024000}.
- @item @code{compression-algorithm} (default @code{'lzo})
- This is the compression algorithm you wish to use. It is difficult to
- list all the possible compression options, but common ones supported by
- Guix's Linux Libre Kernel include @code{'lzo}, @code{'lz4} and @code{'zstd}.
- @item @code{memory-limit} (default @code{0})
- This is the maximum amount of memory which the zram device can use.
- Setting it to '0' disables the limit. While it is generally expected
- that compression will be 2:1, it is possible that uncompressable data
- can be written to swap and this is a method to limit how much memory can
- be used. It accepts a string and can be a number of bytes or use a
- suffix, eg.: @code{"2G"}.
- @item @code{priority} (default @code{-1})
- This is the priority of the swap device created from the zram device.
- @code{swapon} accepts values between -1 and 32767, with higher values
- indicating higher priority. Higher priority swap will generally be used
- first.
- @end table
- @end deftp
- @end deffn
- @node Hurd Services
- @subsection Hurd Services
- @defvr {Scheme Variable} hurd-console-service-type
- This service starts the fancy @code{VGA} console client on the Hurd.
- The service's value is a @code{hurd-console-configuration} record.
- @end defvr
- @deftp {Data Type} hurd-console-configuration
- This is the data type representing the configuration for the
- hurd-console-service.
- @table @asis
- @item @code{hurd} (default: @var{hurd})
- The Hurd package to use.
- @end table
- @end deftp
- @defvr {Scheme Variable} hurd-getty-service-type
- This service starts a tty using the Hurd @code{getty} program.
- The service's value is a @code{hurd-getty-configuration} record.
- @end defvr
- @deftp {Data Type} hurd-getty-configuration
- This is the data type representing the configuration for the
- hurd-getty-service.
- @table @asis
- @item @code{hurd} (default: @var{hurd})
- The Hurd package to use.
- @item @code{tty}
- The name of the console this Getty runs on---e.g., @code{"tty1"}.
- @item @code{baud-rate} (default: @code{38400})
- An integer specifying the baud rate of the tty.
- @end table
- @end deftp
- @node Miscellaneous Services
- @subsection Miscellaneous Services
- @cindex fingerprint
- @subsubheading Fingerprint Service
- The @code{(gnu services authentication)} module provides a DBus service to
- read and identify fingerprints via a fingerprint sensor.
- @defvr {Scheme Variable} fprintd-service-type
- The service type for @command{fprintd}, which provides the fingerprint
- reading capability.
- @lisp
- (service fprintd-service-type)
- @end lisp
- @end defvr
- @cindex sysctl
- @subsubheading System Control Service
- The @code{(gnu services sysctl)} provides a service to configure kernel
- parameters at boot.
- @defvr {Scheme Variable} sysctl-service-type
- The service type for @command{sysctl}, which modifies kernel parameters
- under @file{/proc/sys/}. To enable IPv4 forwarding, it can be
- instantiated as:
- @lisp
- (service sysctl-service-type
- (sysctl-configuration
- (settings '(("net.ipv4.ip_forward" . "1")))))
- @end lisp
- Since @code{sysctl-service-type} is used in the default lists of
- services, @code{%base-services} and @code{%desktop-services}, you can
- use @code{modify-services} to change its configuration and add the
- kernel parameters that you want (@pxref{Service Reference,
- @code{modify-services}}).
- @lisp
- (modify-services %base-services
- (sysctl-service-type config =>
- (sysctl-configuration
- (settings (append '(("net.ipv4.ip_forward" . "1"))
- %default-sysctl-settings)))))
- @end lisp
- @end defvr
- @deftp {Data Type} sysctl-configuration
- The data type representing the configuration of @command{sysctl}.
- @table @asis
- @item @code{sysctl} (default: @code{(file-append procps "/sbin/sysctl"})
- The @command{sysctl} executable to use.
- @item @code{settings} (default: @code{%default-sysctl-settings})
- An association list specifies kernel parameters and their values.
- @end table
- @end deftp
- @defvr {Scheme Variable} %default-sysctl-settings
- An association list specifying the default @command{sysctl} parameters
- on Guix System.
- @end defvr
- @cindex pcscd
- @subsubheading PC/SC Smart Card Daemon Service
- The @code{(gnu services security-token)} module provides the following service
- to run @command{pcscd}, the PC/SC Smart Card Daemon. @command{pcscd} is the
- daemon program for pcsc-lite and the MuscleCard framework. It is a resource
- manager that coordinates communications with smart card readers, smart cards
- and cryptographic tokens that are connected to the system.
- @defvr {Scheme Variable} pcscd-service-type
- Service type for the @command{pcscd} service. Its value must be a
- @code{pcscd-configuration} object. To run pcscd in the default
- configuration, instantiate it as:
- @lisp
- (service pcscd-service-type)
- @end lisp
- @end defvr
- @deftp {Data Type} pcscd-configuration
- The data type representing the configuration of @command{pcscd}.
- @table @asis
- @item @code{pcsc-lite} (default: @code{pcsc-lite})
- The pcsc-lite package that provides pcscd.
- @item @code{usb-drivers} (default: @code{(list ccid)})
- List of packages that provide USB drivers to pcscd. Drivers are expected to be
- under @file{pcsc/drivers} in the store directory of the package.
- @end table
- @end deftp
- @cindex lirc
- @subsubheading Lirc Service
- The @code{(gnu services lirc)} module provides the following service.
- @deffn {Scheme Procedure} lirc-service [#:lirc lirc] @
- [#:device #f] [#:driver #f] [#:config-file #f] @
- [#:extra-options '()]
- Return a service that runs @url{http://www.lirc.org,LIRC}, a daemon that
- decodes infrared signals from remote controls.
- Optionally, @var{device}, @var{driver} and @var{config-file}
- (configuration file name) may be specified. See @command{lircd} manual
- for details.
- Finally, @var{extra-options} is a list of additional command-line options
- passed to @command{lircd}.
- @end deffn
- @cindex spice
- @subsubheading Spice Service
- The @code{(gnu services spice)} module provides the following service.
- @deffn {Scheme Procedure} spice-vdagent-service [#:spice-vdagent]
- Returns a service that runs @url{https://www.spice-space.org,VDAGENT}, a daemon
- that enables sharing the clipboard with a vm and setting the guest display
- resolution when the graphical console window resizes.
- @end deffn
- @cindex inputattach
- @subsubheading inputattach Service
- @cindex tablet input, for Xorg
- @cindex touchscreen input, for Xorg
- The @uref{https://linuxwacom.github.io/, inputattach} service allows you to
- use input devices such as Wacom tablets, touchscreens, or joysticks with the
- Xorg display server.
- @deffn {Scheme Variable} inputattach-service-type
- Type of a service that runs @command{inputattach} on a device and
- dispatches events from it.
- @end deffn
- @deftp {Data Type} inputattach-configuration
- @table @asis
- @item @code{device-type} (default: @code{"wacom"})
- The type of device to connect to. Run @command{inputattach --help}, from the
- @code{inputattach} package, to see the list of supported device types.
- @item @code{device} (default: @code{"/dev/ttyS0"})
- The device file to connect to the device.
- @item @code{baud-rate} (default: @code{#f})
- Baud rate to use for the serial connection.
- Should be a number or @code{#f}.
- @item @code{log-file} (default: @code{#f})
- If true, this must be the name of a file to log messages to.
- @end table
- @end deftp
- @subsubheading Dictionary Service
- @cindex dictionary
- The @code{(gnu services dict)} module provides the following service:
- @defvr {Scheme Variable} dicod-service-type
- This is the type of the service that runs the @command{dicod} daemon, an
- implementation of DICT server (@pxref{Dicod,,, dico, GNU Dico Manual}).
- @end defvr
- @deffn {Scheme Procedure} dicod-service [#:config (dicod-configuration)]
- Return a service that runs the @command{dicod} daemon, an implementation
- of DICT server (@pxref{Dicod,,, dico, GNU Dico Manual}).
- The optional @var{config} argument specifies the configuration for
- @command{dicod}, which should be a @code{<dicod-configuration>} object, by
- default it serves the GNU Collaborative International Dictionary of English.
- You can add @command{open localhost} to your @file{~/.dico} file to make
- @code{localhost} the default server for @command{dico} client
- (@pxref{Initialization File,,, dico, GNU Dico Manual}).
- @end deffn
- @deftp {Data Type} dicod-configuration
- Data type representing the configuration of dicod.
- @table @asis
- @item @code{dico} (default: @var{dico})
- Package object of the GNU Dico dictionary server.
- @item @code{interfaces} (default: @var{'("localhost")})
- This is the list of IP addresses and ports and possibly socket file
- names to listen to (@pxref{Server Settings, @code{listen} directive,,
- dico, GNU Dico Manual}).
- @item @code{handlers} (default: @var{'()})
- List of @code{<dicod-handler>} objects denoting handlers (module instances).
- @item @code{databases} (default: @var{(list %dicod-database:gcide)})
- List of @code{<dicod-database>} objects denoting dictionaries to be served.
- @end table
- @end deftp
- @deftp {Data Type} dicod-handler
- Data type representing a dictionary handler (module instance).
- @table @asis
- @item @code{name}
- Name of the handler (module instance).
- @item @code{module} (default: @var{#f})
- Name of the dicod module of the handler (instance). If it is @code{#f},
- the module has the same name as the handler.
- (@pxref{Modules,,, dico, GNU Dico Manual}).
- @item @code{options}
- List of strings or gexps representing the arguments for the module handler
- @end table
- @end deftp
- @deftp {Data Type} dicod-database
- Data type representing a dictionary database.
- @table @asis
- @item @code{name}
- Name of the database, will be used in DICT commands.
- @item @code{handler}
- Name of the dicod handler (module instance) used by this database
- (@pxref{Handlers,,, dico, GNU Dico Manual}).
- @item @code{complex?} (default: @var{#f})
- Whether the database configuration complex. The complex configuration
- will need a corresponding @code{<dicod-handler>} object, otherwise not.
- @item @code{options}
- List of strings or gexps representing the arguments for the database
- (@pxref{Databases,,, dico, GNU Dico Manual}).
- @end table
- @end deftp
- @defvr {Scheme Variable} %dicod-database:gcide
- A @code{<dicod-database>} object serving the GNU Collaborative International
- Dictionary of English using the @code{gcide} package.
- @end defvr
- The following is an example @code{dicod-service} configuration.
- @lisp
- (dicod-service #:config
- (dicod-configuration
- (handlers (list (dicod-handler
- (name "wordnet")
- (module "dictorg")
- (options
- (list #~(string-append "dbdir=" #$wordnet))))))
- (databases (list (dicod-database
- (name "wordnet")
- (complex? #t)
- (handler "wordnet")
- (options '("database=wn")))
- %dicod-database:gcide))))
- @end lisp
- @cindex Docker
- @subsubheading Docker Service
- The @code{(gnu services docker)} module provides the following services.
- @defvr {Scheme Variable} docker-service-type
- This is the type of the service that runs @url{https://www.docker.com,Docker},
- a daemon that can execute application bundles (sometimes referred to as
- ``containers'') in isolated environments.
- @end defvr
- @deftp {Data Type} docker-configuration
- This is the data type representing the configuration of Docker and Containerd.
- @table @asis
- @item @code{docker} (default: @code{docker})
- The Docker daemon package to use.
- @item @code{docker-cli} (default: @code{docker-cli})
- The Docker client package to use.
- @item @code{containerd} (default: @var{containerd})
- The Containerd package to use.
- @item @code{proxy} (default @var{docker-libnetwork-cmd-proxy})
- The Docker user-land networking proxy package to use.
- @item @code{enable-proxy?} (default @code{#t})
- Enable or disable the use of the Docker user-land networking proxy.
- @item @code{debug?} (default @code{#f})
- Enable or disable debug output.
- @item @code{enable-iptables?} (default @code{#t})
- Enable or disable the addition of iptables rules.
- @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 @code{<setuid-program>} denoting the
- names of programs to have a setuid or setgid bit set (@pxref{Using the
- Configuration System}). For instance, the @command{passwd} program,
- which is part of the Shadow package, with a setuid root can be
- designated like this:
- @example
- (setuid-program
- (program (file-append #$shadow "/bin/passwd")))
- @end example
- @deftp {Data Type} setuid-program
- This data type represents a program with a setuid or setgid bit set.
- @table @asis
- @item @code{program}
- A file-like object having its setuid and/or setgid bit set.
- @item @code{setuid?} (default: @code{#t})
- Whether to set user setuid bit.
- @item @code{setgid?} (default: @code{#f})
- Whether to set group setgid bit.
- @item @code{user} (default: @code{0})
- UID (integer) or user name (string) for the user owner of the program,
- defaults to root.
- @item @code{group} (default: @code{0})
- GID (integer) goup name (string) for the group owner of the program,
- defaults to root.
- @end table
- @end deftp
- A default set of setuid programs is defined by the
- @code{%setuid-programs} variable of the @code{(gnu system)} module.
- @defvr {Scheme Variable} %setuid-programs
- A list of @code{<setuid-program>} denoting common programs that are
- setuid-root.
- The list includes commands such as @command{passwd}, @command{ping},
- @command{su}, and @command{sudo}.
- @end defvr
- Under the hood, the actual setuid programs are created in the
- @file{/run/setuid-programs} directory at system activation time. The
- files in this directory refer to the ``real'' binaries, which are in the
- store.
- @node X.509 Certificates
- @section X.509 Certificates
- @cindex HTTPS, certificates
- @cindex X.509 certificates
- @cindex TLS
- Web servers available over HTTPS (that is, HTTP over the transport-layer
- security mechanism, TLS) send client programs an @dfn{X.509 certificate}
- that the client can then use to @emph{authenticate} the server. To do
- that, clients verify that the server's certificate is signed by a
- so-called @dfn{certificate authority} (CA). But to verify the CA's
- signature, clients must have first acquired the CA's certificate.
- Web browsers such as GNU@tie{}IceCat include their own set of CA
- certificates, such that they are able to verify CA signatures
- out-of-the-box.
- However, most other programs that can talk HTTPS---@command{wget},
- @command{git}, @command{w3m}, etc.---need to be told where CA
- certificates can be found.
- @cindex @code{nss-certs}
- In Guix, this is done by adding a package that provides certificates
- to the @code{packages} field of the @code{operating-system} declaration
- (@pxref{operating-system Reference}). Guix includes one such package,
- @code{nss-certs}, which is a set of CA certificates provided as part of
- Mozilla's Network Security Services.
- Note that it is @emph{not} part of @code{%base-packages}, so you need to
- explicitly add it. The @file{/etc/ssl/certs} directory, which is where
- most applications and libraries look for certificates by default, points
- to the certificates installed globally.
- Unprivileged users, including users of Guix on a foreign distro,
- can also install their own certificate package in
- their profile. A number of environment variables need to be defined so
- that applications and libraries know where to find them. Namely, the
- OpenSSL library honors the @env{SSL_CERT_DIR} and @env{SSL_CERT_FILE}
- variables. Some applications add their own environment variables; for
- instance, the Git version control system honors the certificate bundle
- pointed to by the @env{GIT_SSL_CAINFO} environment variable. Thus, you
- would typically run something like:
- @example
- guix install nss-certs
- export SSL_CERT_DIR="$HOME/.guix-profile/etc/ssl/certs"
- export SSL_CERT_FILE="$HOME/.guix-profile/etc/ssl/certs/ca-certificates.crt"
- export GIT_SSL_CAINFO="$SSL_CERT_FILE"
- @end example
- As another example, R requires the @env{CURL_CA_BUNDLE} environment
- variable to point to a certificate bundle, so you would have to run
- something like this:
- @example
- guix install nss-certs
- export CURL_CA_BUNDLE="$HOME/.guix-profile/etc/ssl/certs/ca-certificates.crt"
- @end example
- For other applications you may want to look up the required environment
- variable in the relevant documentation.
- @node Name Service Switch
- @section Name Service Switch
- @cindex name service switch
- @cindex NSS
- The @code{(gnu system nss)} module provides bindings to the
- configuration file of the libc @dfn{name service switch} or @dfn{NSS}
- (@pxref{NSS Configuration File,,, libc, The GNU C Library Reference
- Manual}). In a nutshell, the NSS is a mechanism that allows libc to be
- extended with new ``name'' lookup methods for system databases, which
- includes host names, service names, user accounts, and more (@pxref{Name
- Service Switch, System Databases and Name Service Switch,, libc, The GNU
- C Library Reference Manual}).
- The NSS configuration specifies, for each system database, which lookup
- method is to be used, and how the various methods are chained
- together---for instance, under which circumstances NSS should try the
- next method in the list. The NSS configuration is given in the
- @code{name-service-switch} field of @code{operating-system} declarations
- (@pxref{operating-system Reference, @code{name-service-switch}}).
- @cindex nss-mdns
- @cindex .local, host name lookup
- As an example, the declaration below configures the NSS to use the
- @uref{https://0pointer.de/lennart/projects/nss-mdns/, @code{nss-mdns}
- back-end}, which supports host name lookups over multicast DNS (mDNS)
- for host names ending in @code{.local}:
- @lisp
- (name-service-switch
- (hosts (list %files ;first, check /etc/hosts
- ;; If the above did not succeed, try
- ;; with 'mdns_minimal'.
- (name-service
- (name "mdns_minimal")
- ;; 'mdns_minimal' is authoritative for
- ;; '.local'. When it returns "not found",
- ;; no need to try the next methods.
- (reaction (lookup-specification
- (not-found => return))))
- ;; Then fall back to DNS.
- (name-service
- (name "dns"))
- ;; Finally, try with the "full" 'mdns'.
- (name-service
- (name "mdns")))))
- @end lisp
- Do not worry: the @code{%mdns-host-lookup-nss} variable (see below)
- contains this configuration, so you will not have to type it if all you
- want is to have @code{.local} host lookup working.
- Note that, in this case, in addition to setting the
- @code{name-service-switch} of the @code{operating-system} declaration,
- you also need to use @code{avahi-service-type} (@pxref{Networking Services,
- @code{avahi-service-type}}), or @code{%desktop-services}, which includes it
- (@pxref{Desktop Services}). Doing this makes @code{nss-mdns} accessible
- to the name service cache daemon (@pxref{Base Services,
- @code{nscd-service}}).
- For convenience, the following variables provide typical NSS
- configurations.
- @defvr {Scheme Variable} %default-nss
- This is the default name service switch configuration, a
- @code{name-service-switch} object.
- @end defvr
- @defvr {Scheme Variable} %mdns-host-lookup-nss
- This is the name service switch configuration with support for host name
- lookup over multicast DNS (mDNS) for host names ending in @code{.local}.
- @end defvr
- The reference for name service switch configuration is given below. It
- is a direct mapping of the configuration file format of the C library , so
- please refer to the C library manual for more information (@pxref{NSS
- Configuration File,,, libc, The GNU C Library Reference Manual}).
- Compared to the configuration file format of libc NSS, it has the advantage
- not only of adding this warm parenthetic feel that we like, but also
- static checks: you will know about syntax errors and typos as soon as you
- run @command{guix system}.
- @deftp {Data Type} name-service-switch
- This is the data type representation the configuration of libc's name
- service switch (NSS). Each field below represents one of the supported
- system databases.
- @table @code
- @item aliases
- @itemx ethers
- @itemx group
- @itemx gshadow
- @itemx hosts
- @itemx initgroups
- @itemx netgroup
- @itemx networks
- @itemx password
- @itemx public-key
- @itemx rpc
- @itemx services
- @itemx shadow
- The system databases handled by the NSS@. Each of these fields must be a
- list of @code{<name-service>} objects (see below).
- @end table
- @end deftp
- @deftp {Data Type} name-service
- This is the data type representing an actual name service and the
- associated lookup action.
- @table @code
- @item name
- A string denoting the name service (@pxref{Services in the NSS
- configuration,,, libc, The GNU C Library Reference Manual}).
- Note that name services listed here must be visible to nscd. This is
- achieved by passing the @code{#:name-services} argument to
- @code{nscd-service} the list of packages providing the needed name
- services (@pxref{Base Services, @code{nscd-service}}).
- @item reaction
- An action specified using the @code{lookup-specification} macro
- (@pxref{Actions in the NSS configuration,,, libc, The GNU C Library
- Reference Manual}). For example:
- @lisp
- (lookup-specification (unavailable => continue)
- (success => return))
- @end lisp
- @end table
- @end deftp
- @node Initial RAM Disk
- @section Initial RAM Disk
- @cindex initrd
- @cindex initial RAM disk
- For bootstrapping purposes, the Linux-Libre kernel is passed an
- @dfn{initial RAM disk}, or @dfn{initrd}. An initrd contains a temporary
- root file system as well as an initialization script. The latter is
- responsible for mounting the real root file system, and for loading any
- kernel modules that may be needed to achieve that.
- The @code{initrd-modules} field of an @code{operating-system}
- declaration allows you to specify Linux-libre kernel modules that must
- be available in the initrd. In particular, this is where you would list
- modules needed to actually drive the hard disk where your root partition
- is---although the default value of @code{initrd-modules} should cover
- most use cases. For example, assuming you need the @code{megaraid_sas}
- module in addition to the default modules to be able to access your root
- file system, you would write:
- @lisp
- (operating-system
- ;; @dots{}
- (initrd-modules (cons "megaraid_sas" %base-initrd-modules)))
- @end lisp
- @defvr {Scheme Variable} %base-initrd-modules
- This is the list of kernel modules included in the initrd by default.
- @end defvr
- Furthermore, if you need lower-level customization, the @code{initrd}
- field of an @code{operating-system} declaration allows
- you to specify which initrd you would like to use. The @code{(gnu
- system linux-initrd)} module provides three ways to build an initrd: the
- high-level @code{base-initrd} procedure and the low-level
- @code{raw-initrd} and @code{expression->initrd} procedures.
- The @code{base-initrd} procedure is intended to cover most common uses.
- For example, if you want to add a bunch of kernel modules to be loaded
- at boot time, you can define the @code{initrd} field of the operating
- system declaration like this:
- @lisp
- (initrd (lambda (file-systems . rest)
- ;; Create a standard initrd but set up networking
- ;; with the parameters QEMU expects by default.
- (apply base-initrd file-systems
- #:qemu-networking? #t
- rest)))
- @end lisp
- The @code{base-initrd} procedure also handles common use cases that
- involves using the system as a QEMU guest, or as a ``live'' system with
- volatile root file system.
- The @code{base-initrd} procedure is built from @code{raw-initrd} procedure.
- Unlike @code{base-initrd}, @code{raw-initrd} doesn't do anything high-level,
- such as trying to guess which kernel modules and packages should be included
- to the initrd. An example use of @code{raw-initrd} is when a user has
- a custom Linux kernel configuration and default kernel modules included by
- @code{base-initrd} are not available.
- The initial RAM disk produced by @code{base-initrd} or @code{raw-initrd}
- honors several options passed on the Linux kernel command line
- (that is, arguments passed @i{via} the @code{linux} command of GRUB, or the
- @code{-append} option of QEMU), notably:
- @table @code
- @item --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-static-stripped] [#:name "guile-initrd"]
- Return as a file-like object a Linux initrd (a gzipped cpio archive)
- containing @var{guile} and that evaluates @var{exp}, a G-expression,
- upon booting. All the derivations referenced by @var{exp} are
- automatically copied to the initrd.
- @end deffn
- @node Bootloader Configuration
- @section Bootloader Configuration
- @cindex bootloader
- @cindex boot loader
- The operating system supports multiple bootloaders. The bootloader is
- configured using @code{bootloader-configuration} declaration. All the
- fields of this structure are bootloader agnostic except for one field,
- @code{bootloader} that indicates the bootloader to be configured and
- installed.
- Some of the bootloaders do not honor every field of
- @code{bootloader-configuration}. For instance, the extlinux
- bootloader does not support themes and thus ignores the @code{theme}
- field.
- @deftp {Data Type} bootloader-configuration
- The type of a bootloader configuration declaration.
- @table @asis
- @item @code{bootloader}
- @cindex EFI, bootloader
- @cindex UEFI, bootloader
- @cindex BIOS, bootloader
- The bootloader to use, as a @code{bootloader} object. For now
- @code{grub-bootloader}, @code{grub-efi-bootloader},
- @code{grub-efi-netboot-bootloader}, @code{extlinux-bootloader} and
- @code{u-boot-bootloader} are supported.
- @cindex ARM, bootloaders
- @cindex AArch64, bootloaders
- Available bootloaders are described in @code{(gnu bootloader @dots{})}
- modules. In particular, @code{(gnu bootloader u-boot)} contains definitions
- of bootloaders for a wide range of ARM and AArch64 systems, using the
- @uref{https://www.denx.de/wiki/U-Boot/, U-Boot bootloader}.
- @vindex grub-efi-bootloader
- @code{grub-efi-bootloader} allows to boot on modern systems using the
- @dfn{Unified Extensible Firmware Interface} (UEFI). This is what you should
- use if the installation image contains a @file{/sys/firmware/efi} directory
- when you boot it on your system.
- @vindex grub-bootloader
- @code{grub-bootloader} allows you to boot in particular Intel-based machines
- in ``legacy'' BIOS mode.
- @vindex grub-efi-netboot-bootloader
- @code{grub-efi-netboot-bootloader} allows you to boot your system over network
- through TFTP@. In combination with an NFS root file system this allows you to
- build a diskless Guix system.
- The installation of the @code{grub-efi-netboot-bootloader} generates the
- content of the TFTP root directory at @code{targets} (@pxref{Bootloader
- Configuration, @code{targets}}), to be served by a TFTP server. You may
- want to mount your TFTP server directories onto the @code{targets} to
- move the required files to the TFTP server automatically.
- If you plan to use an NFS root file system as well (actually if you mount the
- store from an NFS share), then the TFTP server needs to serve the file
- @file{/boot/grub/grub.cfg} and other files from the store (like GRUBs background
- image, the kernel (@pxref{operating-system Reference, @code{kernel}}) and the
- initrd (@pxref{operating-system Reference, @code{initrd}})), too. All these
- files from the store will be accessed by GRUB through TFTP with their normal
- store path, for example as
- @file{tftp://tftp-server/gnu/store/…-initrd/initrd.cpio.gz}.
- Two symlinks are created to make this possible. For each target in the
- @code{targets} field, the first symlink is
- @samp{target}@file{/efi/Guix/boot/grub/grub.cfg} pointing to
- @file{../../../boot/grub/grub.cfg}, where @samp{target} may be
- @file{/boot}. In this case the link is not leaving the served TFTP root
- directory, but otherwise it does. The second link is
- @samp{target}@file{/gnu/store} and points to @file{../gnu/store}. This
- link is leaving the served TFTP root directory.
- The assumption behind all this is that you have an NFS server exporting
- the root file system for your Guix system, and additionally a TFTP
- server exporting your @code{targets} directories—usually a single
- @file{/boot}—from that same root file system for your Guix system. In
- this constellation the symlinks will work.
- For other constellations you will have to program your own bootloader
- installer, which then takes care to make necessary files from the store
- accessible through TFTP, for example by copying them into the TFTP root
- directory to your @code{targets}.
- It is important to note that symlinks pointing outside the TFTP root directory
- may need to be allowed in the configuration of your TFTP server. Further the
- store link exposes the whole store through TFTP@. Both points need to be
- considered carefully for security aspects.
- Beside the @code{grub-efi-netboot-bootloader}, the already mentioned TFTP and
- NFS servers, you also need a properly configured DHCP server to make the booting
- over netboot possible. For all this we can currently only recommend you to look
- for instructions about @acronym{PXE, Preboot eXecution Environment}.
- @item @code{targets}
- This is a list of strings denoting the targets onto which to install the
- bootloader.
- The interpretation of targets depends on the bootloader in question.
- For @code{grub-bootloader}, for example, they should be device names
- understood by the bootloader @command{installer} command, such as
- @code{/dev/sda} or @code{(hd0)} (@pxref{Invoking grub-install,,, grub,
- GNU GRUB Manual}). For @code{grub-efi-bootloader}, they should be mount
- points of the EFI file system, usually @file{/boot/efi}. For
- @code{grub-efi-netboot-bootloader}, @code{targets} should be the mount
- points corresponding to TFTP root directories served by your TFTP
- server.
- @item @code{menu-entries} (default: @code{()})
- A possibly empty list of @code{menu-entry} objects (see below), denoting
- entries to appear in the bootloader menu, in addition to the current
- system entry and the entry pointing to previous system generations.
- @item @code{default-entry} (default: @code{0})
- The index of the default boot menu entry. Index 0 is for the entry of the
- current system.
- @item @code{timeout} (default: @code{5})
- The number of seconds to wait for keyboard input before booting. Set to
- 0 to boot immediately, and to -1 to wait indefinitely.
- @cindex keyboard layout, for the bootloader
- @item @code{keyboard-layout} (default: @code{#f})
- If this is @code{#f}, the bootloader's menu (if any) uses the default keyboard
- layout, usually US@tie{}English (``qwerty'').
- Otherwise, this must be a @code{keyboard-layout} object (@pxref{Keyboard
- Layout}).
- @quotation Note
- This option is currently ignored by bootloaders other than @code{grub} and
- @code{grub-efi}.
- @end quotation
- @item @code{theme} (default: @var{#f})
- The bootloader theme object describing the theme to use. If no theme
- is provided, some bootloaders might use a default theme, that's true
- for GRUB.
- @item @code{terminal-outputs} (default: @code{'(gfxterm)})
- The output terminals used for the bootloader boot menu, as a list of
- symbols. GRUB accepts the values: @code{console}, @code{serial},
- @code{serial_@{0-3@}}, @code{gfxterm}, @code{vga_text},
- @code{mda_text}, @code{morse}, and @code{pkmodem}. This field
- corresponds to the GRUB variable @code{GRUB_TERMINAL_OUTPUT} (@pxref{Simple
- configuration,,, grub,GNU GRUB manual}).
- @item @code{terminal-inputs} (default: @code{'()})
- The input terminals used for the bootloader boot menu, as a list of
- symbols. For GRUB, the default is the native platform terminal as
- determined at run-time. GRUB accepts the values: @code{console},
- @code{serial}, @code{serial_@{0-3@}}, @code{at_keyboard}, and
- @code{usb_keyboard}. This field corresponds to the GRUB variable
- @code{GRUB_TERMINAL_INPUT} (@pxref{Simple configuration,,, grub,GNU GRUB
- manual}).
- @item @code{serial-unit} (default: @code{#f})
- The serial unit used by the bootloader, as an integer from 0 to 3.
- For GRUB, it is chosen at run-time; currently GRUB chooses 0, which
- corresponds to COM1 (@pxref{Serial terminal,,, grub,GNU GRUB manual}).
- @item @code{serial-speed} (default: @code{#f})
- The speed of the serial interface, as an integer. For GRUB, the
- default value is chosen at run-time; currently GRUB chooses
- 9600@tie{}bps (@pxref{Serial terminal,,, grub,GNU GRUB manual}).
- @end table
- @end deftp
- @cindex dual boot
- @cindex boot menu
- Should you want to list additional boot menu entries @i{via} the
- @code{menu-entries} field above, you will need to create them with the
- @code{menu-entry} form. For example, imagine you want to be able to
- boot another distro (hard to imagine!), you can define a menu entry
- along these lines:
- @lisp
- (menu-entry
- (label "The Other Distro")
- (linux "/boot/old/vmlinux-2.6.32")
- (linux-arguments '("root=/dev/sda2"))
- (initrd "/boot/old/initrd"))
- @end lisp
- Details below.
- @deftp {Data Type} menu-entry
- The type of an entry in the bootloader menu.
- @table @asis
- @item @code{label}
- The label to show in the menu---e.g., @code{"GNU"}.
- @item @code{linux} (default: @code{#f})
- The Linux kernel image to boot, for example:
- @lisp
- (file-append linux-libre "/bzImage")
- @end lisp
- For GRUB, it is also possible to specify a device explicitly in the
- file path using GRUB's device naming convention (@pxref{Naming
- convention,,, grub, GNU GRUB manual}), for example:
- @example
- "(hd0,msdos1)/boot/vmlinuz"
- @end example
- If the device is specified explicitly as above, then the @code{device}
- field is ignored entirely.
- @item @code{linux-arguments} (default: @code{()})
- The list of extra Linux kernel command-line arguments---e.g.,
- @code{("console=ttyS0")}.
- @item @code{initrd} (default: @code{#f})
- A G-Expression or string denoting the file name of the initial RAM disk
- to use (@pxref{G-Expressions}).
- @item @code{device} (default: @code{#f})
- The device where the kernel and initrd are to be found---i.e., for GRUB,
- @dfn{root} for this menu entry (@pxref{root,,, grub, GNU GRUB manual}).
- This may be a file system label (a string), a file system UUID (a
- bytevector, @pxref{File Systems}), or @code{#f}, in which case
- the bootloader will search the device containing the file specified by
- the @code{linux} field (@pxref{search,,, grub, GNU GRUB manual}). It
- must @emph{not} be an OS device name such as @file{/dev/sda1}.
- @item @code{multiboot-kernel} (default: @code{#f})
- The kernel to boot in Multiboot-mode (@pxref{multiboot,,, grub, GNU GRUB
- manual}). When this field is set, a Multiboot menu-entry is generated.
- For example:
- @lisp
- (file-append mach "/boot/gnumach")
- @end lisp
- @item @code{multiboot-arguments} (default: @code{()})
- The list of extra command-line arguments for the multiboot-kernel.
- @item @code{multiboot-modules} (default: @code{()})
- The list of commands for loading Multiboot modules. For example:
- @lisp
- (list (list (file-append hurd "/hurd/ext2fs.static") "ext2fs"
- @dots{})
- (list (file-append libc "/lib/ld.so.1") "exec"
- @dots{}))
- @end lisp
- @end table
- @end deftp
- @cindex HDPI
- @cindex HiDPI
- @cindex resolution
- @c FIXME: Write documentation once it's stable.
- For now only GRUB has theme support. GRUB themes are created using
- the @code{grub-theme} form, which is not fully documented yet.
- @deftp {Data Type} grub-theme
- Data type representing the configuration of the GRUB theme.
- @table @asis
- @item @code{gfxmode} (default: @code{'("auto")})
- The GRUB @code{gfxmode} to set (a list of screen resolution strings,
- @pxref{gfxmode,,, grub, GNU GRUB manual}).
- @end table
- @end deftp
- @deffn {Scheme Procedure} grub-theme
- Return the default GRUB theme used by the operating system if no
- @code{theme} field is specified in @code{bootloader-configuration}
- record.
- It comes with a fancy background image displaying the GNU and Guix
- logos.
- @end deffn
- For example, to override the default resolution, you may use something
- like
- @lisp
- (bootloader
- (bootloader-configuration
- ;; @dots{}
- (theme (grub-theme
- (inherit (grub-theme))
- (gfxmode '("1024x786x32" "auto"))))))
- @end lisp
- @node Invoking guix system
- @section Invoking @code{guix system}
- Once you have written an operating system declaration as seen in the
- previous section, it can be @dfn{instantiated} using the @command{guix
- system} command. The synopsis is:
- @example
- guix system @var{options}@dots{} @var{action} @var{file}
- @end example
- @var{file} must be the name of a file containing an
- @code{operating-system} declaration. @var{action} specifies how the
- operating system is instantiated. Currently the following values are
- supported:
- @table @code
- @item search
- Display available service type definitions that match the given regular
- expressions, sorted by relevance:
- @cindex HDPI
- @cindex HiDPI
- @cindex resolution
- @example
- $ guix system search console
- name: console-fonts
- location: gnu/services/base.scm:806:2
- extends: shepherd-root
- description: Install the given fonts on the specified ttys (fonts are per
- + virtual console on GNU/Linux). The value of this service is a list of
- + tty/font pairs. The font can be the name of a font provided by the `kbd'
- + package or any valid argument to `setfont', as in this example:
- +
- + '(("tty1" . "LatGrkCyr-8x16")
- + ("tty2" . (file-append
- + font-tamzen
- + "/share/kbd/consolefonts/TamzenForPowerline10x20.psf"))
- + ("tty3" . (file-append
- + font-terminus
- + "/share/consolefonts/ter-132n"))) ; for HDPI
- relevance: 9
- name: mingetty
- location: gnu/services/base.scm:1190:2
- extends: shepherd-root
- description: Provide console login using the `mingetty' program.
- relevance: 2
- name: login
- location: gnu/services/base.scm:860:2
- extends: pam
- description: Provide a console log-in service as specified by its
- + configuration value, a `login-configuration' object.
- relevance: 2
- @dots{}
- @end example
- As for @command{guix package --search}, the result is written in
- @code{recutils} format, which makes it easy to filter the output
- (@pxref{Top, GNU recutils databases,, recutils, GNU recutils manual}).
- @item reconfigure
- Build the operating system described in @var{file}, activate it, and
- switch to it@footnote{This action (and the related actions
- @code{switch-generation} and @code{roll-back}) are usable only on
- systems already running Guix System.}.
- @quotation Note
- @c The paragraph below refers to the problem discussed at
- @c <https://lists.gnu.org/archive/html/guix-devel/2014-08/msg00057.html>.
- It is highly recommended to run @command{guix pull} once before you run
- @command{guix system reconfigure} for the first time (@pxref{Invoking
- guix pull}). Failing to do that you would see an older version of Guix
- once @command{reconfigure} has completed.
- @end quotation
- This effects all the configuration specified in @var{file}: user
- accounts, system services, global package list, setuid programs, etc.
- The command starts system services specified in @var{file} that are not
- currently running; if a service is currently running this command will
- arrange for it to be upgraded the next time it is stopped (e.g.@: by
- @code{herd stop X} or @code{herd restart X}).
- This command creates a new generation whose number is one greater than
- the current generation (as reported by @command{guix system
- list-generations}). If that generation already exists, it will be
- overwritten. This behavior mirrors that of @command{guix package}
- (@pxref{Invoking guix package}).
- It also adds a bootloader menu entry for the new OS configuration,
- ---unless @option{--no-bootloader} is passed. For GRUB, it moves
- entries for older configurations to a submenu, allowing you to choose
- an older system generation at boot time should you need it.
- @cindex provenance tracking, of the operating system
- Upon completion, the new system is deployed under
- @file{/run/current-system}. This directory contains @dfn{provenance
- meta-data}: the list of channels in use (@pxref{Channels}) and
- @var{file} itself, when available. You can view it by running:
- @example
- guix system describe
- @end example
- This information is useful should you later want to inspect how this
- particular generation was built. In fact, assuming @var{file} is
- self-contained, you can later rebuild generation @var{n} of your
- operating system with:
- @example
- guix time-machine \
- -C /var/guix/profiles/system-@var{n}-link/channels.scm -- \
- system reconfigure \
- /var/guix/profiles/system-@var{n}-link/configuration.scm
- @end example
- You can think of it as some sort of built-in version control! Your
- system is not just a binary artifact: @emph{it carries its own source}.
- @xref{Service Reference, @code{provenance-service-type}}, for more
- information on provenance tracking.
- By default, @command{reconfigure} @emph{prevents you from downgrading
- your system}, which could (re)introduce security vulnerabilities and
- also cause problems with ``stateful'' services such as database
- management systems. You can override that behavior by passing
- @option{--allow-downgrades}.
- @item switch-generation
- @cindex generations
- Switch to an existing system generation. This action atomically
- switches the system profile to the specified system generation. It
- also rearranges the system's existing bootloader menu entries. It
- makes the menu entry for the specified system generation the default,
- and it moves the entries for the other generations to a submenu, if
- supported by the bootloader being used. The next time the system
- boots, it will use the specified system generation.
- The bootloader itself is not being reinstalled when using this
- command. Thus, the installed bootloader is used with an updated
- configuration file.
- The target generation can be specified explicitly by its generation
- number. For example, the following invocation would switch to system
- generation 7:
- @example
- guix system switch-generation 7
- @end example
- The target generation can also be specified relative to the current
- generation with the form @code{+N} or @code{-N}, where @code{+3} means
- ``3 generations ahead of the current generation,'' and @code{-1} means
- ``1 generation prior to the current generation.'' When specifying a
- negative value such as @code{-1}, you must precede it with @code{--} to
- prevent it from being parsed as an option. For example:
- @example
- guix system switch-generation -- -1
- @end example
- Currently, the effect of invoking this action is @emph{only} to switch
- the system profile to an existing generation and rearrange the
- bootloader menu entries. To actually start using the target system
- generation, you must reboot after running this action. In the future,
- it will be updated to do the same things as @command{reconfigure},
- like activating and deactivating services.
- This action will fail if the specified generation does not exist.
- @item roll-back
- @cindex rolling back
- Switch to the preceding system generation. The next time the system
- boots, it will use the preceding system generation. This is the inverse
- of @command{reconfigure}, and it is exactly the same as invoking
- @command{switch-generation} with an argument of @code{-1}.
- Currently, as with @command{switch-generation}, you must reboot after
- running this action to actually start using the preceding system
- generation.
- @item delete-generations
- @cindex deleting system generations
- @cindex saving space
- Delete system generations, making them candidates for garbage collection
- (@pxref{Invoking guix gc}, for information on how to run the ``garbage
- collector'').
- This works in the same way as @samp{guix package --delete-generations}
- (@pxref{Invoking guix package, @option{--delete-generations}}). With no
- arguments, all system generations but the current one are deleted:
- @example
- guix system delete-generations
- @end example
- You can also select the generations you want to delete. The example below
- deletes all the system generations that are more than two 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 targets specified in
- @file{my-os-config}, unless the @option{--no-bootloader} option was
- passed.
- @item vm
- @cindex virtual machine
- @cindex VM
- @anchor{guix system vm}
- Build a virtual machine 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 -nic 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)
- (targets '("/dev/vda"))
- (terminal-outputs '(console))))
- (file-systems (cons (file-system
- (mount-point "/")
- (device "/dev/vda1")
- (type "ext4"))
- %base-file-systems))
- (services
- (append (list (service dhcp-client-service-type)
- (service openssh-service-type
- (openssh-configuration
- (permit-root-login #t)
- (allow-empty-passwords? #t))))
- %base-services))))
- (list (machine
- (operating-system %system)
- (environment managed-host-environment-type)
- (configuration (machine-ssh-configuration
- (host-name "localhost")
- (system "x86_64-linux")
- (user "alice")
- (identity "./id_rsa")
- (port 2222)))))
- @end lisp
- The file should evaluate to a list of @var{machine} objects. This example,
- upon being deployed, will create a new generation on the remote system
- realizing the @code{operating-system} declaration @code{%system}.
- @code{environment} and @code{configuration} specify how the machine should be
- provisioned---that is, how the computing resources should be created and
- managed. The above example does not create any resources, as a
- @code{'managed-host} is a machine that is already running the Guix system and
- available over the network. This is a particularly simple case; a more
- complex deployment may involve, for example, starting virtual machines through
- a Virtual Private Server (VPS) provider. In such a case, a different
- @var{environment} type would be used.
- Do note that you first need to generate a key pair on the coordinator machine
- to allow the daemon to export signed archives of files from the store
- (@pxref{Invoking guix archive}), though this step is automatic on Guix
- System:
- @example
- # guix archive --generate-key
- @end example
- @noindent
- Each target machine must authorize the key of the master machine so that it
- accepts store items it receives from the coordinator:
- @example
- # guix archive --authorize < coordinator-public-key.txt
- @end example
- @code{user}, in this example, specifies the name of the user account to log in
- as to perform the deployment. Its default value is @code{root}, but root
- login over SSH may be forbidden in some cases. To work around this,
- @command{guix deploy} can log in as an unprivileged user and employ
- @code{sudo} to escalate privileges. This will only work if @code{sudo} is
- currently installed on the remote and can be invoked non-interactively as
- @code{user}. That is, the line in @code{sudoers} granting @code{user} the
- ability to use @code{sudo} must contain the @code{NOPASSWD} tag. This can
- be accomplished with the following operating system configuration snippet:
- @lisp
- (use-modules ...
- (gnu system)) ;for %sudoers-specification
- (define %user "username")
- (operating-system
- ...
- (sudoers-file
- (plain-file "sudoers"
- (string-append (plain-file-content %sudoers-specification)
- (format #f "~a ALL = NOPASSWD: ALL~%"
- %user)))))
- @end lisp
- For more information regarding the format of the @file{sudoers} file,
- consult @command{man sudoers}.
- @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.qcow2}.
- This image is a compressed image in QCOW format. You can pass it to an
- emulator such as @uref{https://qemu.org/, QEMU} (see below for details).
- This image boots the Xfce graphical environment and it contains some
- commonly used tools. You can install more software in the image by running
- @command{guix package} in a terminal (@pxref{Invoking guix package}). You can
- also reconfigure the system based on its initial configuration file available
- as @file{/run/current-system/configuration.scm} (@pxref{Using the
- Configuration System}).
- Instead of using this pre-built image, one can also build their own
- image using @command{guix system image} (@pxref{Invoking guix system}).
- @cindex QEMU
- If you built your own image, you must copy it out of the store
- (@pxref{The Store}) and give yourself permission to write to the copy
- before you can use it. When invoking QEMU, you must choose a system
- emulator that is suitable for your hardware platform. Here is a minimal
- QEMU invocation that will boot the result of @command{guix system
- image -t qcow2} on x86_64 hardware:
- @example
- $ qemu-system-x86_64 \
- -nic user,model=virtio-net-pci \
- -enable-kvm -m 1024 \
- -device virtio-blk,drive=myhd \
- -drive if=none,file=/tmp/qemu-image,id=myhd
- @end example
- Here is what each of these options means:
- @table @code
- @item qemu-system-x86_64
- This specifies the hardware platform to emulate. This should match the
- host.
- @item -nic user,model=virtio-net-pci
- Enable the unprivileged user-mode network stack. The guest OS can
- access the host but not vice versa. This is the simplest way to get the
- guest OS online. @code{model} specifies which network device to emulate:
- @code{virtio-net-pci} is a special device made for virtualized operating
- systems and recommended for most uses. Assuming your hardware platform is
- x86_64, you can get a list of available NIC models by running
- @command{qemu-system-x86_64 -nic model=help}.
- @item -enable-kvm
- If your system has hardware virtualization extensions, enabling the
- virtual machine support (KVM) of the Linux kernel will make things run
- faster.
- @c To run Xfce + 'guix pull', we need at least 1G of RAM.
- @item -m 1024
- RAM available to the guest OS, in mebibytes. Defaults to 128@tie{}MiB,
- which may be insufficient for some operations.
- @item -device virtio-blk,drive=myhd
- Create a @code{virtio-blk} drive called ``myhd''. @code{virtio-blk} is a
- ``paravirtualization'' mechanism for block devices that allows QEMU to achieve
- better performance than if it were emulating a complete disk drive. See the
- QEMU and KVM documentation for more info.
- @item -drive if=none,file=/tmp/qemu-image,id=myhd
- Use our QCOW image, the @file{/tmp/qemu-image} file, as the backing
- store of the ``myhd'' drive.
- @end table
- The default @command{run-vm.sh} script that is returned by an invocation of
- @command{guix system vm} does not add a @command{-nic user} flag by default.
- To get network access from within the vm add the @code{(dhcp-client-service)}
- to your system definition and start the VM using
- @command{$(guix system vm config.scm) -nic user}. An important caveat of using
- @command{-nic user} for networking is that @command{ping} will not work, because
- it uses the ICMP protocol. You'll have to use a different command to check for
- network connectivity, for example @command{guix download}.
- @subsection Connecting Through SSH
- @cindex SSH
- @cindex SSH server
- To enable SSH inside a VM you need to add an SSH server like
- @code{openssh-service-type} to your VM (@pxref{Networking Services,
- @code{openssh-service-type}}). In addition you need to forward the SSH port,
- 22 by default, to the host. You can do this with
- @example
- $(guix system vm config.scm) -nic user,model=virtio-net-pci,hostfwd=tcp::10022-:22
- @end example
- To connect to the VM you can run
- @example
- ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -p 10022 localhost
- @end example
- The @command{-p} tells @command{ssh} the port you want to connect to.
- @command{-o UserKnownHostsFile=/dev/null} prevents @command{ssh} from complaining
- every time you modify your @command{config.scm} file and the
- @command{-o StrictHostKeyChecking=no} prevents you from having to allow a
- connection to an unknown host every time you connect.
- @quotation Note
- If you find the above @samp{hostfwd} example not to be working (e.g.,
- your SSH client hangs attempting to connect to the mapped port of your
- VM), make sure that your Guix System VM has networking support, such as
- by using the @code{dhcp-client-service-type} service type.
- @end quotation
- @subsection Using @command{virt-viewer} with Spice
- As an alternative to the default @command{qemu} graphical client you can
- use the @command{remote-viewer} from the @command{virt-viewer} package. To
- connect pass the @command{-spice port=5930,disable-ticketing} flag to
- @command{qemu}. See previous section for further information on how to do this.
- Spice also allows you to do some nice stuff like share your clipboard with your
- VM@. To enable that you'll also have to pass the following flags to @command{qemu}:
- @example
- -device virtio-serial-pci,id=virtio-serial0,max_ports=16,bus=pci.0,addr=0x5
- -chardev spicevmc,name=vdagent,id=vdagent
- -device virtserialport,nr=1,bus=virtio-serial0.0,chardev=vdagent,
- name=com.redhat.spice.0
- @end example
- You'll also need to add the @code{(spice-vdagent-service)} to your
- system definition (@pxref{Miscellaneous Services, Spice service}).
- @node Defining Services
- @section Defining Services
- The previous sections show the available services and how one can combine
- them in an @code{operating-system} declaration. But how do we define
- them in the first place? And what is a service anyway?
- @menu
- * Service Composition:: The model for composing services.
- * Service Types and Services:: Types and services.
- * Service Reference:: API reference.
- * Shepherd Services:: A particular type of service.
- @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
- @defvr {Scheme Variable} linux-loadable-module-service-type
- Type of the service that collects lists of packages containing
- kernel-loadable modules, and adds them to the set of kernel-loadable
- modules.
- This service type is intended to be extended by other service types,
- such as below:
- @lisp
- (simple-service 'installing-module
- linux-loadable-module-service-type
- (list module-to-install-1
- module-to-install-2))
- @end lisp
- This does not actually load modules at bootup, only adds it to the
- kernel profile so that it @emph{can} be loaded by other means.
- @end defvr
- @node Shepherd Services
- @subsection Shepherd Services
- @cindex shepherd services
- @cindex PID 1
- @cindex init system
- The @code{(gnu services shepherd)} module provides a way to define
- services managed by the GNU@tie{}Shepherd, which is the
- initialization system---the first process that is started when the
- system boots, also known as PID@tie{}1
- (@pxref{Introduction,,, shepherd, The GNU Shepherd Manual}).
- Services in the Shepherd can depend on each other. For instance, the
- SSH daemon may need to be started after the syslog daemon has been
- started, which in turn can only happen once all the file systems have
- been mounted. The simple operating system defined earlier (@pxref{Using
- the Configuration System}) results in a service graph like this:
- @image{images/shepherd-graph,,5in,Typical shepherd service graph.}
- You can actually generate such a graph for any operating system
- definition using the @command{guix system shepherd-graph} command
- (@pxref{system-shepherd-graph, @command{guix system shepherd-graph}}).
- The @code{%shepherd-root-service} is a service object representing
- PID@tie{}1, of type @code{shepherd-root-service-type}; it can be extended
- by passing it lists of @code{<shepherd-service>} objects.
- @deftp {Data Type} shepherd-service
- The data type representing a service managed by the Shepherd.
- @table @asis
- @item @code{provision}
- This is a list of symbols denoting what the service provides.
- These are the names that may be passed to @command{herd start},
- @command{herd status}, and similar commands (@pxref{Invoking herd,,,
- shepherd, The GNU Shepherd Manual}). @xref{Slots of services, the
- @code{provides} slot,, shepherd, The GNU Shepherd Manual}, for details.
- @item @code{requirement} (default: @code{'()})
- List of symbols denoting the Shepherd services this one depends on.
- @cindex one-shot services, for the Shepherd
- @item @code{one-shot?} (default: @code{#f})
- Whether this service is @dfn{one-shot}. One-shot services stop immediately
- after their @code{start} action has completed. @xref{Slots of services,,,
- shepherd, The GNU Shepherd Manual}, for more info.
- @item @code{respawn?} (default: @code{#t})
- Whether to restart the service when it stops, for instance when the
- underlying process dies.
- @item @code{start}
- @itemx @code{stop} (default: @code{#~(const #f)})
- The @code{start} and @code{stop} fields refer to the Shepherd's
- facilities to start and stop processes (@pxref{Service De- and
- Constructors,,, shepherd, The GNU Shepherd Manual}). They are given as
- G-expressions that get expanded in the Shepherd configuration file
- (@pxref{G-Expressions}).
- @item @code{actions} (default: @code{'()})
- @cindex actions, of Shepherd services
- This is a list of @code{shepherd-action} objects (see below) defining
- @dfn{actions} supported by the service, in addition to the standard
- @code{start} and @code{stop} actions. Actions listed here become available as
- @command{herd} sub-commands:
- @example
- herd @var{action} @var{service} [@var{arguments}@dots{}]
- @end example
- @item @code{auto-start?} (default: @code{#t})
- Whether this service should be started automatically by the Shepherd. If it
- is @code{#f} the service has to be started manually with @code{herd start}.
- @item @code{documentation}
- A documentation string, as shown when running:
- @example
- herd doc @var{service-name}
- @end example
- where @var{service-name} is one of the symbols in @code{provision}
- (@pxref{Invoking herd,,, shepherd, The GNU Shepherd Manual}).
- @item @code{modules} (default: @code{%default-modules})
- This is the list of modules that must be in scope when @code{start} and
- @code{stop} are evaluated.
- @end table
- @end deftp
- The example below defines a Shepherd service that spawns
- @command{syslogd}, the system logger from the GNU Networking Utilities
- (@pxref{syslogd invocation, @command{syslogd},, inetutils, GNU
- Inetutils}):
- @example
- (let ((config (plain-file "syslogd.conf" "@dots{}")))
- (shepherd-service
- (documentation "Run the syslog daemon (syslogd).")
- (provision '(syslogd))
- (requirement '(user-processes))
- (start #~(make-forkexec-constructor
- (list #$(file-append inetutils "/libexec/syslogd")
- "--rcfile" #$config)
- #:pid-file "/var/run/syslog.pid"))
- (stop #~(make-kill-destructor))))
- @end example
- Key elements in this example are the @code{start} and @code{stop}
- fields: they are @dfn{staged} code snippets that use the
- @code{make-forkexec-constructor} procedure provided by the Shepherd and
- its dual, @code{make-kill-destructor} (@pxref{Service De- and
- Constructors,,, shepherd, The GNU Shepherd Manual}). The @code{start}
- field will have @command{shepherd} spawn @command{syslogd} with the
- given option; note that we pass @code{config} after @option{--rcfile},
- which is a configuration file declared above (contents of this file are
- omitted). Likewise, the @code{stop} field tells how this service is to
- be stopped; in this case, it is stopped by making the @code{kill} system
- call on its PID@. Code staging is achieved using G-expressions:
- @code{#~} stages code, while @code{#$} ``escapes'' back to host code
- (@pxref{G-Expressions}).
- @deftp {Data Type} shepherd-action
- This is the data type that defines additional actions implemented by a
- Shepherd service (see above).
- @table @code
- @item name
- Symbol naming the action.
- @item documentation
- This is a documentation string for the action. It can be viewed by running:
- @example
- herd doc @var{service} action @var{action}
- @end example
- @item procedure
- This should be a gexp that evaluates to a procedure of at least one argument,
- which is the ``running value'' of the service (@pxref{Slots of services,,,
- shepherd, The GNU Shepherd Manual}).
- @end table
- The following example defines an action called @code{say-hello} that kindly
- greets the user:
- @lisp
- (shepherd-action
- (name 'say-hello)
- (documentation "Say hi!")
- (procedure #~(lambda (running . args)
- (format #t "Hello, friend! arguments: ~s\n"
- args)
- #t)))
- @end lisp
- Assuming this action is added to the @code{example} service, then you can do:
- @example
- # herd say-hello example
- Hello, friend! arguments: ()
- # herd say-hello example a b c
- Hello, friend! arguments: ("a" "b" "c")
- @end example
- This, as you can see, is a fairly sophisticated way to say hello.
- @xref{Service Convenience,,, shepherd, The GNU Shepherd Manual}, for more
- info on actions.
- @end deftp
- @defvr {Scheme Variable} shepherd-root-service-type
- The service type for the Shepherd ``root service''---i.e., PID@tie{}1.
- This is the service type that extensions target when they want to create
- shepherd services (@pxref{Service Types and Services}, for an example).
- Each extension must pass a list of @code{<shepherd-service>}. Its
- value must be a @code{shepherd-configuration}, as described below.
- @end defvr
- @deftp {Data Type} shepherd-configuration
- This data type represents the Shepherd's configuration.
- @table @code
- @item shepherd (default: @code{shepherd})
- The Shepherd package to use.
- @item services (default: @code{'()})
- A list of @code{<shepherd-service>} to start.
- You should probably use the service extension
- mechanism instead (@pxref{Shepherd Services}).
- @end table
- @end deftp
- The following example specifies the Shepherd package for the operating
- system:
- @lisp
- (operating-system
- ;; ...
- (services (append (list openssh-service-type))
- ;; ...
- %desktop-services)
- ;; ...
- ;; Use own Shepherd package.
- (essential-services
- (modify-services (operating-system-default-essential-services
- this-operating-system)
- (shepherd-root-service-type config => (shepherd-configuration
- (inherit config)
- (shepherd my-shepherd))))))
- @end lisp
- @defvr {Scheme Variable} %shepherd-root-service
- This service represents PID@tie{}1.
- @end defvr
- @node Documentation
- @chapter Documentation
- @cindex documentation, searching for
- @cindex searching for documentation
- @cindex Info, documentation format
- @cindex man pages
- @cindex manual pages
- In most cases packages installed with Guix come with documentation.
- There are two main documentation formats: ``Info'', a browsable
- hypertext format used for GNU software, and ``manual pages'' (or ``man
- pages''), the linear documentation format traditionally found on Unix.
- Info manuals are accessed with the @command{info} command or with Emacs,
- and man pages are accessed using @command{man}.
- You can look for documentation of software installed on your system by
- keyword. For example, the following command searches for information
- about ``TLS'' in Info manuals:
- @example
- $ info -k TLS
- "(emacs)Network Security" -- STARTTLS
- "(emacs)Network Security" -- TLS
- "(gnutls)Core TLS API" -- gnutls_certificate_set_verify_flags
- "(gnutls)Core TLS API" -- gnutls_certificate_set_verify_function
- @dots{}
- @end example
- @noindent
- The command below searches for the same keyword in man pages:
- @example
- $ man -k TLS
- SSL (7) - OpenSSL SSL/TLS library
- certtool (1) - GnuTLS certificate tool
- @dots {}
- @end example
- These searches are purely local to your computer so you have the
- guarantee that documentation you find corresponds to what you have
- actually installed, you can access it off-line, and your privacy is
- respected.
- Once you have these results, you can view the relevant documentation by
- running, say:
- @example
- $ info "(gnutls)Core TLS API"
- @end example
- @noindent
- or:
- @example
- $ man certtool
- @end example
- Info manuals contain sections and indices as well as hyperlinks like
- those found in Web pages. The @command{info} reader (@pxref{Top, Info
- reader,, info-stnd, Stand-alone GNU Info}) and its Emacs counterpart
- (@pxref{Misc Help,,, emacs, The GNU Emacs Manual}) provide intuitive key
- bindings to navigate manuals. @xref{Getting Started,,, info, Info: An
- Introduction}, for an introduction to Info navigation.
- @node Installing Debugging Files
- @chapter Installing Debugging Files
- @cindex debugging files
- Program binaries, as produced by the GCC compilers for instance, are
- typically written in the ELF format, with a section containing
- @dfn{debugging information}. Debugging information is what allows the
- debugger, GDB, to map binary code to source code; it is required to
- debug a compiled program in good conditions.
- This chapter explains how to use separate debug info when packages
- provide it, and how to rebuild packages with debug info when it's
- missing.
- @menu
- * Separate Debug Info:: Installing 'debug' outputs.
- * Rebuilding Debug Info:: Building missing debug info.
- @end menu
- @node Separate Debug Info
- @section Separate Debug Info
- The problem with debugging information is that is takes up a fair amount
- of disk space. For example, debugging information for the GNU C Library
- weighs in at more than 60 MiB@. Thus, as a user, keeping all the
- debugging info of all the installed programs is usually not an option.
- Yet, space savings should not come at the cost of an impediment to
- debugging---especially in the GNU system, which should make it easier
- for users to exert their computing freedom (@pxref{GNU Distribution}).
- Thankfully, the GNU Binary Utilities (Binutils) and GDB provide a
- mechanism that allows users to get the best of both worlds: debugging
- information can be stripped from the binaries and stored in separate
- files. GDB is then able to load debugging information from those files,
- when they are available (@pxref{Separate Debug Files,,, gdb, Debugging
- with GDB}).
- The GNU distribution takes advantage of this by storing debugging
- information in the @code{lib/debug} sub-directory of a separate package
- output unimaginatively called @code{debug} (@pxref{Packages with
- Multiple Outputs}). Users can choose to install the @code{debug} output
- of a package when they need it. For instance, the following command
- installs the debugging information for the GNU C Library and for GNU
- Guile:
- @example
- guix install glibc:debug guile:debug
- @end example
- GDB must then be told to look for debug files in the user's profile, by
- setting the @code{debug-file-directory} variable (consider setting it
- from the @file{~/.gdbinit} file, @pxref{Startup,,, gdb, Debugging with
- GDB}):
- @example
- (gdb) set debug-file-directory ~/.guix-profile/lib/debug
- @end example
- From there on, GDB will pick up debugging information from the
- @file{.debug} files under @file{~/.guix-profile/lib/debug}.
- Below is an alternative GDB script which is useful when working with
- other profiles. It takes advantage of the optional Guile integration in
- GDB. This snippet is included by default on Guix System in the
- @file{~/.gdbinit} file.
- @example
- guile
- (use-modules (gdb))
- (execute (string-append "set debug-file-directory "
- (or (getenv "GDB_DEBUG_FILE_DIRECTORY")
- "~/.guix-profile/lib/debug")))
- end
- @end example
- In addition, you will most likely want GDB to be able to show the source
- code being debugged. To do that, you will have to unpack the source
- code of the package of interest (obtained with @code{guix build
- --source}, @pxref{Invoking guix build}), and to point GDB to that source
- directory using the @code{directory} command (@pxref{Source Path,
- @code{directory},, gdb, Debugging with GDB}).
- @c XXX: keep me up-to-date
- The @code{debug} output mechanism in Guix is implemented by the
- @code{gnu-build-system} (@pxref{Build Systems}). Currently, it is
- opt-in---debugging information is available only for the packages with
- definitions explicitly declaring a @code{debug} output. To check
- whether a package has a @code{debug} output, use @command{guix package
- --list-available} (@pxref{Invoking guix package}).
- Read on for how to deal with packages lacking a @code{debug} output.
- @node Rebuilding Debug Info
- @section Rebuilding Debug Info
- @cindex debugging info, rebuilding
- As we saw above, some packages, but not all, provide debugging info in a
- @code{debug} output. What can you do when debugging info is missing?
- The @option{--with-debug-info} option provides a solution to that: it
- allows you to rebuild the package(s) for which debugging info is
- missing---and only those---and to graft those onto the application
- you're debugging. Thus, while it's not as fast as installing a
- @code{debug} output, it is relatively inexpensive.
- Let's illustrate that. Suppose you're experiencing a bug in Inkscape
- and would like to see what's going on in GLib, a library that's deep
- down in its dependency graph. As it turns out, GLib does not have a
- @code{debug} output and the backtrace GDB shows is all sadness:
- @example
- (gdb) bt
- #0 0x00007ffff5f92190 in g_getenv ()
- from /gnu/store/@dots{}-glib-2.62.6/lib/libglib-2.0.so.0
- #1 0x00007ffff608a7d6 in gobject_init_ctor ()
- from /gnu/store/@dots{}-glib-2.62.6/lib/libgobject-2.0.so.0
- #2 0x00007ffff7fe275a in call_init (l=<optimized out>, argc=argc@@entry=1, argv=argv@@entry=0x7fffffffcfd8,
- env=env@@entry=0x7fffffffcfe8) at dl-init.c:72
- #3 0x00007ffff7fe2866 in call_init (env=0x7fffffffcfe8, argv=0x7fffffffcfd8, argc=1, l=<optimized out>)
- at dl-init.c:118
- @end example
- To address that, you install Inkscape linked against a variant GLib that
- contains debug info:
- @example
- guix install inkscape --with-debug-info=glib
- @end example
- This time, debugging will be a whole lot nicer:
- @example
- $ gdb --args sh -c 'exec inkscape'
- @dots{}
- (gdb) b g_getenv
- Function "g_getenv" not defined.
- Make breakpoint pending on future shared library load? (y or [n]) y
- Breakpoint 1 (g_getenv) pending.
- (gdb) r
- Starting program: /gnu/store/@dots{}-profile/bin/sh -c exec\ inkscape
- @dots{}
- (gdb) bt
- #0 g_getenv (variable=variable@@entry=0x7ffff60c7a2e "GOBJECT_DEBUG") at ../glib-2.62.6/glib/genviron.c:252
- #1 0x00007ffff608a7d6 in gobject_init () at ../glib-2.62.6/gobject/gtype.c:4380
- #2 gobject_init_ctor () at ../glib-2.62.6/gobject/gtype.c:4493
- #3 0x00007ffff7fe275a in call_init (l=<optimized out>, argc=argc@@entry=3, argv=argv@@entry=0x7fffffffd088,
- env=env@@entry=0x7fffffffd0a8) at dl-init.c:72
- @dots{}
- @end example
- Much better!
- Note that there can be packages for which @option{--with-debug-info}
- will not have the desired effect. @xref{Package Transformation Options,
- @option{--with-debug-info}}, for more information.
- @node Security Updates
- @chapter Security Updates
- @cindex security updates
- @cindex security vulnerabilities
- Occasionally, important security vulnerabilities are discovered in software
- packages and must be patched. Guix developers try hard to keep track of
- known vulnerabilities and to apply fixes as soon as possible in the
- @code{master} branch of Guix (we do not yet provide a ``stable'' branch
- containing only security updates). The @command{guix lint} tool helps
- developers find out about vulnerable versions of software packages in the
- distribution:
- @smallexample
- $ guix lint -c cve
- gnu/packages/base.scm:652:2: glibc@@2.21: probably vulnerable to CVE-2015-1781, CVE-2015-7547
- gnu/packages/gcc.scm:334:2: gcc@@4.9.3: probably vulnerable to CVE-2015-5276
- gnu/packages/image.scm:312:2: openjpeg@@2.1.0: probably vulnerable to CVE-2016-1923, CVE-2016-1924
- @dots{}
- @end smallexample
- @xref{Invoking guix lint}, for more information.
- Guix follows a functional
- package management discipline (@pxref{Introduction}), which implies
- that, when a package is changed, @emph{every package that depends on it}
- must be rebuilt. This can significantly slow down the deployment of
- fixes in core packages such as libc or Bash, since basically the whole
- distribution would need to be rebuilt. Using pre-built binaries helps
- (@pxref{Substitutes}), but deployment may still take more time than
- desired.
- @cindex grafts
- To address this, Guix implements @dfn{grafts}, a mechanism that allows
- for fast deployment of critical updates without the costs associated
- with a whole-distribution rebuild. The idea is to rebuild only the
- package that needs to be patched, and then to ``graft'' it onto packages
- explicitly installed by the user and that were previously referring to
- the original package. The cost of grafting is typically very low, and
- order of magnitudes lower than a full rebuild of the dependency chain.
- @cindex replacements of packages, for grafts
- For instance, suppose a security update needs to be applied to Bash.
- Guix developers will provide a package definition for the ``fixed''
- Bash, say @code{bash-fixed}, in the usual way (@pxref{Defining
- Packages}). Then, the original package definition is augmented with a
- @code{replacement} field pointing to the package containing the bug fix:
- @lisp
- (define bash
- (package
- (name "bash")
- ;; @dots{}
- (replacement bash-fixed)))
- @end lisp
- From there on, any package depending directly or indirectly on Bash---as
- reported by @command{guix gc --requisites} (@pxref{Invoking guix
- gc})---that is installed is automatically ``rewritten'' to refer to
- @code{bash-fixed} instead of @code{bash}. This grafting process takes
- time proportional to the size of the package, usually less than a
- minute for an ``average'' package on a recent machine. Grafting is
- recursive: when an indirect dependency requires grafting, then grafting
- ``propagates'' up to the package that the user is installing.
- Currently, the length of the name and version of the graft and that of
- the package it replaces (@code{bash-fixed} and @code{bash} in the example
- above) must be equal. This restriction mostly comes from the fact that
- grafting works by patching files, including binary files, directly.
- Other restrictions may apply: for instance, when adding a graft to a
- package providing a shared library, the original shared library and its
- replacement must have the same @code{SONAME} and be binary-compatible.
- The @option{--no-grafts} command-line option allows you to forcefully
- avoid grafting (@pxref{Common Build Options, @option{--no-grafts}}).
- Thus, the command:
- @example
- guix build bash --no-grafts
- @end example
- @noindent
- returns the store file name of the original Bash, whereas:
- @example
- guix build bash
- @end example
- @noindent
- returns the store file name of the ``fixed'', replacement Bash. This
- allows you to distinguish between the two variants of Bash.
- To verify which Bash your whole profile refers to, you can run
- (@pxref{Invoking guix gc}):
- @example
- guix gc -R $(readlink -f ~/.guix-profile) | grep bash
- @end example
- @noindent
- @dots{} and compare the store file names that you get with those above.
- Likewise for a complete Guix system generation:
- @example
- guix gc -R $(guix system build my-config.scm) | grep bash
- @end example
- Lastly, to check which Bash running processes are using, you can use the
- @command{lsof} command:
- @example
- lsof | grep /gnu/store/.*bash
- @end example
- @node Bootstrapping
- @chapter Bootstrapping
- @c Adapted from the ELS 2013 paper.
- @cindex bootstrapping
- Bootstrapping in our context refers to how the distribution gets built
- ``from nothing''. Remember that the build environment of a derivation
- contains nothing but its declared inputs (@pxref{Introduction}). So
- there's an obvious chicken-and-egg problem: how does the first package
- get built? How does the first compiler get compiled?
- It is tempting to think of this question as one that only die-hard
- hackers may care about. However, while the answer to that question is
- technical in nature, its implications are wide-ranging. How the
- distribution is bootstrapped defines the extent to which we, as
- individuals and as a collective of users and hackers, can trust the
- software we run. It is a central concern from the standpoint of
- @emph{security} and from a @emph{user freedom} viewpoint.
- @cindex bootstrap binaries
- The GNU system is primarily made of C code, with libc at its core. The
- GNU build system itself assumes the availability of a Bourne shell and
- command-line tools provided by GNU Coreutils, Awk, Findutils, `sed', and
- `grep'. Furthermore, build programs---programs that run
- @code{./configure}, @code{make}, etc.---are written in Guile Scheme
- (@pxref{Derivations}). Consequently, to be able to build anything at
- all, from scratch, Guix relies on pre-built binaries of Guile, GCC,
- Binutils, libc, and the other packages mentioned above---the
- @dfn{bootstrap binaries}.
- These bootstrap binaries are ``taken for granted'', though we can also
- re-create them if needed (@pxref{Preparing to Use the Bootstrap
- Binaries}).
- @menu
- * Reduced Binary Seed Bootstrap:: A Bootstrap worthy of GNU.
- * Preparing to Use the Bootstrap Binaries:: Building that what matters most.
- @end menu
- @node Reduced Binary Seed Bootstrap
- @section The Reduced Binary Seed Bootstrap
- Guix---like other GNU/Linux distributions---is traditionally bootstrapped from
- a set of bootstrap binaries: Bourne shell, command-line tools provided by GNU
- Coreutils, Awk, Findutils, `sed', and `grep' and Guile, GCC, Binutils, and the
- GNU C Library (@pxref{Bootstrapping}). Usually, these bootstrap binaries are
- ``taken for granted.''
- Taking the bootstrap binaries for granted means that we consider them to
- be a correct and trustworthy ``seed'' for building the complete system.
- Therein lies a problem: the combined size of these bootstrap binaries is
- about 250MB (@pxref{Bootstrappable Builds,,, mes, GNU Mes}). Auditing
- or even inspecting these is next to impossible.
- For @code{i686-linux} and @code{x86_64-linux}, Guix now features a
- ``Reduced Binary Seed'' bootstrap @footnote{We would like to say: ``Full
- Source Bootstrap'' and while we are working towards that goal it would
- be hyperbole to use that term for what we do now.}.
- The Reduced Binary Seed bootstrap removes the most critical tools---from a
- trust perspective---from the bootstrap binaries: GCC, Binutils and the GNU C
- Library are replaced by: @code{bootstrap-mescc-tools} (a tiny assembler and
- linker) and @code{bootstrap-mes} (a small Scheme Interpreter and a C compiler
- written in Scheme and the Mes C Library, built for TinyCC and for GCC).
- Using these new binary seeds the ``missing'' Binutils, GCC, and the GNU
- C Library are built from source. From here on the more traditional
- bootstrap process resumes. This approach has reduced the bootstrap
- binaries in size to about 145MB in Guix v1.1.
- The next step that Guix has taken is to replace the shell and all its
- utilities with implementations in Guile Scheme, the @emph{Scheme-only
- bootstrap}. Gash (@pxref{Gash,,, gash, The Gash manual}) is a
- POSIX-compatible shell that replaces Bash, and it comes with Gash Utils
- which has minimalist replacements for Awk, the GNU Core Utilities, Grep,
- Gzip, Sed, and Tar. The rest of the bootstrap binary seeds that were
- removed are now built from source.
- Building the GNU System from source is currently only possible by adding
- some historical GNU packages as intermediate steps@footnote{Packages
- such as @code{gcc-2.95.3}, @code{binutils-2.14}, @code{glibc-2.2.5},
- @code{gzip-1.2.4}, @code{tar-1.22}, and some others. For details, see
- @file{gnu/packages/commencement.scm}.}. As Gash and Gash Utils mature,
- and GNU packages become more bootstrappable again (e.g., new releases of
- GNU Sed will also ship as gzipped tarballs again, as alternative to the
- hard to bootstrap @code{xz}-compression), this set of added packages can
- hopefully be reduced again.
- The graph below shows the resulting dependency graph for
- @code{gcc-core-mesboot0}, the bootstrap compiler used for the
- traditional bootstrap of the rest of the Guix System.
- @c ./pre-inst-env guix graph -e '(@@ (gnu packages commencement) gcc-core-mesboot0)' | sed -re 's,((bootstrap-mescc-tools|bootstrap-mes|guile-bootstrap).*shape =) box,\1 ellipse,' > doc/images/gcc-core-mesboot0-graph.dot
- @image{images/gcc-core-mesboot0-graph,6in,,Dependency graph of gcc-core-mesboot0}
- The only significant binary bootstrap seeds that remain@footnote{
- Ignoring the 68KB @code{mescc-tools}; that will be removed later,
- together with @code{mes}.} are a Scheme interpreter and a Scheme
- compiler: GNU Mes and GNU Guile@footnote{Not shown in this graph are the
- static binaries for @file{bash}, @code{tar}, and @code{xz} that are used
- to get Guile running.}.
- This further reduction has brought down the size of the binary seed to
- about 60MB for @code{i686-linux} and @code{x86_64-linux}.
- Work is ongoing to remove all binary blobs from our free software
- bootstrap stack, working towards a Full Source Bootstrap. Also ongoing
- is work to bring these bootstraps to the @code{arm-linux} and
- @code{aarch64-linux} architectures and to the Hurd.
- If you are interested, join us on @samp{#bootstrappable} on the Freenode
- IRC network or discuss on @email{bug-mes@@gnu.org} or
- @email{gash-devel@@nongnu.org}.
- @node Preparing to Use the Bootstrap Binaries
- @section Preparing to Use the Bootstrap Binaries
- @c As of Emacs 24.3, Info-mode displays the image, but since it's a
- @c large image, it's hard to scroll. Oh well.
- @image{images/bootstrap-graph,6in,,Dependency graph of the early bootstrap derivations}
- The figure above shows the very beginning of the dependency graph of the
- distribution, corresponding to the package definitions of the @code{(gnu
- packages bootstrap)} module. A similar figure can be generated with
- @command{guix graph} (@pxref{Invoking guix graph}), along the lines of:
- @example
- guix graph -t derivation \
- -e '(@@@@ (gnu packages bootstrap) %bootstrap-gcc)' \
- | dot -Tps > gcc.ps
- @end example
- or, for the further Reduced Binary Seed bootstrap
- @example
- guix graph -t derivation \
- -e '(@@@@ (gnu packages bootstrap) %bootstrap-mes)' \
- | dot -Tps > mes.ps
- @end example
- At this level of detail, things are
- slightly complex. First, Guile itself consists of an ELF executable,
- along with many source and compiled Scheme files that are dynamically
- loaded when it runs. This gets stored in the @file{guile-2.0.7.tar.xz}
- tarball shown in this graph. This tarball is part of Guix's ``source''
- distribution, and gets inserted into the store with @code{add-to-store}
- (@pxref{The Store}).
- But how do we write a derivation that unpacks this tarball and adds it
- to the store? To solve this problem, the @code{guile-bootstrap-2.0.drv}
- derivation---the first one that gets built---uses @code{bash} as its
- builder, which runs @code{build-bootstrap-guile.sh}, which in turn calls
- @code{tar} to unpack the tarball. Thus, @file{bash}, @file{tar},
- @file{xz}, and @file{mkdir} are statically-linked binaries, also part of
- the Guix source distribution, whose sole purpose is to allow the Guile
- tarball to be unpacked.
- Once @code{guile-bootstrap-2.0.drv} is built, we have a functioning
- Guile that can be used to run subsequent build programs. Its first task
- is to download tarballs containing the other pre-built binaries---this
- is what the @file{.tar.xz.drv} derivations do. Guix modules such as
- @code{ftp-client.scm} are used for this purpose. The
- @code{module-import.drv} derivations import those modules in a directory
- in the store, using the original layout. The
- @code{module-import-compiled.drv} derivations compile those modules, and
- write them in an output directory with the right layout. This
- corresponds to the @code{#:modules} argument of
- @code{build-expression->derivation} (@pxref{Derivations}).
- Finally, the various tarballs are unpacked by the derivations
- @code{gcc-bootstrap-0.drv}, @code{glibc-bootstrap-0.drv}, or
- @code{bootstrap-mes-0.drv} and @code{bootstrap-mescc-tools-0.drv}, at which
- point we have a working C tool chain.
- @unnumberedsec Building the Build Tools
- Bootstrapping is complete when we have a full tool chain that does not
- depend on the pre-built bootstrap tools discussed above. This
- no-dependency requirement is verified by checking whether the files of
- the final tool chain contain references to the @file{/gnu/store}
- directories of the bootstrap inputs. The process that leads to this
- ``final'' tool chain is described by the package definitions found in
- the @code{(gnu packages commencement)} module.
- The @command{guix graph} command allows us to ``zoom out'' compared to
- the graph above, by looking at the level of package objects instead of
- individual derivations---remember that a package may translate to
- several derivations, typically one derivation to download its source,
- one to build the Guile modules it needs, and one to actually build the
- package from source. The command:
- @example
- guix graph -t bag \
- -e '(@@@@ (gnu packages commencement)
- glibc-final-with-bootstrap-bash)' | xdot -
- @end example
- @noindent
- displays the dependency graph leading to the ``final'' C
- library@footnote{You may notice the @code{glibc-intermediate} label,
- suggesting that it is not @emph{quite} final, but as a good
- approximation, we will consider it final.}, depicted below.
- @image{images/bootstrap-packages,6in,,Dependency graph of the early packages}
- @c See <https://lists.gnu.org/archive/html/gnu-system-discuss/2012-10/msg00000.html>.
- The first tool that gets built with the bootstrap binaries is
- GNU@tie{}Make---noted @code{make-boot0} above---which is a prerequisite
- for all the following packages. From there Findutils and Diffutils get
- built.
- Then come the first-stage Binutils and GCC, built as pseudo cross
- tools---i.e., with @option{--target} equal to @option{--host}. They are
- used to build libc. Thanks to this cross-build trick, this libc is
- guaranteed not to hold any reference to the initial tool chain.
- From there the final Binutils and GCC (not shown above) are built. GCC
- uses @command{ld} from the final Binutils, and links programs against
- the just-built libc. This tool chain is used to build the other
- packages used by Guix and by the GNU Build System: Guile, Bash,
- Coreutils, etc.
- And voilà! At this point we have the complete set of build tools that
- the GNU Build System expects. These are in the @code{%final-inputs}
- variable of the @code{(gnu packages commencement)} module, and are
- implicitly used by any package that uses @code{gnu-build-system}
- (@pxref{Build Systems, @code{gnu-build-system}}).
- @unnumberedsec Building the Bootstrap Binaries
- @cindex bootstrap binaries
- Because the final tool chain does not depend on the bootstrap binaries,
- those rarely need to be updated. Nevertheless, it is useful to have an
- automated way to produce them, should an update occur, and this is what
- the @code{(gnu packages make-bootstrap)} module provides.
- The following command builds the tarballs containing the bootstrap binaries
- (Binutils, GCC, glibc, for the traditional bootstrap and linux-libre-headers,
- bootstrap-mescc-tools, bootstrap-mes for the Reduced Binary Seed bootstrap,
- and Guile, and a tarball containing a mixture of Coreutils and other basic
- command-line tools):
- @example
- guix build bootstrap-tarballs
- @end example
- The generated tarballs are those that should be referred to in the
- @code{(gnu packages bootstrap)} module mentioned at the beginning of
- this section.
- Still here? Then perhaps by now you've started to wonder: when do we
- reach a fixed point? That is an interesting question! The answer is
- unknown, but if you would like to investigate further (and have
- significant computational and storage resources to do so), then let us
- know.
- @unnumberedsec Reducing the Set of Bootstrap Binaries
- Our traditional bootstrap includes GCC, GNU Libc, Guile, etc. That's a lot of
- binary code! Why is that a problem? It's a problem because these big chunks
- of binary code are practically non-auditable, which makes it hard to establish
- what source code produced them. Every unauditable binary also leaves us
- vulnerable to compiler backdoors as described by Ken Thompson in the 1984
- paper @emph{Reflections on Trusting Trust}.
- This is mitigated by the fact that our bootstrap binaries were generated
- from an earlier Guix revision. Nevertheless it lacks the level of
- transparency that we get in the rest of the package dependency graph,
- where Guix always gives us a source-to-binary mapping. Thus, our goal
- is to reduce the set of bootstrap binaries to the bare minimum.
- The @uref{https://bootstrappable.org, Bootstrappable.org web site} lists
- on-going projects to do that. One of these is about replacing the
- bootstrap GCC with a sequence of assemblers, interpreters, and compilers
- of increasing complexity, which could be built from source starting from
- a simple and auditable assembler.
- Our first major achievement is the replacement of of GCC, the GNU C Library
- and Binutils by MesCC-Tools (a simple hex linker and macro assembler) and Mes
- (@pxref{Top, GNU Mes Reference Manual,, mes, GNU Mes}, a Scheme interpreter
- and C compiler in Scheme). Neither MesCC-Tools nor Mes can be fully
- bootstrapped yet and thus we inject them as binary seeds. We call this the
- Reduced Binary Seed bootstrap, as it has halved the size of our bootstrap
- binaries! Also, it has eliminated the C compiler binary; i686-linux and
- x86_64-linux Guix packages are now bootstrapped without any binary C compiler.
- Work is ongoing to make MesCC-Tools and Mes fully bootstrappable and we are
- also looking at any other bootstrap binaries. Your help is welcome!
- @node Porting
- @chapter Porting to a New Platform
- As discussed above, the GNU distribution is self-contained, and
- self-containment is achieved by relying on pre-built ``bootstrap
- binaries'' (@pxref{Bootstrapping}). These binaries are specific to an
- operating system kernel, CPU architecture, and application binary
- interface (ABI). Thus, to port the distribution to a platform that is
- not yet supported, one must build those bootstrap binaries, and update
- the @code{(gnu packages bootstrap)} module to use them on that platform.
- Fortunately, Guix can @emph{cross compile} those bootstrap binaries.
- When everything goes well, and assuming the GNU tool chain supports the
- target platform, this can be as simple as running a command like this
- one:
- @example
- guix build --target=armv5tel-linux-gnueabi bootstrap-tarballs
- @end example
- For this to work, the @code{glibc-dynamic-linker} procedure in
- @code{(gnu packages bootstrap)} must be augmented to return the right
- file name for libc's dynamic linker on that platform; likewise,
- @code{system->linux-architecture} in @code{(gnu packages linux)} must be
- taught about the new platform.
- Once these are built, the @code{(gnu packages bootstrap)} module needs
- to be updated to refer to these binaries on the target platform. That
- is, the hashes and URLs of the bootstrap tarballs for the new platform
- must be added alongside those of the currently supported platforms. The
- bootstrap Guile tarball is treated specially: it is expected to be
- available locally, and @file{gnu/local.mk} has rules to download it for
- the supported architectures; a rule for the new platform must be added
- as well.
- In practice, there may be some complications. First, it may be that the
- extended GNU triplet that specifies an ABI (like the @code{eabi} suffix
- above) is not recognized by all the GNU tools. Typically, glibc
- recognizes some of these, whereas GCC uses an extra @option{--with-abi}
- configure flag (see @code{gcc.scm} for examples of how to handle this).
- Second, some of the required packages could fail to build for that
- platform. Lastly, the generated binaries could be broken for some
- reason.
- @c *********************************************************************
- @include contributing.texi
- @c *********************************************************************
- @node Acknowledgments
- @chapter Acknowledgments
- Guix is based on the @uref{https://nixos.org/nix/, Nix package manager},
- which was designed and
- implemented by Eelco Dolstra, with contributions from other people (see
- the @file{nix/AUTHORS} file in Guix). Nix pioneered functional package
- management, and promoted unprecedented features, such as transactional
- package upgrades and rollbacks, per-user profiles, and referentially
- transparent build processes. Without this work, Guix would not exist.
- The Nix-based software distributions, Nixpkgs and NixOS, have also been
- an inspiration for Guix.
- GNU@tie{}Guix itself is a collective work with contributions from a
- number of people. See the @file{AUTHORS} file in Guix for more
- information on these fine people. The @file{THANKS} file lists people
- who have helped by reporting bugs, taking care of the infrastructure,
- providing artwork and themes, making suggestions, and more---thank you!
- @c *********************************************************************
- @node GNU Free Documentation License
- @appendix GNU Free Documentation License
- @cindex license, GNU Free Documentation License
- @include fdl-1.3.texi
- @c *********************************************************************
- @node Concept Index
- @unnumbered Concept Index
- @printindex cp
- @node Programming Index
- @unnumbered Programming Index
- @syncodeindex tp fn
- @syncodeindex vr fn
- @printindex fn
- @bye
- @c Local Variables:
- @c ispell-local-dictionary: "american";
- @c End:
|
