| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566156715681569157015711572157315741575157615771578157915801581158215831584158515861587158815891590159115921593159415951596159715981599160016011602160316041605160616071608160916101611161216131614161516161617161816191620162116221623162416251626162716281629163016311632163316341635163616371638163916401641164216431644164516461647164816491650165116521653165416551656165716581659166016611662166316641665166616671668166916701671167216731674167516761677167816791680168116821683168416851686168716881689169016911692169316941695169616971698169917001701170217031704170517061707170817091710171117121713171417151716171717181719172017211722172317241725172617271728172917301731173217331734173517361737173817391740174117421743174417451746174717481749175017511752175317541755175617571758175917601761176217631764176517661767176817691770177117721773177417751776177717781779178017811782178317841785178617871788178917901791179217931794179517961797179817991800180118021803180418051806180718081809181018111812181318141815181618171818181918201821182218231824182518261827182818291830183118321833183418351836183718381839184018411842184318441845184618471848184918501851185218531854185518561857185818591860186118621863186418651866186718681869187018711872187318741875187618771878187918801881188218831884188518861887188818891890189118921893189418951896189718981899190019011902190319041905190619071908190919101911191219131914191519161917191819191920192119221923192419251926192719281929193019311932193319341935193619371938193919401941194219431944194519461947194819491950195119521953195419551956195719581959196019611962196319641965196619671968196919701971197219731974197519761977197819791980198119821983198419851986198719881989199019911992199319941995199619971998199920002001200220032004200520062007200820092010201120122013201420152016201720182019202020212022202320242025202620272028202920302031203220332034203520362037203820392040204120422043204420452046204720482049205020512052205320542055205620572058205920602061206220632064206520662067206820692070207120722073207420752076207720782079208020812082208320842085208620872088208920902091209220932094209520962097209820992100210121022103210421052106210721082109211021112112211321142115211621172118211921202121212221232124212521262127212821292130213121322133213421352136213721382139214021412142214321442145214621472148214921502151215221532154215521562157215821592160216121622163216421652166216721682169217021712172217321742175217621772178217921802181218221832184218521862187218821892190219121922193219421952196219721982199220022012202220322042205220622072208220922102211221222132214221522162217221822192220222122222223222422252226222722282229223022312232223322342235223622372238223922402241224222432244224522462247224822492250225122522253225422552256225722582259226022612262226322642265226622672268226922702271227222732274227522762277227822792280228122822283228422852286228722882289229022912292229322942295229622972298229923002301230223032304230523062307230823092310231123122313231423152316231723182319232023212322232323242325232623272328232923302331233223332334233523362337233823392340234123422343234423452346234723482349235023512352235323542355235623572358235923602361236223632364236523662367236823692370237123722373237423752376237723782379238023812382238323842385238623872388238923902391239223932394239523962397239823992400240124022403240424052406240724082409241024112412241324142415241624172418241924202421242224232424242524262427242824292430243124322433243424352436243724382439244024412442244324442445244624472448244924502451245224532454245524562457245824592460246124622463246424652466246724682469247024712472247324742475247624772478247924802481248224832484248524862487248824892490249124922493249424952496249724982499250025012502250325042505250625072508250925102511251225132514251525162517251825192520252125222523252425252526252725282529253025312532253325342535253625372538253925402541254225432544254525462547254825492550255125522553255425552556255725582559256025612562256325642565256625672568256925702571257225732574257525762577257825792580258125822583258425852586258725882589259025912592259325942595259625972598259926002601260226032604260526062607260826092610261126122613261426152616261726182619262026212622262326242625262626272628262926302631263226332634263526362637263826392640264126422643264426452646264726482649265026512652265326542655265626572658265926602661266226632664266526662667266826692670267126722673267426752676267726782679268026812682268326842685268626872688268926902691269226932694269526962697269826992700270127022703270427052706270727082709271027112712271327142715271627172718271927202721272227232724272527262727272827292730273127322733273427352736273727382739274027412742274327442745274627472748274927502751275227532754275527562757275827592760276127622763276427652766276727682769277027712772277327742775277627772778277927802781278227832784278527862787278827892790279127922793279427952796279727982799280028012802280328042805280628072808280928102811281228132814281528162817281828192820282128222823282428252826282728282829283028312832283328342835283628372838283928402841284228432844284528462847284828492850285128522853285428552856285728582859286028612862286328642865286628672868286928702871287228732874287528762877287828792880288128822883288428852886288728882889289028912892289328942895289628972898289929002901290229032904290529062907290829092910291129122913291429152916291729182919292029212922292329242925292629272928292929302931293229332934293529362937293829392940294129422943294429452946294729482949295029512952295329542955295629572958295929602961296229632964296529662967296829692970297129722973297429752976297729782979298029812982298329842985298629872988298929902991299229932994299529962997299829993000300130023003300430053006300730083009301030113012301330143015301630173018301930203021302230233024302530263027302830293030303130323033303430353036303730383039304030413042304330443045304630473048304930503051305230533054305530563057305830593060306130623063306430653066306730683069307030713072307330743075307630773078307930803081308230833084308530863087308830893090309130923093309430953096309730983099310031013102310331043105310631073108310931103111311231133114311531163117311831193120312131223123312431253126312731283129313031313132313331343135313631373138313931403141314231433144314531463147314831493150315131523153315431553156315731583159316031613162316331643165316631673168316931703171317231733174317531763177317831793180318131823183318431853186318731883189319031913192319331943195319631973198319932003201320232033204320532063207320832093210321132123213321432153216321732183219322032213222322332243225322632273228322932303231323232333234323532363237323832393240324132423243324432453246324732483249325032513252325332543255325632573258325932603261326232633264326532663267326832693270327132723273327432753276327732783279328032813282328332843285328632873288328932903291329232933294329532963297329832993300330133023303330433053306330733083309331033113312331333143315331633173318331933203321332233233324332533263327332833293330333133323333333433353336333733383339334033413342334333443345334633473348334933503351335233533354335533563357335833593360336133623363336433653366336733683369337033713372337333743375337633773378337933803381338233833384338533863387338833893390339133923393339433953396339733983399340034013402340334043405340634073408340934103411341234133414341534163417341834193420342134223423342434253426342734283429343034313432343334343435343634373438343934403441344234433444344534463447344834493450345134523453345434553456345734583459346034613462346334643465346634673468346934703471347234733474347534763477347834793480348134823483348434853486348734883489349034913492349334943495349634973498349935003501350235033504350535063507350835093510351135123513351435153516351735183519352035213522352335243525352635273528352935303531353235333534353535363537353835393540354135423543354435453546354735483549355035513552355335543555355635573558355935603561356235633564356535663567356835693570357135723573357435753576357735783579358035813582358335843585358635873588358935903591359235933594359535963597359835993600360136023603360436053606360736083609361036113612361336143615361636173618361936203621362236233624362536263627362836293630363136323633363436353636363736383639364036413642364336443645364636473648364936503651365236533654365536563657365836593660366136623663366436653666366736683669367036713672367336743675367636773678367936803681368236833684368536863687368836893690369136923693369436953696369736983699370037013702370337043705370637073708370937103711371237133714371537163717371837193720372137223723372437253726372737283729373037313732373337343735373637373738373937403741374237433744374537463747374837493750375137523753375437553756375737583759376037613762376337643765376637673768376937703771377237733774377537763777377837793780378137823783378437853786378737883789379037913792379337943795379637973798379938003801380238033804380538063807380838093810381138123813381438153816381738183819382038213822382338243825382638273828382938303831383238333834383538363837383838393840384138423843384438453846384738483849385038513852385338543855385638573858385938603861386238633864386538663867386838693870387138723873387438753876387738783879388038813882388338843885388638873888388938903891389238933894389538963897389838993900390139023903390439053906390739083909391039113912391339143915391639173918391939203921392239233924392539263927392839293930393139323933393439353936393739383939394039413942394339443945394639473948394939503951395239533954395539563957395839593960396139623963396439653966396739683969397039713972397339743975397639773978397939803981398239833984398539863987398839893990399139923993399439953996399739983999400040014002400340044005400640074008400940104011401240134014401540164017401840194020402140224023402440254026402740284029403040314032403340344035403640374038403940404041404240434044404540464047404840494050405140524053405440554056405740584059406040614062406340644065406640674068406940704071407240734074407540764077407840794080408140824083408440854086408740884089409040914092409340944095409640974098409941004101410241034104410541064107410841094110411141124113411441154116411741184119412041214122412341244125412641274128412941304131413241334134413541364137413841394140414141424143414441454146414741484149415041514152415341544155415641574158415941604161416241634164416541664167416841694170417141724173417441754176417741784179418041814182418341844185418641874188418941904191419241934194419541964197419841994200420142024203420442054206420742084209421042114212421342144215421642174218421942204221422242234224422542264227422842294230423142324233423442354236423742384239424042414242424342444245424642474248424942504251425242534254425542564257425842594260426142624263426442654266426742684269427042714272427342744275427642774278427942804281428242834284428542864287428842894290429142924293429442954296429742984299430043014302430343044305430643074308430943104311431243134314431543164317431843194320432143224323432443254326432743284329433043314332433343344335433643374338433943404341434243434344434543464347434843494350435143524353435443554356435743584359436043614362436343644365436643674368436943704371437243734374437543764377437843794380438143824383438443854386438743884389439043914392439343944395439643974398439944004401440244034404440544064407440844094410441144124413441444154416441744184419442044214422442344244425442644274428442944304431443244334434443544364437443844394440444144424443444444454446444744484449445044514452445344544455445644574458445944604461446244634464446544664467446844694470447144724473447444754476447744784479448044814482448344844485448644874488448944904491449244934494449544964497449844994500450145024503450445054506450745084509451045114512451345144515451645174518451945204521452245234524452545264527452845294530453145324533453445354536453745384539454045414542454345444545454645474548454945504551455245534554455545564557455845594560456145624563456445654566456745684569457045714572457345744575457645774578457945804581458245834584458545864587458845894590459145924593459445954596459745984599460046014602460346044605460646074608460946104611461246134614461546164617461846194620462146224623462446254626462746284629463046314632463346344635463646374638463946404641464246434644464546464647464846494650465146524653465446554656465746584659466046614662466346644665466646674668466946704671467246734674467546764677467846794680468146824683468446854686468746884689469046914692469346944695469646974698469947004701470247034704470547064707470847094710471147124713471447154716471747184719472047214722472347244725472647274728472947304731473247334734473547364737473847394740474147424743474447454746474747484749475047514752475347544755475647574758475947604761476247634764476547664767476847694770477147724773477447754776477747784779478047814782478347844785478647874788478947904791479247934794479547964797479847994800480148024803480448054806480748084809481048114812481348144815481648174818481948204821482248234824482548264827482848294830483148324833483448354836483748384839484048414842484348444845484648474848484948504851485248534854485548564857485848594860486148624863486448654866486748684869487048714872487348744875487648774878487948804881488248834884488548864887488848894890489148924893489448954896489748984899490049014902490349044905490649074908490949104911491249134914491549164917491849194920492149224923492449254926492749284929493049314932493349344935493649374938493949404941494249434944494549464947494849494950495149524953495449554956495749584959496049614962496349644965496649674968496949704971497249734974497549764977497849794980498149824983498449854986498749884989499049914992499349944995499649974998499950005001500250035004500550065007500850095010501150125013501450155016501750185019502050215022502350245025502650275028502950305031503250335034503550365037503850395040504150425043504450455046504750485049505050515052505350545055505650575058505950605061506250635064506550665067506850695070507150725073507450755076507750785079508050815082508350845085508650875088508950905091509250935094509550965097509850995100510151025103510451055106510751085109511051115112511351145115511651175118511951205121512251235124512551265127512851295130513151325133513451355136513751385139514051415142514351445145514651475148514951505151515251535154515551565157515851595160516151625163516451655166516751685169517051715172517351745175517651775178517951805181518251835184518551865187518851895190519151925193519451955196519751985199520052015202520352045205520652075208520952105211521252135214521552165217521852195220522152225223522452255226522752285229523052315232523352345235523652375238523952405241524252435244524552465247524852495250525152525253525452555256525752585259526052615262526352645265526652675268526952705271527252735274527552765277527852795280528152825283528452855286528752885289529052915292529352945295529652975298529953005301530253035304530553065307530853095310531153125313531453155316531753185319532053215322532353245325532653275328532953305331533253335334533553365337533853395340534153425343534453455346534753485349535053515352535353545355535653575358535953605361536253635364536553665367536853695370537153725373537453755376537753785379538053815382538353845385538653875388538953905391539253935394539553965397539853995400540154025403540454055406540754085409541054115412541354145415541654175418541954205421542254235424542554265427542854295430543154325433543454355436543754385439544054415442544354445445544654475448544954505451545254535454545554565457545854595460546154625463546454655466546754685469547054715472547354745475547654775478547954805481548254835484548554865487548854895490549154925493549454955496549754985499550055015502550355045505550655075508550955105511551255135514551555165517551855195520552155225523552455255526552755285529553055315532553355345535553655375538553955405541554255435544554555465547554855495550555155525553555455555556555755585559556055615562556355645565556655675568556955705571557255735574557555765577557855795580558155825583558455855586558755885589559055915592559355945595559655975598559956005601560256035604560556065607560856095610561156125613561456155616561756185619562056215622562356245625562656275628562956305631563256335634563556365637563856395640564156425643564456455646564756485649565056515652565356545655565656575658565956605661566256635664566556665667566856695670567156725673567456755676567756785679568056815682568356845685568656875688568956905691569256935694569556965697569856995700570157025703570457055706570757085709571057115712571357145715571657175718571957205721572257235724572557265727572857295730573157325733573457355736573757385739574057415742574357445745574657475748574957505751575257535754575557565757575857595760576157625763576457655766576757685769577057715772577357745775577657775778577957805781578257835784578557865787578857895790579157925793579457955796579757985799580058015802580358045805580658075808580958105811581258135814581558165817581858195820582158225823582458255826582758285829583058315832583358345835583658375838583958405841584258435844584558465847584858495850585158525853585458555856585758585859586058615862586358645865586658675868586958705871587258735874587558765877587858795880588158825883588458855886588758885889589058915892589358945895589658975898589959005901590259035904590559065907590859095910591159125913591459155916591759185919592059215922592359245925592659275928592959305931593259335934593559365937593859395940594159425943594459455946594759485949595059515952595359545955595659575958595959605961596259635964596559665967596859695970597159725973597459755976597759785979598059815982598359845985598659875988598959905991599259935994599559965997599859996000600160026003600460056006600760086009601060116012601360146015601660176018601960206021602260236024602560266027602860296030603160326033603460356036603760386039604060416042604360446045604660476048604960506051605260536054605560566057605860596060606160626063606460656066606760686069607060716072607360746075607660776078607960806081608260836084608560866087608860896090609160926093609460956096609760986099610061016102610361046105610661076108610961106111611261136114611561166117611861196120612161226123612461256126612761286129613061316132613361346135613661376138613961406141614261436144614561466147614861496150615161526153615461556156615761586159616061616162616361646165616661676168616961706171617261736174617561766177617861796180618161826183618461856186618761886189619061916192619361946195619661976198619962006201620262036204620562066207620862096210621162126213621462156216621762186219622062216222622362246225622662276228622962306231623262336234623562366237623862396240624162426243624462456246624762486249625062516252625362546255625662576258625962606261626262636264626562666267626862696270627162726273627462756276627762786279628062816282628362846285628662876288628962906291629262936294629562966297629862996300630163026303630463056306630763086309631063116312631363146315631663176318631963206321632263236324632563266327632863296330633163326333633463356336633763386339634063416342634363446345634663476348634963506351635263536354635563566357635863596360636163626363636463656366636763686369637063716372637363746375637663776378637963806381638263836384638563866387638863896390639163926393639463956396639763986399640064016402640364046405640664076408640964106411641264136414641564166417641864196420642164226423642464256426642764286429643064316432643364346435643664376438643964406441644264436444644564466447644864496450645164526453645464556456645764586459646064616462646364646465646664676468646964706471647264736474647564766477647864796480648164826483648464856486648764886489649064916492649364946495649664976498649965006501650265036504650565066507650865096510651165126513651465156516651765186519652065216522652365246525652665276528652965306531653265336534653565366537653865396540654165426543654465456546654765486549655065516552655365546555655665576558655965606561656265636564656565666567656865696570657165726573657465756576657765786579658065816582658365846585658665876588658965906591659265936594659565966597659865996600660166026603660466056606660766086609661066116612661366146615661666176618661966206621662266236624662566266627662866296630663166326633663466356636663766386639664066416642664366446645664666476648664966506651665266536654665566566657665866596660666166626663666466656666666766686669667066716672667366746675667666776678667966806681668266836684668566866687668866896690669166926693669466956696669766986699670067016702670367046705670667076708670967106711671267136714671567166717671867196720672167226723672467256726672767286729673067316732673367346735673667376738673967406741674267436744674567466747674867496750675167526753675467556756675767586759676067616762676367646765676667676768676967706771677267736774677567766777677867796780678167826783678467856786678767886789679067916792679367946795679667976798679968006801680268036804680568066807680868096810681168126813681468156816681768186819682068216822682368246825682668276828682968306831683268336834683568366837683868396840684168426843684468456846684768486849685068516852685368546855685668576858685968606861686268636864686568666867686868696870687168726873687468756876687768786879688068816882688368846885688668876888688968906891689268936894689568966897689868996900690169026903690469056906690769086909691069116912691369146915691669176918691969206921692269236924692569266927692869296930693169326933693469356936693769386939694069416942694369446945694669476948694969506951695269536954695569566957695869596960696169626963696469656966696769686969697069716972697369746975697669776978697969806981698269836984698569866987698869896990699169926993699469956996699769986999700070017002700370047005700670077008700970107011701270137014701570167017701870197020702170227023702470257026702770287029703070317032703370347035703670377038703970407041704270437044704570467047704870497050705170527053705470557056705770587059706070617062706370647065706670677068706970707071707270737074707570767077707870797080708170827083708470857086708770887089709070917092709370947095709670977098709971007101710271037104710571067107710871097110711171127113711471157116711771187119712071217122712371247125712671277128712971307131713271337134713571367137713871397140714171427143714471457146714771487149715071517152715371547155715671577158715971607161716271637164716571667167716871697170717171727173717471757176717771787179718071817182718371847185718671877188718971907191719271937194719571967197719871997200720172027203720472057206720772087209721072117212721372147215721672177218721972207221722272237224722572267227722872297230723172327233723472357236723772387239724072417242724372447245724672477248724972507251725272537254725572567257725872597260726172627263726472657266726772687269727072717272727372747275727672777278727972807281728272837284728572867287728872897290729172927293729472957296729772987299730073017302730373047305730673077308730973107311731273137314731573167317731873197320732173227323732473257326732773287329733073317332733373347335733673377338733973407341734273437344734573467347734873497350735173527353735473557356735773587359736073617362736373647365736673677368736973707371737273737374737573767377737873797380738173827383738473857386738773887389739073917392739373947395739673977398739974007401740274037404740574067407740874097410741174127413741474157416741774187419742074217422742374247425742674277428742974307431743274337434743574367437743874397440744174427443744474457446744774487449745074517452745374547455745674577458745974607461746274637464746574667467746874697470747174727473747474757476747774787479748074817482748374847485748674877488748974907491749274937494749574967497749874997500750175027503750475057506750775087509751075117512751375147515751675177518751975207521752275237524752575267527752875297530753175327533753475357536753775387539754075417542754375447545754675477548754975507551755275537554755575567557755875597560756175627563756475657566756775687569757075717572757375747575757675777578757975807581758275837584758575867587758875897590759175927593759475957596759775987599760076017602760376047605760676077608760976107611761276137614761576167617761876197620762176227623762476257626762776287629763076317632763376347635763676377638763976407641764276437644764576467647764876497650765176527653765476557656765776587659766076617662766376647665766676677668766976707671767276737674767576767677767876797680768176827683768476857686768776887689769076917692769376947695769676977698769977007701770277037704770577067707770877097710771177127713771477157716771777187719772077217722772377247725772677277728772977307731773277337734773577367737773877397740774177427743774477457746774777487749775077517752775377547755775677577758775977607761776277637764776577667767776877697770777177727773777477757776777777787779778077817782778377847785778677877788778977907791779277937794779577967797779877997800780178027803780478057806780778087809781078117812781378147815781678177818781978207821782278237824782578267827782878297830783178327833783478357836783778387839784078417842784378447845784678477848784978507851785278537854785578567857785878597860786178627863786478657866786778687869787078717872787378747875787678777878787978807881788278837884788578867887788878897890789178927893789478957896789778987899790079017902790379047905790679077908790979107911791279137914791579167917791879197920792179227923792479257926792779287929793079317932793379347935793679377938793979407941794279437944794579467947794879497950795179527953795479557956795779587959796079617962796379647965796679677968796979707971797279737974797579767977797879797980798179827983798479857986798779887989799079917992799379947995799679977998799980008001800280038004800580068007800880098010801180128013801480158016801780188019802080218022802380248025802680278028802980308031803280338034803580368037803880398040804180428043804480458046804780488049805080518052805380548055805680578058805980608061806280638064806580668067806880698070807180728073807480758076807780788079808080818082808380848085808680878088808980908091809280938094809580968097809880998100810181028103810481058106810781088109811081118112811381148115811681178118811981208121812281238124812581268127812881298130813181328133813481358136813781388139814081418142814381448145814681478148814981508151815281538154815581568157815881598160816181628163816481658166816781688169817081718172817381748175817681778178817981808181818281838184818581868187818881898190819181928193819481958196819781988199820082018202820382048205820682078208820982108211821282138214821582168217821882198220822182228223822482258226822782288229823082318232823382348235823682378238823982408241824282438244824582468247824882498250825182528253825482558256825782588259826082618262826382648265826682678268826982708271827282738274827582768277827882798280828182828283828482858286828782888289829082918292829382948295829682978298829983008301830283038304830583068307830883098310831183128313831483158316831783188319832083218322832383248325832683278328832983308331833283338334833583368337833883398340834183428343834483458346834783488349835083518352835383548355835683578358835983608361836283638364836583668367836883698370837183728373837483758376837783788379838083818382838383848385838683878388838983908391839283938394839583968397839883998400840184028403840484058406840784088409841084118412841384148415841684178418841984208421842284238424842584268427842884298430843184328433843484358436843784388439844084418442844384448445844684478448844984508451845284538454845584568457845884598460846184628463846484658466846784688469847084718472847384748475847684778478847984808481848284838484848584868487848884898490849184928493849484958496849784988499850085018502850385048505850685078508850985108511851285138514851585168517851885198520852185228523852485258526852785288529853085318532853385348535853685378538853985408541854285438544854585468547854885498550855185528553855485558556855785588559856085618562856385648565856685678568856985708571857285738574857585768577857885798580858185828583858485858586858785888589859085918592859385948595859685978598859986008601860286038604860586068607860886098610861186128613861486158616861786188619862086218622862386248625862686278628862986308631863286338634863586368637863886398640864186428643864486458646864786488649865086518652865386548655865686578658865986608661866286638664866586668667866886698670867186728673867486758676867786788679868086818682868386848685868686878688868986908691869286938694869586968697869886998700870187028703870487058706870787088709871087118712871387148715871687178718871987208721872287238724872587268727872887298730873187328733873487358736873787388739874087418742874387448745874687478748874987508751875287538754875587568757875887598760876187628763876487658766876787688769877087718772877387748775877687778778877987808781878287838784878587868787878887898790879187928793879487958796879787988799880088018802880388048805880688078808880988108811881288138814881588168817881888198820882188228823882488258826882788288829883088318832883388348835883688378838883988408841884288438844884588468847884888498850885188528853885488558856885788588859886088618862886388648865886688678868886988708871887288738874887588768877887888798880888188828883888488858886888788888889889088918892889388948895889688978898889989008901890289038904890589068907890889098910891189128913891489158916891789188919892089218922892389248925892689278928892989308931893289338934893589368937893889398940894189428943894489458946894789488949895089518952895389548955895689578958895989608961896289638964896589668967896889698970897189728973897489758976897789788979898089818982898389848985898689878988898989908991899289938994899589968997899889999000900190029003900490059006900790089009901090119012901390149015901690179018901990209021902290239024902590269027902890299030903190329033903490359036903790389039904090419042904390449045904690479048904990509051905290539054905590569057905890599060906190629063906490659066906790689069907090719072907390749075907690779078907990809081908290839084908590869087908890899090909190929093909490959096909790989099910091019102910391049105910691079108910991109111911291139114911591169117911891199120912191229123912491259126912791289129913091319132913391349135913691379138913991409141914291439144914591469147914891499150915191529153915491559156915791589159916091619162916391649165916691679168916991709171917291739174917591769177917891799180918191829183918491859186918791889189919091919192919391949195919691979198919992009201920292039204920592069207920892099210921192129213921492159216921792189219922092219222922392249225922692279228922992309231923292339234923592369237923892399240924192429243924492459246924792489249925092519252925392549255925692579258925992609261926292639264926592669267926892699270927192729273927492759276927792789279928092819282928392849285928692879288928992909291929292939294929592969297929892999300930193029303930493059306930793089309931093119312931393149315931693179318931993209321932293239324932593269327932893299330933193329333933493359336933793389339934093419342934393449345934693479348934993509351935293539354935593569357935893599360936193629363936493659366936793689369937093719372937393749375937693779378937993809381938293839384938593869387938893899390939193929393939493959396939793989399940094019402940394049405940694079408940994109411941294139414941594169417941894199420942194229423942494259426942794289429943094319432943394349435943694379438943994409441944294439444944594469447944894499450945194529453945494559456945794589459946094619462946394649465946694679468946994709471947294739474947594769477947894799480948194829483948494859486948794889489949094919492949394949495949694979498949995009501950295039504950595069507950895099510951195129513951495159516951795189519952095219522952395249525952695279528952995309531953295339534953595369537953895399540954195429543954495459546954795489549955095519552955395549555955695579558955995609561956295639564956595669567956895699570957195729573957495759576957795789579958095819582958395849585958695879588958995909591959295939594959595969597959895999600960196029603960496059606960796089609961096119612961396149615961696179618961996209621962296239624962596269627962896299630963196329633963496359636963796389639964096419642964396449645964696479648964996509651965296539654965596569657965896599660966196629663966496659666966796689669967096719672967396749675967696779678967996809681968296839684968596869687968896899690969196929693969496959696969796989699970097019702970397049705970697079708970997109711971297139714971597169717971897199720972197229723972497259726972797289729973097319732973397349735973697379738973997409741974297439744974597469747974897499750975197529753975497559756975797589759976097619762976397649765976697679768976997709771977297739774977597769777977897799780978197829783978497859786978797889789979097919792979397949795979697979798979998009801980298039804980598069807980898099810981198129813981498159816981798189819982098219822982398249825982698279828982998309831983298339834983598369837983898399840984198429843984498459846984798489849985098519852985398549855985698579858985998609861986298639864986598669867986898699870987198729873987498759876987798789879988098819882988398849885988698879888988998909891989298939894989598969897989898999900990199029903990499059906990799089909991099119912991399149915991699179918991999209921992299239924992599269927992899299930993199329933993499359936993799389939994099419942994399449945994699479948994999509951995299539954995599569957995899599960996199629963996499659966996799689969997099719972997399749975997699779978997999809981998299839984998599869987998899899990999199929993999499959996999799989999100001000110002100031000410005100061000710008100091001010011100121001310014100151001610017100181001910020100211002210023100241002510026100271002810029100301003110032100331003410035100361003710038100391004010041100421004310044100451004610047100481004910050100511005210053100541005510056100571005810059100601006110062100631006410065100661006710068100691007010071100721007310074100751007610077100781007910080100811008210083100841008510086100871008810089100901009110092100931009410095100961009710098100991010010101101021010310104101051010610107101081010910110101111011210113101141011510116101171011810119101201012110122101231012410125101261012710128101291013010131101321013310134101351013610137101381013910140101411014210143101441014510146101471014810149101501015110152101531015410155101561015710158101591016010161101621016310164101651016610167101681016910170101711017210173101741017510176101771017810179101801018110182101831018410185101861018710188101891019010191101921019310194101951019610197101981019910200102011020210203102041020510206102071020810209102101021110212102131021410215102161021710218102191022010221102221022310224102251022610227102281022910230102311023210233102341023510236102371023810239102401024110242102431024410245102461024710248102491025010251102521025310254102551025610257102581025910260102611026210263102641026510266102671026810269102701027110272102731027410275102761027710278102791028010281102821028310284102851028610287102881028910290102911029210293102941029510296102971029810299103001030110302103031030410305103061030710308103091031010311103121031310314103151031610317103181031910320103211032210323103241032510326103271032810329103301033110332103331033410335103361033710338103391034010341103421034310344103451034610347103481034910350103511035210353103541035510356103571035810359103601036110362103631036410365103661036710368103691037010371103721037310374103751037610377103781037910380103811038210383103841038510386103871038810389103901039110392103931039410395103961039710398103991040010401104021040310404104051040610407104081040910410104111041210413104141041510416104171041810419104201042110422104231042410425104261042710428104291043010431104321043310434104351043610437104381043910440104411044210443104441044510446104471044810449104501045110452104531045410455104561045710458104591046010461104621046310464104651046610467104681046910470104711047210473104741047510476104771047810479104801048110482104831048410485104861048710488104891049010491104921049310494104951049610497104981049910500105011050210503105041050510506105071050810509105101051110512105131051410515105161051710518105191052010521105221052310524105251052610527105281052910530105311053210533105341053510536105371053810539105401054110542105431054410545105461054710548105491055010551105521055310554105551055610557105581055910560105611056210563105641056510566105671056810569105701057110572105731057410575105761057710578105791058010581105821058310584105851058610587105881058910590105911059210593105941059510596105971059810599106001060110602106031060410605106061060710608106091061010611106121061310614106151061610617106181061910620106211062210623106241062510626106271062810629106301063110632106331063410635106361063710638106391064010641106421064310644106451064610647106481064910650106511065210653106541065510656106571065810659106601066110662106631066410665106661066710668106691067010671106721067310674106751067610677106781067910680106811068210683106841068510686106871068810689106901069110692106931069410695106961069710698106991070010701107021070310704107051070610707107081070910710107111071210713107141071510716107171071810719107201072110722107231072410725107261072710728107291073010731107321073310734107351073610737107381073910740107411074210743107441074510746107471074810749107501075110752107531075410755107561075710758107591076010761107621076310764107651076610767107681076910770107711077210773107741077510776107771077810779107801078110782107831078410785107861078710788107891079010791107921079310794107951079610797107981079910800108011080210803108041080510806108071080810809108101081110812108131081410815108161081710818108191082010821108221082310824108251082610827108281082910830108311083210833108341083510836108371083810839108401084110842108431084410845108461084710848108491085010851108521085310854108551085610857108581085910860108611086210863108641086510866108671086810869108701087110872108731087410875108761087710878108791088010881108821088310884108851088610887108881088910890108911089210893108941089510896108971089810899109001090110902109031090410905109061090710908109091091010911109121091310914109151091610917109181091910920109211092210923109241092510926109271092810929109301093110932109331093410935109361093710938109391094010941109421094310944109451094610947109481094910950109511095210953109541095510956109571095810959109601096110962109631096410965109661096710968109691097010971109721097310974109751097610977109781097910980109811098210983109841098510986109871098810989109901099110992109931099410995109961099710998109991100011001110021100311004110051100611007110081100911010110111101211013110141101511016110171101811019110201102111022110231102411025110261102711028110291103011031110321103311034110351103611037110381103911040110411104211043110441104511046110471104811049110501105111052110531105411055110561105711058110591106011061110621106311064110651106611067110681106911070110711107211073110741107511076110771107811079110801108111082110831108411085110861108711088110891109011091110921109311094110951109611097110981109911100111011110211103111041110511106111071110811109111101111111112111131111411115111161111711118111191112011121111221112311124111251112611127111281112911130111311113211133111341113511136111371113811139111401114111142111431114411145111461114711148111491115011151111521115311154111551115611157111581115911160111611116211163111641116511166111671116811169111701117111172111731117411175111761117711178111791118011181111821118311184111851118611187111881118911190111911119211193111941119511196111971119811199112001120111202112031120411205112061120711208112091121011211112121121311214112151121611217112181121911220112211122211223112241122511226112271122811229112301123111232112331123411235112361123711238112391124011241112421124311244112451124611247112481124911250112511125211253112541125511256112571125811259112601126111262112631126411265112661126711268112691127011271112721127311274112751127611277112781127911280112811128211283112841128511286112871128811289112901129111292112931129411295112961129711298112991130011301113021130311304113051130611307113081130911310113111131211313113141131511316113171131811319113201132111322113231132411325113261132711328113291133011331113321133311334113351133611337113381133911340113411134211343113441134511346113471134811349113501135111352113531135411355113561135711358113591136011361113621136311364113651136611367113681136911370113711137211373113741137511376113771137811379113801138111382113831138411385113861138711388113891139011391113921139311394113951139611397113981139911400114011140211403114041140511406114071140811409114101141111412114131141411415114161141711418114191142011421114221142311424114251142611427114281142911430114311143211433114341143511436114371143811439114401144111442114431144411445114461144711448114491145011451114521145311454114551145611457114581145911460114611146211463114641146511466114671146811469114701147111472114731147411475114761147711478114791148011481114821148311484114851148611487114881148911490114911149211493114941149511496114971149811499115001150111502115031150411505115061150711508115091151011511115121151311514115151151611517115181151911520115211152211523115241152511526115271152811529115301153111532115331153411535115361153711538115391154011541115421154311544115451154611547115481154911550115511155211553115541155511556115571155811559115601156111562115631156411565115661156711568115691157011571115721157311574115751157611577115781157911580115811158211583115841158511586115871158811589115901159111592115931159411595115961159711598115991160011601116021160311604116051160611607116081160911610116111161211613116141161511616116171161811619116201162111622116231162411625116261162711628116291163011631116321163311634116351163611637116381163911640116411164211643116441164511646116471164811649116501165111652116531165411655116561165711658116591166011661116621166311664116651166611667116681166911670116711167211673116741167511676116771167811679116801168111682116831168411685116861168711688116891169011691116921169311694116951169611697116981169911700117011170211703117041170511706117071170811709117101171111712117131171411715117161171711718117191172011721117221172311724117251172611727117281172911730117311173211733117341173511736117371173811739117401174111742117431174411745117461174711748117491175011751117521175311754117551175611757117581175911760117611176211763117641176511766117671176811769117701177111772117731177411775117761177711778117791178011781117821178311784117851178611787117881178911790117911179211793117941179511796117971179811799118001180111802118031180411805118061180711808118091181011811118121181311814118151181611817118181181911820118211182211823118241182511826118271182811829118301183111832118331183411835118361183711838118391184011841118421184311844118451184611847118481184911850118511185211853118541185511856118571185811859118601186111862118631186411865118661186711868118691187011871118721187311874118751187611877118781187911880118811188211883118841188511886118871188811889118901189111892118931189411895118961189711898118991190011901119021190311904119051190611907119081190911910119111191211913119141191511916119171191811919119201192111922119231192411925119261192711928119291193011931119321193311934119351193611937119381193911940119411194211943119441194511946119471194811949119501195111952119531195411955119561195711958119591196011961119621196311964119651196611967119681196911970119711197211973119741197511976119771197811979119801198111982119831198411985119861198711988119891199011991119921199311994119951199611997119981199912000120011200212003120041200512006120071200812009120101201112012120131201412015120161201712018120191202012021120221202312024120251202612027120281202912030120311203212033120341203512036120371203812039120401204112042120431204412045120461204712048120491205012051120521205312054120551205612057120581205912060120611206212063120641206512066120671206812069120701207112072120731207412075120761207712078120791208012081120821208312084120851208612087120881208912090120911209212093120941209512096120971209812099121001210112102121031210412105121061210712108121091211012111121121211312114121151211612117121181211912120121211212212123121241212512126121271212812129121301213112132121331213412135121361213712138121391214012141121421214312144121451214612147121481214912150121511215212153121541215512156121571215812159121601216112162121631216412165121661216712168121691217012171121721217312174121751217612177121781217912180121811218212183121841218512186121871218812189121901219112192121931219412195121961219712198121991220012201122021220312204122051220612207122081220912210122111221212213122141221512216122171221812219122201222112222122231222412225122261222712228122291223012231122321223312234122351223612237122381223912240122411224212243122441224512246122471224812249122501225112252122531225412255122561225712258122591226012261122621226312264122651226612267122681226912270122711227212273122741227512276122771227812279122801228112282122831228412285122861228712288122891229012291122921229312294122951229612297122981229912300123011230212303123041230512306123071230812309123101231112312123131231412315123161231712318123191232012321123221232312324123251232612327123281232912330123311233212333123341233512336123371233812339123401234112342123431234412345123461234712348123491235012351123521235312354123551235612357123581235912360123611236212363123641236512366123671236812369123701237112372123731237412375123761237712378123791238012381123821238312384123851238612387123881238912390123911239212393123941239512396123971239812399124001240112402124031240412405124061240712408124091241012411124121241312414124151241612417124181241912420124211242212423124241242512426124271242812429124301243112432124331243412435124361243712438124391244012441124421244312444124451244612447124481244912450124511245212453124541245512456124571245812459124601246112462124631246412465124661246712468124691247012471124721247312474124751247612477124781247912480124811248212483124841248512486124871248812489124901249112492124931249412495124961249712498124991250012501125021250312504125051250612507125081250912510125111251212513125141251512516125171251812519125201252112522125231252412525125261252712528125291253012531125321253312534125351253612537125381253912540125411254212543125441254512546125471254812549125501255112552125531255412555125561255712558125591256012561125621256312564125651256612567125681256912570125711257212573125741257512576125771257812579125801258112582125831258412585125861258712588125891259012591125921259312594125951259612597125981259912600126011260212603126041260512606126071260812609126101261112612126131261412615126161261712618126191262012621126221262312624126251262612627126281262912630126311263212633126341263512636126371263812639126401264112642126431264412645126461264712648126491265012651126521265312654126551265612657126581265912660126611266212663126641266512666126671266812669126701267112672126731267412675126761267712678126791268012681126821268312684126851268612687126881268912690126911269212693126941269512696126971269812699127001270112702127031270412705127061270712708127091271012711127121271312714127151271612717127181271912720127211272212723127241272512726127271272812729127301273112732127331273412735127361273712738127391274012741127421274312744127451274612747127481274912750127511275212753127541275512756127571275812759127601276112762127631276412765127661276712768127691277012771127721277312774127751277612777127781277912780127811278212783127841278512786127871278812789127901279112792127931279412795127961279712798127991280012801128021280312804128051280612807128081280912810128111281212813128141281512816128171281812819128201282112822128231282412825128261282712828128291283012831128321283312834128351283612837128381283912840128411284212843128441284512846128471284812849128501285112852128531285412855128561285712858128591286012861128621286312864128651286612867128681286912870128711287212873128741287512876128771287812879128801288112882128831288412885128861288712888128891289012891128921289312894128951289612897128981289912900129011290212903129041290512906129071290812909129101291112912129131291412915129161291712918129191292012921129221292312924129251292612927129281292912930129311293212933129341293512936129371293812939129401294112942129431294412945129461294712948129491295012951129521295312954129551295612957129581295912960129611296212963129641296512966129671296812969129701297112972129731297412975129761297712978129791298012981129821298312984129851298612987129881298912990129911299212993129941299512996129971299812999130001300113002130031300413005130061300713008130091301013011130121301313014130151301613017130181301913020130211302213023130241302513026130271302813029130301303113032130331303413035130361303713038130391304013041130421304313044130451304613047130481304913050130511305213053130541305513056130571305813059130601306113062130631306413065130661306713068130691307013071130721307313074130751307613077130781307913080130811308213083130841308513086130871308813089130901309113092130931309413095130961309713098130991310013101131021310313104131051310613107131081310913110131111311213113131141311513116131171311813119131201312113122131231312413125131261312713128131291313013131131321313313134131351313613137131381313913140131411314213143131441314513146131471314813149131501315113152131531315413155131561315713158131591316013161131621316313164131651316613167131681316913170131711317213173131741317513176131771317813179131801318113182131831318413185131861318713188131891319013191131921319313194131951319613197131981319913200132011320213203132041320513206132071320813209132101321113212132131321413215132161321713218132191322013221132221322313224132251322613227132281322913230132311323213233132341323513236132371323813239132401324113242132431324413245132461324713248132491325013251132521325313254132551325613257132581325913260132611326213263132641326513266132671326813269132701327113272132731327413275132761327713278132791328013281132821328313284132851328613287132881328913290132911329213293132941329513296132971329813299133001330113302133031330413305133061330713308133091331013311133121331313314133151331613317133181331913320133211332213323133241332513326133271332813329133301333113332133331333413335133361333713338133391334013341133421334313344133451334613347133481334913350133511335213353133541335513356133571335813359133601336113362133631336413365133661336713368133691337013371133721337313374133751337613377133781337913380133811338213383133841338513386133871338813389133901339113392133931339413395133961339713398133991340013401134021340313404134051340613407134081340913410134111341213413134141341513416134171341813419134201342113422134231342413425134261342713428134291343013431134321343313434134351343613437134381343913440134411344213443134441344513446134471344813449134501345113452134531345413455134561345713458134591346013461134621346313464134651346613467134681346913470134711347213473134741347513476134771347813479134801348113482134831348413485134861348713488134891349013491134921349313494134951349613497134981349913500135011350213503135041350513506135071350813509135101351113512135131351413515135161351713518135191352013521135221352313524135251352613527135281352913530135311353213533135341353513536135371353813539135401354113542135431354413545135461354713548135491355013551135521355313554135551355613557135581355913560135611356213563135641356513566135671356813569135701357113572135731357413575135761357713578135791358013581135821358313584135851358613587135881358913590135911359213593135941359513596135971359813599136001360113602136031360413605136061360713608136091361013611136121361313614136151361613617136181361913620136211362213623136241362513626136271362813629136301363113632136331363413635136361363713638136391364013641136421364313644136451364613647136481364913650136511365213653136541365513656136571365813659136601366113662136631366413665136661366713668136691367013671136721367313674136751367613677136781367913680136811368213683136841368513686136871368813689136901369113692136931369413695136961369713698136991370013701137021370313704137051370613707137081370913710137111371213713137141371513716137171371813719137201372113722137231372413725137261372713728137291373013731137321373313734137351373613737137381373913740137411374213743137441374513746137471374813749137501375113752137531375413755137561375713758137591376013761137621376313764137651376613767137681376913770137711377213773137741377513776137771377813779137801378113782137831378413785137861378713788137891379013791137921379313794137951379613797137981379913800138011380213803138041380513806138071380813809138101381113812138131381413815138161381713818138191382013821138221382313824138251382613827138281382913830138311383213833138341383513836138371383813839138401384113842138431384413845138461384713848138491385013851138521385313854138551385613857138581385913860138611386213863138641386513866138671386813869138701387113872138731387413875138761387713878138791388013881138821388313884138851388613887138881388913890138911389213893138941389513896138971389813899139001390113902139031390413905139061390713908139091391013911139121391313914139151391613917139181391913920139211392213923139241392513926139271392813929139301393113932139331393413935139361393713938139391394013941139421394313944139451394613947139481394913950139511395213953139541395513956139571395813959139601396113962139631396413965139661396713968139691397013971139721397313974139751397613977139781397913980139811398213983139841398513986139871398813989139901399113992139931399413995139961399713998139991400014001140021400314004140051400614007140081400914010140111401214013140141401514016140171401814019140201402114022140231402414025140261402714028140291403014031140321403314034140351403614037140381403914040140411404214043140441404514046140471404814049140501405114052140531405414055140561405714058140591406014061140621406314064140651406614067140681406914070140711407214073140741407514076140771407814079140801408114082140831408414085140861408714088140891409014091140921409314094140951409614097140981409914100141011410214103141041410514106141071410814109141101411114112141131411414115141161411714118141191412014121141221412314124141251412614127141281412914130141311413214133141341413514136141371413814139141401414114142141431414414145141461414714148141491415014151141521415314154141551415614157141581415914160141611416214163141641416514166141671416814169141701417114172141731417414175141761417714178141791418014181141821418314184141851418614187141881418914190141911419214193141941419514196141971419814199142001420114202142031420414205142061420714208142091421014211142121421314214142151421614217142181421914220142211422214223142241422514226142271422814229142301423114232142331423414235142361423714238142391424014241142421424314244142451424614247142481424914250142511425214253142541425514256142571425814259142601426114262142631426414265142661426714268142691427014271142721427314274142751427614277142781427914280142811428214283142841428514286142871428814289142901429114292142931429414295142961429714298142991430014301143021430314304143051430614307143081430914310143111431214313143141431514316143171431814319143201432114322143231432414325143261432714328143291433014331143321433314334143351433614337143381433914340143411434214343143441434514346143471434814349143501435114352143531435414355143561435714358143591436014361143621436314364143651436614367143681436914370143711437214373143741437514376143771437814379143801438114382143831438414385143861438714388143891439014391143921439314394143951439614397143981439914400144011440214403144041440514406144071440814409144101441114412144131441414415144161441714418144191442014421144221442314424144251442614427144281442914430144311443214433144341443514436144371443814439144401444114442144431444414445144461444714448144491445014451144521445314454144551445614457144581445914460144611446214463144641446514466144671446814469144701447114472144731447414475144761447714478144791448014481144821448314484144851448614487144881448914490144911449214493144941449514496144971449814499145001450114502145031450414505145061450714508145091451014511145121451314514145151451614517145181451914520145211452214523145241452514526145271452814529145301453114532145331453414535145361453714538145391454014541145421454314544145451454614547145481454914550145511455214553145541455514556145571455814559145601456114562145631456414565145661456714568145691457014571145721457314574145751457614577145781457914580145811458214583145841458514586145871458814589145901459114592145931459414595145961459714598145991460014601146021460314604146051460614607146081460914610146111461214613146141461514616146171461814619146201462114622146231462414625146261462714628146291463014631146321463314634146351463614637146381463914640146411464214643146441464514646146471464814649146501465114652146531465414655146561465714658146591466014661146621466314664146651466614667146681466914670146711467214673146741467514676146771467814679146801468114682146831468414685146861468714688146891469014691146921469314694146951469614697146981469914700147011470214703147041470514706147071470814709147101471114712147131471414715147161471714718147191472014721147221472314724147251472614727147281472914730147311473214733147341473514736147371473814739147401474114742147431474414745147461474714748147491475014751147521475314754147551475614757147581475914760147611476214763147641476514766147671476814769147701477114772147731477414775147761477714778147791478014781147821478314784147851478614787147881478914790147911479214793147941479514796147971479814799148001480114802148031480414805148061480714808148091481014811148121481314814148151481614817148181481914820148211482214823148241482514826148271482814829148301483114832148331483414835148361483714838148391484014841148421484314844148451484614847148481484914850148511485214853148541485514856148571485814859148601486114862148631486414865148661486714868148691487014871148721487314874148751487614877148781487914880148811488214883148841488514886148871488814889148901489114892148931489414895148961489714898148991490014901149021490314904149051490614907149081490914910149111491214913149141491514916149171491814919149201492114922149231492414925149261492714928149291493014931149321493314934149351493614937149381493914940149411494214943149441494514946149471494814949149501495114952149531495414955149561495714958149591496014961149621496314964149651496614967149681496914970149711497214973149741497514976149771497814979149801498114982149831498414985149861498714988149891499014991149921499314994149951499614997149981499915000150011500215003150041500515006150071500815009150101501115012150131501415015150161501715018150191502015021150221502315024150251502615027150281502915030150311503215033150341503515036150371503815039150401504115042150431504415045150461504715048150491505015051150521505315054150551505615057150581505915060150611506215063150641506515066150671506815069150701507115072150731507415075150761507715078150791508015081150821508315084150851508615087150881508915090150911509215093150941509515096150971509815099151001510115102151031510415105151061510715108151091511015111151121511315114151151511615117151181511915120151211512215123151241512515126151271512815129151301513115132151331513415135151361513715138151391514015141151421514315144151451514615147151481514915150151511515215153151541515515156151571515815159151601516115162151631516415165151661516715168151691517015171151721517315174151751517615177151781517915180151811518215183151841518515186151871518815189151901519115192151931519415195151961519715198151991520015201152021520315204152051520615207152081520915210152111521215213152141521515216152171521815219152201522115222152231522415225152261522715228152291523015231152321523315234152351523615237152381523915240152411524215243152441524515246152471524815249152501525115252152531525415255152561525715258152591526015261152621526315264152651526615267152681526915270152711527215273152741527515276152771527815279152801528115282152831528415285152861528715288152891529015291152921529315294152951529615297152981529915300153011530215303153041530515306153071530815309153101531115312153131531415315153161531715318153191532015321153221532315324153251532615327153281532915330153311533215333153341533515336153371533815339153401534115342153431534415345153461534715348153491535015351153521535315354153551535615357153581535915360153611536215363153641536515366153671536815369153701537115372153731537415375153761537715378153791538015381153821538315384153851538615387153881538915390153911539215393153941539515396153971539815399154001540115402154031540415405154061540715408154091541015411154121541315414154151541615417154181541915420154211542215423154241542515426154271542815429154301543115432154331543415435154361543715438154391544015441154421544315444154451544615447154481544915450154511545215453154541545515456154571545815459154601546115462154631546415465154661546715468154691547015471154721547315474154751547615477154781547915480154811548215483154841548515486154871548815489154901549115492154931549415495154961549715498154991550015501155021550315504155051550615507155081550915510155111551215513155141551515516155171551815519155201552115522155231552415525155261552715528155291553015531155321553315534155351553615537155381553915540155411554215543155441554515546155471554815549155501555115552155531555415555155561555715558155591556015561155621556315564155651556615567155681556915570155711557215573155741557515576155771557815579155801558115582155831558415585155861558715588155891559015591155921559315594155951559615597155981559915600156011560215603156041560515606156071560815609156101561115612156131561415615156161561715618156191562015621156221562315624156251562615627156281562915630156311563215633156341563515636156371563815639156401564115642156431564415645156461564715648156491565015651156521565315654156551565615657156581565915660156611566215663156641566515666156671566815669156701567115672156731567415675156761567715678156791568015681156821568315684156851568615687156881568915690156911569215693156941569515696156971569815699157001570115702157031570415705157061570715708157091571015711157121571315714157151571615717157181571915720157211572215723157241572515726157271572815729157301573115732157331573415735157361573715738157391574015741157421574315744157451574615747157481574915750157511575215753157541575515756157571575815759157601576115762157631576415765157661576715768157691577015771157721577315774157751577615777157781577915780157811578215783157841578515786157871578815789157901579115792157931579415795157961579715798157991580015801158021580315804158051580615807158081580915810158111581215813158141581515816158171581815819158201582115822158231582415825158261582715828158291583015831158321583315834158351583615837158381583915840158411584215843158441584515846158471584815849158501585115852158531585415855158561585715858158591586015861158621586315864158651586615867158681586915870158711587215873158741587515876158771587815879158801588115882158831588415885158861588715888158891589015891158921589315894158951589615897158981589915900159011590215903159041590515906159071590815909159101591115912159131591415915159161591715918159191592015921159221592315924159251592615927159281592915930159311593215933159341593515936159371593815939159401594115942159431594415945159461594715948159491595015951159521595315954159551595615957159581595915960159611596215963159641596515966159671596815969159701597115972159731597415975159761597715978159791598015981159821598315984159851598615987159881598915990159911599215993159941599515996159971599815999160001600116002160031600416005160061600716008160091601016011160121601316014160151601616017160181601916020160211602216023160241602516026160271602816029160301603116032160331603416035160361603716038160391604016041160421604316044160451604616047160481604916050160511605216053160541605516056160571605816059160601606116062160631606416065160661606716068160691607016071160721607316074160751607616077160781607916080160811608216083160841608516086160871608816089160901609116092160931609416095160961609716098160991610016101161021610316104161051610616107161081610916110161111611216113161141611516116161171611816119161201612116122161231612416125161261612716128161291613016131161321613316134161351613616137161381613916140161411614216143161441614516146161471614816149161501615116152161531615416155161561615716158161591616016161161621616316164161651616616167161681616916170161711617216173161741617516176161771617816179161801618116182161831618416185161861618716188161891619016191161921619316194161951619616197161981619916200162011620216203162041620516206162071620816209162101621116212162131621416215162161621716218162191622016221162221622316224162251622616227162281622916230162311623216233162341623516236162371623816239162401624116242162431624416245162461624716248162491625016251162521625316254162551625616257162581625916260162611626216263162641626516266162671626816269162701627116272162731627416275162761627716278162791628016281162821628316284162851628616287162881628916290162911629216293162941629516296162971629816299163001630116302163031630416305163061630716308163091631016311163121631316314163151631616317163181631916320163211632216323163241632516326163271632816329163301633116332163331633416335163361633716338163391634016341163421634316344163451634616347163481634916350163511635216353163541635516356163571635816359163601636116362163631636416365163661636716368163691637016371163721637316374163751637616377163781637916380163811638216383163841638516386163871638816389163901639116392163931639416395163961639716398163991640016401164021640316404164051640616407164081640916410164111641216413164141641516416164171641816419164201642116422164231642416425164261642716428164291643016431164321643316434164351643616437164381643916440164411644216443164441644516446164471644816449164501645116452164531645416455164561645716458164591646016461164621646316464164651646616467164681646916470164711647216473164741647516476164771647816479164801648116482164831648416485164861648716488164891649016491164921649316494164951649616497164981649916500165011650216503165041650516506165071650816509165101651116512165131651416515165161651716518165191652016521165221652316524165251652616527165281652916530165311653216533165341653516536165371653816539165401654116542165431654416545165461654716548165491655016551165521655316554165551655616557165581655916560165611656216563165641656516566165671656816569165701657116572165731657416575165761657716578165791658016581165821658316584165851658616587165881658916590165911659216593165941659516596165971659816599166001660116602166031660416605166061660716608166091661016611166121661316614166151661616617166181661916620166211662216623166241662516626166271662816629166301663116632166331663416635166361663716638166391664016641166421664316644166451664616647166481664916650166511665216653166541665516656166571665816659166601666116662166631666416665166661666716668166691667016671166721667316674166751667616677166781667916680166811668216683166841668516686166871668816689166901669116692166931669416695166961669716698166991670016701167021670316704167051670616707167081670916710167111671216713167141671516716167171671816719167201672116722167231672416725167261672716728167291673016731167321673316734167351673616737167381673916740167411674216743167441674516746167471674816749167501675116752167531675416755167561675716758167591676016761167621676316764167651676616767167681676916770167711677216773167741677516776167771677816779167801678116782167831678416785167861678716788167891679016791167921679316794167951679616797167981679916800168011680216803168041680516806168071680816809168101681116812168131681416815168161681716818168191682016821168221682316824168251682616827168281682916830168311683216833168341683516836168371683816839168401684116842168431684416845168461684716848168491685016851168521685316854168551685616857168581685916860168611686216863168641686516866168671686816869168701687116872168731687416875168761687716878168791688016881168821688316884168851688616887168881688916890168911689216893168941689516896168971689816899169001690116902169031690416905169061690716908169091691016911169121691316914169151691616917169181691916920169211692216923169241692516926169271692816929169301693116932169331693416935169361693716938169391694016941169421694316944169451694616947169481694916950169511695216953169541695516956169571695816959169601696116962169631696416965169661696716968169691697016971169721697316974169751697616977169781697916980169811698216983169841698516986169871698816989169901699116992169931699416995169961699716998169991700017001170021700317004170051700617007170081700917010170111701217013170141701517016170171701817019170201702117022170231702417025170261702717028170291703017031170321703317034170351703617037170381703917040170411704217043170441704517046170471704817049170501705117052170531705417055170561705717058170591706017061170621706317064170651706617067170681706917070170711707217073170741707517076170771707817079170801708117082170831708417085170861708717088170891709017091170921709317094170951709617097170981709917100171011710217103171041710517106171071710817109171101711117112171131711417115171161711717118171191712017121171221712317124171251712617127171281712917130171311713217133171341713517136171371713817139171401714117142171431714417145171461714717148171491715017151171521715317154171551715617157171581715917160171611716217163171641716517166171671716817169171701717117172171731717417175171761717717178171791718017181171821718317184171851718617187171881718917190171911719217193171941719517196171971719817199172001720117202172031720417205172061720717208172091721017211172121721317214172151721617217172181721917220172211722217223172241722517226172271722817229172301723117232172331723417235172361723717238172391724017241172421724317244172451724617247172481724917250172511725217253172541725517256172571725817259172601726117262172631726417265172661726717268172691727017271172721727317274172751727617277172781727917280172811728217283172841728517286172871728817289172901729117292172931729417295172961729717298172991730017301173021730317304173051730617307173081730917310173111731217313173141731517316173171731817319173201732117322173231732417325173261732717328173291733017331173321733317334173351733617337173381733917340173411734217343173441734517346173471734817349173501735117352173531735417355173561735717358173591736017361173621736317364173651736617367173681736917370173711737217373173741737517376173771737817379173801738117382173831738417385173861738717388173891739017391173921739317394173951739617397173981739917400174011740217403174041740517406174071740817409174101741117412174131741417415174161741717418174191742017421174221742317424174251742617427174281742917430174311743217433174341743517436174371743817439174401744117442174431744417445174461744717448174491745017451174521745317454174551745617457174581745917460174611746217463174641746517466174671746817469174701747117472174731747417475174761747717478174791748017481174821748317484174851748617487174881748917490174911749217493174941749517496174971749817499175001750117502175031750417505175061750717508175091751017511175121751317514175151751617517175181751917520175211752217523175241752517526175271752817529175301753117532175331753417535175361753717538175391754017541175421754317544175451754617547175481754917550175511755217553175541755517556175571755817559175601756117562175631756417565175661756717568175691757017571175721757317574175751757617577175781757917580175811758217583175841758517586175871758817589175901759117592175931759417595175961759717598175991760017601176021760317604176051760617607176081760917610176111761217613176141761517616176171761817619176201762117622176231762417625176261762717628176291763017631176321763317634176351763617637176381763917640176411764217643176441764517646176471764817649176501765117652176531765417655176561765717658176591766017661176621766317664176651766617667176681766917670176711767217673176741767517676176771767817679176801768117682176831768417685176861768717688176891769017691176921769317694176951769617697176981769917700177011770217703177041770517706177071770817709177101771117712177131771417715177161771717718177191772017721177221772317724177251772617727177281772917730177311773217733177341773517736177371773817739177401774117742177431774417745177461774717748177491775017751177521775317754177551775617757177581775917760177611776217763177641776517766177671776817769177701777117772177731777417775177761777717778177791778017781177821778317784177851778617787177881778917790177911779217793177941779517796177971779817799178001780117802178031780417805178061780717808178091781017811178121781317814178151781617817178181781917820178211782217823178241782517826178271782817829178301783117832178331783417835178361783717838178391784017841178421784317844178451784617847178481784917850178511785217853178541785517856178571785817859178601786117862178631786417865178661786717868178691787017871178721787317874178751787617877178781787917880178811788217883178841788517886178871788817889178901789117892178931789417895178961789717898178991790017901179021790317904179051790617907179081790917910179111791217913179141791517916179171791817919179201792117922179231792417925179261792717928179291793017931179321793317934179351793617937179381793917940179411794217943179441794517946179471794817949179501795117952179531795417955179561795717958179591796017961179621796317964179651796617967179681796917970179711797217973179741797517976179771797817979179801798117982179831798417985179861798717988179891799017991179921799317994179951799617997179981799918000180011800218003180041800518006180071800818009180101801118012180131801418015180161801718018180191802018021180221802318024180251802618027180281802918030180311803218033180341803518036180371803818039180401804118042180431804418045180461804718048180491805018051180521805318054180551805618057180581805918060180611806218063180641806518066180671806818069180701807118072180731807418075180761807718078180791808018081180821808318084180851808618087180881808918090180911809218093180941809518096180971809818099181001810118102181031810418105181061810718108181091811018111181121811318114181151811618117181181811918120181211812218123181241812518126181271812818129181301813118132181331813418135181361813718138181391814018141181421814318144181451814618147181481814918150181511815218153181541815518156181571815818159181601816118162181631816418165181661816718168181691817018171181721817318174181751817618177181781817918180181811818218183181841818518186181871818818189181901819118192181931819418195181961819718198181991820018201182021820318204182051820618207182081820918210182111821218213182141821518216182171821818219182201822118222182231822418225182261822718228182291823018231182321823318234182351823618237182381823918240182411824218243182441824518246182471824818249182501825118252182531825418255182561825718258182591826018261182621826318264182651826618267182681826918270182711827218273182741827518276182771827818279182801828118282182831828418285182861828718288182891829018291182921829318294182951829618297182981829918300183011830218303183041830518306183071830818309183101831118312183131831418315183161831718318183191832018321183221832318324183251832618327183281832918330183311833218333183341833518336183371833818339183401834118342183431834418345183461834718348183491835018351183521835318354183551835618357183581835918360183611836218363183641836518366183671836818369183701837118372183731837418375183761837718378183791838018381183821838318384183851838618387183881838918390183911839218393183941839518396183971839818399184001840118402184031840418405184061840718408184091841018411184121841318414184151841618417184181841918420184211842218423184241842518426184271842818429184301843118432184331843418435184361843718438184391844018441184421844318444184451844618447184481844918450184511845218453184541845518456184571845818459184601846118462184631846418465184661846718468184691847018471184721847318474184751847618477184781847918480184811848218483184841848518486184871848818489184901849118492184931849418495184961849718498184991850018501185021850318504185051850618507185081850918510185111851218513185141851518516185171851818519185201852118522185231852418525185261852718528185291853018531185321853318534185351853618537185381853918540185411854218543185441854518546185471854818549185501855118552185531855418555185561855718558185591856018561185621856318564185651856618567185681856918570185711857218573185741857518576185771857818579185801858118582185831858418585185861858718588185891859018591185921859318594185951859618597185981859918600186011860218603186041860518606186071860818609186101861118612186131861418615186161861718618186191862018621186221862318624186251862618627186281862918630186311863218633186341863518636186371863818639186401864118642186431864418645186461864718648186491865018651186521865318654186551865618657186581865918660186611866218663186641866518666186671866818669186701867118672186731867418675186761867718678186791868018681186821868318684186851868618687186881868918690186911869218693186941869518696186971869818699187001870118702187031870418705187061870718708187091871018711187121871318714187151871618717187181871918720187211872218723187241872518726187271872818729187301873118732187331873418735187361873718738187391874018741187421874318744187451874618747187481874918750187511875218753187541875518756187571875818759187601876118762187631876418765187661876718768187691877018771187721877318774187751877618777187781877918780187811878218783187841878518786187871878818789187901879118792187931879418795187961879718798187991880018801188021880318804188051880618807188081880918810188111881218813188141881518816188171881818819188201882118822188231882418825188261882718828188291883018831188321883318834188351883618837188381883918840188411884218843188441884518846188471884818849188501885118852188531885418855188561885718858188591886018861188621886318864188651886618867188681886918870188711887218873188741887518876188771887818879188801888118882188831888418885188861888718888188891889018891188921889318894188951889618897188981889918900189011890218903189041890518906189071890818909189101891118912189131891418915189161891718918189191892018921189221892318924189251892618927189281892918930189311893218933189341893518936189371893818939189401894118942189431894418945189461894718948189491895018951189521895318954189551895618957189581895918960189611896218963189641896518966189671896818969189701897118972189731897418975189761897718978189791898018981189821898318984189851898618987189881898918990189911899218993189941899518996189971899818999190001900119002190031900419005190061900719008190091901019011190121901319014190151901619017190181901919020190211902219023190241902519026190271902819029190301903119032190331903419035190361903719038190391904019041190421904319044190451904619047190481904919050190511905219053190541905519056190571905819059190601906119062190631906419065190661906719068190691907019071190721907319074190751907619077190781907919080190811908219083190841908519086190871908819089190901909119092190931909419095190961909719098190991910019101191021910319104191051910619107191081910919110191111911219113191141911519116191171911819119191201912119122191231912419125191261912719128191291913019131191321913319134191351913619137191381913919140191411914219143191441914519146191471914819149191501915119152191531915419155191561915719158191591916019161191621916319164191651916619167191681916919170191711917219173191741917519176191771917819179191801918119182191831918419185191861918719188191891919019191191921919319194191951919619197191981919919200192011920219203192041920519206192071920819209192101921119212192131921419215192161921719218192191922019221192221922319224192251922619227192281922919230192311923219233192341923519236192371923819239192401924119242192431924419245192461924719248192491925019251192521925319254192551925619257192581925919260192611926219263192641926519266192671926819269192701927119272192731927419275192761927719278192791928019281192821928319284192851928619287192881928919290192911929219293192941929519296192971929819299193001930119302193031930419305193061930719308193091931019311193121931319314193151931619317193181931919320193211932219323193241932519326193271932819329193301933119332193331933419335193361933719338193391934019341193421934319344193451934619347193481934919350193511935219353193541935519356193571935819359193601936119362193631936419365193661936719368193691937019371193721937319374193751937619377193781937919380193811938219383193841938519386193871938819389193901939119392193931939419395193961939719398193991940019401194021940319404194051940619407194081940919410194111941219413194141941519416194171941819419194201942119422194231942419425194261942719428194291943019431194321943319434194351943619437194381943919440194411944219443194441944519446194471944819449194501945119452194531945419455194561945719458194591946019461194621946319464194651946619467194681946919470194711947219473194741947519476194771947819479194801948119482194831948419485194861948719488194891949019491194921949319494194951949619497194981949919500195011950219503195041950519506195071950819509195101951119512195131951419515195161951719518195191952019521195221952319524195251952619527195281952919530195311953219533195341953519536195371953819539195401954119542195431954419545195461954719548195491955019551195521955319554195551955619557195581955919560195611956219563195641956519566195671956819569195701957119572195731957419575195761957719578195791958019581195821958319584195851958619587195881958919590195911959219593195941959519596195971959819599196001960119602196031960419605196061960719608196091961019611196121961319614196151961619617196181961919620196211962219623196241962519626196271962819629196301963119632196331963419635196361963719638196391964019641196421964319644196451964619647196481964919650196511965219653196541965519656196571965819659196601966119662196631966419665196661966719668196691967019671196721967319674196751967619677196781967919680196811968219683196841968519686196871968819689196901969119692196931969419695196961969719698196991970019701197021970319704197051970619707197081970919710197111971219713197141971519716197171971819719197201972119722197231972419725197261972719728197291973019731197321973319734197351973619737197381973919740197411974219743197441974519746197471974819749197501975119752197531975419755197561975719758197591976019761197621976319764197651976619767197681976919770197711977219773197741977519776197771977819779197801978119782197831978419785197861978719788197891979019791197921979319794197951979619797197981979919800198011980219803198041980519806198071980819809198101981119812198131981419815198161981719818198191982019821198221982319824198251982619827198281982919830198311983219833198341983519836198371983819839198401984119842198431984419845198461984719848198491985019851198521985319854198551985619857198581985919860198611986219863198641986519866198671986819869198701987119872198731987419875198761987719878198791988019881198821988319884198851988619887198881988919890198911989219893198941989519896198971989819899199001990119902199031990419905199061990719908199091991019911199121991319914199151991619917199181991919920199211992219923199241992519926199271992819929199301993119932199331993419935199361993719938199391994019941199421994319944199451994619947199481994919950199511995219953199541995519956199571995819959199601996119962199631996419965199661996719968199691997019971199721997319974199751997619977199781997919980199811998219983199841998519986199871998819989199901999119992199931999419995199961999719998199992000020001200022000320004200052000620007200082000920010200112001220013200142001520016200172001820019200202002120022200232002420025200262002720028200292003020031200322003320034200352003620037200382003920040200412004220043200442004520046200472004820049200502005120052200532005420055200562005720058200592006020061200622006320064200652006620067200682006920070200712007220073200742007520076200772007820079200802008120082200832008420085200862008720088200892009020091200922009320094200952009620097200982009920100201012010220103201042010520106201072010820109201102011120112201132011420115201162011720118201192012020121201222012320124201252012620127201282012920130201312013220133201342013520136201372013820139201402014120142201432014420145201462014720148201492015020151201522015320154201552015620157201582015920160201612016220163201642016520166201672016820169201702017120172201732017420175201762017720178201792018020181201822018320184201852018620187201882018920190201912019220193201942019520196201972019820199202002020120202202032020420205202062020720208202092021020211202122021320214202152021620217202182021920220202212022220223202242022520226202272022820229202302023120232202332023420235202362023720238202392024020241202422024320244202452024620247202482024920250202512025220253202542025520256202572025820259202602026120262202632026420265202662026720268202692027020271202722027320274202752027620277202782027920280202812028220283202842028520286202872028820289202902029120292202932029420295202962029720298202992030020301203022030320304203052030620307203082030920310203112031220313203142031520316203172031820319203202032120322203232032420325203262032720328203292033020331203322033320334203352033620337203382033920340203412034220343203442034520346203472034820349203502035120352203532035420355203562035720358203592036020361203622036320364203652036620367203682036920370203712037220373203742037520376203772037820379203802038120382203832038420385203862038720388203892039020391203922039320394203952039620397203982039920400204012040220403204042040520406204072040820409204102041120412204132041420415204162041720418204192042020421204222042320424204252042620427204282042920430204312043220433204342043520436204372043820439204402044120442204432044420445204462044720448204492045020451204522045320454204552045620457204582045920460204612046220463204642046520466204672046820469204702047120472204732047420475204762047720478204792048020481204822048320484204852048620487204882048920490204912049220493204942049520496204972049820499205002050120502205032050420505205062050720508205092051020511205122051320514205152051620517205182051920520205212052220523205242052520526205272052820529205302053120532205332053420535205362053720538205392054020541205422054320544205452054620547205482054920550205512055220553205542055520556205572055820559205602056120562205632056420565205662056720568205692057020571205722057320574205752057620577205782057920580205812058220583205842058520586205872058820589205902059120592205932059420595205962059720598205992060020601206022060320604206052060620607206082060920610206112061220613206142061520616206172061820619206202062120622206232062420625206262062720628206292063020631206322063320634206352063620637206382063920640206412064220643206442064520646206472064820649206502065120652206532065420655206562065720658206592066020661206622066320664206652066620667206682066920670206712067220673206742067520676206772067820679206802068120682206832068420685206862068720688206892069020691206922069320694206952069620697206982069920700207012070220703207042070520706207072070820709207102071120712207132071420715207162071720718207192072020721207222072320724207252072620727207282072920730207312073220733207342073520736207372073820739207402074120742207432074420745207462074720748207492075020751207522075320754207552075620757207582075920760207612076220763207642076520766207672076820769207702077120772207732077420775207762077720778207792078020781207822078320784207852078620787207882078920790207912079220793207942079520796207972079820799208002080120802208032080420805208062080720808208092081020811208122081320814208152081620817208182081920820208212082220823208242082520826208272082820829208302083120832208332083420835208362083720838208392084020841208422084320844208452084620847208482084920850208512085220853208542085520856208572085820859208602086120862208632086420865208662086720868208692087020871208722087320874208752087620877208782087920880208812088220883208842088520886208872088820889208902089120892208932089420895208962089720898208992090020901209022090320904209052090620907209082090920910209112091220913209142091520916209172091820919209202092120922209232092420925209262092720928209292093020931209322093320934209352093620937209382093920940209412094220943209442094520946209472094820949209502095120952209532095420955209562095720958209592096020961209622096320964209652096620967209682096920970209712097220973209742097520976209772097820979209802098120982209832098420985209862098720988209892099020991209922099320994209952099620997209982099921000210012100221003210042100521006210072100821009210102101121012210132101421015210162101721018210192102021021210222102321024210252102621027210282102921030210312103221033210342103521036210372103821039210402104121042210432104421045210462104721048210492105021051210522105321054210552105621057210582105921060210612106221063210642106521066210672106821069210702107121072210732107421075210762107721078210792108021081210822108321084210852108621087210882108921090210912109221093210942109521096210972109821099211002110121102211032110421105211062110721108211092111021111211122111321114211152111621117211182111921120211212112221123211242112521126211272112821129211302113121132211332113421135211362113721138211392114021141211422114321144211452114621147211482114921150211512115221153211542115521156211572115821159211602116121162211632116421165211662116721168211692117021171211722117321174211752117621177211782117921180211812118221183211842118521186211872118821189211902119121192211932119421195211962119721198211992120021201212022120321204212052120621207212082120921210212112121221213212142121521216212172121821219212202122121222212232122421225212262122721228212292123021231212322123321234212352123621237212382123921240212412124221243212442124521246212472124821249212502125121252212532125421255212562125721258212592126021261212622126321264212652126621267212682126921270212712127221273212742127521276212772127821279212802128121282212832128421285212862128721288212892129021291212922129321294212952129621297212982129921300213012130221303213042130521306213072130821309213102131121312213132131421315213162131721318213192132021321213222132321324213252132621327213282132921330213312133221333213342133521336213372133821339213402134121342213432134421345213462134721348213492135021351213522135321354213552135621357213582135921360213612136221363213642136521366213672136821369213702137121372213732137421375213762137721378213792138021381213822138321384213852138621387213882138921390213912139221393213942139521396213972139821399214002140121402214032140421405214062140721408214092141021411214122141321414214152141621417214182141921420214212142221423214242142521426214272142821429214302143121432214332143421435214362143721438214392144021441214422144321444214452144621447214482144921450214512145221453214542145521456214572145821459214602146121462214632146421465214662146721468214692147021471214722147321474214752147621477214782147921480214812148221483214842148521486214872148821489214902149121492214932149421495214962149721498214992150021501215022150321504215052150621507215082150921510215112151221513215142151521516215172151821519215202152121522215232152421525215262152721528215292153021531215322153321534215352153621537215382153921540215412154221543215442154521546215472154821549215502155121552215532155421555215562155721558215592156021561215622156321564215652156621567215682156921570215712157221573215742157521576215772157821579215802158121582215832158421585215862158721588215892159021591215922159321594215952159621597215982159921600216012160221603216042160521606216072160821609216102161121612216132161421615216162161721618216192162021621216222162321624216252162621627216282162921630216312163221633216342163521636216372163821639216402164121642216432164421645216462164721648216492165021651216522165321654216552165621657216582165921660216612166221663216642166521666216672166821669216702167121672216732167421675216762167721678216792168021681216822168321684216852168621687216882168921690216912169221693216942169521696216972169821699217002170121702217032170421705217062170721708217092171021711217122171321714217152171621717217182171921720217212172221723217242172521726217272172821729217302173121732217332173421735217362173721738217392174021741217422174321744217452174621747217482174921750217512175221753217542175521756217572175821759217602176121762217632176421765217662176721768217692177021771217722177321774217752177621777217782177921780217812178221783217842178521786217872178821789217902179121792217932179421795217962179721798217992180021801218022180321804218052180621807218082180921810218112181221813218142181521816218172181821819218202182121822218232182421825218262182721828218292183021831218322183321834218352183621837218382183921840218412184221843218442184521846218472184821849218502185121852218532185421855218562185721858218592186021861218622186321864218652186621867218682186921870218712187221873218742187521876218772187821879218802188121882218832188421885218862188721888218892189021891218922189321894218952189621897218982189921900219012190221903219042190521906219072190821909219102191121912219132191421915219162191721918219192192021921219222192321924219252192621927219282192921930219312193221933219342193521936219372193821939219402194121942219432194421945219462194721948219492195021951219522195321954219552195621957219582195921960219612196221963219642196521966219672196821969219702197121972219732197421975219762197721978219792198021981219822198321984219852198621987219882198921990219912199221993219942199521996219972199821999220002200122002220032200422005220062200722008220092201022011220122201322014220152201622017220182201922020220212202222023220242202522026220272202822029220302203122032220332203422035220362203722038220392204022041220422204322044220452204622047220482204922050220512205222053220542205522056220572205822059220602206122062220632206422065220662206722068220692207022071220722207322074220752207622077220782207922080220812208222083220842208522086220872208822089220902209122092220932209422095220962209722098220992210022101221022210322104221052210622107221082210922110221112211222113221142211522116221172211822119221202212122122221232212422125221262212722128221292213022131221322213322134221352213622137221382213922140221412214222143221442214522146221472214822149221502215122152221532215422155221562215722158221592216022161221622216322164221652216622167221682216922170221712217222173221742217522176221772217822179221802218122182221832218422185221862218722188221892219022191221922219322194221952219622197221982219922200222012220222203222042220522206222072220822209222102221122212222132221422215222162221722218222192222022221222222222322224222252222622227222282222922230222312223222233222342223522236222372223822239222402224122242222432224422245222462224722248222492225022251222522225322254222552225622257222582225922260222612226222263222642226522266222672226822269222702227122272222732227422275222762227722278222792228022281222822228322284222852228622287222882228922290222912229222293222942229522296222972229822299223002230122302223032230422305223062230722308223092231022311223122231322314223152231622317223182231922320223212232222323223242232522326223272232822329223302233122332223332233422335223362233722338223392234022341223422234322344223452234622347223482234922350223512235222353223542235522356223572235822359223602236122362223632236422365223662236722368223692237022371223722237322374223752237622377223782237922380223812238222383223842238522386223872238822389223902239122392223932239422395223962239722398223992240022401224022240322404224052240622407224082240922410224112241222413224142241522416224172241822419224202242122422224232242422425224262242722428224292243022431224322243322434224352243622437224382243922440224412244222443224442244522446224472244822449224502245122452224532245422455224562245722458224592246022461224622246322464224652246622467224682246922470224712247222473224742247522476224772247822479224802248122482224832248422485224862248722488224892249022491224922249322494224952249622497224982249922500225012250222503225042250522506225072250822509225102251122512225132251422515225162251722518225192252022521225222252322524225252252622527225282252922530225312253222533225342253522536225372253822539225402254122542225432254422545225462254722548225492255022551225522255322554225552255622557225582255922560225612256222563225642256522566225672256822569225702257122572225732257422575225762257722578225792258022581225822258322584225852258622587225882258922590225912259222593225942259522596225972259822599226002260122602226032260422605226062260722608226092261022611226122261322614226152261622617226182261922620226212262222623226242262522626226272262822629226302263122632226332263422635226362263722638226392264022641226422264322644226452264622647226482264922650226512265222653226542265522656226572265822659226602266122662226632266422665226662266722668226692267022671226722267322674226752267622677226782267922680226812268222683226842268522686226872268822689226902269122692226932269422695226962269722698226992270022701227022270322704227052270622707227082270922710227112271222713227142271522716227172271822719227202272122722227232272422725227262272722728227292273022731227322273322734227352273622737227382273922740227412274222743227442274522746227472274822749227502275122752227532275422755227562275722758227592276022761227622276322764227652276622767227682276922770227712277222773227742277522776227772277822779227802278122782227832278422785227862278722788227892279022791227922279322794227952279622797227982279922800228012280222803228042280522806228072280822809228102281122812228132281422815228162281722818228192282022821228222282322824228252282622827228282282922830228312283222833228342283522836228372283822839228402284122842228432284422845228462284722848228492285022851228522285322854228552285622857228582285922860228612286222863228642286522866228672286822869228702287122872228732287422875228762287722878228792288022881228822288322884228852288622887228882288922890228912289222893228942289522896228972289822899229002290122902229032290422905229062290722908229092291022911229122291322914229152291622917229182291922920229212292222923229242292522926229272292822929229302293122932229332293422935229362293722938229392294022941229422294322944229452294622947229482294922950229512295222953229542295522956229572295822959229602296122962229632296422965229662296722968229692297022971229722297322974229752297622977229782297922980229812298222983229842298522986229872298822989229902299122992229932299422995229962299722998229992300023001230022300323004230052300623007230082300923010230112301223013230142301523016230172301823019230202302123022230232302423025230262302723028230292303023031230322303323034230352303623037230382303923040230412304223043230442304523046230472304823049230502305123052230532305423055230562305723058230592306023061230622306323064230652306623067230682306923070230712307223073230742307523076230772307823079230802308123082230832308423085230862308723088230892309023091230922309323094230952309623097230982309923100231012310223103231042310523106231072310823109231102311123112231132311423115231162311723118231192312023121231222312323124231252312623127231282312923130231312313223133231342313523136231372313823139231402314123142231432314423145231462314723148231492315023151231522315323154231552315623157231582315923160231612316223163231642316523166231672316823169231702317123172231732317423175231762317723178231792318023181231822318323184231852318623187231882318923190231912319223193231942319523196231972319823199232002320123202232032320423205232062320723208232092321023211232122321323214232152321623217232182321923220232212322223223232242322523226232272322823229232302323123232232332323423235232362323723238232392324023241232422324323244232452324623247232482324923250232512325223253232542325523256232572325823259232602326123262232632326423265232662326723268232692327023271232722327323274232752327623277232782327923280232812328223283232842328523286232872328823289232902329123292232932329423295232962329723298232992330023301233022330323304233052330623307233082330923310233112331223313233142331523316233172331823319233202332123322233232332423325233262332723328233292333023331233322333323334233352333623337233382333923340233412334223343233442334523346233472334823349233502335123352233532335423355233562335723358233592336023361233622336323364233652336623367233682336923370233712337223373233742337523376233772337823379233802338123382233832338423385233862338723388233892339023391233922339323394233952339623397233982339923400234012340223403234042340523406234072340823409234102341123412234132341423415234162341723418234192342023421234222342323424234252342623427234282342923430234312343223433234342343523436234372343823439234402344123442234432344423445234462344723448234492345023451234522345323454234552345623457234582345923460234612346223463234642346523466234672346823469234702347123472234732347423475234762347723478234792348023481234822348323484234852348623487234882348923490234912349223493234942349523496234972349823499235002350123502235032350423505235062350723508235092351023511235122351323514235152351623517235182351923520235212352223523235242352523526235272352823529235302353123532235332353423535235362353723538235392354023541235422354323544235452354623547235482354923550235512355223553235542355523556235572355823559235602356123562235632356423565235662356723568235692357023571235722357323574235752357623577235782357923580235812358223583235842358523586235872358823589235902359123592235932359423595235962359723598235992360023601236022360323604236052360623607236082360923610236112361223613236142361523616236172361823619236202362123622236232362423625236262362723628236292363023631236322363323634236352363623637236382363923640236412364223643236442364523646236472364823649236502365123652236532365423655236562365723658236592366023661236622366323664236652366623667236682366923670236712367223673236742367523676236772367823679236802368123682236832368423685236862368723688236892369023691236922369323694236952369623697236982369923700237012370223703237042370523706237072370823709237102371123712237132371423715237162371723718237192372023721237222372323724237252372623727237282372923730237312373223733237342373523736237372373823739237402374123742237432374423745237462374723748237492375023751237522375323754237552375623757237582375923760237612376223763237642376523766237672376823769237702377123772237732377423775237762377723778237792378023781237822378323784237852378623787237882378923790237912379223793237942379523796237972379823799238002380123802238032380423805238062380723808238092381023811238122381323814238152381623817238182381923820238212382223823238242382523826238272382823829238302383123832238332383423835238362383723838238392384023841238422384323844238452384623847238482384923850238512385223853238542385523856238572385823859238602386123862238632386423865238662386723868238692387023871238722387323874238752387623877238782387923880238812388223883238842388523886238872388823889238902389123892238932389423895238962389723898238992390023901239022390323904239052390623907239082390923910239112391223913239142391523916239172391823919239202392123922239232392423925239262392723928239292393023931239322393323934239352393623937239382393923940239412394223943239442394523946239472394823949239502395123952239532395423955239562395723958239592396023961239622396323964239652396623967239682396923970239712397223973239742397523976239772397823979239802398123982239832398423985239862398723988239892399023991239922399323994239952399623997239982399924000240012400224003240042400524006240072400824009240102401124012240132401424015240162401724018240192402024021240222402324024240252402624027240282402924030240312403224033240342403524036240372403824039240402404124042240432404424045240462404724048240492405024051240522405324054240552405624057240582405924060240612406224063240642406524066240672406824069240702407124072240732407424075240762407724078240792408024081240822408324084240852408624087240882408924090240912409224093240942409524096240972409824099241002410124102241032410424105241062410724108241092411024111241122411324114241152411624117241182411924120241212412224123241242412524126241272412824129241302413124132241332413424135241362413724138241392414024141241422414324144241452414624147241482414924150241512415224153241542415524156241572415824159241602416124162241632416424165241662416724168241692417024171241722417324174241752417624177241782417924180241812418224183241842418524186241872418824189241902419124192241932419424195241962419724198241992420024201242022420324204242052420624207242082420924210242112421224213242142421524216242172421824219242202422124222242232422424225242262422724228242292423024231242322423324234242352423624237242382423924240242412424224243242442424524246242472424824249242502425124252242532425424255242562425724258242592426024261242622426324264242652426624267242682426924270242712427224273242742427524276242772427824279242802428124282242832428424285242862428724288242892429024291242922429324294242952429624297242982429924300243012430224303243042430524306243072430824309243102431124312243132431424315243162431724318243192432024321243222432324324243252432624327243282432924330243312433224333243342433524336243372433824339243402434124342243432434424345243462434724348243492435024351243522435324354243552435624357243582435924360243612436224363243642436524366243672436824369243702437124372243732437424375243762437724378243792438024381243822438324384243852438624387243882438924390243912439224393243942439524396243972439824399244002440124402244032440424405244062440724408244092441024411244122441324414244152441624417244182441924420244212442224423244242442524426244272442824429244302443124432244332443424435244362443724438244392444024441244422444324444244452444624447244482444924450244512445224453244542445524456244572445824459244602446124462244632446424465244662446724468244692447024471244722447324474244752447624477244782447924480244812448224483244842448524486244872448824489244902449124492244932449424495244962449724498244992450024501245022450324504245052450624507245082450924510245112451224513245142451524516245172451824519245202452124522245232452424525245262452724528245292453024531245322453324534245352453624537245382453924540245412454224543245442454524546245472454824549245502455124552245532455424555245562455724558245592456024561245622456324564245652456624567245682456924570245712457224573245742457524576245772457824579245802458124582245832458424585245862458724588245892459024591245922459324594245952459624597245982459924600246012460224603246042460524606246072460824609246102461124612246132461424615246162461724618246192462024621246222462324624246252462624627246282462924630246312463224633246342463524636246372463824639246402464124642246432464424645246462464724648246492465024651246522465324654246552465624657246582465924660246612466224663246642466524666246672466824669246702467124672246732467424675246762467724678246792468024681246822468324684246852468624687246882468924690246912469224693246942469524696246972469824699247002470124702247032470424705247062470724708247092471024711247122471324714247152471624717247182471924720247212472224723247242472524726247272472824729247302473124732247332473424735247362473724738247392474024741247422474324744247452474624747247482474924750247512475224753247542475524756247572475824759247602476124762247632476424765247662476724768247692477024771247722477324774247752477624777247782477924780247812478224783247842478524786247872478824789247902479124792247932479424795247962479724798247992480024801248022480324804248052480624807248082480924810248112481224813248142481524816248172481824819248202482124822248232482424825248262482724828248292483024831248322483324834248352483624837248382483924840248412484224843248442484524846248472484824849248502485124852248532485424855248562485724858248592486024861248622486324864248652486624867248682486924870248712487224873248742487524876248772487824879248802488124882248832488424885248862488724888248892489024891248922489324894248952489624897248982489924900249012490224903249042490524906249072490824909249102491124912249132491424915249162491724918249192492024921249222492324924249252492624927249282492924930249312493224933249342493524936249372493824939249402494124942249432494424945249462494724948249492495024951249522495324954249552495624957249582495924960249612496224963249642496524966249672496824969249702497124972249732497424975249762497724978249792498024981249822498324984249852498624987249882498924990249912499224993249942499524996249972499824999250002500125002250032500425005250062500725008250092501025011250122501325014250152501625017250182501925020250212502225023250242502525026250272502825029250302503125032250332503425035250362503725038250392504025041250422504325044250452504625047250482504925050250512505225053250542505525056250572505825059250602506125062250632506425065250662506725068250692507025071250722507325074250752507625077250782507925080250812508225083250842508525086250872508825089250902509125092250932509425095250962509725098250992510025101251022510325104251052510625107251082510925110251112511225113251142511525116251172511825119251202512125122251232512425125251262512725128251292513025131251322513325134251352513625137251382513925140251412514225143251442514525146251472514825149251502515125152251532515425155251562515725158251592516025161251622516325164251652516625167251682516925170251712517225173251742517525176251772517825179251802518125182251832518425185251862518725188251892519025191251922519325194251952519625197251982519925200252012520225203252042520525206252072520825209252102521125212252132521425215252162521725218252192522025221252222522325224252252522625227252282522925230252312523225233252342523525236252372523825239252402524125242252432524425245252462524725248252492525025251252522525325254252552525625257252582525925260252612526225263252642526525266252672526825269252702527125272252732527425275252762527725278252792528025281252822528325284252852528625287252882528925290252912529225293252942529525296252972529825299253002530125302253032530425305253062530725308253092531025311253122531325314253152531625317253182531925320253212532225323253242532525326253272532825329253302533125332253332533425335253362533725338253392534025341253422534325344253452534625347253482534925350253512535225353253542535525356253572535825359253602536125362253632536425365253662536725368253692537025371253722537325374253752537625377253782537925380253812538225383253842538525386253872538825389253902539125392253932539425395253962539725398253992540025401254022540325404254052540625407254082540925410254112541225413254142541525416254172541825419254202542125422254232542425425254262542725428254292543025431254322543325434254352543625437254382543925440254412544225443254442544525446254472544825449254502545125452254532545425455254562545725458254592546025461254622546325464254652546625467254682546925470254712547225473254742547525476254772547825479254802548125482254832548425485254862548725488254892549025491254922549325494254952549625497254982549925500255012550225503255042550525506255072550825509255102551125512255132551425515255162551725518255192552025521255222552325524255252552625527255282552925530255312553225533255342553525536255372553825539255402554125542255432554425545255462554725548255492555025551255522555325554255552555625557255582555925560255612556225563255642556525566255672556825569255702557125572255732557425575255762557725578255792558025581255822558325584255852558625587255882558925590255912559225593255942559525596255972559825599256002560125602256032560425605256062560725608256092561025611256122561325614256152561625617256182561925620256212562225623256242562525626256272562825629256302563125632256332563425635256362563725638256392564025641256422564325644256452564625647256482564925650256512565225653256542565525656256572565825659256602566125662256632566425665256662566725668256692567025671256722567325674256752567625677256782567925680256812568225683256842568525686256872568825689256902569125692256932569425695256962569725698256992570025701257022570325704257052570625707257082570925710257112571225713257142571525716257172571825719257202572125722257232572425725257262572725728257292573025731257322573325734257352573625737257382573925740257412574225743257442574525746257472574825749257502575125752257532575425755257562575725758257592576025761257622576325764257652576625767257682576925770257712577225773257742577525776257772577825779257802578125782257832578425785257862578725788257892579025791257922579325794257952579625797257982579925800258012580225803258042580525806258072580825809258102581125812258132581425815258162581725818258192582025821258222582325824258252582625827258282582925830258312583225833258342583525836258372583825839258402584125842258432584425845258462584725848258492585025851258522585325854258552585625857258582585925860258612586225863258642586525866258672586825869258702587125872258732587425875258762587725878258792588025881258822588325884258852588625887258882588925890258912589225893258942589525896258972589825899259002590125902259032590425905259062590725908259092591025911259122591325914259152591625917259182591925920259212592225923259242592525926259272592825929259302593125932259332593425935259362593725938259392594025941259422594325944259452594625947259482594925950259512595225953259542595525956259572595825959259602596125962259632596425965259662596725968259692597025971259722597325974259752597625977259782597925980259812598225983259842598525986259872598825989259902599125992259932599425995259962599725998259992600026001260022600326004260052600626007260082600926010260112601226013260142601526016260172601826019260202602126022260232602426025260262602726028260292603026031260322603326034260352603626037260382603926040260412604226043260442604526046260472604826049260502605126052260532605426055260562605726058260592606026061260622606326064260652606626067260682606926070260712607226073260742607526076260772607826079260802608126082260832608426085260862608726088260892609026091260922609326094260952609626097260982609926100261012610226103261042610526106261072610826109261102611126112261132611426115261162611726118261192612026121261222612326124261252612626127261282612926130261312613226133261342613526136261372613826139261402614126142261432614426145261462614726148261492615026151261522615326154261552615626157261582615926160261612616226163261642616526166261672616826169261702617126172261732617426175261762617726178261792618026181261822618326184261852618626187261882618926190261912619226193261942619526196261972619826199262002620126202262032620426205262062620726208262092621026211262122621326214262152621626217262182621926220262212622226223262242622526226262272622826229262302623126232262332623426235262362623726238262392624026241262422624326244262452624626247262482624926250262512625226253262542625526256262572625826259262602626126262262632626426265262662626726268262692627026271262722627326274262752627626277262782627926280262812628226283262842628526286262872628826289262902629126292262932629426295262962629726298262992630026301263022630326304263052630626307263082630926310263112631226313263142631526316263172631826319263202632126322263232632426325263262632726328263292633026331263322633326334263352633626337263382633926340263412634226343263442634526346263472634826349263502635126352263532635426355263562635726358263592636026361263622636326364263652636626367263682636926370263712637226373263742637526376263772637826379263802638126382263832638426385263862638726388263892639026391263922639326394263952639626397263982639926400264012640226403264042640526406264072640826409264102641126412264132641426415264162641726418264192642026421264222642326424264252642626427264282642926430264312643226433264342643526436264372643826439264402644126442264432644426445264462644726448264492645026451264522645326454264552645626457264582645926460264612646226463264642646526466264672646826469264702647126472264732647426475264762647726478264792648026481264822648326484264852648626487264882648926490264912649226493264942649526496264972649826499265002650126502265032650426505265062650726508265092651026511265122651326514265152651626517265182651926520265212652226523265242652526526265272652826529265302653126532265332653426535265362653726538265392654026541265422654326544265452654626547265482654926550265512655226553265542655526556265572655826559265602656126562265632656426565265662656726568265692657026571265722657326574265752657626577265782657926580265812658226583265842658526586265872658826589265902659126592265932659426595265962659726598265992660026601266022660326604266052660626607266082660926610266112661226613266142661526616266172661826619266202662126622266232662426625266262662726628266292663026631266322663326634266352663626637266382663926640266412664226643266442664526646266472664826649266502665126652266532665426655266562665726658266592666026661266622666326664266652666626667266682666926670266712667226673266742667526676266772667826679266802668126682266832668426685266862668726688266892669026691266922669326694266952669626697266982669926700267012670226703267042670526706267072670826709267102671126712267132671426715267162671726718267192672026721267222672326724267252672626727267282672926730267312673226733267342673526736267372673826739267402674126742267432674426745267462674726748267492675026751267522675326754267552675626757267582675926760267612676226763267642676526766267672676826769267702677126772267732677426775267762677726778267792678026781267822678326784267852678626787267882678926790267912679226793267942679526796267972679826799268002680126802268032680426805268062680726808268092681026811268122681326814268152681626817268182681926820268212682226823268242682526826268272682826829268302683126832268332683426835268362683726838268392684026841268422684326844268452684626847268482684926850268512685226853268542685526856268572685826859268602686126862268632686426865268662686726868268692687026871268722687326874268752687626877268782687926880268812688226883268842688526886268872688826889268902689126892268932689426895268962689726898268992690026901269022690326904269052690626907269082690926910269112691226913269142691526916269172691826919269202692126922269232692426925269262692726928269292693026931269322693326934269352693626937269382693926940269412694226943269442694526946269472694826949269502695126952269532695426955269562695726958269592696026961269622696326964269652696626967269682696926970269712697226973269742697526976269772697826979269802698126982269832698426985269862698726988269892699026991269922699326994269952699626997269982699927000270012700227003270042700527006270072700827009270102701127012270132701427015270162701727018270192702027021270222702327024270252702627027270282702927030270312703227033270342703527036270372703827039270402704127042270432704427045270462704727048270492705027051270522705327054270552705627057270582705927060270612706227063270642706527066270672706827069270702707127072270732707427075270762707727078270792708027081270822708327084270852708627087270882708927090270912709227093270942709527096270972709827099271002710127102271032710427105271062710727108271092711027111271122711327114271152711627117271182711927120271212712227123271242712527126271272712827129271302713127132271332713427135271362713727138271392714027141271422714327144271452714627147271482714927150271512715227153271542715527156271572715827159271602716127162271632716427165271662716727168271692717027171271722717327174271752717627177271782717927180271812718227183271842718527186271872718827189271902719127192271932719427195271962719727198271992720027201272022720327204272052720627207272082720927210272112721227213272142721527216272172721827219272202722127222272232722427225272262722727228272292723027231272322723327234272352723627237272382723927240272412724227243272442724527246272472724827249272502725127252272532725427255272562725727258272592726027261272622726327264272652726627267272682726927270272712727227273272742727527276272772727827279272802728127282272832728427285272862728727288272892729027291272922729327294272952729627297272982729927300273012730227303273042730527306273072730827309273102731127312273132731427315273162731727318273192732027321273222732327324273252732627327273282732927330273312733227333273342733527336273372733827339273402734127342273432734427345273462734727348273492735027351273522735327354273552735627357273582735927360273612736227363273642736527366273672736827369273702737127372273732737427375273762737727378273792738027381273822738327384273852738627387273882738927390273912739227393273942739527396273972739827399274002740127402274032740427405274062740727408274092741027411274122741327414274152741627417274182741927420274212742227423274242742527426274272742827429274302743127432274332743427435274362743727438274392744027441274422744327444274452744627447274482744927450274512745227453274542745527456274572745827459274602746127462274632746427465274662746727468274692747027471274722747327474274752747627477274782747927480274812748227483274842748527486274872748827489274902749127492274932749427495274962749727498274992750027501275022750327504275052750627507275082750927510275112751227513275142751527516275172751827519275202752127522275232752427525275262752727528275292753027531275322753327534275352753627537275382753927540275412754227543275442754527546275472754827549275502755127552275532755427555275562755727558275592756027561275622756327564275652756627567275682756927570275712757227573275742757527576275772757827579275802758127582275832758427585275862758727588275892759027591275922759327594275952759627597275982759927600276012760227603276042760527606276072760827609276102761127612276132761427615276162761727618276192762027621276222762327624276252762627627276282762927630276312763227633276342763527636276372763827639276402764127642276432764427645276462764727648276492765027651276522765327654276552765627657276582765927660276612766227663276642766527666276672766827669276702767127672276732767427675276762767727678276792768027681276822768327684276852768627687276882768927690276912769227693276942769527696276972769827699277002770127702277032770427705277062770727708277092771027711277122771327714277152771627717277182771927720277212772227723277242772527726277272772827729277302773127732277332773427735277362773727738277392774027741277422774327744277452774627747277482774927750277512775227753277542775527756277572775827759277602776127762277632776427765277662776727768277692777027771277722777327774277752777627777277782777927780277812778227783277842778527786277872778827789277902779127792277932779427795277962779727798277992780027801278022780327804278052780627807278082780927810278112781227813278142781527816278172781827819278202782127822278232782427825278262782727828278292783027831278322783327834278352783627837278382783927840278412784227843278442784527846278472784827849278502785127852278532785427855278562785727858278592786027861278622786327864278652786627867278682786927870278712787227873278742787527876278772787827879278802788127882278832788427885278862788727888278892789027891278922789327894278952789627897278982789927900279012790227903279042790527906279072790827909279102791127912279132791427915279162791727918279192792027921279222792327924279252792627927279282792927930279312793227933279342793527936279372793827939279402794127942279432794427945279462794727948279492795027951279522795327954279552795627957279582795927960279612796227963279642796527966279672796827969279702797127972279732797427975279762797727978279792798027981279822798327984279852798627987279882798927990279912799227993279942799527996279972799827999280002800128002280032800428005280062800728008280092801028011280122801328014280152801628017280182801928020280212802228023280242802528026280272802828029280302803128032280332803428035280362803728038280392804028041280422804328044280452804628047280482804928050280512805228053280542805528056280572805828059280602806128062280632806428065280662806728068280692807028071280722807328074280752807628077280782807928080280812808228083280842808528086280872808828089280902809128092280932809428095280962809728098280992810028101281022810328104281052810628107281082810928110281112811228113281142811528116281172811828119281202812128122281232812428125281262812728128281292813028131281322813328134281352813628137281382813928140281412814228143281442814528146281472814828149281502815128152281532815428155281562815728158281592816028161281622816328164281652816628167281682816928170281712817228173281742817528176281772817828179281802818128182281832818428185281862818728188281892819028191281922819328194281952819628197281982819928200282012820228203282042820528206282072820828209282102821128212282132821428215282162821728218282192822028221282222822328224282252822628227282282822928230282312823228233282342823528236282372823828239282402824128242282432824428245282462824728248282492825028251282522825328254282552825628257282582825928260282612826228263282642826528266282672826828269282702827128272282732827428275282762827728278282792828028281282822828328284282852828628287282882828928290282912829228293282942829528296282972829828299283002830128302283032830428305283062830728308283092831028311283122831328314283152831628317283182831928320283212832228323283242832528326283272832828329283302833128332283332833428335283362833728338283392834028341283422834328344283452834628347283482834928350283512835228353283542835528356283572835828359283602836128362283632836428365283662836728368283692837028371283722837328374283752837628377283782837928380283812838228383283842838528386283872838828389283902839128392283932839428395283962839728398283992840028401284022840328404284052840628407284082840928410284112841228413284142841528416284172841828419284202842128422284232842428425284262842728428284292843028431284322843328434284352843628437284382843928440284412844228443284442844528446284472844828449284502845128452284532845428455284562845728458284592846028461284622846328464284652846628467284682846928470284712847228473284742847528476284772847828479284802848128482284832848428485284862848728488284892849028491284922849328494284952849628497284982849928500285012850228503285042850528506285072850828509285102851128512285132851428515285162851728518285192852028521285222852328524285252852628527285282852928530285312853228533285342853528536285372853828539285402854128542285432854428545285462854728548285492855028551285522855328554285552855628557285582855928560285612856228563285642856528566285672856828569285702857128572285732857428575285762857728578285792858028581285822858328584285852858628587285882858928590285912859228593285942859528596285972859828599286002860128602286032860428605286062860728608286092861028611286122861328614286152861628617286182861928620286212862228623286242862528626286272862828629286302863128632286332863428635286362863728638286392864028641286422864328644286452864628647286482864928650286512865228653286542865528656286572865828659286602866128662286632866428665286662866728668286692867028671286722867328674286752867628677286782867928680286812868228683286842868528686286872868828689286902869128692286932869428695286962869728698286992870028701287022870328704287052870628707287082870928710287112871228713287142871528716287172871828719287202872128722287232872428725287262872728728287292873028731287322873328734287352873628737287382873928740287412874228743287442874528746287472874828749287502875128752287532875428755287562875728758287592876028761287622876328764287652876628767287682876928770287712877228773287742877528776287772877828779287802878128782287832878428785287862878728788287892879028791287922879328794287952879628797287982879928800288012880228803288042880528806288072880828809288102881128812288132881428815288162881728818288192882028821288222882328824288252882628827288282882928830288312883228833288342883528836288372883828839288402884128842288432884428845288462884728848288492885028851288522885328854288552885628857288582885928860288612886228863288642886528866288672886828869288702887128872288732887428875288762887728878288792888028881288822888328884288852888628887288882888928890288912889228893288942889528896288972889828899289002890128902289032890428905289062890728908289092891028911289122891328914289152891628917289182891928920289212892228923289242892528926289272892828929289302893128932289332893428935289362893728938289392894028941289422894328944289452894628947289482894928950289512895228953289542895528956289572895828959289602896128962289632896428965289662896728968289692897028971289722897328974289752897628977289782897928980289812898228983289842898528986289872898828989289902899128992289932899428995289962899728998289992900029001290022900329004290052900629007290082900929010290112901229013290142901529016290172901829019290202902129022290232902429025290262902729028290292903029031290322903329034290352903629037290382903929040290412904229043290442904529046290472904829049290502905129052290532905429055290562905729058290592906029061290622906329064290652906629067290682906929070290712907229073290742907529076290772907829079290802908129082290832908429085290862908729088290892909029091290922909329094290952909629097290982909929100291012910229103291042910529106291072910829109291102911129112291132911429115291162911729118291192912029121291222912329124291252912629127291282912929130291312913229133291342913529136291372913829139291402914129142291432914429145291462914729148291492915029151291522915329154291552915629157291582915929160291612916229163291642916529166291672916829169291702917129172291732917429175291762917729178291792918029181291822918329184291852918629187291882918929190291912919229193291942919529196291972919829199292002920129202292032920429205292062920729208292092921029211292122921329214292152921629217292182921929220292212922229223292242922529226292272922829229292302923129232292332923429235292362923729238292392924029241292422924329244292452924629247292482924929250292512925229253292542925529256292572925829259292602926129262292632926429265292662926729268292692927029271292722927329274292752927629277292782927929280292812928229283292842928529286292872928829289292902929129292292932929429295292962929729298292992930029301293022930329304293052930629307293082930929310293112931229313293142931529316293172931829319293202932129322293232932429325293262932729328293292933029331293322933329334293352933629337293382933929340293412934229343293442934529346293472934829349293502935129352293532935429355293562935729358293592936029361293622936329364293652936629367293682936929370293712937229373293742937529376293772937829379293802938129382293832938429385293862938729388293892939029391293922939329394293952939629397293982939929400294012940229403294042940529406294072940829409294102941129412294132941429415294162941729418294192942029421294222942329424294252942629427294282942929430294312943229433294342943529436294372943829439294402944129442294432944429445294462944729448294492945029451294522945329454294552945629457294582945929460294612946229463294642946529466294672946829469294702947129472294732947429475294762947729478294792948029481294822948329484294852948629487294882948929490294912949229493294942949529496294972949829499295002950129502295032950429505295062950729508295092951029511295122951329514295152951629517295182951929520295212952229523295242952529526295272952829529295302953129532295332953429535295362953729538295392954029541295422954329544295452954629547295482954929550295512955229553295542955529556295572955829559295602956129562295632956429565295662956729568295692957029571295722957329574295752957629577295782957929580295812958229583295842958529586295872958829589295902959129592295932959429595295962959729598295992960029601296022960329604296052960629607296082960929610296112961229613296142961529616296172961829619296202962129622296232962429625296262962729628296292963029631296322963329634296352963629637296382963929640296412964229643296442964529646296472964829649296502965129652296532965429655296562965729658296592966029661296622966329664296652966629667296682966929670296712967229673296742967529676296772967829679296802968129682296832968429685296862968729688296892969029691296922969329694296952969629697296982969929700297012970229703297042970529706297072970829709297102971129712297132971429715297162971729718297192972029721297222972329724297252972629727297282972929730297312973229733297342973529736297372973829739297402974129742297432974429745297462974729748297492975029751297522975329754297552975629757297582975929760297612976229763297642976529766297672976829769297702977129772297732977429775297762977729778297792978029781297822978329784297852978629787297882978929790297912979229793297942979529796297972979829799298002980129802298032980429805298062980729808298092981029811298122981329814298152981629817298182981929820298212982229823298242982529826298272982829829298302983129832298332983429835298362983729838298392984029841298422984329844298452984629847298482984929850298512985229853298542985529856298572985829859298602986129862298632986429865298662986729868298692987029871298722987329874298752987629877298782987929880298812988229883298842988529886298872988829889298902989129892298932989429895298962989729898298992990029901299022990329904299052990629907299082990929910299112991229913299142991529916299172991829919299202992129922299232992429925299262992729928299292993029931299322993329934299352993629937299382993929940299412994229943299442994529946299472994829949299502995129952299532995429955299562995729958299592996029961299622996329964299652996629967299682996929970299712997229973299742997529976299772997829979299802998129982299832998429985299862998729988299892999029991299922999329994299952999629997299982999930000300013000230003300043000530006300073000830009300103001130012300133001430015300163001730018300193002030021300223002330024300253002630027300283002930030300313003230033300343003530036300373003830039300403004130042300433004430045300463004730048300493005030051300523005330054300553005630057300583005930060300613006230063300643006530066300673006830069300703007130072300733007430075300763007730078300793008030081300823008330084300853008630087300883008930090300913009230093300943009530096300973009830099301003010130102301033010430105301063010730108301093011030111301123011330114301153011630117301183011930120301213012230123301243012530126301273012830129301303013130132301333013430135301363013730138301393014030141301423014330144301453014630147301483014930150301513015230153301543015530156301573015830159301603016130162301633016430165301663016730168301693017030171301723017330174301753017630177301783017930180301813018230183301843018530186301873018830189301903019130192301933019430195301963019730198301993020030201302023020330204302053020630207302083020930210302113021230213302143021530216302173021830219302203022130222302233022430225302263022730228302293023030231302323023330234302353023630237302383023930240302413024230243302443024530246302473024830249302503025130252302533025430255302563025730258302593026030261302623026330264302653026630267302683026930270302713027230273302743027530276302773027830279302803028130282302833028430285302863028730288302893029030291302923029330294302953029630297302983029930300303013030230303303043030530306303073030830309303103031130312303133031430315303163031730318303193032030321303223032330324303253032630327303283032930330303313033230333303343033530336303373033830339303403034130342303433034430345303463034730348303493035030351303523035330354303553035630357303583035930360303613036230363303643036530366303673036830369303703037130372303733037430375303763037730378303793038030381303823038330384303853038630387303883038930390303913039230393303943039530396303973039830399304003040130402304033040430405304063040730408304093041030411304123041330414304153041630417304183041930420304213042230423304243042530426304273042830429304303043130432304333043430435304363043730438304393044030441304423044330444304453044630447304483044930450304513045230453304543045530456304573045830459304603046130462304633046430465304663046730468304693047030471304723047330474304753047630477304783047930480304813048230483304843048530486304873048830489304903049130492304933049430495304963049730498304993050030501305023050330504305053050630507305083050930510305113051230513305143051530516305173051830519305203052130522305233052430525305263052730528305293053030531305323053330534305353053630537305383053930540305413054230543305443054530546305473054830549305503055130552305533055430555305563055730558305593056030561305623056330564305653056630567305683056930570305713057230573305743057530576305773057830579305803058130582305833058430585305863058730588305893059030591305923059330594305953059630597305983059930600306013060230603306043060530606306073060830609306103061130612306133061430615306163061730618306193062030621306223062330624306253062630627306283062930630306313063230633306343063530636306373063830639306403064130642306433064430645306463064730648306493065030651306523065330654306553065630657306583065930660306613066230663306643066530666306673066830669306703067130672306733067430675306763067730678306793068030681306823068330684306853068630687306883068930690306913069230693306943069530696306973069830699307003070130702307033070430705307063070730708307093071030711307123071330714307153071630717307183071930720307213072230723307243072530726307273072830729307303073130732307333073430735307363073730738307393074030741307423074330744307453074630747307483074930750307513075230753307543075530756307573075830759307603076130762307633076430765307663076730768307693077030771307723077330774307753077630777307783077930780307813078230783307843078530786307873078830789307903079130792307933079430795307963079730798307993080030801308023080330804308053080630807308083080930810308113081230813308143081530816308173081830819308203082130822308233082430825308263082730828308293083030831308323083330834308353083630837308383083930840308413084230843308443084530846308473084830849308503085130852308533085430855308563085730858308593086030861308623086330864308653086630867308683086930870308713087230873308743087530876308773087830879308803088130882308833088430885308863088730888308893089030891308923089330894308953089630897308983089930900309013090230903309043090530906309073090830909309103091130912309133091430915309163091730918309193092030921309223092330924309253092630927309283092930930309313093230933309343093530936309373093830939309403094130942309433094430945309463094730948309493095030951309523095330954309553095630957309583095930960309613096230963309643096530966309673096830969309703097130972309733097430975309763097730978309793098030981309823098330984309853098630987309883098930990309913099230993309943099530996309973099830999310003100131002310033100431005310063100731008310093101031011310123101331014310153101631017310183101931020310213102231023310243102531026310273102831029310303103131032310333103431035310363103731038310393104031041310423104331044310453104631047310483104931050310513105231053310543105531056310573105831059310603106131062310633106431065310663106731068310693107031071310723107331074310753107631077310783107931080310813108231083310843108531086310873108831089310903109131092310933109431095310963109731098310993110031101311023110331104311053110631107311083110931110311113111231113311143111531116311173111831119311203112131122311233112431125311263112731128311293113031131311323113331134311353113631137311383113931140311413114231143311443114531146311473114831149311503115131152311533115431155311563115731158311593116031161311623116331164311653116631167311683116931170311713117231173311743117531176311773117831179311803118131182311833118431185311863118731188311893119031191311923119331194311953119631197311983119931200312013120231203312043120531206312073120831209312103121131212312133121431215312163121731218312193122031221312223122331224312253122631227312283122931230312313123231233312343123531236312373123831239312403124131242312433124431245312463124731248312493125031251312523125331254312553125631257312583125931260312613126231263312643126531266312673126831269312703127131272312733127431275312763127731278312793128031281312823128331284312853128631287312883128931290312913129231293312943129531296312973129831299313003130131302313033130431305313063130731308313093131031311313123131331314313153131631317313183131931320313213132231323313243132531326313273132831329313303133131332313333133431335313363133731338313393134031341313423134331344313453134631347313483134931350313513135231353313543135531356313573135831359313603136131362313633136431365313663136731368313693137031371313723137331374313753137631377313783137931380313813138231383313843138531386313873138831389313903139131392313933139431395313963139731398313993140031401314023140331404314053140631407314083140931410314113141231413314143141531416314173141831419314203142131422314233142431425314263142731428314293143031431314323143331434314353143631437314383143931440314413144231443314443144531446314473144831449314503145131452314533145431455314563145731458314593146031461314623146331464314653146631467314683146931470314713147231473314743147531476314773147831479314803148131482314833148431485314863148731488314893149031491314923149331494314953149631497314983149931500315013150231503315043150531506315073150831509315103151131512315133151431515315163151731518315193152031521315223152331524315253152631527315283152931530315313153231533315343153531536315373153831539315403154131542315433154431545315463154731548315493155031551315523155331554315553155631557315583155931560315613156231563315643156531566315673156831569315703157131572315733157431575315763157731578315793158031581315823158331584315853158631587315883158931590315913159231593315943159531596315973159831599316003160131602316033160431605316063160731608316093161031611316123161331614316153161631617316183161931620316213162231623316243162531626316273162831629316303163131632316333163431635316363163731638316393164031641316423164331644316453164631647316483164931650316513165231653316543165531656316573165831659316603166131662316633166431665316663166731668316693167031671316723167331674316753167631677316783167931680316813168231683316843168531686316873168831689316903169131692316933169431695316963169731698316993170031701317023170331704317053170631707317083170931710317113171231713317143171531716317173171831719317203172131722317233172431725317263172731728317293173031731317323173331734317353173631737317383173931740317413174231743317443174531746317473174831749317503175131752317533175431755317563175731758317593176031761317623176331764317653176631767317683176931770317713177231773317743177531776317773177831779317803178131782317833178431785317863178731788317893179031791317923179331794317953179631797317983179931800318013180231803318043180531806318073180831809318103181131812318133181431815318163181731818318193182031821318223182331824318253182631827318283182931830318313183231833318343183531836318373183831839318403184131842318433184431845318463184731848318493185031851318523185331854318553185631857318583185931860318613186231863318643186531866318673186831869318703187131872318733187431875318763187731878318793188031881318823188331884318853188631887318883188931890318913189231893318943189531896318973189831899319003190131902319033190431905319063190731908319093191031911319123191331914319153191631917319183191931920319213192231923319243192531926319273192831929319303193131932319333193431935319363193731938319393194031941319423194331944319453194631947319483194931950319513195231953319543195531956319573195831959319603196131962319633196431965319663196731968319693197031971319723197331974319753197631977319783197931980319813198231983319843198531986319873198831989319903199131992319933199431995319963199731998319993200032001320023200332004320053200632007320083200932010320113201232013320143201532016320173201832019320203202132022320233202432025320263202732028320293203032031320323203332034320353203632037320383203932040320413204232043320443204532046320473204832049320503205132052320533205432055320563205732058320593206032061320623206332064320653206632067320683206932070320713207232073320743207532076320773207832079320803208132082320833208432085320863208732088320893209032091320923209332094320953209632097320983209932100321013210232103321043210532106321073210832109321103211132112321133211432115321163211732118321193212032121321223212332124321253212632127321283212932130321313213232133321343213532136321373213832139321403214132142321433214432145321463214732148321493215032151321523215332154321553215632157321583215932160321613216232163321643216532166321673216832169321703217132172321733217432175321763217732178321793218032181321823218332184321853218632187321883218932190321913219232193321943219532196321973219832199322003220132202322033220432205322063220732208322093221032211322123221332214322153221632217322183221932220322213222232223322243222532226322273222832229322303223132232322333223432235322363223732238322393224032241322423224332244322453224632247322483224932250322513225232253322543225532256322573225832259322603226132262322633226432265322663226732268322693227032271322723227332274322753227632277322783227932280322813228232283322843228532286322873228832289322903229132292322933229432295322963229732298322993230032301323023230332304323053230632307323083230932310323113231232313323143231532316323173231832319323203232132322323233232432325323263232732328323293233032331323323233332334323353233632337323383233932340323413234232343323443234532346323473234832349323503235132352323533235432355323563235732358323593236032361323623236332364323653236632367323683236932370323713237232373323743237532376323773237832379323803238132382323833238432385323863238732388323893239032391323923239332394323953239632397323983239932400324013240232403324043240532406324073240832409324103241132412324133241432415324163241732418324193242032421324223242332424324253242632427324283242932430324313243232433324343243532436324373243832439324403244132442324433244432445324463244732448324493245032451324523245332454324553245632457324583245932460324613246232463324643246532466324673246832469324703247132472324733247432475324763247732478324793248032481324823248332484324853248632487324883248932490324913249232493324943249532496324973249832499325003250132502325033250432505325063250732508325093251032511325123251332514325153251632517325183251932520325213252232523325243252532526325273252832529325303253132532325333253432535325363253732538325393254032541325423254332544325453254632547325483254932550325513255232553325543255532556325573255832559325603256132562325633256432565325663256732568325693257032571325723257332574325753257632577325783257932580325813258232583325843258532586325873258832589325903259132592325933259432595325963259732598325993260032601326023260332604326053260632607326083260932610326113261232613326143261532616326173261832619326203262132622326233262432625326263262732628326293263032631326323263332634326353263632637326383263932640326413264232643326443264532646326473264832649326503265132652326533265432655326563265732658326593266032661326623266332664326653266632667326683266932670326713267232673326743267532676326773267832679326803268132682326833268432685326863268732688326893269032691326923269332694326953269632697326983269932700327013270232703327043270532706327073270832709327103271132712327133271432715327163271732718327193272032721327223272332724327253272632727327283272932730327313273232733327343273532736327373273832739327403274132742327433274432745327463274732748327493275032751327523275332754327553275632757327583275932760327613276232763327643276532766327673276832769327703277132772327733277432775327763277732778327793278032781327823278332784327853278632787327883278932790327913279232793327943279532796327973279832799328003280132802328033280432805328063280732808328093281032811328123281332814328153281632817328183281932820328213282232823328243282532826328273282832829328303283132832328333283432835328363283732838328393284032841328423284332844328453284632847328483284932850328513285232853328543285532856328573285832859328603286132862328633286432865328663286732868328693287032871328723287332874328753287632877328783287932880328813288232883328843288532886328873288832889328903289132892328933289432895328963289732898328993290032901329023290332904329053290632907329083290932910329113291232913329143291532916329173291832919329203292132922329233292432925329263292732928329293293032931329323293332934329353293632937329383293932940329413294232943329443294532946329473294832949329503295132952329533295432955329563295732958329593296032961329623296332964329653296632967329683296932970329713297232973329743297532976329773297832979329803298132982329833298432985329863298732988329893299032991329923299332994329953299632997329983299933000330013300233003330043300533006330073300833009330103301133012330133301433015330163301733018330193302033021330223302333024330253302633027330283302933030330313303233033330343303533036330373303833039330403304133042330433304433045330463304733048330493305033051330523305333054330553305633057330583305933060330613306233063330643306533066330673306833069330703307133072330733307433075330763307733078330793308033081330823308333084330853308633087330883308933090330913309233093330943309533096330973309833099331003310133102331033310433105331063310733108331093311033111331123311333114331153311633117331183311933120331213312233123331243312533126331273312833129331303313133132331333313433135331363313733138331393314033141331423314333144331453314633147331483314933150331513315233153331543315533156331573315833159331603316133162331633316433165331663316733168331693317033171331723317333174331753317633177331783317933180331813318233183331843318533186331873318833189331903319133192331933319433195331963319733198331993320033201332023320333204332053320633207332083320933210332113321233213332143321533216332173321833219332203322133222332233322433225332263322733228332293323033231332323323333234332353323633237332383323933240332413324233243332443324533246332473324833249332503325133252332533325433255332563325733258332593326033261332623326333264332653326633267332683326933270332713327233273332743327533276332773327833279332803328133282332833328433285332863328733288332893329033291332923329333294332953329633297332983329933300333013330233303333043330533306333073330833309333103331133312333133331433315333163331733318333193332033321333223332333324333253332633327333283332933330333313333233333333343333533336333373333833339333403334133342333433334433345333463334733348333493335033351333523335333354333553335633357333583335933360333613336233363333643336533366333673336833369333703337133372333733337433375333763337733378333793338033381333823338333384333853338633387333883338933390333913339233393333943339533396333973339833399334003340133402334033340433405334063340733408334093341033411334123341333414334153341633417334183341933420334213342233423334243342533426334273342833429334303343133432334333343433435334363343733438334393344033441334423344333444334453344633447334483344933450334513345233453334543345533456334573345833459334603346133462334633346433465334663346733468334693347033471334723347333474334753347633477334783347933480334813348233483334843348533486334873348833489334903349133492334933349433495334963349733498334993350033501335023350333504335053350633507335083350933510335113351233513335143351533516335173351833519335203352133522335233352433525335263352733528335293353033531335323353333534335353353633537335383353933540335413354233543335443354533546335473354833549335503355133552335533355433555335563355733558335593356033561335623356333564335653356633567335683356933570335713357233573335743357533576335773357833579335803358133582335833358433585335863358733588335893359033591335923359333594335953359633597335983359933600336013360233603336043360533606336073360833609336103361133612336133361433615336163361733618336193362033621336223362333624336253362633627336283362933630336313363233633336343363533636336373363833639336403364133642336433364433645336463364733648336493365033651336523365333654336553365633657336583365933660336613366233663336643366533666336673366833669336703367133672336733367433675336763367733678336793368033681336823368333684336853368633687336883368933690336913369233693336943369533696336973369833699337003370133702337033370433705337063370733708337093371033711337123371333714337153371633717337183371933720337213372233723337243372533726337273372833729337303373133732337333373433735337363373733738337393374033741337423374333744337453374633747337483374933750337513375233753337543375533756337573375833759337603376133762337633376433765337663376733768337693377033771337723377333774337753377633777337783377933780337813378233783337843378533786337873378833789337903379133792337933379433795337963379733798337993380033801338023380333804338053380633807338083380933810338113381233813338143381533816338173381833819338203382133822338233382433825338263382733828338293383033831338323383333834338353383633837338383383933840338413384233843338443384533846338473384833849338503385133852338533385433855338563385733858338593386033861338623386333864338653386633867338683386933870338713387233873338743387533876338773387833879338803388133882338833388433885338863388733888338893389033891338923389333894338953389633897338983389933900339013390233903339043390533906339073390833909339103391133912339133391433915339163391733918339193392033921339223392333924339253392633927339283392933930339313393233933339343393533936339373393833939339403394133942339433394433945339463394733948339493395033951339523395333954339553395633957339583395933960339613396233963339643396533966339673396833969339703397133972339733397433975339763397733978339793398033981339823398333984339853398633987339883398933990339913399233993339943399533996339973399833999340003400134002340033400434005340063400734008340093401034011340123401334014340153401634017340183401934020340213402234023340243402534026340273402834029340303403134032340333403434035340363403734038340393404034041340423404334044340453404634047340483404934050340513405234053340543405534056340573405834059340603406134062340633406434065340663406734068340693407034071340723407334074340753407634077340783407934080340813408234083340843408534086340873408834089340903409134092340933409434095340963409734098340993410034101341023410334104341053410634107341083410934110341113411234113341143411534116341173411834119341203412134122341233412434125341263412734128341293413034131341323413334134341353413634137341383413934140341413414234143341443414534146341473414834149341503415134152341533415434155341563415734158341593416034161341623416334164341653416634167341683416934170341713417234173341743417534176341773417834179341803418134182341833418434185341863418734188341893419034191341923419334194341953419634197341983419934200342013420234203342043420534206342073420834209342103421134212342133421434215342163421734218342193422034221342223422334224342253422634227342283422934230342313423234233342343423534236342373423834239342403424134242342433424434245342463424734248342493425034251342523425334254342553425634257342583425934260342613426234263342643426534266342673426834269342703427134272342733427434275342763427734278342793428034281342823428334284342853428634287342883428934290342913429234293342943429534296342973429834299343003430134302343033430434305343063430734308343093431034311343123431334314343153431634317343183431934320343213432234323343243432534326343273432834329343303433134332343333433434335343363433734338343393434034341343423434334344343453434634347343483434934350343513435234353343543435534356343573435834359343603436134362343633436434365343663436734368343693437034371343723437334374343753437634377343783437934380343813438234383343843438534386343873438834389343903439134392343933439434395343963439734398343993440034401344023440334404344053440634407344083440934410344113441234413344143441534416344173441834419344203442134422344233442434425344263442734428344293443034431344323443334434344353443634437344383443934440344413444234443344443444534446344473444834449344503445134452344533445434455344563445734458344593446034461344623446334464344653446634467344683446934470344713447234473344743447534476344773447834479344803448134482344833448434485344863448734488344893449034491344923449334494344953449634497344983449934500345013450234503345043450534506345073450834509345103451134512345133451434515345163451734518345193452034521345223452334524345253452634527345283452934530345313453234533345343453534536345373453834539345403454134542345433454434545345463454734548345493455034551345523455334554345553455634557345583455934560345613456234563345643456534566345673456834569345703457134572345733457434575345763457734578345793458034581345823458334584345853458634587345883458934590345913459234593345943459534596345973459834599346003460134602346033460434605346063460734608346093461034611346123461334614346153461634617346183461934620346213462234623346243462534626346273462834629346303463134632346333463434635346363463734638346393464034641346423464334644346453464634647346483464934650346513465234653346543465534656346573465834659346603466134662346633466434665346663466734668346693467034671346723467334674346753467634677346783467934680346813468234683346843468534686346873468834689346903469134692346933469434695346963469734698346993470034701347023470334704347053470634707347083470934710347113471234713347143471534716347173471834719347203472134722347233472434725347263472734728347293473034731347323473334734347353473634737347383473934740347413474234743347443474534746347473474834749347503475134752347533475434755347563475734758347593476034761347623476334764347653476634767347683476934770347713477234773347743477534776347773477834779347803478134782347833478434785347863478734788347893479034791347923479334794347953479634797347983479934800348013480234803348043480534806348073480834809348103481134812348133481434815348163481734818348193482034821348223482334824348253482634827348283482934830348313483234833348343483534836348373483834839348403484134842348433484434845348463484734848348493485034851348523485334854348553485634857348583485934860348613486234863348643486534866348673486834869348703487134872348733487434875348763487734878348793488034881348823488334884348853488634887348883488934890348913489234893348943489534896348973489834899349003490134902349033490434905349063490734908349093491034911349123491334914349153491634917349183491934920349213492234923349243492534926349273492834929349303493134932349333493434935349363493734938349393494034941349423494334944349453494634947349483494934950349513495234953349543495534956349573495834959349603496134962349633496434965349663496734968349693497034971349723497334974349753497634977349783497934980349813498234983349843498534986349873498834989349903499134992349933499434995349963499734998349993500035001350023500335004350053500635007350083500935010350113501235013350143501535016350173501835019350203502135022350233502435025350263502735028350293503035031350323503335034350353503635037350383503935040350413504235043350443504535046350473504835049350503505135052350533505435055350563505735058350593506035061350623506335064350653506635067350683506935070350713507235073350743507535076350773507835079350803508135082350833508435085350863508735088350893509035091350923509335094350953509635097350983509935100351013510235103351043510535106351073510835109351103511135112351133511435115351163511735118351193512035121351223512335124351253512635127351283512935130351313513235133351343513535136351373513835139351403514135142351433514435145351463514735148351493515035151351523515335154351553515635157351583515935160351613516235163351643516535166351673516835169351703517135172351733517435175351763517735178351793518035181351823518335184351853518635187351883518935190351913519235193351943519535196351973519835199352003520135202352033520435205352063520735208352093521035211352123521335214352153521635217352183521935220352213522235223352243522535226352273522835229352303523135232352333523435235352363523735238352393524035241352423524335244352453524635247352483524935250352513525235253352543525535256352573525835259352603526135262352633526435265352663526735268352693527035271352723527335274352753527635277352783527935280352813528235283352843528535286352873528835289352903529135292352933529435295352963529735298352993530035301353023530335304353053530635307353083530935310353113531235313353143531535316353173531835319353203532135322353233532435325353263532735328353293533035331353323533335334353353533635337353383533935340353413534235343353443534535346353473534835349353503535135352353533535435355353563535735358353593536035361353623536335364353653536635367353683536935370353713537235373353743537535376353773537835379353803538135382353833538435385353863538735388353893539035391353923539335394353953539635397353983539935400354013540235403354043540535406354073540835409354103541135412354133541435415354163541735418354193542035421354223542335424354253542635427354283542935430354313543235433354343543535436354373543835439354403544135442354433544435445354463544735448354493545035451354523545335454354553545635457354583545935460354613546235463354643546535466354673546835469354703547135472354733547435475354763547735478354793548035481354823548335484354853548635487354883548935490354913549235493354943549535496354973549835499355003550135502355033550435505355063550735508355093551035511355123551335514355153551635517355183551935520355213552235523355243552535526355273552835529355303553135532355333553435535355363553735538355393554035541355423554335544355453554635547355483554935550355513555235553355543555535556355573555835559355603556135562355633556435565355663556735568355693557035571355723557335574355753557635577355783557935580355813558235583355843558535586355873558835589355903559135592355933559435595355963559735598355993560035601356023560335604356053560635607356083560935610356113561235613356143561535616356173561835619356203562135622356233562435625356263562735628356293563035631356323563335634356353563635637356383563935640356413564235643356443564535646356473564835649356503565135652356533565435655356563565735658356593566035661356623566335664356653566635667356683566935670356713567235673356743567535676356773567835679356803568135682356833568435685356863568735688356893569035691356923569335694356953569635697356983569935700357013570235703357043570535706357073570835709357103571135712357133571435715357163571735718357193572035721357223572335724357253572635727357283572935730357313573235733357343573535736357373573835739357403574135742357433574435745357463574735748357493575035751357523575335754357553575635757357583575935760357613576235763357643576535766357673576835769357703577135772357733577435775357763577735778357793578035781357823578335784357853578635787357883578935790357913579235793357943579535796357973579835799358003580135802358033580435805358063580735808358093581035811358123581335814358153581635817358183581935820358213582235823358243582535826358273582835829358303583135832358333583435835358363583735838358393584035841358423584335844358453584635847358483584935850358513585235853358543585535856358573585835859358603586135862358633586435865358663586735868358693587035871358723587335874358753587635877358783587935880358813588235883358843588535886358873588835889358903589135892358933589435895358963589735898358993590035901359023590335904359053590635907359083590935910359113591235913359143591535916359173591835919359203592135922359233592435925359263592735928359293593035931359323593335934359353593635937359383593935940359413594235943359443594535946359473594835949359503595135952359533595435955359563595735958359593596035961359623596335964359653596635967359683596935970359713597235973359743597535976359773597835979359803598135982359833598435985359863598735988359893599035991359923599335994359953599635997359983599936000360013600236003360043600536006360073600836009360103601136012360133601436015360163601736018360193602036021360223602336024360253602636027360283602936030360313603236033360343603536036360373603836039360403604136042360433604436045360463604736048360493605036051360523605336054360553605636057360583605936060360613606236063360643606536066360673606836069360703607136072360733607436075360763607736078360793608036081360823608336084360853608636087360883608936090360913609236093360943609536096360973609836099361003610136102361033610436105361063610736108361093611036111361123611336114361153611636117361183611936120361213612236123361243612536126361273612836129361303613136132361333613436135361363613736138361393614036141361423614336144361453614636147361483614936150361513615236153361543615536156361573615836159361603616136162361633616436165361663616736168361693617036171361723617336174361753617636177361783617936180361813618236183361843618536186361873618836189361903619136192361933619436195361963619736198361993620036201362023620336204362053620636207362083620936210362113621236213362143621536216362173621836219362203622136222362233622436225362263622736228362293623036231362323623336234362353623636237362383623936240362413624236243362443624536246362473624836249362503625136252362533625436255362563625736258362593626036261362623626336264362653626636267362683626936270362713627236273362743627536276362773627836279362803628136282362833628436285362863628736288362893629036291362923629336294362953629636297362983629936300363013630236303363043630536306363073630836309363103631136312363133631436315363163631736318363193632036321363223632336324363253632636327363283632936330363313633236333363343633536336363373633836339363403634136342363433634436345363463634736348363493635036351363523635336354363553635636357363583635936360363613636236363363643636536366363673636836369363703637136372363733637436375363763637736378363793638036381363823638336384363853638636387363883638936390363913639236393363943639536396363973639836399364003640136402364033640436405364063640736408364093641036411364123641336414364153641636417364183641936420364213642236423364243642536426364273642836429364303643136432364333643436435364363643736438364393644036441364423644336444364453644636447364483644936450364513645236453364543645536456364573645836459364603646136462364633646436465364663646736468364693647036471364723647336474364753647636477364783647936480364813648236483364843648536486364873648836489364903649136492364933649436495364963649736498364993650036501365023650336504365053650636507365083650936510365113651236513365143651536516365173651836519365203652136522365233652436525365263652736528365293653036531365323653336534365353653636537365383653936540365413654236543365443654536546365473654836549365503655136552365533655436555365563655736558365593656036561365623656336564365653656636567365683656936570365713657236573365743657536576365773657836579365803658136582365833658436585365863658736588365893659036591365923659336594365953659636597365983659936600366013660236603366043660536606366073660836609366103661136612366133661436615366163661736618366193662036621366223662336624366253662636627366283662936630366313663236633366343663536636366373663836639366403664136642366433664436645366463664736648366493665036651366523665336654366553665636657366583665936660366613666236663366643666536666366673666836669366703667136672366733667436675366763667736678366793668036681366823668336684366853668636687366883668936690366913669236693366943669536696366973669836699367003670136702367033670436705367063670736708367093671036711367123671336714367153671636717367183671936720367213672236723367243672536726367273672836729367303673136732367333673436735367363673736738367393674036741367423674336744367453674636747367483674936750367513675236753367543675536756367573675836759367603676136762367633676436765367663676736768367693677036771367723677336774367753677636777367783677936780367813678236783367843678536786367873678836789367903679136792367933679436795367963679736798367993680036801368023680336804368053680636807368083680936810368113681236813368143681536816368173681836819368203682136822368233682436825368263682736828368293683036831368323683336834368353683636837368383683936840368413684236843368443684536846368473684836849368503685136852368533685436855368563685736858368593686036861368623686336864368653686636867368683686936870368713687236873368743687536876368773687836879368803688136882368833688436885368863688736888368893689036891368923689336894368953689636897368983689936900369013690236903369043690536906369073690836909369103691136912369133691436915369163691736918369193692036921369223692336924369253692636927369283692936930369313693236933369343693536936369373693836939369403694136942369433694436945369463694736948369493695036951369523695336954369553695636957369583695936960369613696236963369643696536966369673696836969369703697136972369733697436975369763697736978369793698036981369823698336984369853698636987369883698936990369913699236993369943699536996369973699836999370003700137002370033700437005370063700737008370093701037011370123701337014370153701637017370183701937020370213702237023370243702537026370273702837029370303703137032370333703437035370363703737038370393704037041370423704337044370453704637047370483704937050370513705237053370543705537056370573705837059370603706137062370633706437065370663706737068370693707037071370723707337074370753707637077370783707937080370813708237083370843708537086370873708837089370903709137092370933709437095370963709737098370993710037101371023710337104371053710637107371083710937110371113711237113371143711537116371173711837119371203712137122371233712437125371263712737128371293713037131371323713337134371353713637137371383713937140371413714237143371443714537146371473714837149371503715137152371533715437155371563715737158371593716037161371623716337164371653716637167371683716937170371713717237173371743717537176371773717837179371803718137182371833718437185371863718737188371893719037191371923719337194371953719637197371983719937200372013720237203372043720537206372073720837209372103721137212372133721437215372163721737218372193722037221372223722337224372253722637227372283722937230372313723237233372343723537236372373723837239372403724137242372433724437245372463724737248372493725037251372523725337254372553725637257372583725937260372613726237263372643726537266372673726837269372703727137272372733727437275372763727737278372793728037281372823728337284372853728637287372883728937290372913729237293372943729537296372973729837299373003730137302373033730437305373063730737308373093731037311373123731337314373153731637317373183731937320373213732237323373243732537326373273732837329373303733137332373333733437335373363733737338373393734037341373423734337344373453734637347373483734937350373513735237353373543735537356373573735837359373603736137362373633736437365373663736737368373693737037371373723737337374373753737637377373783737937380373813738237383373843738537386373873738837389373903739137392373933739437395373963739737398373993740037401374023740337404374053740637407374083740937410374113741237413374143741537416374173741837419374203742137422374233742437425374263742737428374293743037431374323743337434374353743637437374383743937440374413744237443374443744537446374473744837449374503745137452374533745437455374563745737458374593746037461374623746337464374653746637467374683746937470374713747237473374743747537476374773747837479374803748137482374833748437485374863748737488374893749037491374923749337494374953749637497374983749937500375013750237503375043750537506375073750837509375103751137512375133751437515375163751737518375193752037521375223752337524375253752637527375283752937530375313753237533375343753537536375373753837539375403754137542375433754437545375463754737548375493755037551375523755337554375553755637557375583755937560375613756237563375643756537566375673756837569375703757137572375733757437575375763757737578375793758037581375823758337584375853758637587375883758937590375913759237593375943759537596375973759837599376003760137602376033760437605376063760737608376093761037611376123761337614376153761637617376183761937620376213762237623376243762537626376273762837629376303763137632376333763437635376363763737638376393764037641376423764337644376453764637647376483764937650376513765237653376543765537656376573765837659376603766137662376633766437665376663766737668376693767037671376723767337674376753767637677376783767937680376813768237683376843768537686376873768837689376903769137692376933769437695376963769737698376993770037701377023770337704377053770637707377083770937710377113771237713377143771537716377173771837719377203772137722377233772437725377263772737728377293773037731377323773337734377353773637737377383773937740377413774237743377443774537746377473774837749377503775137752377533775437755377563775737758377593776037761377623776337764377653776637767377683776937770377713777237773377743777537776377773777837779377803778137782377833778437785377863778737788377893779037791377923779337794377953779637797377983779937800378013780237803378043780537806378073780837809378103781137812378133781437815378163781737818378193782037821378223782337824378253782637827378283782937830378313783237833378343783537836378373783837839378403784137842378433784437845378463784737848378493785037851378523785337854378553785637857378583785937860378613786237863378643786537866378673786837869378703787137872378733787437875378763787737878378793788037881378823788337884378853788637887378883788937890378913789237893378943789537896378973789837899379003790137902379033790437905379063790737908379093791037911379123791337914379153791637917379183791937920379213792237923379243792537926379273792837929379303793137932379333793437935379363793737938379393794037941379423794337944379453794637947379483794937950379513795237953379543795537956379573795837959379603796137962379633796437965379663796737968379693797037971379723797337974379753797637977379783797937980379813798237983379843798537986379873798837989379903799137992379933799437995379963799737998379993800038001380023800338004380053800638007380083800938010380113801238013380143801538016380173801838019380203802138022380233802438025380263802738028380293803038031380323803338034380353803638037380383803938040380413804238043380443804538046380473804838049380503805138052380533805438055380563805738058380593806038061380623806338064380653806638067380683806938070380713807238073380743807538076380773807838079380803808138082380833808438085380863808738088380893809038091380923809338094380953809638097380983809938100381013810238103381043810538106381073810838109381103811138112381133811438115381163811738118381193812038121381223812338124381253812638127381283812938130381313813238133381343813538136381373813838139381403814138142381433814438145381463814738148381493815038151381523815338154381553815638157381583815938160381613816238163381643816538166381673816838169381703817138172381733817438175381763817738178381793818038181381823818338184381853818638187381883818938190381913819238193381943819538196381973819838199382003820138202382033820438205382063820738208382093821038211382123821338214382153821638217382183821938220382213822238223382243822538226382273822838229382303823138232382333823438235382363823738238382393824038241382423824338244382453824638247382483824938250382513825238253382543825538256382573825838259382603826138262382633826438265382663826738268382693827038271382723827338274382753827638277382783827938280382813828238283382843828538286382873828838289382903829138292382933829438295382963829738298382993830038301383023830338304383053830638307383083830938310383113831238313383143831538316383173831838319383203832138322383233832438325383263832738328383293833038331383323833338334383353833638337383383833938340383413834238343383443834538346383473834838349383503835138352383533835438355383563835738358383593836038361383623836338364383653836638367383683836938370383713837238373383743837538376383773837838379383803838138382383833838438385383863838738388383893839038391383923839338394383953839638397383983839938400384013840238403384043840538406384073840838409384103841138412384133841438415384163841738418384193842038421384223842338424384253842638427384283842938430384313843238433384343843538436384373843838439384403844138442384433844438445384463844738448384493845038451384523845338454384553845638457384583845938460384613846238463384643846538466384673846838469384703847138472384733847438475384763847738478384793848038481384823848338484384853848638487384883848938490384913849238493384943849538496384973849838499385003850138502385033850438505385063850738508385093851038511385123851338514385153851638517385183851938520385213852238523385243852538526385273852838529385303853138532385333853438535385363853738538385393854038541385423854338544385453854638547385483854938550385513855238553385543855538556385573855838559385603856138562385633856438565385663856738568385693857038571385723857338574385753857638577385783857938580385813858238583385843858538586385873858838589385903859138592385933859438595385963859738598385993860038601386023860338604386053860638607386083860938610386113861238613386143861538616386173861838619386203862138622386233862438625386263862738628386293863038631386323863338634386353863638637386383863938640386413864238643386443864538646386473864838649386503865138652386533865438655386563865738658386593866038661386623866338664386653866638667386683866938670386713867238673386743867538676386773867838679386803868138682386833868438685386863868738688386893869038691386923869338694386953869638697386983869938700387013870238703387043870538706387073870838709387103871138712387133871438715387163871738718387193872038721387223872338724387253872638727387283872938730387313873238733387343873538736387373873838739387403874138742387433874438745387463874738748387493875038751387523875338754387553875638757387583875938760387613876238763387643876538766387673876838769387703877138772387733877438775387763877738778387793878038781387823878338784387853878638787387883878938790387913879238793387943879538796387973879838799388003880138802388033880438805388063880738808388093881038811388123881338814388153881638817388183881938820388213882238823388243882538826388273882838829388303883138832388333883438835388363883738838388393884038841388423884338844388453884638847388483884938850388513885238853388543885538856388573885838859388603886138862388633886438865388663886738868388693887038871388723887338874388753887638877388783887938880388813888238883388843888538886388873888838889388903889138892388933889438895388963889738898388993890038901389023890338904389053890638907389083890938910389113891238913389143891538916389173891838919389203892138922389233892438925389263892738928389293893038931389323893338934389353893638937389383893938940389413894238943389443894538946389473894838949389503895138952389533895438955389563895738958389593896038961389623896338964389653896638967389683896938970389713897238973389743897538976389773897838979389803898138982389833898438985389863898738988389893899038991389923899338994389953899638997389983899939000390013900239003390043900539006390073900839009390103901139012390133901439015390163901739018390193902039021390223902339024390253902639027390283902939030390313903239033390343903539036390373903839039390403904139042390433904439045390463904739048390493905039051390523905339054390553905639057390583905939060390613906239063390643906539066390673906839069390703907139072390733907439075390763907739078390793908039081390823908339084390853908639087390883908939090390913909239093390943909539096390973909839099391003910139102391033910439105391063910739108391093911039111391123911339114391153911639117391183911939120391213912239123391243912539126391273912839129391303913139132391333913439135391363913739138391393914039141391423914339144391453914639147391483914939150391513915239153391543915539156391573915839159391603916139162391633916439165391663916739168391693917039171391723917339174391753917639177391783917939180391813918239183391843918539186391873918839189391903919139192391933919439195391963919739198391993920039201392023920339204392053920639207392083920939210392113921239213392143921539216392173921839219392203922139222392233922439225392263922739228392293923039231392323923339234392353923639237392383923939240392413924239243392443924539246392473924839249392503925139252392533925439255392563925739258392593926039261392623926339264392653926639267392683926939270392713927239273392743927539276392773927839279392803928139282392833928439285392863928739288392893929039291392923929339294392953929639297392983929939300393013930239303393043930539306393073930839309393103931139312393133931439315393163931739318393193932039321393223932339324393253932639327393283932939330393313933239333393343933539336393373933839339393403934139342393433934439345393463934739348393493935039351393523935339354393553935639357393583935939360393613936239363393643936539366393673936839369393703937139372393733937439375393763937739378393793938039381393823938339384393853938639387393883938939390393913939239393393943939539396393973939839399394003940139402394033940439405394063940739408394093941039411394123941339414394153941639417394183941939420394213942239423394243942539426394273942839429394303943139432394333943439435394363943739438394393944039441394423944339444394453944639447394483944939450394513945239453394543945539456394573945839459394603946139462394633946439465394663946739468394693947039471394723947339474394753947639477394783947939480394813948239483394843948539486394873948839489394903949139492394933949439495394963949739498394993950039501395023950339504395053950639507395083950939510395113951239513395143951539516395173951839519395203952139522395233952439525395263952739528395293953039531395323953339534395353953639537395383953939540395413954239543395443954539546395473954839549395503955139552395533955439555395563955739558395593956039561395623956339564395653956639567395683956939570395713957239573395743957539576395773957839579395803958139582395833958439585395863958739588395893959039591395923959339594395953959639597395983959939600396013960239603396043960539606396073960839609396103961139612396133961439615396163961739618396193962039621396223962339624396253962639627396283962939630396313963239633396343963539636396373963839639396403964139642396433964439645396463964739648396493965039651396523965339654396553965639657396583965939660396613966239663396643966539666396673966839669396703967139672396733967439675396763967739678396793968039681396823968339684396853968639687396883968939690396913969239693396943969539696396973969839699397003970139702397033970439705397063970739708397093971039711397123971339714397153971639717397183971939720397213972239723397243972539726397273972839729397303973139732397333973439735397363973739738397393974039741397423974339744397453974639747397483974939750397513975239753397543975539756397573975839759397603976139762397633976439765397663976739768397693977039771397723977339774397753977639777397783977939780397813978239783397843978539786397873978839789397903979139792397933979439795397963979739798397993980039801398023980339804398053980639807398083980939810398113981239813398143981539816398173981839819398203982139822398233982439825398263982739828398293983039831398323983339834398353983639837398383983939840398413984239843398443984539846398473984839849398503985139852398533985439855398563985739858398593986039861398623986339864398653986639867398683986939870398713987239873398743987539876398773987839879398803988139882398833988439885398863988739888398893989039891398923989339894398953989639897398983989939900399013990239903399043990539906399073990839909399103991139912399133991439915399163991739918399193992039921399223992339924399253992639927399283992939930399313993239933399343993539936399373993839939399403994139942399433994439945399463994739948399493995039951399523995339954399553995639957399583995939960399613996239963399643996539966399673996839969399703997139972399733997439975399763997739978399793998039981399823998339984399853998639987399883998939990399913999239993399943999539996399973999839999400004000140002400034000440005400064000740008400094001040011400124001340014400154001640017400184001940020400214002240023400244002540026400274002840029400304003140032400334003440035400364003740038400394004040041400424004340044400454004640047400484004940050400514005240053400544005540056400574005840059400604006140062400634006440065400664006740068400694007040071400724007340074400754007640077400784007940080400814008240083400844008540086400874008840089400904009140092400934009440095400964009740098400994010040101401024010340104401054010640107401084010940110401114011240113401144011540116401174011840119401204012140122401234012440125401264012740128401294013040131401324013340134401354013640137401384013940140401414014240143401444014540146401474014840149401504015140152401534015440155401564015740158401594016040161401624016340164401654016640167401684016940170401714017240173401744017540176401774017840179401804018140182401834018440185401864018740188401894019040191401924019340194401954019640197401984019940200402014020240203402044020540206402074020840209402104021140212402134021440215402164021740218402194022040221402224022340224402254022640227402284022940230402314023240233402344023540236402374023840239402404024140242402434024440245402464024740248402494025040251402524025340254402554025640257402584025940260402614026240263402644026540266402674026840269402704027140272402734027440275402764027740278402794028040281402824028340284402854028640287402884028940290402914029240293402944029540296402974029840299403004030140302403034030440305403064030740308403094031040311403124031340314403154031640317403184031940320403214032240323403244032540326403274032840329403304033140332403334033440335403364033740338403394034040341403424034340344403454034640347403484034940350403514035240353403544035540356403574035840359403604036140362403634036440365403664036740368403694037040371403724037340374403754037640377403784037940380403814038240383403844038540386403874038840389403904039140392403934039440395403964039740398403994040040401404024040340404404054040640407404084040940410404114041240413404144041540416404174041840419404204042140422404234042440425404264042740428404294043040431404324043340434404354043640437404384043940440404414044240443404444044540446404474044840449404504045140452404534045440455404564045740458404594046040461404624046340464404654046640467404684046940470404714047240473404744047540476404774047840479404804048140482404834048440485404864048740488404894049040491404924049340494404954049640497404984049940500405014050240503405044050540506405074050840509405104051140512405134051440515405164051740518405194052040521405224052340524405254052640527405284052940530405314053240533405344053540536405374053840539405404054140542405434054440545405464054740548405494055040551405524055340554405554055640557405584055940560405614056240563405644056540566405674056840569405704057140572405734057440575405764057740578405794058040581405824058340584405854058640587405884058940590405914059240593405944059540596405974059840599406004060140602406034060440605406064060740608406094061040611406124061340614406154061640617406184061940620406214062240623406244062540626406274062840629406304063140632406334063440635406364063740638406394064040641406424064340644406454064640647406484064940650406514065240653406544065540656406574065840659406604066140662406634066440665406664066740668406694067040671406724067340674406754067640677406784067940680406814068240683406844068540686406874068840689406904069140692406934069440695406964069740698406994070040701407024070340704407054070640707407084070940710407114071240713407144071540716407174071840719407204072140722407234072440725407264072740728407294073040731407324073340734407354073640737407384073940740407414074240743407444074540746407474074840749407504075140752407534075440755407564075740758407594076040761407624076340764407654076640767407684076940770407714077240773407744077540776407774077840779407804078140782407834078440785407864078740788407894079040791407924079340794407954079640797407984079940800408014080240803408044080540806408074080840809408104081140812408134081440815408164081740818408194082040821408224082340824408254082640827408284082940830408314083240833408344083540836408374083840839408404084140842408434084440845408464084740848408494085040851408524085340854408554085640857408584085940860408614086240863408644086540866408674086840869408704087140872408734087440875408764087740878408794088040881408824088340884408854088640887408884088940890408914089240893408944089540896408974089840899409004090140902409034090440905409064090740908409094091040911409124091340914409154091640917409184091940920409214092240923409244092540926409274092840929409304093140932409334093440935409364093740938409394094040941409424094340944409454094640947409484094940950409514095240953409544095540956409574095840959409604096140962409634096440965409664096740968409694097040971409724097340974409754097640977409784097940980409814098240983409844098540986409874098840989409904099140992409934099440995409964099740998409994100041001410024100341004410054100641007410084100941010410114101241013410144101541016410174101841019410204102141022410234102441025410264102741028410294103041031410324103341034410354103641037410384103941040410414104241043410444104541046410474104841049410504105141052410534105441055410564105741058410594106041061410624106341064410654106641067410684106941070410714107241073410744107541076410774107841079410804108141082410834108441085410864108741088410894109041091410924109341094410954109641097410984109941100411014110241103411044110541106411074110841109411104111141112411134111441115411164111741118411194112041121411224112341124411254112641127411284112941130411314113241133411344113541136411374113841139411404114141142411434114441145411464114741148411494115041151411524115341154411554115641157411584115941160411614116241163411644116541166411674116841169411704117141172411734117441175411764117741178411794118041181411824118341184411854118641187411884118941190411914119241193411944119541196411974119841199412004120141202412034120441205412064120741208412094121041211412124121341214412154121641217412184121941220412214122241223412244122541226412274122841229412304123141232412334123441235412364123741238412394124041241412424124341244412454124641247412484124941250412514125241253412544125541256412574125841259412604126141262412634126441265412664126741268412694127041271412724127341274412754127641277412784127941280412814128241283412844128541286412874128841289412904129141292412934129441295412964129741298412994130041301413024130341304413054130641307413084130941310413114131241313413144131541316413174131841319413204132141322413234132441325413264132741328413294133041331413324133341334413354133641337413384133941340413414134241343413444134541346413474134841349413504135141352413534135441355413564135741358413594136041361413624136341364413654136641367413684136941370413714137241373413744137541376413774137841379413804138141382413834138441385413864138741388413894139041391413924139341394413954139641397413984139941400414014140241403414044140541406414074140841409414104141141412414134141441415414164141741418414194142041421414224142341424414254142641427414284142941430414314143241433414344143541436414374143841439414404144141442414434144441445414464144741448414494145041451414524145341454414554145641457414584145941460414614146241463414644146541466414674146841469414704147141472414734147441475414764147741478414794148041481414824148341484414854148641487414884148941490414914149241493414944149541496414974149841499415004150141502415034150441505415064150741508415094151041511415124151341514415154151641517415184151941520415214152241523415244152541526415274152841529415304153141532415334153441535415364153741538415394154041541415424154341544415454154641547415484154941550415514155241553415544155541556415574155841559415604156141562415634156441565415664156741568415694157041571415724157341574415754157641577415784157941580415814158241583415844158541586415874158841589415904159141592415934159441595415964159741598415994160041601416024160341604416054160641607416084160941610416114161241613416144161541616416174161841619416204162141622416234162441625416264162741628416294163041631416324163341634416354163641637416384163941640416414164241643416444164541646416474164841649416504165141652416534165441655416564165741658416594166041661416624166341664416654166641667416684166941670416714167241673416744167541676416774167841679416804168141682416834168441685416864168741688416894169041691416924169341694416954169641697416984169941700417014170241703417044170541706417074170841709417104171141712417134171441715417164171741718417194172041721417224172341724417254172641727417284172941730417314173241733417344173541736417374173841739417404174141742417434174441745417464174741748417494175041751417524175341754417554175641757417584175941760417614176241763417644176541766417674176841769417704177141772417734177441775417764177741778417794178041781417824178341784417854178641787417884178941790417914179241793417944179541796417974179841799418004180141802418034180441805418064180741808418094181041811418124181341814418154181641817418184181941820418214182241823418244182541826418274182841829418304183141832418334183441835418364183741838418394184041841418424184341844418454184641847418484184941850418514185241853418544185541856418574185841859418604186141862418634186441865418664186741868418694187041871418724187341874418754187641877418784187941880418814188241883418844188541886418874188841889418904189141892418934189441895418964189741898418994190041901419024190341904419054190641907419084190941910419114191241913419144191541916419174191841919419204192141922419234192441925419264192741928419294193041931419324193341934419354193641937419384193941940419414194241943419444194541946419474194841949419504195141952419534195441955419564195741958419594196041961419624196341964419654196641967419684196941970419714197241973419744197541976419774197841979419804198141982419834198441985419864198741988419894199041991419924199341994419954199641997419984199942000420014200242003420044200542006420074200842009420104201142012420134201442015420164201742018420194202042021420224202342024420254202642027420284202942030420314203242033420344203542036420374203842039420404204142042420434204442045420464204742048420494205042051420524205342054420554205642057420584205942060420614206242063420644206542066420674206842069420704207142072420734207442075420764207742078420794208042081420824208342084420854208642087420884208942090420914209242093420944209542096420974209842099421004210142102421034210442105421064210742108421094211042111421124211342114421154211642117421184211942120421214212242123421244212542126421274212842129421304213142132421334213442135421364213742138421394214042141421424214342144421454214642147421484214942150421514215242153421544215542156421574215842159421604216142162421634216442165421664216742168421694217042171421724217342174421754217642177421784217942180421814218242183421844218542186421874218842189421904219142192421934219442195421964219742198421994220042201422024220342204422054220642207422084220942210422114221242213422144221542216422174221842219422204222142222422234222442225422264222742228422294223042231422324223342234422354223642237422384223942240422414224242243422444224542246422474224842249422504225142252422534225442255422564225742258422594226042261422624226342264422654226642267422684226942270422714227242273422744227542276422774227842279422804228142282422834228442285422864228742288422894229042291422924229342294422954229642297422984229942300423014230242303423044230542306423074230842309423104231142312423134231442315423164231742318423194232042321423224232342324423254232642327423284232942330423314233242333423344233542336423374233842339423404234142342423434234442345423464234742348423494235042351423524235342354423554235642357423584235942360423614236242363423644236542366423674236842369423704237142372423734237442375423764237742378423794238042381423824238342384423854238642387423884238942390423914239242393423944239542396423974239842399424004240142402424034240442405424064240742408424094241042411424124241342414424154241642417424184241942420424214242242423424244242542426424274242842429424304243142432424334243442435424364243742438424394244042441424424244342444424454244642447424484244942450424514245242453424544245542456424574245842459424604246142462424634246442465424664246742468424694247042471424724247342474424754247642477424784247942480424814248242483424844248542486424874248842489424904249142492424934249442495424964249742498424994250042501425024250342504425054250642507425084250942510425114251242513425144251542516425174251842519425204252142522425234252442525425264252742528425294253042531425324253342534425354253642537425384253942540425414254242543425444254542546425474254842549425504255142552425534255442555425564255742558425594256042561425624256342564425654256642567425684256942570425714257242573425744257542576425774257842579425804258142582425834258442585425864258742588425894259042591425924259342594425954259642597425984259942600426014260242603426044260542606426074260842609426104261142612426134261442615426164261742618426194262042621426224262342624426254262642627426284262942630426314263242633426344263542636426374263842639426404264142642426434264442645426464264742648426494265042651426524265342654426554265642657426584265942660426614266242663426644266542666426674266842669426704267142672426734267442675426764267742678426794268042681426824268342684426854268642687426884268942690426914269242693426944269542696426974269842699427004270142702427034270442705427064270742708427094271042711427124271342714427154271642717427184271942720427214272242723427244272542726427274272842729427304273142732427334273442735427364273742738427394274042741427424274342744427454274642747427484274942750427514275242753427544275542756427574275842759427604276142762427634276442765427664276742768427694277042771427724277342774427754277642777427784277942780427814278242783427844278542786427874278842789427904279142792427934279442795427964279742798427994280042801428024280342804428054280642807428084280942810428114281242813428144281542816428174281842819428204282142822428234282442825428264282742828428294283042831428324283342834428354283642837428384283942840428414284242843428444284542846428474284842849428504285142852428534285442855428564285742858428594286042861428624286342864428654286642867428684286942870428714287242873428744287542876428774287842879428804288142882428834288442885428864288742888428894289042891428924289342894428954289642897428984289942900429014290242903429044290542906429074290842909429104291142912429134291442915429164291742918429194292042921429224292342924429254292642927429284292942930429314293242933429344293542936429374293842939429404294142942429434294442945429464294742948429494295042951429524295342954429554295642957429584295942960429614296242963429644296542966429674296842969429704297142972429734297442975429764297742978429794298042981429824298342984429854298642987429884298942990429914299242993429944299542996429974299842999430004300143002430034300443005430064300743008430094301043011430124301343014430154301643017430184301943020430214302243023430244302543026430274302843029430304303143032430334303443035430364303743038430394304043041430424304343044430454304643047430484304943050430514305243053430544305543056430574305843059430604306143062430634306443065430664306743068430694307043071430724307343074430754307643077430784307943080430814308243083430844308543086430874308843089430904309143092430934309443095430964309743098430994310043101431024310343104431054310643107431084310943110431114311243113431144311543116431174311843119431204312143122431234312443125431264312743128431294313043131431324313343134431354313643137431384313943140431414314243143431444314543146431474314843149431504315143152431534315443155431564315743158431594316043161431624316343164431654316643167431684316943170431714317243173431744317543176431774317843179431804318143182431834318443185431864318743188431894319043191431924319343194431954319643197431984319943200432014320243203432044320543206432074320843209432104321143212432134321443215432164321743218432194322043221432224322343224432254322643227432284322943230432314323243233432344323543236432374323843239432404324143242432434324443245432464324743248432494325043251432524325343254432554325643257432584325943260432614326243263432644326543266432674326843269432704327143272432734327443275432764327743278432794328043281432824328343284432854328643287432884328943290432914329243293432944329543296432974329843299433004330143302433034330443305433064330743308433094331043311433124331343314433154331643317433184331943320433214332243323433244332543326433274332843329433304333143332433334333443335433364333743338433394334043341433424334343344433454334643347433484334943350433514335243353433544335543356433574335843359433604336143362433634336443365433664336743368433694337043371433724337343374433754337643377433784337943380433814338243383433844338543386433874338843389433904339143392433934339443395433964339743398433994340043401434024340343404434054340643407434084340943410434114341243413434144341543416434174341843419434204342143422434234342443425434264342743428434294343043431434324343343434434354343643437434384343943440434414344243443434444344543446434474344843449434504345143452434534345443455434564345743458434594346043461434624346343464434654346643467434684346943470434714347243473434744347543476434774347843479434804348143482434834348443485434864348743488434894349043491434924349343494434954349643497434984349943500435014350243503435044350543506435074350843509435104351143512435134351443515435164351743518435194352043521435224352343524435254352643527435284352943530435314353243533435344353543536435374353843539435404354143542435434354443545435464354743548435494355043551435524355343554435554355643557435584355943560435614356243563435644356543566435674356843569435704357143572435734357443575435764357743578435794358043581435824358343584435854358643587435884358943590435914359243593435944359543596435974359843599436004360143602436034360443605436064360743608436094361043611436124361343614436154361643617436184361943620436214362243623436244362543626436274362843629436304363143632436334363443635436364363743638436394364043641436424364343644436454364643647436484364943650436514365243653436544365543656436574365843659436604366143662436634366443665436664366743668436694367043671436724367343674436754367643677436784367943680436814368243683436844368543686436874368843689436904369143692436934369443695436964369743698436994370043701437024370343704437054370643707437084370943710437114371243713437144371543716437174371843719437204372143722437234372443725437264372743728437294373043731437324373343734437354373643737437384373943740437414374243743437444374543746437474374843749437504375143752437534375443755437564375743758437594376043761437624376343764437654376643767437684376943770437714377243773437744377543776437774377843779437804378143782437834378443785437864378743788437894379043791437924379343794437954379643797437984379943800438014380243803438044380543806438074380843809438104381143812438134381443815438164381743818438194382043821438224382343824438254382643827438284382943830438314383243833438344383543836438374383843839438404384143842438434384443845438464384743848438494385043851438524385343854438554385643857438584385943860438614386243863438644386543866438674386843869438704387143872438734387443875438764387743878438794388043881438824388343884438854388643887438884388943890438914389243893438944389543896438974389843899439004390143902439034390443905439064390743908439094391043911439124391343914439154391643917439184391943920439214392243923439244392543926439274392843929439304393143932439334393443935439364393743938439394394043941439424394343944439454394643947439484394943950439514395243953439544395543956439574395843959439604396143962439634396443965439664396743968439694397043971439724397343974439754397643977439784397943980439814398243983439844398543986439874398843989439904399143992439934399443995439964399743998439994400044001440024400344004440054400644007440084400944010440114401244013440144401544016440174401844019440204402144022440234402444025440264402744028440294403044031440324403344034440354403644037440384403944040440414404244043440444404544046440474404844049440504405144052440534405444055440564405744058440594406044061440624406344064440654406644067440684406944070440714407244073440744407544076440774407844079440804408144082440834408444085440864408744088440894409044091440924409344094440954409644097440984409944100441014410244103441044410544106441074410844109441104411144112441134411444115441164411744118441194412044121441224412344124441254412644127441284412944130441314413244133441344413544136441374413844139441404414144142441434414444145441464414744148441494415044151441524415344154441554415644157441584415944160441614416244163441644416544166441674416844169441704417144172441734417444175441764417744178441794418044181441824418344184441854418644187441884418944190441914419244193441944419544196441974419844199442004420144202442034420444205442064420744208442094421044211442124421344214442154421644217442184421944220442214422244223442244422544226442274422844229442304423144232442334423444235442364423744238442394424044241442424424344244442454424644247442484424944250442514425244253442544425544256442574425844259442604426144262442634426444265442664426744268442694427044271442724427344274442754427644277442784427944280442814428244283442844428544286442874428844289442904429144292442934429444295442964429744298442994430044301443024430344304443054430644307443084430944310443114431244313443144431544316443174431844319443204432144322443234432444325443264432744328443294433044331443324433344334443354433644337443384433944340443414434244343443444434544346443474434844349443504435144352443534435444355443564435744358443594436044361443624436344364443654436644367443684436944370443714437244373443744437544376443774437844379443804438144382443834438444385443864438744388443894439044391443924439344394443954439644397443984439944400444014440244403444044440544406444074440844409444104441144412444134441444415444164441744418444194442044421444224442344424444254442644427444284442944430444314443244433444344443544436444374443844439444404444144442444434444444445444464444744448444494445044451444524445344454444554445644457444584445944460444614446244463444644446544466444674446844469444704447144472444734447444475444764447744478444794448044481444824448344484444854448644487444884448944490444914449244493444944449544496444974449844499445004450144502445034450444505445064450744508445094451044511445124451344514445154451644517445184451944520445214452244523445244452544526445274452844529445304453144532445334453444535445364453744538445394454044541445424454344544445454454644547445484454944550445514455244553445544455544556445574455844559445604456144562445634456444565445664456744568445694457044571445724457344574445754457644577445784457944580445814458244583445844458544586445874458844589445904459144592445934459444595445964459744598445994460044601446024460344604446054460644607446084460944610446114461244613446144461544616446174461844619446204462144622446234462444625446264462744628446294463044631446324463344634446354463644637446384463944640446414464244643446444464544646446474464844649446504465144652446534465444655446564465744658446594466044661446624466344664446654466644667446684466944670446714467244673446744467544676446774467844679446804468144682446834468444685446864468744688446894469044691446924469344694446954469644697446984469944700447014470244703447044470544706447074470844709447104471144712447134471444715447164471744718447194472044721447224472344724447254472644727447284472944730447314473244733447344473544736447374473844739447404474144742447434474444745447464474744748447494475044751447524475344754447554475644757447584475944760447614476244763447644476544766447674476844769447704477144772447734477444775447764477744778447794478044781447824478344784447854478644787447884478944790447914479244793447944479544796447974479844799448004480144802448034480444805448064480744808448094481044811448124481344814448154481644817448184481944820448214482244823448244482544826448274482844829448304483144832448334483444835448364483744838448394484044841448424484344844448454484644847448484484944850448514485244853448544485544856448574485844859448604486144862448634486444865448664486744868448694487044871448724487344874448754487644877448784487944880448814488244883448844488544886448874488844889448904489144892448934489444895448964489744898448994490044901449024490344904449054490644907449084490944910449114491244913449144491544916449174491844919449204492144922449234492444925449264492744928449294493044931449324493344934449354493644937449384493944940449414494244943449444494544946449474494844949449504495144952449534495444955449564495744958449594496044961449624496344964449654496644967449684496944970449714497244973449744497544976449774497844979449804498144982449834498444985449864498744988449894499044991449924499344994449954499644997449984499945000450014500245003450044500545006450074500845009450104501145012450134501445015450164501745018450194502045021450224502345024450254502645027450284502945030450314503245033450344503545036450374503845039450404504145042450434504445045450464504745048450494505045051450524505345054450554505645057450584505945060450614506245063450644506545066450674506845069450704507145072450734507445075450764507745078450794508045081450824508345084450854508645087450884508945090450914509245093450944509545096450974509845099451004510145102451034510445105451064510745108451094511045111451124511345114451154511645117451184511945120451214512245123451244512545126451274512845129451304513145132451334513445135451364513745138451394514045141451424514345144451454514645147451484514945150451514515245153451544515545156451574515845159451604516145162451634516445165451664516745168451694517045171451724517345174451754517645177451784517945180451814518245183451844518545186451874518845189451904519145192451934519445195451964519745198451994520045201452024520345204452054520645207452084520945210452114521245213452144521545216452174521845219452204522145222452234522445225452264522745228452294523045231452324523345234452354523645237452384523945240452414524245243452444524545246452474524845249452504525145252452534525445255452564525745258452594526045261452624526345264452654526645267452684526945270452714527245273452744527545276452774527845279452804528145282452834528445285452864528745288452894529045291452924529345294452954529645297452984529945300453014530245303453044530545306453074530845309453104531145312453134531445315453164531745318453194532045321453224532345324453254532645327453284532945330453314533245333453344533545336453374533845339453404534145342453434534445345453464534745348453494535045351453524535345354453554535645357453584535945360453614536245363453644536545366453674536845369453704537145372453734537445375453764537745378453794538045381453824538345384453854538645387453884538945390453914539245393453944539545396453974539845399454004540145402454034540445405454064540745408454094541045411454124541345414454154541645417454184541945420454214542245423454244542545426454274542845429454304543145432454334543445435454364543745438454394544045441454424544345444454454544645447454484544945450454514545245453454544545545456454574545845459454604546145462454634546445465454664546745468454694547045471454724547345474454754547645477454784547945480454814548245483454844548545486454874548845489454904549145492454934549445495454964549745498454994550045501455024550345504455054550645507455084550945510455114551245513455144551545516455174551845519455204552145522455234552445525455264552745528455294553045531455324553345534455354553645537455384553945540455414554245543455444554545546455474554845549455504555145552455534555445555455564555745558455594556045561455624556345564455654556645567455684556945570455714557245573455744557545576455774557845579455804558145582455834558445585455864558745588455894559045591455924559345594455954559645597455984559945600456014560245603456044560545606456074560845609456104561145612456134561445615456164561745618456194562045621456224562345624456254562645627456284562945630456314563245633456344563545636456374563845639456404564145642456434564445645456464564745648456494565045651456524565345654456554565645657456584565945660456614566245663456644566545666456674566845669456704567145672456734567445675456764567745678456794568045681456824568345684456854568645687456884568945690456914569245693456944569545696456974569845699457004570145702457034570445705457064570745708457094571045711457124571345714457154571645717457184571945720457214572245723457244572545726457274572845729457304573145732457334573445735457364573745738457394574045741457424574345744457454574645747457484574945750457514575245753457544575545756457574575845759457604576145762457634576445765457664576745768457694577045771457724577345774457754577645777457784577945780457814578245783457844578545786457874578845789457904579145792457934579445795457964579745798457994580045801458024580345804458054580645807458084580945810458114581245813458144581545816458174581845819458204582145822458234582445825458264582745828458294583045831458324583345834458354583645837458384583945840458414584245843458444584545846458474584845849458504585145852458534585445855458564585745858458594586045861458624586345864458654586645867458684586945870458714587245873458744587545876458774587845879458804588145882458834588445885458864588745888458894589045891458924589345894458954589645897458984589945900459014590245903459044590545906459074590845909459104591145912459134591445915459164591745918459194592045921459224592345924459254592645927459284592945930459314593245933459344593545936459374593845939459404594145942459434594445945459464594745948459494595045951459524595345954459554595645957459584595945960459614596245963459644596545966459674596845969459704597145972459734597445975459764597745978459794598045981459824598345984459854598645987459884598945990459914599245993459944599545996459974599845999460004600146002460034600446005460064600746008460094601046011460124601346014460154601646017460184601946020460214602246023460244602546026460274602846029460304603146032460334603446035460364603746038460394604046041460424604346044460454604646047460484604946050460514605246053460544605546056460574605846059460604606146062460634606446065460664606746068460694607046071460724607346074460754607646077460784607946080460814608246083460844608546086460874608846089460904609146092460934609446095460964609746098460994610046101461024610346104461054610646107461084610946110461114611246113461144611546116461174611846119461204612146122461234612446125461264612746128461294613046131461324613346134461354613646137461384613946140461414614246143461444614546146461474614846149461504615146152461534615446155461564615746158461594616046161461624616346164461654616646167461684616946170461714617246173461744617546176461774617846179461804618146182461834618446185461864618746188461894619046191461924619346194461954619646197461984619946200462014620246203462044620546206462074620846209462104621146212462134621446215462164621746218462194622046221462224622346224462254622646227462284622946230462314623246233462344623546236462374623846239462404624146242462434624446245462464624746248462494625046251462524625346254462554625646257462584625946260462614626246263462644626546266462674626846269462704627146272462734627446275462764627746278462794628046281462824628346284462854628646287462884628946290462914629246293462944629546296462974629846299463004630146302463034630446305463064630746308463094631046311463124631346314463154631646317463184631946320463214632246323463244632546326463274632846329463304633146332463334633446335463364633746338463394634046341463424634346344463454634646347463484634946350463514635246353463544635546356463574635846359463604636146362463634636446365463664636746368463694637046371463724637346374463754637646377463784637946380463814638246383463844638546386463874638846389463904639146392463934639446395463964639746398463994640046401464024640346404464054640646407464084640946410464114641246413464144641546416464174641846419464204642146422464234642446425464264642746428464294643046431464324643346434464354643646437464384643946440464414644246443464444644546446464474644846449464504645146452464534645446455464564645746458464594646046461464624646346464464654646646467464684646946470464714647246473464744647546476464774647846479464804648146482464834648446485464864648746488464894649046491464924649346494464954649646497464984649946500465014650246503465044650546506465074650846509465104651146512465134651446515465164651746518465194652046521465224652346524465254652646527465284652946530465314653246533465344653546536465374653846539465404654146542465434654446545465464654746548465494655046551465524655346554465554655646557465584655946560465614656246563465644656546566465674656846569465704657146572465734657446575465764657746578465794658046581465824658346584465854658646587465884658946590465914659246593465944659546596465974659846599466004660146602466034660446605466064660746608466094661046611466124661346614466154661646617466184661946620466214662246623466244662546626466274662846629 |
- \input texinfo
- @c -*-texinfo-*-
- @c %**start of header
- @setfilename guix.info
- @documentencoding UTF-8
- @settitle GNU Guix Reference Manual
- @c %**end of header
- @include version.texi
- @c Identifier of the OpenPGP key used to sign tarballs and such.
- @set OPENPGP-SIGNING-KEY-ID 3CE464558A84FDC69DB40CFB090B11993D9AEBB5
- @set OPENPGP-SIGNING-KEY-URL https://sv.gnu.org/people/viewgpg.php?user_id=15145
- @c Base URL for downloads.
- @set BASE-URL https://ftp.gnu.org/gnu/guix
- @c The official substitute server used by default.
- @set SUBSTITUTE-SERVER-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-2023 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, 2023 Leo Famulari@*
- Copyright @copyright{} 2015, 2016, 2017, 2018, 2019, 2020, 2021, 2022, 2023 Ricardo Wurmus@*
- Copyright @copyright{} 2016 Ben Woodcroft@*
- Copyright @copyright{} 2016, 2017, 2018, 2021 Chris Marusich@*
- Copyright @copyright{} 2016, 2017, 2018, 2019, 2020, 2021, 2022, 2023 Efraim Flashner@*
- Copyright @copyright{} 2016 John Darrington@*
- Copyright @copyright{} 2016, 2017 Nikita Gillmann@*
- Copyright @copyright{} 2016, 2017, 2018, 2019, 2020, 2021, 2022, 2023 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, 2022 Mathieu Othacehe@*
- Copyright @copyright{} 2017 Federico Beffa@*
- Copyright @copyright{} 2017, 2018 Carlo Zancanaro@*
- Copyright @copyright{} 2017 Thomas Danckaert@*
- Copyright @copyright{} 2017 humanitiesNerd@*
- Copyright @copyright{} 2017, 2021 Christine Lemmer-Webber@*
- Copyright @copyright{} 2017, 2018, 2019, 2020, 2021, 2022 Marius Bakke@*
- Copyright @copyright{} 2017, 2019, 2020, 2022 Hartmut Goebel@*
- Copyright @copyright{} 2017, 2019, 2020, 2021, 2022, 2023 Maxim Cournoyer@*
- Copyright @copyright{} 2017–2022 Tobias Geerinckx-Rice@*
- Copyright @copyright{} 2017 George Clemmer@*
- Copyright @copyright{} 2017 Andy Wingo@*
- Copyright @copyright{} 2017, 2018, 2019, 2020, 2023 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, 2022, 2023 Florian Pelz@*
- Copyright @copyright{} 2018 Laura Lazzati@*
- Copyright @copyright{} 2018 Alex Vong@*
- Copyright @copyright{} 2019 Josh Holland@*
- Copyright @copyright{} 2019, 2020 Diego Nicola Barbato@*
- Copyright @copyright{} 2019 Ivan Petkov@*
- Copyright @copyright{} 2019 Jakob L. Kreuze@*
- Copyright @copyright{} 2019 Kyle Andrews@*
- Copyright @copyright{} 2019 Alex Griffin@*
- Copyright @copyright{} 2019, 2020, 2021, 2022 Guillaume Le Vaillant@*
- Copyright @copyright{} 2020 Liliana Marie Prikler@*
- Copyright @copyright{} 2019, 2020, 2021, 2022, 2023 Simon Tournier@*
- Copyright @copyright{} 2020 Wiktor Żelazny@*
- Copyright @copyright{} 2020 Damien Cassou@*
- Copyright @copyright{} 2020 Jakub Kądziołka@*
- Copyright @copyright{} 2020 Jack Hill@*
- Copyright @copyright{} 2020 Naga Malleswari@*
- Copyright @copyright{} 2020, 2021 Brice Waegeneire@*
- Copyright @copyright{} 2020 R Veera Kumar@*
- Copyright @copyright{} 2020, 2021, 2022 Pierre Langlois@*
- Copyright @copyright{} 2020 pinoaffe@*
- Copyright @copyright{} 2020, 2023 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, 2022 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-2023 Josselin Poiret@*
- Copyright @copyright{} 2021, 2023 muradm@*
- Copyright @copyright{} 2021, 2022 Andrew Tropin@*
- Copyright @copyright{} 2021 Sarah Morgensen@*
- Copyright @copyright{} 2022 Remco van 't Veer@*
- Copyright @copyright{} 2022 Aleksandr Vityazev@*
- Copyright @copyright{} 2022 Philip M@sup{c}Grath@*
- Copyright @copyright{} 2022 Karl Hallsby@*
- Copyright @copyright{} 2022 Justin Veilleux@*
- Copyright @copyright{} 2022 Reily Siegel@*
- Copyright @copyright{} 2022 Simon Streit@*
- Copyright @copyright{} 2022 (@*
- Copyright @copyright{} 2022 John Kehayias@*
- Copyright @copyright{} 2022–2023 Bruno Victal@*
- Copyright @copyright{} 2022 Ivan Vilata-i-Balaguer@*
- Copyright @copyright{} 2023 Giacomo Leidi@*
- Copyright @copyright{} 2022 Antero Mejr@*
- Copyright @copyright{} 2023 Karl Hallsby@*
- Copyright @copyright{} 2023 Nathaniel Nicandro@*
- Copyright @copyright{} 2023 Tanguy Le Carrour@*
- Copyright @copyright{} 2023 Zheng Junjie@*
- Copyright @copyright{} 2023 Brian Cully@*
- Copyright @copyright{} 2023 Felix Lechner@*
- Permission is granted to copy, distribute and/or modify this document
- under the terms of the GNU Free Documentation License, Version 1.3 or
- any later version published by the Free Software Foundation; with no
- Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
- copy of the license is included in the section entitled ``GNU Free
- Documentation License''.
- @end copying
- @dircategory System administration
- @direntry
- * Guix: (guix). Manage installed software and system configuration.
- * guix package: (guix)Invoking guix package. Installing, removing, and upgrading packages.
- * guix gc: (guix)Invoking guix gc. Reclaiming unused disk space.
- * guix pull: (guix)Invoking guix pull. Update the list of available packages.
- * guix system: (guix)Invoking guix system. Manage the operating system configuration.
- * guix deploy: (guix)Invoking guix deploy. Manage operating system configurations for remote hosts.
- @end direntry
- @dircategory Software development
- @direntry
- * guix shell: (guix)Invoking guix shell. Creating software environments.
- * guix environment: (guix)Invoking guix environment. Building development environments with Guix.
- * guix build: (guix)Invoking guix build. Building packages.
- * guix pack: (guix)Invoking guix pack. Creating binary bundles.
- @end direntry
- @titlepage
- @title GNU Guix Reference Manual
- @subtitle Using the GNU Guix Functional Package Manager
- @author The GNU Guix Developers
- @page
- @vskip 0pt plus 1filll
- Edition @value{EDITION} @*
- @value{UPDATED} @*
- @insertcopying
- @end titlepage
- @contents
- @c *********************************************************************
- @node Top
- @top GNU Guix
- This document describes GNU Guix version @value{VERSION}, a functional
- package management tool written for the GNU system.
- @c TRANSLATORS: You can replace the following paragraph with information on
- @c how to join your own translation team and how to report issues with the
- @c translation.
- This manual is also available in Simplified Chinese (@pxref{Top,,, guix.zh_CN,
- GNU Guix参考手册}), French (@pxref{Top,,, guix.fr, Manuel de référence de GNU
- Guix}), German (@pxref{Top,,, guix.de, Referenzhandbuch zu GNU Guix}),
- Spanish (@pxref{Top,,, guix.es, Manual de referencia de GNU Guix}),
- Brazilian Portuguese (@pxref{Top,,, guix.pt_BR, Manual de referência do
- 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.
- * System Troubleshooting Tips:: When things don't go as planned.
- * 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.
- * Foreign Architectures:: Build for foreign architectures.
- * System Configuration:: Configuring the operating system.
- * Home Configuration:: Configuring the home environment.
- * Documentation:: Browsing software user manuals.
- * Platforms:: Defining platforms.
- * System Images:: Creating system images.
- * Installing Debugging Files:: Feeding the debugger.
- * Using TeX and LaTeX:: Typesetting.
- * Security Updates:: Deploying security fixes quickly.
- * Bootstrapping:: GNU/Linux built from scratch.
- * Porting:: Targeting another platform or kernel.
- * Contributing:: Your help needed!
- * Acknowledgments:: Thanks!
- * GNU Free Documentation License:: The license of this manual.
- * Concept Index:: Concepts.
- * Programming Index:: Data types, functions, and variables.
- @detailmenu
- --- The Detailed Node Listing ---
- Introduction
- * Managing Software the Guix Way:: What's special.
- * GNU Distribution:: The packages and tools.
- Installation
- * Binary Installation:: Getting Guix running in no time!
- * Requirements:: Software needed to build and run Guix.
- * Running the Test Suite:: Testing Guix.
- * Setting Up the Daemon:: Preparing the build daemon's environment.
- * Invoking guix-daemon:: Running the build daemon.
- * Application Setup:: Application-specific setup.
- * Upgrading Guix:: Upgrading Guix and its build daemon.
- Setting Up the Daemon
- * Build Environment Setup:: Preparing the isolated build environment.
- * Daemon Offload Setup:: Offloading builds to remote machines.
- * SELinux Support:: Using an SELinux policy for the daemon.
- System Installation
- * Limitations:: What you can expect.
- * Hardware Considerations:: Supported hardware.
- * USB Stick and DVD Installation:: Preparing the installation medium.
- * Preparing for Installation:: Networking, partitioning, etc.
- * Guided Graphical Installation:: Easy graphical installation.
- * Manual Installation:: Manual installation for wizards.
- * After System Installation:: When installation succeeded.
- * Installing Guix in a VM:: Guix System playground.
- * Building the Installation Image:: How this comes to be.
- Manual Installation
- * Keyboard Layout and Networking and Partitioning:: Initial setup.
- * Proceeding with the Installation:: Installing.
- System Troubleshooting Tips
- * Chrooting into an existing system::
- 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 locate:: Locating packages that provide a file.
- * Invoking guix gc:: Running the garbage collector.
- * Invoking guix pull:: Fetching the latest Guix and distribution.
- * Invoking guix time-machine:: Running an older revision of Guix.
- * Inferiors:: Interacting with another revision of Guix.
- * Invoking guix describe:: Display information about your Guix revision.
- * Invoking guix archive:: Exporting and importing store files.
- Substitutes
- * Official Substitute Servers:: One particular source of substitutes.
- * Substitute Server Authorization:: How to enable or disable substitutes.
- * Getting Substitutes from Other Servers:: Substitute diversity.
- * Substitute Authentication:: How Guix verifies substitutes.
- * Proxy Settings:: How to get substitutes via proxy.
- * Substitution Failure:: What happens when substitution fails.
- * On Trusting Binaries:: How can you trust that binary blob?
- Channels
- * Specifying Additional Channels:: Extending the package collection.
- * Using a Custom Guix Channel:: Using a customized Guix.
- * Replicating Guix:: Running the @emph{exact same} Guix.
- * Channel Authentication:: How Guix verifies what it fetches.
- * Channels with Substitutes:: Using channels with available substitutes.
- * Creating a Channel:: How to write your custom channel.
- * Package Modules in a Sub-directory:: Specifying the channel's package modules location.
- * Declaring Channel Dependencies:: How to depend on other channels.
- * Specifying Channel Authorizations:: Defining channel authors authorizations.
- * Primary URL:: Distinguishing mirror to original.
- * Writing Channel News:: Communicating information to channel's users.
- Development
- * Invoking guix shell:: Spawning one-off software environments.
- * Invoking guix environment:: Setting up development environments.
- * Invoking guix pack:: Creating software bundles.
- * The GCC toolchain:: Working with languages supported by GCC.
- * Invoking guix git authenticate:: Authenticating Git repositories.
- Programming Interface
- * Package Modules:: Packages from the programmer's viewpoint.
- * Defining Packages:: Defining new packages.
- * Defining Package Variants:: Customizing packages.
- * Writing Manifests:: The bill of materials of your environment.
- * Build Systems:: Specifying how packages are built.
- * Build Phases:: Phases of the build process of a package.
- * Build Utilities:: Helpers for your package definitions and more.
- * Search Paths:: Declaring search path environment variables.
- * The Store:: Manipulating the package store.
- * Derivations:: Low-level interface to package derivations.
- * The Store Monad:: Purely functional interface to the store.
- * G-Expressions:: Manipulating build expressions.
- * Invoking guix repl:: Programming Guix in Guile
- * Using Guix Interactively:: Fine-grain interaction at the REPL.
- 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.
- Foreign Architectures
- * Cross-Compilation:: Cross-compiling for another architecture.
- * Native Builds:: Targeting another architecture through native builds.
- System Configuration
- * Using the Configuration System:: Customizing your GNU system.
- * operating-system Reference:: Detail of operating-system declarations.
- * File Systems:: Configuring file system mounts.
- * Mapped Devices:: Block device extra processing.
- * Swap Space:: Backing RAM with disk space.
- * User Accounts:: Specifying user accounts.
- * Keyboard Layout:: How the system interprets key strokes.
- * Locales:: Language and cultural convention settings.
- * Services:: Specifying system services.
- * Setuid Programs:: Programs running with elevated 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.
- File Systems
- * Btrfs file system::
- Services
- * Base Services:: Essential system services.
- * Scheduled Job Execution:: The mcron service.
- * Log Rotation:: The rottlog service.
- * Networking Setup:: Setting up network interfaces.
- * Networking Services:: Firewall, SSH daemon, etc.
- * Unattended Upgrades:: Automated system upgrades.
- * X Window:: Graphical display.
- * Printing Services:: Local and remote printer support.
- * Desktop Services:: D-Bus and desktop services.
- * Sound Services:: ALSA and Pulseaudio services.
- * File Search Services:: Tools to search for files.
- * 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.
- * VNC Services:: VNC daemons.
- * VPN Services:: VPN daemons.
- * Network File System:: NFS related services.
- * Samba Services:: Samba services.
- * Continuous Integration:: Cuirass and Laminar services.
- * Power Management Services:: Extending battery life.
- * Audio Services:: The MPD.
- * Virtualization Services:: Virtualization services.
- * Version Control Services:: Providing remote access to Git repositories.
- * Game Services:: Game servers.
- * PAM Mount Service:: Service to mount volumes when logging in.
- * Guix Services:: Services relating specifically to Guix.
- * Linux Services:: Services tied to the Linux kernel.
- * Hurd Services:: Services specific for a Hurd System.
- * Miscellaneous Services:: Other services.
- Defining Services
- * Service Composition:: The model for composing services.
- * Service Types and Services:: Types and services.
- * Service Reference:: API reference.
- * Shepherd Services:: A particular type of service.
- * Complex Configurations:: Defining bindings for complex configurations.
- Home Configuration
- * Declaring the Home Environment:: Customizing your Home.
- * Configuring the Shell:: Enabling home environment.
- * Home Services:: Specifying home services.
- * Invoking guix home:: Instantiating a home configuration.
- Home Services
- * Essential Home Services:: Environment variables, packages, on-* scripts.
- * Shells: Shells Home Services. POSIX shells, Bash, Zsh.
- * Mcron: Mcron Home Service. Scheduled User's Job Execution.
- * Power Management: Power Management Home Services. Services for battery power.
- * Shepherd: Shepherd Home Service. Managing User's Daemons.
- * SSH: Secure Shell. Setting up the secure shell client.
- * GPG: GNU Privacy Guard. Setting up GPG and related tools.
- * Desktop: Desktop Home Services. Services for graphical environments.
- * Guix: Guix Home Services. Services for Guix.
- * Fonts: Fonts Home Services. Services for managing User's fonts.
- * Sound: Sound Home Services. Dealing with audio.
- * Mail: Mail Home Services. Services for managing mail.
- * Messaging: Messaging Home Services. Services for managing messaging.
- * Media: Media Home Services. Services for managing media.
- * Networking: Networking Home Services. Networking services.
- * Miscellaneous: Miscellaneous Home Services. More services.
- Platforms
- * platform Reference:: Detail of platform declarations.
- * Supported Platforms:: Description of the supported platforms.
- Creating System Images
- * image Reference:: Detail of image declarations.
- * Instantiate an Image:: How to instantiate an image record.
- * image-type Reference:: Detail of image types declaration.
- * Image Modules:: Definition of image modules.
- @code{image} Reference
- * partition Reference::
- Installing Debugging Files
- * Separate Debug Info:: Installing 'debug' outputs.
- * Rebuilding Debug Info:: Building missing debug info.
- Bootstrapping
- * Full-Source Bootstrap:: A Bootstrap worthy of GNU.
- * Preparing to Use the Bootstrap Binaries:: Building that what matters most.
- @end detailmenu
- @end menu
- @c *********************************************************************
- @node Introduction
- @chapter Introduction
- @cindex purpose
- GNU Guix@footnote{``Guix'' is pronounced like ``geeks'', or ``ɡiːks''
- using the international phonetic alphabet (IPA).} is a package
- management tool for and distribution of the GNU system.
- Guix makes it easy for unprivileged
- users to install, upgrade, or remove software packages, to roll back to a
- previous package set, to build packages from source, and generally
- assists with the creation and maintenance of software environments.
- @cindex Guix System
- @cindex GuixSD, now Guix System
- @cindex Guix System Distribution, now Guix System
- You can install GNU@tie{}Guix on top of an existing GNU/Linux system where it
- complements the available tools without interference (@pxref{Installation}),
- or you can use it as a standalone operating system distribution,
- @dfn{Guix@tie{}System}@footnote{We used to refer to Guix System as ``Guix
- System Distribution'' or ``GuixSD''. We now consider it makes more sense to
- group everything under the ``Guix'' banner since, after all, Guix System is
- readily available through the @command{guix system} command, even if you're
- using a different distro underneath!}. @xref{GNU Distribution}.
- @menu
- * Managing Software the Guix Way:: What's special.
- * GNU Distribution:: The packages and tools.
- @end menu
- @node Managing Software the Guix Way
- @section Managing Software the Guix Way
- @cindex user interfaces
- Guix provides a command-line package management interface
- (@pxref{Package Management}), tools to help with software development
- (@pxref{Development}), command-line utilities for more advanced usage
- (@pxref{Utilities}), as well as Scheme programming interfaces
- (@pxref{Programming Interface}).
- @cindex build daemon
- Its @dfn{build daemon} is responsible for building packages on behalf of
- users (@pxref{Setting Up the Daemon}) and for downloading pre-built
- binaries from authorized sources (@pxref{Substitutes}).
- @cindex extensibility of the distribution
- @cindex customization, of packages
- Guix includes package definitions for many GNU and non-GNU packages, all
- of which @uref{https://www.gnu.org/philosophy/free-sw.html, respect the
- user's computing freedom}. It is @emph{extensible}: users can write
- their own package definitions (@pxref{Defining Packages}) and make them
- available as independent package modules (@pxref{Package Modules}). It
- is also @emph{customizable}: users can @emph{derive} specialized package
- definitions from existing ones, including from the command line
- (@pxref{Package Transformation Options}).
- @cindex functional package management
- @cindex isolation
- Under the hood, Guix implements the @dfn{functional package management}
- discipline pioneered by Nix (@pxref{Acknowledgments}).
- In Guix, the package build and installation process is seen
- as a @emph{function}, in the mathematical sense. That function takes inputs,
- such as build scripts, a compiler, and libraries, and
- returns an installed package. As a pure function, its result depends
- solely on its inputs---for instance, it cannot refer to software or
- scripts that were not explicitly passed as inputs. A build function
- always produces the same result when passed a given set of inputs. It
- cannot alter the environment of the running system in
- any way; for instance, it cannot create, modify, or delete files outside
- of its build and installation directories. This is achieved by running
- build processes in isolated environments (or @dfn{containers}), where only their
- explicit inputs are visible.
- @cindex store
- The result of package build functions is @dfn{cached} in the file
- system, in a special directory called @dfn{the store} (@pxref{The
- Store}). Each package is installed in a directory of its own in the
- store---by default under @file{/gnu/store}. The directory name contains
- a hash of all the inputs used to build that package; thus, changing an
- input yields a different directory name.
- This approach is the foundation for the salient features of Guix: support
- for transactional package upgrade and rollback, per-user installation, and
- garbage collection of packages (@pxref{Features}).
- @node GNU Distribution
- @section GNU Distribution
- @cindex Guix System
- Guix comes with a distribution of the GNU system consisting entirely of
- free software@footnote{The term ``free'' here refers to the
- @url{https://www.gnu.org/philosophy/free-sw.html,freedom provided to
- users of that software}.}. The
- distribution can be installed on its own (@pxref{System Installation}),
- but it is also possible to install Guix as a package manager on top of
- an installed GNU/Linux system (@pxref{Installation}). When we need to
- distinguish between the two, we refer to the standalone distribution as
- Guix@tie{}System.
- The distribution provides core GNU packages such as GNU libc, GCC, and
- Binutils, as well as many GNU and non-GNU applications. The complete
- list of available packages can be browsed
- @url{https://www.gnu.org/software/guix/packages,on-line} or by
- running @command{guix package} (@pxref{Invoking guix package}):
- @example
- guix package --list-available
- @end example
- Our goal is to provide a practical 100% free software distribution of
- Linux-based and other variants of GNU, with a focus on the promotion and
- tight integration of GNU components, and an emphasis on programs and
- tools that help users exert that freedom.
- Packages are currently available on the following platforms:
- @table @code
- @item x86_64-linux
- Intel/AMD @code{x86_64} architecture, Linux-Libre kernel.
- @item i686-linux
- Intel 32-bit architecture (IA32), Linux-Libre kernel.
- @item armhf-linux
- ARMv7-A architecture with hard float, Thumb-2 and NEON,
- using the EABI hard-float application binary interface (ABI),
- and Linux-Libre kernel.
- @item aarch64-linux
- little-endian 64-bit ARMv8-A processors, Linux-Libre kernel.
- @item i586-gnu
- @uref{https://hurd.gnu.org, GNU/Hurd} on the Intel 32-bit architecture
- (IA32).
- This configuration is experimental and under development. The easiest
- way for you to give it a try is by setting up an instance of
- @code{hurd-vm-service-type} on your GNU/Linux machine
- (@pxref{transparent-emulation-qemu, @code{hurd-vm-service-type}}).
- @xref{Contributing}, on how to help!
- @item mips64el-linux (unsupported)
- little-endian 64-bit MIPS processors, specifically the Loongson series,
- n32 ABI, and Linux-Libre kernel. This configuration is no longer fully
- supported; in particular, there is no ongoing work to ensure that this
- architecture still works. Should someone decide they wish to revive this
- architecture then the code is still available.
- @item powerpc-linux (unsupported)
- big-endian 32-bit PowerPC processors, specifically the PowerPC G4 with
- AltiVec support, and Linux-Libre kernel. This configuration is not
- fully supported and there is no ongoing work to ensure this architecture
- works.
- @item powerpc64le-linux
- little-endian 64-bit Power ISA processors, Linux-Libre kernel. This
- includes POWER9 systems such as the
- @uref{https://www.fsf.org/news/talos-ii-mainboard-and-talos-ii-lite-mainboard-now-fsf-certified-to-respect-your-freedom,
- RYF Talos II mainboard}. This platform is available as a "technology
- preview": although it is supported, substitutes are not yet available
- from the build farm (@pxref{Substitutes}), and some packages may fail to
- build (@pxref{Tracking Bugs and Changes}). That said, the Guix
- community is actively working on improving this support, and now is a
- great time to try it and get involved!
- @item riscv64-linux
- little-endian 64-bit RISC-V processors, specifically RV64GC, and
- Linux-Libre kernel. This 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 Changes}). That said, the Guix
- community is actively working on improving this support, and now is a
- great time to try it and get involved!
- @end table
- With Guix@tie{}System, you @emph{declare} all aspects of the operating system
- configuration and Guix takes care of instantiating the configuration in a
- transactional, reproducible, and stateless fashion (@pxref{System
- Configuration}). Guix System uses the Linux-libre kernel, the Shepherd
- initialization system (@pxref{Introduction,,, shepherd, The GNU Shepherd
- Manual}), the well-known GNU utilities and tool chain, as well as the
- graphical environment or system services of your choice.
- Guix System is available on all the above platforms except
- @code{mips64el-linux}, @code{powerpc-linux}, @code{powerpc64le-linux} and
- @code{riscv64-linux}.
- @noindent
- For information on porting to other architectures or kernels,
- @pxref{Porting}.
- Building this distribution is a cooperative effort, and you are invited
- to join! @xref{Contributing}, for information about how you can help.
- @c *********************************************************************
- @node Installation
- @chapter Installation
- @cindex installing Guix
- @quotation Note
- We recommend the use of this
- @uref{https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh,
- shell installer script} to install Guix on top of a running GNU/Linux system,
- thereafter called a @dfn{foreign distro}.@footnote{This section is concerned
- with the installation of the package manager, which can be done on top of a
- running GNU/Linux system. If, instead, you want to install the complete GNU
- operating system, @pxref{System Installation}.} The script automates the
- download, installation, and initial configuration of Guix. It should be run
- as the root user.
- @end quotation
- @cindex foreign distro
- @cindex directories related to foreign distro
- When installed on a foreign distro, GNU@tie{}Guix complements the available
- tools without interference. Its data lives exclusively in two directories,
- usually @file{/gnu/store} and @file{/var/guix}; other files on your system,
- such as @file{/etc}, are left untouched.
- Once installed, Guix can be updated by running @command{guix pull}
- (@pxref{Invoking guix pull}).
- If you prefer to perform the installation steps manually or want to tweak
- them, you may find the following subsections useful. They describe the
- software requirements of Guix, as well as how to install it manually and get
- ready to use it.
- @menu
- * Binary Installation:: Getting Guix running in no time!
- * Requirements:: Software needed to build and run Guix.
- * Running the Test Suite:: Testing Guix.
- * Setting Up the Daemon:: Preparing the build daemon's environment.
- * Invoking guix-daemon:: Running the build daemon.
- * Application Setup:: Application-specific setup.
- * Upgrading Guix:: Upgrading Guix and its build daemon.
- @end menu
- @node Binary Installation
- @section Binary Installation
- @cindex installing Guix from binaries
- @cindex installer script
- This section describes how to install Guix on an arbitrary system from a
- self-contained tarball providing binaries for Guix and for all its
- dependencies. This is often quicker than installing from source, which
- is described in the next sections. The only requirement is to have
- GNU@tie{}tar and Xz.
- @c Note duplicated from the ``Installation'' node.
- @quotation Note
- We recommend the use of this
- @uref{https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh,
- shell installer script}. The script automates the download, installation, and
- initial configuration steps described below. It should be run as the root
- user. As root, you can thus run this:
- @example
- cd /tmp
- wget https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh
- chmod +x guix-install.sh
- ./guix-install.sh
- @end example
- If you're running Debian or a derivative such as Ubuntu, you can instead
- install the package (it might be a version older than @value{VERSION}
- but you can update it afterwards by running @samp{guix pull}):
- @example
- sudo apt install guix
- @end example
- Likewise on openSUSE:
- @example
- sudo zypper install guix
- @end example
- When you're done, @pxref{Application Setup} for extra configuration you
- might need, and @ref{Getting Started} for your first steps!
- @end quotation
- Installing goes along these lines:
- @enumerate
- @item
- @cindex downloading Guix binary
- Download the binary tarball from
- @indicateurl{@value{BASE-URL}/guix-binary-@value{VERSION}.x86_64-linux.tar.xz},
- where @code{x86_64-linux} can be replaced with @code{i686-linux} for an
- @code{i686} (32-bits) machine already running the kernel Linux, and so on
- (@pxref{GNU Distribution}).
- @c The following is somewhat duplicated in ``System Installation''.
- Make sure to download the associated @file{.sig} file and to verify the
- authenticity of the tarball against it, along these lines:
- @example
- $ wget @value{BASE-URL}/guix-binary-@value{VERSION}.x86_64-linux.tar.xz.sig
- $ gpg --verify guix-binary-@value{VERSION}.x86_64-linux.tar.xz.sig
- @end example
- If that command fails because you do not have the required public key,
- then run this command to import it:
- @example
- $ wget '@value{OPENPGP-SIGNING-KEY-URL}' \
- -qO - | gpg --import -
- @end example
- @noindent
- and rerun the @code{gpg --verify} command.
- Take note that a warning like ``This key is not certified with a trusted
- signature!'' is normal.
- @c end authentication part
- @item
- Now, you need to become the @code{root} user. Depending on your distribution,
- you may have to run @code{su -} or @code{sudo -i}. As @code{root}, run:
- @example
- # cd /tmp
- # tar --warning=no-timestamp -xf \
- /path/to/guix-binary-@value{VERSION}.x86_64-linux.tar.xz
- # mv var/guix /var/ && mv gnu /
- @end example
- This creates @file{/gnu/store} (@pxref{The Store}) and @file{/var/guix}.
- The latter contains a ready-to-use profile for @code{root} (see next
- step).
- Do @emph{not} unpack the tarball on a working Guix system since that
- would overwrite its own essential files.
- The @option{--warning=no-timestamp} option makes sure GNU@tie{}tar does
- not emit warnings about ``implausibly old time stamps'' (such
- warnings were triggered by GNU@tie{}tar 1.26 and older; recent
- versions are fine).
- They stem from the fact that all the
- files in the archive have their modification time set to 1 (which
- means January 1st, 1970). This is done on purpose to make sure the
- archive content is independent of its creation time, thus making it
- reproducible.
- @item
- Make the profile available under @file{~root/.config/guix/current}, which is
- where @command{guix pull} will install updates (@pxref{Invoking guix pull}):
- @example
- # mkdir -p ~root/.config/guix
- # ln -sf /var/guix/profiles/per-user/root/current-guix \
- ~root/.config/guix/current
- @end example
- Source @file{etc/profile} to augment @env{PATH} and other relevant
- environment variables:
- @example
- # GUIX_PROFILE="`echo ~root`/.config/guix/current" ; \
- source $GUIX_PROFILE/etc/profile
- @end example
- @item
- Create the group and user accounts for build users as explained below
- (@pxref{Build Environment Setup}).
- @item
- Run the daemon, and set it to automatically start on boot.
- If your host distro uses the systemd init system, this can be achieved
- with these commands:
- @c Versions of systemd that supported symlinked service files are not
- @c yet widely deployed, so we should suggest that users copy the service
- @c files into place.
- @c
- @c See this thread for more information:
- @c https://lists.gnu.org/archive/html/guix-devel/2017-01/msg01199.html
- @example
- # cp ~root/.config/guix/current/lib/systemd/system/gnu-store.mount \
- ~root/.config/guix/current/lib/systemd/system/guix-daemon.service \
- /etc/systemd/system/
- # systemctl enable --now gnu-store.mount guix-daemon
- @end example
- You may also want to arrange for @command{guix gc} to run periodically:
- @example
- # cp ~root/.config/guix/current/lib/systemd/system/guix-gc.service \
- ~root/.config/guix/current/lib/systemd/system/guix-gc.timer \
- /etc/systemd/system/
- # systemctl enable --now guix-gc.timer
- @end example
- You may want to edit @file{guix-gc.service} to adjust the command line
- options to fit your needs (@pxref{Invoking guix gc}).
- If your host distro uses the Upstart init system:
- @example
- # initctl reload-configuration
- # cp ~root/.config/guix/current/lib/upstart/system/guix-daemon.conf \
- /etc/init/
- # start guix-daemon
- @end example
- Otherwise, you can still start the daemon manually with:
- @example
- # ~root/.config/guix/current/bin/guix-daemon \
- --build-users-group=guixbuild
- @end example
- @item
- Make the @command{guix} command available to other users on the machine,
- for instance with:
- @example
- # mkdir -p /usr/local/bin
- # cd /usr/local/bin
- # ln -s /var/guix/profiles/per-user/root/current-guix/bin/guix
- @end example
- It is also a good idea to make the Info version of this manual available
- there:
- @example
- # mkdir -p /usr/local/share/info
- # cd /usr/local/share/info
- # for i in /var/guix/profiles/per-user/root/current-guix/share/info/* ;
- do ln -s $i ; done
- @end example
- That way, assuming @file{/usr/local/share/info} is in the search path,
- running @command{info guix} will open this manual (@pxref{Other Info
- Directories,,, texinfo, GNU Texinfo}, for more details on changing the
- Info search path).
- @item
- @cindex substitutes, authorization thereof
- To use substitutes from @code{@value{SUBSTITUTE-SERVER-1}},
- @code{@value{SUBSTITUTE-SERVER-2}} or a mirror (@pxref{Substitutes}),
- authorize them:
- @example
- # guix archive --authorize < \
- ~root/.config/guix/current/share/guix/@value{SUBSTITUTE-SERVER-1}.pub
- # guix archive --authorize < \
- ~root/.config/guix/current/share/guix/@value{SUBSTITUTE-SERVER-2}.pub
- @end example
- @quotation Note
- If you do not enable substitutes, Guix will end up building
- @emph{everything} from source on your machine, making each installation
- and upgrade very expensive. @xref{On Trusting Binaries}, for a
- discussion of reasons why one might want do disable substitutes.
- @end quotation
- @item
- Each user may need to perform a few additional steps to make their Guix
- environment ready for use, @pxref{Application Setup}.
- @end enumerate
- Voilà, the installation is complete!
- You can confirm that Guix is working by installing a sample package into
- the root profile:
- @example
- # guix install hello
- @end example
- The binary installation tarball can be (re)produced and verified simply
- by running the following command in the Guix source tree:
- @example
- make guix-binary.@var{system}.tar.xz
- @end example
- @noindent
- ...@: which, in turn, runs:
- @example
- guix pack -s @var{system} --localstatedir \
- --profile-name=current-guix guix
- @end example
- @xref{Invoking guix pack}, for more info on this handy tool.
- @node Requirements
- @section Requirements
- This section lists requirements when building Guix from source. The
- build procedure for Guix is the same as for other GNU software, and is
- not covered here. Please see the files @file{README} and @file{INSTALL}
- in the Guix source tree for additional details.
- @cindex official website
- GNU Guix is available for download from its website at
- @url{https://www.gnu.org/software/guix/}.
- GNU Guix depends on the following packages:
- @itemize
- @item @url{https://gnu.org/software/guile/, GNU Guile}, version 3.0.x,
- version 3.0.3 or later;
- @item @url{https://notabug.org/cwebber/guile-gcrypt, Guile-Gcrypt}, version
- 0.1.0 or later;
- @item
- @uref{https://gitlab.com/gnutls/guile/, Guile-GnuTLS} (@pxref{Guile
- Preparations, how to install the GnuTLS bindings for Guile,,
- gnutls-guile, GnuTLS-Guile})@footnote{The Guile bindings to
- @uref{https://gnutls.org/, GnuTLS} were distributed as part of GnuTLS
- until version 3.7.8 included.};
- @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
- @cindex localstatedir
- @cindex system configuration directory
- @cindex sysconfdir
- 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}). The configuration
- directory should also be configured by setting the @option{--sysconfdir}
- option to the @file{/etc} value, which is the location used by Guix to
- store for example the access control list of authorized machines and the
- definition of offload machines.
- @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,
- copying the @file{@var{prefix}/lib/systemd/system/guix-daemon.service}
- file to @file{/etc/systemd/system} will ensure that
- @command{guix-daemon} is automatically started. Similarly, if your
- machine uses the Upstart init system, copy the
- @file{@var{prefix}/lib/upstart/system/guix-daemon.conf}
- file to @file{/etc/init}.}:
- @example
- # guix-daemon --build-users-group=guixbuild
- @end example
- @cindex chroot
- @noindent
- This way, the daemon starts build processes in a chroot, under one of
- the @code{guixbuilder} users. On GNU/Linux, by default, the chroot
- environment contains nothing but:
- @c Keep this list in sync with libstore/build.cc! -----------------------
- @itemize
- @item
- a minimal @code{/dev} directory, created mostly independently from the
- host @code{/dev}@footnote{``Mostly'', because while the set of files
- that appear in the chroot's @code{/dev} is fixed, most of these files
- can only be created if the host has them.};
- @item
- the @code{/proc} directory; it only shows the processes of the container
- since a separate PID name space is used;
- @item
- @file{/etc/passwd} with an entry for the current user and an entry for
- user @file{nobody};
- @item
- @file{/etc/group} with an entry for the user's group;
- @item
- @file{/etc/hosts} with an entry that maps @code{localhost} to
- @code{127.0.0.1};
- @item
- a writable @file{/tmp} directory.
- @end itemize
- The chroot does not contain a @file{/home} directory, and the @env{HOME}
- environment variable is set to the non-existent
- @file{/homeless-shelter}. This helps to highlight inappropriate uses of
- @env{HOME} in the build scripts of packages.
- You can influence the directory where the daemon stores build trees
- @i{via} the @env{TMPDIR} environment variable. However, the build tree
- within the chroot is always called @file{/tmp/guix-build-@var{name}.drv-0},
- where @var{name} is the derivation name---e.g., @code{coreutils-8.24}.
- This way, the value of @env{TMPDIR} does not leak inside build
- environments, which avoids discrepancies in cases where build processes
- capture the name of their build tree.
- @vindex http_proxy
- @vindex https_proxy
- The daemon also honors the @env{http_proxy} and @env{https_proxy}
- environment variables for HTTP and HTTPS downloads it performs, be it
- for fixed-output derivations (@pxref{Derivations}) or for substitutes
- (@pxref{Substitutes}).
- If you are installing Guix as an unprivileged user, it is still possible
- to run @command{guix-daemon} provided you pass @option{--disable-chroot}.
- However, build processes will not be isolated from one another, and not
- from the rest of the system. Thus, build processes may interfere with
- each other, and may access programs, libraries, and other files
- available on the system---making it much harder to view them as
- @emph{pure} functions.
- @node Daemon Offload Setup
- @subsection Using the Offload Facility
- @cindex offloading
- @cindex build hook
- When desired, the build daemon can @dfn{offload} derivation builds to
- other machines running Guix, using the @code{offload} @dfn{build
- hook}@footnote{This feature is available only when
- @uref{https://github.com/artyom-poptsov/guile-ssh, Guile-SSH} is
- present.}. When that feature is enabled, a list of user-specified build
- machines is read from @file{/etc/guix/machines.scm}; every time a build
- is requested, for instance via @code{guix build}, the daemon attempts to
- offload it to one of the machines that satisfy the constraints of the
- derivation, in particular its system types---e.g., @code{x86_64-linux}.
- A single machine can have multiple system types, either because its
- architecture natively supports it, via emulation
- (@pxref{transparent-emulation-qemu, Transparent Emulation with QEMU}),
- or both. Missing prerequisites for the build are
- copied over SSH to the target machine, which then proceeds with the
- build; upon success the output(s) of the build are copied back to the
- initial machine. The offload facility comes with a basic scheduler that
- attempts to select the best machine. The best machine is chosen among
- the available machines based on criteria such as:
- @enumerate
- @item
- The availability of a build slot. A build machine can have as many
- build slots (connections) as the value of the @code{parallel-builds}
- field of its @code{build-machine} object.
- @item
- Its relative speed, as defined via the @code{speed} field of its
- @code{build-machine} object.
- @item
- Its load. The normalized machine load must be lower than a threshold
- value, configurable via the @code{overload-threshold} field of its
- @code{build-machine} object.
- @item
- Disk space availability. More than a 100 MiB must be available.
- @end enumerate
- The @file{/etc/guix/machines.scm} file typically looks like this:
- @lisp
- (list (build-machine
- (name "eightysix.example.org")
- (systems (list "x86_64-linux" "i686-linux"))
- (host-key "ssh-ed25519 AAAAC3Nza@dots{}")
- (user "bob")
- (speed 2.)) ;incredibly fast!
- (build-machine
- (name "armeight.example.org")
- (systems (list "aarch64-linux"))
- (host-key "ssh-rsa AAAAB3Nza@dots{}")
- (user "alice")
- ;; Remember 'guix offload' is spawned by
- ;; 'guix-daemon' as root.
- (private-key "/root/.ssh/identity-for-guix")))
- @end lisp
- @noindent
- In the example above we specify a list of two build machines, one for
- the @code{x86_64} and @code{i686} architectures and one for the
- @code{aarch64} architecture.
- In fact, this file is---not surprisingly!---a Scheme file that is
- evaluated when the @code{offload} hook is started. Its return value
- must be a list of @code{build-machine} objects. While this example
- shows a fixed list of build machines, one could imagine, say, using
- DNS-SD to return a list of potential build machines discovered in the
- local network (@pxref{Introduction, Guile-Avahi,, guile-avahi, Using
- Avahi in Guile Scheme Programs}). The @code{build-machine} data type is
- detailed below.
- @deftp {Data Type} build-machine
- This data type represents build machines to which the daemon may offload
- builds. The important fields are:
- @table @code
- @item name
- The host name of the remote machine.
- @item systems
- The system types the remote machine supports---e.g., @code{(list
- "x86_64-linux" "i686-linux")}.
- @item user
- The user account on the remote machine to use when connecting 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.8})
- 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
- @quotation Note
- This key pair is not related to the SSH key pair that was previously
- mentioned in the description of the @code{build-machine} data type.
- @end quotation
- @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
- @quotation Note
- The @code{guix-install.sh} binary installation script offers to perform
- the steps below for you (@pxref{Binary Installation}).
- @end quotation
- To install the policy run this command as root:
- @example
- semodule -i /var/guix/profiles/per-user/root/current-guix/share/selinux/guix-daemon.cil
- @end example
- Then, as root, relabel the file system, possibly after making it
- writable:
- @example
- mount -o remount,rw /gnu/store
- restorecon -R /gnu /var/guix
- @end example
- At this point you can start or restart @command{guix-daemon}; on a
- distribution that uses systemd as its service manager, you can do that
- with:
- @example
- systemctl restart guix-daemon
- @end example
- 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
- @file{$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}
- @cindex @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
- @cindex socket activation, for @command{guix-daemon}
- This daemon can also be started following the systemd ``socket
- activation'' protocol (@pxref{Service De- and Constructors,
- @code{make-systemd-constructor},, shepherd, The GNU Shepherd Manual}).
- For details on how to set it up, @pxref{Setting Up the Daemon}.
- @cindex chroot
- @cindex container, build environment
- @cindex build environment
- @cindex reproducible builds
- By default, @command{guix-daemon} launches build processes under
- different UIDs, taken from the build group specified with
- @option{--build-users-group}. In addition, each build process is run in a
- chroot environment that only contains the subset of the store that the
- build process depends on, as specified by its derivation
- (@pxref{Programming Interface, derivation}), plus a set of specific
- system directories. By default, the latter contains @file{/dev} and
- @file{/dev/pts}. Furthermore, on GNU/Linux, the build environment is a
- @dfn{container}: in addition to having its own file system tree, it has
- a separate mount name space, its own PID name space, network name space,
- etc. This helps achieve reproducible builds (@pxref{Features}).
- When the daemon performs a build on behalf of the user, it creates a
- build directory under @file{/tmp} or under the directory specified by
- its @env{TMPDIR} environment variable. This directory is shared with
- the container for the duration of the build, though within the container,
- the build tree is always called @file{/tmp/guix-build-@var{name}.drv-0}.
- The build directory is automatically deleted upon completion, unless the
- build failed and the client specified @option{--keep-failed}
- (@pxref{Common Build Options, @option{--keep-failed}}).
- The daemon listens for connections and spawns one sub-process for each session
- started by a client (one of the @command{guix} sub-commands). The
- @command{guix processes} command allows you to get an overview of the activity
- on your system by viewing each of the active sessions and clients.
- @xref{Invoking guix processes}, for more information.
- The following command-line options are supported:
- @table @code
- @item --build-users-group=@var{group}
- Take users from @var{group} to run build processes (@pxref{Setting Up
- the Daemon, build users}).
- @item --no-substitutes
- @cindex substitutes
- Do not use substitutes for build products. That is, always build things
- locally instead of allowing downloads of pre-built binaries
- (@pxref{Substitutes}).
- When the daemon runs with @option{--no-substitutes}, clients can still
- explicitly enable substitution @i{via} the @code{set-build-options}
- remote procedure call (@pxref{The Store}).
- @anchor{daemon-substitute-urls}
- @item --substitute-urls=@var{urls}
- Consider @var{urls} the default whitespace-separated list of substitute
- source URLs. When this option is omitted,
- @indicateurl{@value{SUBSTITUTE-URLS}} is used.
- This means that substitutes may be downloaded from @var{urls}, as long
- as they are signed by a trusted signature (@pxref{Substitutes}).
- @xref{Getting Substitutes from Other Servers}, for more information on
- how to configure the daemon to get substitutes from other servers.
- @cindex offloading
- @item --no-offload
- Do not use offload builds to other machines (@pxref{Daemon Offload
- Setup}). That is, always build things locally instead of offloading
- builds to remote machines.
- @item --cache-failures
- Cache build failures. By default, only successful builds are cached.
- When this option is used, @command{guix gc --list-failures} can be used
- to query the set of store items marked as failed; @command{guix gc
- --clear-failures} removes store items from the set of cached failures.
- @xref{Invoking guix gc}.
- @item --cores=@var{n}
- @itemx -c @var{n}
- Use @var{n} CPU cores to build each derivation; @code{0} means as many
- as available.
- The default value is @code{0}, but it may be overridden by clients, such
- as the @option{--cores} option of @command{guix build} (@pxref{Invoking
- guix build}).
- The effect is to define the @env{NIX_BUILD_CORES} environment variable
- in the build process, which can then use it to exploit internal
- parallelism---for instance, by running @code{make -j$NIX_BUILD_CORES}.
- @item --max-jobs=@var{n}
- @itemx -M @var{n}
- Allow at most @var{n} build jobs in parallel. The default value is
- @code{1}. Setting it to @code{0} means that no builds will be performed
- locally; instead, the daemon will offload builds (@pxref{Daemon Offload
- Setup}), or simply fail.
- @item --max-silent-time=@var{seconds}
- When the build or substitution process remains silent for more than
- @var{seconds}, terminate it and report a build failure.
- The default value is @code{0}, which disables the timeout.
- The value specified here can be overridden by clients (@pxref{Common
- Build Options, @option{--max-silent-time}}).
- @item --timeout=@var{seconds}
- Likewise, when the build or substitution process lasts for more than
- @var{seconds}, terminate it and report a build failure.
- The default value is @code{0}, which disables the timeout.
- The value specified here can be overridden by clients (@pxref{Common
- Build Options, @option{--timeout}}).
- @item --rounds=@var{N}
- Build each derivation @var{n} times in a row, and raise an error if
- consecutive build results are not bit-for-bit identical. Note that this
- setting can be overridden by clients such as @command{guix build}
- (@pxref{Invoking guix build}).
- When used in conjunction with @option{--keep-failed}, the differing
- output is kept in the store, under @file{/gnu/store/@dots{}-check}.
- This makes it easy to look for differences between the two results.
- @item --debug
- Produce debugging output.
- This is useful to debug daemon start-up issues, but then it may be
- overridden by clients, for example the @option{--verbosity} option of
- @command{guix build} (@pxref{Invoking guix build}).
- @item --chroot-directory=@var{dir}
- Add @var{dir} to the build chroot.
- Doing this may change the result of build processes---for instance if
- they use optional dependencies found in @var{dir} when it is available,
- and not otherwise. For that reason, it is not recommended to do so.
- Instead, make sure that each derivation declares all the inputs that it
- needs.
- @item --disable-chroot
- Disable chroot builds.
- Using this option is not recommended since, again, it would allow build
- processes to gain access to undeclared dependencies. It is necessary,
- though, when @command{guix-daemon} is running under an unprivileged user
- account.
- @item --log-compression=@var{type}
- Compress build logs according to @var{type}, one of @code{gzip},
- @code{bzip2}, or @code{none}.
- Unless @option{--lose-logs} is used, all the build logs are kept in the
- @var{localstatedir}. To save space, the daemon automatically compresses
- them with gzip by default.
- @item --discover[=yes|no]
- Whether to discover substitute servers on the local network using mDNS
- and DNS-SD.
- This feature is still experimental. However, here are a few
- considerations.
- @enumerate
- @item
- It might be faster/less expensive than fetching from remote servers;
- @item
- There are no security risks, only genuine substitutes will be used
- (@pxref{Substitute Authentication});
- @item
- An attacker advertising @command{guix publish} on your LAN cannot serve
- you malicious binaries, but they can learn what software you’re
- installing;
- @item
- Servers may serve substitute over HTTP, unencrypted, so anyone on the
- LAN can see what software you’re installing.
- @end enumerate
- It is also possible to enable or disable substitute server discovery at
- run-time by running:
- @example
- herd discover guix-daemon on
- herd discover guix-daemon off
- @end example
- @item --disable-deduplication
- @cindex deduplication
- Disable automatic file ``deduplication'' in the store.
- By default, files added to the store are automatically ``deduplicated'':
- if a newly added file is identical to another one found in the store,
- the daemon makes the new file a hard link to the other file. This can
- noticeably reduce disk usage, at the expense of slightly increased
- input/output load at the end of a build process. This option disables
- this optimization.
- @item --gc-keep-outputs[=yes|no]
- Tell whether the garbage collector (GC) must keep outputs of live
- derivations.
- @cindex GC roots
- @cindex garbage collector roots
- When set to @code{yes}, the GC will keep the outputs of any live
- derivation available in the store---the @file{.drv} files. The default
- is @code{no}, meaning that derivation outputs are kept only if they are
- reachable from a GC root. @xref{Invoking guix gc}, for more on GC
- roots.
- @item --gc-keep-derivations[=yes|no]
- Tell whether the garbage collector (GC) must keep derivations
- corresponding to live outputs.
- When set to @code{yes}, as is the case by default, the GC keeps
- derivations---i.e., @file{.drv} files---as long as at least one of their
- outputs is live. This allows users to keep track of the origins of
- items in their store. Setting it to @code{no} saves a bit of disk
- space.
- In this way, setting @option{--gc-keep-derivations} to @code{yes} causes
- liveness to flow from outputs to derivations, and setting
- @option{--gc-keep-outputs} to @code{yes} causes liveness to flow from
- derivations to outputs. When both are set to @code{yes}, the effect is
- to keep all the build prerequisites (the sources, compiler, libraries,
- and other build-time tools) of live objects in the store, regardless of
- whether these prerequisites are reachable from a GC root. This is
- convenient for developers since it saves rebuilds or downloads.
- @item --impersonate-linux-2.6
- On Linux-based systems, impersonate Linux 2.6. This means that the
- kernel's @command{uname} system call will report 2.6 as the release number.
- This might be helpful to build programs that (usually wrongfully) depend
- on the kernel version number.
- @item --lose-logs
- Do not keep build logs. By default they are kept under
- @file{@var{localstatedir}/guix/log}.
- @item --system=@var{system}
- Assume @var{system} as the current system type. By default it is the
- architecture/kernel pair found at configure time, such as
- @code{x86_64-linux}.
- @item --listen=@var{endpoint}
- Listen for connections on @var{endpoint}. @var{endpoint} is interpreted
- as the file name of a Unix-domain socket if it starts with
- @code{/} (slash sign). Otherwise, @var{endpoint} is interpreted as a
- host name or host name and port to listen to. Here are a few examples:
- @table @code
- @item --listen=/gnu/var/daemon
- Listen for connections on the @file{/gnu/var/daemon} Unix-domain socket,
- creating it if needed.
- @item --listen=localhost
- @cindex daemon, remote access
- @cindex remote access to the daemon
- @cindex daemon, cluster setup
- @cindex clusters, daemon setup
- Listen for TCP connections on the network interface corresponding to
- @code{localhost}, on port 44146.
- @item --listen=128.0.0.42:1234
- Listen for TCP connections on the network interface corresponding to
- @code{128.0.0.42}, on port 1234.
- @end table
- This option can be repeated multiple times, in which case
- @command{guix-daemon} accepts connections on all the specified
- endpoints. Users can tell client commands what endpoint to connect to
- by setting the @env{GUIX_DAEMON_SOCKET} environment variable
- (@pxref{The Store, @env{GUIX_DAEMON_SOCKET}}).
- @quotation Note
- The daemon protocol is @emph{unauthenticated and unencrypted}. Using
- @option{--listen=@var{host}} is suitable on local networks, such as
- clusters, where only trusted nodes may connect to the build daemon. In
- other cases where remote access to the daemon is needed, we recommend
- using Unix-domain sockets along with SSH.
- @end quotation
- When @option{--listen} is omitted, @command{guix-daemon} listens for
- connections on the Unix-domain socket located at
- @file{@var{localstatedir}/guix/daemon-socket/socket}.
- @end table
- @node Application Setup
- @section Application Setup
- @cindex foreign distro
- When using Guix on top of GNU/Linux distribution other than Guix System---a
- so-called @dfn{foreign distro}---a few additional steps are needed to
- get everything in place. Here are some of them.
- @subsection Locales
- @anchor{locales-and-locpath}
- @cindex locales, when not on Guix System
- @vindex LOCPATH
- @vindex GUIX_LOCPATH
- Packages installed @i{via} Guix will not use the locale data of the
- host system. Instead, you must first install one of the locale packages
- available with Guix and then define the @env{GUIX_LOCPATH} environment
- variable:
- @example
- $ guix install glibc-locales
- $ export GUIX_LOCPATH=$HOME/.guix-profile/lib/locale
- @end example
- Note that the @code{glibc-locales} package contains data for all the
- locales supported by the GNU@tie{}libc and weighs in at around
- 930@tie{}MiB@footnote{The size of the @code{glibc-locales} package is
- reduced down to about 213@tie{}MiB with store deduplication and further
- down to about 67@tie{}MiB when using a zstd-compressed Btrfs file
- system.}. If you only need a few locales, you can define your custom
- locales package via the @code{make-glibc-utf8-locales} procedure from
- the @code{(gnu packages base)} module. The following example defines a
- package containing the various Canadian UTF-8 locales known to the
- GNU@tie{}libc, that weighs around 14@tie{}MiB:
- @lisp
- (use-modules (gnu packages base))
- (define my-glibc-locales
- (make-glibc-utf8-locales
- glibc
- #:locales (list "en_CA" "fr_CA" "ik_CA" "iu_CA" "shs_CA")
- #:name "glibc-canadian-utf8-locales"))
- @end lisp
- The @env{GUIX_LOCPATH} variable plays a role similar to @env{LOCPATH}
- (@pxref{Locale Names, @env{LOCPATH},, libc, The GNU C Library Reference
- Manual}). There are two important differences though:
- @enumerate
- @item
- @env{GUIX_LOCPATH} is honored only by the libc in Guix, and not by the libc
- provided by foreign distros. Thus, using @env{GUIX_LOCPATH} allows you
- to make sure the programs of the foreign distro will not end up loading
- incompatible locale data.
- @item
- libc suffixes each entry of @env{GUIX_LOCPATH} with @code{/X.Y}, where
- @code{X.Y} is the libc version---e.g., @code{2.22}. This means that,
- should your Guix profile contain a mixture of programs linked against
- different libc version, each libc version will only try to load locale
- data in the right format.
- @end enumerate
- This is important because the locale data format used by different libc
- versions may be incompatible.
- @subsection Name Service Switch
- @cindex name service switch, glibc
- @cindex NSS (name service switch), glibc
- @cindex @abbr{nscd, name service cache daemon}
- 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}).
- @quotation Note
- Emacs can now compile packages natively. Under the default
- configuration, this means that Emacs packages will now be
- just-in-time (JIT) compiled as you use them, and the results
- stored in a subdirectory of your @code{user-emacs-directory}.
- Furthermore, the build system for Emacs packages transparently
- supports native compilation, but note, that
- @code{emacs-minimal}---the default Emacs for building
- packages---has been configured without native compilation.
- To natively compile your emacs packages ahead of time, use a
- transformation like @option{--with-input=emacs-minimal=emacs}.
- @end quotation
- @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}}).
- The installer warns you early on if it detects devices that are known
- @emph{not} to work due to the lack of free firmware or free drivers.
- @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}.
- Sadly, on some machines, the installation medium cannot be properly
- booted and you only see a black screen after booting even after you
- waited for ten minutes. This may indicate that your machine cannot run
- Guix System; perhaps you instead want to install Guix on a foreign
- distro (@pxref{Binary Installation}). But don't give up just yet; a
- possible workaround is pressing the @kbd{e} key in the GRUB boot menu
- and appending @option{nomodeset} to the Linux bootline.
- Sometimes the black screen issue can also be resolved by connecting a
- different display.
- @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 is also a full-blown
- Guix System. This 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.
- @anchor{manual-installation-networking}
- @subsubsection Networking
- Run the following command to see what your network interfaces are called:
- @example
- ifconfig -a
- @end example
- @noindent
- @dots{} or, using the GNU/Linux-specific @command{ip} command:
- @example
- ip address
- @end example
- @c https://cgit.freedesktop.org/systemd/systemd/tree/src/udev/udev-builtin-net_id.c#n20
- Wired interfaces have a name starting with @samp{e}; for example, the
- interface corresponding to the first on-board Ethernet controller is
- called @samp{eno1}. Wireless interfaces have a name starting with
- @samp{w}, like @samp{w1p2s0}.
- @table @asis
- @item Wired connection
- To configure a wired network run the following command, substituting
- @var{interface} with the name of the wired interface you want to use.
- @example
- ifconfig @var{interface} up
- @end example
- @noindent
- @dots{} or, using the GNU/Linux-specific @command{ip} command:
- @example
- ip link set @var{interface} up
- @end example
- @item Wireless connection
- @cindex wireless
- @cindex WiFi
- To configure wireless networking, you can create a configuration file
- for the @command{wpa_supplicant} configuration tool (its location is not
- important) using one of the available text editors such as
- @command{nano}:
- @example
- nano wpa_supplicant.conf
- @end example
- As an example, the following stanza can go to this file and will work
- for many wireless networks, provided you give the actual SSID and
- passphrase for the network you are connecting to:
- @example
- network=@{
- ssid="@var{my-ssid}"
- key_mgmt=WPA-PSK
- psk="the network's secret passphrase"
- @}
- @end example
- Start the wireless service and run it in the background with the
- following command (substitute @var{interface} with the name of the
- network interface you want to use):
- @example
- wpa_supplicant -c wpa_supplicant.conf -i @var{interface} -B
- @end example
- Run @command{man wpa_supplicant} for more information.
- @end table
- @cindex DHCP
- At this point, you need to acquire an IP address. On a network where IP
- addresses are automatically assigned @i{via} DHCP, you can run:
- @example
- dhclient -v @var{interface}
- @end example
- Try to ping a server to see if networking is up and running:
- @example
- ping -c 3 gnu.org
- @end example
- Setting up network access is almost always a requirement because the
- image does not contain all the software and tools that may be needed.
- @cindex proxy, during system installation
- If you need HTTP and HTTPS access to go through a proxy, run the
- following command:
- @example
- herd set-http-proxy guix-daemon @var{URL}
- @end example
- @noindent
- where @var{URL} is the proxy URL, for example
- @code{http://example.org:8118}.
- @cindex installing over SSH
- If you want to, you can continue the installation remotely by starting
- an SSH server:
- @example
- herd start ssh-daemon
- @end example
- Make sure to either set a password with @command{passwd}, or configure
- OpenSSH public key authentication before logging in.
- @subsubsection Disk Partitioning
- Unless this has already been done, the next step is to partition, and
- then format the target partition(s).
- The installation image includes several partitioning tools, including
- Parted (@pxref{Overview,,, parted, GNU Parted User Manual}),
- @command{fdisk}, and @command{cfdisk}. Run it and set up your disk with
- the partition layout you want:
- @example
- cfdisk
- @end example
- If your disk uses the GUID Partition Table (GPT) format and you plan to
- install BIOS-based GRUB (which is the default), make sure a BIOS Boot
- Partition is available (@pxref{BIOS installation,,, grub, GNU GRUB
- manual}).
- @cindex EFI, installation
- @cindex UEFI, installation
- @cindex ESP, EFI system partition
- If you instead wish to use EFI-based GRUB, a FAT32 @dfn{EFI System Partition}
- (ESP) is required. This partition can be mounted at @file{/boot/efi} for
- instance and must have the @code{esp} flag set. E.g., for @command{parted}:
- @example
- parted /dev/sda set 1 esp on
- @end example
- @quotation Note
- @vindex grub-bootloader
- @vindex grub-efi-bootloader
- Unsure whether to use EFI- or BIOS-based GRUB? If the directory
- @file{/sys/firmware/efi} exists in the installation image, then you should
- probably perform an EFI installation, using @code{grub-efi-bootloader}.
- Otherwise you should use the BIOS-based GRUB, known as
- @code{grub-bootloader}. @xref{Bootloader Configuration}, for more info on
- bootloaders.
- @end quotation
- Once you are done partitioning the target hard disk drive, you have to
- create a file system on the relevant partition(s)@footnote{Currently
- Guix System only supports ext4, btrfs, JFS, F2FS, and XFS file systems. In
- particular, code that reads file system UUIDs and labels only works for these
- file system types.}. For the ESP, if you have one and assuming it is
- @file{/dev/sda1}, run:
- @example
- mkfs.fat -F32 /dev/sda1
- @end example
- For the root file system, ext4 is the most widely used format. Other
- file systems, such as Btrfs, support compression, which is reported to
- nicely complement file deduplication that the daemon performs
- independently of the file system (@pxref{Invoking guix-daemon,
- deduplication}).
- Preferably, assign file systems a label so that you can easily and
- reliably refer to them in @code{file-system} declarations (@pxref{File
- Systems}). This is typically done using the @code{-L} option of
- @command{mkfs.ext4} and related commands. So, assuming the target root
- partition lives at @file{/dev/sda2}, a file system with the label
- @code{my-root} can be created with:
- @example
- mkfs.ext4 -L my-root /dev/sda2
- @end example
- @cindex encrypted disk
- If you are instead planning to encrypt the root partition, you can use
- the Cryptsetup/LUKS utilities to do that (see @inlinefmtifelse{html,
- @uref{https://linux.die.net/man/8/cryptsetup, @code{man cryptsetup}},
- @code{man cryptsetup}} for more information).
- @quotation Warning
- Note that GRUB can unlock LUKS2 devices since version 2.06, but only
- supports the PBKDF2 key derivation function, which is not the default
- for @command{cryptsetup luksFormat}. You can check which key derivation
- function is being used by a device by running @command{cryptsetup
- luksDump @var{device}}, and looking for the PBKDF field of your
- keyslots.
- @end quotation
- Assuming you want to store the root partition on @file{/dev/sda2}, the
- command sequence to format it as a LUKS2 partition would be along these
- lines:
- @example
- cryptsetup luksFormat --type luks2 --pbkdf pbkdf2 /dev/sda2
- cryptsetup open /dev/sda2 my-partition
- mkfs.ext4 -L my-root /dev/mapper/my-partition
- @end example
- Once that is done, mount the target file system under @file{/mnt}
- with a command like (again, assuming @code{my-root} is the label of the
- root file system):
- @example
- mount LABEL=my-root /mnt
- @end example
- Also mount any other file systems you would like to use on the target
- system relative to this path. If you have opted for @file{/boot/efi} as an
- EFI mount point for example, mount it at @file{/mnt/boot/efi} now so it is
- found by @code{guix system init} afterwards.
- Finally, if you plan to use one or more swap partitions (@pxref{Swap
- Space}), make sure to initialize them with @command{mkswap}. Assuming
- you have one swap partition on @file{/dev/sda3}, you would run:
- @example
- mkswap /dev/sda3
- swapon /dev/sda3
- @end example
- Alternatively, you may use a swap file. For example, assuming that in
- the new system you want to use the file @file{/swapfile} as a swap file,
- you would run@footnote{This example will work for many types of file
- systems (e.g., ext4). However, for copy-on-write file systems (e.g.,
- btrfs), the required steps may be different. For details, see the
- manual pages for @command{mkswap} and @command{swapon}.}:
- @example
- # This is 10 GiB of swap space. Adjust "count" to change the size.
- dd if=/dev/zero of=/mnt/swapfile bs=1MiB count=10240
- # For security, make the file readable and writable only by root.
- chmod 600 /mnt/swapfile
- mkswap /mnt/swapfile
- swapon /mnt/swapfile
- @end example
- Note that if you have encrypted the root partition and created a swap
- file in its file system as described above, then the encryption also
- protects the swap file, just like any other file in that file system.
- @node Proceeding with the Installation
- @subsection Proceeding with the Installation
- With the target partitions ready and the target root mounted on
- @file{/mnt}, we're ready to go. First, run:
- @example
- herd start cow-store /mnt
- @end example
- This makes @file{/gnu/store} copy-on-write, such that packages added to it
- during the installation phase are written to the target disk on @file{/mnt}
- rather than kept in memory. This is necessary because the first phase of
- the @command{guix system init} command (see below) entails downloads or
- builds to @file{/gnu/store} which, initially, is an in-memory file system.
- Next, you have to edit a file and
- provide the declaration of the operating system to be installed. To
- that end, the installation system comes with three text editors. We
- recommend GNU nano (@pxref{Top,,, nano, GNU nano Manual}), which
- supports syntax highlighting and parentheses matching; other editors
- include mg (an Emacs clone), and
- nvi (a clone of the original BSD @command{vi} editor).
- We strongly recommend storing that file on the target root file system, say,
- as @file{/mnt/etc/config.scm}. Failing to do that, you will have lost your
- configuration file once you have rebooted into the newly-installed system.
- @xref{Using the Configuration System}, for an overview of the
- configuration file. The example configurations discussed in that
- section are available under @file{/etc/configuration} in the
- installation image. Thus, to get started with a system configuration
- providing a graphical display server (a ``desktop'' system), you can run
- something along these lines:
- @example
- # mkdir /mnt/etc
- # cp /etc/configuration/desktop.scm /mnt/etc/config.scm
- # nano /mnt/etc/config.scm
- @end example
- You should pay attention to what your configuration file contains, and
- in particular:
- @itemize
- @item
- Make sure the @code{bootloader-configuration} form refers to the targets
- you want to install GRUB on. It should mention @code{grub-bootloader}
- if you are installing GRUB in the legacy way, or
- @code{grub-efi-bootloader} for newer UEFI systems. For legacy systems,
- the @code{targets} field contain the names of the devices, like
- @code{(list "/dev/sda")}; for UEFI systems it names the paths to mounted
- EFI partitions, like @code{(list "/boot/efi")}; do make sure the paths
- are currently mounted and a @code{file-system} entry is specified in
- your configuration.
- @item
- Be sure that your file system labels match the value of their respective
- @code{device} fields in your @code{file-system} configuration, assuming
- your @code{file-system} configuration uses the @code{file-system-label}
- procedure in its @code{device} field.
- @item
- If there are encrypted or RAID partitions, make sure to add a
- @code{mapped-devices} field to describe them (@pxref{Mapped Devices}).
- @end itemize
- Once you are done preparing the configuration file, the new system must
- be initialized (remember that the target root file system is mounted
- under @file{/mnt}):
- @example
- guix system init /mnt/etc/config.scm /mnt
- @end example
- @noindent
- This copies all the necessary files and installs GRUB on
- @file{/dev/sdX}, unless you pass the @option{--no-bootloader} option. For
- more information, @pxref{Invoking guix system}. This command may trigger
- downloads or builds of missing packages, which can take some time.
- Once that command has completed---and hopefully succeeded!---you can run
- @command{reboot} and boot into the new system. The @code{root} password
- in the new system is initially empty; other users' passwords need to be
- initialized by running the @command{passwd} command as @code{root},
- unless your configuration specifies otherwise
- (@pxref{user-account-password, user account passwords}).
- @xref{After System Installation}, for what's next!
- @node After System Installation
- @section After System Installation
- Success, you've now booted into Guix System! From then on, you can update the
- system whenever you want by running, say:
- @example
- guix pull
- sudo guix system reconfigure /etc/config.scm
- @end example
- @noindent
- This builds a new system generation with the latest packages and services
- (@pxref{Invoking guix system}). We recommend doing that regularly so that
- your system includes the latest security updates (@pxref{Security Updates}).
- @c See <https://lists.gnu.org/archive/html/guix-devel/2019-01/msg00268.html>.
- @quotation Note
- @cindex sudo vs. @command{guix pull}
- Note that @command{sudo guix} runs your user's @command{guix} command and
- @emph{not} root's, because @command{sudo} leaves @env{PATH} unchanged. To
- explicitly run root's @command{guix}, type @command{sudo -i guix @dots{}}.
- The difference matters here, because @command{guix pull} updates
- the @command{guix} command and package definitions only for the user it is run
- as. This means that if you choose to use @command{guix system reconfigure} in
- root's login shell, you'll need to @command{guix pull} separately.
- @end quotation
- Now, @pxref{Getting Started}, and
- join us on @code{#guix} on the Libera Chat IRC network or on
- @email{guix-devel@@gnu.org} to share your experience!
- @node Installing Guix in a VM
- @section Installing Guix in a Virtual Machine
- @cindex virtual machine, Guix System installation
- @cindex virtual private server (VPS)
- @cindex VPS (virtual private server)
- If you'd like to install Guix System in a virtual machine (VM) or on a
- virtual private server (VPS) rather than on your beloved machine, this
- section is for you.
- To boot a @uref{https://qemu.org/,QEMU} VM for installing Guix System in a
- disk image, follow these steps:
- @enumerate
- @item
- First, retrieve and decompress the Guix system installation image as
- described previously (@pxref{USB Stick and DVD Installation}).
- @item
- Create a disk image that will hold the installed system. To make a
- qcow2-formatted disk image, use the @command{qemu-img} command:
- @example
- qemu-img create -f qcow2 guix-system.img 50G
- @end example
- The resulting file will be much smaller than 50 GB (typically less than
- 1 MB), but it will grow as the virtualized storage device is filled up.
- @item
- Boot the USB installation image in an VM:
- @example
- qemu-system-x86_64 -m 1024 -smp 1 -enable-kvm \
- -nic user,model=virtio-net-pci -boot menu=on,order=d \
- -drive file=guix-system.img \
- -drive media=cdrom,file=guix-system-install-@value{VERSION}.@var{system}.iso
- @end example
- @code{-enable-kvm} is optional, but significantly improves performance,
- @pxref{Running Guix in a VM}.
- @item
- You're now root in the VM, proceed with the installation process.
- @xref{Preparing for Installation}, and follow the instructions.
- @end enumerate
- Once installation is complete, you can boot the system that's on your
- @file{guix-system.img} image. @xref{Running Guix in a VM}, for how to do
- that.
- @node Building the Installation Image
- @section Building the Installation Image
- @cindex installation image
- The installation image described above was built using the @command{guix
- system} command, specifically:
- @example
- guix system image -t iso9660 gnu/system/install.scm
- @end example
- Have a look at @file{gnu/system/install.scm} in the source tree,
- and see also @ref{Invoking guix system} for more information
- about the installation image.
- @section Building the Installation Image for ARM Boards
- Many ARM boards require a specific variant of the
- @uref{https://www.denx.de/wiki/U-Boot/, U-Boot} bootloader.
- If you build a disk image and the bootloader is not available otherwise
- (on another boot drive etc), it's advisable to build an image that
- includes the bootloader, specifically:
- @example
- guix system image --system=armhf-linux -e '((@@ (gnu system install) os-with-u-boot) (@@ (gnu system install) installation-os) "A20-OLinuXino-Lime2")'
- @end example
- @code{A20-OLinuXino-Lime2} is the name of the board. If you specify an invalid
- board, a list of possible boards will be printed.
- @c *********************************************************************
- @cindex troubleshooting, guix system
- @cindex guix system troubleshooting
- @node System Troubleshooting Tips
- @chapter System Troubleshooting Tips
- Guix System allows rebooting into a previous generation should the last
- one be malfunctioning, which makes it quite robust against being broken
- irreversibly. This feature depends on GRUB being correctly functioning
- though, which means that if for whatever reasons your GRUB installation
- becomes corrupted during a system reconfiguration, you may not be able
- to easily boot into a previous generation. A technique that can be used
- in this case is to @i{chroot} into your broken system and reconfigure it
- from there. Such technique is explained below.
- @cindex chroot, guix system
- @cindex chrooting, guix system
- @cindex repairing GRUB, via chroot
- @menu
- * Chrooting into an existing system::
- @end menu
- @node Chrooting into an existing system
- @section Chrooting into an existing system
- This section details how to @i{chroot} to an already installed Guix
- System with the aim of reconfiguring it, for example to fix a broken
- GRUB installation. The process is similar to how it would be done on
- other GNU/Linux systems, but there are some Guix System particularities
- such as the daemon and profiles that make it worthy of explaining here.
- @enumerate
- @item
- Obtain a bootable image of Guix System. It is recommended the latest
- development snapshot so the kernel and the tools used are at least as as
- new as those of your installed system; it can be retrieved from the
- @url{https://ci.guix.gnu.org/search/latest/ISO-9660?query=spec:images+status:success+system:x86_64-linux+image.iso,
- https://ci.guix.gnu.org} URL. Follow the @pxref{USB Stick and DVD
- Installation} section for copying it to a bootable media.
- @item
- Boot the image, and proceed with the graphical text-based installer
- until your network is configured. Alternatively, you could configure
- the network manually by following the
- @ref{manual-installation-networking} section. If you get the error
- @samp{RTNETLINK answers: Operation not possible due to RF-kill}, try
- @samp{rfkill list} followed by @samp{rfkill unblock 0}, where @samp{0}
- is your device identifier (ID).
- @item
- Switch to a virtual console (tty) if you haven't already by pressing
- simultaneously the @kbd{Control + Alt + F4} keys. Mount your file
- system at @file{/mnt}. Assuming your root partition is
- @file{/dev/sda2}, you would do:
- @example sh
- mount /dev/sda2 /mnt
- @end example
- @item
- Mount special block devices and Linux-specific directories:
- @example sh
- mount --rbind /proc /mnt/proc
- mount --rbind /sys /mnt/sys
- mount --rbind /dev /mnt/dev
- @end example
- If your system is EFI-based, you must also mount the ESP partition.
- Assuming it is @file{/dev/sda1}, you can do so with:
- @example sh
- mount /dev/sda1 /mnt/boot/efi
- @end example
- @item
- Enter your system via chroot:
- @example sh
- chroot /mnt /bin/sh
- @end example
- @item
- Source the system profile as well as your @var{user} profile to setup
- the environment, where @var{user} is the user name used for the Guix
- System you are attempting to repair:
- @example sh
- source /var/guix/profiles/system/profile/etc/profile
- source /home/@var{user}/.guix-profile/etc/profile
- @end example
- To ensure you are working with the Guix revision you normally would as
- your normal user, also source your current Guix profile:
- @example sh
- source /home/@var{user}/.config/guix/current/etc/profile
- @end example
- @item
- Start a minimal @command{guix-daemon} in the background:
- @example sh
- guix-daemon --build-users-group=guixbuild --disable-chroot &
- @end example
- @item
- Edit your Guix System configuration if needed, then reconfigure with:
- @example sh
- guix system reconfigure your-config.scm
- @end example
- @item
- Finally, you should be good to reboot the system to test your fix.
- @end enumerate
- @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 locate:: Locating packages that provide a file.
- * Invoking guix gc:: Running the garbage collector.
- * Invoking guix pull:: Fetching the latest Guix and distribution.
- * Invoking guix time-machine:: Running an older revision of Guix.
- * Inferiors:: Interacting with another revision of Guix.
- * Invoking guix describe:: Display information about your Guix revision.
- * Invoking guix archive:: Exporting and importing store files.
- @end menu
- @node Features
- @section Features
- Here we assume you've already made your first steps with Guix
- (@pxref{Getting Started}) and would like to get an overview about what's
- going on under the hood.
- When using Guix, each package ends up in the @dfn{package store}, in its
- own directory---something that resembles
- @file{/gnu/store/xxx-package-1.2}, where @code{xxx} is a base32 string.
- Instead of referring to these directories, users have their own
- @dfn{profile}, which points to the packages that they actually want to
- use. These profiles are stored within each user's home directory, at
- @code{$HOME/.guix-profile}.
- For example, @code{alice} installs GCC 4.7.2. As a result,
- @file{/home/alice/.guix-profile/bin/gcc} points to
- @file{/gnu/store/@dots{}-gcc-4.7.2/bin/gcc}. Now, on the same machine,
- @code{bob} had already installed GCC 4.8.0. The profile of @code{bob}
- simply continues to point to
- @file{/gnu/store/@dots{}-gcc-4.8.0/bin/gcc}---i.e., both versions of GCC
- coexist on the same system without any interference.
- The @command{guix package} command is the central tool to manage
- packages (@pxref{Invoking guix package}). It operates on the per-user
- profiles, and can be used @emph{with normal user privileges}.
- @cindex transactions
- The command provides the obvious install, remove, and upgrade
- operations. Each invocation is actually a @emph{transaction}: either
- the specified operation succeeds, or nothing happens. Thus, if the
- @command{guix package} process is terminated during the transaction,
- or if a power outage occurs during the transaction, then the user's
- profile remains in its previous state, and remains usable.
- In addition, any package transaction may be @emph{rolled back}. So, if,
- for example, an upgrade installs a new version of a package that turns
- out to have a serious bug, users may roll back to the previous instance
- of their profile, which was known to work well. Similarly, the global
- system configuration on Guix is subject to
- transactional upgrades and roll-back
- (@pxref{Using the Configuration System}).
- All packages in the package store may be @emph{garbage-collected}.
- Guix can determine which packages are still referenced by user
- profiles, and remove those that are provably no longer referenced
- (@pxref{Invoking guix gc}). Users may also explicitly remove old
- generations of their profile so that the packages they refer to can be
- collected.
- @cindex reproducibility
- @cindex reproducible builds
- Guix takes a @dfn{purely functional} approach to package
- management, as described in the introduction (@pxref{Introduction}).
- Each @file{/gnu/store} package directory name contains a hash of all the
- inputs that were used to build that package---compiler, libraries, build
- scripts, etc. This direct correspondence allows users to make sure a
- given package installation matches the current state of their
- distribution. It also helps maximize @dfn{build reproducibility}:
- thanks to the isolated build environments that are used, a given build
- is likely to yield bit-identical files when performed on different
- machines (@pxref{Invoking guix-daemon, container}).
- @cindex substitutes
- This foundation allows Guix to support @dfn{transparent binary/source
- deployment}. When a pre-built binary for a @file{/gnu/store} item is
- available from an external source---a @dfn{substitute}, Guix just
- downloads it and unpacks it;
- otherwise, it builds the package from source, locally
- (@pxref{Substitutes}). Because build results are usually bit-for-bit
- reproducible, users do not have to trust servers that provide
- substitutes: they can force a local build and @emph{challenge} providers
- (@pxref{Invoking guix challenge}).
- Control over the build environment is a feature that is also useful for
- developers. The @command{guix shell} command allows developers of
- a package to quickly set up the right development environment for their
- package, without having to manually install the dependencies of the
- package into their profile (@pxref{Invoking guix shell}).
- @cindex replication, of software environments
- @cindex provenance tracking, of software artifacts
- All of Guix and its package definitions is version-controlled, and
- @command{guix pull} allows you to ``travel in time'' on the history of Guix
- itself (@pxref{Invoking guix pull}). This makes it possible to replicate a
- Guix instance on a different machine or at a later point in time, which in
- turn allows you to @emph{replicate complete software environments}, while
- retaining precise @dfn{provenance tracking} of the software.
- @node Invoking guix package
- @section Invoking @command{guix package}
- @cindex installing packages
- @cindex removing packages
- @cindex package installation
- @cindex package removal
- @cindex profile
- @cindex @command{guix package}
- 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 a simple package name, such as
- @code{guile}, optionally followed by an at-sign and version number,
- such as @code{guile@@3.0.7} or simply @code{guile@@3.0}. In the latter
- case, the newest version prefixed by @code{3.0} is selected.
- If no version number is specified, the newest available version will be
- selected. In addition, such a @var{package} specification
- 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}).
- Alternatively, a @var{package} can directly specify a store file name
- such as @file{/gnu/store/...-guile-3.0.7}, as produced by, e.g.,
- @code{guix build}.
- @cindex propagated inputs
- Sometimes packages have @dfn{propagated inputs}: these are dependencies
- that automatically get installed along with the required package
- (@pxref{package-propagated-inputs, @code{propagated-inputs} in
- @code{package} objects}, for information about propagated inputs in
- package definitions).
- @anchor{package-cmd-propagated-inputs}
- An example is the GNU MPC library: its C header files refer to those of
- the GNU MPFR library, which in turn refer to those of the GMP library.
- Thus, when installing MPC, the MPFR and GMP libraries also get installed
- in the profile; removing MPC also removes MPFR and GMP---unless they had
- also been explicitly installed by the user.
- Besides, packages sometimes rely on the definition of environment
- variables for their search paths (see explanation of
- @option{--search-paths} below). Any missing or possibly incorrect
- environment variable definitions are reported here.
- @item --install-from-expression=@var{exp}
- @itemx -e @var{exp}
- Install the package @var{exp} evaluates to.
- @var{exp} must be a Scheme expression that evaluates to a
- @code{<package>} object. This option is notably useful to disambiguate
- between same-named variants of a package, with expressions such as
- @code{(@@ (gnu packages base) guile-final)}.
- Note that this option installs the first output of the specified
- package, which may be insufficient when needing a specific output of a
- multiple-output package.
- @item --install-from-file=@var{file}
- @itemx -f @var{file}
- Install the package that the code within @var{file} evaluates to.
- As an example, @var{file} might contain a definition like this
- (@pxref{Defining Packages}):
- @lisp
- @include package-hello.scm
- @end lisp
- Developers may find it useful to include such a @file{guix.scm} file
- in the root of their project source tree that can be used to test
- development snapshots and create reproducible development environments
- (@pxref{Invoking guix shell}).
- The @var{file} may also contain a JSON representation of one or more
- package definitions. Running @code{guix package -f} on
- @file{hello.json} with the following contents would result in installing
- the package @code{greeter} after building @code{myhello}:
- @example
- @verbatiminclude package-hello.json
- @end example
- @item --remove=@var{package} @dots{}
- @itemx -r @var{package} @dots{}
- Remove the specified @var{package}s.
- As for @option{--install}, each @var{package} may specify a version number
- and/or output name in addition to the package name. For instance,
- @samp{-r glibc:debug} would remove the @code{debug} output of
- @code{glibc}.
- @item --upgrade[=@var{regexp} @dots{}]
- @itemx -u [@var{regexp} @dots{}]
- @cindex upgrading packages
- Upgrade all the installed packages. If one or more @var{regexp}s are
- specified, upgrade only installed packages whose name matches a
- @var{regexp}. Also see the @option{--do-not-upgrade} option below.
- Note that this upgrades package to the latest version of packages found
- in the distribution currently installed. To update your distribution,
- you should regularly run @command{guix pull} (@pxref{Invoking guix
- pull}).
- @cindex package transformations, upgrades
- When upgrading, package transformations that were originally applied
- when creating the profile are automatically re-applied (@pxref{Package
- Transformation Options}). For example, assume you first installed Emacs
- from the tip of its development branch with:
- @example
- guix install emacs-next --with-branch=emacs-next=master
- @end example
- Next time you run @command{guix upgrade}, Guix will again pull the tip
- of the Emacs development branch and build @code{emacs-next} from that
- checkout.
- Note that transformation options such as @option{--with-branch} and
- @option{--with-source} depend on external state; it is up to you to
- ensure that they work as expected. You can also discard a
- transformations that apply to a package by running:
- @example
- guix install @var{package}
- @end example
- @item --do-not-upgrade[=@var{regexp} @dots{}]
- When used together with the @option{--upgrade} option, do @emph{not}
- upgrade any packages whose name matches a @var{regexp}. For example, to
- upgrade all packages in the current profile except those containing the
- substring ``emacs'':
- @example
- $ guix package --upgrade . --do-not-upgrade emacs
- @end example
- @item @anchor{profile-manifest}--manifest=@var{file}
- @itemx -m @var{file}
- @cindex profile declaration
- @cindex profile manifest
- Create a new generation of the profile from the manifest object
- returned by the Scheme code in @var{file}. This option can be repeated
- several times, in which case the manifests are concatenated.
- This allows you to @emph{declare} the profile's contents rather than
- constructing it through a sequence of @option{--install} and similar
- commands. The advantage is that @var{file} can be put under version
- control, copied to different machines to reproduce the same profile, and
- so on.
- @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
- @xref{Writing Manifests}, for information on how to write a manifest.
- @xref{export-manifest, @option{--export-manifest}}, to learn how to
- obtain a manifest file from an existing profile.
- @item --roll-back
- @cindex rolling back
- @cindex undoing transactions
- @cindex transactions, undoing
- Roll back to the previous @dfn{generation} of the profile---i.e., undo
- the last transaction.
- When combined with options such as @option{--install}, roll back occurs
- before any other actions.
- When rolling back from the first generation that actually contains
- installed packages, the profile is made to point to the @dfn{zeroth
- generation}, which contains no files apart from its own metadata.
- After having rolled back, installing, removing, or upgrading packages
- overwrites previous future generations. Thus, the history of the
- generations in a profile is always linear.
- @item --switch-generation=@var{pattern}
- @itemx -S @var{pattern}
- @cindex generations
- Switch to a particular generation defined by @var{pattern}.
- @var{pattern} may be either a generation number or a number prefixed
- with ``+'' or ``-''. The latter means: move forward/backward by a
- specified number of generations. For example, if you want to return to
- the latest generation after @option{--roll-back}, use
- @option{--switch-generation=+1}.
- The difference between @option{--roll-back} and
- @option{--switch-generation=-1} is that @option{--switch-generation} will
- not make a zeroth generation, so if a specified generation does not
- exist, the current generation will not be changed.
- @item --search-paths[=@var{kind}]
- @cindex search paths
- Report environment variable definitions, in Bash syntax, that may be
- needed in order to use the set of installed packages. These environment
- variables are used to specify @dfn{search paths} for files used by some
- of the installed packages.
- For example, GCC needs the @env{CPATH} and @env{LIBRARY_PATH}
- environment variables to be defined so it can look for headers and
- libraries in the user's profile (@pxref{Environment Variables,,, gcc,
- Using the GNU Compiler Collection (GCC)}). If GCC and, say, the C
- library are installed in the profile, then @option{--search-paths} will
- suggest setting these variables to @file{@var{profile}/include} and
- @file{@var{profile}/lib}, respectively (@pxref{Search Paths}, for info
- on search path specifications associated with packages.)
- The typical use case is to define these environment variables in the
- shell:
- @example
- $ eval $(guix package --search-paths)
- @end example
- @var{kind} may be one of @code{exact}, @code{prefix}, or @code{suffix},
- meaning that the returned environment variable definitions will either
- be exact settings, or prefixes or suffixes of the current value of these
- variables. When omitted, @var{kind} defaults to @code{exact}.
- This option can also be used to compute the @emph{combined} search paths
- of several profiles. Consider this example:
- @example
- $ guix package -p foo -i guile
- $ guix package -p bar -i guile-json
- $ guix package -p foo -p bar --search-paths
- @end example
- The last command above reports about the @env{GUILE_LOAD_PATH}
- variable, even though, taken individually, neither @file{foo} nor
- @file{bar} would lead to that recommendation.
- @cindex profile, choosing
- @item --profile=@var{profile}
- @itemx -p @var{profile}
- Use @var{profile} instead of the user's default profile.
- @var{profile} must be the name of a file that will be created upon
- completion. Concretely, @var{profile} will be a mere symbolic link
- (``symlink'') pointing to the actual profile where packages are
- installed:
- @example
- $ guix install hello -p ~/code/my-profile
- @dots{}
- $ ~/code/my-profile/bin/hello
- Hello, world!
- @end example
- All it takes to get rid of the profile is to remove this symlink and its
- siblings that point to specific generations:
- @example
- $ rm ~/code/my-profile ~/code/my-profile-*-link
- @end example
- @item --list-profiles
- List all the user's profiles:
- @example
- $ guix package --list-profiles
- /home/charlie/.guix-profile
- /home/charlie/code/my-profile
- /home/charlie/code/devel-profile
- /home/charlie/tmp/test
- @end example
- When running as root, list all the profiles of all the users.
- @cindex collisions, in a profile
- @cindex colliding packages in profiles
- @cindex profile collisions
- @item --allow-collisions
- Allow colliding packages in the new profile. Use at your own risk!
- By default, @command{guix package} reports as an error @dfn{collisions}
- in the profile. Collisions happen when two or more different versions
- or variants of a given package end up in the profile.
- @item --bootstrap
- Use the bootstrap Guile to build the profile. This option is only
- useful to distribution developers.
- @end table
- In addition to these actions, @command{guix package} supports the
- following options to query the current state of a profile, or the
- availability of packages:
- @table @option
- @item --search=@var{regexp}
- @itemx -s @var{regexp}
- @anchor{guix-search}
- @cindex searching for packages
- List the available packages whose name, synopsis, or description matches
- @var{regexp} (in a case-insensitive fashion), sorted by relevance.
- Print all the metadata of matching packages in
- @code{recutils} format (@pxref{Top, GNU recutils databases,, recutils,
- GNU recutils manual}).
- This allows specific fields to be extracted using the @command{recsel}
- command, for instance:
- @example
- $ guix package -s malloc | recsel -p name,version,relevance
- name: jemalloc
- version: 4.5.0
- relevance: 6
- name: glibc
- version: 2.25
- relevance: 1
- name: libgc
- version: 7.6.0
- relevance: 1
- @end example
- Similarly, to show the name of all the packages available under the
- terms of the GNU@tie{}LGPL version 3:
- @example
- $ guix package -s "" | recsel -p name -e 'license ~ "LGPL 3"'
- name: elfutils
- name: gmp
- @dots{}
- @end example
- It is also possible to refine search results using several @code{-s} flags to
- @command{guix package}, or several arguments to @command{guix search}. For
- example, the following command returns a list of board games (this time using
- the @command{guix search} alias):
- @example
- $ guix search '\<board\>' game | recsel -p name
- name: gnubg
- @dots{}
- @end example
- If we were to omit @code{-s game}, we would also get software packages
- that deal with printed circuit boards; removing the angle brackets
- around @code{board} would further add packages that have to do with
- keyboards.
- And now for a more elaborate example. The following command searches
- for cryptographic libraries, filters out Haskell, Perl, Python, and Ruby
- libraries, and prints the name and synopsis of the matching packages:
- @example
- $ guix search crypto library | \
- recsel -e '! (name ~ "^(ghc|perl|python|ruby)")' -p name,synopsis
- @end example
- @noindent
- @xref{Selection Expressions,,, recutils, GNU recutils manual}, for more
- information on @dfn{selection expressions} for @code{recsel -e}.
- @item --show=@var{package}
- Show details about @var{package}, taken from the list of available packages, in
- @code{recutils} format (@pxref{Top, GNU recutils databases,, recutils, GNU
- recutils manual}).
- @example
- $ guix package --show=guile | recsel -p name,version
- name: guile
- version: 3.0.5
- name: guile
- version: 3.0.2
- name: guile
- version: 2.2.7
- @dots{}
- @end example
- You may also specify the full name of a package to only get details about a
- specific version of it (this time using the @command{guix show} alias):
- @example
- $ guix show guile@@3.0.5 | recsel -p name,version
- name: guile
- version: 3.0.5
- @end example
- @item --list-installed[=@var{regexp}]
- @itemx -I [@var{regexp}]
- List the currently installed packages in the specified profile, with the
- most recently installed packages shown last. When @var{regexp} is
- specified, list only installed packages whose name matches @var{regexp}.
- For each installed package, print the following items, separated by
- tabs: the package name, its version string, the part of the package that
- is installed (for instance, @code{out} for the default output,
- @code{include} for its headers, etc.), and the path of this package in
- the store.
- @item --list-available[=@var{regexp}]
- @itemx -A [@var{regexp}]
- List packages currently available in the distribution for this system
- (@pxref{GNU Distribution}). When @var{regexp} is specified, list only
- available packages whose name matches @var{regexp}.
- For each package, print the following items separated by tabs: its name,
- its version string, the parts of the package (@pxref{Packages with
- Multiple Outputs}), and the source location of its definition.
- @item --list-generations[=@var{pattern}]
- @itemx -l [@var{pattern}]
- @cindex generations
- Return a list of generations along with their creation dates; for each
- generation, show the installed packages, with the most recently
- installed packages shown last. Note that the zeroth generation is never
- shown.
- For each installed package, print the following items, separated by
- tabs: the name of a package, its version string, the part of the package
- that is installed (@pxref{Packages with Multiple Outputs}), and the
- location of this package in the store.
- When @var{pattern} is used, the command returns only matching
- generations. Valid patterns include:
- @itemize
- @item @emph{Integers and comma-separated integers}. Both patterns denote
- generation numbers. For instance, @option{--list-generations=1} returns
- the first one.
- And @option{--list-generations=1,8,2} outputs three generations in the
- specified order. Neither spaces nor trailing commas are allowed.
- @item @emph{Ranges}. @option{--list-generations=2..9} prints the
- specified generations and everything in between. Note that the start of
- a range must be smaller than its end.
- It is also possible to omit the endpoint. For example,
- @option{--list-generations=2..}, returns all generations starting from the
- second one.
- @item @emph{Durations}. You can also get the last @emph{N}@tie{}days, weeks,
- or months by passing an integer along with the first letter of the
- duration. For example, @option{--list-generations=20d} lists generations
- that are up to 20 days old.
- @end itemize
- @item --delete-generations[=@var{pattern}]
- @itemx -d [@var{pattern}]
- When @var{pattern} is omitted, delete all generations except the current
- one.
- This command accepts the same patterns as @option{--list-generations}.
- When @var{pattern} is specified, delete the matching generations. When
- @var{pattern} specifies a duration, generations @emph{older} than the
- specified duration match. For instance, @option{--delete-generations=1m}
- deletes generations that are more than one month old.
- If the current generation matches, it is @emph{not} deleted. Also, the
- zeroth generation is never deleted.
- Note that deleting generations prevents rolling back to them.
- Consequently, this command must be used with care.
- @cindex manifest, exporting
- @anchor{export-manifest}
- @item --export-manifest
- Write to standard output a manifest suitable for @option{--manifest}
- corresponding to the chosen profile(s).
- This option is meant to help you migrate from the ``imperative''
- operating mode---running @command{guix install}, @command{guix upgrade},
- etc.---to the declarative mode that @option{--manifest} offers.
- Be aware that the resulting manifest @emph{approximates} what your
- profile actually contains; for instance, depending on how your profile
- was created, it can refer to packages or package versions that are not
- exactly what you specified.
- Keep in mind that a manifest is purely symbolic: it only contains
- package names and possibly versions, and their meaning varies over time.
- If you wish to ``pin'' channels to the revisions that were used to build
- the profile(s), see @option{--export-channels} below.
- @cindex pinning, channel revisions of a profile
- @item --export-channels
- Write to standard output the list of channels used by the chosen
- profile(s), in a format suitable for @command{guix pull --channels} or
- @command{guix time-machine --channels} (@pxref{Channels}).
- Together with @option{--export-manifest}, this option provides
- information allowing you to replicate the current profile
- (@pxref{Replicating Guix}).
- However, note that the output of this command @emph{approximates} what
- was actually used to build this profile. In particular, a single
- profile might have been built from several different revisions of the
- same channel. In that case, @option{--export-manifest} chooses the last
- one and writes the list of other revisions in a comment. If you really
- need to pick packages from different channel revisions, you can use
- inferiors in your manifest to do so (@pxref{Inferiors}).
- Together with @option{--export-manifest}, this is a good starting point
- if you are willing to migrate from the ``imperative'' model to the fully
- declarative model consisting of a manifest file along with a channels
- file pinning the exact channel revision(s) you want.
- @end table
- Finally, since @command{guix package} may actually start build
- processes, it supports all the common build options (@pxref{Common Build
- Options}). It also supports package transformation options, such as
- @option{--with-source}, and preserves them across upgrades
- (@pxref{Package Transformation Options}).
- @node Substitutes
- @section Substitutes
- @cindex substitutes
- @cindex pre-built binaries
- Guix supports transparent source/binary deployment, which means that it
- can either build things locally, or download pre-built items from a
- server, or both. We call these pre-built items @dfn{substitutes}---they
- are substitutes for local build results. In many cases, downloading a
- substitute is much faster than building things locally.
- Substitutes can be anything resulting from a derivation build
- (@pxref{Derivations}). Of course, in the common case, they are
- pre-built package binaries, but source tarballs, for instance, which
- also result from derivation builds, can be available as substitutes.
- @menu
- * Official Substitute Servers:: One particular source of substitutes.
- * Substitute Server Authorization:: How to enable or disable substitutes.
- * Getting Substitutes from Other Servers:: Substitute diversity.
- * Substitute Authentication:: How Guix verifies substitutes.
- * Proxy Settings:: How to get substitutes via proxy.
- * Substitution Failure:: What happens when substitution fails.
- * On Trusting Binaries:: How can you trust that binary blob?
- @end menu
- @node Official Substitute Servers
- @subsection Official Substitute Servers
- @cindex build farm
- @code{@value{SUBSTITUTE-SERVER-1}} and
- @code{@value{SUBSTITUTE-SERVER-2}} are both front-ends to official build
- farms that build packages from Guix continuously for some architectures,
- and make them available as substitutes. These are the default source of
- substitutes; which can be overridden by passing the
- @option{--substitute-urls} option either to @command{guix-daemon}
- (@pxref{daemon-substitute-urls,, @code{guix-daemon --substitute-urls}})
- or to client tools such as @command{guix package}
- (@pxref{client-substitute-urls,, client @option{--substitute-urls}
- option}).
- Substitute URLs can be either HTTP or HTTPS.
- HTTPS is recommended because communications are encrypted; conversely,
- using HTTP makes all communications visible to an eavesdropper, who
- could use the information gathered to determine, for instance, whether
- your system has unpatched security vulnerabilities.
- Substitutes from the official build farms are enabled by default when
- using Guix System (@pxref{GNU Distribution}). However,
- they are disabled by default when using Guix on a foreign distribution,
- unless you have explicitly enabled them via one of the recommended
- installation steps (@pxref{Installation}). The following paragraphs
- describe how to enable or disable substitutes for the official build
- farm; the same procedure can also be used to enable substitutes for any
- other substitute server.
- @node Substitute Server Authorization
- @subsection Substitute Server Authorization
- @cindex security
- @cindex substitutes, authorization thereof
- @cindex access control list (ACL), for substitutes
- @cindex ACL (access control list), for substitutes
- To allow Guix to download substitutes from @code{@value{SUBSTITUTE-SERVER-1}}, @code{@value{SUBSTITUTE-SERVER-2}} or a mirror, you
- must add the relevant public key to the access control list (ACL) of archive
- imports, using the @command{guix archive} command (@pxref{Invoking guix
- archive}). Doing so implies that you trust the substitute server to not
- be compromised and to serve genuine substitutes.
- @quotation Note
- If you are using Guix System, you can skip this section: Guix System
- authorizes substitutes from @code{@value{SUBSTITUTE-SERVER-1}} and
- @code{@value{SUBSTITUTE-SERVER-2}} by default.
- @end quotation
- The public keys for each of the project maintained substitute servers
- are installed along with Guix, in @code{@var{prefix}/share/guix/}, where
- @var{prefix} is the installation prefix of Guix. If you installed Guix
- from source, make sure you checked the GPG signature of
- @file{guix-@value{VERSION}.tar.gz}, which contains this public key file.
- Then, you can run something like this:
- @example
- # guix archive --authorize < @var{prefix}/share/guix/@value{SUBSTITUTE-SERVER-1}.pub
- # guix archive --authorize < @var{prefix}/share/guix/@value{SUBSTITUTE-SERVER-2}.pub
- @end example
- Once this is in place, the output of a command like @code{guix build}
- should change from something like:
- @example
- $ guix build emacs --dry-run
- The following derivations would be built:
- /gnu/store/yr7bnx8xwcayd6j95r2clmkdl1qh688w-emacs-24.3.drv
- /gnu/store/x8qsh1hlhgjx6cwsjyvybnfv2i37z23w-dbus-1.6.4.tar.gz.drv
- /gnu/store/1ixwp12fl950d15h2cj11c73733jay0z-alsa-lib-1.0.27.1.tar.bz2.drv
- /gnu/store/nlma1pw0p603fpfiqy7kn4zm105r5dmw-util-linux-2.21.drv
- @dots{}
- @end example
- @noindent
- to something like:
- @example
- $ guix build emacs --dry-run
- 112.3 MB would be downloaded:
- /gnu/store/pk3n22lbq6ydamyymqkkz7i69wiwjiwi-emacs-24.3
- /gnu/store/2ygn4ncnhrpr61rssa6z0d9x22si0va3-libjpeg-8d
- /gnu/store/71yz6lgx4dazma9dwn2mcjxaah9w77jq-cairo-1.12.16
- /gnu/store/7zdhgp0n1518lvfn8mb96sxqfmvqrl7v-libxrender-0.9.7
- @dots{}
- @end example
- @noindent
- The text changed from ``The following derivations would be built'' to
- ``112.3 MB would be downloaded''. This indicates that substitutes from
- the configured substitute servers are usable and will be downloaded,
- when possible, for future builds.
- @cindex substitutes, how to disable
- The substitute mechanism can be disabled globally by running
- @code{guix-daemon} with @option{--no-substitutes} (@pxref{Invoking
- guix-daemon}). It can also be disabled temporarily by passing the
- @option{--no-substitutes} option to @command{guix package},
- @command{guix build}, and other command-line tools.
- @node Getting Substitutes from Other Servers
- @subsection Getting Substitutes from Other Servers
- @cindex substitute servers, adding more
- Guix can look up and fetch substitutes from several servers. This is
- useful when you are using packages from additional channels for which
- the official server does not have substitutes but another server
- provides them. Another situation where this is useful is when you would
- prefer to download from your organization's substitute server, resorting
- to the official server only as a fallback or dismissing it altogether.
- You can give Guix a list of substitute server URLs and it will check
- them in the specified order. You also need to explicitly authorize the
- public keys of substitute servers to instruct Guix to accept the
- substitutes they sign.
- On Guix System, this is achieved by modifying the configuration of the
- @code{guix} service. Since the @code{guix} service is part of the
- default lists of services, @code{%base-services} and
- @code{%desktop-services}, you can use @code{modify-services} to change
- its configuration and add the URLs and substitute keys that you want
- (@pxref{Service Reference, @code{modify-services}}).
- As an example, suppose you want to fetch substitutes from
- @code{guix.example.org} and to authorize the signing key of that server,
- in addition to the default @code{@value{SUBSTITUTE-SERVER-1}} and
- @code{@value{SUBSTITUTE-SERVER-2}}. The resulting operating system
- configuration will look something like:
- @lisp
- (operating-system
- ;; @dots{}
- (services
- ;; Assume we're starting from '%desktop-services'. Replace it
- ;; with the list of services you're actually using.
- (modify-services %desktop-services
- (guix-service-type config =>
- (guix-configuration
- (inherit config)
- (substitute-urls
- (append (list "https://guix.example.org")
- %default-substitute-urls))
- (authorized-keys
- (append (list (local-file "./key.pub"))
- %default-authorized-guix-keys)))))))
- @end lisp
- This assumes that the file @file{key.pub} contains the signing key of
- @code{guix.example.org}. With this change in place in your operating
- system configuration file (say @file{/etc/config.scm}), you can
- reconfigure and restart the @code{guix-daemon} service or reboot so the
- changes take effect:
- @example
- $ sudo guix system reconfigure /etc/config.scm
- $ sudo herd restart guix-daemon
- @end example
- If you're running Guix on a ``foreign distro'', you would instead take
- the following steps to get substitutes from additional servers:
- @enumerate
- @item
- Edit the service configuration file for @code{guix-daemon}; when using
- systemd, this is normally
- @file{/etc/systemd/system/guix-daemon.service}. Add the
- @option{--substitute-urls} option on the @command{guix-daemon} command
- line and list the URLs of interest (@pxref{daemon-substitute-urls,
- @code{guix-daemon --substitute-urls}}):
- @example
- @dots{} --substitute-urls='https://guix.example.org @value{SUBSTITUTE-URLS}'
- @end example
- @item
- Restart the daemon. For systemd, it goes like this:
- @example
- systemctl daemon-reload
- systemctl restart guix-daemon.service
- @end example
- @item
- Authorize the key of the new server (@pxref{Invoking guix archive}):
- @example
- guix archive --authorize < key.pub
- @end example
- Again this assumes @file{key.pub} contains the public key that
- @code{guix.example.org} uses to sign substitutes.
- @end enumerate
- Now you're all set! Substitutes will be preferably taken from
- @code{https://guix.example.org}, using
- @code{@value{SUBSTITUTE-SERVER-1}} then
- @code{@value{SUBSTITUTE-SERVER-2}} as fallback options. Of course you
- can list as many substitute servers as you like, with the caveat that
- substitute lookup can be slowed down if too many servers need to be
- contacted.
- Note that there are also situations where one may want to add the URL of
- a substitute server @emph{without} authorizing its key.
- @xref{Substitute Authentication}, to understand this fine point.
- @node Substitute Authentication
- @subsection Substitute Authentication
- @cindex digital signatures
- Guix detects and raises an error when attempting to use a substitute
- that has been tampered with. Likewise, it ignores substitutes that are
- not signed, or that are not signed by one of the keys listed in the ACL.
- There is one exception though: if an unauthorized server provides
- substitutes that are @emph{bit-for-bit identical} to those provided by
- an authorized server, then the unauthorized server becomes eligible for
- downloads. For example, assume we have chosen two substitute servers
- with this option:
- @example
- --substitute-urls="https://a.example.org https://b.example.org"
- @end example
- @noindent
- @cindex reproducible builds
- If the ACL contains only the key for @samp{b.example.org}, and if
- @samp{a.example.org} happens to serve the @emph{exact same} substitutes,
- then Guix will download substitutes from @samp{a.example.org} because it
- comes first in the list and can be considered a mirror of
- @samp{b.example.org}. In practice, independent build machines usually
- produce the same binaries, thanks to bit-reproducible builds (see
- below).
- When using HTTPS, the server's X.509 certificate is @emph{not} validated
- (in other words, the server is not authenticated), contrary to what
- HTTPS clients such as Web browsers usually do. This is because Guix
- authenticates substitute information itself, as explained above, which
- is what we care about (whereas X.509 certificates are about
- authenticating bindings between domain names and public keys).
- @node Proxy Settings
- @subsection Proxy Settings
- @vindex http_proxy
- @vindex https_proxy
- Substitutes are downloaded over HTTP or HTTPS@. The @env{http_proxy} and
- @env{https_proxy} environment variables can be set in the environment of
- @command{guix-daemon} and are honored for downloads of substitutes.
- Note that the value of those environment variables in the environment
- where @command{guix build}, @command{guix package}, and other client
- commands are run has @emph{absolutely no effect}.
- @node Substitution Failure
- @subsection Substitution Failure
- Even when a substitute for a derivation is available, sometimes the
- substitution attempt will fail. This can happen for a variety of
- reasons: the substitute server might be offline, the substitute may
- recently have been deleted, the connection might have been interrupted,
- etc.
- When substitutes are enabled and a substitute for a derivation is
- available, but the substitution attempt fails, Guix will attempt to
- build the derivation locally depending on whether or not
- @option{--fallback} was given (@pxref{fallback-option,, common build
- option @option{--fallback}}). Specifically, if @option{--fallback} was
- omitted, then no local build will be performed, and the derivation is
- considered to have failed. However, if @option{--fallback} was given,
- then Guix will attempt to build the derivation locally, and the success
- or failure of the derivation depends on the success or failure of the
- local build. Note that when substitutes are disabled or no substitute
- is available for the derivation in question, a local build will
- @emph{always} be performed, regardless of whether or not
- @option{--fallback} was given.
- To get an idea of how many substitutes are available right now, you can
- try running the @command{guix weather} command (@pxref{Invoking guix
- weather}). This command provides statistics on the substitutes provided
- by a server.
- @node On Trusting Binaries
- @subsection On Trusting Binaries
- @cindex trust, of pre-built binaries
- Today, each individual's control over their own computing is at the
- mercy of institutions, corporations, and groups with enough power and
- determination to subvert the computing infrastructure and exploit its
- weaknesses. While using substitutes can be convenient, we encourage
- users to also build on their own, or even run their own build farm, such
- that the project run substitute servers are less of an interesting
- target. One way to help is by publishing the software you build using
- @command{guix publish} so that others have one more choice of server to
- download substitutes from (@pxref{Invoking guix publish}).
- Guix has the foundations to maximize build reproducibility
- (@pxref{Features}). In most cases, independent builds of a given
- package or derivation should yield bit-identical results. Thus, through
- a diverse set of independent package builds, we can strengthen the
- integrity of our systems. The @command{guix challenge} command aims to
- help users assess substitute servers, and to assist developers in
- finding out about non-deterministic package builds (@pxref{Invoking guix
- challenge}). Similarly, the @option{--check} option of @command{guix
- build} allows users to check whether previously-installed substitutes
- are genuine by rebuilding them locally (@pxref{build-check,
- @command{guix build --check}}).
- In the future, we want Guix to have support to publish and retrieve
- binaries to/from other users, in a peer-to-peer fashion. If you would
- like to discuss this project, join us on @email{guix-devel@@gnu.org}.
- @node Packages with Multiple Outputs
- @section Packages with Multiple Outputs
- @cindex multiple-output packages
- @cindex package outputs
- @cindex outputs
- Often, packages defined in Guix have a single @dfn{output}---i.e., the
- source package leads to exactly one directory in the store. When running
- @command{guix install glibc}, one installs the default output of the
- GNU libc package; the default output is called @code{out}, but its name
- can be omitted as shown in this command. In this particular case, the
- default output of @code{glibc} contains all the C header files, shared
- libraries, static libraries, Info documentation, and other supporting
- files.
- Sometimes it is more appropriate to separate the various types of files
- produced from a single source package into separate outputs. For
- instance, the GLib C library (used by GTK+ and related packages)
- installs more than 20 MiB of reference documentation as HTML pages.
- To save space for users who do not need it, the documentation goes to a
- separate output, called @code{doc}. To install the main GLib output,
- which contains everything but the documentation, one would run:
- @example
- guix install glib
- @end example
- @cindex documentation
- The command to install its documentation is:
- @example
- guix install glib:doc
- @end example
- While the colon syntax works for command-line specification of package
- outputs, it will not work when using a package @emph{variable} in Scheme
- code. For example, to add the documentation of @code{glib} to the
- globally installed packages of an @code{operating-system} (see
- @ref{operating-system Reference}), a list of two items, the first one
- being the package @emph{variable} and the second one the name of the
- output to select (a string), must be used instead:
- @lisp
- (use-modules (gnu packages glib))
- ;; glib-with-documentation is the Guile symbol for the glib package
- (operating-system
- ...
- (packages
- (append
- (list (list glib-with-documentation "doc"))
- %base-packages)))
- @end lisp
- 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 locate
- @section Invoking @command{guix locate}
- @cindex file, searching in packages
- @cindex file search
- @cindex searching for packages
- There's so much free software out there that sooner or later, you will
- need to search for packages. The @command{guix search} command that
- we've seen before (@pxref{Invoking guix package}) lets you search by
- keywords:
- @example
- guix search video editor
- @end example
- @cindex searching for packages, by file name
- Sometimes, you instead want to find which package provides a given file,
- and this is where @command{guix locate} comes in. Here is how you can
- find which package provides the @command{ls} command:
- @example
- $ guix locate ls
- coreutils@@9.1 /gnu/store/@dots{}-coreutils-9.1/bin/ls
- @end example
- Of course the command works for any file, not just commands:
- @example
- $ guix locate unistr.h
- icu4c@@71.1 /gnu/store/@dots{}/include/unicode/unistr.h
- libunistring@@1.0 /gnu/store/@dots{}/include/unistr.h
- @end example
- You may also specify @dfn{glob patterns} with wildcards. For example,
- here is how you would search for packages providing @file{.service}
- files:
- @example
- $ guix locate -g '*.service'
- man-db@@2.11.1 @dots{}/lib/systemd/system/man-db.service
- wpa-supplicant@@2.10 @dots{}/system-services/fi.w1.wpa_supplicant1.service
- @end example
- The @command{guix locate} command relies on a database that maps file
- names to package names. By default, it automatically creates that
- database if it does not exist yet by traversing packages available
- @emph{locally}, which can take a few minutes (depending on the size of
- your store and the speed of your storage device).
- @quotation Note
- For now, @command{guix locate} builds its database based on purely local
- knowledge---meaning that you will not find packages that never reached
- your store. Eventually it will support downloading a pre-built database
- so you can potentially find more packages.
- @end quotation
- By default, @command{guix locate} first tries to look for a system-wide
- database, usually under @file{/var/cache/guix/locate}; if it does not
- exist or is too old, it falls back to the per-user database, by default
- under @file{~/.cache/guix/locate}. On a multi-user system,
- administrators may want to periodically update the system-wide database
- so that all users can benefit from it, for instance by setting up
- @code{package-database-service-type} (@pxref{File Search Services,
- @code{package-database-service-type}}).
- The general syntax is:
- @example
- guix locate [@var{options}@dots{}] @var{file}@dots{}
- @end example
- @noindent
- ... where @var{file} is the name of a file to search for (specifically,
- the ``base name'' of the file: files whose parent directories are called
- @var{file} are not matched).
- The available options are as follows:
- @table @code
- @item --glob
- @item -g
- Interpret @var{file}@dots{} as @dfn{glob patterns}---patterns that may
- include wildcards, such as @samp{*.scm} to denote all files ending in
- @samp{.scm}.
- @item --stats
- Display database statistics.
- @item --update
- @itemx -u
- Update the file database.
- By default, the database is automatically updated when it is too old.
- @item --clear
- Clear the database and re-populate it.
- This option lets you start anew, ensuring old data is removed from the
- database, which also avoids having an endlessly growing database. By
- default @command{guix locate} automatically does that periodically,
- though infrequently.
- @item --database=@var{file}
- Use @var{file} as the database, creating it if necessary.
- By default, @command{guix locate} picks the database under
- @file{~/.cache/guix} or @file{/var/cache/guix}, whichever is the most
- recent one.
- @item --method=@var{method}
- @itemx -m @var{method}
- Use @var{method} to select the set of packages to index. Possible
- values are:
- @table @code
- @item manifests
- This is the default method: it works by traversing profiles on the
- machine and recording packages it encounters---packages you or other
- users of the machine installed, directly or indirectly. It is fast but
- it can miss other packages available in the store but not referred to by
- any profile.
- @item store
- This is a slower but more exhaustive method: it checks among all the
- existing packages those that are available in the store and records
- them.
- @end table
- @end table
- @node Invoking guix gc
- @section Invoking @command{guix gc}
- @cindex garbage collector
- @cindex disk space
- @cindex @command{guix gc}
- 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 and home environment
- generations; 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}.
- @item --vacuum-database
- @cindex vacuum the store database
- @comment Avoid words like 'repair,' 'compress,' and 'optimize.'
- Guix uses an sqlite database to keep track of the items in (@pxref{The Store}).
- Over time it is possible that the database may grow to a large size and become
- fragmented. As a result, one may wish to clear the freed space and join the
- partially used pages in the database left behind from removed packages or after
- running the garbage collector. Running @command{sudo guix gc
- --vacuum-database} will lock the database and @code{VACUUM} the store,
- defragmenting the database and purging freed pages, unlocking the database when
- it finishes.
- @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/book/en/, 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 following, in this order:
- @enumerate
- @item
- the @option{--channels} option;
- @item
- the user's @file{~/.config/guix/channels.scm} file, unless @option{-q}
- is passed;
- @item
- the system-wide @file{/etc/guix/channels.scm} file, unless @option{-q}
- is passed;
- @item
- the built-in default channels specified in the @code{%default-channels}
- variable.
- @end enumerate
- On completion, @command{guix package} will use packages and package
- versions from this just-retrieved copy of Guix. Not only that, but all
- the Guix commands and Scheme modules will also be taken from that latest
- version. New @command{guix} sub-commands added by the update also
- become available.
- Any user can update their Guix copy using @command{guix pull}, and the
- effect is limited to the user who ran @command{guix pull}. For
- instance, when user @code{root} runs @command{guix pull}, this has no
- effect on the version of Guix that user @code{alice} sees, and vice
- versa.
- The result of running @command{guix pull} is a @dfn{profile} available
- under @file{~/.config/guix/current} containing the latest Guix. Thus,
- make sure to add it to the beginning of your search path so that you use
- the latest version, and similarly for the Info manual
- (@pxref{Documentation}):
- @example
- export PATH="$HOME/.config/guix/current/bin:$PATH"
- export INFOPATH="$HOME/.config/guix/current/share/info:$INFOPATH"
- @end example
- The @option{--list-generations} or @option{-l} option lists past generations
- produced by @command{guix pull}, along with details about their provenance:
- @example
- $ guix pull -l
- Generation 1 Jun 10 2018 00:18:18
- guix 65956ad
- repository URL: https://git.savannah.gnu.org/git/guix.git
- branch: origin/master
- commit: 65956ad3526ba09e1f7a40722c96c6ef7c0936fe
- Generation 2 Jun 11 2018 11:02:49
- guix e0cc7f6
- repository URL: https://git.savannah.gnu.org/git/guix.git
- branch: origin/master
- commit: e0cc7f669bec22c37481dd03a7941c7d11a64f1d
- Generation 3 Jun 13 2018 23:31:07 (current)
- guix 844cc1c
- repository URL: https://git.savannah.gnu.org/git/guix.git
- branch: origin/master
- commit: 844cc1c8f394f03b404c5bb3aee086922373490c
- @end example
- @xref{Invoking guix describe, @command{guix describe}}, for other ways to
- describe the current status of Guix.
- This @code{~/.config/guix/current} profile works exactly like the profiles
- created by @command{guix package} (@pxref{Invoking guix package}). That
- is, you can list generations, roll back to the previous
- generation---i.e., the previous Guix---and so on:
- @example
- $ guix pull --roll-back
- switched from generation 3 to 2
- $ guix pull --delete-generations=1
- deleting /var/guix/profiles/per-user/charlie/current-guix-1-link
- @end example
- You can also use @command{guix package} (@pxref{Invoking guix package})
- to manage the profile by naming it explicitly:
- @example
- $ guix package -p ~/.config/guix/current --roll-back
- switched from generation 3 to 2
- $ guix package -p ~/.config/guix/current --delete-generations=1
- deleting /var/guix/profiles/per-user/charlie/current-guix-1-link
- @end example
- The @command{guix pull} command is usually invoked with no arguments,
- but it supports the following options:
- @table @code
- @item --url=@var{url}
- @itemx --commit=@var{commit}
- @itemx --branch=@var{branch}
- Download code for the @code{guix} channel from the specified @var{url}, at the
- given @var{commit} (a valid Git commit ID represented as a hexadecimal
- string or the name of a tag), 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.
- @item --no-channel-files
- @itemx -q
- Inhibit loading of the user and system channel files,
- @file{~/.config/guix/channels.scm} and @file{/etc/guix/channels.scm}.
- @cindex channel news
- @item --news
- @itemx -N
- Display news written by channel authors for their users for changes made
- since the previous generation (@pxref{Channels, Writing Channel News}).
- When @option{--details} is passed, additionally display new and upgraded
- packages.
- You can view that information for previous generations with
- @command{guix pull -l}.
- @item --list-generations[=@var{pattern}]
- @itemx -l [@var{pattern}]
- List all the generations of @file{~/.config/guix/current} or, if @var{pattern}
- is provided, the subset of generations that match @var{pattern}.
- The syntax of @var{pattern} is the same as with @code{guix package
- --list-generations} (@pxref{Invoking guix package}).
- By default, this prints information about the channels used in each
- revision as well as the corresponding news entries. If you pass
- @option{--details}, it will also print the list of packages added and
- upgraded in each generation compared to the previous one.
- @item --details
- Instruct @option{--list-generations} or @option{--news} to display more
- information about the differences between subsequent generations---see
- above.
- @item --roll-back
- @cindex rolling back
- @cindex undoing transactions
- @cindex transactions, undoing
- Roll back to the previous @dfn{generation} of @file{~/.config/guix/current}---i.e.,
- undo the last transaction.
- @item --switch-generation=@var{pattern}
- @itemx -S @var{pattern}
- @cindex generations
- Switch to a particular generation defined by @var{pattern}.
- @var{pattern} may be either a generation number or a number prefixed
- with ``+'' or ``-''. The latter means: move forward/backward by a
- specified number of generations. For example, if you want to return to
- the latest generation after @option{--roll-back}, use
- @option{--switch-generation=+1}.
- @item --delete-generations[=@var{pattern}]
- @itemx -d [@var{pattern}]
- When @var{pattern} is omitted, delete all generations except the current
- one.
- This command accepts the same patterns as @option{--list-generations}.
- When @var{pattern} is specified, delete the matching generations. When
- @var{pattern} specifies a duration, generations @emph{older} than the
- specified duration match. For instance, @option{--delete-generations=1m}
- deletes generations that are more than one month old.
- If the current generation matches, it is @emph{not} deleted.
- Note that deleting generations prevents rolling back to them.
- Consequently, this command must be used with care.
- @xref{Invoking guix describe}, for a way to display information about the
- current generation only.
- @item --profile=@var{profile}
- @itemx -p @var{profile}
- Use @var{profile} instead of @file{~/.config/guix/current}.
- @item --dry-run
- @itemx -n
- Show which channel commit(s) would be used and what would be built or
- substituted but do not actually do it.
- @item --allow-downgrades
- Allow pulling older or unrelated revisions of channels than those
- currently in use.
- @cindex downgrade attacks, protection against
- By default, @command{guix pull} protects against so-called ``downgrade
- attacks'' whereby the Git repository of a channel would be reset to an
- earlier or unrelated revision of itself, potentially leading you to
- install older, known-vulnerable versions of software packages.
- @quotation Note
- Make sure you understand its security implications before using
- @option{--allow-downgrades}.
- @end quotation
- @item --disable-authentication
- Allow pulling channel code without authenticating it.
- @cindex authentication, of channel code
- By default, @command{guix pull} authenticates code downloaded from
- channels by verifying that its commits are signed by authorized
- developers, and raises an error if this is not the case. This option
- instructs it to not perform any such verification.
- @quotation Note
- Make sure you understand its security implications before using
- @option{--disable-authentication}.
- @end quotation
- @item --system=@var{system}
- @itemx -s @var{system}
- Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of
- the system type of the build host.
- @item --bootstrap
- Use the bootstrap Guile to build the latest Guix. This option is only
- useful to Guix developers.
- @end table
- The @dfn{channel} mechanism allows you to instruct @command{guix pull} which
- repository and branch to pull from, as well as @emph{additional} repositories
- containing package modules that should be deployed. @xref{Channels}, for more
- information.
- In addition, @command{guix pull} supports all the common build options
- (@pxref{Common Build Options}).
- @node Invoking guix time-machine
- @section Invoking @command{guix time-machine}
- @cindex @command{guix time-machine}
- @cindex pinning, channels
- @cindex replicating Guix
- @cindex reproducibility, of Guix
- The @command{guix time-machine} command provides access to other
- revisions of Guix, for example to install older versions of packages,
- or to reproduce a computation in an identical environment. The revision
- of Guix to be used is defined by a commit or by a channel
- description file created by @command{guix describe}
- (@pxref{Invoking guix describe}).
- Let's assume that you want to travel to those days of November 2020 when
- version 1.2.0 of Guix was released and, once you're there, run the
- @command{guile} of that time:
- @example
- guix time-machine --commit=v1.2.0 -- \
- environment -C --ad-hoc guile -- guile
- @end example
- The command above fetches Guix@tie{}1.2.0 (and possibly other channels
- specified by your @file{channels.scm} configuration files---see
- below) and runs its @command{guix
- environment} command to spawn an environment in a container running
- @command{guile} (@command{guix environment} has since been subsumed by
- @command{guix shell}; @pxref{Invoking guix shell}). It's like driving a
- DeLorean@footnote{If you don't know what a DeLorean is, consider
- traveling back to the 1980's.}! The first @command{guix time-machine}
- invocation can be expensive: it may have to download or even build a
- large number of packages; the result is cached though and subsequent
- commands targeting the same commit are almost instantaneous.
- As for @command{guix pull}, in the absence of any options,
- @command{time-machine} fetches the latest commits of the channels
- specified in @file{~/.config/guix/channels.scm},
- @file{/etc/guix/channels.scm}, or the default channels; the @option{-q}
- option lets you ignore these configuration files. The command:
- @example
- guix time-machine -q -- build hello
- @end example
- will thus build the package @code{hello} as defined in the main branch
- of Guix, without any additional channel, which is in general a newer
- revision of Guix than you have installed. Time travel works in both
- directions!
- @quotation Note
- The history of Guix is immutable and @command{guix time-machine}
- provides the exact same software as they are in a specific Guix
- revision. Naturally, no security fixes are provided for old versions
- of Guix or its channels. A careless use of @command{guix time-machine}
- opens the door to security vulnerabilities. @xref{Invoking guix pull,
- @option{--allow-downgrades}}.
- @end quotation
- Due to @command{guix time-machine} relying on the ``inferiors''
- mechanism (@pxref{Inferiors}), the oldest commit it can travel to is
- commit @samp{6298c3ff} (``v1.0.0''), dated May 1@sup{st}, 2019, which is
- the first release that included the inferiors mechanism. An error is
- returned when attempting to navigate to older commits.
- @quotation Note
- Although it should technically be possible to travel to such an old
- commit, the ease to do so will largely depend on the availability of
- binary substitutes. When traveling to a distant past, some packages may
- not easily build from source anymore. One such example are old versions
- of Python 2 which had time bombs in its test suite, in the form of
- expiring SSL certificates. This particular problem can be worked around
- by setting the hardware clock to a value in the past before attempting
- the build.
- @end quotation
- 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 the name of a tag), 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.
- @item --no-channel-files
- @itemx -q
- Inhibit loading of the user and system channel files,
- @file{~/.config/guix/channels.scm} and @file{/etc/guix/channels.scm}.
- Thus, @command{guix time-machine -q} is equivalent to the following Bash
- command, using the ``process substitution'' syntax (@pxref{Process
- Substitution,,, bash, The GNU Bash Reference Manual}):
- @example
- guix time-machine -C <(echo %default-channels) @dots{}
- @end example
- @end table
- 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{Writing Manifests}); 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 {Procedure} inferior-for-channels 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 {Procedure} open-inferior 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 {Procedure} inferior-packages inferior
- Return the list of packages known to @var{inferior}.
- @end deffn
- @deffn {Procedure} lookup-inferior-packages inferior name [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 {Procedure} inferior-package? obj
- Return true if @var{obj} is an inferior package.
- @end deffn
- @deffn {Procedure} inferior-package-name package
- @deffnx {Procedure} inferior-package-version package
- @deffnx {Procedure} inferior-package-synopsis package
- @deffnx {Procedure} inferior-package-description package
- @deffnx {Procedure} inferior-package-home-page package
- @deffnx {Procedure} inferior-package-location package
- @deffnx {Procedure} inferior-package-inputs package
- @deffnx {Procedure} inferior-package-native-inputs package
- @deffnx {Procedure} inferior-package-propagated-inputs package
- @deffnx {Procedure} inferior-package-transitive-propagated-inputs package
- @deffnx {Procedure} inferior-package-native-search-paths package
- @deffnx {Procedure} inferior-package-transitive-native-search-paths package
- @deffnx {Procedure} inferior-package-search-paths 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
- @cindex @command{guix describe}
- 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
- @cindex exporting files from the store
- @cindex importing files to the store
- 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 describe
- 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
- @end example
- @noindent
- The output of @command{guix describe} above shows that we're now running
- Generation@tie{}19 and that it includes
- both Guix and packages from the @code{variant-personal-packages} channel
- (@pxref{Invoking guix describe}).
- @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}).
- Note that you can specify a local directory on the @code{url} field above if
- the channel that you intend to use resides on a local file system. However,
- in this case @command{guix} checks said directory for ownership before any
- further processing. This means that if the user is not the directory owner,
- but wants to use it as their default, they will then need to set it as a safe
- directory in their global git configuration file. Otherwise, @command{guix}
- will refuse to even read it. Supposing your system-wide local directory is at
- @code{/src/guix.git}, you would then create a git configuration file at
- @code{~/.gitconfig} with the following contents:
- @example
- [safe]
- directory = /src/guix.git
- @end example
- @noindent
- This also applies to the root user unless when called with @command{sudo} by
- the directory owner.
- @node Replicating Guix
- @section Replicating Guix
- @cindex pinning, channels
- @cindex replicating Guix
- @cindex reproducibility, of Guix
- The @command{guix describe} command shows precisely which commits were
- used to build the instance of Guix we're using (@pxref{Invoking guix
- describe}). We can replicate this instance on another machine or at a
- different point in time by providing a channel specification ``pinned''
- to these commits that looks like this:
- @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
- To obtain this pinned channel specification, the easiest way is to run
- @command{guix describe} and to save its output in the @code{channels}
- format in a file, like so:
- @example
- guix describe -f channels > channels.scm
- @end example
- The resulting @file{channels.scm} file can be passed to the @option{-C}
- option of @command{guix pull} (@pxref{Invoking guix pull}) or
- @command{guix time-machine} (@pxref{Invoking guix time-machine}), as in
- this example:
- @example
- guix time-machine -C channels.scm -- shell python -- python3
- @end example
- Given the @file{channels.scm} file, the command above will always fetch
- the @emph{exact same Guix instance}, then use that instance to run the
- exact same Python (@pxref{Invoking guix shell}). On any machine, at any
- time, it ends up running the exact same binaries, bit for bit.
- @cindex lock files
- Pinned channels address a problem similar to ``lock files'' as
- implemented by some deployment tools---they let you pin and reproduce a
- set of packages. In the case of Guix though, you are effectively
- pinning the entire package set as defined at the given channel commits;
- in fact, you are pinning all of Guix, including its core modules and
- command-line tools. You're also getting strong guarantees that you are,
- indeed, obtaining the exact same software.
- 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. By creating a @dfn{channel}, you can use and publish such
- a package collection. This involves the following steps:
- @enumerate
- @item
- A channel lives in a Git repository so the first step, when creating a
- channel, is to create its repository:
- @example
- mkdir my-channel
- cd my-channel
- git init
- @end example
- @item
- The next step is to create files containing package modules
- (@pxref{Package Modules}), each of which will contain one or more
- package definitions (@pxref{Defining Packages}). A channel can provide
- things other than packages, such as build systems or services; we're
- using packages as it's the most common use case.
- For example, Alice might want to provide a module called @code{(alice
- packages greetings)} that will provide her favorite ``hello world''
- implementations. To do that Alice will create a directory corresponding
- to that module name.
- @example
- mkdir -p alice/packages
- $EDITOR alice/packages/greetings.scm
- git add alice/packages/greetings.scm
- @end example
- You can name your package modules however you like; the main constraint
- to keep in mind is to avoid name clashes with other package collections,
- which is why our hypothetical Alice wisely chose the @code{(alice
- packages @dots{})} name space.
- Note that you can also place modules in a sub-directory of the
- repository; @pxref{Package Modules in a Sub-directory}, for more info on
- that.
- @item
- With this first module in place, the next step is to test the packages
- it provides. This can be done with @command{guix build}, which needs to
- be told to look for modules in the Git checkout. For example, assuming
- @code{(alice packages greetings)} provides a package called
- @code{hi-from-alice}, Alice will run this command from the Git checkout:
- @example
- guix build -L. hi-from-alice
- @end example
- @noindent
- ... where @code{-L.} adds the current directory to Guile's load path
- (@pxref{Load Paths,,, guile, GNU Guile Reference Manual}).
- @item
- It might take Alice a few iterations to obtain satisfying package
- definitions. Eventually Alice will commit this file:
- @example
- git commit
- @end example
- 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.
- @item
- To use Alice's channel, anyone can now add it to their channel file
- (@pxref{Specifying Additional Channels}) and run @command{guix pull}
- (@pxref{Invoking guix pull}):
- @example
- $EDITOR ~/.config/guix/channels.scm
- guix pull
- @end example
- Guix will now behave as if the root directory of that channel's Git
- repository had been permanently added to the Guile load path. In this
- example, @code{(alice packages greetings)} will automatically be found
- by the @command{guix} command.
- @end enumerate
- Voilà!
- @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 publish your channel, 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
- Package modules and package definitions are Scheme code that uses
- various programming interfaces (APIs). We, Guix developers, never
- change APIs gratuitously, but we do @emph{not} commit to freezing APIs
- either. When you maintain package definitions outside Guix, we consider
- that @emph{the compatibility burden is on you}.
- @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
- @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
- The modules must be @b{underneath} the specified directory, as the
- @code{directory} changes Guile's @code{load-path}. For example, if
- @file{.guix-channel} has @code{(directory "base")}, then a module
- defined as @code{(define-module (gnu packages fun))} must be located at
- @code{base/gnu/packages/fun.scm}.
- Doing this allows for only parts of a repository to be used as a
- channel, as Guix expects valid Guile modules when pulling. For
- instance, @command{guix deploy} machine configuration files are not
- valid Guile modules, and treating them as such would make @command{guix
- pull} fail.
- @node Declaring Channel Dependencies
- @section Declaring Channel Dependencies
- @cindex dependencies, channels
- @cindex meta-data, channels
- Channel authors may decide to augment a package collection provided by other
- channels. They can declare their channel to be dependent on other channels in
- a meta-data file @file{.guix-channel}, which is to be placed in the root of
- the channel repository.
- The meta-data file should contain a simple S-expression like this:
- @lisp
- (channel
- (version 0)
- (dependencies
- (channel
- (name some-collection)
- (url "https://example.org/first-collection.git")
- ;; The 'introduction' bit below is optional: you would
- ;; provide it for dependencies that can be authenticated.
- (introduction
- (channel-introduction
- (version 0)
- (commit "a8883b58dc82e167c96506cf05095f37c2c2c6cd")
- (signer "CABB A931 C0FF EEC6 900D 0CFB 090B 1199 3D9A EBB5"))))
- (channel
- (name some-other-collection)
- (url "https://example.org/second-collection.git")
- (branch "testing"))))
- @end lisp
- In the above example this channel is declared to depend on two other channels,
- which will both be fetched automatically. The modules provided by the channel
- will be compiled in an environment where the modules of all these declared
- channels are available.
- For the sake of reliability and maintainability, you should avoid dependencies
- on channels that you don't control, and you should aim to keep the number of
- dependencies to a minimum.
- @node Specifying Channel Authorizations
- @section Specifying Channel Authorizations
- @cindex channel authorizations
- @anchor{channel-authorizations}
- As we saw above, Guix ensures the source code it pulls from channels
- comes from authorized developers. As a channel author, you need to
- specify the list of authorized developers in the
- @file{.guix-authorizations} file in the channel's Git repository. The
- authentication rule is simple: each commit must be signed by a key
- listed in the @file{.guix-authorizations} file of its parent
- commit(s)@footnote{Git commits form a @dfn{directed acyclic graph}
- (DAG). Each commit can have zero or more parents; ``regular'' commits
- have one parent and merge commits have two parent commits. Read
- @uref{https://eagain.net/articles/git-for-computer-scientists/, @i{Git
- for Computer Scientists}} for a great overview.} The
- @file{.guix-authorizations} file looks like this:
- @lisp
- ;; Example '.guix-authorizations' file.
- (authorizations
- (version 0) ;current file format version
- (("AD17 A21E F8AE D8F1 CC02 DBD9 F8AE D8F1 765C 61E3"
- (name "alice"))
- ("2A39 3FFF 68F4 EF7A 3D29 12AF 68F4 EF7A 22FB B2D5"
- (name "bob"))
- ("CABB A931 C0FF EEC6 900D 0CFB 090B 1199 3D9A EBB5"
- (name "charlie"))))
- @end lisp
- Each fingerprint is followed by optional key/value pairs, as in the
- example above. Currently these key/value pairs are ignored.
- This authentication rule creates a chicken-and-egg issue: how do we
- authenticate the first commit? Related to that: how do we deal with
- channels whose repository history contains unsigned commits and lack
- @file{.guix-authorizations}? And how do we fork existing channels?
- @cindex channel introduction
- Channel introductions answer these questions by describing the first
- commit of a channel that should be authenticated. The first time a
- channel is fetched with @command{guix pull} or @command{guix
- time-machine}, the command looks up the introductory commit and verifies
- that it is signed by the specified OpenPGP key. From then on, it
- authenticates commits according to the rule above. Authentication fails
- if the target commit is neither a descendant nor an ancestor of the
- introductory commit.
- Additionally, your channel must provide all the OpenPGP keys that were
- ever mentioned in @file{.guix-authorizations}, stored as @file{.key}
- files, which can be either binary or ``ASCII-armored''. By default,
- those @file{.key} files are searched for in the branch named
- @code{keyring} but you can specify a different branch name in
- @code{.guix-channel} like so:
- @lisp
- (channel
- (version 0)
- (keyring-reference "my-keyring-branch"))
- @end lisp
- To summarize, as the author of a channel, there are three things you have
- to do to allow users to authenticate your code:
- @enumerate
- @item
- Export the OpenPGP keys of past and present committers with @command{gpg
- --export} and store them in @file{.key} files, by default in a branch
- named @code{keyring} (we recommend making it an @dfn{orphan branch}).
- @item
- Introduce an initial @file{.guix-authorizations} in the channel's
- repository. Do that in a signed commit (@pxref{Commit Access}, for
- information on how to sign Git commits.)
- @item
- Advertise the channel introduction, for instance on your channel's web
- page. The channel introduction, as we saw above, is the commit/key
- pair---i.e., the commit that introduced @file{.guix-authorizations}, and
- the fingerprint of the OpenPGP used to sign it.
- @end enumerate
- Before pushing to your public Git repository, you can run @command{guix
- git authenticate} to verify that you did sign all the commits you are
- about to push with an authorized key:
- @example
- guix git authenticate @var{commit} @var{signer}
- @end example
- @noindent
- where @var{commit} and @var{signer} are your channel introduction.
- @xref{Invoking guix git authenticate}, for details.
- Publishing a signed channel requires discipline: any mistake, such as an
- unsigned commit or a commit signed by an unauthorized key, will prevent
- users from pulling from your channel---well, that's the whole point of
- authentication! Pay attention to merges in particular: merge commits
- are considered authentic if and only if they are signed by a key present
- in the @file{.guix-authorizations} file of @emph{both} branches.
- @node Primary URL
- @section Primary URL
- @cindex primary URL, channels
- Channel authors can indicate the primary URL of their channel's Git
- repository in the @file{.guix-channel} file, like so:
- @lisp
- (channel
- (version 0)
- (url "https://example.org/guix.git"))
- @end lisp
- This allows @command{guix pull} to determine whether it is pulling code
- from a mirror of the channel; when that is the case, it warns the user
- that the mirror might be stale and displays the primary URL@. That way,
- users cannot be tricked into fetching code from a stale mirror that does
- not receive security updates.
- This feature only makes sense for authenticated repositories, such as
- the official @code{guix} channel, for which @command{guix pull} ensures
- the code it fetches is authentic.
- @node Writing Channel News
- @section Writing Channel News
- @cindex news, for channels
- Channel authors may occasionally want to communicate to their users
- information about important changes in the channel. You'd send them all
- an email, but that's not convenient.
- Instead, channels can provide a @dfn{news file}; when the channel users
- run @command{guix pull}, that news file is automatically read and
- @command{guix pull --news} can display the announcements that correspond
- to the new commits that have been pulled, if any.
- To do that, channel authors must first declare the name of the news file
- in their @file{.guix-channel} file:
- @lisp
- (channel
- (version 0)
- (news-file "etc/news.txt"))
- @end lisp
- The news file itself, @file{etc/news.txt} in this example, must look
- something like this:
- @lisp
- (channel-news
- (version 0)
- (entry (tag "the-bug-fix")
- (title (en "Fixed terrible bug")
- (fr "Oh la la"))
- (body (en "@@emph@{Good news@}! It's fixed!")
- (eo "Certe ĝi pli bone funkcias nun!")))
- (entry (commit "bdcabe815cd28144a2d2b4bc3c5057b051fa9906")
- (title (en "Added a great package")
- (ca "Què vol dir guix?"))
- (body (en "Don't miss the @@code@{hello@} package!"))))
- @end lisp
- While the news file is using the Scheme syntax, avoid naming it with a
- @file{.scm} extension or else it will get picked up when building the
- channel and yield an error since it is not a valid module.
- Alternatively, you can move the channel module to a subdirectory and
- store the news file in another directory.
- The file consists of a list of @dfn{news entries}. Each entry is
- associated with a commit or tag: it describes changes made in this
- commit, possibly in preceding commits as well. Users see entries only
- the first time they obtain the commit the entry refers to.
- The @code{title} field should be a one-line summary while @code{body}
- can be arbitrarily long, and both can contain Texinfo markup
- (@pxref{Overview,,, texinfo, GNU Texinfo}). Both the title and body are
- a list of language tag/message tuples, which allows @command{guix pull}
- to display news in the language that corresponds to the user's locale.
- If you want to translate news using a gettext-based workflow, you can
- extract translatable strings with @command{xgettext} (@pxref{xgettext
- Invocation,,, gettext, GNU Gettext Utilities}). For example, assuming
- you write news entries in English first, the command below creates a PO
- file containing the strings to translate:
- @example
- xgettext -o news.po -l scheme -ken etc/news.txt
- @end example
- To sum up, yes, you could use your channel as a blog. But beware, this
- is @emph{not quite} what your users might expect.
- @c *********************************************************************
- @node Development
- @chapter Development
- @cindex software development
- If you are a software developer, Guix provides tools that you should find
- helpful---independently of the language you're developing in. This is what
- this chapter is about.
- The @command{guix shell} command provides a convenient way to set up
- one-off software environments, be it for development purposes or to run
- a command without installing it in your profile. The @command{guix
- pack} command allows you to create @dfn{application bundles} that can be
- easily distributed to users who do not run Guix.
- @menu
- * Invoking guix shell:: Spawning one-off software environments.
- * Invoking guix environment:: Setting up development environments.
- * Invoking guix pack:: Creating software bundles.
- * The GCC toolchain:: Working with languages supported by GCC.
- * Invoking guix git authenticate:: Authenticating Git repositories.
- @end menu
- @node Invoking guix shell
- @section Invoking @command{guix shell}
- @cindex reproducible build environments
- @cindex development environments
- @cindex @command{guix environment}
- @cindex @command{guix shell}
- @cindex environment, package build environment
- The purpose of @command{guix shell} is to make it easy to create one-off
- software environments, without changing one's profile. It is typically
- used to create development environments; it is also a convenient way to
- run applications without ``polluting'' your profile.
- @quotation Note
- The @command{guix shell} command was recently introduced to supersede
- @command{guix environment} (@pxref{Invoking guix environment}). If you
- are familiar with @command{guix environment}, you will notice that it is
- similar but also---we hope!---more convenient.
- @end quotation
- The general syntax is:
- @example
- guix shell [@var{options}] [@var{package}@dots{}]
- @end example
- The following example creates an environment containing Python and NumPy,
- building or downloading any missing package, and runs the
- @command{python3} command in that environment:
- @example
- guix shell python python-numpy -- python3
- @end example
- Note that it is necessary to include the main @code{python} package in
- this command even if it is already installed into your environment.
- This is so that the shell environment knows to set @env{PYTHONPATH} and
- other related variables. The shell environment cannot check the
- previously installed environment, because then it would be
- non-deterministic. This is true for most libraries: their corresponding
- language package should be included in the shell invocation.
- @quotation Note
- @cindex shebang, for @command{guix shell}
- @command{guix shell} can be also be used as a script interpreter, also
- known as @dfn{shebang}. Here is an example self-contained Python script
- making use of this feature:
- @example
- #!/usr/bin/env -S guix shell python python-numpy -- python3
- import numpy
- print("This is numpy", numpy.version.version)
- @end example
- You may pass any @command{guix shell} option, but there's one caveat:
- the Linux kernel has a limit of 127 bytes on shebang length.
- @end quotation
- Development environments can be created as in the example below, which
- spawns an interactive shell containing all the dependencies and
- environment variables needed to work on Inkscape:
- @example
- guix shell --development inkscape
- @end example
- Exiting the shell places the user back in the original environment
- before @command{guix shell} was invoked. The next garbage collection
- (@pxref{Invoking guix gc}) may clean up packages that were installed in
- the environment and that are no longer used outside of it.
- As an added convenience, @command{guix shell} will try to do what you
- mean when it is invoked interactively without any other arguments
- as in:
- @example
- guix shell
- @end example
- If it finds a @file{manifest.scm} in the current working directory or
- any of its parents, it uses this manifest as though it was given via @code{--manifest}.
- Likewise, if it finds a @file{guix.scm} in the same directories, it uses
- it to build a development profile as though both @code{--development}
- and @code{--file} were present.
- In either case, the file will only be loaded if the directory it
- resides in is listed in
- @file{~/.config/guix/shell-authorized-directories}.
- This provides an easy way to define, share, and enter development
- environments.
- By default, the shell session or command runs in an @emph{augmented}
- environment, where the new packages are added to search path environment
- variables such as @code{PATH}. You can, instead, choose to create an
- @emph{isolated} environment containing nothing but the packages you
- asked for. Passing the @option{--pure} option clears environment
- variable definitions found in the parent environment@footnote{Be sure to
- use the @option{--check} option the first time you use @command{guix
- shell} interactively to make sure the shell does not undo the effect of
- @option{--pure}.}; passing @option{--container} goes one step further by
- spawning a @dfn{container} isolated from the rest of the system:
- @example
- guix shell --container emacs gcc-toolchain
- @end example
- The command above spawns an interactive shell in a container where
- nothing but @code{emacs}, @code{gcc-toolchain}, and their dependencies
- is available. The container lacks network access and shares no files
- other than the current working directory with the surrounding
- environment. This is useful to prevent access to system-wide resources
- such as @file{/usr/bin} on foreign distros.
- This @option{--container} option can also prove useful if you wish to
- run a security-sensitive application, such as a web browser, in an
- isolated environment. For example, the command below launches
- Ungoogled-Chromium in an isolated environment, this time sharing network
- access with the host and preserving its @code{DISPLAY} environment
- variable, but without even sharing the current directory:
- @example
- guix shell --container --network --no-cwd ungoogled-chromium \
- --preserve='^DISPLAY$' -- chromium
- @end example
- @vindex GUIX_ENVIRONMENT
- @command{guix shell} defines the @env{GUIX_ENVIRONMENT}
- variable in the shell it spawns; its value is the file name of the
- profile of this environment. This allows users to, say, define a
- specific prompt for development environments in their @file{.bashrc}
- (@pxref{Bash Startup Files,,, bash, The GNU Bash Reference Manual}):
- @example
- if [ -n "$GUIX_ENVIRONMENT" ]
- then
- export PS1="\u@@\h \w [dev]\$ "
- fi
- @end example
- @noindent
- ...@: or to browse the profile:
- @example
- $ ls "$GUIX_ENVIRONMENT/bin"
- @end example
- The available options are summarized below.
- @table @code
- @item --check
- Set up the environment and check whether the shell would clobber
- environment variables. It's a good idea to use this option the first
- time you run @command{guix shell} for an interactive session to make
- sure your setup is correct.
- For example, if the shell modifies the @env{PATH} environment variable,
- report it since you would get a different environment than what you
- asked for.
- Such problems usually indicate that the shell startup files are
- unexpectedly modifying those environment variables. For example, if you
- are using Bash, make sure that environment variables are set or modified
- in @file{~/.bash_profile} and @emph{not} in @file{~/.bashrc}---the
- former is sourced only by log-in shells. @xref{Bash Startup Files,,,
- bash, The GNU Bash Reference Manual}, for details on Bash start-up
- files.
- @anchor{shell-development-option}
- @item --development
- @itemx -D
- Cause @command{guix shell} to include in the environment the
- dependencies of the following package rather than the package itself.
- This can be combined with other packages. For instance, the command
- below starts an interactive shell containing the build-time dependencies
- of GNU@tie{}Guile, plus Autoconf, Automake, and Libtool:
- @example
- guix shell -D guile autoconf automake libtool
- @end example
- @item --expression=@var{expr}
- @itemx -e @var{expr}
- Create an environment for the package or list of packages that
- @var{expr} evaluates to.
- For example, running:
- @example
- guix shell -D -e '(@@ (gnu packages maths) petsc-openmpi)'
- @end example
- starts a shell with the environment for this specific variant of the
- PETSc package.
- Running:
- @example
- guix shell -e '(@@ (gnu) %base-packages)'
- @end example
- starts a shell with all the base system packages available.
- The above commands only use the default output of the given packages.
- To select other outputs, two element tuples can be specified:
- @example
- guix shell -e '(list (@@ (gnu packages bash) bash) "include")'
- @end example
- @xref{package-development-manifest,
- @code{package->development-manifest}}, for information on how to write a
- manifest for the development environment of a package.
- @item --file=@var{file}
- @itemx -f @var{file}
- Create an environment containing the package or list of packages that
- the code within @var{file} evaluates to.
- As an example, @var{file} might contain a definition like this
- (@pxref{Defining Packages}):
- @lisp
- @verbatiminclude environment-gdb.scm
- @end lisp
- With the file above, you can enter a development environment for GDB by
- running:
- @example
- guix shell -D -f gdb-devel.scm
- @end example
- @anchor{shell-manifest}
- @item --manifest=@var{file}
- @itemx -m @var{file}
- Create an environment for the packages contained in the manifest object
- returned by the Scheme code in @var{file}. This option can be repeated
- several times, in which case the manifests are concatenated.
- This is similar to the same-named option in @command{guix package}
- (@pxref{profile-manifest, @option{--manifest}}) and uses the same
- manifest files.
- @xref{Writing Manifests}, for information on how to write a manifest.
- See @option{--export-manifest} below on how to obtain a first manifest.
- @cindex manifest, exporting
- @anchor{shell-export-manifest}
- @item --export-manifest
- Write to standard output a manifest suitable for @option{--manifest}
- corresponding to given command-line options.
- This is a way to ``convert'' command-line arguments into a manifest.
- For example, imagine you are tired of typing long lines and would like
- to get a manifest equivalent to this command line:
- @example
- guix shell -D guile git emacs emacs-geiser emacs-geiser-guile
- @end example
- Just add @option{--export-manifest} to the command line above:
- @example
- guix shell --export-manifest \
- -D guile git emacs emacs-geiser emacs-geiser-guile
- @end example
- @noindent
- ... and you get a manifest along these lines:
- @lisp
- (concatenate-manifests
- (list (specifications->manifest
- (list "git"
- "emacs"
- "emacs-geiser"
- "emacs-geiser-guile"))
- (package->development-manifest
- (specification->package "guile"))))
- @end lisp
- You can store it into a file, say @file{manifest.scm}, and from there
- pass it to @command{guix shell} or indeed pretty much any @command{guix}
- command:
- @example
- guix shell -m manifest.scm
- @end example
- Voilà, you've converted a long command line into a manifest! That
- conversion process honors package transformation options (@pxref{Package
- Transformation Options}) so it should be lossless.
- @item --profile=@var{profile}
- @itemx -p @var{profile}
- Create an environment containing the packages installed in @var{profile}.
- Use @command{guix package} (@pxref{Invoking guix package}) to create
- and manage profiles.
- @item --pure
- Unset existing environment variables when building the new environment, except
- those specified with @option{--preserve} (see below). This has the effect of
- creating an environment in which search paths only contain package inputs.
- @item --preserve=@var{regexp}
- @itemx -E @var{regexp}
- When used alongside @option{--pure}, preserve the environment variables
- matching @var{regexp}---in other words, put them on a ``white list'' of
- environment variables that must be preserved. This option can be repeated
- several times.
- @example
- guix shell --pure --preserve=^SLURM openmpi @dots{} \
- -- mpirun @dots{}
- @end example
- This example runs @command{mpirun} in a context where the only environment
- variables defined are @env{PATH}, environment variables whose name starts
- with @samp{SLURM}, as well as the usual ``precious'' variables (@env{HOME},
- @env{USER}, etc.).
- @item --search-paths
- Display the environment variable definitions that make up the
- environment.
- @item --system=@var{system}
- @itemx -s @var{system}
- Attempt to build for @var{system}---e.g., @code{i686-linux}.
- @item --container
- @itemx -C
- @cindex container
- Run @var{command} within an isolated container. The current working
- directory outside the container is mapped inside the container.
- Additionally, unless overridden with @option{--user}, a dummy home
- directory is created that matches the current user's home directory, and
- @file{/etc/passwd} is configured accordingly.
- The spawned process runs as the current user outside the container. Inside
- the container, it has the same UID and GID as the current user, unless
- @option{--user} is passed (see below).
- @item --network
- @itemx -N
- For containers, share the network namespace with the host system.
- Containers created without this flag only have access to the loopback
- device.
- @item --link-profile
- @itemx -P
- For containers, link the environment profile to @file{~/.guix-profile}
- within the container and set @code{GUIX_ENVIRONMENT} to that.
- This is equivalent to making @file{~/.guix-profile} a symlink to the
- actual profile within the container.
- Linking will fail and abort the environment if the directory already
- exists, which will certainly be the case if @command{guix shell}
- was invoked in the user's home directory.
- Certain packages are configured to look in @file{~/.guix-profile} for
- configuration files and data;@footnote{For example, the
- @code{fontconfig} package inspects @file{~/.guix-profile/share/fonts}
- for additional fonts.} @option{--link-profile} allows these programs to
- behave as expected within the environment.
- @item --user=@var{user}
- @itemx -u @var{user}
- For containers, use the username @var{user} in place of the current
- user. The generated @file{/etc/passwd} entry within the container will
- contain the name @var{user}, the home directory will be
- @file{/home/@var{user}}, and no user GECOS data will be copied. Furthermore,
- the UID and GID inside the container are 1000. @var{user}
- need not exist on the system.
- Additionally, any shared or exposed path (see @option{--share} and
- @option{--expose} respectively) whose target is within the current user's
- home directory will be remapped relative to @file{/home/USER}; this
- includes the automatic mapping of the current working directory.
- @example
- # will expose paths as /home/foo/wd, /home/foo/test, and /home/foo/target
- cd $HOME/wd
- guix shell --container --user=foo \
- --expose=$HOME/test \
- --expose=/tmp/target=$HOME/target
- @end example
- While this will limit the leaking of user identity through home paths
- and each of the user fields, this is only one useful component of a
- broader privacy/anonymity solution---not one in and of itself.
- @item --no-cwd
- For containers, the default behavior is to share the current working
- directory with the isolated container and immediately change to that
- directory within the container. If this is undesirable,
- @option{--no-cwd} will cause the current working directory to @emph{not}
- be automatically shared and will change to the user's home directory
- within the container instead. See also @option{--user}.
- @item --expose=@var{source}[=@var{target}]
- @itemx --share=@var{source}[=@var{target}]
- For containers, @option{--expose} (resp. @option{--share}) exposes the
- file system @var{source} from the host system as the read-only
- (resp. writable) file system @var{target} within the container. If
- @var{target} is not specified, @var{source} is used as the target mount
- point in the container.
- The example below spawns a Guile REPL in a container in which the user's
- home directory is accessible read-only via the @file{/exchange}
- directory:
- @example
- guix shell --container --expose=$HOME=/exchange guile -- guile
- @end example
- @cindex symbolic links, guix shell
- @item --symlink=@var{spec}
- @itemx -S @var{spec}
- For containers, create the symbolic links specified by @var{spec}, as
- documented in @ref{pack-symlink-option}.
- @cindex file system hierarchy standard (FHS)
- @cindex FHS (file system hierarchy standard)
- @item --emulate-fhs
- @itemx -F
- When used with @option{--container}, emulate a
- @uref{https://refspecs.linuxfoundation.org/fhs.shtml, Filesystem
- Hierarchy Standard (FHS)} configuration within the container, providing
- @file{/bin}, @file{/lib}, and other directories and files specified by
- the FHS.
- As Guix deviates from the FHS specification, this
- option sets up the container to more closely mimic that of other
- GNU/Linux distributions. This is useful for reproducing other
- development environments, testing, and using programs which expect the
- FHS specification to be followed. With this option, the container will
- include a version of glibc that will read
- @file{/etc/ld.so.cache} within the container for the shared library
- cache (contrary to glibc in regular Guix usage) and set up the
- expected FHS directories: @file{/bin}, @file{/etc}, @file{/lib}, and
- @file{/usr} from the container's profile.
- @cindex nested containers, for @command{guix shell}
- @cindex container nesting, for @command{guix shell}
- @item --nesting
- @itemx -W
- When used with @option{--container}, provide Guix @emph{inside} the
- container and arrange so that it can interact with the build daemon that
- runs outside the container. This is useful if you want, within your
- isolated container, to create other containers, as in this sample
- session:
- @example
- $ guix shell -CW coreutils
- [env]$ guix shell -C guile -- guile -c '(display "hello!\n")'
- hello!
- [env]$ exit
- @end example
- The session above starts a container with @code{coreutils} programs
- available in @env{PATH}. From there, we spawn @command{guix shell} to
- create a @emph{nested} container that provides nothing but Guile.
- Another example is evaluating a @file{guix.scm} file that is untrusted,
- as shown here:
- @example
- guix shell -CW -- guix build -f guix.scm
- @end example
- The @command{guix build} command as executed above can only access the
- current directory.
- Under the hood, the @option{-W} option does several things:
- @itemize
- @item
- map the daemon's socket (by default
- @file{/var/guix/daemon-socket/socket}) inside the container;
- @item
- map the whole store (by default @file{/gnu/store}) inside the container
- such that store items made available by nested @command{guix}
- invocations are visible;
- @item
- add the currently-used @command{guix} command to the profile in the
- container, such that @command{guix describe} returns the same state
- inside and outside the container;
- @item
- share the cache (by default @file{~/.cache/guix}) with the host, to
- speed up operations such as @command{guix time-machine} and
- @command{guix shell}.
- @end itemize
- @item --rebuild-cache
- @cindex caching, of profiles
- @cindex caching, in @command{guix shell}
- In most cases, @command{guix shell} caches the environment so that
- subsequent uses are instantaneous. Least-recently used cache entries
- are periodically removed. The cache is also invalidated, when using
- @option{--file} or @option{--manifest}, anytime the corresponding file
- is modified.
- The @option{--rebuild-cache} forces the cached environment to be
- refreshed. This is useful when using @option{--file} or
- @option{--manifest} and the @command{guix.scm} or @command{manifest.scm}
- file has external dependencies, or if its behavior depends, say, on
- environment variables.
- @item --root=@var{file}
- @itemx -r @var{file}
- @cindex persistent environment
- @cindex garbage collector root, for environments
- Make @var{file} a symlink to the profile for this environment, and
- register it as a garbage collector root.
- This is useful if you want to protect your environment from garbage
- collection, to make it ``persistent''.
- When this option is omitted, @command{guix shell} caches profiles so
- that subsequent uses of the same environment are instantaneous---this is
- comparable to using @option{--root} except that @command{guix shell}
- takes care of periodically removing the least-recently used garbage
- collector roots.
- In some cases, @command{guix shell} does not cache profiles---e.g., if
- transformation options such as @option{--with-latest} are used. In
- those cases, the environment is protected from garbage collection only
- for the duration of the @command{guix shell} session. This means that
- next time you recreate the same environment, you could have to rebuild
- or re-download packages.
- @xref{Invoking guix gc}, for more on GC roots.
- @end table
- @command{guix shell} also supports all of the common build options that
- @command{guix build} supports (@pxref{Common Build Options}) as well as
- package transformation options (@pxref{Package Transformation Options}).
- @node Invoking guix environment
- @section Invoking @command{guix environment}
- @cindex @command{guix environment}
- The purpose of @command{guix environment} is to assist in creating
- development environments.
- @quotation Deprecation warning
- The @command{guix environment} command is deprecated in favor of
- @command{guix shell}, which performs similar functions but is more
- convenient to use. @xref{Invoking guix shell}.
- Being deprecated, @command{guix environment} is slated for eventual
- removal, but the Guix project is committed to keeping it until May 1st,
- 2023. Please get in touch with us at @email{guix-devel@@gnu.org} if you
- would like to discuss it.
- @end quotation
- The general syntax is:
- @example
- guix environment @var{options} @var{package}@dots{}
- @end example
- The following example spawns a new shell set up for the development of
- GNU@tie{}Guile:
- @example
- guix environment guile
- @end example
- If the needed dependencies are not built yet, @command{guix environment}
- automatically builds them. The environment of the new shell is an
- augmented version of the environment that @command{guix environment} was
- run in. It contains the necessary search paths for building the given
- package added to the existing environment variables. To create
- a ``pure'' environment, in which the original environment variables have
- been unset, use the @option{--pure} option@footnote{Users sometimes
- wrongfully augment environment variables such as @env{PATH} in their
- @file{~/.bashrc} file. As a consequence, when @command{guix
- environment} launches it, Bash may read @file{~/.bashrc}, thereby
- introducing ``impurities'' in these environment variables. It is an
- error to define such environment variables in @file{.bashrc}; instead,
- they should be defined in @file{.bash_profile}, which is sourced only by
- log-in shells. @xref{Bash Startup Files,,, bash, The GNU Bash Reference
- Manual}, for details on Bash start-up files.}.
- Exiting from a Guix environment is the same as exiting from the shell,
- and will place the user back in the old environment before @command{guix
- environment} was invoked. The next garbage collection (@pxref{Invoking
- guix gc}) will clean up packages that were installed from within the
- environment and are no longer used outside of it.
- @vindex GUIX_ENVIRONMENT
- @command{guix environment} defines the @env{GUIX_ENVIRONMENT}
- variable in the shell it spawns; its value is the file name of the
- profile of this environment. This allows users to, say, define a
- specific prompt for development environments in their @file{.bashrc}
- (@pxref{Bash Startup Files,,, bash, The GNU Bash Reference Manual}):
- @example
- if [ -n "$GUIX_ENVIRONMENT" ]
- then
- export PS1="\u@@\h \w [dev]\$ "
- fi
- @end example
- @noindent
- ...@: or to browse the profile:
- @example
- $ ls "$GUIX_ENVIRONMENT/bin"
- @end example
- Additionally, more than one package may be specified, in which case the
- union of the inputs for the given packages are used. For example, the
- command below spawns a shell where all of the dependencies of both Guile
- and Emacs are available:
- @example
- guix environment guile emacs
- @end example
- Sometimes an interactive shell session is not desired. An arbitrary
- command may be invoked by placing the @code{--} token to separate the
- command from the rest of the arguments:
- @example
- guix environment guile -- make -j4
- @end example
- In other situations, it is more convenient to specify the list of
- packages needed in the environment. For example, the following command
- runs @command{python} from an environment containing Python@tie{}3 and
- NumPy:
- @example
- guix environment --ad-hoc python-numpy python -- python3
- @end example
- Furthermore, one might want the dependencies of a package and also some
- additional packages that are not build-time or runtime dependencies, but
- are useful when developing nonetheless. Because of this, the
- @option{--ad-hoc} flag is positional. Packages appearing before
- @option{--ad-hoc} are interpreted as packages whose dependencies will be
- added to the environment. Packages appearing after are interpreted as
- packages that will be added to the environment directly. For example,
- the following command creates a Guix development environment that
- additionally includes Git and strace:
- @example
- guix environment --pure guix --ad-hoc git strace
- @end example
- @cindex container
- Sometimes it is desirable to isolate the environment as much as
- possible, for maximal purity and reproducibility. In particular, when
- using Guix on a host distro that is not Guix System, it is desirable to
- prevent access to @file{/usr/bin} and other system-wide resources from
- the development environment. For example, the following command spawns
- a Guile REPL in a ``container'' where only the store and the current
- working directory are mounted:
- @example
- guix environment --ad-hoc --container guile -- guile
- @end example
- @quotation Note
- The @option{--container} option requires Linux-libre 3.19 or newer.
- @end quotation
- @cindex certificates
- Another typical use case for containers is to run security-sensitive
- applications such as a web browser. To run Eolie, we must expose and
- share some files and directories; we include @code{nss-certs} and expose
- @file{/etc/ssl/certs/} for HTTPS authentication; finally we preserve the
- @env{DISPLAY} environment variable since containerized graphical
- applications won't display without it.
- @example
- guix environment --preserve='^DISPLAY$' --container --network \
- --expose=/etc/machine-id \
- --expose=/etc/ssl/certs/ \
- --share=$HOME/.local/share/eolie/=$HOME/.local/share/eolie/ \
- --ad-hoc eolie nss-certs dbus -- eolie
- @end example
- The available options are summarized below.
- @table @code
- @item --check
- Set up the environment and check whether the shell would clobber
- environment variables. @xref{Invoking guix shell, @option{--check}},
- for more info.
- @item --root=@var{file}
- @itemx -r @var{file}
- @cindex persistent environment
- @cindex garbage collector root, for environments
- Make @var{file} a symlink to the profile for this environment, and
- register it as a garbage collector root.
- This is useful if you want to protect your environment from garbage
- collection, to make it ``persistent''.
- When this option is omitted, the environment is protected from garbage
- collection only for the duration of the @command{guix environment}
- session. This means that next time you recreate the same environment,
- you could have to rebuild or re-download packages. @xref{Invoking guix
- gc}, for more on GC roots.
- @item --expression=@var{expr}
- @itemx -e @var{expr}
- Create an environment for the package or list of packages that
- @var{expr} evaluates to.
- For example, running:
- @example
- guix environment -e '(@@ (gnu packages maths) petsc-openmpi)'
- @end example
- starts a shell with the environment for this specific variant of the
- PETSc package.
- Running:
- @example
- guix environment --ad-hoc -e '(@@ (gnu) %base-packages)'
- @end example
- starts a shell with all the base system packages available.
- The above commands only use the default output of the given packages.
- To select other outputs, two element tuples can be specified:
- @example
- guix environment --ad-hoc -e '(list (@@ (gnu packages bash) bash) "include")'
- @end example
- @item --load=@var{file}
- @itemx -l @var{file}
- Create an environment for the package or list of packages that the code
- within @var{file} evaluates to.
- As an example, @var{file} might contain a definition like this
- (@pxref{Defining Packages}):
- @lisp
- @verbatiminclude environment-gdb.scm
- @end lisp
- @item --manifest=@var{file}
- @itemx -m @var{file}
- Create an environment for the packages contained in the manifest object
- returned by the Scheme code in @var{file}. This option can be repeated
- several times, in which case the manifests are concatenated.
- This is similar to the same-named option in @command{guix package}
- (@pxref{profile-manifest, @option{--manifest}}) and uses the same
- manifest files.
- @xref{shell-export-manifest, @command{guix shell --export-manifest}},
- for information on how to ``convert'' command-line options into a
- manifest.
- @item --ad-hoc
- Include all specified packages in the resulting environment, as if an
- @i{ad hoc} package were defined with them as inputs. This option is
- useful for quickly creating an environment without having to write a
- package expression to contain the desired inputs.
- For instance, the command:
- @example
- guix environment --ad-hoc guile guile-sdl -- guile
- @end example
- runs @command{guile} in an environment where Guile and Guile-SDL are
- available.
- Note that this example implicitly asks for the default output of
- @code{guile} and @code{guile-sdl}, but it is possible to ask for a
- specific output---e.g., @code{glib:bin} asks for the @code{bin} output
- of @code{glib} (@pxref{Packages with Multiple Outputs}).
- This option may be composed with the default behavior of @command{guix
- environment}. Packages appearing before @option{--ad-hoc} are
- interpreted as packages whose dependencies will be added to the
- environment, the default behavior. Packages appearing after are
- interpreted as packages that will be added to the environment directly.
- @item --profile=@var{profile}
- @itemx -p @var{profile}
- Create an environment containing the packages installed in @var{profile}.
- Use @command{guix package} (@pxref{Invoking guix package}) to create
- and manage profiles.
- @item --pure
- Unset existing environment variables when building the new environment, except
- those specified with @option{--preserve} (see below). This has the effect of
- creating an environment in which search paths only contain package inputs.
- @item --preserve=@var{regexp}
- @itemx -E @var{regexp}
- When used alongside @option{--pure}, preserve the environment variables
- matching @var{regexp}---in other words, put them on a ``white list'' of
- environment variables that must be preserved. This option can be repeated
- several times.
- @example
- guix environment --pure --preserve=^SLURM --ad-hoc openmpi @dots{} \
- -- mpirun @dots{}
- @end example
- This example runs @command{mpirun} in a context where the only environment
- variables defined are @env{PATH}, environment variables whose name starts
- with @samp{SLURM}, as well as the usual ``precious'' variables (@env{HOME},
- @env{USER}, etc.).
- @item --search-paths
- Display the environment variable definitions that make up the
- environment.
- @item --system=@var{system}
- @itemx -s @var{system}
- Attempt to build for @var{system}---e.g., @code{i686-linux}.
- @item --container
- @itemx -C
- @cindex container
- Run @var{command} within an isolated container. The current working
- directory outside the container is mapped inside the container.
- Additionally, unless overridden with @option{--user}, a dummy home
- directory is created that matches the current user's home directory, and
- @file{/etc/passwd} is configured accordingly.
- The spawned process runs as the current user outside the container. Inside
- the container, it has the same UID and GID as the current user, unless
- @option{--user} is passed (see below).
- @item --network
- @itemx -N
- For containers, share the network namespace with the host system.
- Containers created without this flag only have access to the loopback
- device.
- @item --link-profile
- @itemx -P
- For containers, link the environment profile to @file{~/.guix-profile}
- within the container and set @code{GUIX_ENVIRONMENT} to that.
- This is equivalent to making @file{~/.guix-profile} a symlink to the
- actual profile within the container.
- Linking will fail and abort the environment if the directory already
- exists, which will certainly be the case if @command{guix environment}
- was invoked in the user's home directory.
- Certain packages are configured to look in @file{~/.guix-profile} for
- configuration files and data;@footnote{For example, the
- @code{fontconfig} package inspects @file{~/.guix-profile/share/fonts}
- for additional fonts.} @option{--link-profile} allows these programs to
- behave as expected within the environment.
- @item --user=@var{user}
- @itemx -u @var{user}
- For containers, use the username @var{user} in place of the current
- user. The generated @file{/etc/passwd} entry within the container will
- contain the name @var{user}, the home directory will be
- @file{/home/@var{user}}, and no user GECOS data will be copied. Furthermore,
- the UID and GID inside the container are 1000. @var{user}
- need not exist on the system.
- Additionally, any shared or exposed path (see @option{--share} and
- @option{--expose} respectively) whose target is within the current user's
- home directory will be remapped relative to @file{/home/USER}; this
- includes the automatic mapping of the current working directory.
- @example
- # will expose paths as /home/foo/wd, /home/foo/test, and /home/foo/target
- cd $HOME/wd
- guix environment --container --user=foo \
- --expose=$HOME/test \
- --expose=/tmp/target=$HOME/target
- @end example
- While this will limit the leaking of user identity through home paths
- and each of the user fields, this is only one useful component of a
- broader privacy/anonymity solution---not one in and of itself.
- @item --no-cwd
- For containers, the default behavior is to share the current working
- directory with the isolated container and immediately change to that
- directory within the container. If this is undesirable,
- @option{--no-cwd} will cause the current working directory to @emph{not}
- be automatically shared and will change to the user's home directory
- within the container instead. See also @option{--user}.
- @item --expose=@var{source}[=@var{target}]
- @itemx --share=@var{source}[=@var{target}]
- For containers, @option{--expose} (resp. @option{--share}) exposes the
- file system @var{source} from the host system as the read-only
- (resp. writable) file system @var{target} within the container. If
- @var{target} is not specified, @var{source} is used as the target mount
- point in the container.
- The example below spawns a Guile REPL in a container in which the user's
- home directory is accessible read-only via the @file{/exchange}
- directory:
- @example
- guix environment --container --expose=$HOME=/exchange --ad-hoc guile -- guile
- @end example
- @item --emulate-fhs
- @item -F
- For containers, emulate a Filesystem Hierarchy Standard (FHS)
- configuration within the container, see
- @uref{https://refspecs.linuxfoundation.org/fhs.shtml, the official
- specification}. As Guix deviates from the FHS specification, this
- option sets up the container to more closely mimic that of other
- GNU/Linux distributions. This is useful for reproducing other
- development environments, testing, and using programs which expect the
- FHS specification to be followed. With this option, the container will
- include a version of @code{glibc} which will read
- @code{/etc/ld.so.cache} within the container for the shared library
- cache (contrary to @code{glibc} in regular Guix usage) and set up the
- expected FHS directories: @code{/bin}, @code{/etc}, @code{/lib}, and
- @code{/usr} from the container's profile.
- @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}
- @cindex @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 @command{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
- @cindex Debian, build a .deb package with guix pack
- 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. You can
- nonetheless pack as many Guix packages as you want in one such archive.
- @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
- @item rpm
- @cindex RPM, build an RPM archive with guix pack
- This produces an RPM archive (a package with the @samp{.rpm} file
- extension) containing all the specified binaries and symbolic links,
- that can be installed on top of any RPM-based GNU/Linux distribution.
- The RPM format embeds checksums for every file it contains, which the
- @command{rpm} command uses to validate the integrity of the archive.
- Advanced RPM-related options are revealed via the
- @option{--help-rpm-format} option. These options allow embedding
- maintainer scripts that can run before or after the installation of the
- RPM archive, for example.
- The RPM format supports relocatable packages via the @option{--prefix}
- option of the @command{rpm} command, which can be handy to install an
- RPM package to a specific prefix.
- @example
- guix pack -f rpm -R -C xz -S /usr/bin/hello=bin/hello hello
- @end example
- @example
- sudo rpm --install --prefix=/opt /gnu/store/...-hello.rpm
- @end example
- @quotation Note
- Contrary to Debian packages, conflicting but @emph{identical} files in
- RPM packages can be installed simultaneously, which means multiple
- @command{guix pack}-produced RPM packages can usually be installed side
- by side without any problem.
- @end quotation
- @quotation Warning
- @command{rpm} assumes ownership of any files contained in the pack,
- which means it will remove @file{/gnu/store} upon uninstalling a
- Guix-generated RPM package, unless the RPM package was installed with
- the @option{--prefix} option of the @command{rpm} command. It is unwise
- to install Guix-produced @samp{.rpm} packages on a system where
- @file{/gnu/store} is shared by other software, such as a Guix
- installation or other, non-rpm 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}}).
- @anchor{pack-manifest}
- @item --manifest=@var{file}
- @itemx -m @var{file}
- Use the packages contained in the manifest object returned by the Scheme
- code in @var{file}. This option can be repeated several times, in which
- case the manifests are concatenated.
- This has a similar purpose as the same-named option in @command{guix
- package} (@pxref{profile-manifest, @option{--manifest}}) and uses the
- same manifest files. It allows you to define a collection of packages
- once and use it both for creating profiles and for creating archives
- for use on machines that do not have Guix installed. Note that you can
- specify @emph{either} a manifest file @emph{or} a list of packages,
- but not both.
- @xref{Writing Manifests}, for information on how to write a manifest.
- @xref{shell-export-manifest, @command{guix shell --export-manifest}},
- for information on how to ``convert'' command-line options into a
- manifest.
- @item --system=@var{system}
- @itemx -s @var{system}
- Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of
- the system type of the build host.
- @item --target=@var{triplet}
- @cindex cross-compilation
- Cross-build for @var{triplet}, which must be a valid GNU triplet, such
- as @code{"aarch64-linux-gnu"} (@pxref{Specifying target triplets, GNU
- configuration triplets,, autoconf, Autoconf}).
- @item --compression=@var{tool}
- @itemx -C @var{tool}
- Compress the resulting tarball using @var{tool}---one of @code{gzip},
- @code{zstd}, @code{bzip2}, @code{xz}, @code{lzip}, or @code{none} for no
- compression.
- @anchor{pack-symlink-option}
- @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}
- @cindex @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.
- * Writing Manifests:: The bill of materials of your environment.
- * Build Systems:: Specifying how packages are built.
- * Build Phases:: Phases of the build process of a package.
- * Build Utilities:: Helpers for your package definitions and more.
- * Search Paths:: Declaring search path environment variables.
- * The Store:: Manipulating the package store.
- * Derivations:: Low-level interface to package derivations.
- * The Store Monad:: Purely functional interface to the store.
- * G-Expressions:: Manipulating build expressions.
- * Invoking guix repl:: Programming Guix in Guile
- * Using Guix Interactively:: Fine-grain interaction at the REPL.
- @end menu
- @node Package Modules
- @section Package Modules
- From a programming viewpoint, the package definitions of the
- GNU distribution are provided by Guile modules in the @code{(gnu packages
- @dots{})} name space@footnote{Note that packages under the @code{(gnu
- packages @dots{})} module name space are not necessarily ``GNU
- packages''. This module naming scheme follows the usual Guile module
- naming convention: @code{gnu} means that these modules are distributed
- as part of the GNU system, and @code{packages} identifies modules that
- define packages.} (@pxref{Modules, Guile modules,, guile, GNU Guile
- Reference Manual}). For instance, the @code{(gnu packages emacs)}
- module exports a variable named @code{emacs}, which is bound to a
- @code{<package>} object (@pxref{Defining Packages}).
- The @code{(gnu packages @dots{})} module name space is
- automatically scanned for packages by the command-line tools. For
- instance, when running @code{guix install emacs}, all the @code{(gnu
- packages @dots{})} modules are scanned until one that exports a package
- object whose name is @code{emacs} is found. This package search
- facility is implemented in the @code{(gnu packages)} module.
- @cindex customization, of packages
- @cindex package module search path
- Users can store package definitions in modules with different
- names---e.g., @code{(my-packages emacs)}@footnote{Note that the file
- name and module name must match. For instance, the @code{(my-packages
- emacs)} module must be stored in a @file{my-packages/emacs.scm} file
- relative to the load path specified with @option{--load-path} or
- @env{GUIX_PACKAGE_PATH}. @xref{Modules and the File System,,,
- guile, GNU Guile Reference Manual}, for details.}. There are two ways to make
- these package definitions visible to the user interfaces:
- @enumerate
- @item
- By adding the directory containing your package modules to the search path
- with the @code{-L} flag of @command{guix package} and other commands
- (@pxref{Common Build Options}), or by setting the @env{GUIX_PACKAGE_PATH}
- environment variable described below.
- @item
- By defining a @dfn{channel} and configuring @command{guix pull} so that it
- pulls from it. A channel is essentially a Git repository containing package
- modules. @xref{Channels}, for more information on how to define and use
- channels.
- @end enumerate
- @env{GUIX_PACKAGE_PATH} works similarly to other search path variables:
- @defvr {Environment Variable} GUIX_PACKAGE_PATH
- This is a colon-separated list of directories to search for additional
- package modules. Directories listed in this variable take precedence
- over the own modules of the distribution.
- @end defvr
- The distribution is fully @dfn{bootstrapped} and @dfn{self-contained}:
- each package is built based solely on other packages in the
- distribution. The root of this dependency graph is a small set of
- @dfn{bootstrap binaries}, provided by the @code{(gnu packages
- bootstrap)} module. For more information on bootstrapping,
- @pxref{Bootstrapping}.
- @node Defining Packages
- @section Defining Packages
- The high-level interface to package definitions is implemented in the
- @code{(guix packages)} and @code{(guix build-system)} modules. As an
- example, the package definition, or @dfn{recipe}, for the GNU Hello
- package looks like this:
- @lisp
- (define-module (gnu packages hello)
- #:use-module (guix packages)
- #:use-module (guix download)
- #:use-module (guix build-system gnu)
- #:use-module (guix licenses)
- #:use-module (gnu packages gawk))
- (define-public hello
- (package
- (name "hello")
- (version "2.10")
- (source (origin
- (method url-fetch)
- (uri (string-append "mirror://gnu/hello/hello-" version
- ".tar.gz"))
- (sha256
- (base32
- "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i"))))
- (build-system gnu-build-system)
- (arguments '(#:configure-flags '("--enable-silent-rules")))
- (inputs (list gawk))
- (synopsis "Hello, GNU world: An example GNU package")
- (description "Guess what GNU Hello prints!")
- (home-page "https://www.gnu.org/software/hello/")
- (license gpl3+)))
- @end lisp
- @noindent
- Without being a Scheme expert, the reader may have guessed the meaning
- of the various fields here. This expression binds the variable
- @code{hello} to a @code{<package>} object, which is essentially a record
- (@pxref{SRFI-9, Scheme records,, guile, GNU Guile Reference Manual}).
- This package object can be inspected using procedures found in the
- @code{(guix packages)} module; for instance, @code{(package-name hello)}
- returns---surprise!---@code{"hello"}.
- With luck, you may be able to import part or all of the definition of
- the package you are interested in from another repository, using the
- @code{guix import} command (@pxref{Invoking guix import}).
- In the example above, @code{hello} is defined in a module of its own,
- @code{(gnu packages hello)}. Technically, this is not strictly
- necessary, but it is convenient to do so: all the packages defined in
- modules under @code{(gnu packages @dots{})} are automatically known to
- the command-line tools (@pxref{Package Modules}).
- There are a few points worth noting in the above package definition:
- @itemize
- @item
- The @code{source} field of the package is an @code{<origin>} object
- (@pxref{origin Reference}, for the complete reference).
- Here, the @code{url-fetch} method from @code{(guix download)} is used,
- meaning that the source is a file to be downloaded over FTP or HTTP.
- The @code{mirror://gnu} prefix instructs @code{url-fetch} to use one of
- the GNU mirrors defined in @code{(guix download)}.
- The @code{sha256} field specifies the expected SHA256 hash of the file
- being downloaded. It is mandatory, and allows Guix to check the
- integrity of the file. The @code{(base32 @dots{})} form introduces the
- base32 representation of the hash. You can obtain this information with
- @code{guix download} (@pxref{Invoking guix download}) and @code{guix
- hash} (@pxref{Invoking guix hash}).
- @cindex patches
- When needed, the @code{origin} form can also have a @code{patches} field
- listing patches to be applied, and a @code{snippet} field giving a
- Scheme expression to modify the source code.
- @item
- @cindex GNU Build System
- The @code{build-system} field specifies the procedure to build the
- package (@pxref{Build Systems}). Here, @code{gnu-build-system}
- represents the familiar GNU Build System, where packages may be
- configured, built, and installed with the usual @code{./configure &&
- make && make check && make install} command sequence.
- When you start packaging non-trivial software, you may need tools to
- manipulate those build phases, manipulate files, and so on. @xref{Build
- Utilities}, for more on this.
- @item
- The @code{arguments} field specifies options for the build system
- (@pxref{Build Systems}). Here it is interpreted by
- @code{gnu-build-system} as a request run @file{configure} with the
- @option{--enable-silent-rules} flag.
- @cindex quote
- @cindex quoting
- @findex '
- @findex quote
- @cindex backquote (quasiquote)
- @findex `
- @findex quasiquote
- @cindex comma (unquote)
- @findex ,
- @findex unquote
- What about these quote (@code{'}) characters? They are Scheme syntax to
- introduce a literal list; @code{'} is synonymous with @code{quote}.
- Sometimes you'll also see @code{`} (a backquote, synonymous with
- @code{quasiquote}) and @code{,} (a comma, synonymous with @code{unquote}).
- @xref{Expression Syntax, quoting,, guile, GNU Guile Reference Manual},
- for details. Here the value of the @code{arguments} field is a list of
- arguments passed to the build system down the road, as with @code{apply}
- (@pxref{Fly Evaluation, @code{apply},, guile, GNU Guile Reference
- Manual}).
- The hash-colon (@code{#:}) sequence defines a Scheme @dfn{keyword}
- (@pxref{Keywords,,, guile, GNU Guile Reference Manual}), and
- @code{#:configure-flags} is a keyword used to pass a keyword argument
- to the build system (@pxref{Coding With Keywords,,, guile, GNU Guile
- Reference Manual}).
- @item
- The @code{inputs} field specifies inputs to the build process---i.e.,
- build-time or run-time dependencies of the package. Here, we add
- an input, a reference to the @code{gawk}
- variable; @code{gawk} is itself bound to a @code{<package>} object.
- Note that GCC, Coreutils, Bash, and other essential tools do not need to
- be specified as inputs here. Instead, @code{gnu-build-system} takes care
- of ensuring that they are present (@pxref{Build Systems}).
- However, any other dependencies need to be specified in the
- @code{inputs} field. Any dependency not specified here will simply be
- unavailable to the build process, possibly leading to a build failure.
- @end itemize
- @xref{package Reference}, for a full description of possible fields.
- @quotation Going further
- @cindex Scheme programming language, getting started
- Intimidated by the Scheme language or curious about it? The Cookbook
- has a short section to get started that recaps some of the things shown
- above and explains the fundamentals. @xref{A Scheme Crash Course,,,
- guix-cookbook, GNU Guix Cookbook}, for more information.
- @end quotation
- 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 {Procedure} package-derivation store package [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 {Procedure} package-cross-derivation store package target [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 (@pxref{Build
- Systems}). This is a list, typically containing sequential
- keyword-value pairs, as in this example:
- @lisp
- (package
- (name "example")
- ;; several fields omitted
- (arguments
- (list #:tests? #f ;skip tests
- #:make-flags #~'("VERBOSE=1") ;pass flags to 'make'
- #:configure-flags #~'("--enable-frobbing"))))
- @end lisp
- The exact set of supported keywords depends on the build system
- (@pxref{Build Systems}), but you will find that almost all of them honor
- @code{#:configure-flags}, @code{#:make-flags}, @code{#:tests?}, and
- @code{#:phases}. The @code{#:phases} keyword in particular lets you
- modify the set of build phases for your package (@pxref{Build Phases}).
- @quotation Compatibility Note
- Until version 1.3.0, the @code{arguments} field would typically use
- @code{quote} (@code{'}) or @code{quasiquote} (@code{`}) and no
- G-expressions, like so:
- @lisp
- (package
- ;; several fields omitted
- (arguments ;old-style quoted arguments
- '(#:tests? #f
- #:configure-flags '("--enable-frobbing"))))
- @end lisp
- To convert from that style to the one shown above, you can run
- @code{guix style -S arguments @var{package}} (@pxref{Invoking guix
- style}).
- @end quotation
- @item @code{inputs} (default: @code{'()})
- @itemx @code{native-inputs} (default: @code{'()})
- @itemx @code{propagated-inputs} (default: @code{'()})
- @cindex inputs, of packages
- These fields list dependencies of the package. Each element of these
- lists is either a package, origin, or other ``file-like object''
- (@pxref{G-Expressions}); to specify the output of that file-like object
- that should be used, pass a two-element list where the second element is
- the output (@pxref{Packages with Multiple Outputs}, for more on package
- outputs). For example, the list below specifies three inputs:
- @lisp
- (list libffi libunistring
- `(,glib "bin")) ;the "bin" output of GLib
- @end lisp
- In the example above, the @code{"out"} output of @code{libffi} and
- @code{libunistring} is used.
- @quotation Compatibility Note
- Until version 1.3.0, input lists were a list of tuples,
- where each tuple has a label for the input (a string) as its
- first element, a package, origin, or derivation as its second element,
- and optionally the name of the output thereof that should be used, which
- defaults to @code{"out"}. For example, the list below is equivalent to
- the one above, but using the @dfn{old input style}:
- @lisp
- ;; Old input style (deprecated).
- `(("libffi" ,libffi)
- ("libunistring" ,libunistring)
- ("glib:bin" ,glib "bin")) ;the "bin" output of GLib
- @end lisp
- This style is now deprecated; it is still supported but support will be
- removed in a future version. It should not be used for new package
- definitions. @xref{Invoking guix style}, on how to migrate to the new
- style.
- @end quotation
- @cindex cross compilation, package dependencies
- The distinction between @code{native-inputs} and @code{inputs} is
- necessary when considering cross-compilation. When cross-compiling,
- dependencies listed in @code{inputs} are built for the @emph{target}
- architecture; conversely, dependencies listed in @code{native-inputs}
- are built for the architecture of the @emph{build} machine.
- @code{native-inputs} is typically used to list tools needed at
- build time, but not at run time, such as Autoconf, Automake, pkg-config,
- Gettext, or Bison. @command{guix lint} can report likely mistakes in
- this area (@pxref{Invoking guix lint}).
- @anchor{package-propagated-inputs}
- Lastly, @code{propagated-inputs} is similar to @code{inputs}, but the
- specified packages will be automatically installed to profiles
- (@pxref{Features, the role of profiles in Guix}) alongside the package
- they belong to (@pxref{package-cmd-propagated-inputs, @command{guix
- package}}, for information on how @command{guix package} deals with
- propagated inputs).
- For example this is necessary when packaging a C/C++ library that needs
- headers of another library to compile, or when a pkg-config file refers
- to another one @i{via} its @code{Requires} field.
- Another example where @code{propagated-inputs} is useful is for languages
- that lack a facility to record the run-time search path akin to the
- @code{RUNPATH} of ELF files; this includes Guile, Python, Perl, and
- more. When packaging libraries written in those languages, ensure they
- can find library code they depend on at run time by listing run-time
- dependencies in @code{propagated-inputs} rather than @code{inputs}.
- @item @code{outputs} (default: @code{'("out")})
- The list of output names of the package. @xref{Packages with Multiple
- Outputs}, for typical uses of additional outputs.
- @item @code{native-search-paths} (default: @code{'()})
- @itemx @code{search-paths} (default: @code{'()})
- A list of @code{search-path-specification} objects describing
- search-path environment variables honored by the package. @xref{Search
- Paths}, for more on search path specifications.
- As for inputs, the distinction between @code{native-search-paths} and
- @code{search-paths} only matters when cross-compiling. In a
- cross-compilation context, @code{native-search-paths} applies
- exclusively to native inputs whereas @code{search-paths} applies only to
- host inputs.
- Packages such as cross-compilers care about target inputs---for
- instance, our (modified) GCC cross-compiler has
- @env{CROSS_C_INCLUDE_PATH} in @code{search-paths}, which allows it to
- pick @file{.h} files for the target system and @emph{not} those of
- native inputs. For the majority of packages though, only
- @code{native-search-paths} makes sense.
- @item @code{replacement} (default: @code{#f})
- This must be either @code{#f} or a package object that will be used as a
- @dfn{replacement} for this package. @xref{Security Updates, grafts},
- for details.
- @item @code{synopsis}
- A one-line description of the package.
- @item @code{description}
- A more elaborate description of the package, as a string in Texinfo
- syntax.
- @item @code{license}
- @cindex license, of packages
- The license of the package; a value from @code{(guix licenses)},
- or a list of such values.
- @item @code{home-page}
- The URL to the home-page of the package, as a string.
- @item @code{supported-systems} (default: @code{%supported-systems})
- The list of systems supported by the package, as strings of the form
- @code{architecture-kernel}, for example @code{"x86_64-linux"}.
- @item @code{location} (default: source location of the @code{package} form)
- The source location of the package. It is useful to override this when
- inheriting from another package, in which case this field is not
- automatically corrected.
- @end table
- @end deftp
- @defmac 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 defmac
- The following helper procedures are provided to help deal with package
- inputs.
- @deffn {Procedure} lookup-package-input package name
- @deffnx {Procedure} lookup-package-native-input package name
- @deffnx {Procedure} lookup-package-propagated-input package name
- @deffnx {Procedure} lookup-package-direct-input package name
- Look up @var{name} among @var{package}'s inputs (or native, propagated,
- or direct inputs). Return it if found, @code{#f} otherwise.
- @var{name} is the name of a package depended on. Here's how you might
- use it:
- @lisp
- (use-modules (guix packages) (gnu packages base))
- (lookup-package-direct-input coreutils "gmp")
- @result{} #<package gmp@@6.2.1 @dots{}>
- @end lisp
- In this example we obtain the @code{gmp} package that is among the
- direct inputs of @code{coreutils}.
- @end deffn
- @cindex development inputs, of a package
- @cindex implicit inputs, of a package
- Sometimes you will want to obtain the list of inputs needed to
- @emph{develop} a package---all the inputs that are visible when the
- package is compiled. This is what the @code{package-development-inputs}
- procedure returns.
- @deffn {Procedure} package-development-inputs package [system] [#:target #f]
- Return the list of inputs required by @var{package} for development
- purposes on @var{system}. When @var{target} is true, return the inputs
- needed to cross-compile @var{package} from @var{system} to
- @var{target}, where @var{target} is a triplet such as
- @code{"aarch64-linux-gnu"}.
- Note that the result includes both explicit inputs and implicit
- inputs---inputs automatically added by the build system (@pxref{Build
- Systems}). Let us take the @code{hello} package to illustrate that:
- @lisp
- (use-modules (gnu packages base) (guix packages))
- hello
- @result{} #<package hello@@2.10 gnu/packages/base.scm:79 7f585d4f6790>
- (package-direct-inputs hello)
- @result{} ()
- (package-development-inputs hello)
- @result{} (("source" @dots{}) ("tar" #<package tar@@1.32 @dots{}>) @dots{})
- @end lisp
- In this example, @code{package-direct-inputs} returns the empty list,
- because @code{hello} has zero explicit dependencies. Conversely,
- @code{package-development-inputs} includes inputs implicitly added by
- @code{gnu-build-system} that are required to build @code{hello}: tar,
- gzip, GCC, libc, Bash, and more. To visualize it, @command{guix graph
- hello} would show you explicit inputs, whereas @command{guix graph -t
- bag hello} would include implicit inputs (@pxref{Invoking guix graph}).
- @end deffn
- Because packages are regular Scheme objects that capture a complete
- dependency graph and associated build procedures, it is often useful to
- write procedures that take a package and return a modified version
- thereof according to some parameters. Below are a few examples.
- @cindex tool chain, choosing a package's tool chain
- @deffn {Procedure} package-with-c-toolchain package 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 {Procedure} url-fetch url hash-algo 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 {Procedure} git-fetch ref hash-algo 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 {Procedure} hg-fetch ref hash-algo 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{Writing Manifests})
- 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-version}
- or @option{--with-source} package transformations option do.
- 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.
- @defmac modify-inputs inputs clauses
- Modify the given package inputs, as returned by @code{package-inputs} & co.,
- according to the given clauses. Each clause must have one of the
- following forms:
- @table @code
- @item (delete @var{name}@dots{})
- Delete from the inputs packages with the given @var{name}s (strings).
- @item (prepend @var{package}@dots{})
- Add @var{package}s to the front of the input list.
- @item (append @var{package}@dots{})
- Add @var{package}s to the end of the input list.
- @item (replace @var{name} @var{replacement})
- Replace the package called @var{name} with @var{replacement}.
- @end table
- The example below removes the GMP and ACL inputs of Coreutils and adds
- libcap to the front of the input list:
- @lisp
- (modify-inputs (package-inputs coreutils)
- (delete "gmp" "acl")
- (prepend 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{append}, to add inputs at the back of
- the list.
- @end defmac
- 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 {Procedure} options->transformation 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 {Procedure} package-input-rewriting replacements [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 {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. Matching packages that have the @code{hidden?} property
- set are not replaced.
- @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 {Procedure} package-mapping proc [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 Writing Manifests
- @section Writing Manifests
- @cindex manifest
- @cindex bill of materials (manifests)
- @command{guix} commands let you specify package lists on the command
- line. This is convenient, but as the command line becomes longer and
- less trivial, it quickly becomes more convenient to have that package
- list in what we call a @dfn{manifest}. A manifest is some sort of a
- ``bill of materials'' that defines a package set. You would typically
- come up with a code snippet that builds the manifest, store it in a
- file, say @file{manifest.scm}, and then pass that file to the
- @option{-m} (or @option{--manifest}) option that many @command{guix}
- commands support. For example, here's what a manifest for a simple
- package set might look like:
- @lisp
- ;; Manifest for three packages.
- (specifications->manifest '("gcc-toolchain" "make" "git"))
- @end lisp
- Once you have that manifest, you can pass it, for example, to
- @command{guix package} to install just those three packages to your
- profile (@pxref{profile-manifest, @option{-m} option of @command{guix
- package}}):
- @example
- guix package -m manifest.scm
- @end example
- @noindent
- ... or you can pass it to @command{guix shell} (@pxref{shell-manifest,
- @command{-m} option of @command{guix shell}}) to spawn an ephemeral
- environment:
- @example
- guix shell -m manifest.scm
- @end example
- @noindent
- ... or you can pass it to @command{guix pack} in pretty much the same
- way (@pxref{pack-manifest, @option{-m} option of @command{guix pack}}).
- You can store the manifest under version control, share it with others
- so they can easily get set up, etc.
- But how do you write your first manifest? To get started, maybe you'll
- want to write a manifest that mirrors what you already have in a
- profile. Rather than start from a blank page, @command{guix package}
- can generate a manifest for you (@pxref{export-manifest, @command{guix
- package --export-manifest}}):
- @example
- # Write to 'manifest.scm' a manifest corresponding to the
- # default profile, ~/.guix-profile.
- guix package --export-manifest > manifest.scm
- @end example
- Or maybe you'll want to ``translate'' command-line arguments into a
- manifest. In that case, @command{guix shell} can help
- (@pxref{shell-export-manifest, @command{guix shell --export-manifest}}):
- @example
- # Write a manifest for the packages specified on the command line.
- guix shell --export-manifest gcc-toolchain make git > manifest.scm
- @end example
- In both cases, the @option{--export-manifest} option tries hard to
- generate a faithful manifest; in particular, it takes package
- transformation options into account (@pxref{Package Transformation
- Options}).
- @quotation Note
- Manifests are @emph{symbolic}: they refer to packages of the channels
- @emph{currently in use} (@pxref{Channels}). In the example above,
- @code{gcc-toolchain} might refer to version 11 today, but it might refer
- to version 13 two years from now.
- If you want to ``pin'' your software environment to specific package
- versions and variants, you need an additional piece of information: the
- list of channel revisions in use, as returned by @command{guix
- describe}. @xref{Replicating Guix}, for more information.
- @end quotation
- Once you've obtained your first manifest, perhaps you'll want to
- customize it. Since your manifest is code, you now have access to all
- the Guix programming interfaces!
- Let's assume you want a manifest to deploy a custom variant of GDB, the
- GNU Debugger, that does not depend on Guile, together with another
- package. Building on the example seen in the previous section
- (@pxref{Defining Package Variants}), you can write a manifest along
- these lines:
- @lisp
- (use-modules (guix packages)
- (gnu packages gdb) ;for 'gdb'
- (gnu packages version-control)) ;for 'git'
- ;; Define a variant of GDB without a dependency on Guile.
- (define gdb-sans-guile
- (package
- (inherit gdb)
- (inputs (modify-inputs (package-inputs gdb)
- (delete "guile")))))
- ;; Return a manifest containing that one package plus Git.
- (packages->manifest (list gdb-sans-guile git))
- @end lisp
- Note that in this example, the manifest directly refers to the
- @code{gdb} and @code{git} variables, which are bound to a @code{package}
- object (@pxref{package Reference}), instead of calling
- @code{specifications->manifest} to look up packages by name as we did
- before. The @code{use-modules} form at the top lets us access the core
- package interface (@pxref{Defining Packages}) and the modules that
- define @code{gdb} and @code{git} (@pxref{Package Modules}). Seamlessly,
- we're weaving all this together---the possibilities are endless, unleash
- your creativity!
- The data type for manifests as well as supporting procedures are defined
- in the @code{(guix profiles)} module, which is automatically available
- to code passed to @option{-m}. The reference follows.
- @deftp {Data Type} manifest
- Data type representing a manifest.
- It currently has one field:
- @table @code
- @item entries
- This must be a list of @code{manifest-entry} records---see below.
- @end table
- @end deftp
- @deftp {Data Type} manifest-entry
- Data type representing a manifest entry. A manifest entry contains
- essential metadata: a name and version string, the object (usually a
- package) for that entry, the desired output (@pxref{Packages with
- Multiple Outputs}), and a number of optional pieces of information
- detailed below.
- Most of the time, you won't build a manifest entry directly; instead,
- you will pass a package to @code{package->manifest-entry}, described
- below. In some unusual cases though, you might want to create manifest
- entries for things that are @emph{not} packages, as in this example:
- @lisp
- ;; Manually build a single manifest entry for a non-package object.
- (let ((hello (program-file "hello" #~(display "Hi!"))))
- (manifest-entry
- (name "foo")
- (version "42")
- (item
- (computed-file "hello-directory"
- #~(let ((bin (string-append #$output "/bin")))
- (mkdir #$output) (mkdir bin)
- (symlink #$hello
- (string-append bin "/hello")))))))
- @end lisp
- The available fields are the following:
- @table @asis
- @item @code{name}
- @itemx @code{version}
- Name and version string for this entry.
- @item @code{item}
- A package or other file-like object (@pxref{G-Expressions, file-like
- objects}).
- @item @code{output} (default: @code{"out"})
- Output of @code{item} to use, in case @code{item} has multiple outputs
- (@pxref{Packages with Multiple Outputs}).
- @item @code{dependencies} (default: @code{'()})
- List of manifest entries this entry depends on. When building a
- profile, dependencies are added to the profile.
- Typically, the propagated inputs of a package (@pxref{package Reference,
- @code{propagated-inputs}}) end up having a corresponding manifest entry
- in among the dependencies of the package's own manifest entry.
- @item @code{search-paths} (default: @code{'()})
- The list of search path specifications honored by this entry
- (@pxref{Search Paths}).
- @item @code{properties} (default: @code{'()})
- List of symbol/value pairs. When building a profile, those properties
- get serialized.
- This can be used to piggyback additional metadata---e.g., the
- transformations applied to a package (@pxref{Package Transformation
- Options}).
- @item @code{parent} (default: @code{(delay #f)})
- A promise pointing to the ``parent'' manifest entry.
- This is used as a hint to provide context when reporting an error
- related to a manifest entry coming from a @code{dependencies} field.
- @end table
- @end deftp
- @deffn {Procedure} concatenate-manifests lst
- Concatenate the manifests listed in @var{lst} and return the resulting
- manifest.
- @end deffn
- @c TODO: <manifest-pattern>, manifest-lookup, manifest-remove, etc.
- @deffn {Procedure} package->manifest-entry package [output] [#:properties]
- Return a manifest entry for the @var{output} of package @var{package},
- where @var{output} defaults to @code{"out"}, and with the given
- @var{properties}. By default @var{properties} is the empty list or, if
- one or more package transformations were applied to @var{package}, it is
- an association list representing those transformations, suitable as an
- argument to @code{options->transformation} (@pxref{Defining Package
- Variants, @code{options->transformation}}).
- The code snippet below builds a manifest with an entry for the default
- output and the @code{send-email} output of the @code{git} package:
- @lisp
- (use-modules (gnu packages version-control))
- (manifest (list (package->manifest-entry git)
- (package->manifest-entry git "send-email")))
- @end lisp
- @end deffn
- @deffn {Procedure} packages->manifest packages
- Return a list of manifest entries, one for each item listed in
- @var{packages}. Elements of @var{packages} can be either package
- objects or package/string tuples denoting a specific output of a
- package.
- Using this procedure, the manifest above may be rewritten more
- concisely:
- @lisp
- (use-modules (gnu packages version-control))
- (packages->manifest (list git `(,git "send-email")))
- @end lisp
- @end deffn
- @anchor{package-development-manifest}
- @deffn {Procedure} package->development-manifest package [system] [#:target]
- Return a manifest for the @dfn{development inputs} of @var{package} for
- @var{system}, optionally when cross-compiling to @var{target}.
- Development inputs include both explicit and implicit inputs of
- @var{package}.
- Like the @option{-D} option of @command{guix shell}
- (@pxref{shell-development-option, @command{guix shell -D}}), the
- resulting manifest describes the environment in which one can develop
- @var{package}. For example, suppose you're willing to set up a
- development environment for Inkscape, with the addition of Git for
- version control; you can describe that ``bill of materials'' with the
- following manifest:
- @lisp
- (use-modules (gnu packages inkscape) ;for 'inkscape'
- (gnu packages version-control)) ;for 'git'
- (concatenate-manifests
- (list (package->development-manifest inkscape)
- (packages->manifest (list git))))
- @end lisp
- In this example, the development manifest that
- @code{package->development-manifest} returns includes the compiler
- (GCC), the many supporting libraries (Boost, GLib, GTK, etc.), and a
- couple of additional development tools---these are the dependencies
- @command{guix show inkscape} lists.
- @end deffn
- @c TODO: Move (gnu packages) interface to a section of its own.
- Last, the @code{(gnu packages)} module provides higher-level facilities
- to build manifests. In particular, it lets you look up packages by
- name---see below.
- @deffn {Procedure} specifications->manifest specs
- Given @var{specs}, a list of specifications such as @code{"emacs@@25.2"}
- or @code{"guile:debug"}, return a manifest. Specs have the format that
- command-line tools such as @command{guix install} and @command{guix
- package} understand (@pxref{Invoking guix package}).
- As an example, it lets you rewrite the Git manifest that we saw earlier
- like this:
- @lisp
- (specifications->manifest '("git" "git:send-email"))
- @end lisp
- Notice that we do not need to worry about @code{use-modules}, importing
- the right set of modules, and referring to the right variables.
- Instead, we directly refer to packages in the same way as on the command
- line, which can often be more convenient.
- @end deffn
- @c TODO: specifications->package, etc.
- @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.
- @defvar 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.
- @xref{phase-validate-runpath, the @code{validate-runpath} phase}, for
- details.
- @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 defvar
- 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.
- @defvar agda-build-system
- This variable is exported by @code{(guix build-system agda)}. It
- implements a build procedure for Agda libraries.
- It adds @code{agda} to the set of inputs. A different Agda can be
- specified with the @code{#:agda} key.
- The @code{#:plan} key is a list of cons cells @code{(@var{regexp}
- . @var{parameters})}, where @var{regexp} is a regexp that should match
- the @code{.agda} files to build, and @var{parameters} is an optional
- list of parameters that will be passed to @code{agda} when type-checking
- it.
- When the library uses Haskell to generate a file containing all imports,
- the convenience @code{#:gnu-and-haskell?} can be set to @code{#t} to add
- @code{ghc} and the standard inputs of @code{gnu-build-system} to the
- input list. You will still need to manually add a phase or tweak the
- @code{'build} phase, as in the definition of @code{agda-stdlib}.
- @end defvar
- @defvar 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 defvar
- @defvar 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 defvar
- @defvar asdf-build-system/source
- @defvarx asdf-build-system/sbcl
- @defvarx 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 defvar
- @defvar 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 defvar
- @defvar 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 defvar
- @defvar 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 defvar
- @cindex Clojure (programming language)
- @cindex simple Clojure build system
- @defvar 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 defvar
- @defvar 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 defvar
- @defvar 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 defvar
- @defvar elm-build-system
- This variable is exported by @code{(guix build-system elm)}. It implements a
- build procedure for @url{https://elm-lang.org, Elm} packages similar to
- @samp{elm install}.
- The build system adds an Elm compiler package to the set of inputs. The
- default compiler package (currently @code{elm-sans-reactor}) can be overridden
- using the @code{#:elm} argument. Additionally, Elm packages needed by the
- build system itself are added as implicit inputs if they are not already
- present: to suppress this behavior, use the
- @code{#:implicit-elm-package-inputs?} argument, which is primarily useful for
- bootstrapping.
- The @code{"dependencies"} and @code{"test-dependencies"} in an Elm package's
- @file{elm.json} file correspond to @code{propagated-inputs} and @code{inputs},
- respectively.
- Elm requires a particular structure for package names: @pxref{Elm Packages}
- for more details, including utilities provided by @code{(guix build-system
- elm)}.
- There are currently a few noteworthy limitations to @code{elm-build-system}:
- @itemize
- @item
- The build system is focused on @dfn{packages} in the Elm sense of the word:
- Elm @dfn{projects} which declare @code{@{ "type": "package" @}} in their
- @file{elm.json} files. Using @code{elm-build-system} to build Elm
- @dfn{applications} (which declare @code{@{ "type": "application" @}}) is
- possible, but requires ad-hoc modifications to the build phases. For
- examples, see the definitions of the @code{elm-todomvc} example application and
- the @code{elm} package itself (because the front-end for the
- @samp{elm reactor} command is an Elm application).
- @item
- Elm supports multiple versions of a package coexisting simultaneously under
- @env{ELM_HOME}, but this does not yet work well with @code{elm-build-system}.
- This limitation primarily affects Elm applications, because they specify
- exact versions for their dependencies, whereas Elm packages specify supported
- version ranges. As a workaround, the example applications mentioned above use
- the @code{patch-application-dependencies} procedure provided by
- @code{(guix build elm-build-system)} to rewrite their @file{elm.json} files to
- refer to the package versions actually present in the build environment.
- Alternatively, Guix package transformations (@pxref{Defining Package
- Variants}) could be used to rewrite an application's entire dependency graph.
- @item
- We are not yet able to run tests for Elm projects because neither
- @url{https://github.com/mpizenberg/elm-test-rs, @command{elm-test-rs}} nor the
- Node.js-based @url{https://github.com/rtfeldman/node-test-runner,
- @command{elm-test}} runner has been packaged for Guix yet.
- @end itemize
- @end defvar
- @defvar 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}.
- The key @code{#:go} can be used to specify the Go compiler package with
- which to build the package.
- @end defvar
- @defvar 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 defvar
- @defvar 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 defvar
- @defvar julia-build-system
- This variable is exported by @code{(guix build-system julia)}. It
- implements the build procedure used by @uref{https://julialang.org/,
- julia} packages, which essentially is similar to running @samp{julia -e
- 'using Pkg; Pkg.add(package)'} in an environment where
- @env{JULIA_LOAD_PATH} contains the paths to all Julia package inputs.
- Tests are run by calling @code{/test/runtests.jl}.
- The Julia package name and uuid is read from the file
- @file{Project.toml}. These values can be overridden by passing the
- argument @code{#:julia-package-name} (which must be correctly
- capitalized) or @code{#:julia-package-uuid}.
- Julia packages usually manage their binary dependencies via
- @code{JLLWrappers.jl}, a Julia package that creates a module (named
- after the wrapped library followed by @code{_jll.jl}.
- To add the binary path @code{_jll.jl} packages, you need to patch the
- files under @file{src/wrappers/}, replacing the call to the macro
- @code{JLLWrappers.@@generate_wrapper_header}, adding as a second
- argument containing the store path the binary.
- As an example, in the MbedTLS Julia package, we add a build phase
- (@pxref{Build Phases}) to insert the absolute file name of the wrapped
- MbedTLS package:
- @lisp
- (add-after 'unpack 'override-binary-path
- (lambda* (#:key inputs #:allow-other-keys)
- (for-each (lambda (wrapper)
- (substitute* wrapper
- (("generate_wrapper_header.*")
- (string-append
- "generate_wrapper_header(\"MbedTLS\", \""
- (assoc-ref inputs "mbedtls-apache") "\")\n"))))
- ;; There's a Julia file for each platform, override them all.
- (find-files "src/wrappers/" "\\.jl$"))))
- @end lisp
- Some older packages that aren't using @file{Project.toml} yet, will
- require this file to be created, too. It is internally done if the
- arguments @code{#:julia-package-name} and @code{#:julia-package-uuid}
- are provided.
- @end defvar
- @defvar 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 defvar
- @defvar 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 defvar
- @defvar 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 defvar
- @defvar mozilla-build-system
- This variable is exported by @code{(guix build-system mozilla)}. It
- sets the @code{--target} and @code{--host} configuration flags to what
- software developed by Mozilla expects -- due to historical reasons,
- Mozilla software expects @code{--host} to be the system that is
- cross-compiled from and @code{--target} to be the system that is
- cross-compiled to, contrary to the standard Autotools conventions.
- @end defvar
- @defvar 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 defvar
- @defvar 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 defvar
- @defvar pyproject-build-system
- This is a variable exported by @code{guix build-system pyproject}. It
- is based on @var{python-build-system}, and adds support for
- @file{pyproject.toml} and @url{https://peps.python.org/pep-0517/, PEP 517}.
- It also supports a variety of build backends and test frameworks.
- The API is slightly different from @var{python-build-system}:
- @itemize
- @item
- @code{#:use-setuptools?} and @code{#:test-target} is removed.
- @item
- @code{#:build-backend} is added. It defaults to @code{#false} and will try
- to guess the appropriate backend based on @file{pyproject.toml}.
- @item
- @code{#:test-backend} is added. It defaults to @code{#false} and will guess
- an appropriate test backend based on what is available in package inputs.
- @item
- @code{#:test-flags} is added. The default is @code{'()}. These flags are
- passed as arguments to the test command. Note that flags for verbose output
- is always enabled on supported backends.
- @end itemize
- It is considered ``experimental'' in that the implementation details are
- not set in stone yet, however users are encouraged to try it for new
- Python projects (even those using @file{setup.py}). The API is subject to
- change, but any breaking changes in the Guix channel will be dealt with.
- Eventually this build system will be deprecated and merged back into
- @var{python-build-system}, probably some time in 2024.
- @end defvar
- @defvar 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 defvar
- @defvar 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 defvar
- @defvar 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 defvar
- @defvar 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 defvar
- @defvar 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 defvar
- @defvar rebar-build-system
- This variable is exported by @code{(guix build-system rebar)}. It
- implements a build procedure around @uref{https://rebar3.org,rebar3},
- a build system for programs written in the Erlang language.
- It adds both @code{rebar3} and the @code{erlang} to the set of inputs.
- Different packages can be specified with the @code{#:rebar} and
- @code{#:erlang} parameters, respectively.
- This build system is based on @code{gnu-build-system}, but with the
- following phases changed:
- @table @code
- @item unpack
- This phase, after unpacking the source like the @code{gnu-build-system}
- does, checks for a file @code{contents.tar.gz} at the top-level of the
- source. If this file exists, it will be unpacked, too. This eases
- handling of package hosted at @uref{https://hex.pm/},
- the Erlang and Elixir package repository.
- @item bootstrap
- @item configure
- There are no @code{bootstrap} and @code{configure} phase because erlang
- packages typically don’t need to be configured.
- @item build
- This phase runs @code{rebar3 compile}
- with the flags listed in @code{#:rebar-flags}.
- @item check
- Unless @code{#:tests? #f} is passed,
- this phase runs @code{rebar3 eunit},
- or some other target specified with @code{#:test-target},
- with the flags listed in @code{#:rebar-flags},
- @item install
- This installs the files created in the @i{default} profile, or some
- other profile specified with @code{#:install-profile}.
- @end table
- @end defvar
- @defvar 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 tries to run @code{luatex} on all @file{.ins} files, and
- if it fails to find any, on all @file{.dtx} files. A different engine
- and format can be specified with, respectively, the @code{#:tex-engine}
- and @code{#:tex-format} arguments. Different build targets can be
- specified with the @code{#:build-targets} argument, which expects a list
- of file names.
- It also generates font metrics (i.e., @file{.tfm} files) out of Metafont
- files whenever possible. Likewise, it can also create TeX formats
- (i.e., @file{.fmt} files) listed in the @code{#:create-formats}
- argument, and generate a symbolic link from @file{bin/} directory to any
- script located in located in @file{texmf-dist/scripts/}, provided its
- file name is listed in @code{#:link-scripts} argument.
- The build system adds @code{texlive-bin} from @code{(gnu packages tex)}
- to the native inputs. It can be overridden with the
- @code{#:texlive-bin} argument.
- The package @code{texlive-latex-bin}, from the same module, contains
- most of the tools for building TeX Live packages; for convenience, it is
- also added by default to the native inputs. However, this can be
- troublesome when building a dependency of @code{texlive-latex-bin}
- itself. In this particular situation, the @code{#:texlive-latex-bin?}
- argument should be set to @code{#f}.
- @end defvar
- @defvar 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 defvar
- @defvar 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 defvar
- @defvar 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 defvar
- @defvar 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 defvar
- @defvar 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 defvar
- @anchor{emacs-build-system}
- @defvar 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 defvar
- @defvar 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 defvar
- @defvar meson-build-system
- This variable is exported by @code{(guix build-system meson)}. It
- implements the build procedure for packages that use
- @url{https://mesonbuild.com, Meson} as their build system.
- It adds both Meson and @uref{https://ninja-build.org/, Ninja} to the set
- of inputs, and they can be changed with the parameters @code{#:meson}
- and @code{#:ninja} if needed.
- This build system is an extension of @code{gnu-build-system}, but with the
- following phases changed to some specific for Meson:
- @table @code
- @item configure
- The phase runs @code{meson} with the flags specified in
- @code{#:configure-flags}. The flag @option{--buildtype} is always set to
- @code{debugoptimized} unless something else is specified in
- @code{#:build-type}.
- @item build
- The phase runs @code{ninja} to build the package in parallel by default, but
- this can be changed with @code{#:parallel-build?}.
- @item check
- The phase runs @samp{meson test} with a base set of options that cannot
- be overridden. This base set of options can be extended via the
- @code{#:test-options} argument, for example to select or skip a specific
- test suite.
- @item install
- The phase runs @code{ninja install} and can not be changed.
- @end table
- Apart from that, the build system also adds the following phases:
- @table @code
- @item fix-runpath
- This phase ensures that all binaries can find the libraries they need.
- It searches for required libraries in subdirectories of the package
- being built, and adds those to @code{RUNPATH} where needed. It also
- removes references to libraries left over from the build phase by
- @code{meson}, such as test dependencies, that aren't actually required
- for the program to run.
- @item glib-or-gtk-wrap
- This phase is the phase provided by @code{glib-or-gtk-build-system}, and it
- is not enabled by default. It can be enabled with @code{#:glib-or-gtk?}.
- @item glib-or-gtk-compile-schemas
- This phase is the phase provided by @code{glib-or-gtk-build-system}, and it
- is not enabled by default. It can be enabled with @code{#:glib-or-gtk?}.
- @end table
- @end defvar
- @defvar 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 defvar
- @defvar 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 defvar
- @defvar tree-sitter-build-system
- This variable is exported by @code{(guix build-system tree-sitter)}. It
- implements procedures to compile grammars for the
- @url{https://tree-sitter.github.io/tree-sitter/, Tree-sitter} parsing
- library. It essentially runs @code{tree-sitter generate} to translate
- @code{grammar.js} grammars to JSON and then to C. Which it then
- compiles to native code.
- Tree-sitter packages may support multiple grammars, so this build system
- supports a @code{#:grammar-directories} keyword to specify a list of
- locations where a @code{grammar.js} file may be found.
- Grammars sometimes depend on each other, such as C++ depending on C and
- TypeScript depending on JavaScript. You may use inputs to declare such
- dependencies.
- @end defvar
- 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.
- @defvar 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 defvar
- @defvar channel-build-system
- This variable is exported by @code{(guix build-system channel)}.
- This build system is meant primarily for internal use. A package using
- this build system must have a channel specification as its @code{source}
- field (@pxref{Channels}); alternatively, its source can be a directory
- name, in which case an additional @code{#:commit} argument must be
- supplied to specify the commit being built (a hexadecimal string).
- The resulting package is a Guix instance of the given channel, similar
- to how @command{guix time-machine} would build it.
- @end defvar
- @node Build Phases
- @section Build Phases
- @cindex build phases, for packages
- Almost all package build systems implement a notion @dfn{build phases}:
- a sequence of actions that the build system executes, when you build the
- package, leading to the installed byproducts in the store. A notable
- exception is the ``bare-bones'' @code{trivial-build-system}
- (@pxref{Build Systems}).
- As discussed in the previous section, those build systems provide a
- standard list of phases. For @code{gnu-build-system}, the main build
- phases are the following:
- @table @code
- @item set-paths
- Define search path environment variables for all the input packages,
- including @env{PATH} (@pxref{Search Paths}).
- @item unpack
- Unpack the source tarball, and change the current directory to the
- extracted source tree. If the source is actually a directory, copy it
- to the build tree, and enter that directory.
- @item patch-source-shebangs
- Patch shebangs encountered in source files so they refer to the right
- store file names. For instance, this changes @code{#!/bin/sh} to
- @code{#!/gnu/store/@dots{}-bash-4.3/bin/sh}.
- @item configure
- Run the @file{configure} script with a number of default options, such
- as @option{--prefix=/gnu/store/@dots{}}, as well as the options specified
- by the @code{#:configure-flags} argument.
- @item build
- Run @code{make} with the list of flags specified with
- @code{#:make-flags}. If the @code{#:parallel-build?} argument is true
- (the default), build with @code{make -j}.
- @item check
- Run @code{make check}, or some other target specified with
- @code{#:test-target}, unless @code{#:tests? #f} is passed. If the
- @code{#:parallel-tests?} argument is true (the default), run @code{make
- check -j}.
- @item install
- Run @code{make install} with the flags listed in @code{#:make-flags}.
- @item patch-shebangs
- Patch shebangs on the installed executable files.
- @item strip
- Strip debugging symbols from ELF files (unless @code{#:strip-binaries?}
- is false), copying them to the @code{debug} output when available
- (@pxref{Installing Debugging Files}).
- @cindex RUNPATH, validation
- @anchor{phase-validate-runpath}
- @item validate-runpath
- Validate the @code{RUNPATH} of ELF binaries, unless
- @code{#:validate-runpath?} is false (@pxref{Build Systems}).
- 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}.
- @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
- (list
- #:phases
- #~(modify-phases %standard-phases
- (delete 'configure)
- (add-before 'build 'set-prefix-in-makefile
- (lambda* (#:key inputs #:allow-other-keys)
- ;; Modify the makefile so that its
- ;; 'PREFIX' variable points to #$output and
- ;; 'XMLLINT' points to the correct path.
- (substitute* "Makefile"
- (("PREFIX =.*")
- (string-append "PREFIX = " #$output "\n"))
- (("XMLLINT =.*")
- (string-append "XMLLINT = "
- (search-input-file inputs "/bin/xmllint")
- "\n"))))))))))
- @end lisp
- The new phase that is inserted is written as an anonymous procedure,
- introduced with @code{lambda*}; it looks for the @file{xmllint}
- executable under a @file{/bin} directory among the package's inputs
- (@pxref{package Reference}). It also 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 {Procedure} %store-directory
- Return the directory name of the store.
- @end deffn
- @deffn {Procedure} store-file-name? file
- Return true if @var{file} is in the store.
- @end deffn
- @deffn {Procedure} strip-store-file-name 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 {Procedure} package-name->name+version 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 {Procedure} directory-exists? dir
- Return @code{#t} if @var{dir} exists and is a directory.
- @end deffn
- @deffn {Procedure} executable-file? file
- Return @code{#t} if @var{file} exists and is executable.
- @end deffn
- @deffn {Procedure} symbolic-link? file
- Return @code{#t} if @var{file} is a symbolic link (aka. a ``symlink'').
- @end deffn
- @deffn {Procedure} elf-file? file
- @deffnx {Procedure} ar-file? file
- @deffnx {Procedure} gzip-file? 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 {Procedure} reset-gzip-timestamp 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}).
- @defmac with-directory-excursion directory 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 defmac
- @deffn {Procedure} mkdir-p dir
- Create directory @var{dir} and all its ancestors.
- @end deffn
- @deffn {Procedure} install-file file directory
- Create @var{directory} if it does not exist and copy @var{file} in there
- under the same name.
- @end deffn
- @deffn {Procedure} make-file-writable file
- Make @var{file} writable for its owner.
- @end deffn
- @deffn {Procedure} copy-recursively source 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 {Procedure} delete-file-recursively 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
- @defmac substitute* file @
- ((regexp match-var@dots{}) body@dots{}) @dots{}
- Substitute @var{regexp} in @var{file} by the string returned by
- @var{body}. @var{body} is evaluated with each @var{match-var} bound to
- the corresponding positional regexp sub-expression. For example:
- @lisp
- (substitute* file
- (("hello")
- "good morning\n")
- (("foo([a-z]+)bar(.*)$" all letters end)
- (string-append "baz" letters end)))
- @end lisp
- Here, anytime a line of @var{file} contains @code{hello}, it is replaced
- by @code{good morning}. Anytime a line of @var{file} matches the second
- regexp, @code{all} is bound to the complete match, @code{letters} is bound
- to the first sub-expression, and @code{end} is bound to the last one.
- When one of the @var{match-var} is @code{_}, no variable is bound to the
- corresponding match substring.
- Alternatively, @var{file} may be a list of file names, in which case
- they are all subject to the substitutions.
- Be careful about using @code{$} to match the end of a line; by itself it
- won't match the terminating newline of a line. For example, to match a
- whole line ending with a backslash, one needs a regex like
- @code{"(.*)\\\\\n$"}.
- @end defmac
- @subsection File Search
- @cindex file, searching
- This section documents procedures to search and filter files.
- @deffn {Procedure} file-name-predicate regexp
- Return a predicate that returns true when passed a file name whose base
- name matches @var{regexp}.
- @end deffn
- @deffn {Procedure} find-files dir [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 {Procedure} which 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 {Procedure} search-input-file inputs name
- @deffnx {Procedure} search-input-directory inputs name
- Return the complete file name for @var{name} as found in @var{inputs};
- @code{search-input-file} searches for a regular file and
- @code{search-input-directory} searches for a directory. If @var{name}
- could not be found, an exception is raised.
- Here, @var{inputs} must be an association list like @code{inputs} and
- @code{native-inputs} as available to build phases (@pxref{Build
- Phases}).
- @end deffn
- Here is a (simplified) example of how @code{search-input-file} is used
- in a build phase of the @code{wireguard-tools} package:
- @lisp
- (add-after 'install 'wrap-wg-quick
- (lambda* (#:key inputs outputs #:allow-other-keys)
- (let ((coreutils (string-append (assoc-ref inputs "coreutils")
- "/bin")))
- (wrap-program (search-input-file outputs "bin/wg-quick")
- #:sh (search-input-file inputs "bin/bash")
- `("PATH" ":" prefix ,(list coreutils))))))
- @end lisp
- @subsection Program Invocation
- @cindex program invocation, from Scheme
- @cindex invoking programs, from Scheme
- You'll find handy procedures to spawn processes in this module,
- essentially convenient wrappers around Guile's @code{system*}
- (@pxref{Processes, @code{system*},, guile, GNU Guile Reference Manual}).
- @deffn {Procedure} invoke program args@dots{}
- Invoke @var{program} with the given @var{args}. Raise an
- @code{&invoke-error} exception if the exit code is non-zero; otherwise
- return @code{#t}.
- The advantage compared to @code{system*} is that you do not need to
- check the return value. This reduces boilerplate in shell-script-like
- snippets for instance in package build phases.
- @end deffn
- @deffn {Procedure} invoke-error? c
- Return true if @var{c} is an @code{&invoke-error} condition.
- @end deffn
- @deffn {Procedure} invoke-error-program c
- @deffnx {Procedure} invoke-error-arguments c
- @deffnx {Procedure} invoke-error-exit-status c
- @deffnx {Procedure} invoke-error-term-signal c
- @deffnx {Procedure} invoke-error-stop-signal c
- Access specific fields of @var{c}, an @code{&invoke-error} condition.
- @end deffn
- @deffn {Procedure} report-invoke-error c [port]
- Report to @var{port} (by default the current error port) about @var{c},
- an @code{&invoke-error} condition, in a human-friendly way.
- Typical usage would look like this:
- @lisp
- (use-modules (srfi srfi-34) ;for 'guard'
- (guix build utils))
- (guard (c ((invoke-error? c)
- (report-invoke-error c)))
- (invoke "date" "--imaginary-option"))
- @print{} command "date" "--imaginary-option" failed with status 1
- @end lisp
- @end deffn
- @deffn {Procedure} invoke/quiet program args@dots{}
- Invoke @var{program} with @var{args} and capture @var{program}'s
- standard output and standard error. If @var{program} succeeds, print
- nothing and return the unspecified value; otherwise, raise a
- @code{&message} error condition that includes the status code and the
- output of @var{program}.
- Here's an example:
- @lisp
- (use-modules (srfi srfi-34) ;for 'guard'
- (srfi srfi-35) ;for 'message-condition?'
- (guix build utils))
- (guard (c ((message-condition? c)
- (display (condition-message c))))
- (invoke/quiet "date") ;all is fine
- (invoke/quiet "date" "--imaginary-option"))
- @print{} 'date --imaginary-option' exited with status 1; output follows:
- date: unrecognized option '--imaginary-option'
- Try 'date --help' for more information.
- @end lisp
- @end deffn
- @subsection Build Phases
- @cindex build phases
- The @code{(guix build utils)} also contains tools to manipulate build
- phases as used by build systems (@pxref{Build Systems}). Build phases
- are represented as association lists or ``alists'' (@pxref{Association
- Lists,,, guile, GNU Guile Reference Manual}) where each key is a symbol
- naming the phase and the associated value is a procedure (@pxref{Build
- Phases}).
- Guile core and the @code{(srfi srfi-1)} module both provide tools to
- manipulate alists. The @code{(guix build utils)} module complements
- those with tools written with build phases in mind.
- @cindex build phases, modifying
- @defmac modify-phases phases 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 defmac
- The example below is taken from the definition of the @code{grep}
- package. It adds a phase to run after the @code{install} phase, called
- @code{fix-egrep-and-fgrep}. That phase is a procedure (@code{lambda*}
- is for anonymous procedures) that takes a @code{#:outputs} keyword
- argument and ignores extra keyword arguments (@pxref{Optional
- Arguments,,, guile, GNU Guile Reference Manual}, for more on
- @code{lambda*} and optional and keyword arguments.) The phase uses
- @code{substitute*} to modify the installed @file{egrep} and @file{fgrep}
- scripts so that they refer to @code{grep} by its absolute file name:
- @lisp
- (modify-phases %standard-phases
- (add-after 'install 'fix-egrep-and-fgrep
- ;; Patch 'egrep' and 'fgrep' to execute 'grep' via its
- ;; absolute file name instead of searching for it in $PATH.
- (lambda* (#:key outputs #:allow-other-keys)
- (let* ((out (assoc-ref outputs "out"))
- (bin (string-append out "/bin")))
- (substitute* (list (string-append bin "/egrep")
- (string-append bin "/fgrep"))
- (("^exec grep")
- (string-append "exec " bin "/grep")))))))
- @end lisp
- In the example below, phases are modified in two ways: the standard
- @code{configure} phase is deleted, presumably because the package does
- not have a @file{configure} script or anything similar, and the default
- @code{install} phase is replaced by one that manually copies the
- executable files to be installed:
- @lisp
- (modify-phases %standard-phases
- (delete 'configure) ;no 'configure' script
- (replace 'install
- (lambda* (#:key outputs #:allow-other-keys)
- ;; The package's Makefile doesn't provide an "install"
- ;; rule so do it by ourselves.
- (let ((bin (string-append (assoc-ref outputs "out")
- "/bin")))
- (install-file "footswitch" bin)
- (install-file "scythe" bin)))))
- @end lisp
- @c TODO: Add more examples.
- @subsection Wrappers
- @cindex program wrappers
- @cindex wrapping programs
- It is not unusual for a command to require certain environment variables
- to be set for proper functioning, typically search paths (@pxref{Search
- Paths}). Failing to do that, the command might fail to find files or
- other commands it relies on, or it might pick the ``wrong''
- ones---depending on the environment in which it runs. Examples include:
- @itemize
- @item
- a shell script that assumes all the commands it uses are in @env{PATH};
- @item
- a Guile program that assumes all its modules are in @env{GUILE_LOAD_PATH}
- and @env{GUILE_LOAD_COMPILED_PATH};
- @item
- a Qt application that expects to find certain plugins in
- @env{QT_PLUGIN_PATH}.
- @end itemize
- For a package writer, the goal is to make sure commands always work the
- same rather than depend on some external settings. One way to achieve
- that is to @dfn{wrap} commands in a thin script that sets those
- environment variables, thereby ensuring that those run-time dependencies
- are always found. The wrapper would be used to set @env{PATH},
- @env{GUILE_LOAD_PATH}, or @env{QT_PLUGIN_PATH} in the examples above.
- To ease that task, the @code{(guix build utils)} module provides a
- couple of helpers to wrap commands.
- @deffn {Procedure} wrap-program program [#:sh sh] [#:rest variables]
- Make a wrapper for @var{program}. @var{variables} should look like this:
- @lisp
- '(@var{variable} @var{delimiter} @var{position} @var{list-of-directories})
- @end lisp
- where @var{delimiter} is optional. @code{:} will be used if
- @var{delimiter} is not given.
- For example, this call:
- @lisp
- (wrap-program "foo"
- '("PATH" ":" = ("/gnu/.../bar/bin"))
- '("CERT_PATH" suffix ("/gnu/.../baz/certs"
- "/qux/certs")))
- @end lisp
- will copy @file{foo} to @file{.foo-real} and create the file @file{foo}
- with the following contents:
- @example
- #!location/of/bin/bash
- export PATH="/gnu/.../bar/bin"
- export CERT_PATH="$CERT_PATH$@{CERT_PATH:+:@}/gnu/.../baz/certs:/qux/certs"
- exec -a $0 location/of/.foo-real "$@@"
- @end example
- If @var{program} has previously been wrapped by @code{wrap-program}, the
- wrapper is extended with definitions for @var{variables}. If it is not,
- @var{sh} will be used as the interpreter.
- @end deffn
- @deffn {Procedure} wrap-script program [#:guile guile] [#:rest variables]
- Wrap the script @var{program} such that @var{variables} are set first.
- The format of @var{variables} is the same as in the @code{wrap-program}
- procedure. This procedure differs from @code{wrap-program} in that it
- does not create a separate shell script. Instead, @var{program} is
- modified directly by prepending a Guile script, which is interpreted as
- a comment in the script's language.
- Special encoding comments as supported by Python are recreated on the
- second line.
- Note that this procedure can only be used once per file as Guile scripts are
- not supported.
- @end deffn
- @node Search Paths
- @section Search Paths
- @cindex search path
- Many programs and libraries look for input data in a @dfn{search path},
- a list of directories: shells like Bash look for executables in the
- command search path, a C compiler looks for @file{.h} files in its
- header search path, the Python interpreter looks for @file{.py}
- files in its search path, the spell checker has a search path for
- dictionaries, and so on.
- Search paths can usually be defined or overridden @i{via} environment
- variables (@pxref{Environment Variables,,, libc, The GNU C Library
- Reference Manual}). For example, the search paths mentioned above can
- be changed by defining the @env{PATH}, @env{C_INCLUDE_PATH},
- @env{PYTHONPATH} (or @env{GUIX_PYTHONPATH}), and @env{DICPATH}
- environment variables---you know, all these something-PATH variables
- that you need to get right or things ``won't be found''.
- You may have noticed from the command line that Guix ``knows'' which
- search path environment variables should be defined, and how. When you
- install packages in your default profile, the file
- @file{~/.guix-profile/etc/profile} is created, which you can ``source''
- from the shell to set those variables. Likewise, if you ask
- @command{guix shell} to create an environment containing Python and
- NumPy, a Python library, and if you pass it the @option{--search-paths}
- option, it will tell you about @env{PATH} and @env{GUIX_PYTHONPATH}
- (@pxref{Invoking guix shell}):
- @example
- $ guix shell python python-numpy --pure --search-paths
- export PATH="/gnu/store/@dots{}-profile/bin"
- export GUIX_PYTHONPATH="/gnu/store/@dots{}-profile/lib/python3.9/site-packages"
- @end example
- When you omit @option{--search-paths}, it defines these environment
- variables right away, such that Python can readily find NumPy:
- @example
- $ guix shell python python-numpy -- python3
- Python 3.9.6 (default, Jan 1 1970, 00:00:01)
- [GCC 10.3.0] on linux
- Type "help", "copyright", "credits" or "license" for more information.
- >>> import numpy
- >>> numpy.version.version
- '1.20.3'
- @end example
- For this to work, the definition of the @code{python} package
- @emph{declares} the search path it cares about and its associated
- environment variable, @env{GUIX_PYTHONPATH}. It looks like this:
- @lisp
- (package
- (name "python")
- (version "3.9.9")
- ;; some fields omitted...
- (native-search-paths
- (list (search-path-specification
- (variable "GUIX_PYTHONPATH")
- (files (list "lib/python/3.9/site-packages"))))))
- @end lisp
- What this @code{native-search-paths} field says is that, when the
- @code{python} package is used, the @env{GUIX_PYTHONPATH} environment
- variable must be defined to include all the
- @file{lib/python/3.9/site-packages} sub-directories encountered in its
- environment. (The @code{native-} bit means that, if we are in a
- cross-compilation environment, only native inputs may be added to the
- search path; @pxref{package Reference, @code{search-paths}}.)
- In the NumPy example above, the profile where
- @code{python} appears contains exactly one such sub-directory, and
- @env{GUIX_PYTHONPATH} is set to that. When there are several
- @file{lib/python/3.9/site-packages}---this is the case in package build
- environments---they are all added to @env{GUIX_PYTHONPATH}, separated by
- colons (@code{:}).
- @quotation Note
- Notice that @env{GUIX_PYTHONPATH} is specified as part of the definition
- of the @code{python} package, and @emph{not} as part of that of
- @code{python-numpy}. This is because this environment variable
- ``belongs'' to Python, not NumPy: Python actually reads the value of
- that variable and honors it.
- Corollary: if you create a profile that does not contain @code{python},
- @code{GUIX_PYTHONPATH} will @emph{not} be defined, even if it contains
- packages that provide @file{.py} files:
- @example
- $ guix shell python-numpy --search-paths --pure
- export PATH="/gnu/store/@dots{}-profile/bin"
- @end example
- This makes a lot of sense if we look at this profile in isolation: no
- software in this profile would read @env{GUIX_PYTHONPATH}.
- @end quotation
- Of course, there are many variations on that theme: some packages honor
- more than one search path, some use separators other than colon, some
- accumulate several directories in their search path, and so on. A more
- complex example is the search path of libxml2: the value of the
- @env{XML_CATALOG_FILES} environment variable is space-separated, it must
- contain a list of @file{catalog.xml} files (not directories), which are
- to be found in @file{xml} sub-directories---nothing less. The search
- path specification looks like this:
- @lisp
- (package
- (name "libxml2")
- ;; some fields omitted
- (native-search-paths
- (list (search-path-specification
- (variable "XML_CATALOG_FILES")
- (separator " ")
- (files '("xml"))
- (file-pattern "^catalog\\.xml$")
- (file-type 'regular)))))
- @end lisp
- Worry not, search path specifications are usually not this tricky.
- The @code{(guix search-paths)} module defines the data type of search
- path specifications and a number of helper procedures. Below is the
- reference of search path specifications.
- @deftp {Data Type} search-path-specification
- The data type for search path specifications.
- @table @asis
- @item @code{variable}
- The name of the environment variable for this search path (a string).
- @item @code{files}
- The list of sub-directories (strings) that should be added to the search
- path.
- @item @code{separator} (default: @code{":"})
- The string used to separate search path components.
- As a special case, a @code{separator} value of @code{#f} specifies a
- ``single-component search path''---in other words, a search path that
- cannot contain more than one element. This is useful in some cases,
- such as the @code{SSL_CERT_DIR} variable (honored by OpenSSL, cURL, and
- a few other packages) or the @code{ASPELL_DICT_DIR} variable (honored by
- the GNU Aspell spell checker), both of which must point to a single
- directory.
- @item @code{file-type} (default: @code{'directory})
- The type of file being matched---@code{'directory} or @code{'regular},
- though it can be any symbol returned by @code{stat:type} (@pxref{File
- System, @code{stat},, guile, GNU Guile Reference Manual}).
- In the libxml2 example above, we would match regular files; in the
- Python example, we would match directories.
- @item @code{file-pattern} (default: @code{#f})
- This must be either @code{#f} or a regular expression specifying
- files to be matched @emph{within} the sub-directories specified by the
- @code{files} field.
- Again, the libxml2 example shows a situation where this is needed.
- @end table
- @end deftp
- Some search paths are not tied by a single package but to many packages.
- To reduce duplications, some of them are pre-defined in @code{(guix
- search-paths)}.
- @defvar $SSL_CERT_DIR
- @defvarx $SSL_CERT_FILE
- These two search paths indicate where X.509 certificates can be found
- (@pxref{X.509 Certificates}).
- @end defvar
- These pre-defined search paths can be used as in the following example:
- @lisp
- (package
- (name "curl")
- ;; some fields omitted ...
- (native-search-paths (list $SSL_CERT_DIR $SSL_CERT_FILE)))
- @end lisp
- How do you turn search path specifications on one hand and a bunch of
- directories on the other hand in a set of environment variable
- definitions? That's the job of @code{evaluate-search-paths}.
- @deffn {Procedure} evaluate-search-paths search-paths directories [getenv]
- Evaluate @var{search-paths}, a list of search-path specifications, for
- @var{directories}, a list of directory names, and return a list of
- specification/value pairs. Use @var{getenv} to determine the current
- settings and report only settings not already effective.
- @end deffn
- The @code{(guix profiles)} provides a higher-level helper procedure,
- @code{load-profile}, that sets the environment variables of a profile.
- @node The Store
- @section The Store
- @cindex store
- @cindex store items
- @cindex store paths
- Conceptually, the @dfn{store} is the place where derivations that have
- been built successfully are stored---by default, @file{/gnu/store}.
- Sub-directories in the store are referred to as @dfn{store items} or
- sometimes @dfn{store paths}. The store has an associated database that
- contains information such as the store paths referred to by each store
- path, and the list of @emph{valid} store items---results of successful
- builds. This database resides in @file{@var{localstatedir}/guix/db},
- where @var{localstatedir} is the state directory specified @i{via}
- @option{--localstatedir} at configure time, usually @file{/var}.
- The store is @emph{always} accessed by the daemon on behalf of its clients
- (@pxref{Invoking guix-daemon}). To manipulate the store, clients
- connect to the daemon over a Unix-domain socket, send requests to it,
- and read the result---these are remote procedure calls, or RPCs.
- @quotation Note
- Users must @emph{never} modify files under @file{/gnu/store} directly.
- This would lead to inconsistencies and break the immutability
- assumptions of Guix's functional model (@pxref{Introduction}).
- @xref{Invoking guix gc, @command{guix gc --verify}}, for information on
- how to check the integrity of the store and attempt recovery from
- accidental modifications.
- @end quotation
- The @code{(guix store)} module provides procedures to connect to the
- daemon, and to perform RPCs. These are described below. By default,
- @code{open-connection}, and thus all the @command{guix} commands,
- connect to the local daemon or to the URI specified by the
- @env{GUIX_DAEMON_SOCKET} environment variable.
- @defvr {Environment Variable} GUIX_DAEMON_SOCKET
- When set, the value of this variable should be a file name or a URI
- designating the daemon endpoint. When it is a file name, it denotes a
- Unix-domain socket to connect to. In addition to file names, the
- supported URI schemes are:
- @table @code
- @item file
- @itemx unix
- These are for Unix-domain sockets.
- @code{file:///var/guix/daemon-socket/socket} is equivalent to
- @file{/var/guix/daemon-socket/socket}.
- @item guix
- @cindex daemon, remote access
- @cindex remote access to the daemon
- @cindex daemon, cluster setup
- @cindex clusters, daemon setup
- These URIs denote connections over TCP/IP, without encryption nor
- authentication of the remote host. The URI must specify the host name
- and optionally a port number (by default port 44146 is used):
- @example
- guix://master.guix.example.org:1234
- @end example
- This setup is suitable on local networks, such as clusters, where only
- trusted nodes may connect to the build daemon at
- @code{master.guix.example.org}.
- The @option{--listen} option of @command{guix-daemon} can be used to
- instruct it to listen for TCP connections (@pxref{Invoking guix-daemon,
- @option{--listen}}).
- @item ssh
- @cindex SSH access to build daemons
- These URIs allow you to connect to a remote daemon over SSH@. This
- feature requires Guile-SSH (@pxref{Requirements}) and a working
- @command{guile} binary in @env{PATH} on the destination machine. It
- supports public key and GSSAPI authentication. A typical URL might look
- like this:
- @example
- ssh://charlie@@guix.example.org:22
- @end example
- As for @command{guix copy}, the usual OpenSSH client configuration files
- are honored (@pxref{Invoking guix copy}).
- @end table
- Additional URI schemes may be supported in the future.
- @c XXX: Remove this note when the protocol incurs fewer round trips
- @c and when (guix derivations) no longer relies on file system access.
- @quotation Note
- The ability to connect to remote build daemons is considered
- experimental as of @value{VERSION}. Please get in touch with us to
- share any problems or suggestions you may have (@pxref{Contributing}).
- @end quotation
- @end defvr
- @deffn {Procedure} open-connection [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 {Procedure} close-connection server
- Close the connection to @var{server}.
- @end deffn
- @defvar 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 defvar
- Procedures that make RPCs all take a server object as their first
- argument.
- @cindex invalid store items
- @deffn {Procedure} valid-path? server path
- 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 {Procedure} add-text-to-store server name text [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 {Procedure} build-derivations store derivations [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 {Procedure} derivation store name builder 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 {Procedure} build-expression->derivation store name 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 ``commands'' to make it easier to deal with monadic procedures:
- @code{run-in-store}, and @code{enter-store-monad} (@pxref{Using Guix
- Interactively}). 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.
- Other meta-commands are available at the REPL, such as @code{,build} to
- build a file-like object (@pxref{Using Guix Interactively}).
- The main syntactic forms to deal with monads in general are provided by
- the @code{(guix monads)} module and are described below.
- @defmac with-monad monad body @dots{}
- Evaluate any @code{>>=} or @code{return} forms in @var{body} as being
- in @var{monad}.
- @end defmac
- @defmac return val
- Return a monadic value that encapsulates @var{val}.
- @end defmac
- @defmac >>= mval mproc @dots{}
- @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 defmac
- @defmac mlet monad ((var mval) @dots{}) body @dots{}
- @defmacx mlet* monad ((var mval) @dots{}) body @dots{}
- 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 defmac
- @defmac mbegin monad mexp @dots{}
- 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 defmac
- @defmac mwhen condition mexp0 mexp* @dots{}
- 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 defmac
- @defmac munless condition mexp0 mexp* @dots{}
- 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 defmac
- @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.
- @defvar %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 defvar
- @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 {Procedure} run-with-state mval [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.
- @defvar %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 defvar
- @deffn {Procedure} run-with-store store mval @
- [#:guile-for-build] [#:system (%current-system)]
- Run @var{mval}, a monadic value in the store monad, in @var{store}, an
- open store connection.
- @end deffn
- @deffn {Monadic Procedure} text-file @var{name} @var{text} [@var{references}]
- Return as a monadic value the absolute file name in the store of the file
- containing @var{text}, a string. @var{references} is a list of store items that the
- resulting text file refers to; it defaults to the empty list.
- @end deffn
- @deffn {Monadic Procedure} binary-file @var{name} @var{data} [@var{references}]
- Return as a monadic value the absolute file name in the store of the file
- containing @var{data}, a bytevector. @var{references} is a list of store
- items that the resulting binary file refers to; it defaults to the empty list.
- @end deffn
- @deffn {Monadic Procedure} interned-file @var{file} [@var{name}] @
- [#:recursive? #t] [#:select? (const #t)]
- Return the name of @var{file} once interned in the store. Use
- @var{name} as its store name, or the basename of @var{file} if
- @var{name} is omitted.
- When @var{recursive?} is true, the contents of @var{file} are added
- recursively; if @var{file} designates a flat file and @var{recursive?}
- is true, its contents are added, and its permission bits are kept.
- When @var{recursive?} is true, call @code{(@var{select?} @var{file}
- @var{stat})} for each directory entry, where @var{file} is the entry's
- absolute file name and @var{stat} is the result of @code{lstat}; exclude
- entries for which @var{select?} does not return true.
- The example below adds a file to the store, under two different names:
- @lisp
- (run-with-store (open-connection)
- (mlet %store-monad ((a (interned-file "README"))
- (b (interned-file "README" "LEGU-MIN")))
- (return (list a b))))
- @result{} ("/gnu/store/rwm@dots{}-README" "/gnu/store/44i@dots{}-LEGU-MIN")
- @end lisp
- @end deffn
- The @code{(guix packages)} module exports the following package-related
- monadic procedures:
- @deffn {Monadic Procedure} package-file @var{package} [@var{file}] @
- [#:system (%current-system)] [#:target #f] @
- [#:output "out"]
- Return as a monadic
- value in the absolute file name of @var{file} within the @var{output}
- directory of @var{package}. When @var{file} is omitted, return the name
- of the @var{output} directory of @var{package}. When @var{target} is
- true, use it as a cross-compilation target triplet.
- Note that this procedure does @emph{not} build @var{package}. Thus, the
- result might or might not designate an existing file. We recommend not
- using this procedure unless you know what you are doing.
- @end deffn
- @deffn {Monadic Procedure} package->derivation @var{package} [@var{system}]
- @deffnx {Monadic Procedure} package->cross-derivation @var{package} @
- @var{target} [@var{system}]
- Monadic version of @code{package-derivation} and
- @code{package-cross-derivation} (@pxref{Defining Packages}).
- @end deffn
- @node G-Expressions
- @section G-Expressions
- @cindex G-expression
- @cindex build code quoting
- So we have ``derivations'', which represent a sequence of build actions
- to be performed to produce an item in the store (@pxref{Derivations}).
- These build actions are performed when asking the daemon to actually
- build the derivations; they are run by the daemon in a container
- (@pxref{Invoking guix-daemon}).
- @cindex code staging
- @cindex staging, of code
- @cindex strata of code
- It should come as no surprise that we like to write these build actions
- in Scheme. When we do that, we end up with two @dfn{strata} of Scheme
- code@footnote{The term @dfn{stratum} in this context was coined by
- Manuel Serrano et al.@: in the context of their work on Hop. Oleg
- Kiselyov, who has written insightful
- @url{http://okmij.org/ftp/meta-programming/#meta-scheme, essays and code
- on this topic}, refers to this kind of code generation as
- @dfn{staging}.}: the ``host code''---code that defines packages, talks
- to the daemon, etc.---and the ``build code''---code that actually
- performs build actions, such as making directories, invoking
- @command{make}, and so on (@pxref{Build Phases}).
- To describe a derivation and its build actions, one typically needs to
- embed build code inside host code. It boils down to manipulating build
- code as data, and the homoiconicity of Scheme---code has a direct
- representation as data---comes in handy for that. But we need more than
- the normal @code{quasiquote} mechanism in Scheme to construct build
- expressions.
- The @code{(guix gexp)} module implements @dfn{G-expressions}, a form of
- S-expressions adapted to build expressions. G-expressions, or
- @dfn{gexps}, consist essentially of three syntactic forms: @code{gexp},
- @code{ungexp}, and @code{ungexp-splicing} (or simply: @code{#~},
- @code{#$}, and @code{#$@@}), which are comparable to
- @code{quasiquote}, @code{unquote}, and @code{unquote-splicing},
- respectively (@pxref{Expression Syntax, @code{quasiquote},, guile,
- GNU Guile Reference Manual}). However, there are major differences:
- @itemize
- @item
- Gexps are meant to be written to a file and run or manipulated by other
- processes.
- @item
- When a high-level object such as a package or derivation is unquoted
- inside a gexp, the result is as if its output file name had been
- introduced.
- @item
- Gexps carry information about the packages or derivations they refer to,
- and these dependencies are automatically added as inputs to the build
- processes that use them.
- @end itemize
- @cindex lowering, of high-level objects in gexps
- This mechanism is not limited to package and derivation
- objects: @dfn{compilers} able to ``lower'' other high-level objects to
- derivations or files in the store can be defined,
- such that these objects can also be inserted
- into gexps. For example, a useful type of high-level objects that can be
- inserted in a gexp is ``file-like objects'', which make it easy to
- add files to the store and to refer to them in
- derivations and such (see @code{local-file} and @code{plain-file}
- below).
- To illustrate the idea, here is an example of a gexp:
- @lisp
- (define build-exp
- #~(begin
- (mkdir #$output)
- (chdir #$output)
- (symlink (string-append #$coreutils "/bin/ls")
- "list-files")))
- @end lisp
- This gexp can be passed to @code{gexp->derivation}; we obtain a
- derivation that builds a directory containing exactly one symlink to
- @file{/gnu/store/@dots{}-coreutils-8.22/bin/ls}:
- @lisp
- (gexp->derivation "the-thing" build-exp)
- @end lisp
- As one would expect, the @code{"/gnu/store/@dots{}-coreutils-8.22"} string is
- substituted to the reference to the @var{coreutils} package in the
- actual build code, and @var{coreutils} is automatically made an input to
- the derivation. Likewise, @code{#$output} (equivalent to @code{(ungexp
- output)}) is replaced by a string containing the directory name of the
- output of the derivation.
- @cindex cross compilation
- In a cross-compilation context, it is useful to distinguish between
- references to the @emph{native} build of a package---that can run on the
- host---versus references to cross builds of a package. To that end, the
- @code{#+} plays the same role as @code{#$}, but is a reference to a
- native package build:
- @lisp
- (gexp->derivation "vi"
- #~(begin
- (mkdir #$output)
- (mkdir (string-append #$output "/bin"))
- (system* (string-append #+coreutils "/bin/ln")
- "-s"
- (string-append #$emacs "/bin/emacs")
- (string-append #$output "/bin/vi")))
- #:target "aarch64-linux-gnu")
- @end lisp
- @noindent
- In the example above, the native build of @var{coreutils} is used, so
- that @command{ln} can actually run on the host; but then the
- cross-compiled build of @var{emacs} is referenced.
- @cindex imported modules, for gexps
- @findex with-imported-modules
- Another gexp feature is @dfn{imported modules}: sometimes you want to be
- able to use certain Guile modules from the ``host environment'' in the
- gexp, so those modules should be imported in the ``build environment''.
- The @code{with-imported-modules} form allows you to express that:
- @lisp
- (let ((build (with-imported-modules '((guix build utils))
- #~(begin
- (use-modules (guix build utils))
- (mkdir-p (string-append #$output "/bin"))))))
- (gexp->derivation "empty-dir"
- #~(begin
- #$build
- (display "success!\n")
- #t)))
- @end lisp
- @noindent
- In this example, the @code{(guix build utils)} module is automatically
- pulled into the isolated build environment of our gexp, such that
- @code{(use-modules (guix build utils))} works as expected.
- @cindex module closure
- @findex source-module-closure
- Usually you want the @emph{closure} of the module to be imported---i.e.,
- the module itself and all the modules it depends on---rather than just
- the module; failing to do that, attempts to use the module will fail
- because of missing dependent modules. The @code{source-module-closure}
- procedure computes the closure of a module by looking at its source file
- headers, which comes in handy in this case:
- @lisp
- (use-modules (guix modules)) ;for 'source-module-closure'
- (with-imported-modules (source-module-closure
- '((guix build utils)
- (gnu build image)))
- (gexp->derivation "something-with-vms"
- #~(begin
- (use-modules (guix build utils)
- (gnu build image))
- @dots{})))
- @end lisp
- @cindex extensions, for gexps
- @findex with-extensions
- In the same vein, sometimes you want to import not just pure-Scheme
- modules, but also ``extensions'' such as Guile bindings to C libraries
- or other ``full-blown'' packages. Say you need the @code{guile-json}
- package available on the build side, here's how you would do it:
- @lisp
- (use-modules (gnu packages guile)) ;for 'guile-json'
- (with-extensions (list guile-json)
- (gexp->derivation "something-with-json"
- #~(begin
- (use-modules (json))
- @dots{})))
- @end lisp
- The syntactic form to construct gexps is summarized below.
- @defmac #~@var{exp}
- @defmacx (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 defmac
- @defmac with-imported-modules modules 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 defmac
- @defmac with-extensions extensions 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 defmac
- @deffn {Procedure} gexp? 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 {Procedure} local-file file [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 {Procedure} plain-file name 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 {Procedure} computed-file name 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 {Procedure} program-file name 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 {Procedure} scheme-file name 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 {Procedure} mixed-text-file name 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 {Procedure} file-union name 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 {Procedure} directory-union name 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 {Procedure} file-append obj 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
- @defmac let-system system body@dots{}
- @defmacx let-system (system target) 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 defmac
- @defmac with-parameters ((parameter value) @dots{}) 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 defmac
- 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 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 @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
- To make a script that launches an interactive REPL directly from the
- shell, use the @code{--interactive} flag:
- @example
- @code{#!/usr/bin/env -S guix repl --interactive}
- @code{!#}
- @end example
- Without a file name argument, a Guile REPL is started, allowing for
- interactive use (@pxref{Using Guix Interactively}):
- @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 --list-types
- Display the @var{TYPE} options for @command{guix repl --type=TYPE} and
- exit.
- @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 --interactive
- @itemx -i
- Launch the interactive REPL after @var{file} is executed.
- @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
- @node Using Guix Interactively
- @section Using Guix Interactively
- @cindex interactive use
- @cindex REPL, read-eval-print loop
- The @command{guix repl} command gives you access to a warm and friendly
- @dfn{read-eval-print loop} (REPL) (@pxref{Invoking guix repl}). If
- you're getting into Guix programming---defining your own packages,
- writing manifests, defining services for Guix System or Guix Home,
- etc.---you will surely find it convenient to toy with ideas at the REPL.
- If you use Emacs, the most convenient way to do that is with Geiser
- (@pxref{The Perfect Setup}), but you do not have to use Emacs to enjoy
- the REPL@. When using @command{guix repl} or @command{guile} in the
- terminal, we recommend using Readline for completion and Colorized to
- get colorful output. To do that, you can run:
- @example
- guix install guile guile-readline guile-colorized
- @end example
- @noindent
- ... and then create a @file{.guile} file in your home directory containing
- this:
- @lisp
- (use-modules (ice-9 readline) (ice-9 colorized))
- (activate-readline)
- (activate-colorized)
- @end lisp
- The REPL lets you evaluate Scheme code; you type a Scheme expression at
- the prompt, and the REPL prints what it evaluates to:
- @example
- $ guix repl
- scheme@@(guix-user)> (+ 2 3)
- $1 = 5
- scheme@@(guix-user)> (string-append "a" "b")
- $2 = "ab"
- @end example
- It becomes interesting when you start fiddling with Guix at the REPL.
- The first thing you'll want to do is to ``import'' the @code{(guix)}
- module, which gives access to the main part of the programming
- interface, and perhaps a bunch of useful Guix modules. You could type
- @code{(use-modules (guix))}, which is valid Scheme code to import a
- module (@pxref{Using Guile Modules,,, guile, GNU Guile Reference
- Manual}), but the REPL provides the @code{use} @dfn{command} as a
- shorthand notation (@pxref{REPL Commands,,, guile, GNU Guile Reference
- Manual}):
- @example
- scheme@@(guix-user)> ,use (guix)
- scheme@@(guix-user)> ,use (gnu packages base)
- @end example
- Notice that REPL commands are introduced by a leading comma. A REPL
- command like @code{use} is not valid Scheme code; it's interpreted
- specially by the REPL.
- Guix extends the Guile REPL with additional commands for convenience.
- Among those, the @code{build} command comes in handy: it ensures that
- the given file-like object is built, building it if needed, and returns
- its output file name(s). In the example below, we build the
- @code{coreutils} and @code{grep} packages, as well as a ``computed
- file'' (@pxref{G-Expressions, @code{computed-file}}), and we use the
- @code{scandir} procedure to list the files in Grep's @code{/bin}
- directory:
- @example
- scheme@@(guix-user)> ,build coreutils
- $1 = "/gnu/store/@dots{}-coreutils-8.32-debug"
- $2 = "/gnu/store/@dots{}-coreutils-8.32"
- scheme@@(guix-user)> ,build grep
- $3 = "/gnu/store/@dots{}-grep-3.6"
- scheme@@(guix-user)> ,build (computed-file "x" #~(mkdir #$output))
- building /gnu/store/@dots{}-x.drv...
- $4 = "/gnu/store/@dots{}-x"
- scheme@@(guix-user)> ,use(ice-9 ftw)
- scheme@@(guix-user)> (scandir (string-append $3 "/bin"))
- $5 = ("." ".." "egrep" "fgrep" "grep")
- @end example
- At a lower-level, a useful command is @code{lower}: it takes a file-like
- object and ``lowers'' it into a derivation (@pxref{Derivations}) or a
- store file:
- @example
- scheme@@(guix-user)> ,lower grep
- $6 = #<derivation /gnu/store/@dots{}-grep-3.6.drv => /gnu/store/@dots{}-grep-3.6 7f0e639115f0>
- scheme@@(guix-user)> ,lower (plain-file "x" "Hello!")
- $7 = "/gnu/store/@dots{}-x"
- @end example
- The full list of REPL commands can be seen by typing @code{,help guix}
- and is given below for reference.
- @deffn {REPL command} build @var{object}
- Lower @var{object} and build it if it's not already built, returning its
- output file name(s).
- @end deffn
- @deffn {REPL command} lower @var{object}
- Lower @var{object} into a derivation or store file name and return it.
- @end deffn
- @deffn {REPL command} verbosity @var{level}
- Change build verbosity to @var{level}.
- This is similar to the @option{--verbosity} command-line option
- (@pxref{Common Build Options}): level 0 means total silence, level 1
- shows build events only, and higher levels print build logs.
- @end deffn
- @deffn {REPL command} run-in-store @var{exp}
- Run @var{exp}, a monadic expression, through the store monad.
- @xref{The Store Monad}, for more information.
- @end deffn
- @deffn {REPL command} enter-store-monad
- Enter a new REPL to evaluate monadic expressions (@pxref{The Store
- Monad}). You can quit this ``inner'' REPL by typing @code{,q}.
- @end deffn
- @c *********************************************************************
- @node Utilities
- @chapter Utilities
- This section describes Guix command-line utilities. Some of them are
- primarily targeted at developers and users who write new package
- definitions, while others are more generally useful. They complement
- the Scheme programming interface of Guix in a convenient way.
- @menu
- * Invoking guix build:: Building packages from the command line.
- * Invoking guix edit:: Editing package definitions.
- * Invoking guix download:: Downloading a file and printing its hash.
- * Invoking guix hash:: Computing the cryptographic hash of a file.
- * Invoking guix import:: Importing package definitions.
- * Invoking guix refresh:: Updating package definitions.
- * Invoking guix style:: Styling package definitions.
- * Invoking guix lint:: Finding errors in package definitions.
- * Invoking guix size:: Profiling disk usage.
- * Invoking guix graph:: Visualizing the graph of packages.
- * Invoking guix publish:: Sharing substitutes.
- * Invoking guix challenge:: Challenging substitute servers.
- * Invoking guix copy:: Copying to and from a remote store.
- * Invoking guix container:: Process isolation.
- * Invoking guix weather:: Assessing substitute availability.
- * Invoking guix processes:: Listing client processes.
- @end menu
- @node Invoking guix build
- @section Invoking @command{guix build}
- @cindex package building
- @cindex @command{guix build}
- The @command{guix build} command builds packages or derivations and
- their dependencies, and prints the resulting store paths. Note that it
- does not modify the user's profile---this is the job of the
- @command{guix package} command (@pxref{Invoking guix package}). Thus,
- it is mainly useful for distribution developers.
- The general syntax is:
- @example
- guix build @var{options} @var{package-or-derivation}@dots{}
- @end example
- As an example, the following command builds the latest versions of Emacs
- and of Guile, displays their build logs, and finally displays the
- resulting directories:
- @example
- guix build emacs guile
- @end example
- Similarly, the following command builds all the available packages:
- @example
- guix build --quiet --keep-going \
- $(guix package -A | awk '@{ print $1 "@@" $2 @}')
- @end example
- @var{package-or-derivation} may be either the name of a package found in
- the software distribution such as @code{coreutils} or
- @code{coreutils@@8.20}, or a derivation such as
- @file{/gnu/store/@dots{}-coreutils-8.19.drv}. In the former case, a
- package with the corresponding name (and optionally version) is searched
- for among the GNU distribution modules (@pxref{Package Modules}).
- Alternatively, the @option{--expression} option may be used to specify a
- Scheme expression that evaluates to a package; this is useful when
- disambiguating among several same-named packages or package variants is
- needed.
- There may be zero or more @var{options}. The available options are
- described in the subsections below.
- @menu
- * Common Build Options:: Build options for most commands.
- * Package Transformation Options:: Creating variants of packages.
- * Additional Build Options:: Options specific to 'guix build'.
- * Debugging Build Failures:: Real life packaging experience.
- @end menu
- @node Common Build Options
- @subsection Common Build Options
- A number of options that control the build process are common to
- @command{guix build} and other commands that can spawn builds, such as
- @command{guix package} or @command{guix archive}. These are the
- following:
- @table @code
- @item --load-path=@var{directory}
- @itemx -L @var{directory}
- Add @var{directory} to the front of the package module search path
- (@pxref{Package Modules}).
- This allows users to define their own packages and make them visible to
- the command-line tools.
- @item --keep-failed
- @itemx -K
- Keep the build tree of failed builds. Thus, if a build fails, its build
- tree is kept under @file{/tmp}, in a directory whose name is shown at
- the end of the build log. This is useful when debugging build issues.
- @xref{Debugging Build Failures}, for tips and tricks on how to debug
- build issues.
- This option implies @option{--no-offload}, and it has no effect when
- connecting to a remote daemon with a @code{guix://} URI (@pxref{The
- Store, the @env{GUIX_DAEMON_SOCKET} variable}).
- @item --keep-going
- @itemx -k
- Keep going when some of the derivations fail to build; return only once
- all the builds have either completed or failed.
- The default behavior is to stop as soon as one of the specified
- derivations has failed.
- @item --dry-run
- @itemx -n
- Do not build the derivations.
- @anchor{fallback-option}
- @item --fallback
- When substituting a pre-built binary fails, fall back to building
- packages locally (@pxref{Substitution Failure}).
- @item --substitute-urls=@var{urls}
- @anchor{client-substitute-urls}
- Consider @var{urls} the whitespace-separated list of substitute source
- URLs, overriding the default list of URLs of @command{guix-daemon}
- (@pxref{daemon-substitute-urls,, @command{guix-daemon} URLs}).
- This means that substitutes may be downloaded from @var{urls}, provided
- they are signed by a key authorized by the system administrator
- (@pxref{Substitutes}).
- When @var{urls} is the empty string, substitutes are effectively
- disabled.
- @item --no-substitutes
- Do not use substitutes for build products. That is, always build things
- locally instead of allowing downloads of pre-built binaries
- (@pxref{Substitutes}).
- @item --no-grafts
- Do not ``graft'' packages. In practice, this means that package updates
- available as grafts are not applied. @xref{Security Updates}, for more
- information on grafts.
- @item --rounds=@var{n}
- Build each derivation @var{n} times in a row, and raise an error if
- consecutive build results are not bit-for-bit identical.
- This is a useful way to detect non-deterministic builds processes.
- Non-deterministic build processes are a problem because they make it
- practically impossible for users to @emph{verify} whether third-party
- binaries are genuine. @xref{Invoking guix challenge}, for more.
- When used in conjunction with @option{--keep-failed}, the differing
- output is kept in the store, under @file{/gnu/store/@dots{}-check}.
- This makes it easy to look for differences between the two results.
- @item --no-offload
- Do not use offload builds to other machines (@pxref{Daemon Offload
- Setup}). That is, always build things locally instead of offloading
- builds to remote machines.
- @item --max-silent-time=@var{seconds}
- When the build or substitution process remains silent for more than
- @var{seconds}, terminate it and report a build failure.
- By default, the daemon's setting is honored (@pxref{Invoking
- guix-daemon, @option{--max-silent-time}}).
- @item --timeout=@var{seconds}
- Likewise, when the build or substitution process lasts for more than
- @var{seconds}, terminate it and report a build failure.
- By default, the daemon's setting is honored (@pxref{Invoking
- guix-daemon, @option{--timeout}}).
- @c Note: This option is actually not part of %standard-build-options but
- @c most programs honor it.
- @cindex verbosity, of the command-line tools
- @cindex build logs, verbosity
- @item -v @var{level}
- @itemx --verbosity=@var{level}
- Use the given verbosity @var{level}, an integer. Choosing 0 means that
- no output is produced, 1 is for quiet output; 2 is similar to 1 but it
- additionally displays download URLs; 3 shows all the build log output on
- standard error.
- @item --cores=@var{n}
- @itemx -c @var{n}
- Allow the use of up to @var{n} CPU cores for the build. The special
- value @code{0} means to use as many CPU cores as available.
- @item --max-jobs=@var{n}
- @itemx -M @var{n}
- Allow at most @var{n} build jobs in parallel. @xref{Invoking
- guix-daemon, @option{--max-jobs}}, for details about this option and the
- equivalent @command{guix-daemon} option.
- @item --debug=@var{level}
- Produce debugging output coming from the build daemon. @var{level} must be an
- integer between 0 and 5; higher means more verbose output. Setting a level of
- 4 or more may be helpful when debugging setup issues with the build daemon.
- @end table
- Behind the scenes, @command{guix build} is essentially an interface to
- the @code{package-derivation} procedure of the @code{(guix packages)}
- module, and to the @code{build-derivations} procedure of the @code{(guix
- derivations)} module.
- In addition to options explicitly passed on the command line,
- @command{guix build} and other @command{guix} commands that support
- building honor the @env{GUIX_BUILD_OPTIONS} environment variable.
- @defvr {Environment Variable} GUIX_BUILD_OPTIONS
- Users can define this variable to a list of command line options that
- will automatically be used by @command{guix build} and other
- @command{guix} commands that can perform builds, as in the example
- below:
- @example
- $ export GUIX_BUILD_OPTIONS="--no-substitutes -c 2 -L /foo/bar"
- @end example
- These options are parsed independently, and the result is appended to
- the parsed command-line options.
- @end defvr
- @node Package Transformation Options
- @subsection Package Transformation Options
- @cindex package variants
- Another set of command-line options supported by @command{guix build}
- and also @command{guix package} are @dfn{package transformation
- options}. These are options that make it possible to define @dfn{package
- variants}---for instance, packages built from different source code.
- This is a convenient way to create customized packages on the fly
- without having to type in the definitions of package variants
- (@pxref{Defining Packages}).
- Package transformation options are preserved across upgrades:
- @command{guix upgrade} attempts to apply transformation options
- initially used when creating the profile to the upgraded packages.
- The available options are listed below. Most commands support them and
- also support a @option{--help-transform} option that lists all the
- available options and a synopsis (these options are not shown in the
- @option{--help} output for brevity).
- @table @code
- @cindex performance, tuning code
- @cindex optimization, of package code
- @cindex tuning, of package code
- @cindex SIMD support
- @cindex tunable packages
- @cindex package multi-versioning
- @item --tune[=@var{cpu}]
- Use versions of the packages marked as ``tunable'' optimized for
- @var{cpu}. When @var{cpu} is @code{native}, or when it is omitted, tune
- for the CPU on which the @command{guix} command is running.
- Valid @var{cpu} names are those recognized by the underlying compiler,
- by default the GNU Compiler Collection. On x86_64 processors, this
- includes CPU names such as @code{nehalem}, @code{haswell}, and
- @code{skylake} (@pxref{x86 Options, @code{-march},, gcc, Using the GNU
- Compiler Collection (GCC)}).
- As new generations of CPUs come out, they augment the standard
- instruction set architecture (ISA) with additional instructions, in
- particular instructions for single-instruction/multiple-data (SIMD)
- parallel processing. For example, while Core2 and Skylake CPUs both
- implement the x86_64 ISA, only the latter supports AVX2 SIMD
- instructions.
- The primary gain one can expect from @option{--tune} is for programs
- that can make use of those SIMD capabilities @emph{and} that do not
- already have a mechanism to select the right optimized code at run time.
- Packages that have the @code{tunable?} property set are considered
- @dfn{tunable packages} by the @option{--tune} option; a package
- definition with the property set looks like this:
- @lisp
- (package
- (name "hello-simd")
- ;; ...
- ;; This package may benefit from SIMD extensions so
- ;; mark it as "tunable".
- (properties '((tunable? . #t))))
- @end lisp
- Other packages are not considered tunable. This allows Guix to use
- generic binaries in the cases where tuning for a specific CPU is
- unlikely to provide any gain.
- Tuned packages are built with @code{-march=@var{CPU}}; under the hood,
- the @option{-march} option is passed to the actual wrapper by a compiler
- wrapper. Since the build machine may not be able to run code for the
- target CPU micro-architecture, the test suite is not run when building a
- tuned package.
- To reduce rebuilds to the minimum, tuned packages are @emph{grafted}
- onto packages that depend on them (@pxref{Security Updates, grafts}).
- Thus, using @option{--no-grafts} cancels the effect of @option{--tune}.
- We call this technique @dfn{package multi-versioning}: several variants
- of tunable packages may be built, one for each CPU variant. It is the
- coarse-grain counterpart of @dfn{function multi-versioning} as
- implemented by the GNU tool chain (@pxref{Function Multiversioning,,,
- gcc, Using the GNU Compiler Collection (GCC)}).
- @item --with-source=@var{source}
- @itemx --with-source=@var{package}=@var{source}
- @itemx --with-source=@var{package}@@@var{version}=@var{source}
- Use @var{source} as the source of @var{package}, and @var{version} as
- its version number.
- @var{source} must be a file name or a URL, as for @command{guix
- download} (@pxref{Invoking guix download}).
- When @var{package} is omitted,
- it is taken to be the package name specified on the
- command line that matches the base of @var{source}---e.g.,
- if @var{source} is @code{/src/guile-2.0.10.tar.gz}, the corresponding
- package is @code{guile}.
- Likewise, when @var{version} is omitted, the version string is inferred from
- @var{source}; in the previous example, it is @code{2.0.10}.
- This option allows users to try out versions of packages other than the
- one provided by the distribution. The example below downloads
- @file{ed-1.7.tar.gz} from a GNU mirror and uses that as the source for
- the @code{ed} package:
- @example
- guix build ed --with-source=mirror://gnu/ed/ed-1.4.tar.gz
- @end example
- As a developer, @option{--with-source} makes it easy to test release
- candidates, and even to test their impact on packages that depend on
- them:
- @example
- guix build elogind --with-source=@dots{}/shepherd-0.9.0rc1.tar.gz
- @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.2}:
- @example
- guix build --with-input=guile=guile@@2.2 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.2}.
- This is implemented using the @code{package-input-rewriting/spec} Scheme
- procedure (@pxref{Defining Packages, @code{package-input-rewriting/spec}}).
- @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 configure flags, changing them
- @item --with-configure-flag=@var{package}=@var{flag}
- Append @var{flag} to the configure flags of @var{package}, where
- @var{package} is a spec such as @code{guile@@3.0} or @code{glibc}. The
- build system of @var{package} must support the @code{#:configure-flags}
- argument.
- For example, the command below builds GNU@tie{}Hello with the
- configure flag @code{--disable-nls}:
- @example
- guix build hello --with-configure-flag=hello=--disable-nls
- @end example
- The following command passes an extra flag to @command{cmake} as it
- builds @code{lapack}:
- @example
- guix build lapack \
- --with-configure-flag=lapack=-DBUILD_SHARED_LIBS=OFF
- @end example
- @quotation Note
- Under the hood, this option works by passing the
- @samp{#:configure-flags} argument 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.
- @end quotation
- @cindex upstream, latest version
- @item --with-latest=@var{package}
- @itemx --with-version=@var{package}=@var{version}
- So you like living on the bleeding edge? The @option{--with-latest}
- 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
- The @option{--with-version} works similarly except that it lets you
- specify that you want precisely @var{version}, assuming that version
- exists upstream. For example, to spawn a development environment with
- SciPy built against version 1.22.4 of NumPy (skipping its test suite
- because hey, we're not gonna wait this long), you would run:
- @example
- guix shell python python-scipy --with-version=python-numpy=1.22.4
- @end example
- @quotation Warning
- Because they depend on source code published at a given point in time on
- upstream servers, deployments made with @option{--with-latest} and
- @option{--with-version} may be non-reproducible: source might disappear
- or be modified in place on the servers.
- To deploy old software versions without compromising on reproducibility,
- @pxref{Invoking guix time-machine, @command{guix time-machine}}.
- @end quotation
- 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! When those limitations are acceptable, 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 with @option{--with-latest} (@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}).
- @item --list-systems
- List all the supported systems, that can be passed as an argument to
- @option{--system}.
- @item --list-targets
- List all the supported targets, that can be passed as an argument to
- @option{--target}.
- @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
- @code{aarch64}, but you are actually on an @code{x86_64} machine:
- @example
- $ guix build --log-file gdb -s aarch64-linux
- https://@value{SUBSTITUTE-SERVER-1}/log/@dots{}-gdb-7.10
- @end example
- You can freely access a huge library of build logs!
- @end table
- @node Debugging Build Failures
- @subsection Debugging Build Failures
- @cindex build failures, debugging
- When defining a new package (@pxref{Defining Packages}), you will
- probably find yourself spending some time debugging and tweaking the
- build until it succeeds. To do that, you need to operate the build
- commands yourself in an environment as close as possible to the one the
- build daemon uses.
- To that end, the first thing to do is to use the @option{--keep-failed}
- or @option{-K} option of @command{guix build}, which will keep the
- failed build tree in @file{/tmp} or whatever directory you specified as
- @env{TMPDIR} (@pxref{Common Build Options, @option{--keep-failed}}).
- From there on, you can @command{cd} to the failed build tree and source
- the @file{environment-variables} file, which contains all the
- environment variable definitions that were in place when the build
- failed. So let's say you're debugging a build failure in package
- @code{foo}; a typical session would look like this:
- @example
- $ guix build foo -K
- @dots{} @i{build fails}
- $ cd /tmp/guix-build-foo.drv-0
- $ source ./environment-variables
- $ cd foo-1.2
- @end example
- Now, you can invoke commands as if you were the daemon (almost) and
- troubleshoot your build process.
- Sometimes it happens that, for example, a package's tests pass when you
- run them manually but they fail when the daemon runs them. This can
- happen because the daemon runs builds in containers where, unlike in our
- environment above, network access is missing, @file{/bin/sh} does not
- exist, etc. (@pxref{Build Environment Setup}).
- In such cases, you may need to run inspect the build process from within
- a container similar to the one the build daemon creates:
- @example
- $ guix build -K foo
- @dots{}
- $ cd /tmp/guix-build-foo.drv-0
- $ guix shell --no-grafts -C -D foo strace gdb
- [env]# source ./environment-variables
- [env]# cd foo-1.2
- @end example
- Here, @command{guix shell -C} creates a container and spawns a new
- shell in it (@pxref{Invoking guix shell}). The @command{strace gdb}
- part adds the @command{strace} and @command{gdb} commands to
- the container, which you may find handy while debugging. The
- @option{--no-grafts} option makes sure we get the exact same
- environment, with ungrafted packages (@pxref{Security Updates}, for more
- info on grafts).
- To get closer to a container like that used by the build daemon, we can
- remove @file{/bin/sh}:
- @example
- [env]# rm /bin/sh
- @end example
- (Don't worry, this is harmless: this is all happening in the throw-away
- container created by @command{guix shell}.)
- The @command{strace} command is probably not in the search path, but we
- can run:
- @example
- [env]# $GUIX_ENVIRONMENT/bin/strace -f -o log make check
- @end example
- In this way, not only you will have reproduced the environment variables
- the daemon uses, you will also be running the build process in a container
- similar to the one the daemon uses.
- @node Invoking guix edit
- @section Invoking @command{guix edit}
- @cindex @command{guix edit}
- @cindex package definition, editing
- So many packages, so many source files! The @command{guix edit} command
- facilitates the life of users and packagers by pointing their editor at
- the source file containing the definition of the specified packages.
- For instance:
- @example
- guix edit gcc@@4.9 vim
- @end example
- @noindent
- launches the program specified in the @env{VISUAL} or in the
- @env{EDITOR} environment variable to view the recipe of GCC@tie{}4.9.3
- and that of Vim.
- If you are using a Guix Git checkout (@pxref{Building from Git}), or
- have created your own packages on @env{GUIX_PACKAGE_PATH}
- (@pxref{Package Modules}), you will be able to edit the package
- recipes. In other cases, you will be able to examine the read-only recipes
- for packages currently in the store.
- Instead of @env{GUIX_PACKAGE_PATH}, the command-line option
- @option{--load-path=@var{directory}} (or in short @option{-L
- @var{directory}}) allows you to add @var{directory} to the front of the
- package module search path and so make your own packages visible.
- @node Invoking guix download
- @section Invoking @command{guix download}
- @cindex @command{guix download}
- @cindex downloading package sources
- When writing a package definition, developers typically need to download
- a source tarball, compute its SHA256 hash, and write that
- hash in the package definition (@pxref{Defining Packages}). The
- @command{guix download} tool helps with this task: it downloads a file
- from the given URI, adds it to the store, and prints both its file name
- in the store and its SHA256 hash.
- The fact that the downloaded file is added to the store saves bandwidth:
- when the developer eventually tries to build the newly defined package
- with @command{guix build}, the source tarball will not have to be
- downloaded again because it is already in the store. It is also a
- convenient way to temporarily stash files, which may be deleted
- eventually (@pxref{Invoking guix gc}).
- The @command{guix download} command supports the same URIs as used in
- package definitions. In particular, it supports @code{mirror://} URIs.
- @code{https} URIs (HTTP over TLS) are supported @emph{provided} the
- Guile bindings for GnuTLS are available in the user's environment; when
- they are not available, an error is raised. @xref{Guile Preparations,
- how to install the GnuTLS bindings for Guile,, gnutls-guile,
- GnuTLS-Guile}, for more information.
- @command{guix download} verifies HTTPS server certificates by loading
- the certificates of X.509 authorities from the directory pointed to by
- the @env{SSL_CERT_DIR} environment variable (@pxref{X.509
- Certificates}), unless @option{--no-check-certificate} is used.
- The following options are available:
- @table @code
- @item --hash=@var{algorithm}
- @itemx -H @var{algorithm}
- Compute a hash using the specified @var{algorithm}. @xref{Invoking guix
- hash}, for more information.
- @item --format=@var{fmt}
- @itemx -f @var{fmt}
- Write the hash in the format specified by @var{fmt}. For more
- information on the valid values for @var{fmt}, @pxref{Invoking guix hash}.
- @item --no-check-certificate
- Do not validate the X.509 certificates of HTTPS servers.
- When using this option, you have @emph{absolutely no guarantee} that you
- are communicating with the authentic server responsible for the given
- URL, which makes you vulnerable to ``man-in-the-middle'' attacks.
- @item --output=@var{file}
- @itemx -o @var{file}
- Save the downloaded file to @var{file} instead of adding it to the
- store.
- @end table
- @node Invoking guix hash
- @section Invoking @command{guix hash}
- @cindex @command{guix hash}
- The @command{guix hash} command computes the hash of a file.
- It is primarily a convenience tool for anyone contributing to the
- distribution: it computes the cryptographic hash of one or more files, which can be
- used in the definition of a package (@pxref{Defining Packages}).
- The general syntax is:
- @example
- guix hash @var{option} @var{file} ...
- @end example
- When @var{file} is @code{-} (a hyphen), @command{guix hash} computes the
- hash of data read from standard input. @command{guix hash} has the
- following options:
- @table @code
- @item --hash=@var{algorithm}
- @itemx -H @var{algorithm}
- Compute a hash using the specified @var{algorithm}, @code{sha256} by
- default.
- @var{algorithm} must be the name of a cryptographic hash algorithm
- supported by Libgcrypt @i{via} Guile-Gcrypt---e.g., @code{sha512} or
- @code{sha3-256} (@pxref{Hash Functions,,, guile-gcrypt, Guile-Gcrypt
- Reference Manual}).
- @item --format=@var{fmt}
- @itemx -f @var{fmt}
- Write the hash in the format specified by @var{fmt}.
- Supported formats: @code{base64}, @code{nix-base32}, @code{base32}, @code{base16}
- (@code{hex} and @code{hexadecimal} can be used as well).
- If the @option{--format} option is not specified, @command{guix hash}
- will output the hash in @code{nix-base32}. This representation is used
- in the definitions of packages.
- @item --recursive
- @itemx -r
- The @option{--recursive} option is deprecated in favor of
- @option{--serializer=nar} (see below); @option{-r} remains accepted as a
- convenient shorthand.
- @item --serializer=@var{type}
- @itemx -S @var{type}
- Compute the hash on @var{file} using @var{type} serialization.
- @var{type} may be one of the following:
- @table @code
- @item none
- This is the default: it computes the hash of a file's contents.
- @item nar
- Compute the hash of a ``normalized archive'' (or ``nar'') containing
- @var{file}, including its children if it is a directory. Some of the
- metadata of @var{file} is part of the archive; for instance, when
- @var{file} is a regular file, the hash is different depending on whether
- @var{file} is executable or not. Metadata such as time stamps have no
- impact on the hash (@pxref{Invoking guix archive}, for more info on the
- nar format).
- @c FIXME: Replace xref above with xref to an ``Archive'' section when
- @c it exists.
- @item git
- Compute the hash of the file or directory as a Git ``tree'', following
- the same method as the Git version control system.
- @end table
- @item --exclude-vcs
- @itemx -x
- When combined with @option{--recursive}, exclude version control system
- directories (@file{.bzr}, @file{.git}, @file{.hg}, etc.).
- @vindex git-fetch
- As an example, here is how you would compute the hash of a Git checkout,
- which is useful when using the @code{git-fetch} method (@pxref{origin
- Reference}):
- @example
- $ git clone http://example.org/foo.git
- $ cd foo
- $ guix hash -x --serializer=nar .
- @end example
- @end table
- @node Invoking guix import
- @section Invoking @command{guix import}
- @cindex importing packages
- @cindex package import
- @cindex package conversion
- @cindex Invoking @command{guix import}
- The @command{guix import} command is useful for people who would like to
- add a package to the distribution with as little work as
- possible---a legitimate demand. The command knows of a few
- repositories from which it can ``import'' package metadata. The result
- is a package definition, or a template thereof, in the format we know
- (@pxref{Defining Packages}).
- The general syntax is:
- @example
- guix import @var{importer} @var{options}@dots{}
- @end example
- @var{importer} specifies the source from which to import package
- metadata, and @var{options} specifies a package identifier and other
- options specific to @var{importer}.
- Some of the importers rely on the ability to run the @command{gpgv} command.
- For these, GnuPG must be installed and in @code{$PATH}; run @code{guix install
- gnupg} if needed.
- Currently, the available ``importers'' are:
- @table @code
- @item gnu
- Import metadata for the given GNU package. This provides a template
- for the latest version of that GNU package, including the hash of its
- source tarball, and its canonical synopsis and description.
- Additional information such as the package dependencies and its
- license needs to be figured out manually.
- For example, the following command returns a package definition for
- GNU@tie{}Hello:
- @example
- guix import gnu hello
- @end example
- Specific command-line options are:
- @table @code
- @item --key-download=@var{policy}
- As for @command{guix refresh}, specify the policy to handle missing
- OpenPGP keys when verifying the package signature. @xref{Invoking guix
- refresh, @option{--key-download}}.
- @end table
- @item pypi
- @cindex pypi
- Import metadata from the @uref{https://pypi.python.org/, Python Package
- Index}. Information is taken from the JSON-formatted description
- available at @code{pypi.python.org} and usually includes all the relevant
- information, including package dependencies. For maximum efficiency, it
- is recommended to install the @command{unzip} utility, so that the
- importer can unzip Python wheels and gather data from them.
- The command below imports metadata for the latest version of the
- @code{itsdangerous} Python package:
- @example
- guix import pypi itsdangerous
- @end example
- You can also ask for a specific version:
- @example
- guix import pypi itsdangerous@@1.1.0
- @end example
- @table @code
- @item --recursive
- @itemx -r
- Traverse the dependency graph of the given upstream package recursively
- and generate package expressions for all those packages that are not yet
- in Guix.
- @end table
- @item gem
- @cindex gem
- Import metadata from @uref{https://rubygems.org/, RubyGems}. Information
- is taken from the JSON-formatted description available at
- @code{rubygems.org} and includes most relevant information, including
- runtime dependencies. There are some caveats, however. The metadata
- doesn't distinguish between synopses and descriptions, so the same string
- is used for both fields. Additionally, the details of non-Ruby
- dependencies required to build native extensions is unavailable and left
- as an exercise to the packager.
- The command below imports metadata for the @code{rails} Ruby package:
- @example
- guix import gem rails
- @end example
- You can also ask for a specific version:
- @example
- guix import gem rails@@7.0.4
- @end example
- @table @code
- @item --recursive
- @itemx -r
- Traverse the dependency graph of the given upstream package recursively
- and generate package expressions for all those packages that are not yet
- in Guix.
- @end table
- @item minetest
- @cindex minetest
- @cindex ContentDB
- Import metadata from @uref{https://content.minetest.net, ContentDB}.
- Information is taken from the JSON-formatted metadata provided through
- @uref{https://content.minetest.net/help/api/, ContentDB's API} and
- includes most relevant information, including dependencies. There are
- some caveats, however. The license information is often incomplete.
- The commit hash is sometimes missing. The descriptions are in the
- Markdown format, but Guix uses Texinfo instead. Texture packs and
- subgames are unsupported.
- The command below imports metadata for the Mesecons mod by Jeija:
- @example
- guix import minetest Jeija/mesecons
- @end example
- The author name can also be left out:
- @example
- guix import minetest mesecons
- @end example
- @table @code
- @item --recursive
- @itemx -r
- Traverse the dependency graph of the given upstream package recursively
- and generate package expressions for all those packages that are not yet
- in Guix.
- @end table
- @item cpan
- @cindex CPAN
- Import metadata from @uref{https://www.metacpan.org/, MetaCPAN}.
- Information is taken from the JSON-formatted metadata provided through
- @uref{https://fastapi.metacpan.org/, MetaCPAN's API} and includes most
- relevant information, such as module dependencies. License information
- should be checked closely. If Perl is available in the store, then the
- @code{corelist} utility will be used to filter core modules out of the
- list of dependencies.
- The command command below imports metadata for the Acme::Boolean Perl
- module:
- @example
- guix import cpan Acme::Boolean
- @end example
- @item cran
- @cindex CRAN
- @cindex Bioconductor
- Import metadata from @uref{https://cran.r-project.org/, CRAN}, the
- central repository for the @uref{https://r-project.org, GNU@tie{}R
- statistical and graphical environment}.
- Information is extracted from the @file{DESCRIPTION} file of the package.
- The command command below imports metadata for the Cairo R package:
- @example
- guix import cran Cairo
- @end example
- You can also ask for a specific version:
- @example
- guix import cran rasterVis@@0.50.3
- @end example
- When @option{--recursive} is added, the importer will traverse the
- dependency graph of the given upstream package recursively and generate
- package expressions for all those packages that are not yet in Guix.
- When @option{--style=specification} is added, the importer will generate
- package definitions whose inputs are package specifications instead of
- references to package variables. This is useful when generated package
- definitions are to be appended to existing user modules, as the list of
- used package modules need not be changed. The default is
- @option{--style=variable}.
- When @option{--prefix=license:} is added, the importer will prefix
- license atoms with @code{license:}, allowing a prefixed import of
- @code{(guix licenses)}.
- When @option{--archive=bioconductor} is added, metadata is imported from
- @uref{https://www.bioconductor.org/, Bioconductor}, a repository of R
- packages for the analysis and comprehension of high-throughput
- genomic data in bioinformatics.
- Information is extracted from the @file{DESCRIPTION} file contained in the
- package archive.
- The command below imports metadata for the GenomicRanges R package:
- @example
- guix import cran --archive=bioconductor GenomicRanges
- @end example
- Finally, you can also import R packages that have not yet been published on
- CRAN or Bioconductor as long as they are in a git repository. Use
- @option{--archive=git} followed by the URL of the git repository:
- @example
- guix import cran --archive=git https://github.com/immunogenomics/harmony
- @end example
- @item texlive
- @cindex TeX Live
- @cindex CTAN
- Import TeX package information from the TeX Live package database for
- TeX packages that are part of the @uref{https://www.tug.org/texlive/,
- TeX Live distribution}.
- Information about the package is obtained from the TeX Live package
- database, a plain text file that is included in the
- @code{texlive-scripts} package. The source code is downloaded from
- possibly multiple locations in the SVN repository of the Tex Live
- project.
- The command command below imports metadata for the @code{fontspec}
- TeX package:
- @example
- guix import texlive fontspec
- @end example
- 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 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 elm
- @cindex elm
- Import metadata from the Elm package repository
- @uref{https://package.elm-lang.org, package.elm-lang.org}, as in this example:
- @example
- guix import elm elm-explorations/webgl
- @end example
- The Elm importer also allows you to specify a version string:
- @example
- guix import elm elm-explorations/webgl@@1.1.3
- @end example
- Additional options include:
- @table @code
- @item --recursive
- @itemx -r
- Traverse the dependency graph of the given upstream package recursively
- and generate package expressions for all those packages that are not yet
- in Guix.
- @end table
- @item opam
- @cindex OPAM
- @cindex OCaml
- Import metadata from the @uref{https://opam.ocaml.org/, OPAM} package
- repository used by the OCaml community.
- Additional options include:
- @table @code
- @item --recursive
- @itemx -r
- Traverse the dependency graph of the given upstream package recursively
- and generate package expressions for all those packages that are not yet
- in Guix.
- @item --repo
- By default, packages are searched in the official OPAM repository. This
- option, which can be used more than once, lets you add other repositories
- which will be searched for packages. It accepts as valid arguments:
- @itemize
- @item the name of a known repository - can be one of @code{opam},
- @code{coq} (equivalent to @code{coq-released}),
- @code{coq-core-dev}, @code{coq-extra-dev} or @code{grew}.
- @item the URL of a repository as expected by the
- @code{opam repository add} command (for instance, the URL equivalent
- of the above @code{opam} name would be
- @uref{https://opam.ocaml.org}).
- @item the path to a local copy of a repository (a directory containing a
- @file{packages/} sub-directory).
- @end itemize
- Repositories are assumed to be passed to this option by order of
- preference. The additional repositories will not replace the default
- @code{opam} repository, which is always kept as a fallback.
- Also, please note that versions are not compared across repositories.
- The first repository (from left to right) that has at least one version
- of a given package will prevail over any others, and the version
- imported will be the latest one found @emph{in this repository only}.
- @end table
- @item go
- @cindex go
- Import metadata for a Go module using
- @uref{https://proxy.golang.org, proxy.golang.org}.
- @example
- guix import go gopkg.in/yaml.v2
- @end example
- It is possible to use a package specification with a @code{@@VERSION}
- suffix to import a specific version.
- Additional options include:
- @table @code
- @item --recursive
- @itemx -r
- Traverse the dependency graph of the given upstream package recursively
- and generate package expressions for all those packages that are not yet
- in Guix.
- @item --pin-versions
- When using this option, the importer preserves the exact versions of the
- Go modules dependencies instead of using their latest available
- versions. This can be useful when attempting to import packages that
- recursively depend on former versions of themselves to build. When
- using this mode, the symbol of the package is made by appending the
- version to its name, so that multiple versions of the same package can
- coexist.
- @end table
- @item egg
- @cindex egg
- Import metadata for @uref{https://wiki.call-cc.org/eggs, CHICKEN eggs}.
- The information is taken from @file{PACKAGE.egg} files found in the
- @uref{git://code.call-cc.org/eggs-5-all, eggs-5-all} Git
- repository. However, it does not provide all the information that we
- need, there is no ``description'' field, and the licenses used are not
- always precise (BSD is often used instead of BSD-N).
- @example
- guix import egg sourcehut
- @end example
- You can also ask for a specific version:
- @example
- guix import egg arrays@@1.0
- @end example
- Additional options include:
- @table @code
- @item --recursive
- @itemx -r
- Traverse the dependency graph of the given upstream package recursively
- and generate package expressions for all those packages that are not yet
- in Guix.
- @end table
- @item hexpm
- @cindex hexpm
- Import metadata from the hex.pm Erlang and Elixir package repository
- @uref{https://hex.pm, hex.pm}, as in this example:
- @example
- guix import hexpm stun
- @end example
- The importer tries to determine the build system used by the package.
- The hexpm importer also allows you to specify a version string:
- @example
- guix import hexpm cf@@0.3.0
- @end example
- Additional options include:
- @table @code
- @item --recursive
- @itemx -r
- Traverse the dependency graph of the given upstream package recursively
- and generate package expressions for all those packages that are not yet
- in Guix.
- @end table
- @end table
- The structure of the @command{guix import} code is modular. It would be
- useful to have more importers for other package formats, and your help
- is welcome here (@pxref{Contributing}).
- @node Invoking guix refresh
- @section Invoking @command{guix refresh}
- @cindex @command {guix refresh}
- The primary audience of the @command{guix refresh} command is packagers.
- As a user, you may be interested in the @option{--with-latest} option,
- which can bring you package update superpowers built upon @command{guix
- refresh} (@pxref{Package Transformation Options,
- @option{--with-latest}}). By default, @command{guix refresh} reports
- any packages provided by the distribution that are outdated compared to
- the latest upstream version, like this:
- @example
- $ guix refresh
- gnu/packages/gettext.scm:29:13: gettext would be upgraded from 0.18.1.1 to 0.18.2.1
- gnu/packages/glib.scm:77:12: glib would be upgraded from 2.34.3 to 2.37.0
- @end example
- Alternatively, one can specify packages to consider, in which case a
- warning is emitted for packages that lack an updater:
- @example
- $ guix refresh coreutils guile guile-ssh
- gnu/packages/ssh.scm:205:2: warning: no updater for guile-ssh
- gnu/packages/guile.scm:136:12: guile would be upgraded from 2.0.12 to 2.0.13
- @end example
- @command{guix refresh} browses the upstream repository of each package and determines
- the highest version number of the releases therein. The command
- knows how to update specific types of packages: GNU packages, ELPA
- packages, etc.---see the documentation for @option{--type} below. There
- are many packages, though, for which it lacks a method to determine
- whether a new upstream release is available. However, the mechanism is
- extensible, so feel free to get in touch with us to add a new method!
- @table @code
- @item --recursive
- Consider the packages specified, and all the packages upon which they depend.
- @example
- $ guix refresh --recursive coreutils
- gnu/packages/acl.scm:40:13: acl would be upgraded from 2.2.53 to 2.3.1
- gnu/packages/m4.scm:30:12: 1.4.18 is already the latest version of m4
- gnu/packages/xml.scm:68:2: warning: no updater for expat
- gnu/packages/multiprecision.scm:40:12: 6.1.2 is already the latest version of gmp
- @dots{}
- @end example
- @end table
- If for some reason you don't want to update to the latest version, you
- can update to a specific version by appending an equal sign and the
- desired version number to the package specification. Note that not all
- updaters support this; an error is reported when an updater cannot
- refresh to the specified version.
- @example
- $ guix refresh trytond-party
- gnu/packages/guile.scm:392:2: guile would be upgraded from 3.0.3 to 3.0.5
- $ guix refresh -u guile=3.0.4
- @dots{}
- gnu/packages/guile.scm:392:2: guile: updating from version 3.0.3 to version 3.0.4...
- @dots{}
- $ guix refresh -u guile@@2.0=2.0.12
- @dots{}
- gnu/packages/guile.scm:147:2: guile: updating from version 2.0.10 to version 2.0.12...
- @dots{}
- @end example
- In some specific cases, you may have many packages specified via a
- manifest or a module selection which should all be updated together; for
- these cases, the @option{--target-version} option can be provided to have
- them all refreshed to the same version, as shown in the examples below:
- @example
- $ guix refresh qtbase qtdeclarative --target-version=6.5.2
- gnu/packages/qt.scm:1248:13: qtdeclarative would be upgraded from 6.3.2 to 6.5.2
- gnu/packages/qt.scm:584:2: qtbase would be upgraded from 6.3.2 to 6.5.2
- @end example
- @example
- $ guix refresh --manifest=qt5-manifest.scm --target-version=5.15.10
- gnu/packages/qt.scm:1173:13: qtxmlpatterns would be upgraded from 5.15.8 to 5.15.10
- gnu/packages/qt.scm:1202:13: qtdeclarative would be upgraded from 5.15.8 to 5.15.10
- gnu/packages/qt.scm:1762:13: qtserialbus would be upgraded from 5.15.8 to 5.15.10
- gnu/packages/qt.scm:2070:13: qtquickcontrols2 would be upgraded from 5.15.8 to 5.15.10
- @dots{}
- @end example
- 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 code hashes of those package
- definitions, as well as possibly their inputs (@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 definitions) 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.
- You can also run it on packages from a third-party channel:
- @example
- guix refresh -L /path/to/channel -u @var{package}
- @end example
- @xref{Creating a Channel}, on how to create a channel.
- This command updates the version and source code hash of the package.
- Depending on the updater being used, it can also update the various
- @samp{inputs} fields of the package. In some cases, the updater might
- get inputs wrong---it might not know about an extra input that's
- necessary, or it might add an input that should be avoided.
- @cindex @code{updater-extra-inputs}, package property
- @cindex @code{updater-ignored-inputs}, package property
- To address that, packagers can add properties stating inputs that should
- be added to those found by the updater or inputs that should be ignored:
- the @code{updater-extra-inputs} and @code{updater-ignored-inputs}
- properties pertain to ``regular'' inputs, and there are equivalent
- properties for @samp{native} and @samp{propagated} inputs. In the
- example below, we tell the updater that we need @samp{openmpi} as an
- additional input:
- @lisp
- (define-public python-mpi4py
- (package
- (name "python-mpi4py")
- ;; @dots{}
- (inputs (list openmpi))
- (properties
- '((updater-extra-inputs . ("openmpi"))))))
- @end lisp
- That way, @command{guix refresh -u python-mpi4py} will leave the
- @samp{openmpi} input, even if it is not among the inputs it would
- normally add.
- @item --select=[@var{subset}]
- @itemx -s @var{subset}
- Select all the packages in @var{subset}, one of @code{core}, @code{non-core}
- or @code{module:@var{name}}.
- 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.
- The @code{module:@var{name}} subset refers to all the packages in a
- specified guile module. The module can be specified as
- @code{module:guile} or @code{module:(gnu packages guile)}, the former is
- a shorthand for the later.
- @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, or the HTML page specified by
- the @code{release-monitoring-url} property of the package.
- @item generic-git
- a generic updater for packages hosted on Git repositories. It tries to
- be smart about parsing Git tag names, but if it is not able to parse the
- tag name and compare tags correctly, users can define the following
- properties for a package.
- @itemize
- @item @code{release-tag-prefix}: a regular expression for matching a prefix of
- the tag name.
- @item @code{release-tag-suffix}: a regular expression for matching a suffix of
- the tag name.
- @item @code{release-tag-version-delimiter}: a string used as the delimiter in
- the tag name for separating the numbers of the version.
- @item @code{accept-pre-releases}: by default, the updater will ignore
- pre-releases; to make it also look for pre-releases, set the this
- property to @code{#t}.
- @end itemize
- @lisp
- (package
- (name "foo")
- ;; ...
- (properties
- '((release-tag-prefix . "^release0-")
- (release-tag-suffix . "[a-z]?$")
- (release-tag-version-delimiter . ":"))))
- @end lisp
- @end table
- For instance, the following command only checks for updates of Emacs
- packages hosted at @code{elpa.gnu.org} and for updates of CRAN packages:
- @example
- $ guix refresh --type=elpa,cran
- gnu/packages/statistics.scm:819:13: r-testthat would be upgraded from 0.10.0 to 0.11.0
- gnu/packages/emacs.scm:856:13: emacs-auctex would be upgraded from 11.88.6 to 11.88.9
- @end example
- @item --list-updaters
- 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
- @itemx -T
- 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}
- @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
- 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}
- @cindex @command{guix style}
- @cindex styling rules
- @cindex lint, code style
- @cindex format, code style
- @cindex format conventions
- The @command{guix style} command helps users and packagers alike style
- their package definitions and configuration files according to the
- latest fashionable trends. It can either reformat whole files, with the
- @option{--whole-file} option, or apply specific @dfn{styling rules} to
- individual package definitions. The command currently provides the
- following styling rules:
- @itemize
- @item
- formatting package definitions according to the project's conventions
- (@pxref{Formatting Code});
- @item
- rewriting package inputs to the ``new style'', as explained below.
- @end itemize
- The way package inputs are written is going through a transition
- (@pxref{package Reference}, for more on package inputs). Until version
- 1.3.0, package inputs were written using the ``old style'', where each
- input was given an explicit label, most of the time the package name:
- @lisp
- (package
- ;; @dots{}
- ;; The "old style" (deprecated).
- (inputs `(("libunistring" ,libunistring)
- ("libffi" ,libffi))))
- @end lisp
- Today, the old style is deprecated and the preferred style looks like
- this:
- @lisp
- (package
- ;; @dots{}
- ;; The "new style".
- (inputs (list libunistring libffi)))
- @end lisp
- Likewise, uses of @code{alist-delete} and friends to manipulate inputs
- is now deprecated in favor of @code{modify-inputs} (@pxref{Defining
- Package Variants}, for more info on @code{modify-inputs}).
- In the vast majority of cases, this is a purely mechanical change on the
- surface syntax that does not even incur a package rebuild. Running
- @command{guix style -S inputs} can do that for you, whether you're working on
- packages in Guix proper or in an external channel.
- The general syntax is:
- @example
- guix style [@var{options}] @var{package}@dots{}
- @end example
- This causes @command{guix style} to analyze and rewrite the definition
- of @var{package}@dots{} or, when @var{package} is omitted, of @emph{all}
- the packages. The @option{--styling} or @option{-S} option allows you
- to select the style rule, the default rule being @code{format}---see
- below.
- To reformat entire source files, the syntax is:
- @example
- guix style --whole-file @var{file}@dots{}
- @end example
- The available options are listed below.
- @table @code
- @item --dry-run
- @itemx -n
- Show source file locations that would be edited but do not modify them.
- @item --whole-file
- @itemx -f
- Reformat the given files in their entirety. In that case, subsequent
- arguments are interpreted as file names (rather than package names), and
- the @option{--styling} option has no effect.
- As an example, here is how you might reformat your operating system
- configuration (you need write permissions for the file):
- @example
- guix style -f /etc/config.scm
- @end example
- @item --styling=@var{rule}
- @itemx -S @var{rule}
- Apply @var{rule}, one of the following styling rules:
- @table @code
- @item format
- Format the given package definition(s)---this is the default styling
- rule. For example, a packager running Guix on a checkout
- (@pxref{Running Guix Before It Is Installed}) might want to reformat the
- definition of the Coreutils package like so:
- @example
- ./pre-inst-env guix style coreutils
- @end example
- @item inputs
- Rewrite package inputs to the ``new style'', as described above. This
- is how you would rewrite inputs of package @code{whatnot} in your own
- channel:
- @example
- guix style -L ~/my/channel -S inputs whatnot
- @end example
- Rewriting is done in a conservative way: preserving comments and bailing
- out if it cannot make sense of the code that appears in an inputs field.
- The @option{--input-simplification} option described below provides
- fine-grain control over when inputs should be simplified.
- @item arguments
- Rewrite package arguments to use G-expressions (@pxref{G-Expressions}).
- For example, consider this package definition:
- @lisp
- (define-public my-package
- (package
- ;; @dots{}
- (arguments ;old-style quoted arguments
- '(#:make-flags '("V=1")
- #:phases (modify-phases %standard-phases
- (delete 'build))))))
- @end lisp
- @noindent
- Running @command{guix style -S arguments} on this package would rewrite
- its @code{arguments} field like to:
- @lisp
- (define-public my-package
- (package
- ;; @dots{}
- (arguments
- (list #:make-flags #~'("V=1")
- #:phases #~(modify-phases %standard-phases
- (delete 'build))))))
- @end lisp
- Note that changes made by the @code{arguments} rule do not entail a
- rebuild of the affected packages. Furthermore, if a package definition
- happens to be using G-expressions already, @command{guix style} leaves
- it unchanged.
- @end table
- @item --list-stylings
- @itemx -l
- List and describe the available styling rules and exit.
- @item --load-path=@var{directory}
- @itemx -L @var{directory}
- Add @var{directory} to the front of the package module search path
- (@pxref{Package Modules}).
- @item --expression=@var{expr}
- @itemx -e @var{expr}
- Style the package @var{expr} evaluates to.
- For example, running:
- @example
- guix style -e '(@@ (gnu packages gcc) gcc-5)'
- @end example
- styles the @code{gcc-5} package definition.
- @item --input-simplification=@var{policy}
- When using the @code{inputs} styling rule, with @samp{-S inputs}, this
- option specifies the package input simplification policy for cases where
- an input label does not match the corresponding package name.
- @var{policy} may be one of the following:
- @table @code
- @item silent
- Simplify inputs only when the change is ``silent'', meaning that the
- package does not need to be rebuilt (its derivation is unchanged).
- @item safe
- Simplify inputs only when that is ``safe'' to do: the package might need
- to be rebuilt, but the change is known to have no observable effect.
- @item always
- Simplify inputs even when input labels do not match package names, and
- even if that might have an observable effect.
- @end table
- The default is @code{silent}, meaning that input simplifications do not
- trigger any package rebuild.
- @end table
- @node Invoking guix lint
- @section Invoking @command{guix lint}
- @cindex @command{guix lint}
- @cindex package, checking for errors
- The @command{guix lint} command is meant to help package developers avoid
- common errors and use a consistent style. It runs a number of checks on
- a given set of packages in order to find common mistakes in their
- definitions. Available @dfn{checkers} include (see
- @option{--list-checkers} for a complete list):
- @table @code
- @item synopsis
- @itemx description
- Validate certain typographical and stylistic rules about package
- descriptions and synopses.
- @item inputs-should-be-native
- Identify inputs that should most likely be native inputs.
- @item source
- @itemx home-page
- @itemx mirror-url
- @itemx github-url
- @itemx source-file-name
- Probe @code{home-page} and @code{source} URLs and report those that are
- invalid. Suggest a @code{mirror://} URL when applicable. If the
- @code{source} URL redirects to a GitHub URL, recommend usage of the GitHub
- URL@. Check that the source file name is meaningful, e.g.@: is not just a
- version number or ``git-checkout'', without a declared @code{file-name}
- (@pxref{origin Reference}).
- @item source-unstable-tarball
- Parse the @code{source} URL to determine if a tarball from GitHub is
- autogenerated or if it is a release tarball. Unfortunately GitHub's
- autogenerated tarballs are sometimes regenerated.
- @item derivation
- Check that the derivation of the given packages can be successfully
- computed for all the supported systems (@pxref{Derivations}).
- @item profile-collisions
- Check whether installing the given packages in a profile would lead to
- collisions. Collisions occur when several packages with the same name
- but a different version or a different store file name are propagated.
- @xref{package Reference, @code{propagated-inputs}}, for more information
- on propagated inputs.
- @item archival
- @cindex Software Heritage, source code archive
- @cindex archival of source code, Software Heritage
- Checks whether the package's source code is archived at
- @uref{https://www.softwareheritage.org, Software Heritage}.
- When the source code that is not archived comes from a version-control system
- (VCS)---e.g., it's obtained with @code{git-fetch}, send Software Heritage a
- ``save'' request so that it eventually archives it. This ensures that the
- source will remain available in the long term, and that Guix can fall back to
- Software Heritage should the source code disappear from its original host.
- The status of recent ``save'' requests can be
- @uref{https://archive.softwareheritage.org/save/#requests, viewed on-line}.
- When source code is a tarball obtained with @code{url-fetch}, simply print a
- message when it is not archived. As of this writing, Software Heritage does
- not allow requests to save arbitrary tarballs; we are working on ways to
- ensure that non-VCS source code is also archived.
- Software Heritage
- @uref{https://archive.softwareheritage.org/api/#rate-limiting, limits the
- request rate per IP address}. When the limit is reached, @command{guix lint}
- prints a message and the @code{archival} checker stops doing anything until
- that limit has been reset.
- @item cve
- @cindex security vulnerabilities
- @cindex CVE, Common Vulnerabilities and Exposures
- Report known vulnerabilities found in the Common Vulnerabilities and
- Exposures (CVE) databases of the current and past year
- @uref{https://nvd.nist.gov/vuln/data-feeds, published by the US
- NIST}.
- To view information about a particular vulnerability, visit pages such as:
- @itemize
- @item
- @indicateurl{https://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-YYYY-ABCD}
- @item
- @indicateurl{https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-YYYY-ABCD}
- @end itemize
- @noindent
- where @code{CVE-YYYY-ABCD} is the CVE identifier---e.g.,
- @code{CVE-2015-7554}.
- Package developers can specify in package recipes the
- @uref{https://nvd.nist.gov/products/cpe,Common Platform Enumeration (CPE)}
- name and version of the package when they differ from the name or version
- that Guix uses, as in this example:
- @lisp
- (package
- (name "grub")
- ;; @dots{}
- ;; CPE calls this package "grub2".
- (properties '((cpe-name . "grub2")
- (cpe-version . "2.3"))))
- @end lisp
- @c See <https://www.openwall.com/lists/oss-security/2017/03/15/3>.
- Some entries in the CVE database do not specify which version of a
- package they apply to, and would thus ``stick around'' forever. Package
- developers who found CVE alerts and verified they can be ignored can
- declare them as in this example:
- @lisp
- (package
- (name "t1lib")
- ;; @dots{}
- ;; These CVEs no longer apply and can be safely ignored.
- (properties `((lint-hidden-cve . ("CVE-2011-0433"
- "CVE-2011-1553"
- "CVE-2011-1554"
- "CVE-2011-5244")))))
- @end lisp
- @item formatting
- Warn about obvious source code formatting issues: trailing white space,
- use of tabulations, etc.
- @item input-labels
- Report old-style input labels that do not match the name of the
- corresponding package. This aims to help migrate from the ``old input
- style''. @xref{package Reference}, for more information on package
- inputs and input styles. @xref{Invoking guix style}, on how to migrate
- to the new style.
- @end table
- The general syntax is:
- @example
- guix lint @var{options} @var{package}@dots{}
- @end example
- If no package is given on the command line, then all packages are checked.
- The @var{options} may be zero or more of the following:
- @table @code
- @item --list-checkers
- @itemx -l
- List and describe all the available checkers that will be run on packages
- and exit.
- @item --checkers
- @itemx -c
- Only enable the checkers specified in a comma-separated list using the
- names returned by @option{--list-checkers}.
- @item --exclude
- @itemx -x
- Only disable the checkers specified in a comma-separated list using the
- names returned by @option{--list-checkers}.
- @item --expression=@var{expr}
- @itemx -e @var{expr}
- Consider the package @var{expr} evaluates to.
- This is useful to unambiguously designate packages, as in this example:
- @example
- guix lint -c archival -e '(@@ (gnu packages guile) guile-3.0)'
- @end example
- @item --no-network
- @itemx -n
- Only enable the checkers that do not depend on Internet access.
- @item --load-path=@var{directory}
- @itemx -L @var{directory}
- Add @var{directory} to the front of the package module search path
- (@pxref{Package Modules}).
- This allows users to define their own packages and make them visible to
- the command-line tools.
- @end table
- @node Invoking guix size
- @section Invoking @command{guix size}
- @cindex size
- @cindex package size
- @cindex closure
- @cindex @command{guix size}
- The @command{guix size} command helps package developers profile the
- disk usage of packages. It is easy to overlook the impact of an
- additional dependency added to a package, or the impact of using a
- single output for a package that could easily be split (@pxref{Packages
- with Multiple Outputs}). Such are the typical issues that
- @command{guix size} can highlight.
- The command can be passed one or more package specifications
- such as @code{gcc@@4.8}
- or @code{guile:debug}, or a file name in the store. Consider this
- example:
- @example
- $ guix size coreutils
- store item total self
- /gnu/store/@dots{}-gcc-5.5.0-lib 60.4 30.1 38.1%
- /gnu/store/@dots{}-glibc-2.27 30.3 28.8 36.6%
- /gnu/store/@dots{}-coreutils-8.28 78.9 15.0 19.0%
- /gnu/store/@dots{}-gmp-6.1.2 63.1 2.7 3.4%
- /gnu/store/@dots{}-bash-static-4.4.12 1.5 1.5 1.9%
- /gnu/store/@dots{}-acl-2.2.52 61.1 0.4 0.5%
- /gnu/store/@dots{}-attr-2.4.47 60.6 0.2 0.3%
- /gnu/store/@dots{}-libcap-2.25 60.5 0.2 0.2%
- total: 78.9 MiB
- @end example
- @cindex closure
- The store items listed here constitute the @dfn{transitive closure} of
- Coreutils---i.e., Coreutils and all its dependencies, recursively---as
- would be returned by:
- @example
- $ guix gc -R /gnu/store/@dots{}-coreutils-8.23
- @end example
- Here the output shows three columns next to store items. The first column,
- labeled ``total'', shows the size in mebibytes (MiB) of the closure of
- the store item---that is, its own size plus the size of all its
- dependencies. The next column, labeled ``self'', shows the size of the
- item itself. The last column shows the ratio of the size of the item
- itself to the space occupied by all the items listed here.
- In this example, we see that the closure of Coreutils weighs in at
- 79@tie{}MiB, most of which is taken by libc and GCC's run-time support
- libraries. (That libc and GCC's libraries represent a large fraction of
- the closure is not a problem @i{per se} because they are always available
- on the system anyway.)
- Since the command also accepts store file names, assessing the size of
- a build result is straightforward:
- @example
- guix size $(guix system build config.scm)
- @end example
- When the package(s) passed to @command{guix size} are available in the
- store@footnote{More precisely, @command{guix size} looks for the
- @emph{ungrafted} variant of the given package(s), as returned by
- @code{guix build @var{package} --no-grafts}. @xref{Security Updates},
- for information on grafts.}, @command{guix size} queries the daemon to determine its
- dependencies, and measures its size in the store, similar to @command{du
- -ms --apparent-size} (@pxref{du invocation,,, coreutils, GNU
- Coreutils}).
- When the given packages are @emph{not} in the store, @command{guix size}
- reports information based on the available substitutes
- (@pxref{Substitutes}). This makes it possible it to profile disk usage of
- store items that are not even on disk, only available remotely.
- You can also specify several package names:
- @example
- $ guix size coreutils grep sed bash
- store item total self
- /gnu/store/@dots{}-coreutils-8.24 77.8 13.8 13.4%
- /gnu/store/@dots{}-grep-2.22 73.1 0.8 0.8%
- /gnu/store/@dots{}-bash-4.3.42 72.3 4.7 4.6%
- /gnu/store/@dots{}-readline-6.3 67.6 1.2 1.2%
- @dots{}
- total: 102.3 MiB
- @end example
- @noindent
- In this example we see that the combination of the four packages takes
- 102.3@tie{}MiB in total, which is much less than the sum of each closure
- since they have a lot of dependencies in common.
- When looking at the profile returned by @command{guix size}, you may
- find yourself wondering why a given package shows up in the profile at
- all. To understand it, you can use @command{guix graph --path -t
- references} to display the shortest path between the two packages
- (@pxref{Invoking guix graph}).
- The available options are:
- @table @option
- @item --substitute-urls=@var{urls}
- Use substitute information from @var{urls}.
- @xref{client-substitute-urls, the same option for @code{guix build}}.
- @item --sort=@var{key}
- Sort lines according to @var{key}, one of the following options:
- @table @code
- @item self
- the size of each item (the default);
- @item closure
- the total size of the item's closure.
- @end table
- @item --map-file=@var{file}
- Write a graphical map of disk usage in PNG format to @var{file}.
- For the example above, the map looks like this:
- @image{images/coreutils-size-map,5in,, map of Coreutils disk usage
- produced by @command{guix size}}
- This option requires that
- @uref{https://wingolog.org/software/guile-charting/, Guile-Charting} be
- installed and visible in Guile's module search path. When that is not
- the case, @command{guix size} fails as it tries to load it.
- @item --system=@var{system}
- @itemx -s @var{system}
- Consider packages for @var{system}---e.g., @code{x86_64-linux}.
- @item --load-path=@var{directory}
- @itemx -L @var{directory}
- Add @var{directory} to the front of the package module search path
- (@pxref{Package Modules}).
- This allows users to define their own packages and make them visible to
- the command-line tools.
- @end table
- @node Invoking guix graph
- @section Invoking @command{guix graph}
- @cindex DAG
- @cindex @command{guix graph}
- @cindex package dependencies
- Packages and their dependencies form a @dfn{graph}, specifically a
- directed acyclic graph (DAG). It can quickly become difficult to have a
- mental model of the package DAG, so the @command{guix graph} command
- provides a visual representation of the DAG@. By default,
- @command{guix graph} emits a DAG representation in the input format of
- @uref{https://www.graphviz.org/, Graphviz}, so its output can be passed
- directly to the @command{dot} command of Graphviz. It can also emit an
- HTML page with embedded JavaScript code to display a ``chord diagram''
- in a Web browser, using the @uref{https://d3js.org/, d3.js} library, or
- emit Cypher queries to construct a graph in a graph database supporting
- the @uref{https://www.opencypher.org/, openCypher} query language. With
- @option{--path}, it simply displays the shortest path between two
- packages. The general syntax is:
- @example
- guix graph @var{options} @var{package}@dots{}
- @end example
- For example, the following command generates a PDF file representing the
- package DAG for the GNU@tie{}Core Utilities, showing its build-time
- dependencies:
- @example
- guix graph coreutils | dot -Tpdf > dag.pdf
- @end example
- The output looks like this:
- @image{images/coreutils-graph,2in,,Dependency graph of the GNU Coreutils}
- Nice little graph, no?
- You may find it more pleasant to navigate the graph interactively with
- @command{xdot} (from the @code{xdot} package):
- @example
- guix graph coreutils | xdot -
- @end example
- But there is more than one graph! The one above is concise: it is the
- graph of package objects, omitting implicit inputs such as GCC, libc,
- grep, etc. It is often useful to have such a concise graph, but
- sometimes one may want to see more details. @command{guix graph} supports
- several types of graphs, allowing you to choose the level of detail:
- @table @code
- @item package
- This is the default type used in the example above. It shows the DAG of
- package objects, excluding implicit dependencies. It is concise, but
- filters out many details.
- @item reverse-package
- This shows the @emph{reverse} DAG of packages. For example:
- @example
- guix graph --type=reverse-package ocaml
- @end example
- ...@: yields the graph of packages that @emph{explicitly} depend on OCaml (if
- you are also interested in cases where OCaml is an implicit dependency, see
- @code{reverse-bag} below).
- Note that for core packages this can yield huge graphs. If all you want
- is to know the number of packages that depend on a given package, use
- @command{guix refresh --list-dependent} (@pxref{Invoking guix refresh,
- @option{--list-dependent}}).
- @item bag-emerged
- This is the package DAG, @emph{including} implicit inputs.
- For instance, the following command:
- @example
- guix graph --type=bag-emerged coreutils
- @end example
- ...@: yields this bigger graph:
- @image{images/coreutils-bag-graph,,5in,Detailed dependency graph of the GNU Coreutils}
- At the bottom of the graph, we see all the implicit inputs of
- @var{gnu-build-system} (@pxref{Build Systems, @code{gnu-build-system}}).
- Now, note that the dependencies of these implicit inputs---that is, the
- @dfn{bootstrap dependencies} (@pxref{Bootstrapping})---are not shown
- here, for conciseness.
- @item bag
- Similar to @code{bag-emerged}, but this time including all the bootstrap
- dependencies.
- @item bag-with-origins
- Similar to @code{bag}, but also showing origins and their dependencies.
- @item reverse-bag
- This shows the @emph{reverse} DAG of packages. Unlike @code{reverse-package},
- it also takes implicit dependencies into account. For example:
- @example
- guix graph -t reverse-bag dune
- @end example
- @noindent
- ...@: yields the graph of all packages that depend on Dune, directly or
- indirectly. Since Dune is an @emph{implicit} dependency of many packages
- @i{via} @code{dune-build-system}, this shows a large number of packages,
- whereas @code{reverse-package} would show very few if any.
- @item derivation
- This is the most detailed representation: It shows the DAG of
- derivations (@pxref{Derivations}) and plain store items. Compared to
- the above representation, many additional nodes are visible, including
- build scripts, patches, Guile modules, etc.
- For this type of graph, it is also possible to pass a @file{.drv} file
- name instead of a package name, as in:
- @example
- guix graph -t derivation $(guix system build -d my-config.scm)
- @end example
- @item module
- This is the graph of @dfn{package modules} (@pxref{Package Modules}).
- For example, the following command shows the graph for the package
- module that defines the @code{guile} package:
- @example
- guix graph -t module guile | xdot -
- @end example
- @end table
- All the types above correspond to @emph{build-time dependencies}. The
- following graph type represents the @emph{run-time dependencies}:
- @table @code
- @item references
- This is the graph of @dfn{references} of a package output, as returned
- by @command{guix gc --references} (@pxref{Invoking guix gc}).
- If the given package output is not available in the store, @command{guix
- graph} attempts to obtain dependency information from substitutes.
- Here you can also pass a store file name instead of a package name. For
- example, the command below produces the reference graph of your profile
- (which can be big!):
- @example
- guix graph -t references $(readlink -f ~/.guix-profile)
- @end example
- @item referrers
- This is the graph of the @dfn{referrers} of a store item, as returned by
- @command{guix gc --referrers} (@pxref{Invoking guix gc}).
- This relies exclusively on local information from your store. For
- instance, let us suppose that the current Inkscape is available in 10
- profiles on your machine; @command{guix graph -t referrers inkscape}
- will show a graph rooted at Inkscape and with those 10 profiles linked
- to it.
- It can help determine what is preventing a store item from being garbage
- collected.
- @end table
- @cindex shortest path, between packages
- Often, the graph of the package you are interested in does not fit on
- your screen, and anyway all you want to know is @emph{why} that package
- actually depends on some seemingly unrelated package. The
- @option{--path} option instructs @command{guix graph} to display the
- shortest path between two packages (or derivations, or store items,
- etc.):
- @example
- $ guix graph --path emacs libunistring
- emacs@@26.3
- mailutils@@3.9
- libunistring@@0.9.10
- $ guix graph --path -t derivation emacs libunistring
- /gnu/store/@dots{}-emacs-26.3.drv
- /gnu/store/@dots{}-mailutils-3.9.drv
- /gnu/store/@dots{}-libunistring-0.9.10.drv
- $ guix graph --path -t references emacs libunistring
- /gnu/store/@dots{}-emacs-26.3
- /gnu/store/@dots{}-libidn2-2.2.0
- /gnu/store/@dots{}-libunistring-0.9.10
- @end example
- Sometimes you still want to visualize the graph but would like to trim
- it so it can actually be displayed. One way to do it is via the
- @option{--max-depth} (or @option{-M}) option, which lets you specify the
- maximum depth of the graph. In the example below, we visualize only
- @code{libreoffice} and the nodes whose distance to @code{libreoffice} is
- at most 2:
- @example
- guix graph -M 2 libreoffice | xdot -f fdp -
- @end example
- Mind you, that's still a big ball of spaghetti, but at least
- @command{dot} can render it quickly and it can be browsed somewhat.
- The available options are the following:
- @table @option
- @item --type=@var{type}
- @itemx -t @var{type}
- Produce a graph output of @var{type}, where @var{type} must be one of
- the values listed above.
- @item --list-types
- List the supported graph types.
- @item --backend=@var{backend}
- @itemx -b @var{backend}
- Produce a graph using the selected @var{backend}.
- @item --list-backends
- List the supported graph backends.
- Currently, the available backends are Graphviz and d3.js.
- @item --path
- Display the shortest path between two nodes of the type specified by
- @option{--type}. The example below shows the shortest path between
- @code{libreoffice} and @code{llvm} according to the references of
- @code{libreoffice}:
- @example
- $ guix graph --path -t references libreoffice llvm
- /gnu/store/@dots{}-libreoffice-6.4.2.2
- /gnu/store/@dots{}-libepoxy-1.5.4
- /gnu/store/@dots{}-mesa-19.3.4
- /gnu/store/@dots{}-llvm-9.0.1
- @end example
- @item --expression=@var{expr}
- @itemx -e @var{expr}
- Consider the package @var{expr} evaluates to.
- This is useful to precisely refer to a package, as in this example:
- @example
- guix graph -e '(@@@@ (gnu packages commencement) gnu-make-final)'
- @end example
- @item --system=@var{system}
- @itemx -s @var{system}
- Display the graph for @var{system}---e.g., @code{i686-linux}.
- The package dependency graph is largely architecture-independent, but there
- are some architecture-dependent bits that this option allows you to visualize.
- @item --load-path=@var{directory}
- @itemx -L @var{directory}
- Add @var{directory} to the front of the package module search path
- (@pxref{Package Modules}).
- This allows users to define their own packages and make them visible to
- the command-line tools.
- @end table
- On top of that, @command{guix graph} supports all the usual package
- transformation options (@pxref{Package Transformation Options}). This
- makes it easy to view the effect of a graph-rewriting transformation
- such as @option{--with-input}. For example, the command below outputs
- the graph of @code{git} once @code{openssl} has been replaced by
- @code{libressl} everywhere in the graph:
- @example
- guix graph git --with-input=openssl=libressl
- @end example
- So many possibilities, so much fun!
- @node Invoking guix publish
- @section Invoking @command{guix publish}
- @cindex @command{guix publish}
- The purpose of @command{guix publish} is to enable users to easily share
- their store with others, who can then use it as a substitute server
- (@pxref{Substitutes}).
- When @command{guix publish} runs, it spawns an HTTP server which allows
- anyone with network access to obtain substitutes from it. This means
- that any machine running Guix can also act as if it were a build farm,
- since the HTTP interface is compatible with Cuirass, the software behind
- the @code{@value{SUBSTITUTE-SERVER-1}} build farm.
- For security, each substitute is signed, allowing recipients to check
- their authenticity and integrity (@pxref{Substitutes}). Because
- @command{guix publish} uses the signing key of the system, which is only
- readable by the system administrator, it must be started as root; the
- @option{--user} option makes it drop root privileges early on.
- The signing key pair must be generated before @command{guix publish} is
- launched, using @command{guix archive --generate-key} (@pxref{Invoking
- guix archive}).
- When the @option{--advertise} option is passed, the server advertises
- its availability on the local network using multicast DNS (mDNS) and DNS
- service discovery (DNS-SD), currently @i{via} Guile-Avahi (@pxref{Top,,,
- guile-avahi, Using Avahi in Guile Scheme Programs}).
- The general syntax is:
- @example
- guix publish @var{options}@dots{}
- @end example
- Running @command{guix publish} without any additional arguments will
- spawn an HTTP server on port 8080:
- @example
- guix publish
- @end example
- @cindex socket activation, for @command{guix publish}
- @command{guix publish} can also be started following the systemd
- ``socket activation'' protocol (@pxref{Service De- and Constructors,
- @code{make-systemd-constructor},, shepherd, The GNU Shepherd Manual}).
- 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" \
- openssl git pius coreutils grep
- updating substitutes from 'https://@value{SUBSTITUTE-SERVER-1}'... 100.0%
- updating 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{}
- 5 store items were analyzed:
- - 2 (40.0%) were identical
- - 3 (60.0%) differed
- - 0 (0.0%) were inconclusive
- @end smallexample
- @noindent
- In this example, @command{guix challenge} queries all the substitute
- servers for each of the fives packages specified on the command line.
- It then reports those store items for which the servers obtained a
- result different from the local build (if it exists) and/or different
- from one another; here, the @samp{local hash} lines indicate that a
- local build result was available for each of these packages and shows
- its hash.
- @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
- The general syntax is:
- @example
- guix challenge @var{options} @var{argument}@dots{}
- @end example
- @noindent
- where @var{argument} is a package specification such as
- @code{guile@@2.0} or @code{glibc:debug} or, alternatively, a store file
- name as returned, for example, by @command{guix build} or @command{guix
- gc --list-live}.
- 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 @command{guix copy}
- @cindex copy, of store items, over SSH
- @cindex SSH, copy of store items
- @cindex sharing store items across machines
- @cindex transferring store items across machines
- The @command{guix copy} command copies items from the store of one
- machine to that of another machine over a secure shell (SSH)
- connection@footnote{This command is available only when Guile-SSH was
- found. @xref{Requirements}, for details.}. For example, the following
- command copies the @code{coreutils} package, the user's profile, and all
- their dependencies over to @var{host}, logged in as @var{user}:
- @example
- guix copy --to=@var{user}@@@var{host} \
- coreutils $(readlink -f ~/.guix-profile)
- @end example
- If some of the items to be copied are already present on @var{host},
- they are not actually sent.
- The command below retrieves @code{libreoffice} and @code{gimp} from
- @var{host}, assuming they are available there:
- @example
- guix copy --from=@var{host} libreoffice gimp
- @end example
- The SSH connection is established using the Guile-SSH client, which is
- compatible with OpenSSH: it honors @file{~/.ssh/known_hosts} and
- @file{~/.ssh/config}, and uses the SSH agent for authentication.
- The key used to sign items that are sent must be accepted by the remote
- machine. Likewise, the key used by the remote machine to sign items you
- are retrieving must be in @file{/etc/guix/acl} so it is accepted by your
- own daemon. @xref{Invoking guix archive}, for more information about
- store item authentication.
- The general syntax is:
- @example
- guix copy [--to=@var{spec}|--from=@var{spec}] @var{items}@dots{}
- @end example
- You must always specify one of the following options:
- @table @code
- @item --to=@var{spec}
- @itemx --from=@var{spec}
- Specify the host to send to or receive from. @var{spec} must be an SSH
- spec such as @code{example.org}, @code{charlie@@example.org}, or
- @code{charlie@@example.org:2222}.
- @end table
- The @var{items} can be either package names, such as @code{gimp}, or
- store items, such as @file{/gnu/store/@dots{}-idutils-4.6}.
- When specifying the name of a package to send, it is first built if
- needed, unless @option{--dry-run} was specified. Common build options
- are supported (@pxref{Common Build Options}).
- @node Invoking guix container
- @section Invoking @command{guix container}
- @cindex container
- @cindex @command{guix container}
- @quotation Note
- As of version @value{VERSION}, this tool is experimental. The interface
- is subject to radical change in the future.
- @end quotation
- The purpose of @command{guix container} is to manipulate processes
- running within an isolated environment, commonly known as a
- ``container'', typically created by the @command{guix shell}
- (@pxref{Invoking guix shell}) and @command{guix system container}
- (@pxref{Invoking guix system}) commands.
- The general syntax is:
- @example
- guix container @var{action} @var{options}@dots{}
- @end example
- @var{action} specifies the operation to perform with a container, and
- @var{options} specifies the context-specific arguments for the action.
- The following actions are available:
- @table @code
- @item exec
- Execute a command within the context of a running container.
- The syntax is:
- @example
- guix container exec @var{pid} @var{program} @var{arguments}@dots{}
- @end example
- @var{pid} specifies the process ID of the running container.
- @var{program} specifies an executable file name within the root file
- system of the container. @var{arguments} are the additional options that
- will be passed to @var{program}.
- The following command launches an interactive login shell inside a
- Guix system container, started by @command{guix system container}, and whose
- process ID is 9001:
- @example
- guix container exec 9001 /run/current-system/profile/bin/bash --login
- @end example
- Note that the @var{pid} cannot be the parent process of a container. It
- must be PID 1 of the container or one of its child processes.
- @end table
- @node Invoking guix weather
- @section Invoking @command{guix weather}
- @cindex @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 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}
- @cindex @command{guix processes}
- The @command{guix processes} command can be useful to developers and system
- administrators, especially on multi-user machines and on build farms: it lists
- the current sessions (connections to the daemon), as well as information about
- the processes involved@footnote{Remote sessions, when @command{guix-daemon} is
- started with @option{--listen} specifying a TCP endpoint, are @emph{not}
- listed.}. Here's an example of the information it returns:
- @example
- $ sudo guix processes
- SessionPID: 19002
- ClientPID: 19090
- ClientCommand: guix shell python
- SessionPID: 19402
- ClientPID: 19367
- ClientCommand: guix publish -u guix-publish -p 3000 -C 9 @dots{}
- SessionPID: 19444
- ClientPID: 19419
- ClientCommand: cuirass --cache-directory /var/cache/cuirass @dots{}
- LockHeld: /gnu/store/@dots{}-perl-ipc-cmd-0.96.lock
- LockHeld: /gnu/store/@dots{}-python-six-bootstrap-1.11.0.lock
- LockHeld: /gnu/store/@dots{}-libjpeg-turbo-2.0.0.lock
- ChildPID: 20495
- ChildCommand: guix offload x86_64-linux 7200 1 28800
- ChildPID: 27733
- ChildCommand: guix offload x86_64-linux 7200 1 28800
- ChildPID: 27793
- ChildCommand: guix offload x86_64-linux 7200 1 28800
- @end example
- In this example we see that @command{guix-daemon} has three clients:
- @command{guix environment}, @command{guix publish}, and the Cuirass continuous
- integration tool; their process identifier (PID) is given by the
- @code{ClientPID} field. The @code{SessionPID} field gives the PID of the
- @command{guix-daemon} sub-process of this particular session.
- The @code{LockHeld} fields show which store items are currently locked
- by this session, which corresponds to store items being built or
- substituted (the @code{LockHeld} field is not displayed when
- @command{guix processes} is not running as root). Last, by looking at
- the @code{ChildPID} and @code{ChildCommand} fields, we understand that
- these three builds are being offloaded (@pxref{Daemon Offload Setup}).
- The output is in Recutils format so we can use the handy @command{recsel}
- command to select sessions of interest (@pxref{Selection Expressions,,,
- recutils, GNU recutils manual}). As an example, the command shows the command
- line and PID of the client that triggered the build of a Perl package:
- @example
- $ sudo guix processes | \
- recsel -p ClientPID,ClientCommand -e 'LockHeld ~ "perl"'
- ClientPID: 19419
- ClientCommand: cuirass --cache-directory /var/cache/cuirass @dots{}
- @end example
- Additional options are listed below.
- @table @code
- @item --format=@var{format}
- @itemx -f @var{format}
- Produce output in the specified @var{format}, one of:
- @table @code
- @item recutils
- The default option. It outputs a set of Session recutils records
- that include each @code{ChildProcess} as a field.
- @item normalized
- Normalize the output records into record sets (@pxref{Record Sets,,,
- recutils, GNU recutils manual}). Normalizing into record sets allows
- joins across record types. The example below lists the PID of each
- @code{ChildProcess} and the associated PID for @code{Session} that
- spawned the @code{ChildProcess} where the @code{Session} was started
- using @command{guix build}.
- @example
- $ guix processes --format=normalized | \
- recsel \
- -j Session \
- -t ChildProcess \
- -p Session.PID,PID \
- -e 'Session.ClientCommand ~ "guix build"'
- PID: 4435
- Session_PID: 4278
- PID: 4554
- Session_PID: 4278
- PID: 4646
- Session_PID: 4278
- @end example
- @end table
- @end table
- @node Foreign Architectures
- @chapter Foreign Architectures
- You can target computers of different CPU architectures when producing
- packages (@pxref{Invoking guix package}), packs (@pxref{Invoking guix
- pack}) or full systems (@pxref{Invoking guix system}).
- GNU Guix supports two distinct mechanisms to target foreign
- architectures:
- @enumerate
- @item
- The traditional
- @uref{https://en.wikipedia.org/wiki/Cross_compiler,cross-compilation}
- mechanism.
- @item
- The native building mechanism which consists in building using the CPU
- instruction set of the foreign system you are targeting. It often
- requires emulation, using the QEMU program for instance.
- @end enumerate
- @menu
- * Cross-Compilation:: Cross-compiling for another architecture.
- * Native Builds:: Targeting another architecture through native builds.
- @end menu
- @node Cross-Compilation
- @section Cross-Compilation
- @cindex foreign architectures
- The commands supporting cross-compilation are proposing the
- @option{--list-targets} and @option{--target} options.
- The @option{--list-targets} option lists all the supported targets that
- can be passed as an argument to @option{--target}.
- @example
- $ guix build --list-targets
- The available targets are:
- - aarch64-linux-gnu
- - arm-linux-gnueabihf
- - i586-pc-gnu
- - i686-linux-gnu
- - i686-w64-mingw32
- - mips64el-linux-gnu
- - powerpc-linux-gnu
- - powerpc64le-linux-gnu
- - riscv64-linux-gnu
- - x86_64-linux-gnu
- - x86_64-w64-mingw32
- @end example
- Targets are specified as GNU triplets (@pxref{Specifying Target
- Triplets, GNU configuration triplets,, autoconf, Autoconf}).
- Those triplets are passed to GCC and the other underlying compilers
- possibly involved when building a package, a system image or any other
- GNU Guix output.
- @example
- $ guix build --target=aarch64-linux-gnu hello
- /gnu/store/9926by9qrxa91ijkhw9ndgwp4bn24g9h-hello-2.12
- $ file /gnu/store/9926by9qrxa91ijkhw9ndgwp4bn24g9h-hello-2.12/bin/hello
- /gnu/store/9926by9qrxa91ijkhw9ndgwp4bn24g9h-hello-2.12/bin/hello: ELF
- 64-bit LSB executable, ARM aarch64 @dots{}
- @end example
- The major benefit of cross-compilation is that there are no performance
- penalty compared to emulation using QEMU. There are however higher
- risks that some packages fail to cross-compile because fewer users are
- using this mechanism extensively.
- @node Native Builds
- @section Native Builds
- The commands that support impersonating a specific system have the
- @option{--list-systems} and @option{--system} options.
- The @option{--list-systems} option lists all the supported systems that
- can be passed as an argument to @option{--system}.
- @example
- $ guix build --list-systems
- The available systems are:
- - x86_64-linux [current]
- - aarch64-linux
- - armhf-linux
- - i586-gnu
- - i686-linux
- - mips64el-linux
- - powerpc-linux
- - powerpc64le-linux
- - riscv64-linux
- $ guix build --system=i686-linux hello
- /gnu/store/cc0km35s8x2z4pmwkrqqjx46i8b1i3gm-hello-2.12
- $ file /gnu/store/cc0km35s8x2z4pmwkrqqjx46i8b1i3gm-hello-2.12/bin/hello
- /gnu/store/cc0km35s8x2z4pmwkrqqjx46i8b1i3gm-hello-2.12/bin/hello: ELF
- 32-bit LSB executable, Intel 80386 @dots{}
- @end example
- In the above example, the current system is @var{x86_64-linux}. The
- @var{hello} package is however built for the @var{i686-linux} system.
- This is possible because the @var{i686} CPU instruction set is a subset
- of the @var{x86_64}, hence @var{i686} targeting binaries can be run on
- @var{x86_64}.
- Still in the context of the previous example, if picking the
- @var{aarch64-linux} system and the @command{guix build
- --system=aarch64-linux hello} has to build some derivations, an extra
- step might be needed.
- The @var{aarch64-linux} targeting binaries cannot directly be run on a
- @var{x86_64-linux} system. An emulation layer is requested. The GNU
- Guix daemon can take advantage of the Linux kernel
- @uref{https://en.wikipedia.org/wiki/Binfmt_misc,binfmt_misc} mechanism
- for that. In short, the Linux kernel can defer the execution of a
- binary targeting a foreign platform, here @var{aarch64-linux}, to a
- userspace program, usually an emulator.
- There is a service that registers QEMU as a backend for the
- @code{binfmt_misc} mechanism (@pxref{Virtualization Services,
- @code{qemu-binfmt-service-type}}). On Debian based foreign
- distributions, the alternative would be the @code{qemu-user-static}
- package.
- If the @code{binfmt_misc} mechanism is not setup correctly, the building
- will fail this way:
- @example
- $ guix build --system=armhf-linux hello --check
- @dots{}
- @ unsupported-platform /gnu/store/jjn969pijv7hff62025yxpfmc8zy0aq0-hello-2.12.drv aarch64-linux
- while setting up the build environment: a `aarch64-linux' is required to
- build `/gnu/store/jjn969pijv7hff62025yxpfmc8zy0aq0-hello-2.12.drv', but
- I am a `x86_64-linux'@dots{}
- @end example
- whereas, with the @code{binfmt_misc} mechanism correctly linked with
- QEMU, one can expect to see:
- @example
- $ guix build --system=armhf-linux hello --check
- /gnu/store/13xz4nghg39wpymivlwghy08yzj97hlj-hello-2.12
- @end example
- The main advantage of native building compared to cross-compiling, is
- that more packages are likely to build correctly. However it comes at a
- price: compilation backed by QEMU is @emph{way slower} than
- cross-compilation, because every instruction needs to be emulated.
- The availability of substitutes for the architecture targeted by the
- @code{--system} option can mitigate this problem. An other way to work
- around it is to install GNU Guix on a machine whose CPU supports
- the targeted instruction set, and set it up as an offload machine
- (@pxref{Daemon Offload Setup}).
- @node System Configuration
- @chapter System Configuration
- @cindex system configuration
- Guix System supports a consistent whole-system configuration
- mechanism. By that we mean that all aspects of the global system
- configuration---such as the available system services, timezone and
- locale settings, user accounts---are declared in a single place. Such
- a @dfn{system configuration} can be @dfn{instantiated}---i.e., effected.
- One of the advantages of putting all the system configuration under the
- control of Guix is that it supports transactional system upgrades, and
- makes it possible to roll back to a previous system instantiation,
- should something go wrong with the new one (@pxref{Features}). Another
- advantage is that it makes it easy to replicate the exact same configuration
- across different machines, or at different points in time, without
- having to resort to additional administration tools layered on top of
- the own tools of the system.
- @c Yes, we're talking of Puppet, Chef, & co. here. ↑
- This section describes this mechanism. First we focus on the system
- administrator's viewpoint---explaining how the system is configured and
- instantiated. Then we show how this mechanism can be extended, for
- instance to support new system services.
- @menu
- * Using the Configuration System:: Customizing your GNU system.
- * operating-system Reference:: Detail of operating-system declarations.
- * File Systems:: Configuring file system mounts.
- * Mapped Devices:: Block device extra processing.
- * Swap Space:: Backing RAM with disk space.
- * User Accounts:: Specifying user accounts.
- * Keyboard Layout:: How the system interprets key strokes.
- * Locales:: Language and cultural convention settings.
- * Services:: Specifying system services.
- * Setuid Programs:: Programs running with elevated 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 Linux-Libre
- kernel, initial RAM disk, and a couple of system services added to those
- provided by default looks like this:
- @findex operating-system
- @lisp
- @include os-config-bare-bones.texi
- @end lisp
- The configuration is declarative and hopefully mostly self-describing.
- It is actually code in the Scheme programming language; the whole
- @code{(operating-system @dots{})} expression produces a @dfn{record}
- with a number of @dfn{fields}.
- 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. @xref{operating-system Reference},
- for details about all the available fields.
- Below we discuss the effect of some of the most important fields,
- and how to @dfn{instantiate} the operating system using
- @command{guix system}.
- @quotation Do not panic
- @cindex Scheme programming language, getting started
- Intimidated by the Scheme language or curious about it? The Cookbook
- has a short section to get started that explains the fundamentals, which
- you will find helpful when hacking your configuration. @xref{A Scheme
- Crash Course,,, guix-cookbook, GNU Guix Cookbook}.
- @end quotation
- @unnumberedsubsec Bootloader
- @cindex legacy boot, on Intel machines
- @cindex BIOS boot, on Intel machines
- @cindex UEFI boot
- @cindex EFI boot
- The @code{bootloader} field describes the method that will be used to boot
- your system. Machines based on Intel processors can boot in ``legacy'' BIOS
- mode, as in the example above. However, more recent machines rely instead on
- the @dfn{Unified Extensible Firmware Interface} (UEFI) to boot. In that case,
- the @code{bootloader} field should contain something along these lines:
- @lisp
- (bootloader-configuration
- (bootloader grub-efi-bootloader)
- (targets '("/boot/efi")))
- @end lisp
- @xref{Bootloader Configuration}, for more information on the available
- configuration options.
- @unnumberedsubsec Globally-Visible Packages
- @vindex %base-packages
- The @code{packages} field lists packages that will be globally visible
- on the system, for all user accounts---i.e., in every user's @env{PATH}
- environment variable---in addition to the per-user profiles
- (@pxref{Invoking guix package}). The @code{%base-packages} variable
- provides all the tools one would expect for basic user and administrator
- tasks---including the GNU Core Utilities, the GNU Networking Utilities,
- the @command{mg} lightweight text editor, @command{find}, @command{grep},
- etc. The example above adds GNU@tie{}Screen to those,
- taken from the @code{(gnu packages screen)}
- module (@pxref{Package Modules}). The
- @code{(list package output)} syntax can be used to add a specific output
- of a package:
- @lisp
- (use-modules (gnu packages))
- (use-modules (gnu packages dns))
- (operating-system
- ;; ...
- (packages (cons (list isc-bind "utils")
- %base-packages)))
- @end lisp
- @findex specification->package
- Referring to packages by variable name, like @code{isc-bind} above, has
- the advantage of being unambiguous; it also allows typos and such to be
- diagnosed right away as ``unbound variables''. The downside is that one
- needs to know which module defines which package, and to augment the
- @code{use-package-modules} line accordingly. To avoid that, one can use
- the @code{specification->package} procedure of the @code{(gnu packages)}
- module, which returns the best package for a given name or name and
- version:
- @lisp
- (use-modules (gnu packages))
- (operating-system
- ;; ...
- (packages (append (map specification->package
- '("tcpdump" "htop" "gnupg@@2.0"))
- %base-packages)))
- @end lisp
- @unnumberedsubsec System Services
- @cindex services
- @vindex %base-services
- The @code{services} field lists @dfn{system services} to be made
- available when the system starts (@pxref{Services}).
- The @code{operating-system} declaration above specifies that, in
- addition to the basic services, we want the OpenSSH secure shell
- daemon listening on port 2222 (@pxref{Networking Services,
- @code{openssh-service-type}}). Under the hood,
- @code{openssh-service-type} arranges so that @command{sshd} is started with the
- right command-line options, possibly with supporting configuration files
- generated as needed (@pxref{Defining Services}).
- @cindex customization, of services
- @findex modify-services
- Occasionally, instead of using the base services as is, you will want to
- customize them. To do this, use @code{modify-services} (@pxref{Service
- Reference, @code{modify-services}}) to modify the list.
- @anchor{auto-login to TTY} For example, suppose you want to modify
- @code{guix-daemon} and Mingetty (the console log-in) in the
- @code{%base-services} list (@pxref{Base Services,
- @code{%base-services}}). To do that, you can write the following in
- your operating system declaration:
- @lisp
- (define %my-services
- ;; My very own list of services.
- (modify-services %base-services
- (guix-service-type config =>
- (guix-configuration
- (inherit config)
- ;; Fetch substitutes from example.org.
- (substitute-urls
- (list "https://example.org/guix"
- "https://ci.guix.gnu.org"))))
- (mingetty-service-type config =>
- (mingetty-configuration
- (inherit config)
- ;; Automatically log in as "guest".
- (auto-login "guest")))))
- (operating-system
- ;; @dots{}
- (services %my-services))
- @end lisp
- This changes the configuration---i.e., the service parameters---of the
- @code{guix-service-type} instance, and that of all the
- @code{mingetty-service-type} instances in the @code{%base-services} list
- (@pxref{Auto-Login to a Specific TTY, see the cookbook for how to
- auto-login one user to a specific TTY,, guix-cookbook, GNU Guix Cookbook})).
- Observe how this is accomplished: first, we arrange for the original
- configuration to be bound to the identifier @code{config} in the
- @var{body}, and then we write the @var{body} so that it evaluates to the
- desired configuration. In particular, notice how we use @code{inherit}
- to create a new configuration which has the same values as the old
- configuration, but with a few modifications.
- @cindex encrypted disk
- The configuration for a typical ``desktop'' usage, with an encrypted
- root partition, a swap file on the root partition, the X11 display
- server, GNOME and Xfce (users can choose which of these desktop
- environments to use at the log-in screen by pressing @kbd{F1}), network
- management, power management, and more, would look like this:
- @lisp
- @include os-config-desktop.texi
- @end lisp
- A graphical system with a choice of lightweight window managers
- instead of full-blown desktop environments would look like this:
- @lisp
- @include os-config-lightweight-desktop.texi
- @end lisp
- This example refers to the @file{/boot/efi} file system by its UUID,
- @code{1234-ABCD}. Replace this UUID with the right UUID on your system,
- as returned by the @command{blkid} command.
- @xref{Desktop Services}, for the exact list of services provided by
- @code{%desktop-services}. @xref{X.509 Certificates}, for background
- information about the @code{nss-certs} package that is used here.
- Again, @code{%desktop-services} is just a list of service objects. If
- you want to remove services from there, you can do so using the
- procedures for list filtering (@pxref{SRFI-1 Filtering and
- Partitioning,,, guile, GNU Guile Reference Manual}). For instance, the
- following expression returns a list that contains all the services in
- @code{%desktop-services} minus the Avahi service:
- @lisp
- (remove (lambda (service)
- (eq? (service-kind service) avahi-service-type))
- %desktop-services)
- @end lisp
- Alternatively, the @code{modify-services} macro can be used:
- @lisp
- (modify-services %desktop-services
- (delete avahi-service-type))
- @end lisp
- @unnumberedsubsec Instantiating the System
- Assuming the @code{operating-system} declaration
- is stored in the @file{my-system-config.scm}
- file, the @command{guix system reconfigure my-system-config.scm} command
- instantiates that configuration, and makes it the default GRUB boot
- entry (@pxref{Invoking guix system}).
- @quotation Note
- We recommend that you keep this @file{my-system-config.scm} file safe
- and under version control to easily track changes to your configuration.
- @end quotation
- 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{mapped-devices} (default: @code{'()})
- A list of mapped devices. @xref{Mapped Devices}.
- @item @code{file-systems}
- A list of file systems. @xref{File Systems}.
- @item @code{swap-devices} (default: @code{'()})
- @cindex swap devices
- A list of swap spaces. @xref{Swap Space}.
- @item @code{users} (default: @code{%base-user-accounts})
- @itemx @code{groups} (default: @code{%base-groups})
- List of user accounts and groups. @xref{User Accounts}.
- If the @code{users} list lacks a user account with UID@tie{}0, a
- ``root'' account with UID@tie{}0 is automatically added.
- @item @code{skeletons} (default: @code{(default-skeletons)})
- A list of target file name/file-like object tuples (@pxref{G-Expressions,
- file-like objects}). These are the skeleton files that will be added to
- the home directory of newly-created user accounts.
- For instance, a valid value may look like this:
- @lisp
- `((".bashrc" ,(plain-file "bashrc" "echo Hello\n"))
- (".guile" ,(plain-file "guile"
- "(use-modules (ice-9 readline))
- (activate-readline)")))
- @end lisp
- @item @code{issue} (default: @code{%default-issue})
- A string denoting the contents of the @file{/etc/issue} file, which is
- displayed when users log in on a text console.
- @item @code{packages} (default: @code{%base-packages})
- A list of packages to be installed in the global profile, which is accessible
- at @file{/run/current-system/profile}. Each element is either a package
- variable or a package/output tuple. Here's a simple example of both:
- @lisp
- (cons* git ; the default "out" output
- (list git "send-email") ; another output of git
- %base-packages) ; the default set
- @end lisp
- The default set includes core utilities and it is good practice to
- install non-core utilities in user profiles (@pxref{Invoking guix
- package}).
- @item @code{timezone} (default: @code{"Etc/UTC"})
- 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}.
- @anchor{operating-system-essential-services}
- @cindex essential services
- @item @code{essential-services} (default: ...)
- The list of ``essential services''---i.e., things like instances of
- @code{system-service-type} (@pxref{Service Reference}) and
- @code{host-name-service-type}, 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
- @defmac 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 defmac
- @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{no-diratime} (likewise for directories only),
- @code{strict-atime} (update file access time), @code{lazy-time} (only
- update time on the in-memory version of the file inode),
- @code{no-exec} (disallow program execution), and @code{shared} (make the
- mount shared).
- @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.
- Run @command{man 8 mount} for options for various file systems, but
- beware that what it lists as file-system-independent ``mount options'' are
- in fact flags, and belong in the @code{flags} field described above.
- The @code{file-system-options->alist} and @code{alist->file-system-options}
- procedures from @code{(gnu system file-systems)} can be used to convert
- file system options given as an association list to the string
- representation, and vice-versa.
- @item @code{mount?} (default: @code{#t})
- This value indicates whether to automatically mount the file system when
- the system is brought up. When set to @code{#f}, the file system gets
- an entry in @file{/etc/fstab} (read by the @command{mount} command) but
- is not automatically mounted.
- @item @code{needed-for-boot?} (default: @code{#f})
- This Boolean value indicates whether the file system is needed when
- booting. If that is true, then the file system is mounted when the
- initial RAM disk (initrd) is loaded. This is always the case, for
- instance, for the root file system.
- @item @code{check?} (default: @code{#t})
- This Boolean indicates whether the file system should be checked for
- errors before being mounted. How and when this happens can be further
- adjusted with the following options.
- @item @code{skip-check-if-clean?} (default: @code{#t})
- When true, this Boolean indicates that a file system check triggered
- by @code{check?} may exit early if the file system is marked as
- ``clean'', meaning that it was previously correctly unmounted and
- should not contain errors.
- Setting this to false will always force a full consistency check when
- @code{check?} is true. This may take a very long time and is not
- recommended on healthy systems---in fact, it may reduce reliability!
- Conversely, some primitive file systems like @code{fat} do not keep
- track of clean shutdowns and will perform a full scan regardless of the
- value of this option.
- @item @code{repair} (default: @code{'preen})
- When @code{check?} finds errors, it can (try to) repair them and
- continue booting. This option controls when and how to do so.
- If false, try not to modify the file system at all. Checking certain
- file systems like @code{jfs} may still write to the device to replay
- the journal. No repairs will be attempted.
- If @code{#t}, try to repair any errors found and assume ``yes'' to
- all questions. This will fix the most errors, but may be risky.
- If @code{'preen}, repair only errors that are safe to fix without
- human interaction. What that means is left up to the developers of
- each file system and may be equivalent to ``none'' or ``all''.
- @item @code{create-mount-point?} (default: @code{#f})
- When true, the mount point is created if it does not exist yet.
- @item @code{mount-may-fail?} (default: @code{#f})
- When true, this indicates that mounting this file system can fail but
- that should not be considered an error. This is useful in unusual
- cases; an example of this is @code{efivarfs}, a file system that can
- only be mounted on EFI/UEFI systems.
- @item @code{dependencies} (default: @code{'()})
- This is a list of @code{<file-system>} or @code{<mapped-device>} objects
- representing file systems that must be mounted or mapped devices that
- must be opened before (and unmounted or closed after) this one.
- As an example, consider a hierarchy of mounts: @file{/sys/fs/cgroup} is
- a dependency of @file{/sys/fs/cgroup/cpu} and
- @file{/sys/fs/cgroup/memory}.
- Another example is a file system that depends on a mapped device, for
- example for an encrypted partition (@pxref{Mapped Devices}).
- @end table
- @end deftp
- @deffn {Procedure} file-system-label 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.
- @defvar %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 defvar
- @defvar %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 defvar
- @defvar %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 defvar
- @defvar %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 defvar
- @defvar %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 defvar
- @defvar %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 defvar
- The @code{(gnu system uuid)} module provides tools to deal with file
- system ``unique identifiers'' (UUIDs).
- @deffn {Procedure} uuid str [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
- @menu
- * Btrfs file system::
- @end menu
- @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
- @defvar 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 defvar
- @defvar 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 defvar
- @cindex LVM, logical volume manager
- @defvar 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 defvar
- @cindex disk encryption
- @cindex LUKS
- The following example specifies a mapping from @file{/dev/sda3} to
- @file{/dev/mapper/home} using LUKS---the
- @url{https://gitlab.com/cryptsetup/cryptsetup,Linux Unified Key Setup}, a
- standard mechanism for disk encryption.
- The @file{/dev/mapper/home}
- device can then be used as the @code{device} of a @code{file-system}
- declaration (@pxref{File Systems}).
- @lisp
- (mapped-device
- (source "/dev/sda3")
- (target "home")
- (type luks-device-mapping))
- @end lisp
- Alternatively, to become independent of device numbering, one may obtain
- the LUKS UUID (@dfn{unique identifier}) of the source device by a
- command like:
- @example
- cryptsetup luksUUID /dev/sda3
- @end example
- and use it as follows:
- @lisp
- (mapped-device
- (source (uuid "cb67fc72-0d54-4c88-9d4b-b225f30b0f44"))
- (target "home")
- (type luks-device-mapping))
- @end lisp
- @cindex swap encryption
- It is also desirable to encrypt swap space, since swap space may contain
- sensitive data. One way to accomplish that is to use a swap file in a
- file system on a device mapped via LUKS encryption. In this way, the
- swap file is encrypted because the entire device is encrypted.
- @xref{Swap Space}, or @xref{Preparing for Installation,,Disk
- Partitioning}, for an example.
- A RAID device formed of the partitions @file{/dev/sda1} and @file{/dev/sdb1}
- may be declared as follows:
- @lisp
- (mapped-device
- (source (list "/dev/sda1" "/dev/sdb1"))
- (target "/dev/md0")
- (type raid-device-mapping))
- @end lisp
- The @file{/dev/md0} device can then be used as the @code{device} of a
- @code{file-system} declaration (@pxref{File Systems}).
- Note that the RAID level need not be given; it is chosen during the
- initial creation and formatting of the RAID device and is determined
- automatically later.
- LVM logical volumes ``alpha'' and ``beta'' from volume group ``vg0'' can
- be declared as follows:
- @lisp
- (mapped-device
- (source "vg0")
- (targets (list "vg0-alpha" "vg0-beta"))
- (type lvm-device-mapping))
- @end lisp
- Devices @file{/dev/mapper/vg0-alpha} and @file{/dev/mapper/vg0-beta} can
- then be used as the @code{device} of a @code{file-system} declaration
- (@pxref{File Systems}).
- @node Swap Space
- @section Swap Space
- @cindex swap space
- Swap space, as it is commonly called, is a disk area specifically
- designated for paging: the process in charge of memory management
- (the Linux kernel or Hurd's default pager) can decide that some memory
- pages stored in RAM which belong to a running program but are unused
- should be stored on disk instead. It unloads those from the RAM,
- freeing up precious fast memory, and writes them to the swap space. If
- the program tries to access that very page, the memory management
- process loads it back into memory for the program to use.
- A common misconception about swap is that it is only useful when small
- amounts of RAM are available to the system. However, it should be noted
- that kernels often use all available RAM for disk access caching to make
- I/O faster, and thus paging out unused portions of program memory will
- expand the RAM available for such caching.
- For a more detailed description of how memory is managed from the
- viewpoint of a monolithic kernel, @pxref{Memory
- Concepts,,, libc, The GNU C Library Reference Manual}.
- The Linux kernel has support for swap partitions and swap files: the
- former uses a whole disk partition for paging, whereas the second uses a
- file on a file system for that (the file system driver needs to support
- it). On a comparable setup, both have the same performance, so one
- should consider ease of use when deciding between them. Partitions are
- ``simpler'' and do not need file system support, but need to be
- allocated at disk formatting time (logical volumes notwithstanding),
- whereas files can be allocated and deallocated at any time.
- @cindex hibernation
- @cindex suspend to disk
- Swap space is also required to put the system into @dfn{hibernation}
- (also called @dfn{suspend to disk}), whereby memory is dumped to swap
- before shutdown so it can be restored when the machine is eventually
- restarted. Hibernation uses at most half the size of the RAM in the
- configured swap space. The Linux kernel needs to know about the swap
- space to be used to resume from hibernation on boot (@i{via} a kernel
- argument). When using a swap file, its offset in the device holding it
- also needs to be given to the kernel; that value has to be updated if
- the file is initialized again as swap---e.g., because its size was
- changed.
- Note that swap space is not zeroed on shutdown, so sensitive data (such
- as passwords) may linger on it if it was paged out. As such, you should
- consider having your swap reside on an encrypted device (@pxref{Mapped
- Devices}).
- @deftp {Data Type} swap-space
- Objects of this type represent swap spaces. They contain the following
- members:
- @table @asis
- @item @code{target}
- The device or file to use, either a UUID, a @code{file-system-label} or
- a string, as in the definition of a @code{file-system} (@pxref{File
- Systems}).
- @item @code{dependencies} (default: @code{'()})
- A list of @code{file-system} or @code{mapped-device} objects, upon which
- the availability of the space depends. Note that just like for
- @code{file-system} objects, dependencies which are needed for boot and
- mounted in early userspace are not managed by the Shepherd, and so
- automatically filtered out for you.
- @item @code{priority} (default: @code{#f})
- Only supported by the Linux kernel. Either @code{#f} to disable swap
- priority, or an integer between 0 and 32767. The kernel will first use
- swap spaces of higher priority when paging, and use same priority spaces
- on a round-robin basis. The kernel will use swap spaces without a set
- priority after prioritized spaces, and in the order that they appeared in
- (not round-robin).
- @item @code{discard?} (default: @code{#f})
- Only supported by the Linux kernel. When true, the kernel will notify
- the disk controller of discarded pages, for example with the TRIM
- operation on Solid State Drives.
- @end table
- @end deftp
- Here are some examples:
- @lisp
- (swap-space (target (uuid "4dab5feb-d176-45de-b287-9b0a6e4c01cb")))
- @end lisp
- Use the swap partition with the given UUID@. You can learn the UUID of a
- Linux swap partition by running @command{swaplabel @var{device}}, where
- @var{device} is the @file{/dev} file name of that partition.
- @lisp
- (swap-space
- (target (file-system-label "swap"))
- (dependencies mapped-devices))
- @end lisp
- Use the partition with label @code{swap}, which can be found after all
- the @var{mapped-devices} mapped devices have been opened. Again, the
- @command{swaplabel} command allows you to view and change the label of a
- Linux swap partition.
- Here's a more involved example with the corresponding @code{file-systems} part
- of an @code{operating-system} declaration.
- @lisp
- (file-systems
- (list (file-system
- (device (file-system-label "root"))
- (mount-point "/")
- (type "ext4"))
- (file-system
- (device (file-system-label "btrfs"))
- (mount-point "/btrfs")
- (type "btrfs"))))
- (swap-devices
- (list
- (swap-space
- (target "/btrfs/swapfile")
- (dependencies (filter (file-system-mount-point-predicate "/btrfs")
- file-systems)))))
- @end lisp
- Use the file @file{/btrfs/swapfile} as swap space, which depends on the
- file system mounted at @file{/btrfs}. Note how we use Guile's filter to
- select the file system in an elegant fashion!
- @lisp
- (swap-devices
- (list
- (swap-space
- (target "/dev/mapper/my-swap")
- (dependencies mapped-devices))))
- (kernel-arguments
- (cons* "resume=/dev/mapper/my-swap"
- %default-kernel-arguments))
- @end lisp
- The above snippet of an @code{operating-system} declaration enables
- the mapped device @file{/dev/mapper/my-swap} (which may be part of an
- encrypted device) as swap space, and tells the kernel to use it for
- hibernation via the @code{resume} kernel argument
- (@pxref{operating-system Reference}, @code{kernel-arguments}).
- @lisp
- (swap-devices
- (list
- (swap-space
- (target "/swapfile")
- (dependencies (filter (file-system-mount-point-predicate "/")
- file-systems)))))
- (kernel-arguments
- (cons* "resume=/dev/sda3" ;device that holds /swapfile
- "resume_offset=92514304" ;offset of /swapfile on device
- %default-kernel-arguments))
- @end lisp
- This other snippet of @code{operating-system} enables the swap file
- @file{/swapfile} for hibernation by telling the kernel about the
- partition containing it
- (@code{resume} argument) and its offset on that partition (@code{resume_offset}
- argument). The latter value can be found in the output of the command
- @command{filefrag -e} as the first number right under the
- @code{physical_offset} column header (the second command extracts its
- value directly):
- @smallexample
- $ sudo filefrag -e /swapfile
- Filesystem type is: ef53
- File size of /swapfile is 2463842304 (601524 blocks of 4096 bytes)
- ext: logical_offset: physical_offset: length: expected: flags:
- 0: 0.. 2047: 92514304.. 92516351: 2048:
- @dots{}
- $ sudo filefrag -e /swapfile | grep '^ *0:' | cut -d: -f3 | cut -d. -f1
- 92514304
- @end smallexample
- @node User Accounts
- @section User Accounts
- @cindex users
- @cindex accounts
- @cindex user accounts
- User accounts and groups are entirely managed through the
- @code{operating-system} declaration. They are specified with the
- @code{user-account} and @code{user-group} forms:
- @lisp
- (user-account
- (name "alice")
- (group "users")
- (supplementary-groups '("wheel" ;allow use of sudo, etc.
- "audio" ;sound card
- "video" ;video devices such as webcams
- "cdrom")) ;the good ol' CD-ROM
- (comment "Bob's sister"))
- @end lisp
- Here's a user account that uses a different shell and a custom home
- directory (the default would be @file{"/home/bob"}):
- @lisp
- (user-account
- (name "bob")
- (group "users")
- (comment "Alice's bro")
- (shell (file-append zsh "/bin/zsh"))
- (home-directory "/home/robert"))
- @end lisp
- When booting or upon completion of @command{guix system reconfigure},
- the system ensures that only the user accounts and groups specified in
- the @code{operating-system} declaration exist, and with the specified
- properties. Thus, account or group creations or modifications made by
- directly invoking commands such as @command{useradd} are lost upon
- reconfiguration or reboot. This ensures that the system remains exactly
- as declared.
- @deftp {Data Type} user-account
- Objects of this type represent user accounts. The following members may
- be specified:
- @table @asis
- @item @code{name}
- The name of the user account.
- @item @code{group}
- @cindex groups
- This is the name (a string) or identifier (a number) of the user group
- this account belongs to.
- @item @code{supplementary-groups} (default: @code{'()})
- Optionally, this can be defined as a list of group names that this
- account belongs to.
- @item @code{uid} (default: @code{#f})
- This is the user ID for this account (a number), or @code{#f}. In the
- latter case, a number is automatically chosen by the system when the
- account is created.
- @item @code{comment} (default: @code{""})
- A comment about the account, such as the account owner's full name.
- Note that, for non-system accounts, users are free to change their real
- name as it appears in @file{/etc/passwd} using the @command{chfn}
- command. When they do, their choice prevails over the system
- administrator's choice; reconfiguring does @emph{not} change their name.
- @item @code{home-directory}
- This is the name of the home directory for the account.
- @item @code{create-home-directory?} (default: @code{#t})
- Indicates whether the home directory of this account should be created
- if it does not exist yet.
- @item @code{shell} (default: Bash)
- This is a G-expression denoting the file name of a program to be used as
- the shell (@pxref{G-Expressions}). For example, you would refer to the
- Bash executable like this:
- @lisp
- (file-append bash "/bin/bash")
- @end lisp
- @noindent
- ... and to the Zsh executable like that:
- @lisp
- (file-append zsh "/bin/zsh")
- @end lisp
- @item @code{system?} (default: @code{#f})
- This Boolean value indicates whether the account is a ``system''
- account. System accounts are sometimes treated specially; for instance,
- graphical login managers do not list them.
- @anchor{user-account-password}
- @cindex password, for user accounts
- @item @code{password} (default: @code{#f})
- You would normally leave this field to @code{#f}, initialize user
- passwords as @code{root} with the @command{passwd} command, and then let
- users change it with @command{passwd}. Passwords set with
- @command{passwd} are of course preserved across reboot and
- reconfiguration.
- If you @emph{do} want to set an initial password for an account, then
- this field must contain the encrypted password, as a string. You can use the
- @code{crypt} procedure for this purpose:
- @lisp
- (user-account
- (name "charlie")
- (group "users")
- ;; Specify a SHA-512-hashed initial password.
- (password (crypt "InitialPassword!" "$6$abc")))
- @end lisp
- @quotation Note
- The hash of this initial password will be available in a file in
- @file{/gnu/store}, readable by all the users, so this method must be used with
- care.
- @end quotation
- @xref{Passphrase Storage,,, libc, The GNU C Library Reference Manual}, for
- more information on password encryption, and @ref{Encryption,,, guile, GNU
- Guile Reference Manual}, for information on Guile's @code{crypt} procedure.
- @end table
- @end deftp
- @cindex groups
- User group declarations are even simpler:
- @lisp
- (user-group (name "students"))
- @end lisp
- @deftp {Data Type} user-group
- This type is for, well, user groups. There are just a few fields:
- @table @asis
- @item @code{name}
- The name of the group.
- @item @code{id} (default: @code{#f})
- The group identifier (a number). If @code{#f}, a new number is
- automatically allocated when the group is created.
- @item @code{system?} (default: @code{#f})
- This Boolean value indicates whether the group is a ``system'' group.
- System groups have low numerical IDs.
- @item @code{password} (default: @code{#f})
- What, user groups can have a password? Well, apparently yes. Unless
- @code{#f}, this field specifies the password of the group.
- @end table
- @end deftp
- For convenience, a variable lists all the basic user groups one may
- expect:
- @defvar %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 defvar
- @defvar %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 defvar
- @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 {Procedure} keyboard-layout name [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
- @defvar %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 defvar
- @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
- @cindex configuration, action for shepherd services
- @cindex configuration file, of a shepherd service
- For some services, @command{herd configuration} returns the name of the
- service's configuration file, which can be handy to inspect its
- configuration:
- @example
- # herd configuration sshd
- /gnu/store/@dots{}-sshd_config
- @end example
- The following sections document the available services, starting with
- the core services, that may be used in an @code{operating-system}
- declaration.
- @menu
- * Base Services:: Essential system services.
- * Scheduled Job Execution:: The mcron service.
- * Log Rotation:: The rottlog service.
- * Networking Setup:: Setting up network interfaces.
- * Networking Services:: Firewall, SSH daemon, etc.
- * Unattended Upgrades:: Automated system upgrades.
- * X Window:: Graphical display.
- * Printing Services:: Local and remote printer support.
- * Desktop Services:: D-Bus and desktop services.
- * Sound Services:: ALSA and Pulseaudio services.
- * File Search Services:: Tools to search for files.
- * 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.
- * VNC Services:: VNC daemons.
- * VPN Services:: VPN daemons.
- * Network File System:: NFS related services.
- * Samba Services:: Samba 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.
- @defvar %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 defvar
- @defvar 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 two-element lists 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"))
- ("/usr/bin/env" ,(file-append coreutils "/bin/env")))
- @end lisp
- @cindex @file{/usr/bin/env}
- @cindex @file{env}, in @file{/usr/bin}
- If you want to add, say, @code{/bin/bash} to your system, you can
- change it to:
- @lisp
- `(("/bin/sh" ,(file-append bash "/bin/sh"))
- ("/usr/bin/env" ,(file-append coreutils "/bin/env"))
- ("/bin/bash" ,(file-append bash "/bin/bash")))
- @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 defvar
- @deffn {Procedure} extra-special-file file 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
- @defvar host-name-service-type
- Type of the service that sets the system host name, whose value
- is a string. This service is included in @code{operating-system} by
- default (@pxref{operating-system-essential-services,@code{essential-services}}).
- @end defvar
- @defvar 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 defvar
- @defvar hosts-service-type
- Type of the service that populates the entries for (@file{/etc/hosts}).
- This service type can be @emph{extended} by passing it a list of
- @code{host} records.
- The example below shows how to add two entries to @file{/etc/hosts}:
- @c TRANSLATORS: The domain names below SHOULD NOT be translated.
- @c They're domains reserved for use in documentation. (RFC6761 Section 6.5)
- @c The addresses used are explained in RFC3849 and RFC5737.
- @lisp
- (simple-service 'add-extra-hosts
- hosts-service-type
- (list (host "192.0.2.1" "example.com"
- '("example.net" "example.org"))
- (host "2001:db8::1" "example.com"
- '("example.net" "example.org"))))
- @end lisp
- @quotation Note
- @cindex @file{/etc/hosts} default entries
- By default @file{/etc/hosts} comes with the following entries:
- @example
- 127.0.0.1 localhost @var{host-name}
- ::1 localhost @var{host-name}
- @end example
- For most setups this is what you want though if you find yourself in
- the situation where you want to change the default entries, you can
- do so in @code{operating-system} via @code{modify-services}
- (@pxref{Service Reference,@code{modify-services}}).
- The following example shows how to unset @var{host-name} from being an
- alias of @code{localhost}.
- @lisp
- (operating-system
- ;; @dots{}
- (essential-services
- (modify-services
- (operating-system-default-essential-services this-operating-system)
- (hosts-service-type config => (list
- (host "127.0.0.1" "localhost")
- (host "::1" "localhost"))))))
- @end lisp
- @end quotation
- @end defvar
- @deffn {Procedure} host @var{address} @var{canonical-name} [@var{aliases}]
- Return a new record for the host at @var{address} with the given
- @var{canonical-name} and possibly @var{aliases}.
- @var{address} must be a string denoting a valid IPv4 or IPv6 address, and
- @var{canonical-name} and the strings listed in @var{aliases} must be valid
- host names.
- @end deffn
- @defvar login-service-type
- Type of the service that provides a console login service, whose value
- is a @code{<login-configuration>} object.
- @end defvar
- @deftp {Data Type} login-configuration
- Data type representing the configuration of login, which specifies the
- @acronym{MOTD, message of the day}, among other things.
- @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
- @defvar mingetty-service-type
- Type of the service that runs Mingetty, an implementation of the
- virtual console log-in. The value for this service is a
- @code{<mingetty-configuration>} object.
- @end defvar
- @deftp {Data Type} mingetty-configuration
- Data type representing the configuration of Mingetty, which specifies
- the tty to run, among other things.
- @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
- @defvar agetty-service-type
- Type of the service that runs agetty, which implements virtual and
- serial console log-in. The value for this service is a
- @code{<agetty-configuration>} object.
- @end defvar
- @deftp {Data Type} agetty-configuration
- Data type representing the configuration of agetty, which specifies the
- tty to run, among other things@footnote{See the @code{agetty(8)}
- man page for more information.}.
- @table @asis
- @item @code{tty}
- The name of the console this agetty runs on, as a string---e.g.,
- @code{"ttyS0"}. This argument is optional, it will default to
- a reasonable default serial port used by the kernel Linux.
- For this, if there is a value for an option @code{agetty.tty} in the kernel
- command line, agetty will extract the device name of the serial port
- from it and use that.
- If not and if there is a value for an option @code{console} with a tty in
- the Linux command line, agetty will extract the device name of the
- serial port from it and use that.
- In both cases, agetty will leave the other serial device settings
- (baud rate etc.)@: alone---in the hope that Linux pinned them to the
- correct values.
- @item @code{baud-rate} (default: @code{#f})
- A string containing a comma-separated list of one or more baud rates, in
- descending order.
- @item @code{term} (default: @code{#f})
- A string containing the value used for the @env{TERM} environment
- variable.
- @item @code{eight-bits?} (default: @code{#f})
- When @code{#t}, the tty is assumed to be 8-bit clean, and parity detection is
- disabled.
- @item @code{auto-login} (default: @code{#f})
- When passed a login name, as a string, the specified user will be logged
- in automatically without prompting for their login name or password.
- @item @code{no-reset?} (default: @code{#f})
- When @code{#t}, don't reset terminal cflags (control modes).
- @item @code{host} (default: @code{#f})
- This accepts a string containing the ``login_host'', which will be written
- into the @file{/var/run/utmpx} file.
- @item @code{remote?} (default: @code{#f})
- When set to @code{#t} in conjunction with @var{host}, this will add an
- @code{-r} fakehost option to the command line of the login program
- specified in @var{login-program}.
- @item @code{flow-control?} (default: @code{#f})
- When set to @code{#t}, enable hardware (RTS/CTS) flow control.
- @item @code{no-issue?} (default: @code{#f})
- When set to @code{#t}, the contents of the @file{/etc/issue} file will
- not be displayed before presenting the login prompt.
- @item @code{init-string} (default: @code{#f})
- This accepts a string that will be sent to the tty or modem before
- sending anything else. It can be used to initialize a modem.
- @item @code{no-clear?} (default: @code{#f})
- When set to @code{#t}, agetty will not clear the screen before showing
- the login prompt.
- @item @code{login-program} (default: (file-append shadow "/bin/login"))
- This must be either a gexp denoting the name of a log-in program, or
- unset, in which case the default value is the @command{login} from the
- Shadow tool suite.
- @item @code{local-line} (default: @code{#f})
- Control the CLOCAL line flag. This accepts one of three symbols as
- arguments, @code{'auto}, @code{'always}, or @code{'never}. If @code{#f},
- the default value chosen by agetty is @code{'auto}.
- @item @code{extract-baud?} (default: @code{#f})
- When set to @code{#t}, instruct agetty to try to extract the baud rate
- from the status messages produced by certain types of modems.
- @item @code{skip-login?} (default: @code{#f})
- When set to @code{#t}, do not prompt the user for a login name. This
- can be used with @var{login-program} field to use non-standard login
- systems.
- @item @code{no-newline?} (default: @code{#f})
- When set to @code{#t}, do not print a newline before printing the
- @file{/etc/issue} file.
- @c Is this dangerous only when used with login-program, or always?
- @item @code{login-options} (default: @code{#f})
- This option accepts a string containing options that are passed to the
- login program. When used with the @var{login-program}, be aware that a
- malicious user could try to enter a login name containing embedded
- options that could be parsed by the login program.
- @item @code{login-pause} (default: @code{#f})
- When set to @code{#t}, wait for any key before showing the login prompt.
- This can be used in conjunction with @var{auto-login} to save memory by
- lazily spawning shells.
- @item @code{chroot} (default: @code{#f})
- Change root to the specified directory. This option accepts a directory
- path as a string.
- @item @code{hangup?} (default: @code{#f})
- Use the Linux system call @code{vhangup} to do a virtual hangup of the
- specified terminal.
- @item @code{keep-baud?} (default: @code{#f})
- When set to @code{#t}, try to keep the existing baud rate. The baud
- rates from @var{baud-rate} are used when agetty receives a @key{BREAK}
- character.
- @item @code{timeout} (default: @code{#f})
- When set to an integer value, terminate if no user name could be read
- within @var{timeout} seconds.
- @item @code{detect-case?} (default: @code{#f})
- When set to @code{#t}, turn on support for detecting an uppercase-only
- terminal. This setting will detect a login name containing only
- uppercase letters as indicating an uppercase-only terminal and turn on
- some upper-to-lower case conversions. Note that this will not support
- Unicode characters.
- @item @code{wait-cr?} (default: @code{#f})
- When set to @code{#t}, wait for the user or modem to send a
- carriage-return or linefeed character before displaying
- @file{/etc/issue} or login prompt. This is typically used with the
- @var{init-string} option.
- @item @code{no-hints?} (default: @code{#f})
- When set to @code{#t}, do not print hints about Num, Caps, and Scroll
- locks.
- @item @code{no-hostname?} (default: @code{#f})
- By default, the hostname is printed. When this option is set to
- @code{#t}, no hostname will be shown at all.
- @item @code{long-hostname?} (default: @code{#f})
- By default, the hostname is only printed until the first dot. When this
- option is set to @code{#t}, the fully qualified hostname by
- @code{gethostname} or @code{getaddrinfo} is shown.
- @item @code{erase-characters} (default: @code{#f})
- This option accepts a string of additional characters that should be
- interpreted as backspace when the user types their login name.
- @item @code{kill-characters} (default: @code{#f})
- This option accepts a string that should be interpreted to mean ``ignore
- all previous characters'' (also called a ``kill'' character) when the user
- types their login name.
- @item @code{chdir} (default: @code{#f})
- This option accepts, as a string, a directory path that will be changed
- to before login.
- @item @code{delay} (default: @code{#f})
- This options accepts, as an integer, the number of seconds to sleep
- before opening the tty and displaying the login prompt.
- @item @code{nice} (default: @code{#f})
- This option accepts, as an integer, the nice value with which to run the
- @command{login} program.
- @item @code{extra-options} (default: @code{'()})
- This option provides an ``escape hatch'' for the user to provide arbitrary
- command-line arguments to @command{agetty} as a list of strings.
- @item @code{shepherd-requirement} (default: @code{'()})
- The option can be used to provides extra shepherd requirements (for example
- @code{'syslogd}) to the respective @code{'term-}* shepherd service.
- @end table
- @end deftp
- @defvar kmscon-service-type
- Type of the service that runs @uref{https://www.freedesktop.org/wiki/Software/kmscon,kmscon},
- which implements virtual console log-in. The value for this service is a
- @code{<kmscon-configuration>} object.
- @end defvar
- @deftp {Data Type} kmscon-configuration
- Data type representing the configuration of Kmscon, which specifies the
- tty to run, among other things.
- @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 @abbr{nscd, name service cache daemon}
- @defvar nscd-service-type
- Type of the service that runs the libc @abbr{nscd, name service cache
- daemon}, whose value is an @code{<nscd-configuration>} object.
- For convenience, the Shepherd service for nscd provides the following actions:
- @table @code
- @item invalidate
- @cindex nscd, cache invalidation
- @cindex cache invalidation, nscd
- 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 defvar
- @deftp {Data Type} nscd-configuration
- Data type representing the @abbr{nscd, name service cache daemon}
- 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
- @defvar %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 defvar
- @cindex syslog
- @cindex logging
- @defvar syslog-service-type
- Type of the service that runs the syslog daemon, whose value is a
- @code{<syslog-configuration>} object.
- @end defvar
- To have a modified @code{syslog-configuration} come into effect after
- reconfiguring your system, the @samp{reload} action should be preferred
- to restarting the service, as many services such as the login manager
- depend on it and would be restarted as well:
- @example
- # herd reload syslog
- @end example
- which will cause the running @command{syslogd} process to reload its
- configuration.
- @deftp {Data Type} syslog-configuration
- Data type representing 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.
- @xref{syslogd invocation,,, inetutils, GNU Inetutils}, for more
- information on the configuration file syntax.
- @end table
- @end deftp
- @defvar 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 defvar
- @anchor{guix-configuration-type}
- @deftp {Data Type} guix-configuration
- This data type represents the configuration of the Guix build daemon.
- @xref{Invoking guix-daemon}, for more information.
- @table @asis
- @item @code{guix} (default: @var{guix})
- The Guix package to use.
- @item @code{build-group} (default: @code{"guixbuild"})
- Name of the group for build user accounts.
- @item @code{build-accounts} (default: @code{10})
- Number of build user accounts to create.
- @item @code{authorize-key?} (default: @code{#t})
- @cindex substitutes, authorization thereof
- Whether to authorize the substitute keys listed in
- @code{authorized-keys}---by default that of
- @code{@value{SUBSTITUTE-SERVER-1}} and
- @code{@value{SUBSTITUTE-SERVER-2}}
- (@pxref{Substitutes}).
- When @code{authorize-key?} is true, @file{/etc/guix/acl} cannot be
- changed by invoking @command{guix archive --authorize}. You must
- instead adjust @code{guix-configuration} as you wish and reconfigure the
- system. This ensures that your operating system configuration file is
- self-contained.
- @quotation Note
- When booting or reconfiguring to a system where @code{authorize-key?}
- is true, the existing @file{/etc/guix/acl} file is backed up as
- @file{/etc/guix/acl.bak} if it was determined to be a manually modified
- file. This is to facilitate migration from earlier versions, which
- allowed for in-place modifications to @file{/etc/guix/acl}.
- @end quotation
- @vindex %default-authorized-guix-keys
- @item @code{authorized-keys} (default: @code{%default-authorized-guix-keys})
- The list of authorized key files for archive imports, as a list of
- string-valued gexps (@pxref{Invoking guix archive}). By default, it
- contains that of @code{@value{SUBSTITUTE-SERVER-1}} and
- @code{@value{SUBSTITUTE-SERVER-2}} (@pxref{Substitutes}). See
- @code{substitute-urls} below for an example on how to change it.
- @item @code{use-substitutes?} (default: @code{#t})
- Whether to use substitutes.
- @item @code{substitute-urls} (default: @code{%default-substitute-urls})
- The list of URLs where to look for substitutes by default.
- Suppose you would like to fetch substitutes from @code{guix.example.org}
- in addition to @code{@value{SUBSTITUTE-SERVER-1}}. You will need to do
- two things: (1) add @code{guix.example.org} to @code{substitute-urls},
- and (2) authorize its signing key, having done appropriate checks
- (@pxref{Substitute Server Authorization}). The configuration below does
- exactly that:
- @lisp
- (guix-configuration
- (substitute-urls
- (append (list "https://guix.example.org")
- %default-substitute-urls))
- (authorized-keys
- (append (list (local-file "./guix.example.org-key.pub"))
- %default-authorized-guix-keys)))
- @end lisp
- This example assumes that the file @file{./guix.example.org-key.pub}
- contains the public key that @code{guix.example.org} uses to sign
- substitutes.
- @item @code{generate-substitute-key?} (default: @code{#t})
- Whether to generate a @dfn{substitute key pair} under
- @file{/etc/guix/signing-key.pub} and @file{/etc/guix/signing-key.sec} if
- there is not already one.
- This key pair is used when exporting store items, for instance with
- @command{guix publish} (@pxref{Invoking guix publish}) or @command{guix
- archive} (@pxref{Invoking guix archive}). Generating a key pair takes a
- few seconds when enough entropy is available and is only done once; you
- might want to turn it off for instance in a virtual machine that does
- not need it and where the extra boot time is a problem.
- @item @code{max-silent-time} (default: @code{0})
- @itemx @code{timeout} (default: @code{0})
- The number of seconds of silence and the number of seconds of activity,
- respectively, after which a build process times out. A value of zero
- disables the timeout.
- @item @code{log-compression} (default: @code{'gzip})
- The type of compression used for build logs---one of @code{gzip},
- @code{bzip2}, or @code{none}.
- @item @code{discover?} (default: @code{#f})
- Whether to discover substitute servers on the local network using mDNS
- and DNS-SD.
- @item @code{extra-options} (default: @code{'()})
- List of extra command-line options for @command{guix-daemon}.
- @item @code{log-file} (default: @code{"/var/log/guix-daemon.log"})
- File where @command{guix-daemon}'s standard output and standard error
- are written.
- @cindex HTTP proxy, for @code{guix-daemon}
- @cindex proxy, for @code{guix-daemon} HTTP access
- @item @code{http-proxy} (default: @code{#f})
- The URL of the HTTP and HTTPS proxy used for downloading fixed-output
- derivations and substitutes.
- It is also possible to change the daemon's proxy at run time through the
- @code{set-http-proxy} action, which restarts it:
- @example
- herd set-http-proxy guix-daemon http://localhost:8118
- @end example
- To clear the proxy settings, run:
- @example
- herd set-http-proxy guix-daemon
- @end example
- @item @code{tmpdir} (default: @code{#f})
- A directory path where the @command{guix-daemon} will perform builds.
- @item @code{environment} (default: @code{'()})
- Environment variables to be set before starting the daemon, as a list of
- @code{key=value} strings.
- @end table
- @end deftp
- @deftp {Data Type} guix-extension
- This data type represents the parameters of the Guix build daemon that
- are extendable. This is the type of the object that must be used within
- a guix service extension.
- @xref{Service Composition}, for more information.
- @table @asis
- @item @code{authorized-keys} (default: @code{'()})
- A list of file-like objects where each element contains a public key.
- @item @code{substitute-urls} (default: @code{'()})
- A list of strings where each element is a substitute URL.
- @item @code{chroot-directories} (default: @code{'()})
- A list of file-like objects or strings pointing to additional directories the build daemon can use.
- @end table
- @end deftp
- @defvar udev-service-type
- Type of the service that runs udev, a service which populates the
- @file{/dev} directory dynamically, whose value is a
- @code{<udev-configuration>} object.
- This service type can be @emph{extended} using procedures
- @code{udev-rules-service} along with @code{file->udev-rule} or
- @code{udev-rule} which simplify the process of writing udev rules.
- @end defvar
- @deftp {Data Type} udev-configuration
- Data type representing the configuration of udev.
- @table @asis
- @item @code{udev} (default: @code{eudev}) (type: file-like)
- Package object of the udev service.
- @item @code{rules} (default: @var{'()}) (type: list-of-file-like)
- List of file-like objects denoting udev-rule files.
- @end table
- @end deftp
- @deffn {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 {Procedure} udev-rules-service @var{name} @var{rules} [#: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 {Procedure} file->udev-rule @var{file-name} @var{file}
- Return a udev-rule 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
- @defvar 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 defvar
- @defvar %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 defvar
- @cindex mouse
- @cindex gpm
- @defvar 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 defvar
- @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}
- @defvar 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 defvar
- @deftp {Data Type} guix-publish-configuration
- Data type representing the configuration of the @code{guix publish}
- service.
- @table @asis
- @item @code{guix} (default: @code{guix})
- The Guix package to use.
- @item @code{port} (default: @code{80})
- The TCP port to listen for connections.
- @item @code{host} (default: @code{"localhost"})
- The host (and thus, network interface) to listen to. Use
- @code{"0.0.0.0"} to listen on all the network interfaces.
- @item @code{advertise?} (default: @code{#f})
- When true, advertise the service on the local network @i{via} the DNS-SD
- protocol, using Avahi.
- This allows neighboring Guix devices with discovery on (see
- @code{guix-configuration} above) to discover this @command{guix publish}
- instance and to automatically download substitutes from it.
- @item @code{compression} (default: @code{'(("gzip" 3) ("zstd" 3))})
- This is a list of compression method/level tuple used when compressing
- substitutes. For example, to compress all substitutes with @emph{both} lzip
- at level 7 and gzip at level 9, write:
- @lisp
- '(("lzip" 7) ("gzip" 9))
- @end lisp
- Level 9 achieves the best compression ratio at the expense of increased CPU
- usage, whereas level 1 achieves fast compression. @xref{Invoking guix
- publish}, for more information on the available compression methods and
- the tradeoffs involved.
- An empty list disables compression altogether.
- @item @code{nar-path} (default: @code{"nar"})
- The URL path at which ``nars'' can be fetched. @xref{Invoking guix
- publish, @option{--nar-path}}, for details.
- @item @code{cache} (default: @code{#f})
- When it is @code{#f}, disable caching and instead generate archives on
- demand. Otherwise, this should be the name of a directory---e.g.,
- @code{"/var/cache/guix/publish"}---where @command{guix publish} caches
- archives and meta-data ready to be sent. @xref{Invoking guix publish,
- @option{--cache}}, for more information on the tradeoffs involved.
- @item @code{workers} (default: @code{#f})
- When it is an integer, this is the number of worker threads used for
- caching; when @code{#f}, the number of processors is used.
- @xref{Invoking guix publish, @option{--workers}}, for more information.
- @item @code{cache-bypass-threshold} (default: 10 MiB)
- When @code{cache} is true, this is the maximum size in bytes of a store
- item for which @command{guix publish} may bypass its cache in case of a
- cache miss. @xref{Invoking guix publish,
- @option{--cache-bypass-threshold}}, for more information.
- @item @code{ttl} (default: @code{#f})
- When it is an integer, this denotes the @dfn{time-to-live} in seconds
- of the published archives. @xref{Invoking guix publish, @option{--ttl}},
- for more information.
- @item @code{negative-ttl} (default: @code{#f})
- When it is an integer, this denotes the @dfn{time-to-live} in
- seconds for the negative lookups. @xref{Invoking guix publish,
- @option{--negative-ttl}}, for more information.
- @end table
- @end deftp
- @defvar rngd-service-type
- Type of the service that runs rng-tools rngd, whose value is an
- @code{<rngd-configuration>} object.
- @end defvar
- @deftp {Data Type} rngd-configuration
- Data type representing the configuration of rngd.
- @table @asis
- @item @code{rng-tools} (default: @code{rng-tools}) (type: file-like)
- Package object of the rng-tools rngd.
- @item @code{device} (default: @var{"/dev/hwrng"}) (type: string)
- Path of the device to add to the kernel's entropy pool. The service
- will fail if @var{device} does not exist.
- @end table
- @end deftp
- @cindex session limits
- @cindex ulimit
- @cindex priority
- @cindex realtime
- @cindex jackd
- @cindex nofile
- @cindex open file descriptors
- @anchor{pam-limits-service-type}
- @defvar pam-limits-service-type
- Type of the 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 value for this service type is
- 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.
- By default, the value is the empty list.
- The following limits definition sets two hard and soft limits for all
- login sessions of users in the @code{realtime} group:
- @lisp
- (service pam-limits-service-type
- (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
- (service pam-limits-service-type
- (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 defvar
- @defvar greetd-service-type
- @uref{https://git.sr.ht/~kennylevinsen/greetd, @code{greetd}} is a minimal and
- flexible login manager daemon, that makes no assumptions about what you
- want to launch.
- If you can run it from your shell in a TTY, greetd can start it. If it
- can be taught to speak a simple JSON-based IPC protocol, then it can be
- a geeter.
- @code{greetd-service-type} provides necessary infrastructure for logging
- in users, including:
- @itemize @bullet
- @item
- @code{greetd} PAM service
- @item
- Special variation of @code{pam-mount} to mount @code{XDG_RUNTIME_DIR}
- @end itemize
- Here is example of switching from @code{mingetty-service-type} to
- @code{greetd-service-type}, and how different terminals could be:
- @lisp
- (append
- (modify-services %base-services
- ;; greetd-service-type provides "greetd" PAM service
- (delete login-service-type)
- ;; and can be used in place of mingetty-service-type
- (delete mingetty-service-type))
- (list
- (service greetd-service-type
- (greetd-configuration
- (terminals
- (list
- ;; we can make any terminal active by default
- (greetd-terminal-configuration (terminal-vt "1") (terminal-switch #t))
- ;; we can make environment without XDG_RUNTIME_DIR set
- ;; even provide our own environment variables
- (greetd-terminal-configuration
- (terminal-vt "2")
- (default-session-command
- (greetd-agreety-session
- (extra-env '(("MY_VAR" . "1")))
- (xdg-env? #f))))
- ;; we can use different shell instead of default bash
- (greetd-terminal-configuration
- (terminal-vt "3")
- (default-session-command
- (greetd-agreety-session (command (file-append zsh "/bin/zsh")))))
- ;; we can use any other executable command as greeter
- (greetd-terminal-configuration
- (terminal-vt "4")
- (default-session-command (program-file "my-noop-greeter" #~(exit))))
- (greetd-terminal-configuration (terminal-vt "5"))
- (greetd-terminal-configuration (terminal-vt "6"))))))
- ;; mingetty-service-type can be used in parallel
- ;; if needed to do so, do not (delete login-service-type)
- ;; as illustrated above
- #| (service mingetty-service-type (mingetty-configuration (tty "tty8"))) |#))
- @end lisp
- @end defvar
- @deftp {Data Type} greetd-configuration
- Configuration record for the @code{greetd-service-type}.
- @table @asis
- @item @code{motd}
- 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.
- @item @code{terminals} (default: @code{'()})
- List of @code{greetd-terminal-configuration} per terminal for which
- @code{greetd} should be started.
- @item @code{greeter-supplementary-groups} (default: @code{'()})
- List of groups which should be added to @code{greeter} user. For instance:
- @lisp
- (greeter-supplementary-groups '("seat" "video"))
- @end lisp
- Note that this example will fail if @code{seat} group does not exist.
- @end table
- @end deftp
- @deftp {Data Type} greetd-terminal-configuration
- Configuration record for per terminal greetd daemon service.
- @table @asis
- @item @code{greetd} (default: @code{greetd})
- The greetd package to use.
- @item @code{config-file-name}
- Configuration file name to use for greetd daemon. Generally, autogenerated
- derivation based on @code{terminal-vt} value.
- @item @code{log-file-name}
- Log file name to use for greetd daemon. Generally, autogenerated
- name based on @code{terminal-vt} value.
- @item @code{terminal-vt} (default: @samp{"7"})
- The VT to run on. Use of a specific VT with appropriate conflict avoidance
- is recommended.
- @item @code{terminal-switch} (default: @code{#f})
- Make this terminal active on start of @code{greetd}.
- @item @code{source-profile?} (default: @code{#t})
- Whether to source @file{/etc/profile} and @file{~/.profile}, when they
- exist.
- @item @code{default-session-user} (default: @samp{"greeter"})
- The user to use for running the greeter.
- @item @code{default-session-command} (default: @code{(greetd-agreety-session)})
- Can be either instance of @code{greetd-agreety-session} configuration or
- @code{gexp->script} like object to use as greeter.
- @end table
- @end deftp
- @deftp {Data Type} greetd-agreety-session
- Configuration record for the agreety greetd greeter.
- @table @asis
- @item @code{agreety} (default: @code{greetd})
- The package with @command{/bin/agreety} command.
- @item @code{command} (default: @code{(file-append bash "/bin/bash")})
- Command to be started by @command{/bin/agreety} on successful login.
- @item @code{command-args} (default: @code{'("-l")})
- Command arguments to pass to command.
- @item @code{extra-env} (default: @code{'()})
- Extra environment variables to set on login.
- @item @code{xdg-env?} (default: @code{#t})
- If true @code{XDG_RUNTIME_DIR} and @code{XDG_SESSION_TYPE} will be set
- before starting command. One should note that, @code{extra-env} variables
- are set right after mentioned variables, so that they can be overridden.
- @end table
- @end deftp
- @deftp {Data Type} greetd-wlgreet-session
- Generic configuration record for the wlgreet greetd greeter.
- @table @asis
- @item @code{wlgreet} (default: @code{wlgreet})
- The package with the @command{/bin/wlgreet} command.
- @item @code{command} (default: @code{(file-append sway "/bin/sway")})
- Command to be started by @command{/bin/wlgreet} on successful login.
- @item @code{command-args} (default: @code{'()})
- Command arguments to pass to command.
- @item @code{output-mode} (default: @code{"all"})
- Option to use for @code{outputMode} in the TOML configuration file.
- @item @code{scale} (default: @code{1})
- Option to use for @code{scale} in the TOML configuration file.
- @item @code{background} (default: @code{'(0 0 0 0.9)})
- RGBA list to use as the background colour of the login prompt.
- @item @code{headline} (default: @code{'(1 1 1 1)})
- RGBA list to use as the headline colour of the UI popup.
- @item @code{prompt} (default: @code{'(1 1 1 1)})
- RGBA list to use as the prompt colour of the UI popup.
- @item @code{prompt-error} (default: @code{'(1 1 1 1)})
- RGBA list to use as the error colour of the UI popup.
- @item @code{border} (default: @code{'(1 1 1 1)})
- RGBA list to use as the border colour of the UI popup.
- @item @code{extra-env} (default: @code{'()})
- Extra environment variables to set on login.
- @end table
- @end deftp
- @deftp {Data Type} greetd-wlgreet-sway-session
- Sway-specific configuration record for the wlgreet greetd greeter.
- @table @asis
- @item @code{wlgreet-session} (default: @code{(greetd-wlgreet-session)})
- A @code{greetd-wlgreet-session} record for generic wlgreet configuration,
- on top of the Sway-specific @code{greetd-wlgreet-sway-session}.
- @item @code{sway} (default: @code{sway})
- The package providing the @command{/bin/sway} command.
- @item @code{sway-configuration} (default: #f)
- File-like object providing an additional Sway configuration file to be
- prepended to the mandatory part of the configuration.
- @end table
- Here is an example of a greetd configuration that uses wlgreet and Sway:
- @lisp
- (greetd-configuration
- ;; We need to give the greeter user these permissions, otherwise
- ;; Sway will crash on launch.
- (greeter-supplementary-groups (list "video" "input" "seat"))
- (terminals
- (list (greetd-terminal-configuration
- (terminal-vt "1")
- (terminal-switch #t)
- (default-session-command
- (greetd-wlgreet-sway-session
- (sway-configuration
- (local-file "sway-greetd.conf"))))))))
- @end lisp
- @end deftp
- @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 ()
- (system* (string-append #$findutils "/bin/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
- @quotation Tip
- Avoid calling the Guile procedures @code{execl}, @code{execle} or
- @code{execlp} inside a job specification, else mcron won't be able to
- output the completion status of the job.
- @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
- @defvar mcron-service-type
- This is the type of the @code{mcron} service, whose value is an
- @code{mcron-configuration} object.
- This service type can be the target of a service extension that provides
- additional job specifications (@pxref{Service Composition}). In other
- words, it is possible to define services that provide additional mcron
- jobs to run.
- @end defvar
- @c Generated via (generate-documentation) at the bottom of (gnu services
- @c mcron).
- @c %start of fragment
- @deftp {Data Type} mcron-configuration
- Available @code{mcron-configuration} fields are:
- @table @asis
- @item @code{mcron} (default: @code{mcron}) (type: file-like)
- The mcron package to use.
- @item @code{jobs} (default: @code{'()}) (type: list-of-gexps)
- 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}).
- @item @code{log?} (default: @code{#t}) (type: boolean)
- Log messages to standard output.
- @item @code{log-file} (default: @code{"/var/log/mcron.log"}) (type: string)
- Log file location.
- @item @code{log-format} (default: @code{"~1@@*~a ~a: ~a~%"}) (type: string)
- @code{(ice-9 format)} format string for log messages. The default value
- produces messages like @samp{@var{pid} @var{name}: @var{message}}
- (@pxref{Invoking mcron, Invoking,, mcron,GNU@tie{}mcron}). Each message
- is also prefixed by a timestamp by GNU Shepherd.
- @item @code{date-format} (type: maybe-string)
- @code{(srfi srfi-19)} format string for date.
- @end table
- @end deftp
- @c %end of fragment
- @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
- @defvar 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 defvar
- @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.
- @vindex %default-log-rotation-options
- @item @code{options} (default: @code{%default-log-rotation-options})
- The list of rottlog options for this rotation (@pxref{Configuration
- parameters,,, rottlog, GNU Rot[t]log 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
- @defvar %default-rotations
- Specifies weekly rotation of @code{%rotated-files} and of
- @file{/var/log/guix-daemon.log}.
- @end defvar
- @defvar %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 defvar
- Some log files just need to be deleted periodically once they are old,
- without any other criterion and without any archival step. This is the
- case of build logs stored by @command{guix-daemon} under
- @file{/var/log/guix/drvs} (@pxref{Invoking guix-daemon}). The
- @code{log-cleanup} service addresses this use case. For example,
- @code{%base-services} (@pxref{Base Services}) includes the following:
- @lisp
- ;; Periodically delete old build logs.
- (service log-cleanup-service-type
- (log-cleanup-configuration
- (directory "/var/log/guix/drvs")))
- @end lisp
- That ensures build logs do not accumulate endlessly.
- @defvar log-cleanup-service-type
- This is the type of the service to delete old logs. Its value must be a
- @code{log-cleanup-configuration} record as described below.
- @end defvar
- @deftp {Data Type} log-cleanup-configuration
- Data type representing the log cleanup configuration
- @table @asis
- @item @code{directory}
- Name of the directory containing log files.
- @item @code{expiry} (default: @code{(* 6 30 24 3600)})
- Age in seconds after which a file is subject to deletion (six months by
- default).
- @item @code{schedule} (default: @code{"30 12 01,08,15,22 * *"})
- String or gexp denoting the corresponding mcron job schedule
- (@pxref{Scheduled Job Execution}).
- @end table
- @end deftp
- @cindex logging, anonymization
- @subheading Anonip Service
- Anonip is a privacy filter that removes IP address from web server logs.
- This service creates a FIFO and filters any written lines with anonip
- before writing the filtered log to a target file.
- The following example sets up the FIFO
- @file{/var/run/anonip/https.access.log} and writes the filtered log file
- @file{/var/log/anonip/https.access.log}.
- @lisp
- (service anonip-service-type
- (anonip-configuration
- (input "/var/run/anonip/https.access.log")
- (output "/var/log/anonip/https.access.log")))
- @end lisp
- Configure your web server to write its logs to the FIFO at
- @file{/var/run/anonip/https.access.log} and collect the anonymized log
- file at @file{/var/web-logs/https.access.log}.
- @deftp {Data Type} anonip-configuration
- This data type represents the configuration of anonip.
- It has the following parameters:
- @table @asis
- @item @code{anonip} (default: @code{anonip})
- The anonip package to use.
- @item @code{input}
- The file name of the input log file to process. The service creates a
- FIFO of this name. The web server should write its logs to this FIFO.
- @item @code{output}
- The file name of the processed log file.
- @end table
- The following optional settings may be provided:
- @table @asis
- @item @code{skip-private?}
- When @code{#true} do not mask addresses in private ranges.
- @item @code{column}
- A 1-based indexed column number. Assume IP address is in the specified
- column (default is 1).
- @item @code{replacement}
- Replacement string in case address parsing fails, e.g. @code{"0.0.0.0"}.
- @item @code{ipv4mask}
- Number of bits to mask in IPv4 addresses.
- @item @code{ipv6mask}
- Number of bits to mask in IPv6 addresses.
- @item @code{increment}
- Increment the IP address by the given number. By default this is zero.
- @item @code{delimiter}
- Log delimiter string.
- @item @code{regex}
- Regular expression for detecting IP addresses. Use this instead of @code{column}.
- @end table
- @end deftp
- @node Networking Setup
- @subsection Networking Setup
- The @code{(gnu services networking)} module provides services to
- configure network interfaces and set up networking on your machine.
- Those services provide different ways for you to set up your machine: by
- declaring a static network configuration, by running a Dynamic Host
- Configuration Protocol (DHCP) client, or by running daemons such as
- NetworkManager and Connman that automate the whole process,
- automatically adapt to connectivity changes, and provide a high-level
- user interface.
- On a laptop, NetworkManager and Connman are by far the most convenient
- options, which is why the default desktop services include
- NetworkManager (@pxref{Desktop Services, @code{%desktop-services}}).
- For a server, or for a virtual machine or a container, static network
- configuration or a simple DHCP client are often more appropriate.
- This section describes the various network setup services available,
- starting with static network configuration.
- @defvar static-networking-service-type
- This is the type for statically-configured network interfaces. Its
- value must be a list of @code{static-networking} records. Each of them
- declares a set of @dfn{addresses}, @dfn{routes}, and @dfn{links}, as
- shown below.
- @cindex network interface controller (NIC)
- @cindex NIC, networking interface controller
- Here is the simplest configuration, with only one network interface
- controller (NIC) and only IPv4 connectivity:
- @lisp
- ;; Static networking for one NIC, IPv4-only.
- (service static-networking-service-type
- (list (static-networking
- (addresses
- (list (network-address
- (device "eno1")
- (value "10.0.2.15/24"))))
- (routes
- (list (network-route
- (destination "default")
- (gateway "10.0.2.2"))))
- (name-servers '("10.0.2.3")))))
- @end lisp
- The snippet above can be added to the @code{services} field of your
- operating system configuration (@pxref{Using the Configuration System}).
- It will configure your machine to have 10.0.2.15 as its IP address, with
- a 24-bit netmask for the local network---meaning that any 10.0.2.@var{x}
- address is on the local area network (LAN). Traffic to addresses
- outside the local network is routed @i{via} 10.0.2.2. Host names are
- resolved by sending domain name system (DNS) queries to 10.0.2.3.
- @end defvar
- @deftp {Data Type} static-networking
- This is the data type representing a static network configuration.
- As an example, here is how you would declare the configuration of a
- machine with a single network interface controller (NIC) available as
- @code{eno1}, and with one IPv4 and one IPv6 address:
- @lisp
- ;; Network configuration for one NIC, IPv4 + IPv6.
- (static-networking
- (addresses (list (network-address
- (device "eno1")
- (value "10.0.2.15/24"))
- (network-address
- (device "eno1")
- (value "2001:123:4567:101::1/64"))))
- (routes (list (network-route
- (destination "default")
- (gateway "10.0.2.2"))
- (network-route
- (destination "default")
- (gateway "2020:321:4567:42::1"))))
- (name-servers '("10.0.2.3")))
- @end lisp
- If you are familiar with the @command{ip} command of the
- @uref{https://wiki.linuxfoundation.org/networking/iproute2,
- @code{iproute2} package} found on Linux-based systems, the declaration
- above is equivalent to typing:
- @example
- ip address add 10.0.2.15/24 dev eno1
- ip address add 2001:123:4567:101::1/64 dev eno1
- ip route add default via inet 10.0.2.2
- ip route add default via inet6 2020:321:4567:42::1
- @end example
- Run @command{man 8 ip} for more info. Venerable GNU/Linux users will
- certainly know how to do it with @command{ifconfig} and @command{route},
- but we'll spare you that.
- The available fields of this data type are as follows:
- @table @asis
- @item @code{addresses}
- @itemx @code{links} (default: @code{'()})
- @itemx @code{routes} (default: @code{'()})
- The list of @code{network-address}, @code{network-link}, and
- @code{network-route} records for this network (see below).
- @item @code{name-servers} (default: @code{'()})
- The list of IP addresses (strings) of domain name servers. These IP
- addresses go to @file{/etc/resolv.conf}.
- @item @code{provision} (default: @code{'(networking)})
- If true, this should be a list of symbols for the Shepherd service
- corresponding to this network configuration.
- @item @code{requirement} (default @code{'()})
- The list of Shepherd services depended on.
- @end table
- @end deftp
- @deftp {Data Type} network-address
- This is the data type representing the IP address of a network
- interface.
- @table @code
- @item device
- The name of the network interface for this address---e.g.,
- @code{"eno1"}.
- @item value
- The actual IP address and network mask, in
- @uref{https://en.wikipedia.org/wiki/CIDR#CIDR_notation, @acronym{CIDR,
- Classless Inter-Domain Routing} notation}, as a string.
- For example, @code{"10.0.2.15/24"} denotes IPv4 address 10.0.2.15 on a
- 24-bit sub-network---all 10.0.2.@var{x} addresses are on the same local
- network.
- @item ipv6?
- Whether @code{value} denotes an IPv6 address. By default this is
- automatically determined.
- @end table
- @end deftp
- @deftp {Data Type} network-route
- This is the data type representing a network route.
- @table @asis
- @item @code{destination}
- The route destination (a string), either an IP address and network mask
- or @code{"default"} to denote the default route.
- @item @code{source} (default: @code{#f})
- The route source.
- @item @code{device} (default: @code{#f})
- The device used for this route---e.g., @code{"eno2"}.
- @item @code{ipv6?} (default: auto)
- Whether this is an IPv6 route. By default this is automatically
- determined based on @code{destination} or @code{gateway}.
- @item @code{gateway} (default: @code{#f})
- IP address (a string) through which traffic is routed.
- @end table
- @end deftp
- @deftp {Data Type} network-link
- Data type for a network link (@pxref{Link,,, guile-netlink,
- Guile-Netlink Manual}).
- @table @code
- @item name
- The name of the link---e.g., @code{"v0p0"}.
- @item type
- A symbol denoting the type of the link---e.g., @code{'veth}.
- @item arguments
- List of arguments for this type of link.
- @end table
- @end deftp
- @cindex loopback device
- @defvar %loopback-static-networking
- This is the @code{static-networking} record representing the ``loopback
- device'', @code{lo}, for IP addresses 127.0.0.1 and ::1, and providing
- the @code{loopback} Shepherd service.
- @end defvar
- @cindex networking, with QEMU
- @cindex QEMU, networking
- @defvar %qemu-static-networking
- This is the @code{static-networking} record representing network setup
- when using QEMU's user-mode network stack on @code{eth0} (@pxref{Using
- the user mode network stack,,, QEMU, QEMU Documentation}).
- @end defvar
- @cindex DHCP, networking service
- @defvar dhcp-client-service-type
- This is the type of services that run @var{dhcp}, a Dynamic Host Configuration
- Protocol (DHCP) client.
- @end defvar
- @deftp {Data Type} dhcp-client-configuration
- Data type representing the configuration of the DHCP client service.
- @table @asis
- @item @code{package} (default: @code{isc-dhcp})
- DHCP client package to use.
- @item @code{interfaces} (default: @code{'all})
- Either @code{'all} or the list of interface names that the DHCP client
- should listen on---e.g., @code{'("eno1")}.
- When set to @code{'all}, the DHCP client listens on all the available
- non-loopback interfaces that can be activated. Otherwise the DHCP
- client listens only on the specified interfaces.
- @item @code{shepherd-requirement} (default: @code{'()})
- @itemx @code{shepherd-provision} (default: @code{'(networking)})
- This option can be used to provide a list of symbols naming Shepherd services
- that this service will depend on, such as @code{'wpa-supplicant} or
- @code{'iwd} if you require authenticated access for encrypted WiFi or Ethernet
- networks.
- Likewise, @code{shepherd-provision} is a list of Shepherd service names
- (symbols) provided by this service. You might want to change the
- default value if you intend to run several DHCP clients, only one of
- which provides the @code{networking} Shepherd service.
- @end table
- @end deftp
- @cindex NetworkManager
- @defvar 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 defvar
- @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{shepherd-requirement} (default: @code{'(wpa-supplicant)})
- This option can be used to provide a list of symbols naming Shepherd services
- that this service will depend on, such as @code{'wpa-supplicant} or
- @code{'iwd} if you require authenticated access for encrypted WiFi or Ethernet
- networks.
- @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
- @defvar 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 defvar
- @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{shepherd-requirement} (default: @code{'()})
- This option can be used to provide a list of symbols naming Shepherd services
- that this service will depend on, such as @code{'wpa-supplicant} or
- @code{'iwd} if you require authenticated access for encrypted WiFi or Ethernet
- networks.
- @item @code{disable-vpn?} (default: @code{#f})
- When true, disable connman's vpn plugin.
- @end table
- @end deftp
- @cindex WPA Supplicant
- @defvar 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 defvar
- @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 ModemManager
- Some networking devices such as modems require special care, and this is
- what the services below focus on.
- @defvar 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 defvar
- @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
- @defvar 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 defvar
- @deftp {Data Type} usb-modeswitch-configuration
- Data type representing the configuration of USB_ModeSwitch.
- @table @asis
- @item @code{usb-modeswitch} (default: @code{usb-modeswitch})
- The USB_ModeSwitch package providing the binaries for modeswitching.
- @item @code{usb-modeswitch-data} (default: @code{usb-modeswitch-data})
- The package providing the device data and udev rules file used by
- USB_ModeSwitch.
- @item @code{config-file} (default: @code{#~(string-append #$usb-modeswitch:dispatcher "/etc/usb_modeswitch.conf")})
- Which config file to use for the USB_ModeSwitch dispatcher. By default the
- config file shipped with USB_ModeSwitch is used which disables logging to
- @file{/var/log} among other default settings. If set to @code{#f}, no config
- file is used.
- @end table
- @end deftp
- @node Networking Services
- @subsection Networking Services
- The @code{(gnu services networking)} module discussed in the previous
- section provides services for more advanced setups: providing a DHCP
- service for others to use, filtering packets with iptables or nftables,
- running a WiFi access point with @command{hostapd}, running the
- @command{inetd} ``superdaemon'', and more. This section describes
- those.
- @defvar 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 defvar
- @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/dhcp/, ISC's DHCP server}.
- @item @code{config-file} (default: @code{#f})
- The configuration file to use. This is required. It will be passed to
- @code{dhcpd} via its @code{-cf} option. This may be any ``file-like''
- object (@pxref{G-Expressions, file-like objects}). See @code{man
- dhcpd.conf} for details on the configuration file syntax.
- @item @code{version} (default: @code{"4"})
- The DHCP version to use. The ISC DHCP server supports the values ``4'',
- ``6'', and ``4o6''. These correspond to the @code{dhcpd} program
- options @code{-4}, @code{-6}, and @code{-4o6}. See @code{man dhcpd} for
- details.
- @item @code{run-directory} (default: @code{"/run/dhcpd"})
- The run directory to use. At service activation time, this directory
- will be created if it does not exist.
- @item @code{pid-file} (default: @code{"/run/dhcpd/dhcpd.pid"})
- The PID file to use. This corresponds to the @code{-pf} option of
- @code{dhcpd}. See @code{man dhcpd} for details.
- @item @code{interfaces} (default: @code{'()})
- The names of the network interfaces on which dhcpd should listen for
- broadcasts. If this list is not empty, then its elements (which must be
- strings) will be appended to the @code{dhcpd} invocation when starting
- the daemon. It may not be necessary to explicitly specify any
- interfaces here; see @code{man dhcpd} for details.
- @end table
- @end deftp
- @cindex hostapd service, for Wi-Fi access points
- @cindex Wi-Fi access points, hostapd service
- @defvar 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 defvar
- @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
- @defvar 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 defvar
- @cindex iptables
- @defvar 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 defvar
- @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
- @defvar 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 defvar
- @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
- @defvar 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 defvar
- @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
- @defvar %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 defvar
- @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
- @defvar 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 defvar
- @defvar %openntpd-servers
- This variable is a list of the server addresses defined in
- @code{%ntp-servers}.
- @end defvar
- @deftp {Data Type} openntpd-configuration
- @table @asis
- @item @code{openntpd} (default: @code{openntpd})
- The openntpd package 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
- @defvar 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 defvar
- @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
- @defvar 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 defvar
- @c The fields documentation has been auto-generated using the
- @c configuration->documentation procedure from
- @c (gnu services configuration).
- @deftp {Data Type} opendht-configuration
- Available @code{opendht-configuration} fields are:
- @table @asis
- @item @code{opendht} (default: @code{opendht}) (type: file-like)
- The @code{opendht} package to use.
- @item @code{peer-discovery?} (default: @code{#f}) (type: boolean)
- Whether to enable the multicast local peer discovery mechanism.
- @item @code{enable-logging?} (default: @code{#f}) (type: boolean)
- Whether to enable logging messages to syslog. It is disabled by default
- as it is rather verbose.
- @item @code{debug?} (default: @code{#f}) (type: boolean)
- Whether to enable debug-level logging messages. This has no effect if
- logging is disabled.
- @item @code{bootstrap-host} (default: @code{"bootstrap.jami.net:4222"}) (type: maybe-string)
- 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
- bootstrapping by explicitly setting this field to the
- @code{%unset-value} value.
- @item @code{port} (default: @code{4222}) (type: maybe-number)
- The UDP port to bind to. When left unspecified, an available port is
- automatically selected.
- @item @code{proxy-server-port} (type: maybe-number)
- Spawn a proxy server listening on the specified port.
- @item @code{proxy-server-port-tls} (type: maybe-number)
- Spawn a proxy server listening to TLS connections on the specified port.
- @end table
- @end deftp
- @cindex Tor
- @defvar tor-service-type
- 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.
- @cindex onion services, for Tor
- Services of this type can be extended by other services to specify
- @dfn{onion services} (in addition to those already specified in
- @code{tor-configuration}) as in this example:
- @lisp
- (simple-service 'my-extra-onion-service tor-service-type
- (list (tor-onion-service-configuration
- (name "extra-onion-service")
- (mapping '((80 . "127.0.0.1:8080"))))))
- @end lisp
- @end defvar
- @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{<tor-onion-service-configuration>} records to use.
- For any onion service you include in this list, appropriate
- configuration to enable the onion service will be automatically added to
- the default configuration file.
- @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 onion service, tor
- @deftp {Data Type} tor-onion-service-configuration
- Data Type representing a Tor @dfn{Onion Service} configuration.
- See @url{https://community.torproject.org/onion-services/, the Tor
- project's documentation} for more information.
- Available @code{tor-onion-service-configuration} fields are:
- @table @asis
- @item @code{name} (type: string)
- Name for this Onion Service. This creates a
- @file{/var/lib/tor/hidden-services/@var{name}} directory, where the
- @file{hostname} file contains the @indicateurl{.onion} host name for this Onion
- Service.
- @item @code{mapping} (type: alist)
- Association list of port to address mappings. The following example:
- @lisp
- '((22 . "127.0.0.1:22")
- (80 . "127.0.0.1:8080"))
- @end lisp
- maps ports 22 and 80 of the Onion Service to the local ports 22 and 8080.
- @end table
- @end deftp
- 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.
- @defvar rsync-service-type
- This is the service type for the @uref{https://rsync.samba.org, rsync} daemon,
- The value for this service type is a
- @command{rsync-configuration} record as in this example:
- @lisp
- ;; Export two directories over rsync. By default rsync listens on
- ;; all the network interfaces.
- (service rsync-service-type
- (rsync-configuration
- (modules (list (rsync-module
- (name "music")
- (file-name "/srv/zik")
- (read-only? #f))
- (rsync-module
- (name "movies")
- (file-name "/home/charlie/movies"))))))
- @end lisp
- See below for details about @code{rsync-configuration}.
- @end defvar
- @deftp {Data Type} rsync-configuration
- Data type representing the configuration for @code{rsync-service}.
- @table @asis
- @item @code{package} (default: @var{rsync})
- @code{rsync} package to use.
- @item @code{address} (default: @code{#f})
- IP address on which @command{rsync} listens for incoming connections.
- If unspecified, it defaults to listening on all available addresses.
- @item @code{port-number} (default: @code{873})
- TCP port on which @command{rsync} listens for incoming connections. If port
- is less than @code{1024} @command{rsync} needs to be started as the
- @code{root} user and group.
- @item @code{pid-file} (default: @code{"/var/run/rsyncd/rsyncd.pid"})
- Name of the file where @command{rsync} writes its PID.
- @item @code{lock-file} (default: @code{"/var/run/rsyncd/rsyncd.lock"})
- Name of the file where @command{rsync} writes its lock file.
- @item @code{log-file} (default: @code{"/var/log/rsyncd.log"})
- Name of the file where @command{rsync} writes its log file.
- @item @code{user} (default: @code{"root"})
- Owner of the @code{rsync} process.
- @item @code{group} (default: @code{"root"})
- Group of the @code{rsync} process.
- @item @code{uid} (default: @code{"rsyncd"})
- User name or user ID that file transfers to and from that module should take
- place as when the daemon was run as @code{root}.
- @item @code{gid} (default: @code{"rsyncd"})
- Group name or group ID that will be used when accessing the module.
- @item @code{modules} (default: @code{%default-modules})
- List of ``modules''---i.e., directories exported over rsync. Each
- element must be a @code{rsync-module} record, as described below.
- @end table
- @end deftp
- @deftp {Data Type} rsync-module
- This is the data type for rsync ``modules''. A module is a directory
- exported over the rsync protocol. The available fields are as follows:
- @table @asis
- @item @code{name}
- The module name. This is the name that shows up in URLs. For example,
- if the module is called @code{music}, the corresponding URL will be
- @code{rsync://host.example.org/music}.
- @item @code{file-name}
- Name of the directory being exported.
- @item @code{comment} (default: @code{""})
- Comment associated with the module. Client user interfaces may display
- it when they obtain the list of available modules.
- @item @code{read-only?} (default: @code{#t})
- Whether or not client will be able to upload files. If this is false,
- the uploads will be authorized if permissions on the daemon side permit
- it.
- @item @code{chroot?} (default: @code{#t})
- When this is true, the rsync daemon changes root to the module's
- directory before starting file transfers with the client. This improves
- security, but requires rsync to run as root.
- @item @code{timeout} (default: @code{300})
- Idle time in seconds after which the daemon closes a connection with the
- client.
- @end table
- @end deftp
- @cindex Syncthing, file synchronization service
- @cindex backup service, Syncthing
- 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.
- @defvar 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
- @quotation Note
- This service is also available for Guix Home, where it runs directly
- with your user privileges (@pxref{Networking Home Services,
- @code{home-syncthing-service-type}}).
- @end quotation
- See below for details about @code{syncthing-configuration}.
- @end defvar
- @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
- Furthermore, @code{(gnu services ssh)} provides the following services.
- @cindex SSH
- @cindex SSH server
- @defvar lsh-service-type
- Type of the service that runs the GNU@tie{}lsh secure shell (SSH)
- daemon, @command{lshd}. The value for this service is a
- @code{<lsh-configuration>} object.
- @end defvar
- @deftp {Data Type} lsh-configuration
- Data type representing the configuration of @command{lshd}.
- @table @asis
- @item @code{lsh} (default: @code{lsh}) (type: file-like)
- The package object of the GNU@tie{}lsh secure shell (SSH) daemon.
- @item @code{daemonic?} (default: @code{#t}) (type: boolean)
- Whether to detach from the controlling terminal.
- @item @code{host-key} (default: @code{"/etc/lsh/host-key"}) (type: string)
- File containing the @dfn{host key}. This file must be readable by
- root only.
- @item @code{interfaces} (default: @code{'()}) (type: list)
- List of host names or addresses that @command{lshd} will listen on.
- If empty, @command{lshd} listens for connections on all the network
- interfaces.
- @item @code{port-number} (default: @code{22}) (type: integer)
- Port to listen on.
- @item @code{allow-empty-passwords?} (default: @code{#f}) (type: boolean)
- Whether to accept log-ins with empty passwords.
- @item @code{root-login?} (default: @code{#f}) (type: boolean)
- Whether to accept log-ins as root.
- @item @code{syslog-output?} (default: @code{#t}) (type: boolean)
- Whether to log @command{lshd} standard output to syslogd.
- This will make the service depend on the existence of a syslogd service.
- @item @code{pid-file?} (default: @code{#f}) (type: boolean)
- When @code{#t}, @command{lshd} writes its PID to the file specified in
- @var{pid-file}.
- @item @code{pid-file} (default: @code{"/var/run/lshd.pid"}) (type: string)
- File that @command{lshd} will write its PID to.
- @item @code{x11-forwarding?} (default: @code{#t}) (type: boolean)
- Whether to enable X11 forwarding.
- @item @code{tcp/ip-forwarding?} (default: @code{#t}) (type: boolean)
- Whether to enable TCP/IP forwarding.
- @item @code{password-authentication?} (default: @code{#t}) (type: boolean)
- Whether to accept log-ins using password authentication.
- @item @code{public-key-authentication?} (default: @code{#t}) (type: boolean)
- Whether to accept log-ins using public key authentication.
- @item @code{initialize?} (default: @code{#t}) (type: boolean)
- When @code{#f}, 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}).
- @end table
- @end deftp
- @cindex SSH
- @cindex SSH server
- @defvar 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 defvar
- @deftp {Data Type} openssh-configuration
- This is the configuration record for OpenSSH's @command{sshd}.
- @table @asis
- @item @code{openssh} (default @var{openssh})
- The OpenSSH package to use.
- @item @code{pid-file} (default: @code{"/var/run/sshd.pid"})
- Name of the file where @command{sshd} writes its PID.
- @item @code{port-number} (default: @code{22})
- TCP port on which @command{sshd} listens for incoming connections.
- @item @code{max-connections} (default: @code{200})
- Hard limit on the maximum number of simultaneous client connections,
- enforced by the inetd-style Shepherd service (@pxref{Service De- and
- Constructors, @code{make-inetd-constructor},, shepherd, The GNU Shepherd
- Manual}).
- @item @code{permit-root-login} (default: @code{#f})
- This field determines whether and when to allow logins as root. If
- @code{#f}, root logins are disallowed; if @code{#t}, they are allowed.
- If it's the symbol @code{'prohibit-password}, then root logins are
- permitted but not with password-based authentication.
- @item @code{allow-empty-passwords?} (default: @code{#f})
- When true, users with empty passwords may log in. When false, they may
- not.
- @item @code{password-authentication?} (default: @code{#t})
- When true, users may log in with their password. When false, they have
- other authentication methods.
- @item @code{public-key-authentication?} (default: @code{#t})
- When true, users may log in using public key authentication. When
- false, users have to use other authentication method.
- Authorized public keys are stored in @file{~/.ssh/authorized_keys}.
- This is used only by protocol version 2.
- @item @code{x11-forwarding?} (default: @code{#f})
- When true, forwarding of X11 graphical client connections is
- enabled---in other words, @command{ssh} options @option{-X} and
- @option{-Y} will work.
- @item @code{allow-agent-forwarding?} (default: @code{#t})
- Whether to allow agent forwarding.
- @item @code{allow-tcp-forwarding?} (default: @code{#t})
- Whether to allow TCP forwarding.
- @item @code{gateway-ports?} (default: @code{#f})
- Whether to allow gateway ports.
- @item @code{challenge-response-authentication?} (default: @code{#f})
- Specifies whether challenge response authentication is allowed (e.g.@: via
- PAM).
- @item @code{use-pam?} (default: @code{#t})
- Enables the Pluggable Authentication Module interface. If set to
- @code{#t}, this will enable PAM authentication using
- @code{challenge-response-authentication?} and
- @code{password-authentication?}, in addition to PAM account and session
- module processing for all authentication types.
- Because PAM challenge response authentication usually serves an
- equivalent role to password authentication, you should disable either
- @code{challenge-response-authentication?} or
- @code{password-authentication?}.
- @item @code{print-last-log?} (default: @code{#t})
- Specifies whether @command{sshd} should print the date and time of the
- last user login when a user logs in interactively.
- @item @code{subsystems} (default: @code{'(("sftp" "internal-sftp"))})
- Configures external subsystems (e.g.@: file transfer daemon).
- This is a list of two-element lists, each of which containing the
- subsystem name and a command (with optional arguments) to execute upon
- subsystem request.
- The command @command{internal-sftp} implements an in-process SFTP
- server. Alternatively, one can specify the @command{sftp-server} command:
- @lisp
- (service openssh-service-type
- (openssh-configuration
- (subsystems
- `(("sftp" ,(file-append openssh "/libexec/sftp-server"))))))
- @end lisp
- @item @code{accepted-environment} (default: @code{'()})
- List of strings describing which environment variables may be exported.
- Each string gets on its own line. See the @code{AcceptEnv} option in
- @code{man sshd_config}.
- This example allows ssh-clients to export the @env{COLORTERM} variable.
- It is set by terminal emulators, which support colors. You can use it in
- your shell's resource file to enable colors for the prompt and commands
- if this variable is set.
- @lisp
- (service openssh-service-type
- (openssh-configuration
- (accepted-environment '("COLORTERM"))))
- @end lisp
- @item @code{authorized-keys} (default: @code{'()})
- @cindex authorized keys, SSH
- @cindex SSH authorized keys
- This is the list of authorized keys. Each element of the list is a user
- name followed by one or more file-like objects that represent SSH public
- keys. For example:
- @lisp
- (openssh-configuration
- (authorized-keys
- `(("rekado" ,(local-file "rekado.pub"))
- ("chris" ,(local-file "chris.pub"))
- ("root" ,(local-file "rekado.pub") ,(local-file "chris.pub")))))
- @end lisp
- @noindent
- registers the specified public keys for user accounts @code{rekado},
- @code{chris}, and @code{root}.
- Additional authorized keys can be specified @i{via}
- @code{service-extension}.
- Note that this does @emph{not} interfere with the use of
- @file{~/.ssh/authorized_keys}.
- @item @code{generate-host-keys?} (default: @code{#t})
- Whether to generate host key pairs with @command{ssh-keygen -A} under
- @file{/etc/ssh} if there are none.
- Generating key pairs takes a few seconds when enough entropy is
- available and is only done once. You might want to turn it off for
- instance in a virtual machine that does not need it because host keys
- are provided in some other way, and where the extra boot time is a
- problem.
- @item @code{log-level} (default: @code{'info})
- This is a symbol specifying the logging level: @code{quiet}, @code{fatal},
- @code{error}, @code{info}, @code{verbose}, @code{debug}, etc. See the man
- page for @file{sshd_config} for the full list of level names.
- @item @code{extra-content} (default: @code{""})
- This field can be used to append arbitrary text to the configuration file. It
- is especially useful for elaborate configurations that cannot be expressed
- otherwise. This configuration, for example, would generally disable root
- logins, but permit them from one specific IP address:
- @lisp
- (openssh-configuration
- (extra-content "\
- Match Address 192.168.0.1
- PermitRootLogin yes"))
- @end lisp
- @end table
- @end deftp
- @defvar dropbear-service-type
- Type of the service that runs the
- @url{https://matt.ucc.asn.au/dropbear/dropbear.html, Dropbear SSH daemon},
- whose value is a @code{<dropbear-configuration>} object.
- For example, to specify a Dropbear service listening on port 1234:
- @lisp
- (service dropbear-service-type (dropbear-configuration
- (port-number 1234)))
- @end lisp
- @end defvar
- @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
- @defvar 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 defvar
- @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
- @defvar 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 defvar
- @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
- @defvar block-facebook-hosts-service-type
- This service type adds a list of known Facebook hosts to the
- @file{/etc/hosts} file.
- (@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 mechanism can prevent programs running locally, such as Web
- browsers, from accessing Facebook.
- @end defvar
- The @code{(gnu services avahi)} provides the following definition.
- @defvar 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 defvar
- @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
- @defvar 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 defvar
- @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
- @defvar 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 defvar
- @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
- @defvar yggdrasil-service-type
- The service type for connecting to the @uref{https://yggdrasil-network.github.io/,
- Yggdrasil network}, an early-stage implementation of a fully end-to-end
- encrypted IPv6 network.
- @quotation
- Yggdrasil provides name-independent routing with cryptographically generated
- addresses. Static addressing means you can keep the same address as long as
- you want, even if you move to a new location, or generate a new address (by
- generating new keys) whenever you want.
- @uref{https://yggdrasil-network.github.io/2018/07/28/addressing.html}
- @end quotation
- Pass it a value of @code{yggdrasil-configuration} to connect it to public
- peers and/or local peers.
- Here is an example using public peers and a static address. The static
- signing and encryption keys are defined in @file{/etc/yggdrasil-private.conf}
- (the default value for @code{config-file}).
- @lisp
- ;; part of the operating-system declaration
- (service yggdrasil-service-type
- (yggdrasil-configuration
- (autoconf? #f) ;; use only the public peers
- (json-config
- ;; choose one from
- ;; https://github.com/yggdrasil-network/public-peers
- '((peers . #("tcp://1.2.3.4:1337"))))
- ;; /etc/yggdrasil-private.conf is the default value for config-file
- ))
- @end lisp
- @example
- # sample content for /etc/yggdrasil-private.conf
- @{
- # Your public key. Your peers may ask you for this to put
- # into their AllowedPublicKeys configuration.
- PublicKey: 64277...
- # Your private key. DO NOT share this with anyone!
- PrivateKey: 5c750...
- @}
- @end example
- @end defvar
- @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
- @defvar 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 defvar
- @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
- @defvar 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 defvar
- @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).
- @defvar 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 defvar
- @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{operating-system-expression} (default: @code{#f})
- This field specifies an expression that evaluates to the operating
- system to use for the upgrade. If no value is provided the
- @code{operating-system-file} field value is used.
- @lisp
- (unattended-upgrade-configuration
- (operating-system-expression
- #~(@@ (guix system install) installation-os)))
- @end lisp
- @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
- @anchor{gdm}
- 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}.
- @defvar 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 defvar
- @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{auto-suspend?} (default @code{#t})
- When true, GDM will automatically suspend to RAM when nobody is
- physically connected. When a machine is used via remote desktop or SSH,
- this should be set to false to avoid GDM interrupting remote sessions or
- rendering the machine unavailable.
- @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{x-session} (default: @code{(xinitrc)})
- Script to run before starting a X session.
- @item @code{xdmcp?} (default: @code{#f})
- When true, enable the X Display Manager Control Protocol (XDMCP). This
- should only be enabled in trusted environments, as the protocol is not
- secure. When enabled, GDM listens for XDMCP queries on the UDP port
- 177.
- @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
- @defvar slim-service-type
- This is the type for the SLiM graphical login manager for X11.
- Like GDM, SLiM looks for session types described by @file{.desktop} files and
- allows users to choose a session from the log-in screen using @kbd{F1}. It
- also honors @file{~/.xsession} files.
- Unlike GDM, SLiM does not spawn the user session on a different VT after
- logging in, which means that you can only start one graphical session. If you
- want to be able to run multiple graphical sessions at the same time you have
- to add multiple SLiM services to your system services. The following example
- shows how to replace the default GDM service with two SLiM services on tty7
- and tty8.
- @lisp
- (use-modules (gnu services)
- (gnu services desktop)
- (gnu services xorg))
- (operating-system
- ;; ...
- (services (cons* (service slim-service-type (slim-configuration
- (display ":0")
- (vt "vt7")))
- (service slim-service-type (slim-configuration
- (display ":1")
- (vt "vt8")))
- (modify-services %desktop-services
- (delete gdm-service-type)))))
- @end lisp
- @end defvar
- @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
- @defvar %default-theme
- @defvarx %default-theme-name
- The default SLiM theme and its name.
- @end defvar
- @cindex login manager
- @cindex X11 login
- @defvar 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 defvar
- @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: "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-append #$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 account that will be automatically logged in.
- Setting this to the empty string disables auto-login.
- @item @code{auto-login-session} (default "")
- The @file{.desktop} file name to use as the auto-login session, or the empty string.
- @item @code{relogin?} (default #f)
- Relogin after logout.
- @end table
- @end deftp
- @cindex lightdm, graphical login manager
- @cindex display manager, lightdm
- @anchor{lightdm}
- @defvar lightdm-service-type
- This is the type of the service to run the
- @url{https://github.com/canonical/lightdm,LightDM display manager}. Its
- value must be a @code{lightdm-configuration} record, which is documented
- below. Among its distinguishing features are TigerVNC integration for
- easily remoting your desktop as well as support for the XDMCP protocol,
- which can be used by remote clients to start a session from the login
- manager.
- In its most basic form, it can be used simply as:
- @lisp
- (service lightdm-service-type)
- @end lisp
- A more elaborate example making use of the VNC capabilities and enabling
- more features and verbose logs could look like:
- @lisp
- (service lightdm-service-type
- (lightdm-configuration
- (allow-empty-passwords? #t)
- (xdmcp? #t)
- (vnc-server? #t)
- (vnc-server-command
- (file-append tigervnc-server "/bin/Xvnc"
- " -SecurityTypes None"))
- (seats
- (list (lightdm-seat-configuration
- (name "*")
- (user-session "ratpoison"))))))
- @end lisp
- @end defvar
- @c The LightDM service documentation can be auto-generated via the
- @c 'generate-doc' procedure at the bottom of the (gnu services lightdm)
- @c module.
- @c %start of fragment
- @deftp {Data Type} lightdm-configuration
- Available @code{lightdm-configuration} fields are:
- @table @asis
- @item @code{lightdm} (default: @code{lightdm}) (type: file-like)
- The lightdm package to use.
- @item @code{allow-empty-passwords?} (default: @code{#f}) (type: boolean)
- Whether users not having a password set can login.
- @item @code{debug?} (default: @code{#f}) (type: boolean)
- Enable verbose output.
- @item @code{xorg-configuration} (type: xorg-configuration)
- The default Xorg server configuration to use to generate the Xorg server
- start script. It can be refined per seat via the @code{xserver-command}
- of the @code{<lightdm-seat-configuration>} record, if desired.
- @item @code{greeters} (type: list-of-greeter-configurations)
- The LightDM greeter configurations specifying the greeters to use.
- @item @code{seats} (type: list-of-seat-configurations)
- The seat configurations to use. A LightDM seat is akin to a user.
- @item @code{xdmcp?} (default: @code{#f}) (type: boolean)
- Whether a XDMCP server should listen on port UDP 177.
- @item @code{xdmcp-listen-address} (type: maybe-string)
- The host or IP address the XDMCP server listens for incoming
- connections. When unspecified, listen on for any hosts/IP addresses.
- @item @code{vnc-server?} (default: @code{#f}) (type: boolean)
- Whether a VNC server is started.
- @item @code{vnc-server-command} (type: file-like)
- The Xvnc command to use for the VNC server, it's possible to provide
- extra options not otherwise exposed along the command, for example to
- disable security:
- @lisp
- (vnc-server-command (file-append tigervnc-server "/bin/Xvnc"
- " -SecurityTypes None" ))
- @end lisp
- Or to set a PasswordFile for the classic (unsecure) VncAuth
- mechanism:
- @lisp
- (vnc-server-command (file-append tigervnc-server "/bin/Xvnc"
- " -PasswordFile /var/lib/lightdm/.vnc/passwd"))
- @end lisp
- The password file should be manually created using the
- @command{vncpasswd} command. Note that LightDM will create new sessions
- for VNC users, which means they need to authenticate in the same way as
- local users would.
- @item @code{vnc-server-listen-address} (type: maybe-string)
- The host or IP address the VNC server listens for incoming connections.
- When unspecified, listen for any hosts/IP addresses.
- @item @code{vnc-server-port} (default: @code{5900}) (type: number)
- The TCP port the VNC server should listen to.
- @item @code{extra-config} (default: @code{'()}) (type: list-of-strings)
- Extra configuration values to append to the LightDM configuration file.
- @end table
- @end deftp
- @c %end of fragment
- @c %start of fragment
- @deftp {Data Type} lightdm-gtk-greeter-configuration
- Available @code{lightdm-gtk-greeter-configuration} fields are:
- @table @asis
- @item @code{lightdm-gtk-greeter} (default: @code{lightdm-gtk-greeter}) (type: file-like)
- The lightdm-gtk-greeter package to use.
- @item @code{assets} (default: @code{(adwaita-icon-theme gnome-themes-extra hicolor-icon-theme)}) (type: list-of-file-likes)
- The list of packages complementing the greeter, such as package
- providing icon themes.
- @item @code{theme-name} (default: @code{"Adwaita"}) (type: string)
- The name of the theme to use.
- @item @code{icon-theme-name} (default: @code{"Adwaita"}) (type: string)
- The name of the icon theme to use.
- @item @code{cursor-theme-name} (default: @code{"Adwaita"}) (type: string)
- The name of the cursor theme to use.
- @item @code{cursor-theme-size} (default: @code{16}) (type: number)
- The size to use for the cursor theme.
- @item @code{allow-debugging?} (type: maybe-boolean)
- Set to #t to enable debug log level.
- @item @code{background} (type: file-like)
- The background image to use.
- @item @code{at-spi-enabled?} (default: @code{#f}) (type: boolean)
- Enable accessibility support through the Assistive Technology Service
- Provider Interface (AT-SPI).
- @item @code{a11y-states} (default: @code{(contrast font keyboard reader)}) (type: list-of-a11y-states)
- The accessibility features to enable, given as list of symbols.
- @item @code{reader} (type: maybe-file-like)
- The command to use to launch a screen reader.
- @item @code{extra-config} (default: @code{'()}) (type: list-of-strings)
- Extra configuration values to append to the LightDM GTK Greeter
- configuration file.
- @end table
- @end deftp
- @c %end of fragment
- @c %start of fragment
- @deftp {Data Type} lightdm-seat-configuration
- Available @code{lightdm-seat-configuration} fields are:
- @table @asis
- @item @code{name} (type: seat-name)
- The name of the seat. An asterisk (*) can be used in the name to apply
- the seat configuration to all the seat names it matches.
- @item @code{user-session} (type: maybe-string)
- The session to use by default. The session name must be provided as a
- lowercase string, such as @code{"gnome"}, @code{"ratpoison"}, etc.
- @item @code{type} (default: @code{local}) (type: seat-type)
- The type of the seat, either the @code{local} or @code{xremote} symbol.
- @item @code{autologin-user} (type: maybe-string)
- The username to automatically log in with by default.
- @item @code{greeter-session} (default: @code{lightdm-gtk-greeter}) (type: greeter-session)
- The greeter session to use, specified as a symbol. Currently, only
- @code{lightdm-gtk-greeter} is supported.
- @item @code{xserver-command} (type: maybe-file-like)
- The Xorg server command to run.
- @item @code{session-wrapper} (type: file-like)
- The xinitrc session wrapper to use.
- @item @code{extra-config} (default: @code{'()}) (type: list-of-strings)
- Extra configuration values to append to the seat configuration section.
- @end table
- @end deftp
- @c %end of fragment
- @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, LightDM or
- 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 {Procedure} set-xorg-configuration config [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 {Procedure} xorg-start-command [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
- @defvar screen-locker-service-type
- Type for a service that adds a package for a screen locker or screen
- saver to the set of setuid programs and/or add a PAM entry for it. The
- value for this service is a @code{<screen-locker-configuration>} object.
- While the default behavior is to setup both a setuid program and PAM
- entry, these two methods are redundant. Screen locker programs may not
- execute when PAM is configured and @code{setuid} is set on their
- executable. In this case, @code{using-setuid?} can be set to @code{#f}.
- For example, to make XlockMore usable:
- @lisp
- (service screen-locker-service-type
- (screen-locker-configuration
- (name "xlock")
- (program (file-append xlockmore "/bin/xlock"))))
- @end lisp
- makes the good ol' XlockMore usable.
- For example, swaylock fails to execute when compiled with PAM support
- and setuid enabled. One can thus disable setuid:
- @lisp
- (service screen-locker-service-type
- (screen-locker-configuration
- (name "swaylock")
- (program (file-append swaylock "/bin/swaylock"))
- (using-pam? #t)
- (using-setuid? #f)))
- @end lisp
- @end defvar
- @deftp {Data Type} screen-locker-configuration
- Available @code{screen-locker-configuration} fields are:
- @table @asis
- @item @code{name} (type: string)
- Name of the screen locker.
- @item @code{program} (type: file-like)
- Path to the executable for the screen locker as a G-Expression.
- @item @code{allow-empty-password?} (default: @code{#f}) (type: boolean)
- Whether to allow empty passwords.
- @item @code{using-pam?} (default: @code{#t}) (type: boolean)
- Whether to setup PAM entry.
- @item @code{using-setuid?} (default: @code{#t}) (type: boolean)
- Whether to setup program as setuid binary.
- @end table
- @end deftp
- @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:
- @defvar 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 defvar
- 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
- @quotation 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.
- @end quotation
- 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.
- The default @samp{(list "_cups" "_print" "_universal")} tells clients
- that CUPS sharing, IPP Everywhere, AirPrint, and Mopria are supported.
- @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} 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} 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 @code{max-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 @code{max-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 max-subscriptions
- Specifies the maximum number of simultaneous event subscriptions that are
- allowed. Set to @samp{0} to allow an unlimited number of subscriptions.
- Defaults to @samp{0}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} non-negative-integer max-subscriptions-per-job
- Specifies the maximum number of simultaneous event subscriptions that are
- allowed per job. A value of @samp{0} allows up to @code{max-subscriptions}
- per job.
- Defaults to @samp{0}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} non-negative-integer max-subscriptions-per-printer
- Specifies the maximum number of simultaneous event subscriptions that are
- allowed per printer. A value of @samp{0} allows up to @code{max-subscriptions}
- per printer.
- Defaults to @samp{0}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} non-negative-integer max-subscriptions-per-user
- Specifies the maximum number of simultaneous event subscriptions that are
- allowed per user. A value of @samp{0} allows up to @code{max-subscriptions}
- per user.
- Defaults to @samp{0}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} non-negative-integer multiple-operation-timeout
- Specifies the maximum amount of time to allow between files in a
- multiple file print job, in seconds.
- Defaults to @samp{900}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} 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} comma-separated-string-list-or-#f ready-paper-sizes
- Specifies a list of potential paper sizes that are reported as ready,
- that is: loaded. The actual list will contain only the sizes that each
- printer supports.
- The default value of @code{#f} is a special case: CUPS will use
- @samp{(list \"Letter\" \"Legal\" \"Tabloid\" \"4x6\" \"Env10\")}
- if the default paper size is \"Letter\", and
- @samp{(list \"A3\" \"A4\" \"A5\" \"A6\" \"EnvDL\")} otherwise.
- @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 server-admin
- Specifies the email address of the server administrator.
- Defaults to @samp{"root@@localhost.localdomain"}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} host-name-list-or-* server-alias
- The ServerAlias directive is used for HTTP Host header validation when
- clients connect to the scheduler from external interfaces. Using the
- special name @code{*} can expose your system to known browser-based DNS
- rebinding attacks, even when accessing sites through a firewall. If the
- auto-discovery of alternate names does not work, we recommend listing
- each alternate name with a ServerAlias directive instead of using
- @code{*}.
- Defaults to @samp{*}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} string server-name
- Specifies the fully-qualified host name of the server.
- Defaults to @samp{"localhost"}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} server-tokens server-tokens
- Specifies what information is included in the Server header of HTTP
- responses. @code{None} disables the Server header. @code{ProductOnly}
- reports @code{CUPS}. @code{Major} reports @code{CUPS 2}. @code{Minor}
- reports @code{CUPS 2.0}. @code{Minimal} reports @code{CUPS 2.0.0}.
- @code{OS} reports @code{CUPS 2.0.0 (@var{uname})} where @var{uname} is
- the output of the @code{uname} command. @code{Full} reports @code{CUPS
- 2.0.0 (@var{uname}) IPP/2.0}.
- Defaults to @samp{Minimal}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} multiline-string-list ssl-listen
- Listens on the specified interfaces for encrypted connections. Valid
- values are of the form @var{address}:@var{port}, where @var{address} is
- either an IPv6 address enclosed in brackets, an IPv4 address, or
- @code{*} to indicate all addresses.
- Defaults to @samp{'()}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} ssl-options ssl-options
- Sets encryption options. By default, CUPS only supports encryption
- using TLS v1.0 or higher using known secure cipher suites. Security is
- reduced when @code{Allow} options are used, and enhanced when @code{Deny}
- options are used. The @code{AllowRC4} option enables the 128-bit RC4 cipher
- suites, which are required for some older clients. The @code{AllowSSL3} option
- enables SSL v3.0, which is required for some older clients that do not support
- TLS v1.0. The @code{DenyCBC} option disables all CBC cipher suites. The
- @code{DenyTLS1.0} option disables TLS v1.0 support - this sets the minimum
- protocol version to TLS v1.1.
- Defaults to @samp{'()}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} boolean strict-conformance?
- Specifies whether the scheduler requires clients to strictly adhere to
- the IPP specifications.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} non-negative-integer timeout
- Specifies the HTTP request timeout, in seconds.
- Defaults to @samp{900}.
- @end deftypevr
- @deftypevr {@code{cups-configuration} parameter} boolean web-interface?
- Specifies whether the web interface is enabled.
- Defaults to @samp{#f}.
- @end deftypevr
- At this point you're probably thinking ``oh dear, Guix manual, I like
- you but you can stop already with the configuration options''. Indeed.
- However, one more point: it could be that you have an existing
- @code{cupsd.conf} that you want to use. In that case, you can pass an
- @code{opaque-cups-configuration} as the configuration of a
- @code{cups-service-type}.
- Available @code{opaque-cups-configuration} fields are:
- @deftypevr {@code{opaque-cups-configuration} parameter} package cups
- The CUPS package.
- @end deftypevr
- @deftypevr {@code{opaque-cups-configuration} parameter} string cupsd.conf
- The contents of the @code{cupsd.conf}, as a string.
- @end deftypevr
- @deftypevr {@code{opaque-cups-configuration} parameter} string cups-files.conf
- The contents of the @code{cups-files.conf} file, as a string.
- @end deftypevr
- For example, if your @code{cupsd.conf} and @code{cups-files.conf} are in
- strings of the same name, you could instantiate a CUPS service like
- this:
- @lisp
- (service cups-service-type
- (opaque-cups-configuration
- (cupsd.conf cupsd.conf)
- (cups-files.conf cups-files.conf)))
- @end lisp
- @node Desktop Services
- @subsection Desktop Services
- The @code{(gnu services desktop)} module provides services that are
- usually useful in the context of a ``desktop'' setup---that is, on a
- machine running a graphical display server, possibly with graphical user
- interfaces, etc. It also defines services that provide specific desktop
- environments like GNOME, Xfce or MATE.
- To simplify things, the module defines a variable containing the set of
- services that users typically expect on a machine with a graphical
- environment and networking:
- @defvar %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,
- a NTP client (@pxref{Networking Services}) and the Avahi daemon.
- @end defvar
- 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.
- @defvar 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 defvar
- @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
- @defvar plasma-desktop-service-type
- This is the type of the service that adds the @uref{https://kde.org/plasma-desktop/,
- Plasma} desktop environment. Its value is a @code{plasma-desktop-configuration}
- object (see below).
- This service adds the @code{plasma} package to the system profile.
- @end defvar
- @deftp {Data Type} plasma-desktop-configuration
- Configuration record for the Plasma desktop environment.
- @table @asis
- @item @code{plasma} (default: @code{plasma})
- The Plasma package to use.
- @end table
- @end deftp
- @defvar 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 defvar
- @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
- @defvar 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 defvar
- @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
- @defvar 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 defvar
- @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
- @defvar sugar-desktop-service-type
- This is the type of the service that runs the
- @uref{https://www.sugarlabs.org, Sugar desktop environment}. Its value
- is a @code{sugar-desktop-configuration} object (see below).
- This service adds the @code{sugar} package to the system profile, as
- well as any selected Sugar activities. By default it only includes a
- minimal set of activities.
- @end defvar
- @deftp {Data Type} sugar-desktop-configuration
- Configuration record for the Sugar desktop environment.
- @table @asis
- @item @code{sugar} (default: @code{sugar})
- The Sugar package to use.
- @item @code{gobject-introspection} (default: @code{gobject-introspection})
- The @code{gobject-introspection} package to use. This package is used
- to access libraries installed as dependencies of Sugar activities.
- @item @code{activities} (default: @code{(list sugar-help-activity)})
- A list of Sugar activities to install.
- @end table
- @end deftp
- The following example configures the Sugar desktop environment with a
- number of useful activities:
- @lisp
- (use-modules (gnu))
- (use-package-modules sugar)
- (use-service-modules desktop)
- (operating-system
- ...
- (services (cons* (service sugar-desktop-service-type
- (sugar-desktop-configuration
- (activities (list sugar-browse-activity
- sugar-help-activity
- sugar-jukebox-activity
- sugar-typing-turtle-activity))))
- %desktop-services))
- ...)
- @end lisp
- @defvar 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 defvar
- @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.
- @defvar dbus-root-service-type
- Type for a service that runs the D-Bus ``system bus''.
- @footnote{@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.}
- The value for this service type is a @code{<dbus-configuration>} record.
- @end defvar
- @deftp {Data Type} dbus-configuration
- Data type representing the configuration for @code{dbus-root-service-type}.
- @table @asis
- @item @code{dbus} (default: @code{dbus}) (type: file-like)
- Package object for dbus.
- @item @code{services} (default: @code{'()}) (type: list)
- 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)}.
- @item @code{verbose?} (default: @code{#f}) (type: boolean)
- When @code{#t}, D-Bus is launched with environment variable
- @samp{DBUS_VERBOSE} set to @samp{1}. A verbose-enabled D-Bus package
- such as @code{dbus-verbose} should be provided to @var{dbus} in this
- scenario. The verbose output is logged to
- @file{/var/log/dbus-daemon.log}.
- @end table
- @end deftp
- @subsubheading Elogind
- @uref{https://github.com/elogind/elogind, Elogind} is a login and seat
- management daemon that also 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.
- It also provides 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.
- @defvar elogind-service-type
- Type of the service that runs @command{elogind}, a login and
- seat management daemon. The value for this service is a
- @code{<elogind-configuration>} object.
- @end defvar
- @c TODO: field descriptions. This is best done by refactoring
- @c elogind-configuration to use define-configuration which embeds the
- @c descriptions in the code and then use configuration->documentation.
- @deftp {Data Type} elogind-configuration
- Data type representing the configuration of @command{elogind}.
- @table @asis
- @item @code{elogind} (default: @code{elogind}) (type: file-like)
- ...
- @item @code{kill-user-processes?} (default: @code{#f}) (type: boolean)
- ...
- @item @code{kill-only-users} (default: @code{'()}) (type: list)
- ...
- @item @code{kill-exclude-users} (default: @code{'("root")}) (type: list-of-string)
- ...
- @item @code{inhibit-delay-max-seconds} (default: @code{5}) (type: integer)
- ...
- @item @code{handle-power-key} (default: @code{'poweroff}) (type: symbol)
- ...
- @item @code{handle-suspend-key} (default: @code{'suspend}) (type: symbol)
- ...
- @item @code{handle-hibernate-key} (default: @code{'hibernate}) (type: symbol)
- ...
- @item @code{handle-lid-switch} (default: @code{'suspend}) (type: symbol)
- ...
- @item @code{handle-lid-switch-docked} (default: @code{'ignore}) (type: symbol)
- ...
- @item @code{handle-lid-switch-external-power} (default: @code{*unspecified*}) (type: symbol)
- ...
- @item @code{power-key-ignore-inhibited?} (default: @code{#f}) (type: boolean)
- ...
- @item @code{suspend-key-ignore-inhibited?} (default: @code{#f}) (type: boolean)
- ...
- @item @code{hibernate-key-ignore-inhibited?} (default: @code{#f}) (type: boolean)
- ...
- @item @code{lid-switch-ignore-inhibited?} (default: @code{#t}) (type: boolean)
- ...
- @item @code{holdoff-timeout-seconds} (default: @code{30}) (type: integer)
- ...
- @item @code{idle-action} (default: @code{'ignore}) (type: symbol)
- ...
- @item @code{idle-action-seconds} (default: @code{(* 30 60)}) (type: integer)
- ...
- @item @code{runtime-directory-size-percent} (default: @code{10}) (type: integer)
- ...
- @item @code{runtime-directory-size} (default: @code{#f}) (type: integer)
- ...
- @item @code{remove-ipc?} (default: @code{#t}) (type: boolean)
- ...
- @item @code{suspend-state} (default: @code{'("mem" "standby" "freeze")}) (type: list)
- ...
- @item @code{suspend-mode} (default: @code{'()}) (type: list)
- ...
- @item @code{hibernate-state} (default: @code{'("disk")}) (type: list)
- ...
- @item @code{hibernate-mode} (default: @code{'("platform" "shutdown")}) (type: list)
- ...
- @item @code{hybrid-sleep-state} (default: @code{'("disk")}) (type: list)
- ...
- @item @code{hybrid-sleep-mode} (default: @code{'("suspend" "platform" "shutdown")}) (type: list)
- ...
- @end table
- @end deftp
- @defvar accountsservice-service-type
- Type for the 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.
- See @url{https://www.freedesktop.org/wiki/Software/AccountsService/,
- AccountsService} for more information.
- The value for this service is a file-like object, by default it is
- set to @code{accountsservice} (the package object for AccountsService).
- @end defvar
- @defvar polkit-service-type
- Type for the service that runs the
- @url{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.
- The value for this service is a @code{<polkit-configuration>} object.
- @end defvar
- @c TODO: Document <polkit-configuration>, preferably by refactoring this to use
- @c define-configuration and generating documentation from it.
- @defvar 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 defvar
- @defvar 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 defvar
- @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{#t})
- Whether to use a policy based on battery percentage rather than on
- estimated time left. A policy based on battery percentage is usually
- more reliable.
- @item @code{percentage-low} (default: @code{20})
- 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{5})
- 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
- @defvar udisks-service-type
- Type for the service that runs
- @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.
- The value for this service is a @code{<udisks-configuration>} object.
- @end defvar
- @deftp {Data Type} udisks-configuration
- Data type representing the configuration for @code{udisks-service-type}.
- @table @asis
- @item @code{udisks} (default: @code{udisks}) (type: file-like)
- Package object for UDisks.
- @end table
- @end deftp
- @defvar 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 defvar
- @cindex scanner access
- @defvar 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 defvar
- @defvar sane-backends-minimal
- The default package which the @code{sane-service-type} installs. It
- supports many recent scanners.
- @end defvar
- @defvar 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 defvar
- @deffn {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
- @defvar %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 defvar
- @defvar geoclue-service-type
- Type for the service that runs the
- @url{https://wiki.freedesktop.org/www/Software/GeoClue/, 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.
- The value for this service is a @code{<geoclue-configuration>} object.
- @end defvar
- @c TODO: Document <geoclue-configuration>, preferably by refactoring this to use
- @c define-configuration and generating documentation from it.
- @defvar bluetooth-service-type
- This is the type for the @uref{https://bluez.org/, Linux Bluetooth Protocol
- Stack} (BlueZ) system, which generates the @file{/etc/bluetooth/main.conf}
- configuration file. The value for this type is a @command{bluetooth-configuration}
- record as in this example:
- @lisp
- (service bluetooth-service-type)
- @end lisp
- See below for details about @code{bluetooth-configuration}.
- @end defvar
- @deftp {Data Type} bluetooth-configuration
- Data type representing the configuration for @code{bluetooth-service}.
- @table @asis
- @item @code{bluez} (default: @code{bluez})
- @code{bluez} package to use.
- @item @code{name} (default: @code{"BlueZ"})
- Default adapter name.
- @item @code{class} (default: @code{#x000000})
- Default device class. Only the major and minor device class bits are considered.
- @item @code{discoverable-timeout} (default: @code{180})
- How long to stay in discoverable mode before going back to non-discoverable. The
- value is in seconds.
- @item @code{always-pairable?} (default: @code{#f})
- Always allow pairing even if there are no agents registered.
- @item @code{pairable-timeout} (default: @code{0})
- How long to stay in pairable mode before going back to non-discoverable. The
- value is in seconds.
- @item @code{device-id} (default: @code{#f})
- Use vendor id source (assigner), vendor, product and version information for
- DID profile support. The values are separated by ":" and @var{assigner}, @var{VID},
- @var{PID} and @var{version}.
- Possible values are:
- @itemize @bullet
- @item
- @code{#f} to disable it,
- @item
- @code{"assigner:1234:5678:abcd"}, where @var{assigner} is either @code{usb} (default)
- or @code{bluetooth}.
- @end itemize
- @item @code{reverse-service-discovery?} (default: @code{#t})
- Do reverse service discovery for previously unknown devices that connect to
- us. For BR/EDR this option is really only needed for qualification since the
- BITE tester doesn't like us doing reverse SDP for some test cases, for LE
- this disables the GATT client functionally so it can be used in system which
- can only operate as peripheral.
- @item @code{name-resolving?} (default: @code{#t})
- Enable name resolving after inquiry. Set it to @code{#f} if you don't need
- remote devices name and want shorter discovery cycle.
- @item @code{debug-keys?} (default: @code{#f})
- Enable runtime persistency of debug link keys. Default is false which makes
- debug link keys valid only for the duration of the connection that they were
- created for.
- @item @code{controller-mode} (default: @code{'dual})
- Restricts all controllers to the specified transport. @code{'dual} means both
- BR/EDR and LE are enabled (if supported by the hardware).
- Possible values are:
- @itemize @bullet
- @item
- @code{'dual}
- @item
- @code{'bredr}
- @item
- @code{'le}
- @end itemize
- @item @code{multi-profile} (default: @code{'off})
- Enables Multi Profile Specification support. This allows to specify if system
- supports only Multiple Profiles Single Device (MPSD) configuration or both
- Multiple Profiles Single Device (MPSD) and Multiple Profiles Multiple Devices
- (MPMD) configurations.
- Possible values are:
- @itemize @bullet
- @item
- @code{'off}
- @item
- @code{'single}
- @item
- @code{'multiple}
- @end itemize
- @item @code{fast-connectable?} (default: @code{#f})
- Permanently enables the Fast Connectable setting for adapters that support
- it. When enabled other devices can connect faster to us, however the
- tradeoff is increased power consumptions. This feature will fully work only
- on kernel version 4.1 and newer.
- @item @code{privacy} (default: @code{'off})
- Default privacy settings.
- @itemize @bullet
- @item
- @code{'off}: Disable local privacy
- @item
- @code{'network/on}: A device will only accept advertising packets from peer
- devices that contain private addresses. It may not be compatible with some
- legacy devices since it requires the use of RPA(s) all the time
- @item
- @code{'device}: A device in device privacy mode is only concerned about the
- privacy of the device and will accept advertising packets from peer devices
- that contain their Identity Address as well as ones that contain a private
- address, even if the peer device has distributed its IRK in the past
- @end itemize
- and additionally, if @var{controller-mode} is set to @code{'dual}:
- @itemize @bullet
- @item
- @code{'limited-network}: Apply Limited Discoverable Mode to advertising, which
- follows the same policy as to BR/EDR that publishes the identity address when
- discoverable, and Network Privacy Mode for scanning
- @item
- @code{'limited-device}: Apply Limited Discoverable Mode to advertising, which
- follows the same policy as to BR/EDR that publishes the identity address when
- discoverable, and Device Privacy Mode for scanning.
- @end itemize
- @item @code{just-works-repairing} (default: @code{'never})
- Specify the policy to the JUST-WORKS repairing initiated by peer.
- Possible values:
- @itemize @bullet
- @item
- @code{'never}
- @item
- @code{'confirm}
- @item
- @code{'always}
- @end itemize
- @item @code{temporary-timeout} (default: @code{30})
- How long to keep temporary devices around. The value is in seconds. @code{0}
- disables the timer completely.
- @item @code{refresh-discovery?} (default: @code{#t})
- Enables the device to issue an SDP request to update known services when
- profile is connected.
- @item @code{experimental} (default: @code{#f})
- Enables experimental features and interfaces, alternatively a list of UUIDs
- can be given.
- Possible values:
- @itemize @bullet
- @item
- @code{#t}
- @item
- @code{#f}
- @item
- @code{(list (uuid <uuid-1>) (uuid <uuid-2>) ...)}.
- @end itemize
- List of possible UUIDs:
- @itemize @bullet
- @item
- @code{d4992530-b9ec-469f-ab01-6c481c47da1c}: BlueZ Experimental Debug,
- @item
- @code{671b10b5-42c0-4696-9227-eb28d1b049d6}: BlueZ Experimental Simultaneous Central and Peripheral,
- @item
- @code{"15c0a148-c273-11ea-b3de-0242ac130004}: BlueZ Experimental LL privacy,
- @item
- @code{330859bc-7506-492d-9370-9a6f0614037f}: BlueZ Experimental Bluetooth Quality Report,
- @item
- @code{a6695ace-ee7f-4fb9-881a-5fac66c629af}: BlueZ Experimental Offload Codecs.
- @end itemize
- @item @code{remote-name-request-retry-delay} (default: @code{300})
- The duration to avoid retrying to resolve a peer's name, if the previous
- try failed.
- @item @code{page-scan-type} (default: @code{#f})
- BR/EDR Page scan activity type.
- @item @code{page-scan-interval} (default: @code{#f})
- BR/EDR Page scan activity interval.
- @item @code{page-scan-window} (default: @code{#f})
- BR/EDR Page scan activity window.
- @item @code{inquiry-scan-type} (default: @code{#f})
- BR/EDR Inquiry scan activity type.
- @item @code{inquiry-scan-interval} (default: @code{#f})
- BR/EDR Inquiry scan activity interval.
- @item @code{inquiry-scan-window} (default: @code{#f})
- BR/EDR Inquiry scan activity window.
- @item @code{link-supervision-timeout} (default: @code{#f})
- BR/EDR Link supervision timeout.
- @item @code{page-timeout} (default: @code{#f})
- BR/EDR Page timeout.
- @item @code{min-sniff-interval} (default: @code{#f})
- BR/EDR minimum sniff interval.
- @item @code{max-sniff-interval} (default: @code{#f})
- BR/EDR maximum sniff interval.
- @item @code{min-advertisement-interval} (default: @code{#f})
- LE minimum advertisement interval (used for legacy advertisement only).
- @item @code{max-advertisement-interval} (default: @code{#f})
- LE maximum advertisement interval (used for legacy advertisement only).
- @item @code{multi-advertisement-rotation-interval} (default: @code{#f})
- LE multiple advertisement rotation interval.
- @item @code{scan-interval-auto-connect} (default: @code{#f})
- LE scanning interval used for passive scanning supporting auto connect.
- @item @code{scan-window-auto-connect} (default: @code{#f})
- LE scanning window used for passive scanning supporting auto connect.
- @item @code{scan-interval-suspend} (default: @code{#f})
- LE scanning interval used for active scanning supporting wake from suspend.
- @item @code{scan-window-suspend} (default: @code{#f})
- LE scanning window used for active scanning supporting wake from suspend.
- @item @code{scan-interval-discovery} (default: @code{#f})
- LE scanning interval used for active scanning supporting discovery.
- @item @code{scan-window-discovery} (default: @code{#f})
- LE scanning window used for active scanning supporting discovery.
- @item @code{scan-interval-adv-monitor} (default: @code{#f})
- LE scanning interval used for passive scanning supporting the advertisement monitor APIs.
- @item @code{scan-window-adv-monitor} (default: @code{#f})
- LE scanning window used for passive scanning supporting the advertisement monitor APIs.
- @item @code{scan-interval-connect} (default: @code{#f})
- LE scanning interval used for connection establishment.
- @item @code{scan-window-connect} (default: @code{#f})
- LE scanning window used for connection establishment.
- @item @code{min-connection-interval} (default: @code{#f})
- LE default minimum connection interval. This value is superseded by any specific
- value provided via the Load Connection Parameters interface.
- @item @code{max-connection-interval} (default: @code{#f})
- LE default maximum connection interval. This value is superseded by any specific
- value provided via the Load Connection Parameters interface.
- @item @code{connection-latency} (default: @code{#f})
- LE default connection latency. This value is superseded by any specific
- value provided via the Load Connection Parameters interface.
- @item @code{connection-supervision-timeout} (default: @code{#f})
- LE default connection supervision timeout. This value is superseded by any specific
- value provided via the Load Connection Parameters interface.
- @item @code{autoconnect-timeout} (default: @code{#f})
- LE default autoconnect timeout. This value is superseded by any specific
- value provided via the Load Connection Parameters interface.
- @item @code{adv-mon-allowlist-scan-duration} (default: @code{300})
- Allowlist scan duration during interleaving scan. Only used when scanning for ADV
- monitors. The units are msec.
- @item @code{adv-mon-no-filter-scan-duration} (default: @code{500})
- No filter scan duration during interleaving scan. Only used when scanning for ADV
- monitors. The units are msec.
- @item @code{enable-adv-mon-interleave-scan?} (default: @code{#t})
- Enable/Disable Advertisement Monitor interleave scan for power saving.
- @item @code{cache} (default: @code{'always})
- GATT attribute cache.
- Possible values are:
- @itemize @bullet
- @item
- @code{'always}: Always cache attributes even for devices not paired, this is
- recommended as it is best for interoperability, with more consistent
- reconnection times and enables proper tracking of notifications for all
- devices
- @item
- @code{'yes}: Only cache attributes of paired devices
- @item
- @code{'no}: Never cache attributes.
- @end itemize
- @item @code{key-size} (default: @code{0})
- Minimum required Encryption Key Size for accessing secured characteristics.
- Possible values are:
- @itemize @bullet
- @item
- @code{0}: Don't care
- @item
- @code{7 <= N <= 16}
- @end itemize
- @item @code{exchange-mtu} (default: @code{517})
- Exchange MTU size. Possible values are:
- @itemize @bullet
- @item
- @code{23 <= N <= 517}
- @end itemize
- @item @code{att-channels} (default: @code{3})
- Number of ATT channels. Possible values are:
- @itemize @bullet
- @item
- @code{1}: Disables EATT
- @item
- @code{2 <= N <= 5}
- @end itemize
- @item @code{session-mode} (default: @code{'basic})
- AVDTP L2CAP signalling channel mode.
- Possible values are:
- @itemize @bullet
- @item
- @code{'basic}: Use L2CAP basic mode
- @item
- @code{'ertm}: Use L2CAP enhanced retransmission mode.
- @end itemize
- @item @code{stream-mode} (default: @code{'basic})
- AVDTP L2CAP transport channel mode.
- Possible values are:
- @itemize @bullet
- @item
- @code{'basic}: Use L2CAP basic mode
- @item
- @code{'streaming}: Use L2CAP streaming mode.
- @end itemize
- @item @code{reconnect-uuids} (default: @code{'()})
- The ReconnectUUIDs defines the set of remote services that should try
- to be reconnected to in case of a link loss (link supervision
- timeout). The policy plugin should contain a sane set of values by
- default, but this list can be overridden here. By setting the list to
- empty the reconnection feature gets disabled.
- Possible values:
- @itemize @bullet
- @item
- @code{'()}
- @item
- @code{(list (uuid <uuid-1>) (uuid <uuid-2>) ...)}.
- @end itemize
- @item @code{reconnect-attempts} (default: @code{7})
- Defines the number of attempts to reconnect after a link lost. Setting
- the value to 0 disables reconnecting feature.
- @item @code{reconnect-intervals} (default: @code{'(1 2 4 8 16 32 64)})
- Defines a list of intervals in seconds to use in between attempts. If
- the number of attempts defined in @var{reconnect-attempts} is bigger than
- the list of intervals the last interval is repeated until the last attempt.
- @item @code{auto-enable?} (default: @code{#f})
- Defines option to enable all controllers when they are found. This includes
- adapters present on start as well as adapters that are plugged in later on.
- @item @code{resume-delay} (default: @code{2})
- Audio devices that were disconnected due to suspend will be reconnected on
- resume. @var{resume-delay} determines the delay between when the controller
- resumes from suspend and a connection attempt is made. A longer delay is
- better for better co-existence with Wi-Fi. The value is in seconds.
- @item @code{rssi-sampling-period} (default: @code{#xFF})
- Default RSSI Sampling Period. This is used when a client registers an
- advertisement monitor and leaves the RSSISamplingPeriod unset.
- Possible values are:
- @itemize @bullet
- @item
- @code{#x0}: Report all advertisements
- @item
- @code{N = #xXX}: Report advertisements every N x 100 msec (range: #x01 to #xFE)
- @item
- @code{#xFF}: Report only one advertisement per device during monitoring period.
- @end itemize
- @end table
- @end deftp
- @defvar 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 defvar
- @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
- @defvar seatd-service-type
- @uref{https://sr.ht/~kennylevinsen/seatd/, seatd} is a minimal seat
- management daemon.
- Seat management takes care of mediating access to shared devices (graphics,
- input), without requiring the applications needing access to be root.
- @lisp
- (append
- (list
- ;; make sure seatd is running
- (service seatd-service-type))
- ;; normally one would want %base-services
- %base-services)
- @end lisp
- @code{seatd} operates over a UNIX domain socket, with @code{libseat}
- providing the client side of the protocol. Applications that acquire
- access to the shared resources via @code{seatd} (e.g. @code{sway})
- need to be able to talk to this socket.
- This can be achieved by adding the user they run under to the group
- owning @code{seatd}'s socket (usually ``seat''), like so:
- @lisp
- (user-account
- (name "alice")
- (group "users")
- (supplementary-groups '("wheel" ; allow use of sudo, etc.
- "seat" ; seat management
- "audio" ; sound card
- "video" ; video devices such as webcams
- "cdrom")) ; the good ol' CD-ROM
- (comment "Bob's sister"))
- @end lisp
- Depending on your setup, you will have to not only add regular users,
- but also system users to this group. For instance, some greetd greeters
- require graphics and therefore also need to negotiate with seatd.
- @end defvar
- @deftp {Data Type} seatd-configuration
- Configuration record for the seatd daemon service.
- @table @asis
- @item @code{seatd} (default: @code{seatd})
- The seatd package to use.
- @item @code{group} (default: @samp{"seat"})
- Group to own the seatd socket.
- @item @code{socket} (default: @samp{"/run/seatd.sock"})
- Where to create the seatd socket.
- @item @code{logfile} (default: @samp{"/var/log/seatd.log"})
- Log file to write to.
- @item @code{loglevel} (default: @samp{"error"})
- Log level to output logs. Possible values: @samp{"silent"}, @samp{"error"},
- @samp{"info"} and @samp{"debug"}.
- @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.
- @defvar 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 defvar
- @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.
- @defvar 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 defvar
- @deftp {Data Type} pulseaudio-configuration
- Data type representing the configuration for @code{pulseaudio-service}.
- @table @asis
- @item @code{client-conf} (default: @code{'()})
- List of settings to set in @file{client.conf}.
- Accepts a list of strings or symbol-value pairs. A string will be
- inserted as-is with a newline added. A pair will be formatted as
- ``key = value'', again with a newline added.
- @item @code{daemon-conf} (default: @code{'((flat-volumes . no))})
- List of settings to set in @file{daemon.conf}, formatted just like
- @var{client-conf}.
- @item @code{script-file} (default: @code{(file-append pulseaudio "/etc/pulse/default.pa")})
- Script file to use as @file{default.pa}. In case the
- @code{extra-script-files} field below is used, an @code{.include}
- directive pointing to @file{/etc/pulse/default.pa.d} is appended to the
- provided script.
- @item @code{extra-script-files} (default: @code{'()})
- A list of file-like objects defining extra PulseAudio scripts to run at
- the initialization of the @command{pulseaudio} daemon, after the main
- @code{script-file}. The scripts are deployed to the
- @file{/etc/pulse/default.pa.d} directory; they should have the
- @samp{.pa} file name extension. For a reference of the available
- commands, refer to @command{man pulse-cli-syntax}.
- @item @code{system-script-file} (default: @code{(file-append pulseaudio "/etc/pulse/system.pa")})
- Script file to use as @file{system.pa}.
- @end table
- The example below sets the default PulseAudio card profile, the default
- sink and the default source to use for a old SoundBlaster Audigy sound
- card:
- @lisp
- (pulseaudio-configuration
- (extra-script-files
- (list (plain-file "audigy.pa"
- (string-append "\
- set-card-profile alsa_card.pci-0000_01_01.0 \
- output:analog-surround-40+input:analog-mono
- set-default-source alsa_input.pci-0000_01_01.0.analog-mono
- set-default-sink alsa_output.pci-0000_01_01.0.analog-surround-40\n")))))
- @end lisp
- Note that @code{pulseaudio-service-type} is part of
- @code{%desktop-services}; if your operating system declaration was
- derived from one of the desktop templates, you'll want to adjust the
- above example to modify the existing @code{pulseaudio-service-type} via
- @code{modify-services} (@pxref{Service Reference,
- @code{modify-services}}), instead of defining a new one.
- @end deftp
- @defvar 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 defvar
- @node File Search Services
- @subsection File Search Services
- @cindex file search
- @cindex searching for a file
- The services in this section populate @dfn{file databases} that let you
- search for files on your machine. These services are provided by the
- @code{(gnu services admin)} module.
- The first one, @code{file-database-service-type}, periodically runs the
- venerable @command{updatedb} command (@pxref{Invoking updatedb,,, find,
- GNU Findutils}). That command populates a database of file names that
- you can then search with the @command{locate} command (@pxref{Invoing
- locate,,, find, GNU Findutils}), as in this example:
- @example
- locate important-notes.txt
- @end example
- You can enable this service with its default settings by adding this
- snippet to your operating system services:
- @lisp
- (service file-database-service-type)
- @end lisp
- This updates the database once a week, excluding files from
- @file{/gnu/store}---these are more usefully handled by @command{guix
- locate} (@pxref{Invoking guix locate}). You can of course provide a
- custom configuration, as described below.
- @defvar file-database-service-type
- This is the type of the file database service, which runs
- @command{updatedb} periodically. Its associated value must be a
- @code{file-database-configuration} record, as described below.
- @end defvar
- @deftp {Data Type} file-database-configuration
- Record type for the @code{file-database-service-type} configuration,
- with the following fields:
- @table @asis
- @item @code{package} (default: @code{findutils})
- The GNU@tie{}Findutils package from which the @command{updatedb} command
- is taken.
- @item @code{schedule} (default: @code{%default-file-database-update-schedule})
- String or G-exp denoting an mcron schedule for the periodic
- @command{updatedb} job (@pxref{Guile Syntax,,, mcron, GNU@tie{}mcron}).
- @item @code{excluded-directories} (default @code{%default-file-database-excluded-directories})
- List of regular expressions of directories to ignore when building the
- file database. By default, this includes @file{/tmp} and @file{/gnu/store};
- the latter should instead be indexed by @command{guix locate} (@pxref{Invoking
- guix locate}). This list is passed to the @option{--prunepaths} option of
- @command{updatedb} (@pxref{Invoking updatedb,,, find, GNU@tie{}Findutils}).
- @end table
- @end deftp
- The second service, @code{package-database-service-type}, builds the
- database used by @command{guix locate}, which lets you search for
- packages that contain a given file (@pxref{Invoking guix locate}). The
- service periodically updates a system-wide database, which will be
- readily available to anyone running @command{guix locate} on the system.
- To use this service with its default settings, add this snippet to your
- service list:
- @lisp
- (service package-database-service-type)
- @end lisp
- This will run @command{guix locate --update} once a week.
- @defvar package-database-service-type
- This is the service type for periodic @command{guix locate} updates
- (@pxref{Invoking guix locate}). Its value must be a
- @code{package-database-configuration} record, as shown below.
- @end defvar
- @deftp {Data Type} package-database-configuration
- Data type to configure periodic package database updates. It has the
- following fields:
- @table @asis
- @item @code{package} (default: @code{guix})
- The Guix package to use.
- @item @code{schedule} (default: @code{%default-package-database-update-schedule})
- String or G-exp denoting an mcron schedule for the periodic
- @command{guix locate --update} job (@pxref{Guile Syntax,,, mcron,
- GNU@tie{}mcron}).
- @item @code{method} (default: @code{'store})
- Indexing method for @command{guix locate}. The default value,
- @code{'store}, yields a more complete database but is relatively
- expensive in terms of CPU and input/output.
- @item @code{channels} (default: @code{#~%default-channels})
- G-exp denoting the channels to use when updating the database
- (@pxref{Channels}).
- @end table
- @end deftp
- @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.
- @item @code{create-account?} (default: @code{#t})
- Whether or not the @code{postgres} user and group should be created.
- @item @code{uid} (default: @code{#f})
- Explicitly specify the UID of the @code{postgres} daemon account.
- You normally do not need to specify this, in which case a free UID will
- be automatically assigned.
- One situation where this option might be useful is if the @var{data-directory}
- is located on a mounted network share.
- @item @code{gid} (default: @code{#f})
- Explicitly specify the GID of the @code{postgres} group.
- @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
- @defvar 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 defvar
- @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.
- @item @code{encoding} (default: @code{"UTF8"})
- The character set to use for storing text in the database.
- @item @code{collation} (default: @code{"en_US.utf8"})
- The string sort order locale setting.
- @item @code{ctype} (default: @code{"en_US.utf8"})
- The character classification locale setting.
- @item @code{template} (default: @code{"template1"})
- The default template to copy the new database from when creating it.
- Use @code{"template0"} for a pristine database with no system-local
- modifications.
- @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
- @defvar 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 defvar
- @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
- @defvar 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 defvar
- @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
- @defvar 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 defvar
- @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
- @defvar dovecot-service-type
- Type for the service that runs the Dovecot IMAP/POP3/LMTP mail server,
- whose value is a @code{<dovecot-configuration>} object.
- @end defvar
- 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
- (service dovecot-service-type
- (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
- @defvar 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 defvar
- @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{shepherd-requirement} (default: @code{'()})
- This option can be used to provide a list of symbols naming Shepherd services
- that this service will depend on, such as @code{'networking}
- if you want to configure OpenSMTPD to listen on non-loopback interfaces.
- @item @code{config-file} (default: @code{%default-opensmtpd-config-file})
- File-like object of the OpenSMTPD configuration file to use. By default
- it listens on the loopback network interface, and allows for mail from
- users and daemons on the local machine, as well as permitting email to
- remote servers. Run @command{man smtpd.conf} for more information.
- @item @code{setgid-commands?} (default: @code{#t})
- Make the following commands setgid to @code{smtpq} so they can be
- executed: @command{smtpctl}, @command{sendmail}, @command{send-mail},
- @command{makemap}, @command{mailq}, and @command{newaliases}.
- @xref{Setuid Programs}, for more information on setgid programs.
- @end table
- @end deftp
- @subsubheading Exim Service
- @cindex mail transfer agent (MTA)
- @cindex MTA (mail transfer agent)
- @cindex SMTP
- @defvar 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 defvar
- 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
- @defvar getmail-service-type
- This is the type of the @uref{http://pyropus.ca/software/getmail/, Getmail}
- mail retriever, whose value should be a @code{getmail-configuration}.
- @end defvar
- 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
- @defvar 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 defvar
- 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
- @defvar 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 defvar
- @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
- @defvar 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 defvar
- @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
- @defvar 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 defvar
- 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 left unspecified.
- 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.
- @quotation 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}.
- @end quotation
- 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.
- @defvar 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 defvar
- @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.
- @defvar 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 defvar
- @deftp {Data Type} quassel-configuration
- This is the configuration for Quassel, with the following fields:
- @table @asis
- @item @code{quassel} (default: @code{quassel})
- The Quassel package to use.
- @item @code{interface} (default: @code{"::,0.0.0.0"})
- @item @code{port} (default: @code{4242})
- Listen on the network interface(s) corresponding to the IPv4 or IPv6
- interfaces specified in the comma delimited @var{interface}, on
- @var{port}.
- @item @code{loglevel} (default: @code{"Info"})
- The level of logging desired. Accepted values are Debug, Info, Warning
- and Error.
- @end table
- @end deftp
- @node Telephony Services
- @subsection Telephony Services
- @cindex telephony, services
- The @code{(gnu services telephony)} module contains Guix service
- definitions for telephony services. Currently it provides the following
- services:
- @subsubheading Jami
- @cindex jami, service
- This section describes how to configure a Jami server that can be used
- to host video (or audio) conferences, among other uses. The following
- example demonstrates how to specify Jami account archives (backups) to
- be provisioned automatically:
- @lisp
- (service jami-service-type
- (jami-configuration
- (accounts
- (list (jami-account
- (archive "/etc/jami/unencrypted-account-1.gz"))
- (jami-account
- (archive "/etc/jami/unencrypted-account-2.gz"))))))
- @end lisp
- When the accounts field is specified, the Jami account files of the
- service found under @file{/var/lib/jami} are recreated every time the
- service starts.
- Jami accounts and their corresponding backup archives can be generated
- using the @code{jami} or @code{jami-gnome} Jami clients. The accounts
- should not be password-protected, but it is wise to ensure their files
- are only readable by @samp{root}.
- The next example shows how to declare that only some contacts should be
- allowed to communicate with a given account:
- @lisp
- (service jami-service-type
- (jami-configuration
- (accounts
- (list (jami-account
- (archive "/etc/jami/unencrypted-account-1.gz")
- (peer-discovery? #t)
- (rendezvous-point? #t)
- (allowed-contacts
- '("1dbcb0f5f37324228235564b79f2b9737e9a008f"
- "2dbcb0f5f37324228235564b79f2b9737e9a008f")))))))
- @end lisp
- In this mode, only the declared @code{allowed-contacts} can initiate
- communication with the Jami account. This can be used, for example,
- with rendezvous point accounts to create a private video conferencing
- space.
- To put the system administrator in full control of the conferences
- hosted on their system, the Jami service supports the following actions:
- @example sh
- # herd doc jami list-actions
- (list-accounts
- list-account-details
- list-banned-contacts
- list-contacts
- list-moderators
- add-moderator
- ban-contact
- enable-account
- disable-account)
- @end example
- The above actions aim to provide the most valuable actions for
- moderation purposes, not to cover the whole Jami API. Users wanting to
- interact with the Jami daemon from Guile may be interested in
- experimenting with the @code{(gnu build jami-service)} module, which
- powers the above Shepherd actions.
- @c TODO: This should be auto-generated from the doc already defined on
- @c the shepherd-actions themselves in (gnu services telephony).
- The @code{add-moderator} and @code{ban-contact} actions accept a contact
- @emph{fingerprint} (40 characters long hash) as first argument and an
- account fingerprint or username as second argument:
- @example sh
- # herd add-moderator jami 1dbcb0f5f37324228235564b79f2b9737e9a008f \
- f3345f2775ddfe07a4b0d95daea111d15fbc1199
- # herd list-moderators jami
- Moderators for account f3345f2775ddfe07a4b0d95daea111d15fbc1199:
- - 1dbcb0f5f37324228235564b79f2b9737e9a008f
- @end example
- In the case of @code{ban-contact}, the second username argument is
- optional; when omitted, the account is banned from all Jami accounts:
- @example sh
- # herd ban-contact jami 1dbcb0f5f37324228235564b79f2b9737e9a008f
- # herd list-banned-contacts jami
- Banned contacts for account f3345f2775ddfe07a4b0d95daea111d15fbc1199:
- - 1dbcb0f5f37324228235564b79f2b9737e9a008f
- @end example
- Banned contacts are also stripped from their moderation privileges.
- The @code{disable-account} action allows to completely disconnect an
- account from the network, making it unreachable, while
- @code{enable-account} does the inverse. They accept a single account
- username or fingerprint as first argument:
- @example sh
- # herd disable-account jami f3345f2775ddfe07a4b0d95daea111d15fbc1199
- # herd list-accounts jami
- The following Jami accounts are available:
- - f3345f2775ddfe07a4b0d95daea111d15fbc1199 (dummy) [disabled]
- @end example
- The @code{list-account-details} action prints the detailed parameters of
- each accounts in the Recutils format, which means the @command{recsel}
- command can be used to select accounts of interest (@pxref{Selection
- Expressions,,,recutils, GNU recutils manual}). Note that period
- characters (@samp{.}) found in the account parameter keys are mapped to
- underscores (@samp{_}) in the output, to meet the requirements of the
- Recutils format. The following example shows how to print the account
- fingerprints for all accounts operating in the rendezvous point mode:
- @example sh
- # herd list-account-details jami | \
- recsel -p Account.username -e 'Account.rendezVous ~ "true"'
- Account_username: f3345f2775ddfe07a4b0d95daea111d15fbc1199
- @end example
- The remaining actions should be self-explanatory.
- The complete set of available configuration options is detailed below.
- @c TODO: Ideally, the following fragments would be auto-generated at
- @c build time, so that they needn't be manually duplicated.
- @c Auto-generated via (configuration->documentation 'jami-configuration)
- @deftp {Data Type} jami-configuration
- Available @code{jami-configuration} fields are:
- @table @asis
- @item @code{libjami} (default: @code{libjami}) (type: package)
- The Jami daemon package to use.
- @item @code{dbus} (default: @code{dbus-for-jami}) (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} (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} (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 left specified, 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} (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 left 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?} (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?} (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 Internet has been lost. When left unspecified,
- the value from the account archive prevails.
- @item @code{bootstrap-hostnames} (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} (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 Mumble server
- @cindex Mumble
- @cindex Murmur
- @cindex VoIP server
- This section describes how to set up and run a
- @uref{https://mumble.info, Mumble} server (formerly known as Murmur).
- @deftp {Data Type} mumble-server-configuration
- The service type for the Mumble server. An example configuration can
- look like this:
- @lisp
- (service mumble-server-service-type
- (mumble-server-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 mumble-server
- @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{mumble-server-configuration} fields are:
- @table @asis
- @item @code{package} (default: @code{mumble})
- Package that contains @code{bin/mumble-server}.
- @item @code{user} (default: @code{"mumble-server"})
- User who will run the Mumble-Server server.
- @item @code{group} (default: @code{"mumble-server"})
- Group of the user who will run the mumble-server 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/mumble-server/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/mumble-server/mumble-server.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 mumble-server 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 mumble-server server version be exposed in ping requests.
- @item @code{log-days} (default: @code{31})
- Mumble 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 Mumble
- server log to ensure that Mumble is using the cipher suites that you
- expected it to.
- @quotation Note
- Changing this option may impact the backwards compatibility of your
- Mumble-Server server, and can remove the ability for older Mumble clients to be able to connect to it.
- @end quotation
- @item @code{public-registration} (default: @code{#f})
- Must be a @code{<mumble-server-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} mumble-server-public-registration-configuration
- Configuration for public registration of a mumble-server 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
- @quotation Deprecation notice
- Due to historical reasons, all of the above @code{mumble-server-}
- procedures are also exported with the @code{murmur-} prefix.
- It is recommended that you switch to using @code{mumble-server-}
- going forward.
- @end quotation
- @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.
- @defvar 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 defvar
- 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 {Procedure} transmission-password-hash password 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 {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}. When left unspecified, 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 darkstat-service-type
- This is the service type for the
- @uref{https://unix4lyfe.org/darkstat/, darkstat}
- service, its value must be a @code{darkstat-configuration} record as in
- this example:
- @lisp
- (service darkstat-service-type
- (darkstat-configuration
- (interface "eno1")))
- @end lisp
- @end defvar
- @deftp {Data Type} darkstat-configuration
- Data type representing the configuration of @command{darkstat}.
- @table @asis
- @item @code{package} (default: @code{darkstat})
- The darkstat package to use.
- @item @code{interface}
- Capture traffic on the specified network interface.
- @item @code{port} (default: @code{"667"})
- Bind the web interface to the specified port.
- @item @code{bind-address} (default: @code{"127.0.0.1"})
- Bind the web interface to the specified address.
- @item @code{base} (default: @code{"/"})
- Specify the path of the base URL@. This can be useful if
- @command{darkstat} is accessed via a reverse proxy.
- @end table
- @end deftp
- @anchor{prometheus-node-exporter}
- @subsubheading Prometheus Node Exporter Service
- @cindex prometheus-node-exporter
- The Prometheus ``node exporter'' makes hardware and operating system statistics
- provided by the Linux kernel available for the Prometheus monitoring system.
- This service should be deployed on all physical nodes and virtual machines,
- where monitoring these statistics is desirable.
- @defvar 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
- @anchor{vnstat}
- @subsubheading vnStat Network Traffic Monitor
- @cindex vnstat
- vnStat is a network traffic monitor that uses interface statistics provided
- by the kernel rather than traffic sniffing. This makes it a light resource
- monitor, regardless of network traffic rate.
- @defvar vnstat-service-type
- This is the service type for the @uref{https://humdi.net/vnstat/,vnStat} daemon
- and accepts a @code{vnstat-configuration} value.
- The following example will configure the service with default values:
- @lisp
- (service vnstat-service-type)
- @end lisp
- @end defvar
- @c %start of fragment
- @deftp {Data Type} vnstat-configuration
- Available @code{vnstat-configuration} fields are:
- @table @asis
- @item @code{package} (default: @code{vnstat}) (type: file-like)
- The vnstat package.
- @item @code{database-directory} (default: @code{"/var/lib/vnstat"}) (type: string)
- Specifies the directory where the database is to be stored. A full path
- must be given and a leading '/' isn't required.
- @item @code{5-minute-hours} (default: @code{48}) (type: maybe-integer)
- Data retention duration for the 5 minute resolution entries. The
- configuration defines for how many past hours entries will be stored.
- Set to @code{-1} for unlimited entries or to @code{0} to disable the
- data collection of this resolution.
- @item @code{64bit-interface-counters} (default: @code{-2}) (type: maybe-integer)
- Select interface counter handling. Set to @code{1} for defining that
- all interfaces use 64-bit counters on the kernel side and @code{0} for
- defining 32-bit counter. Set to @code{-1} for using the old style logic
- used in earlier versions where counter values within 32-bits are assumed
- to be 32-bit and anything larger is assumed to be a 64-bit counter. This
- may produce false results if a 64-bit counter is reset within the
- 32-bits. Set to @code{-2} for using automatic detection based on
- available kernel datastructures.
- @item @code{always-add-new-interfaces?} (default: @code{#t}) (type: maybe-boolean)
- Enable or disable automatic creation of new database entries for
- interfaces not currently in the database even if the database file
- already exists when the daemon is started. New database entries will
- also get created for new interfaces seen while the daemon is running.
- Pseudo interfaces @samp{lo}, @samp{lo0} and @samp{sit0} are always excluded from getting
- added.
- @item @code{bandwidth-detection?} (default: @code{#t}) (type: maybe-boolean)
- Try to automatically detect @var{max-bandwidth} value for each monitored
- interface. Mostly only ethernet interfaces support this feature.
- @var{max-bandwidth} will be used as fallback value if detection fails.
- Any interface specific @var{max-BW} configuration will disable the
- detection for the specified interface. In Linux, the detection is
- disabled for tun interfaces due to the Linux kernel always reporting 10
- Mbit regardless of the used real interface.
- @item @code{bandwidth-detection-interval} (default: @code{5}) (type: maybe-integer)
- How often in minutes interface specific detection of @var{max-bandwidth}
- is done for detecting possible changes when @var{bandwidth-detection} is
- enabled. Can be disabled by setting to @code{0}. Value range:
- @samp{0}..@samp{30}
- @item @code{boot-variation} (default: @code{15}) (type: maybe-integer)
- Time in seconds how much the boot time reported by system kernel can
- variate between updates. Value range: @samp{0}..@samp{300}
- @item @code{check-disk-space?} (default: @code{#t}) (type: maybe-boolean)
- Enable or disable the availability check of at least some free disk
- space before a database write.
- @item @code{create-directories?} (default: @code{#t}) (type: maybe-boolean)
- Enable or disable the creation of directories when a configured path
- doesn't exist. This includes @var{database-directory}.
- @item @code{daemon-group} (type: maybe-user-group)
- Specify the group to which the daemon process should switch during
- startup. Set to @code{%unset-value} to disable group switching.
- @item @code{daemon-user} (type: maybe-user-account)
- Specify the user to which the daemon process should switch during
- startup. Set to @code{%unset-value} to disable user switching.
- @item @code{daily-days} (default: @code{62}) (type: maybe-integer)
- Data retention duration for the one day resolution entries. The
- configuration defines for how many past days entries will be stored. Set
- to @code{-1} for unlimited entries or to @code{0} to disable the data
- collection of this resolution.
- @item @code{database-synchronous} (default: @code{-1}) (type: maybe-integer)
- Change the setting of the SQLite "synchronous" flag which controls how
- much care is taken to ensure disk writes have fully completed when
- writing data to the database before continuing other actions. Higher
- values take extra steps to ensure data safety at the cost of slower
- performance. A value of @code{0} will result in all handling being left
- to the filesystem itself. Set to @code{-1} to select the default value
- according to database mode controlled by
- @var{database-write-ahead-logging} setting. See SQLite documentation
- for more details regarding values from @code{1} to @code{3}. Value
- range: @samp{-1}..@samp{3}
- @item @code{database-write-ahead-logging?} (default: @code{#f}) (type: maybe-boolean)
- Enable or disable SQLite Write-Ahead Logging mode for the database. See
- SQLite documentation for more details and note that support for
- read-only operations isn't available in older SQLite versions.
- @item @code{hourly-days} (default: @code{4}) (type: maybe-integer)
- Data retention duration for the one hour resolution entries. The
- configuration defines for how many past days entries will be stored. Set
- to @code{-1} for unlimited entries or to @code{0} to disable the data
- collection of this resolution.
- @item @code{log-file} (type: maybe-string)
- Specify log file path and name to be used if @var{use-logging} is set to
- @code{1}.
- @item @code{max-bandwidth} (type: maybe-integer)
- Maximum bandwidth for all interfaces. If the interface specific traffic
- exceeds the given value then the data is assumed to be invalid and
- rejected. Set to 0 in order to disable the feature. Value range:
- @samp{0}..@samp{50000}
- @item @code{max-bw} (type: maybe-alist)
- Same as @var{max-bandwidth} but can be used for setting individual
- limits for selected interfaces. This is an association list of
- interfaces as strings to integer values. For example,
- @lisp
- (max-bw `(("eth0" . 15000)
- ("ppp0" . 10000)))
- @end lisp
- @var{bandwidth-detection} is disabled on an interface specific level for
- each @var{max-bw} configuration. Value range: @samp{0}..@samp{50000}
- @item @code{monthly-months} (default: @code{25}) (type: maybe-integer)
- Data retention duration for the one month resolution entries. The
- configuration defines for how many past months entries will be stored.
- Set to @code{-1} for unlimited entries or to @code{0} to disable the
- data collection of this resolution.
- @item @code{month-rotate} (default: @code{1}) (type: maybe-integer)
- Day of month that months are expected to change. Usually set to 1 but
- can be set to alternative values for example for tracking monthly billed
- traffic where the billing period doesn't start on the first day. For
- example, if set to 7, days of February up to and including the 6th will
- count for January. Changing this option will not cause existing data to
- be recalculated. Value range: @samp{1}..@samp{28}
- @item @code{month-rotate-affects-years?} (default: @code{#f}) (type: maybe-boolean)
- Enable or disable @var{month-rotate} also affecting yearly data.
- Applicable only when @var{month-rotate} has a value greater than one.
- @item @code{offline-save-interval} (default: @code{30}) (type: maybe-integer)
- How often in minutes cached interface data is saved to file when all
- monitored interfaces are offline. Value range:
- @var{save-interval}..@samp{60}
- @item @code{pid-file} (default: @code{"/var/run/vnstatd.pid"}) (type: maybe-string)
- Specify pid file path and name to be used.
- @item @code{poll-interval} (default: @code{5}) (type: maybe-integer)
- How often in seconds interfaces are checked for status changes. Value
- range: @samp{2}..@samp{60}
- @item @code{rescan-database-on-save?} (type: maybe-boolean)
- Automatically discover added interfaces from the database and start
- monitoring. The rescan is done every @var{save-interval} or
- @var{offline-save-interval} minutes depending on the current activity
- state.
- @item @code{save-interval} (default: @code{5}) (type: maybe-integer)
- How often in minutes cached interface data is saved to file. Value
- range: ( @var{update-interval} / 60 )..@samp{60}
- @item @code{save-on-status-change?} (default: @code{#t}) (type: maybe-boolean)
- Enable or disable the additional saving to file of cached interface data
- when the availability of an interface changes, i.e., when an interface
- goes offline or comes online.
- @item @code{time-sync-wait} (default: @code{5}) (type: maybe-integer)
- How many minutes to wait during daemon startup for system clock to sync
- if most recent database update appears to be in the future. This may be
- needed in systems without a real-time clock (RTC) which require some
- time after boot to query and set the correct time. @code{0} = wait
- disabled. Value range: @samp{0}..@samp{60}
- @item @code{top-day-entries} (default: @code{20}) (type: maybe-integer)
- Data retention duration for the top day entries. The configuration
- defines how many of the past top day entries will be stored. Set to
- @code{-1} for unlimited entries or to @code{0} to disable the data
- collection of this resolution.
- @item @code{trafficless-entries?} (default: @code{#t}) (type: maybe-boolean)
- Create database entries even when there is no traffic during the entry's
- time period.
- @item @code{update-file-owner?} (default: @code{#t}) (type: maybe-boolean)
- Enable or disable the update of file ownership during daemon process
- startup. During daemon startup, only database, log and pid files will
- be modified if the user or group change feature ( @var{daemon-user} or
- @var{daemon-group} ) is enabled and the files don't match the requested
- user or group. During manual database creation, this option will cause
- file ownership to be inherited from the database directory if the
- directory already exists. This option only has effect when the process
- is started as root or via sudo.
- @item @code{update-interval} (default: @code{20}) (type: maybe-integer)
- How often in seconds the interface data is updated. Value range:
- @var{poll-interval}..@samp{300}
- @item @code{use-logging} (default: @code{2}) (type: maybe-integer)
- Enable or disable logging. Accepted values are: @code{0} = disabled,
- @code{1} = logfile and @code{2} = syslog.
- @item @code{use-utc?} (type: maybe-boolean)
- Enable or disable using UTC as timezone in the database for all entries.
- When enabled, all entries added to the database will use UTC regardless
- of the configured system timezone. When disabled, the configured system
- timezone will be used. Changing this setting will not result in already
- existing data to be modified.
- @item @code{yearly-years} (default: @code{-1}) (type: maybe-integer)
- Data retention duration for the one year resolution entries. The
- configuration defines for how many past years entries will be stored.
- Set to @code{-1} for unlimited entries or to @code{0} to disable the
- data collection of this resolution.
- @end table
- @end deftp
- @c %end of fragment
- @subsubheading Zabbix server
- @cindex zabbix zabbix-server
- Zabbix is a high performance monitoring system that can collect data from a
- variety of sources and provide the results in a web-based interface. Alerting
- and reporting is built-in, as well as @dfn{templates} for common operating
- system metrics such as network utilization, CPU load, and disk space consumption.
- This service provides the central Zabbix monitoring service; you also need
- @ref{zabbix-front-end,@code{zabbix-front-end-service-type}} to configure Zabbix
- and display results, and optionally @ref{zabbix-agent,
- @code{zabbix-agent-service-type}} on machines that should be monitored (other
- data sources are supported, such as @ref{prometheus-node-exporter,
- Prometheus Node Exporter}).
- @defvar zabbix-server-service-type
- This is the service type for the Zabbix server service. Its value must be a
- @code{zabbix-server-configuration} record, shown below.
- @end defvar
- @c %start of fragment
- @deftp {Data Type} zabbix-server-configuration
- Available @code{zabbix-server-configuration} fields are:
- @table @asis
- @item @code{zabbix-server} (default: @code{zabbix-server}) (type: file-like)
- The zabbix-server package.
- @item @code{user} (default: @code{"zabbix"}) (type: string)
- User who will run the Zabbix server.
- @item @code{group} (default: @code{"zabbix"}) (type: string)
- Group who will run the Zabbix server.
- @item @code{db-host} (default: @code{"127.0.0.1"}) (type: string)
- Database host name.
- @item @code{db-name} (default: @code{"zabbix"}) (type: string)
- Database name.
- @item @code{db-user} (default: @code{"zabbix"}) (type: string)
- Database user.
- @item @code{db-password} (default: @code{""}) (type: string)
- Database password. Please, use @code{include-files} with
- @code{DBPassword=SECRET} inside a specified file instead.
- @item @code{db-port} (default: @code{5432}) (type: number)
- Database port.
- @item @code{log-type} (default: @code{""}) (type: string)
- Specifies where log messages are written to:
- @itemize @bullet
- @item @code{system} - syslog.
- @item @code{file} - file specified with @code{log-file} parameter.
- @item @code{console} - standard output.
- @end itemize
- @item @code{log-file} (default: @code{"/var/log/zabbix/server.log"}) (type: string)
- Log file name for @code{log-type} @code{file} parameter.
- @item @code{pid-file} (default: @code{"/var/run/zabbix/zabbix_server.pid"}) (type: string)
- Name of PID file.
- @item @code{ssl-ca-location} (default: @code{"/etc/ssl/certs/ca-certificates.crt"}) (type: string)
- The location of certificate authority (CA) files for SSL server
- certificate verification.
- @item @code{ssl-cert-location} (default: @code{"/etc/ssl/certs"}) (type: string)
- Location of SSL client certificates.
- @item @code{extra-options} (default: @code{""}) (type: extra-options)
- Extra options will be appended to Zabbix server configuration file.
- @item @code{include-files} (default: @code{'()}) (type: include-files)
- You may include individual files or all files in a directory in the
- configuration file.
- @end table
- @end deftp
- @c %end of fragment
- @anchor{zabbix-agent}
- @subsubheading Zabbix agent
- @cindex zabbix zabbix-agent
- The Zabbix agent gathers information about the running system for the Zabbix
- monitoring server. It has a variety of built-in checks, and can be extended
- with custom
- @uref{https://www.zabbix.com/documentation/current/en/manual/config/items/userparameters,
- @dfn{user parameters}}.
- @defvar zabbix-agent-service-type
- This is the service type for the Zabbix agent service. Its value must be a
- @code{zabbix-agent-configuration} record, shown below.
- @end defvar
- @c %start of fragment
- @deftp {Data Type} zabbix-agent-configuration
- Available @code{zabbix-agent-configuration} fields are:
- @table @asis
- @item @code{zabbix-agent} (default: @code{zabbix-agentd}) (type: file-like)
- The zabbix-agent package.
- @item @code{user} (default: @code{"zabbix"}) (type: string)
- User who will run the Zabbix agent.
- @item @code{group} (default: @code{"zabbix"}) (type: string)
- Group who will run the Zabbix agent.
- @item @code{hostname} (default: @code{""}) (type: string)
- Unique, case sensitive hostname which is required for active checks and
- must match hostname as configured on the server.
- @item @code{log-type} (default: @code{""}) (type: string)
- Specifies where log messages are written to:
- @itemize @bullet
- @item
- @code{system} - syslog.
- @item @code{file} - file specified with
- @code{log-file} parameter.
- @item @code{console} - standard output.
- @end itemize
- @item @code{log-file} (default: @code{"/var/log/zabbix/agent.log"}) (type: string)
- Log file name for @code{log-type} @code{file} parameter.
- @item @code{pid-file} (default: @code{"/var/run/zabbix/zabbix_agent.pid"}) (type: string)
- Name of PID file.
- @item @code{server} (default: @code{'("127.0.0.1")}) (type: list)
- List of IP addresses, optionally in CIDR notation, or hostnames of
- Zabbix servers and Zabbix proxies. Incoming connections will be
- accepted only from the hosts listed here.
- @item @code{server-active} (default: @code{'("127.0.0.1")}) (type: list)
- List of IP:port (or hostname:port) pairs of Zabbix servers and Zabbix
- proxies for active checks. If port is not specified, default port is
- used. If this parameter is not specified, active checks are disabled.
- @item @code{extra-options} (default: @code{""}) (type: extra-options)
- Extra options will be appended to Zabbix server configuration file.
- @item @code{include-files} (default: @code{'()}) (type: include-files)
- You may include individual files or all files in a directory in the
- configuration file.
- @end table
- @end deftp
- @c %end of fragment
- @anchor{zabbix-front-end}
- @subsubheading Zabbix front-end
- @cindex zabbix zabbix-front-end
- The Zabbix front-end provides a web interface to Zabbix. It does not need
- to run on the same machine as the Zabbix server. This service works by
- extending the @ref{PHP-FPM} and @ref{NGINX} services with the configuration
- necessary for loading the Zabbix user interface.
- @defvar zabbix-front-end-service-type
- This is the service type for the Zabbix web frontend. Its value must be a
- @code{zabbix-front-end-configuration} record, shown below.
- @end defvar
- @c %start of fragment
- @deftp {Data Type} zabbix-front-end-configuration
- Available @code{zabbix-front-end-configuration} fields are:
- @table @asis
- @item @code{zabbix-server} (default: @code{zabbix-server}) (type: file-like)
- The Zabbix server package to use.
- @item @code{nginx} (default: @code{'()}) (type: list)
- List of @ref{nginx-server-configuration,@code{nginx-server-configuration}}
- blocks for the Zabbix front-end. When empty, a default that listens on
- port 80 is used.
- @item @code{db-host} (default: @code{"localhost"}) (type: string)
- Database host name.
- @item @code{db-port} (default: @code{5432}) (type: number)
- Database port.
- @item @code{db-name} (default: @code{"zabbix"}) (type: string)
- Database name.
- @item @code{db-user} (default: @code{"zabbix"}) (type: string)
- Database user.
- @item @code{db-password} (default: @code{""}) (type: string)
- Database password. Please, use @code{db-secret-file} instead.
- @item @code{db-secret-file} (default: @code{""}) (type: string)
- Secret file which will be appended to @file{zabbix.conf.php} file. This
- file contains credentials for use by Zabbix front-end. You are expected
- to create it manually.
- @item @code{zabbix-host} (default: @code{"localhost"}) (type: string)
- Zabbix server hostname.
- @item @code{zabbix-port} (default: @code{10051}) (type: number)
- Zabbix server port.
- @end table
- @end deftp
- @c %end of fragment
- @node Kerberos Services
- @subsection Kerberos Services
- @cindex Kerberos
- The @code{(gnu services kerberos)} module provides services relating to
- the authentication protocol @dfn{Kerberos}.
- @subsubheading Krb5 Service
- Programs using a Kerberos client library normally
- expect a configuration file in @file{/etc/krb5.conf}.
- This service generates such a file from a definition provided in the
- operating system declaration.
- It does not cause any daemon to be started.
- No ``keytab'' files are provided by this service---you must explicitly create them.
- This service is known to work with the MIT client library, @code{mit-krb5}.
- Other implementations have not been tested.
- @defvar krb5-service-type
- A service type for Kerberos 5 clients.
- @end defvar
- @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.
- @defvar pam-krb5-service-type
- A service type for the Kerberos 5 PAM module.
- @end defvar
- @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
- @subsubheading Authentication against LDAP with nslcd
- @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
- @subsubheading LDAP Directory Server
- @cindex LDAP, server
- The @code{(gnu services ldap)} module provides the
- @code{directory-server-service-type}, which can be used to create and
- launch an LDAP server instance.
- Here is an example configuration of the
- @code{directory-server-service-type}:
- @lisp
- (use-service-modules ldap)
- ...
- (operating-system
- ...
- (services
- (cons
- (service directory-server-service-type
- (directory-server-instance-configuration
- (slapd
- (slapd-configuration
- (root-password "@{PBKDF2_SHA256@}AAAgAG@dots{}ABSOLUTELYSECRET")))))
- %base-services)))
- @end lisp
- The root password should be generated with the @command{pwdhash} utility
- that is provided by the @code{389-ds-base} package.
- Note that changes to the directory server configuration will not be
- applied to existing instances. You will need to back up and restore
- server data manually. Only new directory server instances will be
- created upon system reconfiguration.
- @c %start of generated documentation for directory-server-instance-configuration
- @deftp {Data Type} directory-server-instance-configuration
- Available @code{directory-server-instance-configuration} fields are:
- @table @asis
- @item @code{package} (default: @code{389-ds-base}) (type: file-like)
- The @code{389-ds-base} package.
- @item @code{config-version} (default: @code{2}) (type: number)
- Sets the format version of the configuration file. To use the INF file
- with @command{dscreate}, this parameter must be 2.
- @item @code{full-machine-name} (default: @code{"localhost"}) (type: string)
- Sets the fully qualified hostname (FQDN) of this system.
- @item @code{selinux} (default: @code{#false}) (type: boolean)
- Enables SELinux detection and integration during the installation of
- this instance. If set to @code{#true}, @command{dscreate} auto-detects
- whether SELinux is enabled.
- @item @code{strict-host-checking} (default: @code{#true}) (type: boolean)
- Sets whether the server verifies the forward and reverse record set in
- the @code{full-machine-name} parameter. When installing this instance with
- GSSAPI authentication behind a load balancer, set this parameter to
- @code{#false}.
- @item @code{systemd} (default: @code{#false}) (type: boolean)
- Enables systemd platform features. If set to @code{#true},
- @command{dscreate} auto-detects whether systemd is installed.
- @item @code{slapd} (type: slapd-configuration)
- Configuration of slapd.
- @deftp {Data Type} slapd-configuration
- Available @code{slapd-configuration} fields are:
- @table @asis
- @item @code{instance-name} (default: @code{"localhost"}) (type: string)
- Sets the name of the instance. You can refer to this value in other
- parameters of this INF file using the @code{@{instance_name@}} variable.
- Note that this name cannot be changed after the installation!
- @item @code{user} (default: @code{"dirsrv"}) (type: string)
- Sets the user name the ns-slapd process will use after the service
- started.
- @item @code{group} (default: @code{"dirsrv"}) (type: string)
- Sets the group name the ns-slapd process will use after the service
- started.
- @item @code{port} (default: @code{389}) (type: number)
- Sets the TCP port the instance uses for LDAP connections.
- @item @code{secure-port} (default: @code{636}) (type: number)
- Sets the TCP port the instance uses for TLS-secured LDAP connections
- (LDAPS).
- @item @code{root-dn} (default: @code{"cn=Directory Manager"}) (type: string)
- Sets the @dfn{Distinquished Name} (DN) of the administrator account for this
- instance.
- @item @code{root-password} (default: @code{"@{invalid@}YOU-SHOULD-CHANGE-THIS"}) (type: string)
- Sets the password of the account specified in the @code{root-dn}
- parameter. You can either set this parameter to a plain text password
- @command{dscreate} hashes during the installation or to a
- "@{algorithm@}hash" string generated by the @command{pwdhash} utility.
- Note that setting a plain text password can be a security risk if
- unprivileged users can read this INF file!
- @item @code{self-sign-cert} (default: @code{#true}) (type: boolean)
- Sets whether the setup creates a self-signed certificate and enables TLS
- encryption during the installation. This is not suitable for
- production, but it enables administrators to use TLS right after the
- installation. You can replace the self-signed certificate with a
- certificate issued by a certificate authority.
- @item @code{self-sign-cert-valid-months} (default: @code{24}) (type: number)
- Set the number of months the issued self-signed certificate will be
- valid.
- @item @code{backup-dir} (default: @code{"/var/lib/dirsrv/slapd-@{instance_name@}/bak"}) (type: string)
- Set the backup directory of the instance.
- @item @code{cert-dir} (default: @code{"/etc/dirsrv/slapd-@{instance_name@}"}) (type: string)
- Sets the directory of the instance's Network Security Services (NSS)
- database.
- @item @code{config-dir} (default: @code{"/etc/dirsrv/slapd-@{instance_name@}"}) (type: string)
- Sets the configuration directory of the instance.
- @item @code{db-dir} (default: @code{"/var/lib/dirsrv/slapd-@{instance_name@}/db"}) (type: string)
- Sets the database directory of the instance.
- @item @code{initconfig-dir} (default: @code{"/etc/dirsrv/registry"}) (type: string)
- Sets the directory of the operating system's rc configuration directory.
- @item @code{ldif-dir} (default: @code{"/var/lib/dirsrv/slapd-@{instance_name@}/ldif"}) (type: string)
- Sets the LDIF export and import directory of the instance.
- @item @code{lock-dir} (default: @code{"/var/lock/dirsrv/slapd-@{instance_name@}"}) (type: string)
- Sets the lock directory of the instance.
- @item @code{log-dir} (default: @code{"/var/log/dirsrv/slapd-@{instance_name@}"}) (type: string)
- Sets the log directory of the instance.
- @item @code{run-dir} (default: @code{"/run/dirsrv"}) (type: string)
- Sets PID directory of the instance.
- @item @code{schema-dir} (default: @code{"/etc/dirsrv/slapd-@{instance_name@}/schema"}) (type: string)
- Sets schema directory of the instance.
- @item @code{tmp-dir} (default: @code{"/tmp"}) (type: string)
- Sets the temporary directory of the instance.
- @end table
- @end deftp
- @item @code{backend-userroot} (type: backend-userroot-configuration)
- Configuration of the userroot backend.
- @deftp {Data Type} backend-userroot-configuration
- Available @code{backend-userroot-configuration} fields are:
- @table @asis
- @item @code{create-suffix-entry?} (default: @code{#false}) (type: boolean)
- Set this parameter to @code{#true} to create a generic root node entry
- for the suffix in the database.
- @item @code{require-index?} (default: @code{#false}) (type: boolean)
- Set this parameter to @code{#true} to refuse unindexed searches in this
- database.
- @item @code{sample-entries} (default: @code{"no"}) (type: string)
- Set this parameter to @code{"yes"} to add latest version of sample
- entries to this database. Or, use @code{"001003006"} to use the 1.3.6
- version sample entries. Use this option, for example, to create a
- database for testing purposes.
- @item @code{suffix} (type: maybe-string)
- Sets the root suffix stored in this database. If you do not set the
- suffix attribute the install process will not create the backend/suffix.
- You can also create multiple backends/suffixes by duplicating this
- section.
- @end table
- @end deftp
- @end table
- @end deftp
- @c end of generated documentation for directory-server
- @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
- @defvar 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 defvar
- The details for the @code{httpd-configuration}, @code{httpd-module},
- @code{httpd-config-file} and @code{httpd-virtualhost} record types are
- given below.
- @deftp {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 deftp
- @deftp {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 deftp
- @defvar %default-httpd-modules
- A default list of @code{httpd-module} objects.
- @end defvar
- @deftp {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 deftp
- @deftp {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 deftp
- @anchor{NGINX}
- @subsubheading NGINX
- @defvar 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 defvar
- 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.
- @deftp {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{shepherd-requirement} (default: @code{'()})
- This is a list of symbols naming Shepherd services the nginx service
- will depend on.
- This is useful if you would like @command{nginx} to be started after a
- back-end web server or a logging service such as Anonip has been
- started.
- @item @code{log-directory} (default: @code{"/var/log/nginx"})
- The directory to which NGinx will write log files.
- @item @code{log-level} (default: @code{'error}) (type: symbol)
- Logging level, which can be any of the following values: @code{'debug},
- @code{'info}, @code{'notice}, @code{'warn}, @code{'error}, @code{'crit},
- @code{'alert}, or @code{'emerg}.
- @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 deftp
- @anchor{nginx-server-configuration}
- @deftp {Data Type} nginx-server-configuration
- Data type representing the configuration of an nginx server block.
- This type has the following parameters:
- @table @asis
- @item @code{listen} (default: @code{'("80" "443 ssl")})
- Each @code{listen} directive sets the address and port for IP, or the
- path for a UNIX-domain socket on which the server will accept requests.
- Both address and port, or only address or only port can be specified.
- An address may also be a hostname, for example:
- @lisp
- '("127.0.0.1:8000" "127.0.0.1" "8000" "*:8000" "localhost:8000")
- @end lisp
- @item @code{server-name} (default: @code{(list 'default)})
- A list of server names this server represents. @code{'default} represents the
- default server for connections matching no other server.
- @item @code{root} (default: @code{"/srv/http"})
- Root of the website nginx will serve.
- @item @code{locations} (default: @code{'()})
- A list of @dfn{nginx-location-configuration} or
- @dfn{nginx-named-location-configuration} records to use within this
- server block.
- @item @code{index} (default: @code{(list "index.html")})
- Index files to look for when clients ask for a directory. If it cannot be found,
- Nginx will send the list of files in the directory.
- @item @code{try-files} (default: @code{'()})
- A list of files whose existence is checked in the specified order.
- @code{nginx} will use the first file it finds to process the request.
- @item @code{ssl-certificate} (default: @code{#f})
- Where to find the certificate for secure connections. Set it to @code{#f} if
- you don't have a certificate or you don't want to use HTTPS.
- @item @code{ssl-certificate-key} (default: @code{#f})
- Where to find the private key for secure connections. Set it to @code{#f} if
- you don't have a key or you don't want to use HTTPS.
- @item @code{server-tokens?} (default: @code{#f})
- Whether the server should add its configuration to response.
- @item @code{raw-content} (default: @code{'()})
- A list of raw lines added to the server block.
- @end table
- @end deftp
- @deftp {Data Type} nginx-upstream-configuration
- Data type representing the configuration of an nginx @code{upstream}
- block. This type has the following parameters:
- @table @asis
- @item @code{name}
- Name for this group of servers.
- @item @code{servers}
- Specify the addresses of the servers in the group. The address can be
- specified as a IP address (e.g.@: @samp{127.0.0.1}), domain name
- (e.g.@: @samp{backend1.example.com}) or a path to a UNIX socket using the
- prefix @samp{unix:}. For addresses using an IP address or domain name,
- the default port is 80, and a different port can be specified
- explicitly.
- @item @code{extra-content}
- A string or list of strings to add to the upstream block.
- @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.
- @defvar varnish-service-type
- Service type for the Varnish daemon.
- @end defvar
- @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.
- @defvar patchwork-service-type
- Service type for Patchwork.
- @end defvar
- 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.savannah.gnu.org/cgit/guix/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.
- @defvar mumi-service-type
- This is the service type for Mumi.
- @end defvar
- @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.
- @defvar fcgiwrap-service-type
- A service type for the @code{fcgiwrap} FastCGI proxy.
- @end defvar
- @deftp {Data Type} fcgiwrap-configuration
- Data type representing the configuration of the @code{fcgiwrap} service.
- This type has the following parameters:
- @table @asis
- @item @code{package} (default: @code{fcgiwrap})
- The fcgiwrap package to use.
- @item @code{socket} (default: @code{tcp:127.0.0.1:9000})
- The socket on which the @code{fcgiwrap} process should listen, as a
- string. Valid @var{socket} values include
- @code{unix:@var{/path/to/unix/socket}},
- @code{tcp:@var{dot.ted.qu.ad}:@var{port}} and
- @code{tcp6:[@var{ipv6_addr}]:port}.
- @item @code{user} (default: @code{fcgiwrap})
- @itemx @code{group} (default: @code{fcgiwrap})
- The user and group names, as strings, under which to run the
- @code{fcgiwrap} process. The @code{fastcgi} service will ensure that if
- the user asks for the specific user or group names @code{fcgiwrap} that
- the corresponding user and/or group is present on the system.
- It is possible to configure a FastCGI-backed web service to pass HTTP
- authentication information from the front-end to the back-end, and to
- allow @code{fcgiwrap} to run the back-end process as a corresponding
- local user. To enable this capability on the back-end, run
- @code{fcgiwrap} as the @code{root} user and group. Note that this
- capability also has to be configured on the front-end as well.
- @end table
- @end deftp
- @anchor{PHP-FPM}
- @subsubheading PHP-FPM
- @cindex php-fpm
- PHP-FPM (FastCGI Process Manager) is an alternative PHP FastCGI implementation
- with some additional features useful for sites of any size.
- These features include:
- @itemize @bullet
- @item Adaptive process spawning
- @item Basic statistics (similar to Apache's mod_status)
- @item Advanced process management with graceful stop/start
- @item Ability to start workers with different uid/gid/chroot/environment
- and different php.ini (replaces safe_mode)
- @item Stdout & stderr logging
- @item Emergency restart in case of accidental opcode cache destruction
- @item Accelerated upload support
- @item Support for a "slowlog"
- @item Enhancements to FastCGI, such as fastcgi_finish_request() -
- a special function to finish request & flush all data while continuing to do
- something time-consuming (video converting, stats processing, etc.)
- @end itemize
- ...@: and much more.
- @defvar php-fpm-service-type
- A Service type for @code{php-fpm}.
- @end defvar
- @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 {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 {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.
- @defvar hpcguix-web-service-type
- The service type for @code{hpcguix-web}.
- @end defvar
- @deftp {Data Type} hpcguix-web-configuration
- Data type for the hpcguix-web service configuration.
- @table @asis
- @item @code{specs} (default: @code{#f})
- Either @code{#f} or a gexp (@pxref{G-Expressions}) specifying the
- hpcguix-web service configuration as an @code{hpcguix-web-configuration}
- record. The main fields of that record type 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 to use in examples that appear on HTML pages.
- @item @code{package-filter-proc} (default: @code{(const #t)})
- A procedure specifying how to filter packages that are displayed.
- @item @code{package-page-extension-proc} (default: @code{(const '())})
- Extension package for @code{hpcguix-web}.
- @item @code{menu} (default: @code{'()})
- Additional entry in page @code{menu}.
- @item @code{channels} (default: @code{%default-channels})
- List of channels from which the package list is built (@pxref{Channels}).
- @item @code{package-list-expiration} (default: @code{(* 12 3600)})
- The expiration time, in seconds, after which the package list is rebuilt from
- the latest instances of the given channels.
- @end table
- See the hpcguix-web repository for a
- @uref{https://github.com/UMCUGenetics/hpcguix-web/blob/master/hpcweb-configuration.scm,
- complete example}.
- @item @code{package} (default: @code{hpcguix-web})
- The hpcguix-web package to use.
- @item @code{address} (default: @code{"127.0.0.1"})
- The IP address to listen to.
- @item @code{port} (default: @code{5000})
- The port number to listen to.
- @end table
- @end deftp
- A typical hpcguix-web service declaration looks like this:
- @lisp
- (service hpcguix-web-service-type
- (hpcguix-web-configuration
- (specs
- #~(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.
- @defvar 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 defvar
- @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.
- @defvar 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 defvar
- @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}.
- @defvar 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 defvar
- @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
- @defvar 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 defvar
- @deftp {Data Type} knot-key-configuration
- Data type representing a key.
- This type has the following parameters:
- @table @asis
- @item @code{id} (default: @code{""})
- An identifier for other configuration fields to refer to this key. IDs must
- be unique and must not be empty.
- @item @code{algorithm} (default: @code{#f})
- The algorithm to use. Choose between @code{#f}, @code{'hmac-md5},
- @code{'hmac-sha1}, @code{'hmac-sha224}, @code{'hmac-sha256}, @code{'hmac-sha384}
- and @code{'hmac-sha512}.
- @item @code{secret} (default: @code{""})
- The secret key itself.
- @end table
- @end deftp
- @deftp {Data Type} knot-acl-configuration
- Data type representing an Access Control List (ACL) configuration.
- This type has the following parameters:
- @table @asis
- @item @code{id} (default: @code{""})
- An identifier for other configuration fields to refer to this key. IDs must be
- unique and must not be empty.
- @item @code{address} (default: @code{'()})
- An ordered list of IP addresses, network subnets, or network ranges represented
- with strings. The query must match one of them. Empty value means that
- address match is not required.
- @item @code{key} (default: @code{'()})
- An ordered list of references to keys represented with strings. The string
- must match a key ID defined in a @code{knot-key-configuration}. No key means
- that a key is not require to match that ACL.
- @item @code{action} (default: @code{'()})
- An ordered list of actions that are permitted or forbidden by this ACL@. Possible
- values are lists of zero or more elements from @code{'transfer}, @code{'notify}
- and @code{'update}.
- @item @code{deny?} (default: @code{#f})
- When true, the ACL defines restrictions. Listed actions are forbidden. When
- false, listed actions are allowed.
- @end table
- @end deftp
- @deftp {Data Type} zone-entry
- Data type representing a record entry in a zone file.
- This type has the following parameters:
- @table @asis
- @item @code{name} (default: @code{"@@"})
- The name of the record. @code{"@@"} refers to the origin of the zone. Names
- are relative to the origin of the zone. For example, in the @code{example.org}
- zone, @code{"ns.example.org"} actually refers to @code{ns.example.org.example.org}.
- Names ending with a dot are absolute, which means that @code{"ns.example.org."}
- refers to @code{ns.example.org}.
- @item @code{ttl} (default: @code{""})
- The Time-To-Live (TTL) of this record. If not set, the default TTL is used.
- @item @code{class} (default: @code{"IN"})
- The class of the record. Knot currently supports only @code{"IN"} and
- partially @code{"CH"}.
- @item @code{type} (default: @code{"A"})
- The type of the record. Common types include A (IPv4 address), AAAA (IPv6
- address), NS (Name Server) and MX (Mail eXchange). Many other types are
- defined.
- @item @code{data} (default: @code{""})
- The data contained in the record. For instance an IP address associated with
- an A record, or a domain name associated with an NS record. Remember that
- domain names are relative to the origin unless they end with a dot.
- @end table
- @end deftp
- @deftp {Data Type} zone-file
- Data type representing the content of a zone file.
- This type has the following parameters:
- @table @asis
- @item @code{entries} (default: @code{'()})
- The list of entries. The SOA record is taken care of, so you don't need to
- put it in the list of entries. This list should probably contain an entry
- for your primary authoritative DNS server. Other than using a list of entries
- directly, you can use @code{define-zone-entries} to define a object containing
- the list of entries more easily, that you can later pass to the @code{entries}
- field of the @code{zone-file}.
- @item @code{origin} (default: @code{""})
- The name of your zone. This parameter cannot be empty.
- @item @code{ns} (default: @code{"ns"})
- The domain of your primary authoritative DNS server. The name is relative to
- the origin, unless it ends with a dot. It is mandatory that this primary
- DNS server corresponds to an NS record in the zone and that it is associated
- to an IP address in the list of entries.
- @item @code{mail} (default: @code{"hostmaster"})
- An email address people can contact you at, as the owner of the zone. This
- is translated as @code{<mail>@@<origin>}.
- @item @code{serial} (default: @code{1})
- The serial number of the zone. As this is used to keep track of changes by
- both slaves and resolvers, it is mandatory that it @emph{never} decreases.
- Always increment it when you make a change in your zone.
- @item @code{refresh} (default: @code{(* 2 24 3600)})
- The frequency at which slaves will do a zone transfer. This value is a number
- of seconds. It can be computed by multiplications or with
- @code{(string->duration)}.
- @item @code{retry} (default: @code{(* 15 60)})
- The period after which a slave will retry to contact its master when it fails
- to do so a first time.
- @item @code{expiry} (default: @code{(* 14 24 3600)})
- Default TTL of records. Existing records are considered correct for at most
- this amount of time. After this period, resolvers will invalidate their cache
- and check again that it still exists.
- @item @code{nx} (default: @code{3600})
- Default TTL of inexistent records. This delay is usually short because you want
- your new domains to reach everyone quickly.
- @end table
- @end deftp
- @deftp {Data Type} knot-remote-configuration
- Data type representing a remote configuration.
- This type has the following parameters:
- @table @asis
- @item @code{id} (default: @code{""})
- An identifier for other configuration fields to refer to this remote. IDs must
- be unique and must not be empty.
- @item @code{address} (default: @code{'()})
- An ordered list of destination IP addresses. Addresses are tried in sequence.
- An optional port can be given with the @@ separator. For instance:
- @code{(list "1.2.3.4" "2.3.4.5@@53")}. Default port is 53.
- @item @code{via} (default: @code{'()})
- An ordered list of source IP addresses. An empty list will have Knot choose
- an appropriate source IP@. An optional port can be given with the @@ separator.
- The default is to choose at random.
- @item @code{key} (default: @code{#f})
- A reference to a key, that is a string containing the identifier of a key
- defined in a @code{knot-key-configuration} field.
- @end table
- @end deftp
- @deftp {Data Type} knot-keystore-configuration
- Data type representing a keystore to hold dnssec keys.
- This type has the following parameters:
- @table @asis
- @item @code{id} (default: @code{""})
- The id of the keystore. It must not be empty.
- @item @code{backend} (default: @code{'pem})
- The backend to store the keys in. Can be @code{'pem} or @code{'pkcs11}.
- @item @code{config} (default: @code{"/var/lib/knot/keys/keys"})
- The configuration string of the backend. An example for the PKCS#11 is:
- @code{"pkcs11:token=knot;pin-value=1234 /gnu/store/.../lib/pkcs11/libsofthsm2.so"}.
- For the pem backend, the string represents a path in the file system.
- @end table
- @end deftp
- @deftp {Data Type} knot-policy-configuration
- Data type representing a dnssec policy. Knot DNS is able to automatically
- sign your zones. It can either generate and manage your keys automatically or
- use keys that you generate.
- Dnssec is usually implemented using two keys: a Key Signing Key (KSK) that is
- used to sign the second, and a Zone Signing Key (ZSK) that is used to sign the
- zone. In order to be trusted, the KSK needs to be present in the parent zone
- (usually a top-level domain). If your registrar supports dnssec, you will
- have to send them your KSK's hash so they can add a DS record in their zone.
- This is not automated and need to be done each time you change your KSK.
- The policy also defines the lifetime of keys. Usually, ZSK can be changed
- easily and use weaker cryptographic functions (they use lower parameters) in
- order to sign records quickly, so they are changed often. The KSK however
- requires manual interaction with the registrar, so they are changed less often
- and use stronger parameters because they sign only one record.
- This type has the following parameters:
- @table @asis
- @item @code{id} (default: @code{""})
- The id of the policy. It must not be empty.
- @item @code{keystore} (default: @code{"default"})
- A reference to a keystore, that is a string containing the identifier of a
- keystore defined in a @code{knot-keystore-configuration} field. The
- @code{"default"} identifier means the default keystore (a kasp database that
- was setup by this service).
- @item @code{manual?} (default: @code{#f})
- Whether the key management is manual or automatic.
- @item @code{single-type-signing?} (default: @code{#f})
- When @code{#t}, use the Single-Type Signing Scheme.
- @item @code{algorithm} (default: @code{"ecdsap256sha256"})
- An algorithm of signing keys and issued signatures.
- @item @code{ksk-size} (default: @code{256})
- The length of the KSK@. Note that this value is correct for the default
- algorithm, but would be unsecure for other algorithms.
- @item @code{zsk-size} (default: @code{256})
- The length of the ZSK@. Note that this value is correct for the default
- algorithm, but would be unsecure for other algorithms.
- @item @code{dnskey-ttl} (default: @code{'default})
- The TTL value for DNSKEY records added into zone apex. The special
- @code{'default} value means same as the zone SOA TTL.
- @item @code{zsk-lifetime} (default: @code{(* 30 24 3600)})
- The period between ZSK publication and the next rollover initiation.
- @item @code{propagation-delay} (default: @code{(* 24 3600)})
- An extra delay added for each key rollover step. This value should be high
- enough to cover propagation of data from the master server to all slaves.
- @item @code{rrsig-lifetime} (default: @code{(* 14 24 3600)})
- A validity period of newly issued signatures.
- @item @code{rrsig-refresh} (default: @code{(* 7 24 3600)})
- A period how long before a signature expiration the signature will be refreshed.
- @item @code{nsec3?} (default: @code{#f})
- When @code{#t}, NSEC3 will be used instead of NSEC.
- @item @code{nsec3-iterations} (default: @code{5})
- The number of additional times the hashing is performed.
- @item @code{nsec3-salt-length} (default: @code{8})
- The length of a salt field in octets, which is appended to the original owner
- name before hashing.
- @item @code{nsec3-salt-lifetime} (default: @code{(* 30 24 3600)})
- The validity period of newly issued salt field.
- @end table
- @end deftp
- @deftp {Data Type} knot-zone-configuration
- Data type representing a zone served by Knot.
- This type has the following parameters:
- @table @asis
- @item @code{domain} (default: @code{""})
- The domain served by this configuration. It must not be empty.
- @item @code{file} (default: @code{""})
- The file where this zone is saved. This parameter is ignored by master zones.
- Empty means default location that depends on the domain name.
- @item @code{zone} (default: @code{(zone-file)})
- The content of the zone file. This parameter is ignored by slave zones. It
- must contain a zone-file record.
- @item @code{master} (default: @code{'()})
- A list of master remotes. When empty, this zone is a master. When set, this
- zone is a slave. This is a list of remotes identifiers.
- @item @code{ddns-master} (default: @code{#f})
- The main master. When empty, it defaults to the first master in the list of
- masters.
- @item @code{notify} (default: @code{'()})
- A list of slave remote identifiers.
- @item @code{acl} (default: @code{'()})
- A list of acl identifiers.
- @item @code{semantic-checks?} (default: @code{#f})
- When set, this adds more semantic checks to the zone.
- @item @code{zonefile-sync} (default: @code{0})
- The delay between a modification in memory and on disk. 0 means immediate
- synchronization.
- @item @code{zonefile-load} (default: @code{#f})
- The way the zone file contents are applied during zone load. Possible values
- are:
- @itemize
- @item @code{#f} for using the default value from Knot,
- @item @code{'none} for not using the zone file at all,
- @item @code{'difference} for computing the difference between already available
- contents and zone contents and applying it to the current zone contents,
- @item @code{'difference-no-serial} for the same as @code{'difference}, but
- ignoring the SOA serial in the zone file, while the server takes care of it
- automatically.
- @item @code{'whole} for loading zone contents from the zone file.
- @end itemize
- @item @code{journal-content} (default: @code{#f})
- The way the journal is used to store zone and its changes. Possible values
- are @code{'none} to not use it at all, @code{'changes} to store changes and
- @code{'all} to store contents. @code{#f} does not set this option, so the
- default value from Knot is used.
- @item @code{max-journal-usage} (default: @code{#f})
- The maximum size for the journal on disk. @code{#f} does not set this option,
- so the default value from Knot is used.
- @item @code{max-journal-depth} (default: @code{#f})
- The maximum size of the history. @code{#f} does not set this option, so the
- default value from Knot is used.
- @item @code{max-zone-size} (default: @code{#f})
- The maximum size of the zone file. This limit is enforced for incoming
- transfer and updates. @code{#f} does not set this option, so the default
- value from Knot is used.
- @item @code{dnssec-policy} (default: @code{#f})
- A reference to a @code{knot-policy-configuration} record, or the special
- name @code{"default"}. If the value is @code{#f}, there is no dnssec signing
- on this zone.
- @item @code{serial-policy} (default: @code{'increment})
- A policy between @code{'increment} and @code{'unixtime}.
- @end table
- @end deftp
- @deftp {Data Type} knot-configuration
- Data type representing the Knot configuration.
- This type has the following parameters:
- @table @asis
- @item @code{knot} (default: @code{knot})
- The Knot package.
- @item @code{run-directory} (default: @code{"/var/run/knot"})
- The run directory. This directory will be used for pid file and sockets.
- @item @code{includes} (default: @code{'()})
- A list of strings or file-like objects denoting other files that must be
- included at the top of the configuration file.
- @cindex secrets, Knot service
- This can be used to manage secrets out-of-band. For example, secret
- keys may be stored in an out-of-band file not managed by Guix, and
- thus not visible in @file{/gnu/store}---e.g., you could store secret
- key configuration in @file{/etc/knot/secrets.conf} and add this file
- to the @code{includes} list.
- One can generate a secret tsig key (for nsupdate and zone transfers with the
- keymgr command from the knot package. Note that the package is not automatically
- installed by the service. The following example shows how to generate a new
- tsig key:
- @example
- keymgr -t mysecret > /etc/knot/secrets.conf
- chmod 600 /etc/knot/secrets.conf
- @end example
- Also note that the generated key will be named @var{mysecret}, so it is the
- name that needs to be used in the @var{key} field of the
- @code{knot-acl-configuration} record and in other places that need to refer
- to that key.
- It can also be used to add configuration not supported by this interface.
- @item @code{listen-v4} (default: @code{"0.0.0.0"})
- An ip address on which to listen.
- @item @code{listen-v6} (default: @code{"::"})
- An ip address on which to listen.
- @item @code{listen-port} (default: @code{53})
- A port on which to listen.
- @item @code{keys} (default: @code{'()})
- The list of knot-key-configuration used by this configuration.
- @item @code{acls} (default: @code{'()})
- The list of knot-acl-configuration used by this configuration.
- @item @code{remotes} (default: @code{'()})
- The list of knot-remote-configuration used by this configuration.
- @item @code{zones} (default: @code{'()})
- The list of knot-zone-configuration used by this configuration.
- @end table
- @end deftp
- @subsubheading Knot Resolver Service
- @defvar knot-resolver-service-type
- This is the type of the knot resolver service, whose value should be
- a @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.io/en/stable/config-overview.html, manual}.
- @end defvar
- @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
- @defvar dnsmasq-service-type
- This is the type of the dnsmasq service, whose value should be a
- @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 defvar
- @deftp {Data Type} dnsmasq-configuration
- Data type representing the configuration of dnsmasq.
- @table @asis
- @item @code{package} (default: @var{dnsmasq})
- Package object of the dnsmasq server.
- @item @code{no-hosts?} (default: @code{#f})
- When true, don't read the hostnames in /etc/hosts.
- @item @code{port} (default: @code{53})
- The port to listen on. Setting this to zero completely disables DNS
- responses, leaving only DHCP and/or TFTP functions.
- @item @code{local-service?} (default: @code{#t})
- Accept DNS queries only from hosts whose address is on a local subnet,
- ie a subnet for which an interface exists on the server.
- @item @code{listen-addresses} (default: @code{'()})
- Listen on the given IP addresses.
- @item @code{resolv-file} (default: @code{"/etc/resolv.conf"})
- The file to read the IP address of the upstream nameservers from.
- @item @code{no-resolv?} (default: @code{#f})
- When true, don't read @var{resolv-file}.
- @item @code{forward-private-reverse-lookup?} (default: @code{#t})
- When false, all reverse lookups for private IP ranges are answered with
- "no such domain" rather than being forwarded upstream.
- @item @code{query-servers-in-order?} (default: @code{#f})
- When true, dnsmasq queries the servers in the same order as they appear
- in @var{servers}.
- @item @code{servers} (default: @code{'()})
- Specify IP address of upstream servers directly.
- @item @code{servers-file} (default: @code{#f})
- Specify file containing upstream servers. This file is re-read when dnsmasq receives SIGHUP.
- Could be either a string or a file-like object.
- @item @code{addresses} (default: @code{'()})
- For each entry, specify an IP address to return for any host in the
- given domains. Queries in the domains are never forwarded and always
- replied to with the specified IP address.
- This is useful for redirecting hosts locally, for example:
- @lisp
- (service dnsmasq-service-type
- (dnsmasq-configuration
- (addresses
- '(; Redirect to a local web-server.
- "/example.org/127.0.0.1"
- ; Redirect subdomain to a specific IP.
- "/subdomain.example.org/192.168.1.42"))))
- @end lisp
- Note that rules in @file{/etc/hosts} take precedence over this.
- @item @code{cache-size} (default: @code{150})
- Set the size of dnsmasq's cache. Setting the cache size to zero
- disables caching.
- @item @code{negative-cache?} (default: @code{#t})
- When false, disable negative caching.
- @item @code{cpe-id} (default: @code{#f})
- If set, add a CPE (Customer-Premises Equipment) identifier to DNS
- queries which are forwarded upstream.
- @item @code{tftp-enable?} (default: @code{#f})
- Whether to enable the built-in TFTP server.
- @item @code{tftp-no-fail?} (default: @code{#f})
- If true, does not fail dnsmasq if the TFTP server could not start up.
- @item @code{tftp-single-port?} (default: @code{#f})
- Whether to use only one single port for TFTP.
- @item @code{tftp-secure?} (default: @code{#f})
- If true, only files owned by the user running the dnsmasq process are accessible.
- If dnsmasq is being run as root, different rules apply:
- @code{tftp-secure?} has no effect, but only files which have the
- world-readable bit set are accessible.
- @item @code{tftp-max} (default: @code{#f})
- If set, sets the maximal number of concurrent connections allowed.
- @item @code{tftp-mtu} (default: @code{#f})
- If set, sets the MTU for TFTP packets to that value.
- @item @code{tftp-no-blocksize?} (default: @code{#f})
- If true, stops the TFTP server from negotiating the blocksize with a client.
- @item @code{tftp-lowercase?} (default: @code{#f})
- Whether to convert all filenames in TFTP requests to lowercase.
- @item @code{tftp-port-range} (default: @code{#f})
- If set, fixes the dynamical ports (one per client) to the given range
- (@code{"<start>,<end>"}).
- @item @code{tftp-root} (default: @code{/var/empty,lo})
- Look for files to transfer using TFTP relative to the given directory.
- When this is set, TFTP paths which include @samp{..} are rejected, to stop clients
- getting outside the specified root. Absolute paths (starting with @samp{/}) are
- allowed, but they must be within the TFTP-root. If the optional interface
- argument is given, the directory is only used for TFTP requests via that
- interface.
- @item @code{tftp-unique-root} (default: @code{#f})
- If set, add the IP or hardware address of the TFTP client as a path component
- on the end of the TFTP-root. Only valid if a TFTP root is set and the
- directory exists. Defaults to adding IP address (in standard dotted-quad
- format).
- For instance, if @option{--tftp-root} is @samp{/tftp} and client
- @samp{1.2.3.4} requests file @file{myfile} then the effective path will
- be @file{/tftp/1.2.3.4/myfile} if @file{/tftp/1.2.3.4} exists or
- @file{/tftp/myfile} otherwise. When @samp{=mac} is specified it will
- append the MAC address instead, using lowercase zero padded digits
- separated by dashes, e.g.: @samp{01-02-03-04-aa-bb}. Note that
- resolving MAC addresses is only possible if the client is in the local
- network or obtained a DHCP lease from dnsmasq.
- @end table
- @end deftp
- @node VNC Services
- @subsection VNC Services
- @cindex VNC (virtual network computing)
- @cindex XDMCP (x display manager control protocol)
- The @code{(gnu services vnc)} module provides services related to
- @dfn{Virtual Network Computing} (VNC), which makes it possible to
- locally use graphical Xorg applications running on a remote machine.
- Combined with a graphical manager that supports the @dfn{X Display
- Manager Control Protocol}, such as GDM (@pxref{gdm}) or LightDM
- (@pxref{lightdm}), it is possible to remote an entire desktop for a
- multi-user environment.
- @subsubheading Xvnc
- Xvnc is a VNC server that spawns its own X window server; which means it
- can run on headless servers. The Xvnc implementations provided by the
- @code{tigervnc-server} and @code{turbovnc} aim to be fast and efficient.
- @defvar xvnc-service-type
- The @code{xvnc-service-type} service can be configured via the
- @code{xvnc-configuration} record, documented below. A second virtual
- display could be made available on a remote machine via the
- following configuration:
- @end defvar
- @lisp
- (service xvnc-service-type
- (xvnc-configuration (display-number 10)))
- @end lisp
- As a demonstration, the @command{xclock} command could then be started
- on the remote machine on display number 10, and it could be displayed
- locally via the @command{vncviewer} command:
- @example
- # Start xclock on the remote machine.
- ssh -L5910:localhost:5910 @var{your-host} -- guix shell xclock \
- -- env DISPLAY=:10 xclock
- # Access it via VNC.
- guix shell tigervnc-client -- vncviewer localhost:5910
- @end example
- The following configuration combines XDMCP and Inetd to allow multiple
- users to concurrently use the remote system and login graphically via
- the GDM display manager:
- @lisp
- (operating-system
- [...]
- (services (cons*
- [...]
- (service xvnc-service-type (xvnc-configuration
- (display-number 5)
- (localhost? #f)
- (xdmcp? #t)
- (inetd? #t)))
- (modify-services %desktop-services
- (gdm-service-type config => (gdm-configuration
- (inherit config)
- (auto-suspend? #f)
- (xdmcp? #t)))))))
- @end lisp
- A remote user could then connect to it by using the @command{vncviewer}
- command or a compatible VNC client and start a desktop session of their
- choosing:
- @example
- vncviewer remote-host:5905
- @end example
- @quotation Warning
- Unless your machine is in a controlled environment, for security
- reasons, the @code{localhost?} configuration of the
- @code{xvnc-configuration} record should be left to its default @code{#t}
- value and exposed via a secure means such as an SSH port forward. The
- XDMCP port, UDP 177 should also be blocked from the outside by a
- firewall, as it is not a secure protocol and can expose login
- credentials in clear.
- @end quotation
- @c Use (configuration->documentation 'xvnc-configuration) to regenerate
- @c the documentation.
- @c %start of fragment
- @deftp {Data Type} xvnc-configuration
- Available @code{xvnc-configuration} fields are:
- @table @asis
- @item @code{xvnc} (default: @code{tigervnc-server}) (type: file-like)
- The package that provides the Xvnc binary.
- @item @code{display-number} (default: @code{0}) (type: number)
- The display number used by Xvnc. You should set this to a number not
- already used a Xorg server.
- @item @code{geometry} (default: @code{"1024x768"}) (type: string)
- The size of the desktop to be created.
- @item @code{depth} (default: @code{24}) (type: color-depth)
- The pixel depth in bits of the desktop to be created. Accepted values
- are 16, 24 or 32.
- @item @code{port} (type: maybe-port)
- The port on which to listen for connections from viewers. When left
- unspecified, it defaults to 5900 plus the display number.
- @item @code{ipv4?} (default: @code{#t}) (type: boolean)
- Use IPv4 for incoming and outgoing connections.
- @item @code{ipv6?} (default: @code{#t}) (type: boolean)
- Use IPv6 for incoming and outgoing connections.
- @item @code{password-file} (type: maybe-string)
- The password file to use, if any. Refer to vncpasswd(1) to learn how to
- generate such a file.
- @item @code{xdmcp?} (default: @code{#f}) (type: boolean)
- Query the XDMCP server for a session. This enables users to log in a
- desktop session from the login manager screen. For a multiple users
- scenario, you'll want to enable the @code{inetd?} option as well, so
- that each connection to the VNC server is handled separately rather than
- shared.
- @item @code{inetd?} (default: @code{#f}) (type: boolean)
- Use an Inetd-style service, which runs the Xvnc server on demand.
- @item @code{frame-rate} (default: @code{60}) (type: number)
- The maximum number of updates per second sent to each client.
- @item @code{security-types} (default: @code{'("None")}) (type: security-types)
- The allowed security schemes to use for incoming connections. The
- default is "None", which is safe given that Xvnc is configured to
- authenticate the user via the display manager, and only for local
- connections. Accepted values are any of the following: ("None"
- "VncAuth" "Plain" "TLSNone" "TLSVnc" "TLSPlain" "X509None" "X509Vnc")
- @item @code{localhost?} (default: @code{#t}) (type: boolean)
- Only allow connections from the same machine. It is set to #true by
- default for security, which means SSH or another secure means should be
- used to expose the remote port.
- @item @code{log-level} (default: @code{30}) (type: log-level)
- The log level, a number between 0 and 100, 100 meaning most verbose
- output. The log messages are output to syslog.
- @item @code{extra-options} (default: @code{'()}) (type: strings)
- This can be used to provide extra Xvnc options not exposed via this
- <xvnc-configuration> record.
- @end table
- @end deftp
- @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
- @defvar 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 defvar
- @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@.
- Both @code{openvpn-client-service-type} and
- @code{openvpn-server-service-type} can be run simultaneously.
- @defvar openvpn-client-service-type
- Type of the service that runs @command{openvpn}, a VPN daemon, as a client.
- The value for this service is a @code{<openvpn-client-configuration>}
- object.
- @end defvar
- @defvar openvpn-server-service-type
- Type of the service that runs @command{openvpn}, a VPN daemon, as a server.
- The value for this service is a @code{<openvpn-server-configuration>}
- object.
- @end defvar
- @c %automatically generated documentation
- @deftp {Data Type} openvpn-client-configuration
- Available @code{openvpn-client-configuration} fields are:
- @table @asis
- @item @code{openvpn} (default: @code{openvpn}) (type: file-like)
- The OpenVPN package.
- @item @code{pid-file} (default: @code{"/var/run/openvpn/openvpn.pid"}) (type: string)
- The OpenVPN pid file.
- @item @code{proto} (default: @code{udp}) (type: proto)
- The protocol (UDP or TCP) used to open a channel between clients and
- servers.
- @item @code{dev} (default: @code{tun}) (type: dev)
- The device type used to represent the VPN connection.
- @item @code{ca} (default: @code{"/etc/openvpn/ca.crt"}) (type: maybe-string)
- The certificate authority to check connections against.
- @item @code{cert} (default: @code{"/etc/openvpn/client.crt"}) (type: maybe-string)
- The certificate of the machine the daemon is running on. It should be
- signed by the authority given in @code{ca}.
- @item @code{key} (default: @code{"/etc/openvpn/client.key"}) (type: maybe-string)
- The key of the machine the daemon is running on. It must be the key
- whose certificate is @code{cert}.
- @item @code{comp-lzo?} (default: @code{#t}) (type: boolean)
- Whether to use the lzo compression algorithm.
- @item @code{persist-key?} (default: @code{#t}) (type: boolean)
- Don't re-read key files across SIGUSR1 or --ping-restart.
- @item @code{persist-tun?} (default: @code{#t}) (type: boolean)
- Don't close and reopen TUN/TAP device or run up/down scripts across
- SIGUSR1 or --ping-restart restarts.
- @item @code{fast-io?} (default: @code{#f}) (type: boolean)
- (Experimental) Optimize TUN/TAP/UDP I/O writes by avoiding a call to
- poll/epoll/select prior to the write operation.
- @item @code{verbosity} (default: @code{3}) (type: number)
- Verbosity level.
- @item @code{tls-auth} (default: @code{#f}) (type: tls-auth-client)
- Add an additional layer of HMAC authentication on top of the TLS control
- channel to protect against DoS attacks.
- @item @code{auth-user-pass} (type: maybe-string)
- 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.
- @item @code{verify-key-usage?} (default: @code{#t}) (type: key-usage)
- Whether to check the server certificate has server usage extension.
- @item @code{bind?} (default: @code{#f}) (type: bind)
- Bind to a specific local port number.
- @item @code{resolv-retry?} (default: @code{#t}) (type: resolv-retry)
- Retry resolving server address.
- @item @code{remote} (default: @code{'()}) (type: openvpn-remote-list)
- A list of remote servers to connect to.
- @deftp {Data Type} openvpn-remote-configuration
- Available @code{openvpn-remote-configuration} fields are:
- @table @asis
- @item @code{name} (default: @code{"my-server"}) (type: string)
- Server name.
- @item @code{port} (default: @code{1194}) (type: number)
- Port number the server listens to.
- @end table
- @end deftp
- @end table
- @end deftp
- @c %end of automatic openvpn-client documentation
- @c %automatically generated documentation
- @deftp {Data Type} openvpn-server-configuration
- Available @code{openvpn-server-configuration} fields are:
- @table @asis
- @item @code{openvpn} (default: @code{openvpn}) (type: file-like)
- The OpenVPN package.
- @item @code{pid-file} (default: @code{"/var/run/openvpn/openvpn.pid"}) (type: string)
- The OpenVPN pid file.
- @item @code{proto} (default: @code{udp}) (type: proto)
- The protocol (UDP or TCP) used to open a channel between clients and
- servers.
- @item @code{dev} (default: @code{tun}) (type: dev)
- The device type used to represent the VPN connection.
- @item @code{ca} (default: @code{"/etc/openvpn/ca.crt"}) (type: maybe-string)
- The certificate authority to check connections against.
- @item @code{cert} (default: @code{"/etc/openvpn/client.crt"}) (type: maybe-string)
- The certificate of the machine the daemon is running on. It should be
- signed by the authority given in @code{ca}.
- @item @code{key} (default: @code{"/etc/openvpn/client.key"}) (type: maybe-string)
- The key of the machine the daemon is running on. It must be the key
- whose certificate is @code{cert}.
- @item @code{comp-lzo?} (default: @code{#t}) (type: boolean)
- Whether to use the lzo compression algorithm.
- @item @code{persist-key?} (default: @code{#t}) (type: boolean)
- Don't re-read key files across SIGUSR1 or --ping-restart.
- @item @code{persist-tun?} (default: @code{#t}) (type: boolean)
- Don't close and reopen TUN/TAP device or run up/down scripts across
- SIGUSR1 or --ping-restart restarts.
- @item @code{fast-io?} (default: @code{#f}) (type: boolean)
- (Experimental) Optimize TUN/TAP/UDP I/O writes by avoiding a call to
- poll/epoll/select prior to the write operation.
- @item @code{verbosity} (default: @code{3}) (type: number)
- Verbosity level.
- @item @code{tls-auth} (default: @code{#f}) (type: tls-auth-server)
- Add an additional layer of HMAC authentication on top of the TLS control
- channel to protect against DoS attacks.
- @item @code{port} (default: @code{1194}) (type: number)
- Specifies the port number on which the server listens.
- @item @code{server} (default: @code{"10.8.0.0 255.255.255.0"}) (type: ip-mask)
- An ip and mask specifying the subnet inside the virtual network.
- @item @code{server-ipv6} (default: @code{#f}) (type: cidr6)
- A CIDR notation specifying the IPv6 subnet inside the virtual network.
- @item @code{dh} (default: @code{"/etc/openvpn/dh2048.pem"}) (type: string)
- The Diffie-Hellman parameters file.
- @item @code{ifconfig-pool-persist} (default: @code{"/etc/openvpn/ipp.txt"}) (type: string)
- The file that records client IPs.
- @item @code{redirect-gateway?} (default: @code{#f}) (type: gateway)
- When true, the server will act as a gateway for its clients.
- @item @code{client-to-client?} (default: @code{#f}) (type: boolean)
- When true, clients are allowed to talk to each other inside the VPN.
- @item @code{keepalive} (default: @code{(10 120)}) (type: 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.
- @item @code{max-clients} (default: @code{100}) (type: number)
- The maximum number of clients.
- @item @code{status} (default: @code{"/var/run/openvpn/status"}) (type: string)
- The status file. This file shows a small report on current connection.
- It is truncated and rewritten every minute.
- @item @code{client-config-dir} (default: @code{'()}) (type: openvpn-ccd-list)
- The list of configuration for some clients.
- @end table
- @end deftp
- @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.
- @defvar 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 defvar
- @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
- @defvar 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 defvar
- @deftp {Data Type} wireguard-configuration
- Data type representing the configuration of the Wireguard service.
- @table @asis
- @item @code{wireguard}
- The wireguard package to use for this service.
- @item @code{interface} (default: @code{"wg0"})
- The interface name for the VPN.
- @item @code{addresses} (default: @code{'("10.0.0.1/32")})
- The IP addresses to be assigned to the above interface.
- @item @code{port} (default: @code{51820})
- The port on which to listen for incoming connections.
- @item @code{dns} (default: @code{'())})
- The DNS server(s) to announce to VPN clients via DHCP.
- @item @code{monitor-ips?} (default: @code{#f})
- @cindex Dynamic IP, with Wireguard
- @cindex dyndns, usage with Wireguard
- Whether to monitor the resolved Internet addresses (IPs) of the
- endpoints of the configured peers, resetting the peer endpoints using an
- IP address that no longer correspond to their freshly resolved host
- name. Set this to @code{#t} if one or more endpoints use host names
- provided by a dynamic DNS service to keep the sessions alive.
- @item @code{monitor-ips-interval} (default: @code{'(next-minute (range 0 60 5))})
- The time interval at which the IP monitoring job should run, provided as
- an mcron time specification (@pxref{Guile Syntax,,,mcron}).
- @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.
- @item @code{pre-up} (default: @code{'()})
- The script commands to be run before setting up the interface.
- @item @code{post-up} (default: @code{'()})
- The script commands to be run after setting up the interface.
- @item @code{pre-down} (default: @code{'()})
- The script commands to be run before tearing down the interface.
- @item @code{post-down} (default: @code{'()})
- The script commands to be run after tearing down the interface.
- @item @code{table} (default: @code{"auto"})
- The routing table to which routes are added, as a string. There are two
- special values: @code{"off"} that disables the creation of routes
- altogether, and @code{"auto"} (the default) that adds routes to the
- default table and enables special handling of default routes.
- @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{preshared-key} (default: @code{#f})
- An optional pre-shared key file for this peer. The given file will not
- be autogenerated.
- @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.
- @defvar nfs-service-type
- A service type for a complete NFS server.
- @end defvar
- @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.
- @defvar rpcbind-service-type
- A service type for the RPC portmapper daemon.
- @end defvar
- @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.
- @defvar pipefs-service-type
- A service type for the pipefs pseudo file system.
- @end defvar
- @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}).
- @defvar gss-service-type
- A service type for the Global Security System (GSS) daemon.
- @end defvar
- @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.
- @defvar idmap-service-type
- A service type for the Identity Mapper (IDMAP) daemon.
- @end defvar
- @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 Samba Services, Continuous Integration, Network File System, Services
- @subsection Samba Services
- @cindex Samba
- @cindex SMB
- The @code{(gnu services samba)} module provides service definitions for
- Samba as well as additional helper services. Currently it provides the
- following services.
- @subsubheading Samba
- @uref{https://www.samba.org, Samba} provides network shares for folders
- and printers using the SMB/CIFS protocol commonly used on Windows. It
- can also act as an Active Directory Domain Controller (AD DC) for other
- hosts in an heterougenious network with different types of Computer
- systems.
- @defvar samba-service-type
- The service type to enable the samba services @code{samba}, @code{nmbd},
- @code{smbd} and @code{winbindd}. By default this service type does not
- run any of the Samba daemons; they must be enabled individually.
- Below is a basic example that configures a simple, anonymous
- (unauthenticated) Samba file share exposing the @file{/public}
- directory.
- @quotation Tip
- The @file{/public} directory and its contents must be world
- readable/writable, so you'll want to run @samp{chmod -R 777 /public} on
- it.
- @end quotation
- @quotation Caution
- Such a Samba configuration should only be used in controlled
- environments, and you should not share any private files using it, as
- anyone connecting to your network would be able to access them.
- @end quotation
- @lisp
- (service samba-service-type (samba-configuration
- (enable-smbd? #t)
- (config-file (plain-file "smb.conf" "\
- [global]
- map to guest = Bad User
- logging = syslog@@1
- [public]
- browsable = yes
- path = /public
- read only = no
- guest ok = yes
- guest only = yes\n"))))
- @end lisp
- @end defvar
- @deftp {Data Type} samba-service-configuration
- Configuration record for the Samba suite.
- @table @asis
- @item @code{package} (default: @code{samba})
- The samba package to use.
- @item @code{config-file} (default: @code{#f})
- The config file to use. To learn about its syntax, run @samp{man
- smb.conf}.
- @item @code{enable-samba?} (default: @code{#f})
- Enable the @code{samba} daemon.
- @item @code{enable-smbd?} (default: @code{#f})
- Enable the @code{smbd} daemon.
- @item @code{enable-nmbd?} (default: @code{#f})
- Enable the @code{nmbd} daemon.
- @item @code{enable-winbindd?} (default: @code{#f})
- Enable the @code{winbindd} daemon.
- @end table
- @end deftp
- @cindex wsdd, Web service discovery daemon
- @subsubheading Web Service Discovery Daemon
- The @acronym{WSDD, Web Service Discovery daemon} implements the
- @uref{http://docs.oasis-open.org/ws-dd/discovery/1.1/os/wsdd-discovery-1.1-spec-os.html,
- Web Services Dynamic Discovery} protocol that enables host discovery
- over Multicast DNS, similar to what Avahi does. It is a drop-in
- replacement for SMB hosts that have had SMBv1 disabled for security
- reasons.
- @defvar wsdd-service-type
- Service type for the WSD host daemon. The value for
- this service type is a @code{wsdd-configuration} record. The details
- for the @code{wsdd-configuration} record type are given below.
- @end defvar
- @deftp {Data Type} wsdd-configuration
- This data type represents the configuration for the wsdd service.
- @table @asis
- @item @code{package} (default: @code{wsdd})
- The wsdd package to use.
- @item @code{ipv4only?} (default: @code{#f})
- Only listen to IPv4 addresses.
- @item @code{ipv6only} (default: @code{#f})
- Only listen to IPv6 addresses. Please note: Activating both options is
- not possible, since there would be no IP versions to listen to.
- @item @code{chroot} (default: @code{#f})
- Chroot into a separate directory to prevent access to other directories.
- This is to increase security in case there is a vulnerability in
- @command{wsdd}.
- @item @code{hop-limit} (default: @code{1})
- Limit to the level of hops for multicast packets. The default is
- @var{1} which should prevent packets from leaving the local network.
- @item @code{interface} (default: @code{'()})
- Limit to the given list of interfaces to listen to. By default wsdd
- will listen to all interfaces. Except the loopback interface is never
- used.
- @item @code{uuid-device} (default: @code{#f})
- The WSD protocol requires a device to have a UUID. Set this to manually
- assign the service a UUID.
- @item @code{domain} (default: @code{#f})
- Notify this host is a member of an Active Directory.
- @item @code{host-name} (default: @code{#f})
- Manually set the hostname rather than letting @command{wsdd} inherit
- this host's hostname. Only the host name part of a possible FQDN will
- be used in the default case.
- @item @code{preserve-case?} (default: @code{#f})
- By default @command{wsdd} will convert the hostname in workgroup to all
- uppercase. The opposite is true for hostnames in domains. Setting this
- parameter will preserve case.
- @item @code{workgroup} (default: @var{"WORKGROUP"})
- Change the name of the workgroup. By default @command{wsdd} reports
- this host being member of a workgroup.
- @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 {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.
- @defvar 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 defvar
- @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}.
- @defvar 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 defvar
- 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
- left unset, or is explicitly set to the @code{%unset-value} value.
- @c The following documentation was initially generated by
- @c (generate-tlp-documentation) in (gnu services pm). Manually maintained
- @c documentation is better, so we shouldn't hesitate to edit below as
- @c needed. However if the change you want to make to this documentation
- @c can be done in an automated way, it's probably easier to change
- @c (generate-documentation) than to make it below and have to deal with
- @c the churn as TLP updates.
- Available @code{tlp-configuration} fields are:
- @deftypevr {@code{tlp-configuration} parameter} package tlp
- The TLP package.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} boolean tlp-enable?
- Set to true if you wish to enable TLP.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} string tlp-default-mode
- Default mode when no power supply can be detected. Alternatives are AC
- and BAT.
- Defaults to @samp{"AC"}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} non-negative-integer disk-idle-secs-on-ac
- Number of seconds Linux kernel has to wait after the disk goes idle,
- before syncing on AC.
- Defaults to @samp{0}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} non-negative-integer disk-idle-secs-on-bat
- Same as @code{disk-idle-ac} but on BAT mode.
- Defaults to @samp{2}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} non-negative-integer max-lost-work-secs-on-ac
- Dirty pages flushing periodicity, expressed in seconds.
- Defaults to @samp{15}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} non-negative-integer max-lost-work-secs-on-bat
- Same as @code{max-lost-work-secs-on-ac} but on BAT mode.
- Defaults to @samp{60}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list cpu-scaling-governor-on-ac
- CPU frequency scaling governor on AC mode. With intel_pstate driver,
- alternatives are powersave and performance. With acpi-cpufreq driver,
- alternatives are ondemand, powersave, performance and conservative.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list cpu-scaling-governor-on-bat
- Same as @code{cpu-scaling-governor-on-ac} but on BAT mode.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-scaling-min-freq-on-ac
- Set the min available frequency for the scaling governor on AC.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-scaling-max-freq-on-ac
- Set the max available frequency for the scaling governor on AC.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-scaling-min-freq-on-bat
- Set the min available frequency for the scaling governor on BAT.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-scaling-max-freq-on-bat
- Set the max available frequency for the scaling governor on BAT.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-min-perf-on-ac
- Limit the min P-state to control the power dissipation of the CPU, in AC
- mode. Values are stated as a percentage of the available performance.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-max-perf-on-ac
- Limit the max P-state to control the power dissipation of the CPU, in AC
- mode. Values are stated as a percentage of the available performance.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-min-perf-on-bat
- Same as @code{cpu-min-perf-on-ac} on BAT mode.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-max-perf-on-bat
- Same as @code{cpu-max-perf-on-ac} on BAT mode.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-boolean cpu-boost-on-ac?
- Enable CPU turbo boost feature on AC mode.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-boolean cpu-boost-on-bat?
- Same as @code{cpu-boost-on-ac?} on BAT mode.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} boolean sched-powersave-on-ac?
- Allow Linux kernel to minimize the number of CPU cores/hyper-threads
- used under light load conditions.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} boolean sched-powersave-on-bat?
- Same as @code{sched-powersave-on-ac?} but on BAT mode.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} boolean nmi-watchdog?
- Enable Linux kernel NMI watchdog.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-string phc-controls
- For Linux kernels with PHC patch applied, change CPU voltages. An
- example value would be @samp{"F:V F:V F:V F:V"}.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} string energy-perf-policy-on-ac
- Set CPU performance versus energy saving policy on AC@. Alternatives are
- performance, normal, powersave.
- Defaults to @samp{"performance"}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} string energy-perf-policy-on-bat
- Same as @code{energy-perf-policy-ac} but on BAT mode.
- Defaults to @samp{"powersave"}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} space-separated-string-list disks-devices
- Hard disk devices.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} space-separated-string-list disk-apm-level-on-ac
- Hard disk advanced power management level.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} space-separated-string-list disk-apm-level-on-bat
- Same as @code{disk-apm-bat} but on BAT mode.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list disk-spindown-timeout-on-ac
- Hard disk spin down timeout. One value has to be specified for each
- declared hard disk.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list disk-spindown-timeout-on-bat
- Same as @code{disk-spindown-timeout-on-ac} but on BAT mode.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list disk-iosched
- Select IO scheduler for disk devices. One value has to be specified for
- each declared hard disk. Example alternatives are cfq, deadline and
- noop.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} string sata-linkpwr-on-ac
- SATA aggressive link power management (ALPM) level. Alternatives are
- min_power, medium_power, max_performance.
- Defaults to @samp{"max_performance"}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} string sata-linkpwr-on-bat
- Same as @code{sata-linkpwr-ac} but on BAT mode.
- Defaults to @samp{"min_power"}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-string sata-linkpwr-blacklist
- Exclude specified SATA host devices for link power management.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-on-off-boolean ahci-runtime-pm-on-ac?
- Enable Runtime Power Management for AHCI controller and disks on AC
- mode.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-on-off-boolean ahci-runtime-pm-on-bat?
- Same as @code{ahci-runtime-pm-on-ac} on BAT mode.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} non-negative-integer ahci-runtime-pm-timeout
- Seconds of inactivity before disk is suspended.
- Defaults to @samp{15}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} string pcie-aspm-on-ac
- PCI Express Active State Power Management level. Alternatives are
- default, performance, powersave.
- Defaults to @samp{"performance"}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} string pcie-aspm-on-bat
- Same as @code{pcie-aspm-ac} but on BAT mode.
- Defaults to @samp{"powersave"}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer start-charge-thresh-bat0
- Percentage when battery 0 should begin charging. Only supported on some laptops.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer stop-charge-thresh-bat0
- Percentage when battery 0 should stop charging. Only supported on some laptops.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer start-charge-thresh-bat1
- Percentage when battery 1 should begin charging. Only supported on some laptops.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer stop-charge-thresh-bat1
- Percentage when battery 1 should stop charging. Only supported on some laptops.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} string radeon-power-profile-on-ac
- Radeon graphics clock speed level. Alternatives are low, mid, high,
- auto, default.
- Defaults to @samp{"high"}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} string radeon-power-profile-on-bat
- Same as @code{radeon-power-ac} but on BAT mode.
- Defaults to @samp{"low"}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} string radeon-dpm-state-on-ac
- Radeon dynamic power management method (DPM). Alternatives are battery,
- performance.
- Defaults to @samp{"performance"}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} string radeon-dpm-state-on-bat
- Same as @code{radeon-dpm-state-ac} but on BAT mode.
- Defaults to @samp{"battery"}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} string radeon-dpm-perf-level-on-ac
- Radeon DPM performance level. Alternatives are auto, low, high.
- Defaults to @samp{"auto"}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} string radeon-dpm-perf-level-on-bat
- Same as @code{radeon-dpm-perf-ac} but on BAT mode.
- Defaults to @samp{"auto"}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} on-off-boolean wifi-pwr-on-ac?
- Wifi power saving mode.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} on-off-boolean wifi-pwr-on-bat?
- Same as @code{wifi-power-ac?} but on BAT mode.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} y-n-boolean wol-disable?
- Disable wake on LAN.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} non-negative-integer sound-power-save-on-ac
- Timeout duration in seconds before activating audio power saving on
- Intel HDA and AC97 devices. A value of 0 disables power saving.
- Defaults to @samp{0}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} non-negative-integer sound-power-save-on-bat
- Same as @code{sound-powersave-ac} but on BAT mode.
- Defaults to @samp{1}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} y-n-boolean sound-power-save-controller?
- Disable controller in powersaving mode on Intel HDA devices.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} boolean bay-poweroff-on-bat?
- Enable optical drive in UltraBay/MediaBay on BAT mode. Drive can be
- powered on again by releasing (and reinserting) the eject lever or by
- pressing the disc eject button on newer models.
- Defaults to @samp{#f}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} string bay-device
- Name of the optical drive device to power off.
- Defaults to @samp{"sr0"}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} string runtime-pm-on-ac
- Runtime Power Management for PCI(e) bus devices. Alternatives are on
- and auto.
- Defaults to @samp{"on"}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} string runtime-pm-on-bat
- Same as @code{runtime-pm-ac} but on BAT mode.
- Defaults to @samp{"auto"}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} boolean runtime-pm-all?
- Runtime Power Management for all PCI(e) bus devices, except blacklisted
- ones.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list runtime-pm-blacklist
- Exclude specified PCI(e) device addresses from Runtime Power Management.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} space-separated-string-list runtime-pm-driver-blacklist
- Exclude PCI(e) devices assigned to the specified drivers from Runtime
- Power Management.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} boolean usb-autosuspend?
- Enable USB autosuspend feature.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-string usb-blacklist
- Exclude specified devices from USB autosuspend.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} boolean usb-blacklist-wwan?
- Exclude WWAN devices from USB autosuspend.
- Defaults to @samp{#t}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-string usb-whitelist
- Include specified devices into USB autosuspend, even if they are already
- excluded by the driver or via @code{usb-blacklist-wwan?}.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} maybe-boolean usb-autosuspend-disable-on-shutdown?
- Enable USB autosuspend before shutdown.
- Defaults to @samp{disabled}.
- @end deftypevr
- @deftypevr {@code{tlp-configuration} parameter} boolean restore-device-state-on-startup?
- Restore radio device state (bluetooth, wifi, wwan) from previous
- shutdown on system startup.
- Defaults to @samp{#f}.
- @end deftypevr
- @cindex thermald
- @cindex CPU frequency scaling with thermald
- @subsubheading Thermald daemon
- The @code{(gnu services pm)} module provides an interface to
- thermald, a CPU frequency scaling service which helps prevent overheating.
- @defvar 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 defvar
- @deftp {Data Type} thermald-configuration
- Data type representing the configuration of @code{thermald-service-type}.
- @table @asis
- @item @code{adaptive?} (default: @code{#f})
- Use @acronym{DPTF, Dynamic Power and Thermal Framework} adaptive tables
- when present.
- @item @code{ignore-cpuid-check?} (default: @code{#f})
- Ignore cpuid check for supported CPU models.
- @item @code{thermald} (default: @var{thermald})
- Package object of thermald.
- @end table
- @end deftp
- @node Audio Services
- @subsection Audio Services
- The @code{(gnu services audio)} module provides a service to start MPD
- (the Music Player Daemon).
- @cindex mpd
- @subsubheading Music Player Daemon
- The Music Player Daemon (MPD) is a service that can play music while
- being controlled from the local machine or over the network by a variety
- of clients.
- The following example shows the simplest configuration to locally
- expose, via PulseAudio, a music collection kept at @file{/srv/music},
- with @command{mpd} running as the default @samp{mpd} user. This user
- will spawn its own PulseAudio daemon, which may compete for the sound
- card access with that of your own user. In this configuration, you may
- have to stop the playback of your user audio applications to hear MPD's
- output and vice-versa.
- @lisp
- (service mpd-service-type
- (mpd-configuration
- (music-directory "/srv/music")))
- @end lisp
- @quotation Important
- The music directory must be readable to the MPD user, by default,
- @samp{mpd}. Permission problems will be reported via @samp{Permission
- denied} errors in the MPD logs, which appear in @file{/var/log/messages}
- by default.
- @end quotation
- Most MPD clients will trigger a database update upon connecting, but you
- can also use the @code{update} action do to so:
- @example
- herd update mpd
- @end example
- All the MPD configuration fields are documented below, and a more
- complex example follows.
- @defvar mpd-service-type
- The service type for @command{mpd}
- @end defvar
- @c %start of fragment
- @deftp {Data Type} mpd-configuration
- Available @code{mpd-configuration} fields are:
- @table @asis
- @item @code{package} (default: @code{mpd}) (type: file-like)
- The MPD package.
- @item @code{user} (type: user-account)
- The user to run mpd as.
- @item @code{group} (type: user-group)
- The group to run mpd as.
- The default @code{%mpd-group} is a system group with name ``mpd''.
- @item @code{shepherd-requirement} (default: @code{'()}) (type: list-of-symbol)
- A list of symbols naming Shepherd services that this service
- will depend on.
- @item @code{environment-variables} (default: @code{'("PULSE_CLIENTCONFIG=/etc/pulse/client.conf" "PULSE_CONFIG=/etc/pulse/daemon.conf")}) (type: list-of-strings)
- A list of strings specifying environment variables.
- @item @code{log-file} (type: maybe-string)
- The location of the log file. Unless specified, logs are sent to the
- local syslog daemon. Alternatively, a log file name can be specified,
- for example @file{/var/log/mpd.log}.
- @item @code{log-level} (type: maybe-string)
- Supress any messages below this threshold. The available values, in
- decreasing order of verbosity, are: @code{verbose}, @code{info},
- @code{notice}, @code{warning} and @code{error}.
- @item @code{music-directory} (type: maybe-string)
- The directory to scan for music files.
- @item @code{music-dir} (type: maybe-string)
- The directory to scan for music files.
- @item @code{playlist-directory} (type: maybe-string)
- The directory to store playlists.
- @item @code{playlist-dir} (type: maybe-string)
- The directory to store playlists.
- @item @code{db-file} (type: maybe-string)
- The location of the music database. When left unspecified,
- @file{~/.cache/db} is used.
- @item @code{state-file} (type: maybe-string)
- The location of the file that stores current MPD's state.
- @item @code{sticker-file} (type: maybe-string)
- The location of the sticker database.
- @item @code{default-port} (default: @code{6600}) (type: maybe-port)
- The default port to run mpd on.
- @item @code{endpoints} (type: maybe-list-of-strings)
- The addresses that mpd will bind to. A port different from
- @var{default-port} may be specified, e.g. @code{localhost:6602} and
- IPv6 addresses must be enclosed in square brackets when a different port
- is used. To use a Unix domain socket, an absolute path or a path
- starting with @code{~} can be specified here.
- @item @code{address} (type: maybe-string)
- The address that mpd will bind to. To use a Unix domain socket, an
- absolute path can be specified here.
- @item @code{database} (type: maybe-mpd-plugin)
- MPD database plugin configuration.
- @item @code{partitions} (default: @code{'()}) (type: list-of-mpd-partition)
- List of MPD "partitions".
- @item @code{neighbors} (default: @code{'()}) (type: list-of-mpd-plugin)
- List of MPD neighbor plugin configurations.
- @item @code{inputs} (default: @code{'()}) (type: list-of-mpd-plugin)
- List of MPD input plugin configurations.
- @item @code{archive-plugins} (default: @code{'()}) (type: list-of-mpd-plugin)
- List of MPD archive plugin configurations.
- @item @code{auto-update?} (type: maybe-boolean)
- Whether to automatically update the music database when files are
- changed in the @var{music-directory}.
- @item @code{input-cache-size} (type: maybe-string)
- MPD input cache size.
- @item @code{decoders} (default: @code{'()}) (type: list-of-mpd-plugin)
- List of MPD decoder plugin configurations.
- @item @code{resampler} (type: maybe-mpd-plugin)
- MPD resampler plugin configuration.
- @item @code{filters} (default: @code{'()}) (type: list-of-mpd-plugin)
- List of MPD filter plugin configurations.
- @item @code{outputs} (type: list-of-mpd-plugin-or-output)
- The audio outputs that MPD can use. By default this is a single output
- using pulseaudio.
- @item @code{playlist-plugins} (default: @code{'()}) (type: list-of-mpd-plugin)
- List of MPD playlist plugin configurations.
- @item @code{extra-options} (default: @code{'()}) (type: alist)
- An association list of option symbols/strings to string values to be
- appended to the configuration.
- @end table
- @end deftp
- @c %end of fragment
- @deftp {Data Type} mpd-plugin
- Data type representing a @command{mpd} plugin.
- @table @asis
- @item @code{plugin} (type: maybe-string)
- Plugin name.
- @item @code{name} (type: maybe-string)
- Name.
- @item @code{enabled?} (type: maybe-boolean)
- Whether the plugin is enabled/disabled.
- @item @code{extra-options} (default: @code{'()}) (type: alist)
- An association list of option symbols/strings to string values to be
- appended to the plugin configuration. See
- @uref{https://mpd.readthedocs.io/en/latest/plugins.html,MPD plugin
- reference} for available options.
- @end table
- @end deftp
- @deftp {Data Type} mpd-partition
- Data type representing a @command{mpd} partition.
- @table @asis
- @item @code{name} (type: string)
- Partition name.
- @item @code{extra-options} (default: @code{'()}) (type: alist)
- An association list of option symbols/strings to string values to be
- appended to the partition configuration. See
- @uref{https://mpd.readthedocs.io/en/latest/user.html#configuring-partitions,Configuring
- Partitions} for available options.
- @end table
- @end deftp
- @c %start of fragment
- @deftp {Data Type} mpd-output
- Available @code{mpd-output} fields are:
- @table @asis
- @item @code{name} (default: @code{"MPD"}) (type: string)
- The name of the audio output.
- @item @code{type} (default: @code{"pulse"}) (type: string)
- The type of audio output.
- @item @code{enabled?} (default: @code{#t}) (type: boolean)
- 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{format} (type: maybe-string)
- Force a specific audio format on output. See
- @uref{https://mpd.readthedocs.io/en/latest/user.html#audio-output-format,Global
- Audio Format} for a more detailed description.
- @item @code{tags?} (default: @code{#t}) (type: boolean)
- 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}) (type: boolean)
- 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} (type: maybe-string)
- This field accepts a string 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}). When left unspecified, a
- @code{hardware} mixer is used for devices that support it.
- @item @code{replay-gain-handler} (type: maybe-string)
- This field accepts a string that specifies how
- @uref{https://mpd.readthedocs.io/en/latest/user.html#replay-gain,Replay
- Gain} is to be applied. @code{software} uses an internal software
- volume control, @code{mixer} uses the configured (hardware) mixer
- control and @code{none} disables replay gain on this audio output.
- @item @code{extra-options} (default: @code{'()}) (type: alist)
- An association list of option symbols/strings to string values to be
- appended to the audio output configuration.
- @end table
- @end deftp
- @c %end of fragment
- The following example shows a configuration of @command{mpd} that
- configures some of its plugins and provides a 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"))))))
- (decoders
- (list (mpd-plugin
- (plugin "mikmod")
- (enabled? #f))
- (mpd-plugin
- (plugin "openmpt")
- (enabled? #t)
- (extra-options `((repeat-count . -1)
- (interpolation-filter . 1))))))
- (resampler (mpd-plugin
- (plugin "libsamplerate")
- (extra-options `((type . 0)))))))
- @end lisp
- @subsubheading myMPD
- @cindex MPD, web interface
- @cindex myMPD service
- @uref{https://jcorporation.github.io/myMPD/, myMPD} is a web server
- frontend for MPD that provides a mobile friendly web client for MPD.
- The following example shows a myMPD instance listening on port 80,
- with album cover caching disabled.
- @lisp
- (service mympd-service-type
- (mympd-configuration
- (port 80)
- (covercache-ttl 0)))
- @end lisp
- @defvar mympd-service-type
- The service type for @command{mympd}.
- @end defvar
- @c %start of fragment
- @deftp {Data Type} mympd-configuration
- Available @code{mympd-configuration} fields are:
- @table @asis
- @item @code{package} (default: @code{mympd}) (type: file-like)
- The package object of the myMPD server.
- @item @code{shepherd-requirement} (default: @code{'()}) (type: list-of-symbol)
- This is a list of symbols naming Shepherd services that this service
- will depend on.
- @item @code{user} (default: @code{%mympd-user}) (type: user-account)
- Owner of the @command{mympd} process.
- The default @code{%mympd-user} is a system user with the name ``mympd'',
- who is a part of the group @var{group} (see below).
- @item @code{group} (default: @code{%mympd-group}) (type: user-group)
- Owner group of the @command{mympd} process.
- The default @code{%mympd-group} is a system group with name ``mympd''.
- @item @code{work-directory} (default: @code{"/var/lib/mympd"}) (type: string)
- Where myMPD will store its data.
- @item @code{cache-directory} (default: @code{"/var/cache/mympd"}) (type: string)
- Where myMPD will store its cache.
- @item @code{acl} (type: maybe-mympd-ip-acl)
- ACL to access the myMPD webserver.
- @item @code{covercache-ttl} (default: @code{31}) (type: maybe-integer)
- How long to keep cached covers, @code{0} disables cover caching.
- @item @code{http?} (default: @code{#t}) (type: boolean)
- HTTP support.
- @item @code{host} (default: @code{"[::]"}) (type: string)
- Host name to listen on.
- @item @code{port} (default: @code{80}) (type: maybe-port)
- HTTP port to listen on.
- @item @code{log-level} (default: @code{5}) (type: integer)
- How much detail to include in logs, possible values: @code{0} to
- @code{7}.
- @item @code{log-to} (type: maybe-string)
- Where to send logs. Unless specified, the service logs to the local
- syslog service under the @samp{daemon} facility. Alternatively, a log
- file name can be specified, for example @file{/var/log/mympd.log}.
- @item @code{lualibs} (default: @code{"all"}) (type: maybe-string)
- See
- @uref{https://jcorporation.github.io/myMPD/scripting/#lua-standard-libraries}.
- @item @code{uri} (type: maybe-string)
- Override URI to myMPD. See
- @uref{https://github.com/jcorporation/myMPD/issues/950}.
- @item @code{script-acl} (default: @code{(mympd-ip-acl (allow '("127.0.0.1")))}) (type: maybe-mympd-ip-acl)
- ACL to access the myMPD script backend.
- @item @code{ssl?} (default: @code{#f}) (type: boolean)
- SSL/TLS support.
- @item @code{ssl-port} (default: @code{443}) (type: maybe-port)
- Port to listen for HTTPS.
- @item @code{ssl-cert} (type: maybe-string)
- Path to PEM encoded X.509 SSL/TLS certificate (public key).
- @item @code{ssl-key} (type: maybe-string)
- Path to PEM encoded SSL/TLS private key.
- @item @code{pin-hash} (type: maybe-string)
- SHA-256 hashed pin used by myMPD to control settings access by prompting
- a pin from the user.
- @item @code{save-caches?} (type: maybe-boolean)
- Whether to preserve caches between service restarts.
- @end table
- @end deftp
- @c %end of fragment
- @c %start of fragment
- @deftp {Data Type} mympd-ip-acl
- Available @code{mympd-ip-acl} fields are:
- @table @asis
- @item @code{allow} (default: @code{'()}) (type: list-of-strings)
- Allowed IP addresses.
- @item @code{deny} (default: @code{'()}) (type: list-of-strings)
- Disallowed IP addresses.
- @end table
- @end deftp
- @c %end of fragment
- @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.
- @defvar 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 defvar
- @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.
- @defvar 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 defvar
- @deftypevr {@code{libvirt} parameter} package libvirt
- Libvirt package.
- @end deftypevr
- @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.
- @defvar 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 defvar
- @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 {Procedure} lookup-qemu-platforms 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 {Procedure} qemu-platform? obj
- Return true if @var{obj} is a platform object.
- @end deffn
- @deffn {Procedure} qemu-platform-name platform
- Return the name of @var{platform}---a string such as @code{"arm"}.
- @end deffn
- @subsubheading QEMU Guest Agent
- @cindex emulation
- The QEMU guest agent provides control over the emulated system to the
- host. The @code{qemu-guest-agent} service runs the agent on Guix
- guests. To control the agent from the host, open a socket by invoking
- QEMU with the following arguments:
- @example
- qemu-system-x86_64 \
- -chardev socket,path=/tmp/qga.sock,server=on,wait=off,id=qga0 \
- -device virtio-serial \
- -device virtserialport,chardev=qga0,name=org.qemu.guest_agent.0 \
- ...
- @end example
- This creates a socket at @file{/tmp/qga.sock} on the host. Once the
- guest agent is running, you can issue commands with @code{socat}:
- @example
- $ guix shell socat -- socat unix-connect:/tmp/qga.sock stdio
- @{"execute": "guest-get-host-name"@}
- @{"return": @{"host-name": "guix"@}@}
- @end example
- See @url{https://wiki.qemu.org/Features/GuestAgent,QEMU guest agent
- documentation} for more options and commands.
- @defvar qemu-guest-agent-service-type
- Service type for the QEMU guest agent service.
- @end defvar
- @deftp {Data Type} qemu-guest-agent-configuration
- Configuration for the @code{qemu-guest-agent} service.
- @table @asis
- @item @code{qemu} (default: @code{qemu-minimal})
- The QEMU package to use.
- @item @code{device} (default: @code{""})
- File name of the device or socket the agent uses to communicate with the
- host. If empty, QEMU uses a default file name.
- @end table
- @end deftp
- @subsubheading The Hurd in a Virtual Machine
- @cindex @code{hurd}
- @cindex the Hurd
- @cindex childhurd
- Service @code{hurd-vm} provides support for running GNU/Hurd in a
- virtual machine (VM), a so-called @dfn{childhurd}. This service is meant
- to be used on GNU/Linux and the given GNU/Hurd operating system
- configuration is cross-compiled. The virtual machine is a Shepherd
- service that can be referred to by the names @code{hurd-vm} and
- @code{childhurd} and be controlled with commands such as:
- @example
- herd start hurd-vm
- herd stop childhurd
- @end example
- When the service is running, you can view its console by connecting to
- it with a VNC client, for example with:
- @example
- guix shell tigervnc-client -- vncviewer localhost:5900
- @end example
- The default configuration (see @code{hurd-vm-configuration} below)
- spawns a secure shell (SSH) server in your GNU/Hurd system, which QEMU
- (the virtual machine emulator) redirects to port 10222 on the host.
- Thus, you can connect over SSH to the childhurd with:
- @example
- ssh root@@localhost -p 10022
- @end example
- The childhurd is volatile and stateless: it starts with a fresh root
- file system every time you restart it. By default though, all the files
- under @file{/etc/childhurd} on the host are copied as is to the root
- file system of the childhurd when it boots. This allows you to
- initialize ``secrets'' inside the VM: SSH host keys, authorized
- substitute keys, and so on---see the explanation of @code{secret-root}
- below.
- @defvar 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 defvar
- @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{Service Reference, @code{hosts-service-type}}) 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")
- ;; Install QEMU so we can use KVM-based instances, and LVM, DRBD and Ceph
- ;; in order to use the "plain", "drbd" and "rbd" storage backends.
- (packages (append (map specification->package
- '("qemu" "lvm2" "drbd-utils" "ceph"
- ;; Add the debootstrap and guix OS providers.
- "ganeti-instance-guix" "ganeti-instance-debootstrap"))
- %base-packages))
- (services
- (append (list (service static-networking-service-type
- (list (static-networking
- (addresses
- (list (network-address
- (device "eth0")
- (value "192.168.1.201/24"))))
- (routes
- (list (network-route
- (destination "default")
- (gateway "192.168.1.254"))))
- (name-servers '("192.168.1.252"
- "192.168.1.253")))))
- ;; Ganeti uses SSH to communicate between nodes.
- (service openssh-service-type
- (openssh-configuration
- (permit-root-login 'prohibit-password)))
- (simple-service 'ganeti-hosts-entries hosts-service-type
- (list
- (host "192.168.1.200" "ganeti.example.com")
- (host "192.168.1.201" "node1.example.com"
- '("node1"))
- (host "192.168.1.202" "node2.example.com"
- '("node2"))))
- (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{https://docs.ganeti.org/docs/ganeti/3.0/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.
- @defvar 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 defvar
- @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{hooks} (default: @code{#f})
- When set, this should be a file-like object containing a directory with
- @url{https://docs.ganeti.org/docs/ganeti/3.0/html/hooks.html,cluster execution hooks}.
- @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} (default: @code{#f})
- The file extension for variants of this OS type. For example @file{.conf}
- or @file{.scm}. It will be appended to the variant file name if set.
- @item @code{variants} (default: @code{'()})
- This must be either a list of @code{ganeti-os-variant} objects for this OS,
- or a ``file-like'' object (@pxref{G-Expressions, file-like objects})
- representing the variants directory.
- To use the Guix OS provider with variant definitions residing in a local
- directory instead of declaring individual variants (see @var{guix-variants}
- below), you can do:
- @lisp
- (ganeti-os
- (name "guix")
- (variants (local-file "ganeti-guix-variants"
- #:recursive? #true)))
- @end lisp
- Note that you will need to maintain the @file{variants.list} file
- (see @code{@url{https://docs.ganeti.org/docs/ganeti/3.0/man/ganeti-os-interface.html,
- ganeti-os-interface(7)}})
- manually in this case.
- @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
- @defvar %default-debootstrap-hooks
- This variable contains hooks to configure networking and the GRUB bootloader.
- @end defvar
- @defvar %default-debootstrap-extra-pkgs
- This variable contains a list of packages suitable for a fully-virtualized guest.
- @end defvar
- @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 {Procedure} debootstrap-variant name 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 {Procedure} debootstrap-os 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 {Procedure} guix-variant name 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 {Procedure} guix-os 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
- @defvar %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 defvar
- @defvar %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 defvar
- 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}.
- @defvar 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 defvar
- @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
- @defvar 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 defvar
- @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
- @defvar 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 defvar
- @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
- @defvar 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 defvar
- @deftp {Data Type} ganeti-luxid-configuration
- This is the configuration for the @code{ganeti-luxid} service.
- @table @asis
- @item @code{ganeti} (default: @code{ganeti})
- The @code{ganeti} package to use for this service.
- @item @code{no-voting?} (default: @code{#f})
- The daemon will refuse to start if it cannot verify that the majority of
- cluster nodes believes that it is running on the master node. Set to
- @code{#t} to ignore such checks and start anyway (this can be dangerous).
- @item @code{debug?} (default: @code{#f})
- When true, the daemon performs additional logging for debugging purposes.
- @end table
- @end deftp
- @defvar 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{https://docs.ganeti.org/docs/ganeti/3.0/html/rapi.html, Ganeti Remote
- API documentation} for more information.
- The value of this service must be a @code{ganeti-rapi-configuration} object.
- @end defvar
- @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
- @defvar 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 defvar
- @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
- @defvar 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 defvar
- @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
- @defvar 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 defvar
- @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
- @defvar 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 defvar
- @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
- @defvar 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 defvar
- @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-type}, 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}.
- @defvar git-daemon-service-type
- Type for a service that runs @command{git daemon}, a simple TCP server to
- expose repositories over the Git protocol for anonymous access.
- The value for this service type is a @code{<git-daemon-configuration>}
- record, 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 defvar
- @deftp {Data Type} git-daemon-configuration
- Data type representing the configuration for @code{git-daemon-service-type}.
- @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 that will be passed to @command{git daemon}.@footnote{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 {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 @code{repository-cgit-configuration}
- @code{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 @code{repository-cgit-configuration} records.
- 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. There are optional Gitolite dependencies that
- are not included in the default package, such as Redis and git-annex.
- These features can be made available by using the @code{make-gitolite}
- procedure in the @code{(gnu packages version-control}) module to produce
- a variant of Gitolite with the desired additional dependencies.
- The following code returns a package in which the Redis and git-annex
- programs can be invoked by Gitolite's scripts:
- @example
- (use-modules (gnu packages databases)
- (gnu packages haskell-apps)
- (gnu packages version-control))
- (make-gitolite (list redis git-annex))
- @end example
- @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{local-code} (default: @code{"$rc@{GL_ADMIN_BASE@}/local"})
- Allows you to add your own non-core programs, or even override the
- shipped ones with your own.
- Please supply the FULL path to this variable. By default, directory
- called "local" in your gitolite clone is used, providing the benefits of
- versioning them as well as making changes to them without having to log
- on to the server.
- @item @code{unsafe-pattern} (default: @code{#f})
- An optional Perl regular expression for catching unsafe configurations in
- the configuration file. See
- @uref{https://gitolite.com/gitolite/git-config.html#compensating-for-unsafe_patt,
- Gitolite's documentation} for more information.
- When the value is not @code{#f}, it should be a string containing a Perl
- regular expression, such as @samp{"[`~#\$\&()|;<>]"}, which is the default
- value used by gitolite. It rejects any special character in configuration
- that might be interpreted by a shell, which is useful when sharing the
- administration burden with other people that do not otherwise have shell
- access on the server.
- @item @code{git-config-keys} (default: @code{""})
- Gitolite allows you to set git config values using the @samp{config}
- keyword. This setting allows control over the config keys to accept.
- @item @code{roles} (default: @code{'(("READERS" . 1) ("WRITERS" . ))})
- Set the role names allowed to be used by users running the perms command.
- @item @code{enable} (default: @code{'("help" "desc" "info" "perms" "writable" "ssh-authkeys" "git-config" "daemon" "gitweb")})
- This setting controls the commands and features to enable within Gitolite.
- @end table
- @end deftp
- @subsubheading Gitile Service
- @cindex Gitile service
- @cindex Git, forge
- @uref{https://git.lepiller.eu/gitile, Gitile} is a Git forge for viewing
- public git repository contents from a web browser.
- Gitile works best in collaboration with Gitolite, and will serve the public
- repositories from Gitolite by default. The service should listen only on
- a local port, and a webserver should be configured to serve static resources.
- The gitile service provides an easy way to extend the Nginx service for
- that purpose (@pxref{NGINX}).
- The following example will configure Gitile to serve repositories from a
- custom location, with some default messages for the home page and the
- footers.
- @lisp
- (service gitile-service-type
- (gitile-configuration
- (repositories "/srv/git")
- (base-git-url "https://myweb.site/git")
- (index-title "My git repositories")
- (intro '((p "This is all my public work!")))
- (footer '((p "This is the end")))
- (nginx-server-block
- (nginx-server-configuration
- (ssl-certificate
- "/etc/letsencrypt/live/myweb.site/fullchain.pem")
- (ssl-certificate-key
- "/etc/letsencrypt/live/myweb.site/privkey.pem")
- (listen '("443 ssl http2" "[::]:443 ssl http2"))
- (locations
- (list
- ;; Allow for https anonymous fetch on /git/ urls.
- (git-http-nginx-location-configuration
- (git-http-configuration
- (uri-path "/git/")
- (git-root "/var/lib/gitolite/repositories")))))))))
- @end lisp
- In addition to the configuration record, you should configure your git
- repositories to contain some optional information. First, your public
- repositories need to contain the @file{git-daemon-export-ok} magic file
- that allows Git to export the repository. Gitile uses the presence of this
- file to detect public repositories it should make accessible. To do so with
- Gitolite for instance, modify your @file{conf/gitolite.conf} to include
- this in the repositories you want to make public:
- @example
- repo foo
- R = daemon
- @end example
- In addition, Gitile can read the repository configuration to display more
- information on the repository. Gitile uses the gitweb namespace for its
- configuration. As an example, you can use the following in your
- @file{conf/gitolite.conf}:
- @example
- repo foo
- R = daemon
- desc = A long description, optionally with <i>HTML</i>, shown on the index page
- config gitweb.name = The Foo Project
- config gitweb.synopsis = A short description, shown on the main page of the project
- @end example
- Do not forget to commit and push these changes once you are satisfied. You
- may need to change your gitolite configuration to allow the previous
- configuration options to be set. One way to do that is to add the
- following service definition:
- @lisp
- (service gitolite-service-type
- (gitolite-configuration
- (admin-pubkey (local-file "key.pub"))
- (rc-file
- (gitolite-rc-file
- (umask #o0027)
- ;; Allow to set any configuration key
- (git-config-keys ".*")
- ;; Allow any text as a valid configuration value
- (unsafe-patt "^$")))))
- @end lisp
- @deftp {Data Type} gitile-configuration
- Data type representing the configuration for @code{gitile-service-type}.
- @table @asis
- @item @code{package} (default: @var{gitile})
- Gitile package to use.
- @item @code{host} (default: @code{"localhost"})
- The host on which gitile is listening.
- @item @code{port} (default: @code{8080})
- The port on which gitile is listening.
- @item @code{database} (default: @code{"/var/lib/gitile/gitile-db.sql"})
- The location of the database.
- @item @code{repositories} (default: @code{"/var/lib/gitolite/repositories"})
- The location of the repositories. Note that only public repositories will
- be shown by Gitile. To make a repository public, add an empty
- @file{git-daemon-export-ok} file at the root of that repository.
- @item @code{base-git-url}
- The base git url that will be used to show clone commands.
- @item @code{index-title} (default: @code{"Index"})
- The page title for the index page that lists all the available repositories.
- @item @code{intro} (default: @code{'()})
- The intro content, as a list of sxml expressions. This is shown above the list
- of repositories, on the index page.
- @item @code{footer} (default: @code{'()})
- The footer content, as a list of sxml expressions. This is shown on every
- page served by Gitile.
- @item @code{nginx-server-block}
- An nginx server block that will be extended and used as a reverse proxy by
- Gitile to serve its pages, and as a normal web server to serve its assets.
- You can use this block to add more custom URLs to your domain, such as a
- @code{/git/} URL for anonymous clones, or serving any other files you would
- like to serve.
- @end table
- @end deftp
- @node Game Services
- @subsection Game Services
- @subsubheading Joycond service
- @cindex joycond
- The joycond service allows the pairing of Nintendo joycon game
- controllers over Bluetooth. (@pxref{Desktop Services} for setting up
- Bluetooth.)
- @deftp {Data Type} joycond-configuration
- Data type representing the configuration of @command{joycond}.
- @table @asis
- @item @code{package} (default: @code{joycond})
- The joycond package to use.
- @end table
- @end deftp
- @defvar joycond-service-type
- Service type for the joycond service.
- @end defvar
- @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 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 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
- @subheading PAM Mount Volume Service
- @cindex pam volume mounting
- PAM mount volumes are automatically mounted at login by the PAM login
- service according to a set of per-volume rules. Because they are
- mounted by PAM the password entered during login may be used directly to
- mount authenticated volumes, such as @code{cifs}, using the same
- credentials.
- These volumes will be added in addition to any volumes directly
- specified in @code{pam-mount-rules}.
- Here is an example of a rule which will mount a remote CIFS share from
- @file{//remote-server/share} into a sub-directory of @file{/shares}
- named after the user logging in:
- @lisp
- (simple-service 'pam-mount-remote-share pam-mount-volume-service-type
- (list (pam-mount-volume
- (secondary-group "users")
- (file-system-type "cifs")
- (server "remote-server")
- (file-name "share")
- (mount-point "/shares/%(USER)")
- (options "nosuid,nodev,seal,cifsacl"))))
- @end lisp
- @deftp {Data Type} pam-mount-volume-service-type
- Configuration for a single volume to be mounted. Any fields not
- specified will be omitted from the run-time PAM configuration. See
- @uref{http://pam-mount.sourceforge.net/pam_mount.conf.5.html,
- the man page} for the default values when unspecified.
- @table @asis
- @item @code{user-name} (type: maybe-string)
- Mount the volume for the given user.
- @item @code{user-id} (type: maybe-integer-or-range)
- Mount the volume for the user with this ID. This field may also be
- specified as a pair of @code{(start . end)} indicating a range of user
- IDs for whom to mount the volume.
- @item @code{primary-group} (type: maybe-string)
- Mount the volume for users with this primary group name.
- @item @code{group-id} (type: maybe-integer-or-range)
- Mount the volume for the users with this primary group ID. This field
- may also be specified as a cons cell of @code{(start . end)} indicating
- a range of group ids for whom to mount the volume.
- @item @code{secondary-group} (type: maybe-string)
- Mount the volume for users who are members of this group as either a
- primary or secondary group.
- @item @code{file-system-type} (type: maybe-string)
- The file system type for the volume being mounted (e.g., @code{cifs})
- @item @code{no-mount-as-root?} (type: maybe-boolean)
- Whether or not to mount the volume with root privileges. This is
- normally disabled, but may be enabled for mounts of type @code{fuse}, or
- other user-level mounts.
- @item @code{server} (type: maybe-string)
- The name of the remote server to mount the volume from, when necessary.
- @item @code{file-name} (type: maybe-string)
- The location of the volume, either local or remote, depending on the
- @code{file-system-type}.
- @item @code{mount-point} (type: maybe-string)
- Where to mount the volume in the local file-system. This may be set to
- @file{~} to indicate the home directory of the user logging in. If this
- field is omitted then @file{/etc/fstab} is consulted for the mount
- destination.
- @item @code{options} (type: maybe-string)
- The options to be passed as-is to the underlying mount program.
- @item @code{ssh?} (type: maybe-boolean)
- Enable this option to pass the login password to SSH for use with mounts
- involving SSH (e.g., @code{sshfs}).
- @item @code{cipher} (type: maybe-string)
- Cryptsetup cipher name for the volume. To be used with the @code{crypt}
- @code{file-system-type}.
- @item @code{file-system-key-cipher} (type: maybe-string)
- Cipher name used by the target volume.
- @item @code{file-system-key-hash} (type: maybe-string)
- SSL hash name used by the target volume.
- @item @code{file-system-key-file-name} (type: maybe-string)
- File name of the file system key for the target volume.
- @end table
- @end deftp
- @node Guix Services
- @subsection Guix Services
- @subsubheading Build Farm Front-End (BFFE)
- The @uref{https://git.cbaines.net/guix/bffe/,Build Farm Front-End}
- assists with building Guix packages in bulk. It's responsible for
- submitting builds and displaying the status of the build farm.
- @defvar bffe-service-type
- Service type for the Build Farm Front-End. Its value must be a
- @code{bffe-configuration} object.
- @end defvar
- @deftp {Data Type} bffe-configuration
- Data type representing the configuration of the Build Farm Front-End.
- @table @asis
- @item @code{package} (default: @code{bffe})
- The Build Farm Front-End package to use.
- @item @code{user} (default: @code{"bffe"})
- The system user to run the service as.
- @item @code{group} (default: @code{"bffe"})
- The system group to run the service as.
- @item @code{arguments}
- A list of arguments to the Build Farm Front-End. These are passed to
- the @code{run-bffe-service} procedure when starting the service.
- For example, the following value directs the Build Farm Front-End to
- submit builds for derivations available from @code{data.guix.gnu.org} to
- the Build Coordinator instance assumed to be running on the same
- machine.
- @example
- (list
- #:build
- (list
- (build-from-guix-data-service
- (data-service-url "https://data.guix.gnu.org")
- (build-coordinator-url "http://127.0.0.1:8746")
- (branches '("master"))
- (systems '("x86_64-linux" "i686-linux"))
- (systems-and-targets
- (map (lambda (target)
- (cons "x86_64-linux" target))
- '("aarch64-linux-gnu"
- "i586-pc-gnu")))
- (build-priority (const 0))))
- #:web-server-args
- '(#:event-source "https://example.com"
- #:controller-args
- (#:title "example.com build farm")))
- @end example
- @item @code{extra-environment-variables} (default: @var{'()})
- Extra environment variables to set via the shepherd service.
- @end table
- @end deftp
- @subsubheading Guix Build Coordinator
- The @uref{https://git.cbaines.net/guix/build-coordinator/,Guix Build
- Coordinator} aids in distributing derivation builds among machines
- running an @dfn{agent}. The build daemon is still used to build the
- derivations, but the Guix Build Coordinator manages allocating builds
- and working with the results.
- The Guix Build Coordinator consists of one @dfn{coordinator}, and one or
- more connected @dfn{agent} processes. The coordinator process handles
- clients submitting builds, and allocating builds to agents. The agent
- processes talk to a build daemon to actually perform the builds, then
- send the results back to the coordinator.
- There is a script to run the coordinator component of the Guix Build
- Coordinator, but the Guix service uses a custom Guile script instead, to
- provide better integration with G-expressions used in the configuration.
- @defvar 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{parallel-hooks} (default: @var{'()})
- Hooks can be configured to run in parallel. This parameter is an
- association list of hooks to do in parallel, where the key is the symbol
- for the hook and the value is the number of threads to run.
- @item @code{guile} (default: @code{guile-3.0-latest})
- The Guile package with which to run the Guix Build Coordinator.
- @item @code{extra-environment-variables} (default: @var{'()})
- Extra environment variables to set via the shepherd service.
- @end table
- @end deftp
- @defvar guix-build-coordinator-agent-service-type
- Service type for a Guix Build Coordinator agent. Its value must be a
- @code{guix-build-coordinator-agent-configuration} object.
- @end defvar
- @deftp {Data Type} guix-build-coordinator-agent-configuration
- Data type representing the configuration a Guix Build Coordinator agent.
- @table @asis
- @item @code{package} (default: @code{guix-build-coordinator/agent-only})
- The Guix Build Coordinator package to use.
- @item @code{user} (default: @code{"guix-build-coordinator-agent"})
- The system user to run the service as.
- @item @code{coordinator} (default: @code{"http://localhost:8745"})
- The URI to use when connecting to the coordinator.
- @item @code{authentication}
- Record describing how this agent should authenticate with the
- coordinator. Possible record types are described below.
- @item @code{systems} (default: @code{#f})
- The systems for which this agent should fetch builds. The agent process
- will use the current system it's running on as the default.
- @item @code{max-parallel-builds} (default: @code{1})
- The number of builds to perform in parallel.
- @item @code{max-parallel-uploads} (default: @code{1})
- The number of uploads to perform in parallel.
- @item @code{max-allocated-builds} (default: @code{#f})
- The maximum number of builds this agent can be allocated.
- @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 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{guix-data-service-build-server-id} (default: @code{#f})
- The Guix Data Service build server ID corresponding to the builds being
- submitted. Providing this speeds up the submitting of builds as
- derivations that have already been submitted can be skipped before
- asking the coordinator to build them.
- @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 guix-data-service-type
- Service type for the Guix Data Service. Its value must be a
- @code{guix-data-service-configuration} object. The service optionally
- extends the getmail service, as the guix-commits mailing list is used to
- find out about changes in the Guix git repository.
- @end defvar
- @deftp {Data Type} guix-data-service-configuration
- Data type representing the configuration of the Guix Data Service.
- @table @asis
- @item @code{package} (default: @code{guix-data-service})
- The Guix Data Service package to use.
- @item @code{user} (default: @code{"guix-data-service"})
- The system user to run the service as.
- @item @code{group} (default: @code{"guix-data-service"})
- The system group to run the service as.
- @item @code{port} (default: @code{8765})
- The port to bind the web service to.
- @item @code{host} (default: @code{"127.0.0.1"})
- The host to bind the web service to.
- @item @code{getmail-idle-mailboxes} (default: @code{#f})
- If set, this is the list of mailboxes that the getmail service will be
- configured to listen to.
- @item @code{commits-getmail-retriever-configuration} (default: @code{#f})
- If set, this is the @code{getmail-retriever-configuration} object with
- which to configure getmail to fetch mail from the guix-commits mailing
- list.
- @item @code{extra-options} (default: @var{'()})
- Extra command line options for @code{guix-data-service}.
- @item @code{extra-process-jobs-options} (default: @var{'()})
- Extra command line options for @code{guix-data-service-process-jobs}.
- @end table
- @end deftp
- @subsubheading Nar Herder
- The @uref{https://git.cbaines.net/guix/nar-herder/about/,Nar Herder} is
- a utility for managing a collection of nars.
- @defvar nar-herder-type
- Service type for the Guix Data Service. Its value must be a
- @code{nar-herder-configuration} object. The service optionally
- extends the getmail service, as the guix-commits mailing list is used to
- find out about changes in the Guix git repository.
- @end defvar
- @deftp {Data Type} nar-herder-configuration
- Data type representing the configuration of the Guix Data Service.
- @table @asis
- @item @code{package} (default: @code{nar-herder})
- The Nar Herder package to use.
- @item @code{user} (default: @code{"nar-herder"})
- The system user to run the service as.
- @item @code{group} (default: @code{"nar-herder"})
- The system group to run the service as.
- @item @code{port} (default: @code{8734})
- The port to bind the server to.
- @item @code{host} (default: @code{"127.0.0.1"})
- The host to bind the server to.
- @item @code{mirror} (default: @code{#f})
- Optional URL of the other Nar Herder instance which should be mirrored.
- This means that this Nar Herder instance will download it's database,
- and keep it up to date.
- @item @code{database} (default: @code{"/var/lib/nar-herder/nar_herder.db"})
- Location for the database. If this Nar Herder instance is mirroring
- another, the database will be downloaded if it doesn't exist. If this
- Nar Herder instance isn't mirroring another, an empty database will be
- created.
- @item @code{database-dump} (default: @code{"/var/lib/nar-herder/nar_herder_dump.db"})
- Location of the database dump. This is created and regularly updated by
- taking a copy of the database. This is the version of the database that
- is available to download.
- @item @code{storage} (default: @code{#f})
- Optional location in which to store nars.
- @item @code{storage-limit} (default: @code{"none"})
- Limit in bytes for the nars stored in the storage location. This can
- also be set to ``none'' so that there is no limit.
- When the storage location exceeds this size, nars are removed according
- to the nar removal criteria.
- @item @code{storage-nar-removal-criteria} (default: @code{'()})
- Criteria used to remove nars from the storage location. These are used
- in conjunction with the storage limit.
- When the storage location exceeds the storage limit size, nars will be
- checked against the nar removal criteria and if any of the criteria
- match, they will be removed. This will continue until the storage
- location is below the storage limit size.
- Each criteria is specified by a string, then an equals sign, then
- another string. Currently, only one criteria is supported, checking if a
- nar is stored on another Nar Herder instance.
- @item @code{ttl} (default: @code{#f})
- Produce @code{Cache-Control} HTTP headers that advertise a time-to-live
- (TTL) of @var{ttl}. @var{ttl} must denote a duration: @code{5d} means 5
- days, @code{1m} means 1 month, and so on.
- This allows the user's Guix to keep substitute information in cache for
- @var{ttl}.
- @item @code{negative-ttl} (default: @code{#f})
- Similarly produce @code{Cache-Control} HTTP headers to advertise the
- time-to-live (TTL) of @emph{negative} lookups---missing store items, for
- which the HTTP 404 code is returned. By default, no negative TTL is
- advertised.
- @item @code{log-level} (default: @code{'DEBUG})
- Log level to use, specify a log level like @code{'INFO} to stop logging
- individual requests.
- @item @code{cached-compressions} (default: @code{'()})
- Activate generating cached nars with different compression details from
- the stored nars. This is a list of
- nar-herder-cached-compression-configuration records.
- @item @code{min-uses} (default: @code{3})
- When cached-compressions are enabled, generate cached nars when at least
- this number of requests are made for a nar.
- @item @code{workers} (default: @code{2})
- Number of cached nars to generate at a time.
- @item @code{nar-source} (default: @code{#f})
- Location to fetch nars from when computing cached compressions. By
- default, the storage location will be used.
- @item @code{extra-environment-variables} (default: @code{'()})
- Extra environment variables to set via the shepherd service.
- @end table
- @end deftp
- @deftp {Data Type} nar-herder-cached-compression-configuration
- Data type representing the cached compression configuration.
- @table @asis
- @item @code{type}
- Type of compression to use, e.g. @code{'zstd}.
- @item @code{workers} (default: @code{#f})
- Level of the compression to use.
- @item @code{directory} (default: @code{#f})
- Location to store the cached nars. If unspecified, they will be stored
- in /var/cache/nar-herder/nar/TYPE.
- @item @code{directory-max-size} (default: @code{#f})
- Maximum size in bytes of the directory.
- @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.
- @defvar 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 defvar
- @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
- @subsubheading fstrim Service
- @cindex fstrim service
- @cindex solid state drives, periodic trim
- @cindex solid state drives, trim
- The command @command{fstrim} can be used to discard (or @dfn{trim})
- unused blocks on a mounted file system.
- @c This was copied from the fstrim manpage, with some Texinfo touch-ups.
- @quotation Warning
- Running @command{fstrim} frequently, or even using
- @command{mount -o discard}, might negatively affect the lifetime of
- poor-quality SSD devices. For most desktop and server systems a
- sufficient trimming frequency is once a week. Note that not all devices
- support a queued trim, so each trim command incurs a performance penalty
- on whatever else might be trying to use the disk at the time.
- @end quotation
- @defvar fstrim-service-type
- Type for a service that periodically runs @command{fstrim}, whose value must
- be an @code{<fstrim-configuration>} object. The service can be instantiated
- in its default configuration with:
- @lisp
- (service fstrim-service-type)
- @end lisp
- @end defvar
- @c %start of fragment
- @deftp {Data Type} fstrim-configuration
- Available @code{fstrim-configuration} fields are:
- @table @asis
- @item @code{package} (default: @code{util-linux}) (type: file-like)
- The package providing the @command{fstrim} command.
- @item @code{schedule} (default: @code{"0 0 * * 0"}) (type: mcron-time)
- Schedule for launching @command{fstrim}. This can be a procedure, a
- list or a string. For additional information, see @ref{Guile
- Syntax,,Job specification,mcron,the mcron manual}. By default this is
- set to run weekly on Sunday at 00:00.
- @item @code{listed-in} (default: @code{'("/etc/fstab" "/proc/self/mountinfo")}) (type: maybe-list-of-strings)
- List of files in fstab or kernel mountinfo format. All missing or empty
- files are silently ignored. The evaluation of the list @emph{stops}
- after the first non-empty file. File systems with
- @code{X-fstrim.notrim} mount option in fstab are skipped.
- @item @code{verbose?} (default: @code{#t}) (type: boolean)
- Verbose execution.
- @item @code{quiet-unsupported?} (default: @code{#t}) (type: boolean)
- Suppress error messages if trim operation (ioctl) is unsupported.
- @item @code{extra-arguments} (type: maybe-list-of-strings)
- Extra options to append to @command{fstrim} (run @samp{man fstrim} for
- more information).
- @end table
- @end deftp
- @c %end of fragment
- @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}.
- @defvar 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 defvar
- @subsubheading Cachefilesd Service
- @cindex cachefilesd
- @cindex fscache, file system caching (Linux)
- The Cachefilesd service starts a daemon that caches network file system
- data locally. It is especially useful for NFS and AFS shares, where it
- reduces latencies for repeated access when reading files.
- The daemon can be configured as follows:
- @lisp
- (service cachefilesd-service-type
- (cachefilesd-configuration
- (cache-directory "/var/cache/fscache")))
- @end lisp
- @defvar cachefilesd-service-type
- The service type for starting @command{cachefilesd}. The value for this
- service type is a @code{cachefilesd-configuration}, whose only required
- field is @var{cache-directory}.
- @end defvar
- @c %start of fragment
- @deftp {Data Type} cachefilesd-configuration
- Available @code{cachefilesd-configuration} fields are:
- @table @asis
- @item @code{cachefilesd} (default: @code{cachefilesd}) (type: file-like)
- The cachefilesd package to use.
- @item @code{debug-output?} (default: @code{#f}) (type: boolean)
- Print debugging output to stderr.
- @item @code{use-syslog?} (default: @code{#t}) (type: boolean)
- Log to syslog facility instead of stdout.
- @item @code{scan?} (default: @code{#t}) (type: boolean)
- Scan for cachable objects.
- @item @code{cache-directory} (type: maybe-string)
- Location of the cache directory.
- @item @code{cache-name} (default: @code{"CacheFiles"}) (type: maybe-string)
- Name of cache (keep unique).
- @item @code{security-context} (type: maybe-string)
- SELinux security context.
- @item @code{pause-culling-for-block-percentage} (default: @code{7}) (type: maybe-non-negative-integer)
- Pause culling when available blocks exceed this percentage.
- @item @code{pause-culling-for-file-percentage} (default: @code{7}) (type: maybe-non-negative-integer)
- Pause culling when available files exceed this percentage.
- @item @code{resume-culling-for-block-percentage} (default: @code{5}) (type: maybe-non-negative-integer)
- Start culling when available blocks drop below this percentage.
- @item @code{resume-culling-for-file-percentage} (default: @code{5}) (type: maybe-non-negative-integer)
- Start culling when available files drop below this percentage.
- @item @code{pause-caching-for-block-percentage} (default: @code{1}) (type: maybe-non-negative-integer)
- Pause further allocations when available blocks drop below this
- percentage.
- @item @code{pause-caching-for-file-percentage} (default: @code{1}) (type: maybe-non-negative-integer)
- Pause further allocations when available files drop below this
- percentage.
- @item @code{log2-table-size} (default: @code{12}) (type: maybe-non-negative-integer)
- Size of tables holding cullable objects in logarithm of base 2.
- @item @code{cull?} (default: @code{#t}) (type: boolean)
- Create free space by culling (consumes system load).
- @item @code{trace-function-entry-in-kernel-module?} (default: @code{#f}) (type: boolean)
- Trace function entry in the kernel module (for debugging).
- @item @code{trace-function-exit-in-kernel-module?} (default: @code{#f}) (type: boolean)
- Trace function exit in the kernel module (for debugging).
- @item @code{trace-internal-checkpoints-in-kernel-module?} (default: @code{#f}) (type: boolean)
- Trace internal checkpoints in the kernel module (for debugging).
- @end table
- @end deftp
- @c %end of fragment
- @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}.
- @defvar 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 defvar
- @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.
- @defvar 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{#f})
- This is the priority of the swap device created from the zram device.
- @xref{Swap Space} for a description of swap priorities. You might want
- to set a specific priority for the zram device, otherwise it could end
- up not being used much for the reasons described there.
- @end table
- @end deftp
- @end defvar
- @node Hurd Services
- @subsection Hurd Services
- @defvar 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 defvar
- @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
- @defvar 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 defvar
- @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.
- @defvar fprintd-service-type
- The service type for @command{fprintd}, which provides the fingerprint
- reading capability.
- @lisp
- (service fprintd-service-type)
- @end lisp
- @end defvar
- @cindex sysctl
- @subsubheading System Control Service
- The @code{(gnu services sysctl)} provides a service to configure kernel
- parameters at boot.
- @defvar 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 defvar
- @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
- @defvar %default-sysctl-settings
- An association list specifying the default @command{sysctl} parameters
- on Guix System.
- @end defvar
- @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.
- @defvar 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 defvar
- @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.
- @defvar lirc-service-type
- Type for a service that runs @url{http://www.lirc.org, LIRC}, a daemon
- that decodes infrared signals from remote controls.
- The value for this service is a @code{<lirc-configuration>} object.
- @end defvar
- @deftp {Data Type} lirc-configuration
- Data type representing the configuration of @command{lircd}.
- @table @asis
- @item @code{lirc} (default: @code{lirc}) (type: file-like)
- Package object for @command{lirc}.
- @item @code{device} (default: @code{#f}) (type: string)
- @itemx @code{driver} (default: @code{#f}) (type: string)
- @itemx @code{config-file} (default: @code{#f}) (type: string-or-file-like)
- TODO. See @command{lircd} manual for details.
- @item @code{extra-options} (default: @code{'()}) (type: list-of-string)
- Additional command-line options to pass to @command{lircd}.
- @end table
- @end deftp
- @c TODO: Document <lirc-configuration>, preferably by refactoring this to use
- @c define-configuration and generating documentation from it.
- @cindex SPICE
- @subsubheading SPICE Service
- The @code{(gnu services spice)} module provides the following service.
- @defvar spice-vdagent-service-type
- Type of the 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 defvar
- @deftp {Data Type} spice-vdagent-configuration
- Data type representing the configuration of
- @code{spice-vdagent-service-type}.
- @table @asis
- @item @code{spice-vdagent} (default: @code{spice-vdagent}) (type: file-like)
- Package object for VDAGENT.
- @end table
- @end deftp
- @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.
- @defvar inputattach-service-type
- Type of a service that runs @command{inputattach} on a device and
- dispatches events from it.
- @end defvar
- @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:
- @defvar 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}).
- 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}).
- @quotation Note
- This service is also available for Guix Home, where it runs directly
- with your user privileges (@pxref{Miscellaneous Home Services,
- @code{home-dicod-service-type}}).
- @end quotation
- @end defvar
- @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
- @defvar %dicod-database:gcide
- A @code{<dicod-database>} object serving the GNU Collaborative International
- Dictionary of English using the @code{gcide} package.
- @end defvar
- The following is an example @code{dicod-service-type} configuration.
- @lisp
- (service dicod-service-type
- (dicod-configuration
- (handlers (list
- (dicod-handler
- (name "wordnet")
- (module "wordnet")
- (options
- (list #~(string-append "wnhome=" #$wordnet))))))
- (databases (list
- (dicod-database
- (name "wordnet")
- (complex? #t)
- (handler "wordnet"))
- %dicod-database:gcide))))
- @end lisp
- @cindex Docker
- @subsubheading Docker Service
- The @code{(gnu services docker)} module provides the following services.
- @defvar 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 defvar
- @deftp {Data Type} docker-configuration
- This is the data type representing the configuration of Docker and Containerd.
- @table @asis
- @item @code{docker} (default: @code{docker})
- The Docker daemon package to use.
- @item @code{docker-cli} (default: @code{docker-cli})
- The Docker client package to use.
- @item @code{containerd} (default: @var{containerd})
- The Containerd package to use.
- @item @code{proxy} (default @var{docker-libnetwork-cmd-proxy})
- The Docker user-land networking proxy package to use.
- @item @code{enable-proxy?} (default @code{#t})
- Enable or disable the use of the Docker user-land networking proxy.
- @item @code{debug?} (default @code{#f})
- Enable or disable debug output.
- @item @code{enable-iptables?} (default @code{#t})
- Enable or disable the addition of iptables rules.
- @item @code{environment-variables} (default: @code{'()})
- List of environment variables to set for @command{dockerd}.
- This must be a list of strings where each string has the form
- @samp{@var{key}=@var{value}} as in this example:
- @lisp
- (list "LANGUAGE=eo:ca:eu"
- "TMPDIR=/tmp/dockerd")
- @end lisp
- @end table
- @end deftp
- @cindex Singularity, container service
- @defvar 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 defvar
- @cindex Audit
- @subsubheading Auditd Service
- The @code{(gnu services auditd)} module provides the following service.
- @defvar 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 defvar
- @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.
- @defvar 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} (default @code{"rshiny"})
- The name of the binary or shell script located at @code{package/bin/} to
- run when the service is run.
- The common way to create this file is as follows:
- @lisp
- @dots{}
- (let* ((out (assoc-ref %outputs "out"))
- (targetdir (string-append out "/share/" ,name))
- (app (string-append out "/bin/" ,name))
- (Rbin (search-input-file %build-inputs "/bin/Rscript")))
- ;; @dots{}
- (mkdir-p (string-append out "/bin"))
- (call-with-output-file app
- (lambda (port)
- (format port
- "#!~a
- library(shiny)
- setwd(\"~a\")
- runApp(launch.browser=0, port=4202)~%\n"
- Rbin targetdir))))
- @end lisp
- @end table
- @end deftp
- @end defvar
- @cindex Nix
- @subsubheading Nix service
- The @code{(gnu services nix)} module provides the following service.
- @defvar 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 defvar
- @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-directory} (default: @code{"/tmp"})
- The directory where build directory are stored during builds.
- This is useful to change if, for example, the default location does not
- have enough space to hold build trees for big packages.
- This is similar to setting the @env{TMPDIR} environment variable for
- @command{guix-daemon}. @ref{Build Environment Setup, @env{TMPDIR}},
- for more info.
- @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
- @cindex Fail2Ban
- @subsubheading Fail2Ban service
- @uref{http://www.fail2ban.org/, @code{fail2ban}} scans log files
- (e.g. @code{/var/log/apache/error_log}) and bans IP addresses that show
- malicious signs -- repeated password failures, attempts to make use of
- exploits, etc.
- @code{fail2ban-service-type} service type is provided by the @code{(gnu
- services security)} module.
- This service type runs the @code{fail2ban} daemon. It can be configured
- in various ways, which are:
- @table @asis
- @item Basic configuration
- The basic parameters of the Fail2Ban service can be configured via its
- @code{fail2ban} configuration, which is documented below.
- @item User-specified jail extensions
- The @code{fail2ban-jail-service} function can be used to add new
- Fail2Ban jails.
- @item Shepherd extension mechanism
- Service developers can extend the @code{fail2ban-service-type} service
- type itself via the usual service extension mechanism.
- @end table
- @defvar fail2ban-service-type
- This is the type of the service that runs @code{fail2ban} daemon. Below
- is an example of a basic, explicit configuration:
- @lisp
- (append
- (list
- (service fail2ban-service-type
- (fail2ban-configuration
- (extra-jails
- (list
- (fail2ban-jail-configuration
- (name "sshd")
- (enabled? #t))))))
- ;; There is no implicit dependency on an actual SSH
- ;; service, so you need to provide one.
- (service openssh-service-type))
- %base-services)
- @end lisp
- @end defvar
- @deffn {Procedure} fail2ban-jail-service svc-type jail
- Extend @var{svc-type}, a @code{<service-type>} object with @var{jail}, a
- @code{fail2ban-jail-configuration} object.
- For example:
- @lisp
- (append
- (list
- (service
- ;; The 'fail2ban-jail-service' procedure can extend any service type
- ;; with a fail2ban jail. This removes the requirement to explicitly
- ;; extend services with fail2ban-service-type.
- (fail2ban-jail-service
- openssh-service-type
- (fail2ban-jail-configuration
- (name "sshd")
- (enabled? #t)))
- (openssh-configuration ...))))
- @end lisp
- @end deffn
- Below is the reference for the different @code{jail-service-type}
- configuration records.
- @c The documentation is to be auto-generated via
- @c 'generate-documentation'. See at the bottom of (gnu services
- @c security).
- @deftp {Data Type} fail2ban-configuration
- Available @code{fail2ban-configuration} fields are:
- @table @asis
- @item @code{fail2ban} (default: @code{fail2ban}) (type: package)
- The @code{fail2ban} package to use. It is used for both binaries and as
- base default configuration that is to be extended with
- @code{<fail2ban-jail-configuration>} objects.
- @item @code{run-directory} (default: @code{"/var/run/fail2ban"}) (type: string)
- The state directory for the @code{fail2ban} daemon.
- @item @code{jails} (default: @code{'()}) (type: list-of-fail2ban-jail-configurations)
- Instances of @code{<fail2ban-jail-configuration>} collected from
- extensions.
- @item @code{extra-jails} (default: @code{'()}) (type: list-of-fail2ban-jail-configurations)
- Instances of @code{<fail2ban-jail-configuration>} explicitly provided.
- @item @code{extra-content} (default: @code{'()}) (type: text-config)
- Extra raw content to add to the end of the @file{jail.local} file,
- provided as a list of file-like objects.
- @end table
- @end deftp
- @deftp {Data Type} fail2ban-ignore-cache-configuration
- Available @code{fail2ban-ignore-cache-configuration} fields are:
- @table @asis
- @item @code{key} (type: string)
- Cache key.
- @item @code{max-count} (type: integer)
- Cache size.
- @item @code{max-time} (type: integer)
- Cache time.
- @end table
- @end deftp
- @deftp {Data Type} fail2ban-jail-action-configuration
- Available @code{fail2ban-jail-action-configuration} fields are:
- @table @asis
- @item @code{name} (type: string)
- Action name.
- @item @code{arguments} (default: @code{'()}) (type: list-of-arguments)
- Action arguments.
- @end table
- @end deftp
- @deftp {Data Type} fail2ban-jail-configuration
- Available @code{fail2ban-jail-configuration} fields are:
- @table @asis
- @item @code{name} (type: string)
- Required name of this jail configuration.
- @item @code{enabled?} (default: @code{#t}) (type: boolean)
- Whether this jail is enabled.
- @item @code{backend} (type: maybe-symbol)
- Backend to use to detect changes in the @code{log-path}. The default is
- 'auto. To consult the defaults of the jail configuration, refer to the
- @file{/etc/fail2ban/jail.conf} file of the @code{fail2ban} package.
- @item @code{max-retry} (type: maybe-integer)
- The number of failures before a host get banned (e.g. @code{(max-retry
- 5)}).
- @item @code{max-matches} (type: maybe-integer)
- The number of matches stored in ticket (resolvable via tag
- @code{<matches>}) in action.
- @item @code{find-time} (type: maybe-string)
- The time window during which the maximum retry count must be reached for
- an IP address to be banned. A host is banned if it has generated
- @code{max-retry} during the last @code{find-time} seconds (e.g.
- @code{(find-time "10m")}). It can be provided in seconds or using
- Fail2Ban's "time abbreviation format", as described in @command{man 5
- jail.conf}.
- @item @code{ban-time} (type: maybe-string)
- The duration, in seconds or time abbreviated format, that a ban should
- last. (e.g. @code{(ban-time "10m")}).
- @item @code{ban-time-increment?} (type: maybe-boolean)
- Whether to consider past bans to compute increases to the default ban
- time of a specific IP address.
- @item @code{ban-time-factor} (type: maybe-string)
- The coefficient to use to compute an exponentially growing ban time.
- @item @code{ban-time-formula} (type: maybe-string)
- This is the formula used to calculate the next value of a ban time.
- @item @code{ban-time-multipliers} (type: maybe-string)
- Used to calculate next value of ban time instead of formula.
- @item @code{ban-time-max-time} (type: maybe-string)
- The maximum number of seconds a ban should last.
- @item @code{ban-time-rnd-time} (type: maybe-string)
- The maximum number of seconds a randomized ban time should last. This
- can be useful to stop ``clever'' botnets calculating the exact time an
- IP address can be unbanned again.
- @item @code{ban-time-overall-jails?} (type: maybe-boolean)
- When true, it specifies the search of an IP address in the database
- should be made across all jails. Otherwise, only the current jail of
- the ban IP address is considered.
- @item @code{ignore-self?} (type: maybe-boolean)
- Never ban the local machine's own IP address.
- @item @code{ignore-ip} (default: @code{'()}) (type: list-of-strings)
- A list of IP addresses, CIDR masks or DNS hosts to ignore.
- @code{fail2ban} will not ban a host which matches an address in this
- list.
- @item @code{ignore-cache} (type: maybe-fail2ban-ignore-cache-configuration)
- Provide cache parameters for the ignore failure check.
- @item @code{filter} (type: maybe-fail2ban-jail-filter-configuration)
- The filter to use by the jail, specified via a
- @code{<fail2ban-jail-filter-configuration>} object. By default, jails
- have names matching their filter name.
- @item @code{log-time-zone} (type: maybe-string)
- The default time zone for log lines that do not have one.
- @item @code{log-encoding} (type: maybe-symbol)
- The encoding of the log files handled by the jail. Possible values are:
- @code{'ascii}, @code{'utf-8} and @code{'auto}.
- @item @code{log-path} (default: @code{'()}) (type: list-of-strings)
- The file names of the log files to be monitored.
- @item @code{action} (default: @code{'()}) (type: list-of-fail2ban-jail-actions)
- A list of @code{<fail2ban-jail-action-configuration>}.
- @item @code{extra-content} (default: @code{'()}) (type: text-config)
- Extra content for the jail configuration, provided as a list of file-like
- objects.
- @end table
- @end deftp
- @deftp {Data Type} fail2ban-jail-filter-configuration
- Available @code{fail2ban-jail-filter-configuration} fields are:
- @table @asis
- @item @code{name} (type: string)
- Filter to use.
- @item @code{mode} (type: maybe-string)
- Mode for filter.
- @end table
- @end deftp
- @c End of auto-generated fail2ban documentation.
- @node Setuid Programs
- @section Setuid Programs
- @cindex setuid programs
- @cindex setgid programs
- Some programs need to run with elevated 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, @command{passwd} should be
- @dfn{setuid-root}, meaning that it always runs 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 or setgid bits directly on files that
- are in the store, we let the system administrator @emph{declare} which
- programs should be entrusted with these additional privileges.
- The @code{setuid-programs} field of an @code{operating-system}
- declaration contains a list of @code{<setuid-program>} denoting the
- names of programs to have a setuid or setgid bit set (@pxref{Using the
- Configuration System}). For instance, the @command{mount.nfs} program,
- which is part of the nfs-utils package, with a setuid root can be
- designated like this:
- @lisp
- (setuid-program
- (program (file-append nfs-utils "/sbin/mount.nfs")))
- @end lisp
- And then, to make @command{mount.nfs} setuid on your system, add the
- previous example to your operating system declaration by appending it to
- @code{%setuid-programs} like this:
- @lisp
- (operating-system
- ;; Some fields omitted...
- (setuid-programs
- (append (list (setuid-program
- (program (file-append nfs-utils "/sbin/mount.nfs"))))
- %setuid-programs)))
- @end lisp
- @deftp {Data Type} setuid-program
- This data type represents a program with a setuid or setgid bit set.
- @table @asis
- @item @code{program}
- A file-like object having its setuid and/or setgid bit set.
- @item @code{setuid?} (default: @code{#t})
- Whether to set user setuid bit.
- @item @code{setgid?} (default: @code{#f})
- Whether to set group setgid bit.
- @item @code{user} (default: @code{0})
- UID (integer) or user name (string) for the user owner of the program,
- defaults to root.
- @item @code{group} (default: @code{0})
- GID (integer) group 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.
- @defvar %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 defvar
- 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}
- For users of Guix System, 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.
- @defvar %default-nss
- This is the default name service switch configuration, a
- @code{name-service-switch} object.
- @end defvar
- @defvar %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 defvar
- 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
- @defvar %base-initrd-modules
- This is the list of kernel modules included in the initrd by default.
- @end defvar
- Furthermore, if you need lower-level customization, the @code{initrd}
- field of an @code{operating-system} declaration allows
- you to specify which initrd you would like to use. The @code{(gnu
- system linux-initrd)} module provides three ways to build an initrd: the
- high-level @code{base-initrd} procedure and the low-level
- @code{raw-initrd} and @code{expression->initrd} procedures.
- The @code{base-initrd} procedure is intended to cover most common uses.
- For example, if you want to add a bunch of kernel modules to be loaded
- at boot time, you can define the @code{initrd} field of the operating
- system declaration like this:
- @lisp
- (initrd (lambda (file-systems . rest)
- ;; Create a standard initrd but set up networking
- ;; with the parameters QEMU expects by default.
- (apply base-initrd file-systems
- #:qemu-networking? #t
- rest)))
- @end lisp
- The @code{base-initrd} procedure also handles common use cases that
- involves using the system as a QEMU guest, or as a ``live'' system with
- volatile root file system.
- The @code{base-initrd} procedure is built from @code{raw-initrd} procedure.
- Unlike @code{base-initrd}, @code{raw-initrd} doesn't do anything high-level,
- such as trying to guess which kernel modules and packages should be included
- to the initrd. An example use of @code{raw-initrd} is when a user has
- a custom Linux kernel configuration and default kernel modules included by
- @code{base-initrd} are not available.
- The initial RAM disk produced by @code{base-initrd} or @code{raw-initrd}
- honors several options passed on the Linux kernel command line
- (that is, arguments passed @i{via} the @code{linux} command of GRUB, or the
- @code{-append} option of QEMU), notably:
- @table @code
- @item gnu.load=@var{boot}
- Tell the initial RAM disk to load @var{boot}, a file containing a Scheme
- program, once it has mounted the root file system.
- Guix uses this option to yield control to a boot program that runs the
- service activation programs and then spawns the GNU@tie{}Shepherd, the
- initialization system.
- @item root=@var{root}
- Mount @var{root} as the root file system. @var{root} can be a device
- name like @code{/dev/sda1}, a file system label, or a file system UUID.
- When unspecified, the device name from the root file system of the
- operating system declaration is used.
- @item rootfstype=@var{type}
- Set the type of the root file system. It overrides the @code{type}
- field of the root file system specified via the @code{operating-system}
- declaration, if any.
- @item rootflags=@var{options}
- Set the mount @emph{options} of the root file system. It overrides the
- @code{options} field of the root file system specified via the
- @code{operating-system} declaration, if any.
- @item fsck.mode=@var{mode}
- Whether to check the @var{root} file system for errors before mounting
- it. @var{mode} is one of @code{skip} (never check), @code{force} (always
- check), or @code{auto} to respect the root @code{<file-system>} object's
- @code{check?} setting (@pxref{File Systems}) and run a full scan only if
- the file system was not cleanly shut down.
- @code{auto} is the default if this option is not present or if @var{mode}
- is not one of the above.
- @item fsck.repair=@var{level}
- The level of repairs to perform automatically if errors are found in the
- @var{root} file system. @var{level} is one of @code{no} (do not write to
- @var{root} at all if possible), @code{yes} (repair as much as possible),
- or @code{preen} to repair problems considered safe to repair automatically.
- @code{preen} is the default if this option is not present or if @var{level}
- is not one of the above.
- @item gnu.system=@var{system}
- Have @file{/run/booted-system} and @file{/run/current-system} point to
- @var{system}.
- @item modprobe.blacklist=@var{modules}@dots{}
- @cindex module, black-listing
- @cindex black list, of kernel modules
- Instruct the initial RAM disk as well as the @command{modprobe} command
- (from the kmod package) to refuse to load @var{modules}. @var{modules}
- must be a comma-separated list of module names---e.g.,
- @code{usbkbd,9pnet}.
- @item gnu.repl
- Start a read-eval-print loop (REPL) from the initial RAM disk before it
- tries to load kernel modules and to mount the root file system. Our
- marketing team calls it @dfn{boot-to-Guile}. The Schemer in you will
- love it. @xref{Using Guile Interactively,,, guile, GNU Guile Reference
- Manual}, for more information on Guile's REPL.
- @end table
- Now that you know all the features that initial RAM disks produced by
- @code{base-initrd} and @code{raw-initrd} provide,
- here is how to use it and customize it further.
- @cindex initrd
- @cindex initial RAM disk
- @deffn {Procedure} raw-initrd file-systems @
- [#:linux-modules '()] [#:pre-mount #t] [#: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{pre-mount} is a G-expression to evaluate before realizing
- @var{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 {Procedure} base-initrd 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 {Procedure} expression->initrd 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-removable-bootloader}, @code{grub-efi-netboot-bootloader},
- @code{grub-efi-netboot-removable-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-bootloader
- @code{grub-bootloader} allows you to boot in particular Intel-based machines
- in ``legacy'' BIOS mode.
- @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-efi-removable-bootloader
- @code{grub-efi-removable-bootloader} allows you to boot your system from
- removable media by writing the GRUB file to the UEFI-specification location of
- @file{/EFI/BOOT/BOOTX64.efi} of the boot directory, usually @file{/boot/efi}.
- This is also useful for some UEFI firmwares that ``forget'' their configuration
- from their non-volatile storage. Like @code{grub-efi-bootloader}, this can only
- be used if the @file{/sys/firmware/efi} directory is available.
- @quotation Note
- This @emph{will} overwrite the GRUB file from any other operating systems that
- also place their GRUB file in the UEFI-specification location; making them
- unbootable.
- @end quotation
- @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}}) below the sub-directory @file{efi/Guix}, 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 during installation.
- 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 for 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. It is advised to disable any TFTP
- write access!
- Please note, that this bootloader will not modify the ‘UEFI Boot Manager’ of
- the system.
- 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}.
- If a local EFI System Partition (ESP) or a similar partition with a FAT
- file system is mounted in @code{targets}, then symlinks cannot be
- created. In this case everything will be prepared for booting from
- local storage, matching the behavior of @code{grub-efi-bootloader}, with
- the difference that all GRUB binaries are copied to @code{targets},
- necessary for booting over the network.
- @vindex grub-efi-netboot-removable-bootloader
- @code{grub-efi-netboot-removable-bootloader} is identical to
- @code{grub-efi-netboot-bootloader} with the exception that the
- sub-directory @file{efi/boot} will be used instead of @file{efi/Guix} to
- comply with the UEFI specification for removable media.
- @quotation Note
- This @emph{will} overwrite the GRUB file from any other operating systems that
- also place their GRUB file in the UEFI-specification location; making them
- unbootable.
- @end quotation
- @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} and
- @code{grub-efi-removable-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}).
- @item @code{device-tree-support?} (default: @code{#t})
- Whether to support Linux @uref{https://en.wikipedia.org/wiki/Devicetree,
- device tree} files loading.
- This option in enabled by default. In some cases involving the
- @code{u-boot} bootloader, where the device tree has already been loaded
- in RAM, it can be handy to disable the option by setting it to
- @code{#f}.
- @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.
- For example, when running in QEMU it can be useful to use a text-based
- console (use options @option{--nographic} @option{--serial mon:stdio}):
- @lisp
- '("console=com0")
- @end lisp
- To use the new and still experimental
- @uref{https://darnassus.sceen.net/~hurd-web/rump_kernel/, rumpdisk
- user-level disk driver} instead of GNU@tie{}Mach's in-kernel IDE driver,
- set @code{kernel-arguments} to:
- @lisp
- '("noide")
- @end lisp
- Of course, these options can be combined:
- @lisp
- '("console=com0" "noide")
- @end lisp
- +@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
- @item @code{chain-loader} (default: @code{#f})
- A string that can be accepted by @code{grub}'s @code{chainloader}
- directive. This has no effect if either @code{linux} or
- @code{multiboot-kernel} fields are specified. The following is an
- example of chainloading a different GNU/Linux system.
- @lisp
- (bootloader
- (bootloader-configuration
- ;; @dots{}
- (menu-entries
- (list
- (menu-entry
- (label "GNU/Linux")
- (device (uuid "1C31-A17C" 'fat))
- (chain-loader "/EFI/GNULinux/grubx64.efi"))))))
- @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 {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 @command{guix system}
- @cindex @command{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}).
- @cindex service type definition, editing
- @cindex editing, service type definition
- @item edit
- Edit or view the definition of the given service types.
- For example, the command below opens your editor, as specified by the
- @env{EDITOR} environment variable, on the definition of the
- @code{openssh} service type:
- @example
- guix system edit openssh
- @end example
- @item reconfigure
- Build the operating system described in @var{file}, activate it, and
- switch to it@footnote{This action (and the related actions
- @code{switch-generation} and @code{roll-back}) are usable only on
- systems already running Guix System.}.
- @quotation Note
- @c The paragraph below refers to the problem discussed at
- @c <https://lists.gnu.org/archive/html/guix-devel/2014-08/msg00057.html>.
- It is highly recommended to run @command{guix pull} once before you run
- @command{guix system reconfigure} for the first time (@pxref{Invoking
- guix pull}). Failing to do that you would see an older version of Guix
- once @command{reconfigure} has completed.
- @end quotation
- This effects all the configuration specified in @var{file}: user
- accounts, system services, global package list, setuid programs, etc.
- The command starts system services specified in @var{file} that are not
- currently running; if a service is currently running this command will
- arrange for it to be upgraded the next time it is stopped (e.g.@: by
- @code{herd stop X} or @code{herd restart X}).
- This command creates a new generation whose number is one greater than
- the current generation (as reported by @command{guix system
- list-generations}). If that generation already exists, it will be
- overwritten. This behavior mirrors that of @command{guix package}
- (@pxref{Invoking guix package}).
- It also adds a bootloader menu entry for the new OS configuration,
- ---unless @option{--no-bootloader} is passed. For GRUB, it moves
- entries for older configurations to a submenu, allowing you to choose
- an older system generation at boot time should you need it.
- @cindex provenance tracking, of the operating system
- Upon completion, the new system is deployed under
- @file{/run/current-system}. This directory contains @dfn{provenance
- meta-data}: the list of channels in use (@pxref{Channels}) and
- @var{file} itself, when available. You can view it by running:
- @example
- guix system describe
- @end example
- This information is useful should you later want to inspect how this
- particular generation was built. In fact, assuming @var{file} is
- self-contained, you can later rebuild generation @var{n} of your
- operating system with:
- @example
- guix time-machine \
- -C /var/guix/profiles/system-@var{n}-link/channels.scm -- \
- system reconfigure \
- /var/guix/profiles/system-@var{n}-link/configuration.scm
- @end example
- You can think of it as some sort of built-in version control! Your
- system is not just a binary artifact: @emph{it carries its own source}.
- @xref{Service Reference, @code{provenance-service-type}}, for more
- information on provenance tracking.
- By default, @command{reconfigure} @emph{prevents you from downgrading
- your system}, which could (re)introduce security vulnerabilities and
- also cause problems with ``stateful'' services such as database
- management systems. You can override that behavior by passing
- @option{--allow-downgrades}.
- @item switch-generation
- @cindex generations
- Switch to an existing system generation. This action atomically
- switches the system profile to the specified system generation. It
- also rearranges the system's existing bootloader menu entries. It
- makes the menu entry for the specified system generation the default,
- and it moves the entries for the other generations to a submenu, if
- supported by the bootloader being used. The next time the system
- boots, it will use the specified system generation.
- The bootloader itself is not being reinstalled when using this
- command. Thus, the installed bootloader is used with an updated
- configuration file.
- The target generation can be specified explicitly by its generation
- number. For example, the following invocation would switch to system
- generation 7:
- @example
- guix system switch-generation 7
- @end example
- The target generation can also be specified relative to the current
- generation with the form @code{+N} or @code{-N}, where @code{+3} means
- ``3 generations ahead of the current generation,'' and @code{-1} means
- ``1 generation prior to the current generation.'' When specifying a
- negative value such as @code{-1}, you must precede it with @code{--} to
- prevent it from being parsed as an option. For example:
- @example
- guix system switch-generation -- -1
- @end example
- Currently, the effect of invoking this action is @emph{only} to switch
- the system profile to an existing generation and rearrange the
- bootloader menu entries. To actually start using the target system
- generation, you must reboot after running this action. In the future,
- it will be updated to do the same things as @command{reconfigure},
- like activating and deactivating services.
- This action will fail if the specified generation does not exist.
- @item roll-back
- @cindex rolling back
- Switch to the preceding system generation. The next time the system
- boots, it will use the preceding system generation. This is the inverse
- of @command{reconfigure}, and it is exactly the same as invoking
- @command{switch-generation} with an argument of @code{-1}.
- Currently, as with @command{switch-generation}, you must reboot after
- running this action to actually start using the preceding system
- generation.
- @item delete-generations
- @cindex deleting system generations
- @cindex saving space
- Delete system generations, making them candidates for garbage collection
- (@pxref{Invoking guix gc}, for information on how to run the ``garbage
- collector'').
- This works in the same way as @samp{guix package --delete-generations}
- (@pxref{Invoking guix package, @option{--delete-generations}}). With no
- arguments, all system generations but the current one are deleted:
- @example
- guix system delete-generations
- @end example
- You can also select the generations you want to delete. The example below
- deletes all the system generations that are more than two months old:
- @example
- guix system delete-generations 2m
- @end example
- Running this command automatically reinstalls the bootloader with an updated
- list of menu entries---e.g., the ``old generations'' sub-menu in GRUB no
- longer lists the generations that have been deleted.
- @item build
- Build the derivation of the operating system, which includes all the
- configuration files and programs needed to boot and run the system.
- This action does not actually install anything.
- @item init
- Populate the given directory with all the files necessary to run the
- operating system specified in @var{file}. This is useful for first-time
- installations of Guix System. For instance:
- @example
- guix system init my-os-config.scm /mnt
- @end example
- copies to @file{/mnt} all the store items required by the configuration
- specified in @file{my-os-config.scm}. This includes configuration
- files, packages, and so on. It also creates other essential files
- needed for the system to operate correctly---e.g., the @file{/etc},
- @file{/var}, and @file{/run} directories, and the @file{/bin/sh} file.
- This command also installs bootloader on the targets specified in
- @file{my-os-config}, unless the @option{--no-bootloader} option was
- passed.
- @item vm
- @cindex virtual machine
- @cindex VM
- @anchor{guix system vm}
- Build a virtual machine (VM) that contains the operating system declared
- in @var{file}, and return a script to run that VM.
- @quotation Note
- The @code{vm} action and others below
- can use KVM support in the Linux-libre kernel. Specifically, if the
- machine has hardware virtualization support, the corresponding
- KVM kernel module should be loaded, and the @file{/dev/kvm} device node
- must exist and be readable and writable by the user and by the
- build users of the daemon (@pxref{Build Environment Setup}).
- @end quotation
- Arguments given to the script are passed to QEMU as in the example
- below, which enables networking and requests 1@tie{}GiB of RAM for the
- emulated machine:
- @example
- $ /gnu/store/@dots{}-run-vm.sh -m 1024 -smp 2 -nic user,model=virtio-net-pci
- @end example
- It's possible to combine the two steps into one:
- @example
- $ $(guix system vm my-config.scm) -m 1024 -smp 2 -nic user,model=virtio-net-pci
- @end example
- The VM shares its store with the host system.
- By default, the root file system of the VM is mounted volatile; the
- @option{--persistent} option can be provided to make it persistent
- instead. In that case, the VM disk-image file will be copied from the
- store to the @env{TMPDIR} directory to make it writable.
- Additional file systems can be shared between the host and the VM using
- the @option{--share} and @option{--expose} command-line options: the former
- specifies a directory to be shared with write access, while the latter
- provides read-only access to the shared directory.
- The example below creates a VM in which the user's home directory is
- accessible read-only, and where the @file{/exchange} directory is a
- read-write mapping of @file{$HOME/tmp} on the host:
- @example
- guix system vm my-config.scm \
- --expose=$HOME --share=$HOME/tmp=/exchange
- @end example
- On GNU/Linux, the default is to boot directly to the kernel; this has
- the advantage of requiring only a very tiny root disk image since the
- store of the host can then be mounted.
- The @option{--full-boot} option forces a complete boot sequence, starting
- with the bootloader. This requires more disk space since a root image
- containing at least the kernel, initrd, and bootloader data files must
- be created.
- The @option{--image-size} option can be used to specify the size of the
- image.
- The @option{--no-graphic} option will instruct @command{guix system} to
- spawn a headless VM that will use the invoking tty for IO. Among other
- things, this enables copy-pasting, and scrollback. Use the @kbd{ctrl-a}
- prefix to issue QEMU commands; e.g. @kbd{ctrl-a h} prints a help,
- @kbd{ctrl-a x} quits the VM, and @kbd{ctrl-a c} switches between the
- QEMU monitor and the VM.
- @cindex System images, creation in various formats
- @cindex Creating system images in various formats
- @item image
- @cindex image, creating disk images
- The @code{image} command can produce various image types. The image
- type can be selected using the @option{--image-type} option. It
- defaults to @code{mbr-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{mbr-raw} image type, a raw disk image is produced;
- it can be copied as is to a USB stick, for instance. Assuming
- @code{/dev/sdc} is the device corresponding to a USB stick, one can copy
- the image to it using the following command:
- @example
- # dd if=$(guix system image my-os.scm) of=/dev/sdc status=progress
- @end example
- The @code{--list-image-types} command lists all the available image
- types.
- @cindex creating virtual machine images
- When using the @code{qcow2} image type, the returned image is in qcow2
- format, which the QEMU emulator can efficiently use. @xref{Running Guix
- in a VM}, for more information on how to run the image in a virtual
- machine. The @code{grub-bootloader} bootloader is always used
- independently of what is declared in the @code{operating-system} file
- passed as argument. This is to make it easier to work with QEMU, which
- uses the SeaBIOS BIOS by default, expecting a bootloader to be installed
- in the Master Boot Record (MBR).
- @cindex docker-image, creating docker images
- When using the @code{docker} image type, a Docker image is produced.
- Guix builds the image from scratch, not from a pre-existing Docker base
- image. As a result, it contains @emph{exactly} what you define in the
- operating system configuration file. You can then load the image and
- launch a Docker container using commands like the following:
- @example
- image_id="$(docker load < guix-system-docker-image.tar.gz)"
- container_id="$(docker create $image_id)"
- docker start $container_id
- @end example
- This command starts a new Docker container from the specified image. It
- will boot the Guix system in the usual manner, which means it will
- start any services you have defined in the operating system
- configuration. You can get an interactive shell running in the container
- using @command{docker exec}:
- @example
- docker exec -ti $container_id /run/current-system/profile/bin/bash --login
- @end example
- Depending on what you run in the Docker container, it
- may be necessary to give the container additional permissions. For
- example, if you intend to build software using Guix inside of the Docker
- container, you may need to pass the @option{--privileged} option to
- @code{docker create}.
- Last, the @option{--network} option applies to @command{guix system
- docker-image}: it produces an image where network is supposedly shared
- with the host, and thus without services like nscd or NetworkManager.
- @item container
- Return a script to run the operating system declared in @var{file}
- within a container. Containers are a set of lightweight isolation
- mechanisms provided by the kernel Linux-libre. Containers are
- substantially less resource-demanding than full virtual machines since
- the kernel, shared objects, and other resources can be shared with the
- host system; this also means they provide thinner isolation.
- Currently, the script must be run as root in order to support more than
- a single user and group. The container shares its store with the host
- system.
- As with the @code{vm} action (@pxref{guix system vm}), additional file
- systems to be shared between the host and container can be specified
- using the @option{--share} and @option{--expose} options:
- @example
- guix system container my-config.scm \
- --expose=$HOME --share=$HOME/tmp=/exchange
- @end example
- The @option{--share} and @option{--expose} options can also be passed to
- the generated script to bind-mount additional directories into the
- container.
- @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 --target=@var{triplet}
- 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 --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{mbr-raw} image type.
- @cindex ISO-9660 format
- @cindex CD image format
- @cindex DVD image format
- @option{--image-type=iso9660} produces an ISO-9660 image, suitable
- for burning on CDs and DVDs.
- @item --image-size=@var{size}
- For the @code{image} action, create an image of the given @var{size}.
- @var{size} may be a number of bytes, or it may include a unit as a
- suffix (@pxref{Block size, size specifications,, coreutils, GNU
- Coreutils}).
- When this option is omitted, @command{guix system} computes an estimate
- of the image size as a function of the size of the system declared in
- @var{file}.
- @item --network
- @itemx -N
- For the @code{container} action, allow containers to access the host network,
- that is, do not create a network namespace.
- @item --root=@var{file}
- @itemx -r @var{file}
- Make @var{file} a symlink to the result, and register it as a garbage
- collector root.
- @item --skip-checks
- Skip pre-installation safety checks.
- By default, @command{guix system init} and @command{guix system
- reconfigure} perform safety checks: they make sure the file systems that
- appear in the @code{operating-system} declaration actually exist
- (@pxref{File Systems}), and that any Linux kernel modules that may be
- needed at boot time are listed in @code{initrd-modules} (@pxref{Initial
- RAM Disk}). Passing this option skips these tests altogether.
- @item --allow-downgrades
- Instruct @command{guix system reconfigure} to allow system downgrades.
- By default, @command{reconfigure} prevents you from downgrading your
- system. It achieves that by comparing the provenance info of your
- system (shown by @command{guix system describe}) with that of your
- @command{guix} command (shown by @command{guix describe}). If the
- commits for @command{guix} are not descendants of those used for your
- system, @command{guix system reconfigure} errors out. Passing
- @option{--allow-downgrades} allows you to bypass these checks.
- @quotation Note
- Make sure you understand its security implications before using
- @option{--allow-downgrades}.
- @end quotation
- @cindex on-error
- @cindex on-error strategy
- @cindex error strategy
- @item --on-error=@var{strategy}
- Apply @var{strategy} when an error occurs when reading @var{file}.
- @var{strategy} may be one of the following:
- @table @code
- @item nothing-special
- Report the error concisely and exit. This is the default strategy.
- @item backtrace
- Likewise, but also display a backtrace.
- @item debug
- Report the error and enter Guile's debugger. From there, you can run
- commands such as @code{,bt} to get a backtrace, @code{,locals} to
- display local variable values, and more generally inspect the state of the
- program. @xref{Debug Commands,,, guile, GNU Guile Reference Manual}, for
- a list of available debugging commands.
- @end table
- @end table
- Once you have built, configured, re-configured, and re-re-configured
- your Guix installation, you may find it useful to list the operating
- system generations available on disk---and that you can choose from the
- bootloader boot menu:
- @table @code
- @item describe
- Describe the running system generation: its file name, the kernel and
- bootloader used, etc., as well as provenance information when available.
- The @code{--list-installed} flag is available, with the same
- syntax that is used in @command{guix package --list-installed}
- (@pxref{Invoking guix package}). When the flag is used,
- the description will include a list of packages that are currently
- installed in the system profile, with optional filtering based on a
- regular expression.
- @quotation Note
- The @emph{running} system generation---referred to by
- @file{/run/current-system}---is not necessarily the @emph{current}
- system generation---referred to by @file{/var/guix/profiles/system}: it
- differs when, for instance, you chose from the bootloader menu to boot
- an older generation.
- It can also differ from the @emph{booted} system generation---referred
- to by @file{/run/booted-system}---for instance because you reconfigured
- the system in the meantime.
- @end quotation
- @item list-generations
- List a summary of each generation of the operating system available on
- disk, in a human-readable way. This is similar to the
- @option{--list-generations} option of @command{guix package}
- (@pxref{Invoking guix package}).
- Optionally, one can specify a pattern, with the same syntax that is used
- in @command{guix package --list-generations}, to restrict the list of
- generations displayed. For instance, the following command displays
- generations that are up to 10 days old:
- @example
- $ guix system list-generations 10d
- @end example
- The @code{--list-installed} flag may also be specified, with the same
- syntax that is used in @command{guix package --list-installed}. This
- may be helpful if trying to determine when a package was added to the
- system.
- @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.
- @quotation Note
- The @command{dot} program is provided by the @code{graphviz} package.
- @end quotation
- @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 @command{guix deploy}
- @cindex @command{guix deploy}
- We've already seen @code{operating-system} declarations used to manage a
- machine's configuration locally. Suppose you need to configure multiple
- machines, though---perhaps you're managing a service on the web that's
- comprised of several servers. @command{guix deploy} enables you to use those
- same @code{operating-system} declarations to manage multiple remote hosts at
- once as a logical ``deployment''.
- @quotation Note
- The functionality described in this section is still under development
- and is subject to change. Get in touch with us on
- @email{guix-devel@@gnu.org}!
- @end quotation
- @example
- guix deploy @var{file}
- @end example
- Such an invocation will deploy the machines that the code within @var{file}
- evaluates to. As an example, @var{file} might contain a definition like this:
- @lisp
- ;; This is a Guix deployment of a "bare bones" setup, with
- ;; no X11 display server, to a machine with an SSH daemon
- ;; listening on localhost:2222. A configuration such as this
- ;; may be appropriate for virtual machine with ports
- ;; forwarded to the host's loopback interface.
- (use-service-modules networking ssh)
- (use-package-modules bootloaders)
- (define %system
- (operating-system
- (host-name "gnu-deployed")
- (timezone "Etc/UTC")
- (bootloader (bootloader-configuration
- (bootloader grub-bootloader)
- (targets '("/dev/vda"))
- (terminal-outputs '(console))))
- (file-systems (cons (file-system
- (mount-point "/")
- (device "/dev/vda1")
- (type "ext4"))
- %base-file-systems))
- (services
- (append (list (service dhcp-client-service-type)
- (service openssh-service-type
- (openssh-configuration
- (permit-root-login #t)
- (allow-empty-passwords? #t))))
- %base-services))))
- (list (machine
- (operating-system %system)
- (environment managed-host-environment-type)
- (configuration (machine-ssh-configuration
- (host-name "localhost")
- (system "x86_64-linux")
- (user "alice")
- (identity "./id_rsa")
- (port 2222)))))
- @end lisp
- The file should evaluate to a list of @var{machine} objects. This example,
- upon being deployed, will create a new generation on the remote system
- realizing the @code{operating-system} declaration @code{%system}.
- @code{environment} and @code{configuration} specify how the machine should be
- provisioned---that is, how the computing resources should be created and
- managed. The above example does not create any resources, as a
- @code{'managed-host} is a machine that is already running the Guix system and
- available over the network. This is a particularly simple case; a more
- complex deployment may involve, for example, starting virtual machines through
- a Virtual Private Server (VPS) provider. In such a case, a different
- @var{environment} type would be used.
- Do note that you first need to generate a key pair on the coordinator machine
- to allow the daemon to export signed archives of files from the store
- (@pxref{Invoking guix archive}), though this step is automatic on Guix
- System:
- @example
- # guix archive --generate-key
- @end example
- @noindent
- Each target machine must authorize the key of the master machine so that it
- accepts store items it receives from the coordinator:
- @example
- # guix archive --authorize < coordinator-public-key.txt
- @end example
- @code{user}, in this example, specifies the name of the user account to log in
- as to perform the deployment. Its default value is @code{root}, but root
- login over SSH may be forbidden in some cases. To work around this,
- @command{guix deploy} can log in as an unprivileged user and employ
- @code{sudo} to escalate privileges. This will only work if @code{sudo} is
- currently installed on the remote and can be invoked non-interactively as
- @code{user}. That is, the line in @code{sudoers} granting @code{user} the
- ability to use @code{sudo} must contain the @code{NOPASSWD} tag. This can
- be accomplished with the following operating system configuration snippet:
- @lisp
- (use-modules ...
- (gnu system)) ;for %sudoers-specification
- (define %user "username")
- (operating-system
- ...
- (sudoers-file
- (plain-file "sudoers"
- (string-append (plain-file-content %sudoers-specification)
- (format #f "~a ALL = NOPASSWD: ALL~%"
- %user)))))
- @end lisp
- For more information regarding the format of the @file{sudoers} file,
- consult @command{man sudoers}.
- Once you've deployed a system on a set of machines, you may find it
- useful to run a command on all of them. The @option{--execute} or
- @option{-x} option lets you do that; the example below runs
- @command{uname -a} on all the machines listed in the deployment file:
- @example
- guix deploy @var{file} -x -- uname -a
- @end example
- One thing you may often need to do after deployment is restart specific
- services on all the machines, which you can do like so:
- @example
- guix deploy @var{file} -x -- herd restart @var{service}
- @end example
- The @command{guix deploy -x} command returns zero if and only if the
- command succeeded on all the machines.
- @c FIXME/TODO: Separate the API doc from the CLI doc.
- Below are the data types you need to know about when writing a
- deployment file.
- @deftp {Data Type} machine
- This is the data type representing a single machine in a heterogeneous Guix
- deployment.
- @table @asis
- @item @code{operating-system}
- The object of the operating system configuration to deploy.
- @item @code{environment}
- An @code{environment-type} describing how the machine should be provisioned.
- @item @code{configuration} (default: @code{#f})
- An object describing the configuration for the machine's @code{environment}.
- If the @code{environment} has a default configuration, @code{#f} may be used.
- If @code{#f} is used for an environment with no default configuration,
- however, an error will be thrown.
- @end table
- @end deftp
- @deftp {Data Type} machine-ssh-configuration
- This is the data type representing the SSH client parameters for a machine
- with an @code{environment} of @code{managed-host-environment-type}.
- @table @asis
- @item @code{host-name}
- @item @code{build-locally?} (default: @code{#t})
- If false, system derivations will be built on the machine being deployed to.
- @item @code{system}
- The system type describing the architecture of the machine being deployed
- to---e.g., @code{"x86_64-linux"}.
- @item @code{authorize?} (default: @code{#t})
- If true, the coordinator's signing key will be added to the remote's ACL
- keyring.
- @item @code{port} (default: @code{22})
- @item @code{user} (default: @code{"root"})
- @item @code{identity} (default: @code{#f})
- If specified, the path to the SSH private key to use to authenticate with the
- remote host.
- @item @code{host-key} (default: @code{#f})
- This should be the SSH host key of the machine, which looks like this:
- @example
- ssh-ed25519 AAAAC3Nz@dots{} root@@example.org
- @end example
- When @code{host-key} is @code{#f}, the server is authenticated against
- the @file{~/.ssh/known_hosts} file, just like the OpenSSH @command{ssh}
- client does.
- @item @code{allow-downgrades?} (default: @code{#f})
- Whether to allow potential downgrades.
- Like @command{guix system reconfigure}, @command{guix deploy} compares
- the channel commits currently deployed on the remote host (as returned
- by @command{guix system describe}) to those currently in use (as
- returned by @command{guix describe}) to determine whether commits
- currently in use are descendants of those deployed. When this is not
- the case and @code{allow-downgrades?} is false, it raises an error.
- This ensures you do not accidentally downgrade remote machines.
- @item @code{safety-checks?} (default: @code{#t})
- Whether to perform ``safety checks'' before deployment. This includes
- verifying that devices and file systems referred to in the operating
- system configuration actually exist on the target machine, and making
- sure that Linux modules required to access storage devices at boot time
- are listed in the @code{initrd-modules} field of the operating system.
- These safety checks ensure that you do not inadvertently deploy a system
- that would fail to boot. Be careful before turning them off!
- @end table
- @end deftp
- @deftp {Data Type} digital-ocean-configuration
- This is the data type describing the Droplet that should be created for a
- machine with an @code{environment} of @code{digital-ocean-environment-type}.
- @table @asis
- @item @code{ssh-key}
- The path to the SSH private key to use to authenticate with the remote
- host. In the future, this field may not exist.
- @item @code{tags}
- A list of string ``tags'' that uniquely identify the machine. Must be given
- such that no two machines in the deployment have the same set of tags.
- @item @code{region}
- A Digital Ocean region slug, such as @code{"nyc3"}.
- @item @code{size}
- A Digital Ocean size slug, such as @code{"s-1vcpu-1gb"}
- @item @code{enable-ipv6?}
- Whether or not the droplet should be created with IPv6 networking.
- @end table
- @end deftp
- @node Running Guix in a VM
- @section Running Guix in a Virtual Machine
- @cindex virtual machine
- To run Guix in a virtual machine (VM), one can use the pre-built Guix VM
- image distributed at
- @url{@value{BASE-URL}/guix-system-vm-image-@value{VERSION}.x86_64-linux.qcow2}.
- This image is a compressed image in QCOW format. You can pass it to an
- emulator such as @uref{https://qemu.org/, QEMU} (see below for details).
- This image boots the Xfce graphical environment and it contains some
- commonly used tools. You can install more software in the image by running
- @command{guix package} in a terminal (@pxref{Invoking guix package}). You can
- also reconfigure the system based on its initial configuration file available
- as @file{/run/current-system/configuration.scm} (@pxref{Using the
- Configuration System}).
- Instead of using this pre-built image, one can also build their own
- image using @command{guix system image} (@pxref{Invoking guix system}).
- @cindex QEMU
- If you built your own image, you must copy it out of the store
- (@pxref{The Store}) and give yourself permission to write to the copy
- before you can use it. When invoking QEMU, you must choose a system
- emulator that is suitable for your hardware platform. Here is a minimal
- QEMU invocation that will boot the result of @command{guix system
- image -t qcow2} on x86_64 hardware:
- @example
- $ qemu-system-x86_64 \
- -nic user,model=virtio-net-pci \
- -enable-kvm -m 2048 \
- -device virtio-blk,drive=myhd \
- -drive if=none,file=guix-system-vm-image-@value{VERSION}.x86_64-linux.qcow2,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 2048
- 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{guix-system-vm-image-@value{VERSION}.x86_64-linux.qcow2} file, as
- the backing store of the ``myhd'' drive.
- @end table
- The default @command{run-vm.sh} script that is returned by an invocation of
- @command{guix system vm} does not add a @command{-nic user} flag by default.
- To get network access from within the vm add the @code{(dhcp-client-service)}
- to your system definition and start the VM using
- @command{$(guix system vm config.scm) -nic user}. An important caveat of using
- @command{-nic user} for networking is that @command{ping} will not work, because
- it uses the ICMP protocol. You'll have to use a different command to check for
- network connectivity, for example @command{guix download}.
- @subsection Connecting Through SSH
- @cindex SSH
- @cindex SSH server
- To enable SSH inside a VM you need to add an SSH server like
- @code{openssh-service-type} to your VM (@pxref{Networking Services,
- @code{openssh-service-type}}). In addition you need to forward the SSH port,
- 22 by default, to the host. You can do this with
- @example
- $(guix system vm config.scm) -nic user,model=virtio-net-pci,hostfwd=tcp::10022-:22
- @end example
- To connect to the VM you can run
- @example
- ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -p 10022 localhost
- @end example
- The @command{-p} tells @command{ssh} the port you want to connect to.
- @command{-o UserKnownHostsFile=/dev/null} prevents @command{ssh} from complaining
- every time you modify your @command{config.scm} file and the
- @command{-o StrictHostKeyChecking=no} prevents you from having to allow a
- connection to an unknown host every time you connect.
- @quotation Note
- If you find the above @samp{hostfwd} example not to be working (e.g.,
- your SSH client hangs attempting to connect to the mapped port of your
- VM), make sure that your Guix System VM has networking support, such as
- by using the @code{dhcp-client-service-type} service type.
- @end quotation
- @subsection Using @command{virt-viewer} with Spice
- As an alternative to the default @command{qemu} graphical client you can
- use the @command{remote-viewer} from the @command{virt-viewer} package. To
- connect pass the @command{-spice port=5930,disable-ticketing} flag to
- @command{qemu}. See previous section for further information on how to do this.
- Spice also allows you to do some nice stuff like share your clipboard with your
- VM@. To enable that you'll also have to pass the following flags to @command{qemu}:
- @example
- -device virtio-serial-pci,id=virtio-serial0,max_ports=16,bus=pci.0,addr=0x5
- -chardev spicevmc,name=vdagent,id=vdagent
- -device virtserialport,nr=1,bus=virtio-serial0.0,chardev=vdagent,\
- name=com.redhat.spice.0
- @end example
- You'll also need to add the @code{(spice-vdagent-service)} to your
- system definition (@pxref{Miscellaneous Services, Spice service}).
- @node Defining Services
- @section Defining Services
- The previous sections show the available services and how one can combine
- them in an @code{operating-system} declaration. But how do we define
- them in the first place? And what is a service anyway?
- @menu
- * Service Composition:: The model for composing services.
- * Service Types and Services:: Types and services.
- * Service Reference:: API reference.
- * Shepherd Services:: A particular type of service.
- * Complex Configurations:: Defining bindings for complex configurations.
- @end menu
- @node Service Composition
- @subsection Service Composition
- @cindex services
- @cindex daemons
- Here we define a @dfn{service} as, broadly, something that extends the
- functionality of the operating system. Often a service is a process---a
- @dfn{daemon}---started when the system boots: a secure shell server, a
- Web server, the Guix build daemon, etc. Sometimes a service is a daemon
- whose execution can be triggered by another daemon---e.g., an FTP server
- started by @command{inetd} or a D-Bus service activated by
- @command{dbus-daemon}. Occasionally, a service does not map to a
- daemon. For instance, the ``account'' service collects user accounts
- and makes sure they exist when the system runs; the ``udev'' service
- collects device management rules and makes them available to the eudev
- daemon; the @file{/etc} service populates the @file{/etc} directory
- of the system.
- @cindex service extensions
- Guix system services are connected by @dfn{extensions}. For instance, the
- secure shell service @emph{extends} the Shepherd---the
- initialization system, running as PID@tie{}1---by giving it the command
- lines to start and stop the secure shell daemon (@pxref{Networking
- Services, @code{openssh-service-type}}); the UPower service extends the D-Bus
- service by passing it its @file{.service} specification, and extends the
- udev service by passing it device management rules (@pxref{Desktop
- Services, @code{upower-service}}); the Guix daemon service extends the
- Shepherd by passing it the command lines to start and stop the daemon,
- and extends the account service by passing it a list of required build
- user accounts (@pxref{Base Services}).
- All in all, services and their ``extends'' relations form a directed
- acyclic graph (DAG). If we represent services as boxes and extensions
- as arrows, a typical system might provide something like this:
- @image{images/service-graph,,5in,Typical service extension graph.}
- @cindex system service
- At the bottom, we see the @dfn{system service}, which produces the
- directory containing everything to run and boot the system, as returned
- by the @command{guix system build} command. @xref{Service Reference},
- to learn about the other service types shown here.
- @xref{system-extension-graph, the @command{guix system extension-graph}
- command}, for information on how to generate this representation for a
- particular operating system definition.
- @cindex service types
- Technically, developers can define @dfn{service types} to express these
- relations. There can be any number of services of a given type on the
- system---for instance, a system running two instances of the GNU secure
- shell server (lsh) has two instances of @code{lsh-service-type}, with
- different parameters.
- The following section describes the programming interface for service
- types and services.
- @node Service Types and Services
- @subsection Service Types and Services
- A @dfn{service type} is a node in the DAG described above. Let us start
- with a simple example, the service type for the Guix build daemon
- (@pxref{Invoking guix-daemon}):
- @lisp
- (define guix-service-type
- (service-type
- (name 'guix)
- (extensions
- (list (service-extension shepherd-root-service-type guix-shepherd-service)
- (service-extension account-service-type guix-accounts)
- (service-extension activation-service-type guix-activation)))
- (default-value (guix-configuration))))
- @end lisp
- @noindent
- It defines three things:
- @enumerate
- @item
- A name, whose sole purpose is to make inspection and debugging easier.
- @item
- A list of @dfn{service extensions}, where each extension designates the
- target service type and a procedure that, given the parameters of the
- service, returns a list of objects to extend the service of that type.
- Every service type has at least one service extension. The only
- exception is the @dfn{boot service type}, which is the ultimate service.
- @item
- Optionally, a default value for instances of this type.
- @end enumerate
- In this example, @code{guix-service-type} extends three services:
- @table @code
- @item shepherd-root-service-type
- The @code{guix-shepherd-service} procedure defines how the Shepherd
- service is extended. Namely, it returns a @code{<shepherd-service>}
- object that defines how @command{guix-daemon} is started and stopped
- (@pxref{Shepherd Services}).
- @item account-service-type
- This extension for this service is computed by @code{guix-accounts},
- which returns a list of @code{user-group} and @code{user-account}
- objects representing the build user accounts (@pxref{Invoking
- guix-daemon}).
- @item activation-service-type
- Here @code{guix-activation} is a procedure that returns a gexp, which is
- a code snippet to run at ``activation time''---e.g., when the service is
- booted.
- @end table
- A service of this type is instantiated like this:
- @lisp
- (service guix-service-type
- (guix-configuration
- (build-accounts 5)
- (extra-options '("--gc-keep-derivations"))))
- @end lisp
- The second argument to the @code{service} form is a value representing
- the parameters of this specific service instance.
- @xref{guix-configuration-type, @code{guix-configuration}}, for
- information about the @code{guix-configuration} data type. When the
- value is omitted, the default value specified by
- @code{guix-service-type} is used:
- @lisp
- (service guix-service-type)
- @end lisp
- @code{guix-service-type} is quite simple because it extends other
- services but is not extensible itself.
- @c @subsubsubsection Extensible Service Types
- The service type for an @emph{extensible} service looks like this:
- @lisp
- (define udev-service-type
- (service-type (name 'udev)
- (extensions
- (list (service-extension shepherd-root-service-type
- udev-shepherd-service)))
- (compose concatenate) ;concatenate the list of rules
- (extend (lambda (config rules)
- (udev-configuration
- (inherit config)
- (rules (append (udev-configuration-rules config)
- rules)))))))
- @end lisp
- This is the service type for the
- @uref{https://github.com/eudev-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 {Procedure} service type [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 {Procedure} service? obj
- Return true if @var{obj} is a service.
- @end deffn
- @deffn {Procedure} service-kind service
- Return the type of @var{service}---i.e., a @code{<service-type>} object.
- @end deffn
- @deffn {Procedure} service-value 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.
- @defspec modify-services services @
- (type variable => body) @dots{}
- Modify the services listed in @var{services} according to the given
- clauses. Each clause has the form:
- @example
- (@var{type} @var{variable} => @var{body})
- @end example
- where @var{type} is a service type---e.g.,
- @code{guix-service-type}---and @var{variable} is an identifier that is
- bound within the @var{body} to the service parameters---e.g., a
- @code{guix-configuration} instance---of the original service of that
- @var{type}.
- The @var{body} should evaluate to the new service parameters, which will
- be used to configure the new service. This new service will replace the
- original in the resulting list. Because a service's service parameters
- are created using @code{define-record-type*}, you can write a succinct
- @var{body} that evaluates to the new service parameters by using the
- @code{inherit} feature that @code{define-record-type*} provides.
- Clauses can also have the following form:
- @lisp
- (delete @var{type})
- @end lisp
- Such a clause removes all services of the given @var{type} from
- @var{services}.
- @xref{Using the Configuration System}, for example usage.
- @end defspec
- 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 {Procedure} service-extension target-type 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 {Procedure} service-extension? 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 {Procedure} simple-service name target 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 {Procedure} fold-services services [#:target-type 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.
- @defvar 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 defvar
- @defvar 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 defvar
- @defvar 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 defvar
- @defvar 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 and setgid programs on the system (@pxref{Setuid Programs}).
- @end defvar
- @defvar 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 defvar
- @cindex provenance tracking, of the operating system
- @anchor{provenance-service-type}
- @defvar 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 defvar
- @defvar 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 defvar
- @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{Defining Services,,,
- 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{Defining Services,,, shepherd, The GNU Shepherd Manual}, for more
- info on actions.
- @end deftp
- @cindex configuration file, of Shepherd services
- @deffn {Procedure} shepherd-configuration-action
- Return a @code{configuration} action to display @var{file}, which should
- be the name of the service's configuration file.
- It can be useful to equip services with that action. For example, the
- service for the Tor anonymous router (@pxref{Networking Services,
- @code{tor-service-type}}) is defined roughly like this:
- @lisp
- (let ((torrc (plain-file "torrc" @dots{})))
- (shepherd-service
- (provision '(tor))
- (requirement '(user-processes loopback syslogd))
- (start #~(make-forkexec-constructor
- (list #$(file-append tor "/bin/tor") "-f" #$torrc)
- #:user "tor" #:group "tor"))
- (stop #~(make-kill-destructor))
- (actions (list (shepherd-configuration-action torrc)))
- (documentation "Run the Tor anonymous network overlay.")))
- @end lisp
- Thanks to this action, administrators can inspect the configuration file
- passed to @command{tor} with this shell command:
- @example
- cat $(herd configuration tor)
- @end example
- This can come in as a handy debugging tool!
- @end deffn
- @defvar 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 defvar
- @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
- @defvar %shepherd-root-service
- This service represents PID@tie{}1.
- @end defvar
- @node Complex Configurations
- @subsection Complex Configurations
- @cindex complex configurations
- Some programs might have rather complex configuration files or formats,
- and to make it easier to create Scheme bindings for these configuration
- files, you can use the utilities defined in the @code{(gnu services
- configuration)} module.
- The main utility is the @code{define-configuration} macro, which you
- will use to define a Scheme record type (@pxref{Record Overview,,,
- guile, GNU Guile Reference Manual}). The Scheme record will be
- serialized to a configuration file by using @dfn{serializers}, which are
- procedures that take some kind of Scheme value and returns a
- G-expression (@pxref{G-Expressions}), which should, once serialized to
- the disk, return a string. More details are listed below.
- @defmac define-configuration name clause1 clause2 @dots{}
- Create a record type named @code{@var{name}} that contains the
- fields found in the clauses.
- A clause can have one of the following forms:
- @example
- (@var{field-name}
- (@var{type} @var{default-value})
- @var{documentation})
- (@var{field-name}
- (@var{type} @var{default-value})
- @var{documentation}
- (serializer @var{serializer}))
- (@var{field-name}
- (@var{type})
- @var{documentation})
- (@var{field-name}
- (@var{type})
- @var{documentation}
- (serializer @var{serializer}))
- (@var{field-name}
- (@var{type})
- @var{documentation}
- (sanitizer @var{sanitizer})
- (@var{field-name}
- (@var{type})
- @var{documentation}
- (sanitizer @var{sanitizer})
- (serializer @var{serializer}))
- @end example
- @var{field-name} is an identifier that denotes the name of the field in
- the generated record.
- @var{type} is the type of the value corresponding to @var{field-name};
- since Guile is untyped, a predicate
- procedure---@code{@var{type}?}---will be called on the value
- corresponding to the field to ensure that the value is of the correct
- type. This means that if say, @var{type} is @code{package}, then a
- procedure named @code{package?} will be applied on the value to make
- sure that it is indeed a @code{<package>} object.
- @var{default-value} is the default value corresponding to the field; if
- none is specified, the user is forced to provide a value when creating
- an object of the record type.
- @c XXX: Should these be full sentences or are they allow to be very
- @c short like package synopses?
- @var{documentation} is a string formatted with Texinfo syntax which
- should provide a description of what setting this field does.
- @var{sanitizer} is a procedure which takes one argument,
- a user-supplied value, and returns a ``sanitized'' value for the field.
- If no sanitizer is specified, a default sanitizer is used, which raises
- an error if the value is not of type @var{type}.
- An example of a sanitizer for a field that accepts both strings and
- symbols looks like this:
- @lisp
- (define (sanitize-foo value)
- (cond ((string? value) value)
- ((symbol? value) (symbol->string value))
- (else (error "bad value"))))
- @end lisp
- @var{serializer} is the name of a procedure which takes two arguments,
- the first is the name of the field, and the second is the value
- corresponding to the field. The procedure should return a string or
- G-expression (@pxref{G-Expressions}) that represents the content that
- will be serialized to the configuration file. If none is specified, a
- procedure of the name @code{serialize-@var{type}} will be used.
- A simple serializer procedure could look like this:
- @lisp
- (define (serialize-boolean field-name value)
- (let ((value (if value "true" "false")))
- #~(string-append #$field-name #$value)))
- @end lisp
- In some cases multiple different configuration records might be defined
- in the same file, but their serializers for the same type might have to
- be different, because they have different configuration formats. For
- example, the @code{serialize-boolean} procedure for the Getmail service
- would have to be different from the one for the Transmission service. To
- make it easier to deal with this situation, one can specify a serializer
- prefix by using the @code{prefix} literal in the
- @code{define-configuration} form. This means that one doesn't have to
- manually specify a custom @var{serializer} for every field.
- @lisp
- (define (foo-serialize-string field-name value)
- @dots{})
- (define (bar-serialize-string field-name value)
- @dots{})
- (define-configuration foo-configuration
- (label
- (string)
- "The name of label.")
- (prefix foo-))
- (define-configuration bar-configuration
- (ip-address
- (string)
- "The IPv4 address for this device.")
- (prefix bar-))
- @end lisp
- However, in some cases you might not want to serialize any of the values
- of the record, to do this, you can use the @code{no-serialization}
- literal. There is also the @code{define-configuration/no-serialization}
- macro which is a shorthand of this.
- @lisp
- ;; Nothing will be serialized to disk.
- (define-configuration foo-configuration
- (field
- (string "test")
- "Some documentation.")
- (no-serialization))
- ;; The same thing as above.
- (define-configuration/no-serialization bar-configuration
- (field
- (string "test")
- "Some documentation."))
- @end lisp
- @end defmac
- @defmac define-maybe type
- Sometimes a field should not be serialized if the user doesn’t specify a
- value. To achieve this, you can use the @code{define-maybe} macro to
- define a ``maybe type''; if the value of a maybe type is left unset, or
- is set to the @code{%unset-value} value, then it will not be serialized.
- When defining a ``maybe type'', the corresponding serializer for the
- regular type will be used by default. For example, a field of type
- @code{maybe-string} will be serialized using the @code{serialize-string}
- procedure by default, you can of course change this by specifying a
- custom serializer procedure. Likewise, the type of the value would have
- to be a string, or left unspecified.
- @lisp
- (define-maybe string)
- (define (serialize-string field-name value)
- @dots{})
- (define-configuration baz-configuration
- (name
- ;; If set to a string, the `serialize-string' procedure will be used
- ;; to serialize the string. Otherwise this field is not serialized.
- maybe-string
- "The name of this module."))
- @end lisp
- Like with @code{define-configuration}, one can set a prefix for the
- serializer name by using the @code{prefix} literal.
- @lisp
- (define-maybe integer
- (prefix baz-))
- (define (baz-serialize-integer field-name value)
- @dots{})
- @end lisp
- There is also the @code{no-serialization} literal, which when set means
- that no serializer will be defined for the ``maybe type'', regardless of
- whether its value is set or not.
- @code{define-maybe/no-serialization} is a shorthand for specifying the
- @code{no-serialization} literal.
- @lisp
- (define-maybe/no-serialization symbol)
- (define-configuration/no-serialization test-configuration
- (mode
- maybe-symbol
- "Docstring."))
- @end lisp
- @end defmac
- @deffn {Procedure} maybe-value-set? value
- Predicate to check whether a user explicitly specified the value of a
- maybe field.
- @end deffn
- @deffn {Procedure} serialize-configuration configuration fields
- Return a G-expression that contains the values corresponding to the
- @var{fields} of @var{configuration}, a record that has been generated by
- @code{define-configuration}. The G-expression can then be serialized to
- disk by using something like @code{mixed-text-file}.
- @end deffn
- @deffn {Procedure} empty-serializer field-name value
- A serializer that just returns an empty string. The
- @code{serialize-package} procedure is an alias for this.
- @end deffn
- Once you have defined a configuration record, you will most likely also
- want to document it so that other people know to use it. To help with
- that, there are two procedures, both of which are documented below.
- @deffn {Procedure} generate-documentation documentation documentation-name
- Generate a Texinfo fragment from the docstrings in @var{documentation},
- a list of @code{(@var{label} @var{fields} @var{sub-documentation} ...)}.
- @var{label} should be a symbol and should be the name of the
- configuration record. @var{fields} should be a list of all the fields
- available for the configuration record.
- @var{sub-documentation} is a @code{(@var{field-name}
- @var{configuration-name})} tuple. @var{field-name} is the name of the
- field which takes another configuration record as its value, and
- @var{configuration-name} is the name of that configuration record.
- @var{sub-documentation} is only needed if there are nested configuration
- records. For example, the @code{getmail-configuration} record
- (@pxref{Mail Services}) accepts a @code{getmail-configuration-file}
- record in one of its @code{rcfile} field, therefore documentation for
- @code{getmail-configuration-file} is nested in
- @code{getmail-configuration}.
- @lisp
- (generate-documentation
- `((getmail-configuration ,getmail-configuration-fields
- (rcfile getmail-configuration-file))
- @dots{})
- 'getmail-configuration)
- @end lisp
- @var{documentation-name} should be a symbol and should be the name of
- the configuration record.
- @end deffn
- @deffn {Procedure} configuration->documentation configuration-symbol
- Take @var{configuration-symbol}, the symbol corresponding to the name
- used when defining a configuration record with
- @code{define-configuration}, and print the Texinfo documentation of its
- fields. This is useful if there aren’t any nested configuration records
- since it only prints the documentation for the top-level fields.
- @end deffn
- As of right now, there is no automated way to generate documentation for
- configuration records and put them in the manual. Instead, every
- time you make a change to the docstrings of a configuration record, you
- have to manually call @code{generate-documentation} or
- @code{configuration->documentation}, and paste the output into the
- @file{doc/guix.texi} file.
- @c TODO: Actually test this
- Below is an example of a record type created using
- @code{define-configuration} and friends.
- @lisp
- (use-modules (gnu services)
- (guix gexp)
- (gnu services configuration)
- (srfi srfi-26)
- (srfi srfi-1))
- ;; Turn field names, which are Scheme symbols into strings
- (define (uglify-field-name field-name)
- (let ((str (symbol->string field-name)))
- ;; field? -> is-field
- (if (string-suffix? "?" str)
- (string-append "is-" (string-drop-right str 1))
- str)))
- (define (serialize-string field-name value)
- #~(string-append #$(uglify-field-name field-name) " = " #$value "\n"))
- (define (serialize-integer field-name value)
- (serialize-string field-name (number->string value)))
- (define (serialize-boolean field-name value)
- (serialize-string field-name (if value "true" "false")))
- (define (serialize-contact-name field-name value)
- #~(string-append "\n[" #$value "]\n"))
- (define (list-of-contact-configurations? lst)
- (every contact-configuration? lst))
- (define (serialize-list-of-contact-configurations field-name value)
- #~(string-append #$@@(map (cut serialize-configuration <>
- contact-configuration-fields)
- value)))
- (define (serialize-contacts-list-configuration configuration)
- (mixed-text-file
- "contactrc"
- #~(string-append "[Owner]\n"
- #$(serialize-configuration
- configuration contacts-list-configuration-fields))))
- (define-maybe integer)
- (define-maybe string)
- (define-configuration contact-configuration
- (name
- (string)
- "The name of the contact."
- serialize-contact-name)
- (phone-number
- maybe-integer
- "The person's phone number.")
- (email
- maybe-string
- "The person's email address.")
- (married?
- (boolean)
- "Whether the person is married."))
- (define-configuration contacts-list-configuration
- (name
- (string)
- "The name of the owner of this contact list.")
- (email
- (string)
- "The owner's email address.")
- (contacts
- (list-of-contact-configurations '())
- "A list of @@code@{contact-configuation@} records which contain
- information about all your contacts."))
- @end lisp
- A contacts list configuration could then be created like this:
- @lisp
- (define my-contacts
- (contacts-list-configuration
- (name "Alice")
- (email "alice@@example.org")
- (contacts
- (list (contact-configuration
- (name "Bob")
- (phone-number 1234)
- (email "bob@@gnu.org")
- (married? #f))
- (contact-configuration
- (name "Charlie")
- (phone-number 0000)
- (married? #t))))))
- @end lisp
- After serializing the configuration to disk, the resulting file would
- look like this:
- @example
- [owner]
- name = Alice
- email = alice@@example.org
- [Bob]
- phone-number = 1234
- email = bob@@gnu.org
- is-married = false
- [Charlie]
- phone-number = 0
- is-married = true
- @end example
- @node Home Configuration
- @chapter Home Configuration
- @cindex home configuration
- Guix supports declarative configuration of @dfn{home environments} by
- utilizing the configuration mechanism described in the previous chapter
- (@pxref{Defining Services}), but for user's dotfiles and packages. It
- works both on Guix System and foreign distros and allows users to
- declare all the packages and services that should be installed and
- configured for the user. Once a user has written a file containing
- @code{home-environment} record, such a configuration can be
- @dfn{instantiated} by an unprivileged user with the @command{guix home}
- command (@pxref{Invoking guix home}).
- @c Maybe later, it will be possible to make home configuration a part of
- @c system configuration to make everything managed by guix system.
- @quotation Note
- The functionality described in this section is still under development
- and is subject to change. Get in touch with us on
- @email{guix-devel@@gnu.org}!
- @end quotation
- The user's home environment usually consists of three basic parts:
- software, configuration, and state. Software in mainstream distros are
- usually installed system-wide, but with GNU Guix most software packages
- can be installed on a per-user basis without needing root privileges,
- and are thus considered part of the user’s @dfn{home environment}.
- Packages on their own are not very useful in many cases, because often they
- require some additional configuration, usually config files that reside
- in @env{XDG_CONFIG_HOME} (@file{~/.config} by default) or other
- directories. Everything else can be considered state, like media files,
- application databases, and logs.
- Using Guix for managing home environments provides a number of
- advantages:
- @itemize
- @item All software can be configured in one language (Guile Scheme),
- this gives users the ability to share values between configurations of
- different programs.
- @item A well-defined home environment is self-contained and can be
- created in a declarative and reproducible way---there is no need to grab
- external binaries or manually edit some configuration file.
- @item After every @command{guix home reconfigure} invocation, a new home
- environment generation will be created. This means that users can
- rollback to a previous home environment generation so they don’t have to
- worry about breaking their configuration.
- @item It is possible to manage stateful data with Guix Home, this
- includes the ability to automatically clone Git repositories on the
- initial setup of the machine, and periodically running commands like
- @command{rsync} to sync data with another host. This functionality is
- still in an experimental stage, though.
- @end itemize
- @menu
- * Declaring the Home Environment:: Customizing your Home.
- * Configuring the Shell:: Enabling home environment.
- * Home Services:: Specifying home services.
- * Invoking guix home:: Instantiating a home configuration.
- @end menu
- @node Declaring the Home Environment
- @section Declaring the Home Environment
- The home environment is configured by providing a
- @code{home-environment} declaration in a file that can be passed to the
- @command{guix home} command (@pxref{Invoking guix home}). The easiest
- way to get started is by generating an initial configuration with
- @command{guix home import}:
- @example
- guix home import ~/src/guix-config
- @end example
- The @command{guix home import} command reads some of the ``dot files''
- such as @file{~/.bashrc} found in your home directory and copies them to
- the given directory, @file{~/src/guix-config} in this case; it also
- reads the contents of your profile, @file{~/.guix-profile}, and, based
- on that, it populates @file{~/src/guix-config/home-configuration.scm}
- with a Home configuration that resembles your current configuration.
- A simple setup can include Bash and a custom text configuration, like in
- the example below. Don't be afraid to declare home environment parts,
- which overlaps with your current dot files: before installing any
- configuration files, Guix Home will back up existing config files to a
- separate place in the home directory.
- @quotation Note
- It is highly recommended that you manage your shell or shells with Guix
- Home, because it will make sure that all the necessary scripts are
- sourced by the shell configuration file. Otherwise you will need to do
- it manually. (@pxref{Configuring the Shell}).
- @end quotation
- @findex home-environment
- @lisp
- @include he-config-bare-bones.scm
- @end lisp
- The @code{packages} field should be self-explanatory, it will install
- the list of packages into the user's profile. The most important field
- is @code{services}, it contains a list of @dfn{home services}, which are
- the basic building blocks of a home environment.
- There is no daemon (at least not necessarily) related to a home service,
- a home service is just an element that is used to declare part of home
- environment and extend other parts of it. The extension mechanism
- discussed in the previous chapter (@pxref{Defining Services}) should not
- be confused with Shepherd services (@pxref{Shepherd Services}). Using this extension
- mechanism and some Scheme code that glues things together gives the user
- the freedom to declare their own, very custom, home environments.
- @cindex container, for @command{guix home}
- Once the configuration looks good, you can first test it in a throw-away
- ``container'':
- @example
- guix home container config.scm
- @end example
- The command above spawns a shell where your home environment is running.
- The shell runs in a container, meaning it's isolated from the rest of
- the system, so it's a good way to try out your configuration---you can
- see if configuration bits are missing or misbehaving, if daemons get
- started, and so on. Once you exit that shell, you're back to the prompt
- of your original shell ``in the real world''.
- Once you have a configuration file that suits your needs, you can
- reconfigure your home by running:
- @example
- guix home reconfigure config.scm
- @end example
- This ``builds'' your home environment and creates @file{~/.guix-home}
- pointing to it. Voilà!
- @quotation Note
- Make sure the operating system has elogind, systemd, or a similar
- mechanism to create the XDG run-time directory and has the
- @env{XDG_RUNTIME_DIR} variable set. Failing that, the
- @file{on-first-login} script will not execute anything, and processes
- like user Shepherd and its descendants will not start.
- @end quotation
- @node Configuring the Shell
- @section Configuring the Shell
- This section is safe to skip if your shell or shells are managed by
- Guix Home. Otherwise, read it carefully.
- There are a few scripts that must be evaluated by a login shell to
- activate the home environment. The shell startup files only read by
- login shells often have @code{profile} suffix. For more information
- about login shells see @ref{Invoking Bash,,, bash, The GNU Bash
- Reference Manual} and see @ref{Bash Startup Files,,, bash, The GNU Bash
- Reference Manual}.
- The first script that needs to be sourced is @file{setup-environment},
- which sets all the necessary environment variables (including variables
- declared by the user) and the second one is @file{on-first-login}, which
- starts Shepherd for the current user and performs actions declared by
- other home services that extends
- @code{home-run-on-first-login-service-type}.
- Guix Home will always create @file{~/.profile}, which contains the
- following lines:
- @example
- HOME_ENVIRONMENT=$HOME/.guix-home
- . $HOME_ENVIRONMENT/setup-environment
- $HOME_ENVIRONMENT/on-first-login
- @end example
- This makes POSIX compliant login shells activate the home environment.
- However, in most cases this file won't be read by most modern shells,
- because they are run in non POSIX mode by default and have their own
- @file{*profile} startup files. For example Bash will prefer
- @file{~/.bash_profile} in case it exists and only if it doesn't will it
- fallback to @file{~/.profile}. Zsh (if no additional options are
- specified) will ignore @file{~/.profile}, even if @file{~/.zprofile}
- doesn't exist.
- To make your shell respect @file{~/.profile}, add @code{. ~/.profile} or
- @code{source ~/.profile} to the startup file for the login shell. In
- case of Bash, it is @file{~/.bash_profile}, and in case of Zsh, it is
- @file{~/.zprofile}.
- @quotation Note
- This step is only required if your shell is @emph{not} managed by Guix Home.
- Otherwise, everything will be done automatically.
- @end quotation
- @node Home Services
- @section Home Services
- @cindex home services
- A @dfn{home service} is not necessarily something that has a daemon and
- is managed by Shepherd (@pxref{Jump Start,,, shepherd, The GNU Shepherd
- Manual}), in most cases it doesn't. It's a simple building block of the
- home environment, often declaring a set of packages to be installed in
- the home environment profile, a set of config files to be symlinked into
- @env{XDG_CONFIG_HOME} (@file{~/.config} by default), and environment
- variables to be set by a login shell.
- There is a service extension mechanism (@pxref{Service Composition})
- which allows home services to extend other home services and utilize
- capabilities they provide; for example: declare mcron jobs
- (@pxref{Top,,, mcron, GNU@tie{}Mcron}) by extending @ref{Mcron Home
- Service}; declare daemons by extending @ref{Shepherd Home Service}; add
- commands, which will be invoked on by the Bash by extending
- @ref{Shells Home Services, @code{home-bash-service-type}}.
- A good way to discover available home services is using the
- @command{guix home search} command (@pxref{Invoking guix home}). After
- the required home services are found, include its module with the
- @code{use-modules} form (@pxref{use-modules,, Using Guile Modules,
- guile, The GNU Guile Reference Manual}), or the @code{#:use-modules}
- directive (@pxref{define-module,, Creating Guile Modules, guile, The GNU
- Guile Reference Manual}) and declare a home service using the
- @code{service} function, or extend a service type by declaring a new
- service with the @code{simple-service} procedure from @code{(gnu
- services)}.
- @menu
- * Essential Home Services:: Environment variables, packages, on-* scripts.
- * Shells: Shells Home Services. POSIX shells, Bash, Zsh.
- * Mcron: Mcron Home Service. Scheduled User's Job Execution.
- * Power Management: Power Management Home Services. Services for battery power.
- * Shepherd: Shepherd Home Service. Managing User's Daemons.
- * SSH: Secure Shell. Setting up the secure shell client.
- * GPG: GNU Privacy Guard. Setting up GPG and related tools.
- * Desktop: Desktop Home Services. Services for graphical environments.
- * Guix: Guix Home Services. Services for Guix.
- * Fonts: Fonts Home Services. Services for managing User's fonts.
- * Sound: Sound Home Services. Dealing with audio.
- * Mail: Mail Home Services. Services for managing mail.
- * Messaging: Messaging Home Services. Services for managing messaging.
- * Media: Media Home Services. Services for managing media.
- * Networking: Networking Home Services. Networking services.
- * Miscellaneous: Miscellaneous Home Services. More services.
- @end menu
- @c In addition to that Home Services can provide
- @node Essential Home Services
- @subsection Essential Home Services
- There are a few essential home services defined in
- @code{(gnu home services)}, they are mostly for internal use and are
- required to build a home environment, but some of them will be useful
- for the end user.
- @cindex environment variables
- @defvar home-environment-variables-service-type
- The service of this type will be instantiated by every home environment
- automatically by default, there is no need to define it, but someone may
- want to extend it with a list of pairs to set some environment
- variables.
- @lisp
- (list ("ENV_VAR1" . "value1")
- ("ENV_VAR2" . "value2"))
- @end lisp
- The easiest way to extend a service type, without defining a new service
- type is to use the @code{simple-service} helper from @code{(gnu
- services)}.
- @findex literal-string
- @lisp
- (simple-service 'some-useful-env-vars-service
- home-environment-variables-service-type
- `(("LESSHISTFILE" . "$XDG_CACHE_HOME/.lesshst")
- ("SHELL" . ,(file-append zsh "/bin/zsh"))
- ("USELESS_VAR" . #f)
- ("_JAVA_AWT_WM_NONREPARENTING" . #t)
- ("LITERAL_VALUE" . ,(literal-string "$@{abc@}"))))
- @end lisp
- If you include such a service in you home environment definition, it
- will add the following content to the @file{setup-environment} script
- (which is expected to be sourced by the login shell):
- @example
- export LESSHISTFILE="$XDG_CACHE_HOME/.lesshst"
- export SHELL="/gnu/store/2hsg15n644f0glrcbkb1kqknmmqdar03-zsh-5.8/bin/zsh"
- export _JAVA_AWT_WM_NONREPARENTING
- export LITERAL_VALUE='$@{abc@}'
- @end example
- Notice that @code{literal-string} above lets us declare that a value is
- to be interpreted as a @dfn{literal string}, meaning that ``special
- characters'' such as the dollar sign will not be interpreted by the
- shell.
- @quotation Note
- Make sure that module @code{(gnu packages shells)} is imported with
- @code{use-modules} or any other way, this namespace contains the
- definition of the @code{zsh} package, which is used in the example
- above.
- @end quotation
- The association list (@pxref{Association Lists, alists, Association
- Lists, guile, The GNU Guile Reference manual}) is a data structure
- containing key-value pairs, for
- @code{home-environment-variables-service-type} the key is always a
- string, the value can be a string, string-valued gexp
- (@pxref{G-Expressions}), file-like object (@pxref{G-Expressions,
- file-like object}) or boolean. For gexps, the variable will be set to
- the value of the gexp; for file-like objects, it will be set to the path
- of the file in the store (@pxref{The Store}); for @code{#t}, it will
- export the variable without any value; and for @code{#f}, it will omit
- variable.
- @end defvar
- @defvar home-profile-service-type
- The service of this type will be instantiated by every home environment
- automatically, there is no need to define it, but you may want to extend
- it with a list of packages if you want to install additional packages
- into your profile. Other services, which need to make some programs
- available to the user will also extend this service type.
- The extension value is just a list of packages:
- @lisp
- (list htop vim emacs)
- @end lisp
- The same approach as @code{simple-service} (@pxref{Service Reference,
- simple-service}) for @code{home-environment-variables-service-type} can
- be used here, too. Make sure that modules containing the specified
- packages are imported with @code{use-modules}. To find a package or
- information about its module use @command{guix search} (@pxref{Invoking
- guix package}). Alternatively, @code{specification->package} can be
- used to get the package record from string without importing related
- module.
- @end defvar
- There are few more essential services, but users are not expected to
- extend them.
- @defvar home-service-type
- The root of home services DAG, it generates a folder, which later will be
- symlinked to @file{~/.guix-home}, it contains configurations,
- profile with binaries and libraries, and some necessary scripts to glue
- things together.
- @end defvar
- @defvar home-run-on-first-login-service-type
- The service of this type generates a Guile script, which is expected to
- be executed by the login shell. It is only executed if the special flag
- file inside @env{XDG_RUNTIME_DIR} hasn't been created, this prevents
- redundant executions of the script if multiple login shells are spawned.
- It can be extended with a gexp. However, to autostart an application,
- users @emph{should not} use this service, in most cases it's better to extend
- @code{home-shepherd-service-type} with a Shepherd service
- (@pxref{Shepherd Services}), or extend the shell's startup file with
- the required command using the appropriate service type.
- @end defvar
- @defvar home-files-service-type
- The service of this type allows to specify a list of files, which will
- go to @file{~/.guix-home/files}, usually this directory contains
- configuration files (to be more precise it contains symlinks to files in
- @file{/gnu/store}), which should be placed in @file{$XDG_CONFIG_DIR} or
- in rare cases in @file{$HOME}. It accepts extension values in the
- following format:
- @lisp
- `((".sway/config" ,sway-file-like-object)
- (".tmux.conf" ,(local-file "./tmux.conf")))
- @end lisp
- Each nested list contains two values: a subdirectory and file-like
- object. After building a home environment @file{~/.guix-home/files}
- will be populated with appropriate content and all nested directories will
- be created accordingly, however, those files won't go any further until
- some other service will do it. By default a
- @code{home-symlink-manager-service-type}, which creates necessary
- symlinks in home folder to files from @file{~/.guix-home/files} and
- backs up already existing, but clashing configs and other things, is a
- part of essential home services (enabled by default), but it's possible
- to use alternative services to implement more advanced use cases like
- read-only home. Feel free to experiment and share your results.
- @end defvar
- @defvar home-xdg-configuration-files-service-type
- The service is very similar to @code{home-files-service-type} (and
- actually extends it), but used for defining files, which will go to
- @file{~/.guix-home/files/.config}, which will be symlinked to
- @file{$XDG_CONFIG_DIR} by @code{home-symlink-manager-service-type} (for
- example) during activation. It accepts extension values in the
- following format:
- @lisp
- `(("sway/config" ,sway-file-like-object)
- ;; -> ~/.guix-home/files/.config/sway/config
- ;; -> $XDG_CONFIG_DIR/sway/config (by symlink-manager)
- ("tmux/tmux.conf" ,(local-file "./tmux.conf")))
- @end lisp
- @end defvar
- @defvar home-activation-service-type
- The service of this type generates a guile script, which runs on every
- @command{guix home reconfigure} invocation or any other action, which
- leads to the activation of the home environment.
- @end defvar
- @defvar home-symlink-manager-service-type
- The service of this type generates a guile script, which will be
- executed during activation of home environment, and do a few following
- steps:
- @enumerate
- @item
- Reads the content of @file{files/} directory of current and pending home
- environments.
- @item
- Cleans up all symlinks created by symlink-manager on previous
- activation. Also, sub-directories, which become empty also will be
- cleaned up.
- @item
- Creates new symlinks the following way: It looks @file{files/} directory
- (usually defined with @code{home-files-service-type},
- @code{home-xdg-configuration-files-service-type} and maybe some others),
- takes the files from @file{files/.config/} subdirectory and put
- respective links in @env{XDG_CONFIG_DIR}. For example symlink for
- @file{files/.config/sway/config} will end up in
- @file{$XDG_CONFIG_DIR/sway/config}. The rest files in @file{files/}
- outside of @file{files/.config/} subdirectory will be treated slightly
- different: symlink will just go to @file{$HOME}.
- @file{files/.some-program/config} will end up in
- @file{$HOME/.some-program/config}.
- @item
- If some sub-directories are missing, they will be created.
- @item
- If there is a clashing files on the way, they will be backed up.
- @end enumerate
- symlink-manager is a part of essential home services and is enabled and
- used by default.
- @end defvar
- @node Shells Home Services
- @subsection Shells
- @cindex shell
- @cindex login shell
- @cindex interactive shell
- @cindex bash
- @cindex zsh
- Shells play a quite important role in the environment initialization
- process, you can configure them manually as described in section
- @ref{Configuring the Shell}, but the recommended way is to use home services
- listed below. It's both easier and more reliable.
- Each home environment instantiates
- @code{home-shell-profile-service-type}, which creates a
- @file{~/.profile} startup file for all POSIX-compatible shells. This
- file contains all the necessary steps to properly initialize the
- environment, but many modern shells like Bash or Zsh prefer their own
- startup files, that's why the respective home services
- (@code{home-bash-service-type} and @code{home-zsh-service-type}) ensure
- that @file{~/.profile} is sourced by @file{~/.bash_profile} and
- @file{~/.zprofile}, respectively.
- @subsubheading Shell Profile Service
- @deftp {Data Type} home-shell-profile-configuration
- Available @code{home-shell-profile-configuration} fields are:
- @table @asis
- @item @code{profile} (default: @code{'()}) (type: text-config)
- @code{home-shell-profile} is instantiated automatically by
- @code{home-environment}, DO NOT create this service manually, it can
- only be extended. @code{profile} is a list of file-like objects, which
- will go to @file{~/.profile}. By default @file{~/.profile} contains the
- initialization code which must be evaluated by the login shell to make
- home-environment's profile available to the user, but other commands can
- be added to the file if it is really necessary. In most cases shell's
- configuration files are preferred places for user's customizations.
- Extend home-shell-profile service only if you really know what you do.
- @end table
- @end deftp
- @subsubheading Bash Home Service
- @anchor{home-bash-configuration}
- @deftp {Data Type} home-bash-configuration
- Available @code{home-bash-configuration} fields are:
- @table @asis
- @item @code{package} (default: @code{bash}) (type: package)
- The Bash package to use.
- @item @code{guix-defaults?} (default: @code{#t}) (type: boolean)
- Add sane defaults like reading @file{/etc/bashrc} and coloring the output of
- @command{ls} to the top of the @file{.bashrc} file.
- @item @code{environment-variables} (default: @code{'()}) (type: alist)
- Association list of environment variables to set for the Bash session. The
- rules for the @code{home-environment-variables-service-type} apply
- here (@pxref{Essential Home Services}). The contents of this field will be
- added after the contents of the @code{bash-profile} field.
- @item @code{aliases} (default: @code{'()}) (type: alist)
- Association list of aliases to set for the Bash session. The aliases
- will be defined after the contents of the @code{bashrc} field has been
- put in the @file{.bashrc} file. The alias will automatically be quoted,
- so something like this:
- @lisp
- '(("ls" . "ls -alF"))
- @end lisp
- turns into
- @example
- alias ls="ls -alF"
- @end example
- @item @code{bash-profile} (default: @code{'()}) (type: text-config)
- List of file-like objects, which will be added to @file{.bash_profile}.
- Used for executing user's commands at start of login shell (In most
- cases the shell started on tty just after login). @file{.bash_login}
- won't be ever read, because @file{.bash_profile} always present.
- @item @code{bashrc} (default: @code{'()}) (type: text-config)
- List of file-like objects, which will be added to @file{.bashrc}. Used
- for executing user's commands at start of interactive shell (The shell
- for interactive usage started by typing @code{bash} or by terminal app
- or any other program).
- @item @code{bash-logout} (default: @code{'()}) (type: text-config)
- List of file-like objects, which will be added to @file{.bash_logout}.
- Used for executing user's commands at the exit of login shell. It won't
- be read in some cases (if the shell terminates by exec'ing another
- process for example).
- @end table
- @end deftp
- You can extend the Bash service by using the @code{home-bash-extension}
- configuration record, whose fields must mirror that of
- @code{home-bash-configuration} (@pxref{home-bash-configuration}). The
- contents of the extensions will be added to the end of the corresponding
- Bash configuration files (@pxref{Bash Startup Files,,, bash, The GNU
- Bash Reference Manual}.
- For example, here is how you would define a service that extends the
- Bash service such that @file{~/.bash_profile} defines an additional
- environment variable, @env{PS1}:
- @lisp
- (define bash-fancy-prompt-service
- (simple-service 'bash-fancy-prompt
- home-bash-service-type
- (home-bash-extension
- (environment-variables
- '(("PS1" . "\\u \\wλ "))))))
- @end lisp
- You would then add @code{bash-fancy-prompt-service} to the list in the
- @code{services} field of your @code{home-environment}. The reference of
- @code{home-bash-extension} follows.
- @deftp {Data Type} home-bash-extension
- Available @code{home-bash-extension} fields are:
- @table @asis
- @item @code{environment-variables} (default: @code{'()}) (type: alist)
- Additional environment variables to set. These will be combined with the
- environment variables from other extensions and the base service to form one
- coherent block of environment variables.
- @item @code{aliases} (default: @code{'()}) (type: alist)
- Additional aliases to set. These will be combined with the aliases from
- other extensions and the base service.
- @item @code{bash-profile} (default: @code{'()}) (type: text-config)
- Additional text blocks to add to @file{.bash_profile}, which will be combined
- with text blocks from other extensions and the base service.
- @item @code{bashrc} (default: @code{'()}) (type: text-config)
- Additional text blocks to add to @file{.bashrc}, which will be combined
- with text blocks from other extensions and the base service.
- @item @code{bash-logout} (default: @code{'()}) (type: text-config)
- Additional text blocks to add to @file{.bash_logout}, which will be combined
- with text blocks from other extensions and the base service.
- @end table
- @end deftp
- @subsubheading Zsh Home Service
- @deftp {Data Type} home-zsh-configuration
- Available @code{home-zsh-configuration} fields are:
- @table @asis
- @item @code{package} (default: @code{zsh}) (type: package)
- The Zsh package to use.
- @item @code{xdg-flavor?} (default: @code{#t}) (type: boolean)
- Place all the configs to @file{$XDG_CONFIG_HOME/zsh}. Makes
- @file{~/.zshenv} to set @env{ZDOTDIR} to @file{$XDG_CONFIG_HOME/zsh}.
- Shell startup process will continue with
- @file{$XDG_CONFIG_HOME/zsh/.zshenv}.
- @item @code{environment-variables} (default: @code{'()}) (type: alist)
- Association list of environment variables to set for the Zsh session.
- @item @code{zshenv} (default: @code{'()}) (type: text-config)
- List of file-like objects, which will be added to @file{.zshenv}. Used
- for setting user's shell environment variables. Must not contain
- commands assuming the presence of tty or producing output. Will be read
- always. Will be read before any other file in @env{ZDOTDIR}.
- @item @code{zprofile} (default: @code{'()}) (type: text-config)
- List of file-like objects, which will be added to @file{.zprofile}. Used
- for executing user's commands at start of login shell (In most cases the
- shell started on tty just after login). Will be read before
- @file{.zlogin}.
- @item @code{zshrc} (default: @code{'()}) (type: text-config)
- List of file-like objects, which will be added to @file{.zshrc}. Used
- for executing user's commands at start of interactive shell (The shell
- for interactive usage started by typing @code{zsh} or by terminal app or
- any other program).
- @item @code{zlogin} (default: @code{'()}) (type: text-config)
- List of file-like objects, which will be added to @file{.zlogin}. Used
- for executing user's commands at the end of starting process of login
- shell.
- @item @code{zlogout} (default: @code{'()}) (type: text-config)
- List of file-like objects, which will be added to @file{.zlogout}. Used
- for executing user's commands at the exit of login shell. It won't be
- read in some cases (if the shell terminates by exec'ing another process
- for example).
- @end table
- @end deftp
- @subsubheading Inputrc Profile Service
- @cindex inputrc
- @cindex readline
- The @uref{https://tiswww.cwru.edu/php/chet/readline/rltop.html, GNU
- Readline package} includes Emacs and vi editing modes, with the ability
- to customize the configuration with settings in the @file{~/.inputrc}
- file. With the @code{gnu home services shells} module, you can setup
- your readline configuration in a predictable manner, as shown below.
- For more information about configuring an @file{~/.inputrc} file,
- @pxref{Readline Init File,,, readline, GNU Readline}.
- @defvar home-inputrc-service-type
- This is the service to setup various @file{.inputrc} configurations. The
- settings in @file{.inputrc} are read by all programs which are linked
- with GNU Readline.
- Here is an example of a service and its configuration that you could add
- to the @code{services} field of your @code{home-environment}:
- @lisp
- (service home-inputrc-service-type
- (home-inputrc-configuration
- (key-bindings
- `(("Control-l" . "clear-screen")))
- (variables
- `(("bell-style" . "visible")
- ("colored-completion-prefix" . #t)
- ("editing-mode" . "vi")
- ("show-mode-in-prompt" . #t)))
- (conditional-constructs
- `(("$if mode=vi" .
- ,(home-inputrc-configuration
- (variables
- `(("colored-stats" . #t)
- ("enable-bracketed-paste" . #t)))))
- ("$else" .
- ,(home-inputrc-configuration
- (variables
- `(("show-all-if-ambiguous" . #t)))))
- ("endif" . #t)
- ("$include" . "/etc/inputrc")
- ("$include" . ,(file-append
- (specification->package "readline")
- "/etc/inputrc"))))))
- @end lisp
- The example above starts with a combination of @code{key-bindings} and
- @code{variables}. The @code{conditional-constructs} show how it is
- possible to add conditionals and includes. In the example above
- @code{colored-stats} is only enabled if the editing mode is @code{vi}
- style, and it also reads any additional configuration located in
- @file{/etc/inputrc} or in @file{/gnu/store/@dots{}-readline/etc/inputrc}.
- The value associated with a @code{home-inputrc-service-type} instance
- must be a @code{home-inputrc-configuration} record, as described below.
- @end defvar
- @anchor{home-inputrc-configuration}
- @deftp {Data Type} home-inputrc-configuration
- Available @code{home-inputrc-configuration} fields are:
- @table @asis
- @item @code{key-bindings} (default: @code{'()}) (type: alist)
- Association list of readline key bindings to be added to the
- @file{~/.inputrc} file.
- @lisp
- '((\"Control-l\" . \"clear-screen\"))
- @end lisp
- turns into
- @example
- Control-l: clear-screen
- @end example
- @item @code{variables} (default: @code{'()}) (type: alist)
- Association list of readline variables to set.
- @lisp
- '((\"bell-style\" . \"visible\")
- (\"colored-completion-prefix\" . #t))
- @end lisp
- turns into
- @example
- set bell-style visible
- set colored-completion-prefix on
- @end example
- @item @code{conditional-constructs} (default: @code{'()}) (type: alist)
- Association list of conditionals to add to the initialization file. This
- includes @command{$if}, @command{else}, @command{endif} and @command{include}
- and they receive a value of another @command{home-inputrc-configuration}.
- @lisp
- (conditional-constructs
- `((\"$if mode=vi\" .
- ,(home-inputrc-configuration
- (variables
- `((\"show-mode-in-prompt\" . #t)))))
- (\"$else\" .
- ,(home-inputrc-configuration
- (key-bindings
- `((\"Control-l\" . \"clear-screen\")))))
- (\"$endif\" . #t)))
- @end lisp
- turns into
- @example
- $if mode=vi
- set show-mode-in-prompt on
- $else
- Control-l: clear-screen
- $endif
- @end example
- @item @code{extra-content} (default: @code{""}) (type: text-config)
- Extra content appended as-is to the configuration file. Run @command{man
- readline} for more information about all the configuration options.
- @end table
- @end deftp
- @node Mcron Home Service
- @subsection Scheduled User's Job Execution
- @cindex cron
- @cindex mcron
- @cindex scheduling jobs
- The @code{(gnu home services mcron)} module provides an interface to
- GNU@tie{}mcron, a daemon to run jobs at scheduled times (@pxref{Top,,,
- mcron, GNU@tie{}mcron}). The information about system's mcron is
- applicable here (@pxref{Scheduled Job Execution}), the only difference
- for home services is that they have to be declared in a
- @code{home-environment} record instead of an @code{operating-system}
- record.
- @defvar home-mcron-service-type
- This is the type of the @code{mcron} home service, whose value is a
- @code{home-mcron-configuration} object. It allows to manage scheduled
- tasks.
- This service type can be the target of a service extension that provides
- additional job specifications (@pxref{Service Composition}). In other
- words, it is possible to define services that provide additional mcron
- jobs to run.
- @end defvar
- @deftp {Data Type} home-mcron-configuration
- Available @code{home-mcron-configuration} fields are:
- @c Auto-generated with (gnu home services mcron)'s
- @c generate-documentation procedure.
- @c %start of fragment
- @table @asis
- @item @code{mcron} (default: @code{mcron}) (type: file-like)
- The mcron package to use.
- @item @code{jobs} (default: @code{'()}) (type: list-of-gexps)
- 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}).
- @item @code{log?} (default: @code{#t}) (type: boolean)
- Log messages to standard output.
- @item @code{log-format} (default: @code{"~1@@*~a ~a: ~a~%"}) (type: string)
- @code{(ice-9 format)} format string for log messages. The default value
- produces messages like "@samp{@var{pid} @var{name}: @var{message}"}
- (@pxref{Invoking mcron, Invoking,, mcron,GNU@tie{}mcron}). Each message
- is also prefixed by a timestamp by GNU Shepherd.
- @end table
- @end deftp
- @c %end of fragment
- @node Power Management Home Services
- @subsection Power Management Home Services
- @cindex power management
- The @code{(gnu home services pm)} module provides home services
- pertaining to battery power.
- @defvar home-batsignal-service-type
- Service for @code{batsignal}, a program that monitors battery levels
- and warns the user through desktop notifications when their battery
- is getting low. You can also configure a command to be run when the
- battery level passes a point deemed ``dangerous''. This service is
- configured with the @code{home-batsignal-configuration} record.
- @end defvar
- @deftp {Data Type} home-batsignal-configuration
- Data type representing the configuration for batsignal.
- @table @asis
- @item @code{warning-level} (default: @code{15})
- The battery level to send a warning message at.
- @item @code{warning-message} (default: @code{#f})
- The message to send as a notification when the battery level reaches
- the @code{warning-level}. Setting to @code{#f} uses the default
- message.
- @item @code{critical-level} (default: @code{5})
- The battery level to send a critical message at.
- @item @code{critical-message} (default: @code{#f})
- The message to send as a notification when the battery level reaches
- the @code{critical-level}. Setting to @code{#f} uses the default
- message.
- @item @code{danger-level} (default: @code{2})
- The battery level to run the @code{danger-command} at.
- @item @code{danger-command} (default: @code{#f})
- The command to run when the battery level reaches the @code{danger-level}.
- Setting to @code{#f} disables running the command entirely.
- @item @code{full-level} (default: @code{#f})
- The battery level to send a full message at. Setting to @code{#f}
- disables sending the full message entirely.
- @item @code{full-message} (default: @code{#f})
- The message to send as a notification when the battery level reaches
- the @code{full-level}. Setting to @code{#f} uses the default message.
- @item @code{batteries} (default: @code{'()})
- The batteries to monitor. Setting to @code{'()} tries to find batteries
- automatically.
- @item @code{poll-delay} (default: @code{60})
- The time in seconds to wait before checking the batteries again.
- @item @code{icon} (default: @code{#f})
- A file-like object to use as the icon for battery notifications. Setting
- to @code{#f} disables notification icons entirely.
- @item @code{notifications?} (default: @code{#t})
- Whether to send any notifications.
- @item @code{notifications-expire?} (default: @code{#f})
- Whether notifications sent expire after a time.
- @item @code{notification-command} (default: @code{#f})
- Command to use to send messages. Setting to @code{#f} sends a notification
- through @code{libnotify}.
- @item @code{ignore-missing?} (default: @code{#f})
- Whether to ignore missing battery errors.
- @end table
- @end deftp
- @node Shepherd Home Service
- @subsection Managing User Daemons
- @cindex shepherd services, for users
- The @code{(gnu home services shepherd)} module supports the definitions
- of per-user Shepherd services (@pxref{Introduction,,, shepherd, The GNU
- Shepherd Manual}). You extend @code{home-shepherd-service-type} with
- new services; Guix Home then takes care of starting the @code{shepherd}
- daemon for you when you log in, which in turns starts the services you
- asked for.
- @defvar home-shepherd-service-type
- The service type for the userland Shepherd, which allows one to manage
- long-running processes or one-shot tasks. User's Shepherd is not an
- init process (PID 1), but almost all other information described in
- (@pxref{Shepherd Services}) is applicable here too.
- This is the service type that extensions target when they want to create
- shepherd services (@pxref{Service Types and Services}, for an example).
- Each extension must pass a list of @code{<shepherd-service>}. Its
- value must be a @code{home-shepherd-configuration}, as described below.
- @end defvar
- @deftp {Data Type} home-shepherd-configuration
- This data type represents the Shepherd's configuration.
- @table @code
- @item shepherd (default: @code{shepherd})
- The Shepherd package to use.
- @item auto-start? (default: @code{#t})
- Whether or not to start Shepherd on first login.
- @item services (default: @code{'()})
- A list of @code{<shepherd-service>} to start.
- You should probably use the service extension
- mechanism instead (@pxref{Shepherd Services}).
- @end table
- @end deftp
- @node Secure Shell
- @subsection Secure Shell
- @cindex secure shell client, configuration
- @cindex SSH client, configuration
- The @uref{https://www.openssh.com, OpenSSH package} includes a client,
- the @command{ssh} command, that allows you to connect to remote machines
- using the @acronym{SSH, secure shell} protocol. With the @code{(gnu
- home services ssh)} module, you can set up OpenSSH so that it works in a
- predictable fashion, almost independently of state on the local machine.
- To do that, you instantiate @code{home-openssh-service-type} in your
- Home configuration, as explained below.
- @defvar home-openssh-service-type
- This is the type of the service to set up the OpenSSH client. It takes
- care of several things:
- @itemize
- @item
- providing a @file{~/.ssh/config} file based on your configuration so
- that @command{ssh} knows about hosts you regularly connect to and their
- associated parameters;
- @item
- providing a @file{~/.ssh/authorized_keys}, which lists public keys that
- the local SSH server, @command{sshd}, may accept to connect to this user
- account;
- @item
- optionally providing a @file{~/.ssh/known_hosts} file so that @file{ssh}
- can authenticate hosts you connect to.
- @end itemize
- Here is an example of a service and its configuration that you could add
- to the @code{services} field of your @code{home-environment}:
- @lisp
- (service home-openssh-service-type
- (home-openssh-configuration
- (hosts
- (list (openssh-host (name "ci.guix.gnu.org")
- (user "charlie"))
- (openssh-host (name "chbouib")
- (host-name "chbouib.example.org")
- (user "supercharlie")
- (port 10022))))
- (authorized-keys (list (local-file "alice.pub")))))
- @end lisp
- The example above lists two hosts and their parameters. For instance,
- running @command{ssh chbouib} will automatically connect to
- @code{chbouib.example.org} on port 10022, logging in as user
- @samp{supercharlie}. Further, it marks the public key in
- @file{alice.pub} as authorized for incoming connections.
- The value associated with a @code{home-openssh-service-type} instance
- must be a @code{home-openssh-configuration} record, as describe below.
- @end defvar
- @deftp {Data Type} home-openssh-configuration
- This is the datatype representing the OpenSSH client and server
- configuration in one's home environment. It contains the following
- fields:
- @table @asis
- @item @code{hosts} (default: @code{'()})
- A list of @code{openssh-host} records specifying host names and
- associated connection parameters (see below). This host list goes into
- @file{~/.ssh/config}, which @command{ssh} reads at startup.
- @item @code{known-hosts} (default: @code{*unspecified*})
- This must be either:
- @itemize
- @item
- @code{*unspecified*}, in which case @code{home-openssh-service-type}
- leaves it up to @command{ssh} and to the user to maintain the list of
- known hosts at @file{~/.ssh/known_hosts}, or
- @item
- a list of file-like objects, in which case those are concatenated and
- emitted as @file{~/.ssh/known_hosts}.
- @end itemize
- The @file{~/.ssh/known_hosts} contains a list of host name/host key
- pairs that allow @command{ssh} to authenticate hosts you connect to and
- to detect possible impersonation attacks. By default, @command{ssh}
- updates it in a @dfn{TOFU, trust-on-first-use} fashion, meaning that it
- records the host's key in that file the first time you connect to it.
- This behavior is preserved when @code{known-hosts} is set to
- @code{*unspecified*}.
- If you instead provide a list of host keys upfront in the
- @code{known-hosts} field, your configuration becomes self-contained and
- stateless: it can be replicated elsewhere or at another point in time.
- Preparing this list can be relatively tedious though, which is why
- @code{*unspecified*} is kept as a default.
- @item @code{authorized-keys} (default: @code{#false})
- The default @code{#false} value means: Leave any
- @file{~/.ssh/authorized_keys} file alone. Otherwise, this must be a
- list of file-like objects, each of which containing an SSH public key
- that should be authorized to connect to this machine.
- Concretely, these files are concatenated and made available as
- @file{~/.ssh/authorized_keys}. If an OpenSSH server, @command{sshd}, is
- running on this machine, then it @emph{may} take this file into account:
- this is what @command{sshd} does by default, but be aware that it can
- also be configured to ignore it.
- @item @code{add-keys-to-agent} (default: @code{``no''})
- This string specifies whether keys should be automatically added to a
- running ssh-agent. If this option is set to @code{``yes''} and a key is
- loaded from a file, the key and its passphrase are added to the agent
- with the default lifetime, as if by @code{ssh-add}. If this option is
- set to @code{``ask''}, @code{ssh} will require confirmation. If this
- option is set to @code{``confirm''}, each use of the key must be
- confirmed. If this option is set to @code{``no''}, no keys are added to
- the agent. Alternately, this option may be specified as a time interval
- to specify the key's lifetime in @code{ssh-agent}, after which it will
- automatically be removed. The argument must be @code{``no''},
- @code{``yes''}, @code{``confirm''} (optionally followed by a time
- interval), @code{``ask''} or a time interval.
- @end table
- @end deftp
- @c %start of fragment
- @deftp {Data Type} openssh-host
- Available @code{openssh-host} fields are:
- @table @asis
- @item @code{name} (type: string)
- Name of this host declaration. A @code{openssh-host} must define only
- @code{name} or @code{match-criteria}. Use host-name @code{\"*\"} for
- top-level options.
- @item @code{host-name} (type: maybe-string)
- Host name---e.g., @code{"foo.example.org"} or @code{"192.168.1.2"}.
- @item @code{match-criteria} (type: maybe-match-criteria)
- When specified, this string denotes the set of hosts to which the entry
- applies, superseding the @code{host-name} field. Its first element must be
- all or one of @code{ssh-match-keywords}. The rest of the elements are
- arguments for the keyword, or other criteria. A @code{openssh-host} must
- define only @code{name} or @code{match-criteria}. Other host configuration
- options will apply to all hosts matching @code{match-criteria}.
- @item @code{address-family} (type: maybe-address-family)
- Address family to use when connecting to this host: one of
- @code{AF_INET} (for IPv4 only), @code{AF_INET6} (for IPv6 only).
- Additionally, the field can be left unset to allow any address family.
- @item @code{identity-file} (type: maybe-string)
- The identity file to use---e.g., @code{"/home/charlie/.ssh/id_ed25519"}.
- @item @code{port} (type: maybe-natural-number)
- TCP port number to connect to.
- @item @code{user} (type: maybe-string)
- User name on the remote host.
- @item @code{forward-x11?} (type: maybe-boolean)
- Whether to forward remote client connections to the local X11 graphical
- display.
- @item @code{forward-x11-trusted?} (type: maybe-boolean)
- Whether remote X11 clients have full access to the original X11
- graphical display.
- @item @code{forward-agent?} (type: maybe-boolean)
- Whether the authentication agent (if any) is forwarded to the remote
- machine.
- @item @code{compression?} (type: maybe-boolean)
- Whether to compress data in transit.
- @item @code{proxy} (type: maybe-proxy-command-or-jump-list)
- The command to use to connect to the server or a list of SSH hosts to
- jump through before connecting to the server. The field may be set to either a
- @code{proxy-command} or a list of @code{proxy-jump} records.
- As an example, a @code{proxy-command} to connect via an HTTP proxy at 192.0.2.0
- would be constructed with: @code{(proxy-command "nc -X connect -x
- 192.0.2.0:8080 %h %p")}.
- @deftp {Data Type} proxy-jump
- Available @code{proxy-jump} fields are:
- @table @asis
- @item @code{user} (type: maybe-string)
- User name on the remote host.
- @item @code{host-name} (type: string)
- Host name---e.g., @code{foo.example.org} or @code{192.168.1.2}.
- @item @code{port} (type: maybe-natural-number)
- TCP port number to connect to.
- @end table
- @end deftp
- @item @code{host-key-algorithms} (type: maybe-string-list)
- The list of accepted host key algorithms---e.g.,
- @code{'("ssh-ed25519")}.
- @item @code{accepted-key-types} (type: maybe-string-list)
- The list of accepted user public key types.
- @item @code{extra-content} (default: @code{""}) (type: raw-configuration-string)
- Extra content appended as-is to this @code{Host} block in
- @file{~/.ssh/config}.
- @end table
- @end deftp
- @cindex Parcimonie, Home service
- The @code{parcimonie} service runs a daemon that slowly refreshes a GnuPG
- public key from a keyserver. It refreshes one key at a time; between every
- key update parcimonie sleeps a random amount of time, long enough for the
- previously used Tor circuit to expire. This process is meant to make it hard
- for an attacker to correlate the multiple key update.
- As an example, here is how you would configure @code{parcimonie} to refresh the
- keys in your GnuPG keyring, as well as those keyrings created by Guix, such as
- when running @code{guix import}:
- @lisp
- (service home-parcimonie-service-type
- (home-parcimonie-configuration
- (refresh-guix-keyrings? #t)))
- @end lisp
- This assumes that the Tor anonymous routing daemon is already running on your
- system. On Guix System, this can be achieved by setting up
- @code{tor-service-type} (@pxref{Networking Services, @code{tor-service-type}}).
- The service reference is given below.
- @defvar parcimonie-service-type
- This is the service type for @command{parcimonie}
- (@uref{https://salsa.debian.org/intrigeri/parcimonie, Parcimonie's web site}).
- Its value must be a @code{home-parcimonie-configuration}, as shown below.
- @end defvar
- @c %start of fragment
- @deftp {Data Table} home-parcimonie-configuration
- Available @code{home-parcimonie-configuration} fields are:
- @table @asis
- @item @code{parcimonie} (default: @code{parcimonie}) (type: file-like)
- The parcimonie package to use.
- @item @code{verbose?} (default: @code{#f}) (type: boolean)
- Whether to have more verbose logging from the service.
- @item @code{gnupg-already-torified?} (default: @code{#f}) (type: boolean)
- Whether GnuPG is already configured to pass all traffic through
- @uref{https://torproject.org, Tor}.
- @item @code{refresh-guix-keyrings?} (default: @code{#f}) (type: boolean)
- Guix creates a few keyrings in the @var{$XDG_CONFIG_DIR}, such as when running
- @code{guix import} (@pxref{Invoking guix import}). Setting this to @code{#t}
- will also refresh any keyrings which Guix has created.
- @item @code{extra-content} (default: @code{#f}) (type: raw-configuration-string)
- Raw content to add to the parcimonie command.
- @end table
- @end deftp
- @c %end of fragment
- @cindex ssh-agent
- The @uref{https://www.openssh.com, OpenSSH package} includes a daemon,
- the @command{ssh-agent} command, that manages keys to connect to remote
- machines using the @acronym{SSH, secure shell} protocol. With the
- @code{(gnu home services ssh)} service, you can configure the
- OpenSSH ssh-agent to run upon login. @xref{GNU Privacy Guard,
- @code{home-gpg-agent-service-type}}, for an alternative to OpenSSH's
- @command{ssh-agent}.
- Here is an example of a service and its configuration that you could add
- to the @code{services} field of your @code{home-environment}:
- @lisp
- (service home-ssh-agent-service-type
- (home-ssh-agent-configuration
- (extra-options '("-t" "1h30m"))))
- @end lisp
- @defvar home-ssh-agent-service-type
- This is the type of the @code{ssh-agent} home service, whose value is a
- @code{home-ssh-agent-configuration} object.
- @end defvar
- @deftp {Data Type} home-ssh-agent-configuration
- Available @code{home-ssh-agent-configuration} fields are:
- @table @asis
- @item @code{openssh} (default: @code{openssh}) (type: file-like)
- The OpenSSH package to use.
- @item @code{socket-directory} (default: @code{@env{XDG_RUNTIME_DIR}/ssh-agent"}) (type: gexp)
- The directory to write the ssh-agent's @file{socket} file.
- @item @code{extra-options} (default: @code{'()})
- Extra options will be passed to @command{ssh-agent}, please run
- @command{man ssh-agent} for more information.
- @end table
- @end deftp
- @node GNU Privacy Guard
- @subsection GNU Privacy Guard
- @cindex GNU Privacy Guard, Home service
- @cindex GPG, Home service
- The @code{(gnu home services gnupg)} modules provides services that help
- you set up the GNU Privacy Guard, also known as GnuPG or GPG, in your
- home environment.
- @cindex gpg-agent, Home service
- @cindex SSH agent, with gpg-agent
- The @code{gpg-agent} service configures and sets up GPG's agent, the
- program that is responsible for managing OpenPGP private keys and,
- optionally, OpenSSH (secure shell) private keys (@pxref{Invoking
- GPG-AGENT,,, gnupg, Using the GNU Privacy Guard}).
- As an example, here is how you would configure @code{gpg-agent} with SSH
- support such that it uses the Emacs-based Pinentry interface when
- prompting for a passphrase:
- @lisp
- (service home-gpg-agent-service-type
- (home-gpg-agent-configuration
- (pinentry-program
- (file-append pinentry-emacs "/bin/pinentry-emacs"))
- (ssh-support? #t)))
- @end lisp
- The service reference is given below.
- @defvar home-gpg-agent-service-type
- This is the service type for @command{gpg-agent} (@pxref{Invoking
- GPG-AGENT,,, gnupg, Using the GNU Privacy Guard}). Its value must be a
- @code{home-gpg-agent-configuration}, as shown below.
- @end defvar
- @c %start of fragment
- @deftp {Data Type} home-gpg-agent-configuration
- Available @code{home-gpg-agent-configuration} fields are:
- @table @asis
- @item @code{gnupg} (default: @code{gnupg}) (type: file-like)
- The GnuPG package to use.
- @item @code{pinentry-program} (type: file-like)
- Pinentry program to use. Pinentry is a small user interface that
- @command{gpg-agent} delegates to anytime it needs user input for a
- passphrase or @acronym{PIN,personal identification number}
- (@pxref{Top,,, pinentry,Using the PIN-Entry}).
- @item @code{ssh-support?} (default: @code{#f}) (type: boolean)
- Whether to enable @acronym{SSH,secure shell} support. When true,
- @command{gpg-agent} acts as a drop-in replacement for OpenSSH's
- @command{ssh-agent} program, taking care of OpenSSH secret keys and
- directing passphrase requests to the chosen Pinentry program.
- @item @code{default-cache-ttl} (default: @code{600}) (type: integer)
- Time a cache entry is valid, in seconds.
- @item @code{max-cache-ttl} (default: @code{7200}) (type: integer)
- Maximum time a cache entry is valid, in seconds. After this time a
- cache entry will be expired even if it has been accessed recently.
- @item @code{default-cache-ttl-ssh} (default: @code{1800}) (type: integer)
- Time a cache entry for SSH keys is valid, in seconds.
- @item @code{max-cache-ttl-ssh} (default: @code{7200}) (type: integer)
- Maximum time a cache entry for SSH keys is valid, in seconds.
- @item @code{extra-content} (default: @code{""}) (type: raw-configuration-string)
- Raw content to add to the end of @file{~/.gnupg/gpg-agent.conf}.
- @end table
- @end deftp
- @c %end of fragment
- @node Desktop Home Services
- @subsection Desktop Home Services
- The @code{(gnu home services desktop)} module provides services that you
- may find useful on ``desktop'' systems running a graphical user
- environment such as Xorg.
- @defvar home-redshift-service-type
- This is the service type for @uref{https://github.com/jonls/redshift,
- Redshift}, a program that adjusts the display color temperature
- according to the time of day. Its associated value must be a
- @code{home-redshift-configuration} record, as shown below.
- A typical configuration, where we manually specify the latitude and
- longitude, might look like this:
- @lisp
- (service home-redshift-service-type
- (home-redshift-configuration
- (location-provider 'manual)
- (latitude 35.81) ;northern hemisphere
- (longitude -0.80))) ;west of Greenwich
- @end lisp
- @end defvar
- @deftp {Data Type} home-redshift-configuration
- Available @code{home-redshift-configuration} fields are:
- @table @asis
- @item @code{redshift} (default: @code{redshift}) (type: file-like)
- Redshift package to use.
- @item @code{location-provider} (default: @code{geoclue2}) (type: symbol)
- Geolocation provider---@code{'manual} or @code{'geoclue2}. In the
- former case, you must also specify the @code{latitude} and
- @code{longitude} fields so Redshift can determine daytime at your place.
- In the latter case, the Geoclue system service must be running; it will
- be queried for location information.
- @item @code{adjustment-method} (default: @code{randr}) (type: symbol)
- Color adjustment method.
- @item @code{daytime-temperature} (default: @code{6500}) (type: integer)
- Daytime color temperature (kelvins).
- @item @code{nighttime-temperature} (default: @code{4500}) (type: integer)
- Nighttime color temperature (kelvins).
- @item @code{daytime-brightness} (type: maybe-inexact-number)
- Daytime screen brightness, between 0.1 and 1.0, or left unspecified.
- @item @code{nighttime-brightness} (type: maybe-inexact-number)
- Nighttime screen brightness, between 0.1 and 1.0, or left unspecified.
- @item @code{latitude} (type: maybe-inexact-number)
- Latitude, when @code{location-provider} is @code{'manual}.
- @item @code{longitude} (type: maybe-inexact-number)
- Longitude, when @code{location-provider} is @code{'manual}.
- @item @code{dawn-time} (type: maybe-string)
- Custom time for the transition from night to day in the
- morning---@code{"HH:MM"} format. When specified, solar elevation is not
- used to determine the daytime/nighttime period.
- @item @code{dusk-time} (type: maybe-string)
- Likewise, custom time for the transition from day to night in the
- evening.
- @item @code{extra-content} (default: @code{""}) (type: raw-configuration-string)
- Extra content appended as-is to the Redshift configuration file. Run
- @command{man redshift} for more information about the configuration file
- format.
- @end table
- @end deftp
- @defvar home-dbus-service-type
- This is the service type for running a session-specific D-Bus, for
- unprivileged applications that require D-Bus to be running.
- @end defvar
- @deftp {Data Type} home-dbus-configuration
- The configuration record for @code{home-dbus-service-type}.
- @table @asis
- @item @code{dbus} (default: @code{dbus})
- The package providing the @code{/bin/dbus-daemon} command.
- @end table
- @end deftp
- @defvar home-unclutter-service-type
- This is the service type for Unclutter, a program that runs on the
- background of an X11 session and detects when the X pointer hasn't moved
- for a specified idle timeout, after which it hides the cursor so that
- you can focus on the text underneath. Its associated value must be a
- @code{home-unclutter-configuration} record, as shown below.
- A typical configuration, where we manually specify the idle timeout (in
- seconds), might look like this:
- @lisp
- (service home-unclutter-service-type
- (home-unclutter-configuration
- (idle-timeout 2)))
- @end lisp
- @end defvar
- @deftp {Data Type} home-unclutter-configuration
- The configuration record for @code{home-unclutter-service-type}.
- @table @asis
- @item @code{unclutter} (default: @code{unclutter}) (type: file-like)
- Unclutter package to use.
- @item @code{idle-timeout} (default: @code{5}) (type: integer)
- A timeout in seconds after which to hide cursor.
- @end table
- @end deftp
- @defvar home-xmodmap-service-type
- This is the service type for the
- @uref{https://gitlab.freedesktop.org/xorg/app/xmodmap,xmodmap} utility
- to modify keymaps and pointer button mappings under the Xorg display
- server. Its associated value must be a
- @code{home-xmodmap-configuration} record, as shown below.
- The @code{key-map} field takes a list of objects, each of which is
- either a @dfn{statement} (a string) or an @dfn{assignment} (a pair of
- strings). As an example, the snippet below swaps around the
- @kbd{Caps_Lock} and the @kbd{Control_L} keys, by first removing the
- keysyms (on the right-hand side) from the corresponding modifier maps
- (on the left-hand side), re-assigning them by swapping each other out,
- and finally adding back the keysyms to the modifier maps.
- @lisp
- (service home-xmodmap-service-type
- (home-xmodmap-configuration
- (key-map '(("remove Lock" . "Caps_Lock")
- ("remove Control" . "Control_L")
- ("keysym Control_L" . "Caps_Lock")
- ("keysym Caps_Lock" . "Control_L")
- ("add Lock" . "Caps_Lock")
- ("add Control" . "Control_L")))))
- @end lisp
- @end defvar
- @deftp {Data Type} home-xmodmap-configuration
- The configuration record for @code{home-xmodmap-service-type}. Its
- available fields are:
- @table @asis
- @item @code{xmodmap} (default: @code{xmodmap}) (type: file-like)
- The @code{xmodmap} package to use.
- @item @code{key-map} (default: @code{'()}) (type: list)
- The list of expressions to be read by @code{xmodmap} on service startup.
- @end table
- @end deftp
- @node Guix Home Services
- @subsection Guix Home Services
- The @code{(gnu home services guix)} module provides services for
- user-specific Guix configuration.
- @defvar home-channels-service-type
- This is the service type for managing
- @file{$XDG_CONFIG_HOME/guix/channels.scm}, the file that controls the
- channels received on @command{guix pull} (@pxref{Channels}). Its
- associated value is a list of @code{channel} records, defined in the
- @code{(guix channels)} module.
- Generally, it is better to extend this service than to directly
- configure it, as its default value is the default guix channel(s)
- defined by @code{%default-channels}. If you configure this service
- directly, be sure to include a guix channel. @xref{Specifying
- Additional Channels} and @ref{Using a Custom Guix Channel} for more
- details.
- A typical extension for adding a channel might look like this:
- @lisp
- (simple-service 'variant-packages-service
- home-channels-service-type
- (list
- (channel
- (name 'variant-packages)
- (url "https://example.org/variant-packages.git"))))
- @end lisp
- @end defvar
- @node Fonts Home Services
- @subsection Fonts Home Services
- The @code{(gnu home services fontutils)} module provides services for
- user-specific Fontconfig setup. The
- @uref{https://www.freedesktop.org/wiki/Software/fontconfig,Fontconfig}
- library is used by many applications to access fonts on the system.
- @defvar home-fontconfig-service-type
- This is the service type for generating configurations for Fontconfig.
- Its associated value is a list of either strings (or gexps) pointing to
- fonts locations, or SXML (@pxref{SXML,,, guile, GNU Guile Reference
- Manual}) fragments to be converted into XML and put inside the main
- @code{fontconfig} node.
- Generally, it is better to extend this service than to directly
- configure it, as its default value is the default Guix Home's profile
- font installation path (@file{~/.guix-home/profile/share/fonts}). If
- you configure this service directly, be sure to include the above
- directory.
- Here's how you'd extend it to include fonts installed with the Nix
- package manager, and to prefer your favourite monospace font:
- @lisp
- (simple-service 'additional-fonts-service
- home-fontconfig-service-type
- (list "~/.nix-profile/share/fonts"
- '(alias
- (family "monospace")
- (prefer
- (family "Liberation Mono")))))
- @end lisp
- @end defvar
- @node Sound Home Services
- @subsection Sound Home Services
- The @code{(gnu home services sound)} module provides services related to
- sound support.
- @cindex PulseAudio, home service
- @cindex RTP, for PulseAudio
- The following services dynamically reconfigure the
- @uref{https://pulseaudio.org,PulseAudio sound server}: they let you
- toggle broadcast of audio output over the network using the
- @acronym{RTP, real-time transport protocol} and, correspondingly,
- playback of sound received over RTP. Once
- @code{home-pulseaudio-rtp-sink-service-type} is among your home
- services, you can start broadcasting audio output by running this
- command:
- @example
- herd start pulseaudio-rtp-sink
- @end example
- You can then run a PulseAudio-capable mixer, such as @code{pavucontrol}
- or @code{pulsemixer} (both from the same-named package) to control which
- audio stream(s) should be sent to the RTP ``sink''.
- By default, audio is broadcasted to a multicast address: any device on
- the @acronym{LAN, local area network} receives it and may play it.
- Using multicast in this way puts a lot of pressure on the network and
- degrades its performance, so you may instead prefer sending to
- specifically one device. The first way to do that is by specifying the
- IP address of the target device when starting the service:
- @example
- herd start pulseaudio-rtp-sink 192.168.1.42
- @end example
- The other option is to specify this IP address as the one to use by
- default in your home environment configuration:
- @lisp
- (service home-pulseaudio-rtp-sink-service-type
- "192.168.1.42")
- @end lisp
- On the device where you intend to receive and play the RTP stream, you
- can use @code{home-pulseaudio-rtp-source-service-type}, like so:
- @lisp
- (service home-pulseaudio-rtp-source-service-type)
- @end lisp
- This will then let you start the receiving module for PulseAudio:
- @example
- herd start pulseaudio-rtp-source
- @end example
- Again, by default it will listen on the multicast address. If, instead,
- you'd like it to listen for direct incoming connections, you can do that
- by running:
- @lisp
- (service home-pulseaudio-rtp-source-service-type
- "0.0.0.0")
- @end lisp
- The reference of these services is given below.
- @defvar home-pulseaudio-rtp-sink-service-type
- @defvarx home-pulseaudio-rtp-source-service-type
- This is the type of the service to send, respectively receive, audio
- streams over @acronym{RTP, real-time transport protocol}.
- The value associated with this service is the IP address (a string)
- where to send, respectively receive, the audio stream. By default,
- audio is sent/received on multicast address
- @code{%pulseaudio-rtp-multicast-address}.
- This service defines one Shepherd service: @code{pulseaudio-rtp-sink},
- respectively @code{pulseaudio-rtp-source}. The service is not started
- by default, so you have to explicitly start it when you want to turn it
- on, as in this example:
- @example
- herd start pulseaudio-rtp-sink
- @end example
- Stopping the Shepherd service turns off broadcasting.
- @end defvar
- @defvar %pulseaudio-rtp-multicast-address
- This is the multicast address used by default by the two services above.
- @end defvar
- @node Mail Home Services
- @subsection Mail Home Services
-
- The @code{(gnu home services mail)} module provides services that help
- you set up the tools to work with emails in your home environment.
-
- @cindex msmtp
- @uref{https://marlam.de/msmtp, MSMTP} is a @acronym{SMTP, Simple Mail
- Transfer Protocol} client. It sends mail to a predefined SMTP server
- that takes care of proper delivery.
-
- The service reference is given below.
-
- @defvar home-msmtp-service-type
- This is the service type for @command{msmtp}. Its value must be a
- @code{home-msmtp-configuration}, as shown below. It provides the
- @file{~/.config/msmtp/config} file.
-
- As an example, here is how you would configure @code{msmtp} for a single
- account:
-
- @lisp
- (service home-msmtp-service-type
- (home-msmtp-configuration
- (accounts
- (list
- (msmtp-account
- (name "alice")
- (configuration
- (msmtp-configuration
- (host "mail.example.org")
- (port 587)
- (user "alice")
- (password-eval "pass Mail/alice"))))))))
- @end lisp
- @end defvar
- @c %start of fragment
-
- @deftp {Data Type} home-msmtp-configuration
- Available @code{home-msmtp-configuration} fields are:
-
- @table @asis
- @item @code{defaults} (type: msmtp-configuration)
- The configuration that will be set as default for all accounts.
-
- @item @code{accounts} (default: @code{'()}) (type: list-of-msmtp-accounts)
- A list of @code{msmtp-account} records which contain information about
- all your accounts.
-
- @item @code{default-account} (type: maybe-string)
- Set the default account.
-
- @item @code{extra-content} (default: @code{""}) (type: string)
- Extra content appended as-is to the configuration file. Run
- @command{man msmtp} for more information about the configuration file
- format.
-
- @end table
-
- @end deftp
-
- @c %end of fragment
-
- @c %start of fragment
-
- @deftp {Data Type} msmtp-account
- Available @code{msmtp-account} fields are:
-
- @table @asis
- @item @code{name} (type: string)
- The unique name of the account.
-
- @item @code{configuration} (type: msmtp-configuration)
- The configuration for this given account.
-
- @end table
-
- @end deftp
-
- @c %end of fragment
- @c %start of fragment
-
- @deftp {Data Type} msmtp-configuration
- Available @code{msmtp-configuration} fields are:
-
- @table @asis
- @item @code{auth?} (type: maybe-boolean)
- Enable or disable authentication.
-
- @item @code{tls?} (type: maybe-boolean)
- Enable or disable TLS (also known as SSL) for secured connections.
-
- @item @code{tls-starttls?} (type: maybe-boolean)
- Choose the TLS variant: start TLS from within the session (‘on’,
- default), or tunnel the session through TLS (‘off’).
-
- @item @code{tls-trust-file} (type: maybe-string)
- Activate server certificate verification using a list of trusted
- Certification Authorities (CAs).
-
- @item @code{log-file} (type: maybe-string)
- Enable logging to the specified file. An empty argument disables
- logging. The file name ‘-’ directs the log information to standard
- output.
-
- @item @code{host} (type: maybe-string)
- The SMTP server to send the mail to.
-
- @item @code{port} (type: maybe-integer)
- The port that the SMTP server listens on. The default is 25 ("smtp"),
- unless TLS without STARTTLS is used, in which case it is 465 ("smtps").
-
- @item @code{user} (type: maybe-string)
- Set the user name for authentication.
-
- @item @code{from} (type: maybe-string)
- Set the envelope-from address.
-
- @item @code{password-eval} (type: maybe-string)
- Set the password for authentication to the output (stdout) of the
- command cmd.
-
- @item @code{extra-content} (default: @code{""}) (type: string)
- Extra content appended as-is to the configuration block. Run
- @command{man msmtp} for more information about the configuration file
- format.
-
- @end table
-
- @end deftp
-
- @c %end of fragment
- @node Messaging Home Services
- @subsection Messaging Home Services
- @cindex znc
- The @uref{https://znc.in, ZNC bouncer} can be run as a daemon to manage
- your IRC presence. With the @code{(gnu home services messaging)} service, you
- can configure ZNC to run upon login.
- You will have to provide a @file{~/.znc/configs/znc.conf} separately.
- Here is an example of a service and its configuration that you could add
- to the @code{services} field of your @code{home-environment}:
- @lisp
- (service home-znc-service-type)
- @end lisp
- @defvar home-znc-service-type
- This is the type of the ZNC home service, whose value is a
- @code{home-znc-configuration} object.
- @end defvar
- @deftp {Data Type} home-znc-configuration
- Available @code{home-znc-configuration} fields are:
- @table @asis
- @item @code{znc} (default: @code{znc}) (type: file-like)
- The ZNC package to use.
- @item @code{extra-options} (default: @code{'()})
- Extra options will be passed to @command{znc}, please run @command{man
- znc} for more information.
- @end table
- @end deftp
- @node Media Home Services
- @subsection Media Home Services
- @cindex kodi
- The @uref{https://kodi.tv, Kodi media center} can be run as a daemon on
- a media server. With the @code{(gnu home services kodi)} service, you
- can configure Kodi to run upon login.
- Here is an example of a service and its configuration that you could add
- to the @code{services} field of your @code{home-environment}:
- @lisp
- (service home-kodi-service-type
- (home-kodi-configuration
- (extra-options '("--settings="<settings-file>"))))
- @end lisp
- @defvar home-kodi-service-type
- This is the type of the Kodi home service, whose value is a
- @code{home-kodi-configuration} object.
- @end defvar
- @deftp {Data Type} home-kodi-configuration
- Available @code{home-kodi-configuration} fields are:
- @table @asis
- @item @code{kodi} (default: @code{kodi}) (type: file-like)
- The Kodi package to use.
- @item @code{extra-options} (default: @code{'()})
- Extra options will be passed to @command{kodi}, please run @command{man
- kodi} for more information.
- @end table
- @end deftp
- @node Networking Home Services
- @subsection Networking Home Services
- This section lists services somewhat networking-related that you may use
- with Guix Home.
- @cindex Syncthing, file synchronization service
- @cindex backup service, Syncthing
- The @code{(gnu home services syncthing)} module provides a service to
- set up the @uref{Syncthing, https://syncthing.net} continuous file
- backup service.
- @defvar home-syncthing-service-type
- This is the service type for the @command{syncthing} daemon; it is the
- Home counterpart of the @code{syncthing-service-type} system service
- (@pxref{Networking Services, @code{syncthing-service-type}}). The value
- for this service type is a @command{syncthing-configuration}.
- Here is how you would set it up with the default configuration:
- @lisp
- (service home-syncthing-service-type)
- @end lisp
- For a custom configuration, wrap you @code{syncthing-configuration} in
- @code{for-home}, as in this example:
- @lisp
- (service home-syncthing-service-type
- (for-home
- (syncthing-configuration (logflags 5))))
- @end lisp
- For details about @code{syncthing-configuration}, check out the
- documentation of the system service (@pxref{Networking Services,
- @code{syncthing-service-type}}).
- @end defvar
- @node Miscellaneous Home Services
- @subsection Miscellaneous Home Services
- This section lists Home services that lack a better place.
- @subsubheading Dictionary Service
- @cindex dictionary service, for Home
- The @code{(gnu home services dict)} module provides the following service:
- @defvar home-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}).
- 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 defvar
- This service is a direct mapping of the @code{dicod-service-type} system
- service (@pxref{Miscellaneous Services, Dictionary Service}). You can
- use it like this:
- @lisp
- (service home-dicod-service-type)
- @end lisp
- You may specify a custom configuration by providing a
- @code{dicod-configuration} record, exactly like for
- @code{dicod-service-type}, but wrapping it in @code{for-home}:
- @lisp
- (service home-dicod-service-type
- (for-home
- (dicod-configuration @dots{})))
- @end lisp
- @node Invoking guix home
- @section Invoking @command{guix home}
- @cindex @command{guix home}
- Once you have written a home environment declaration (@pxref{Declaring
- the Home Environment,,,,}, it can be @dfn{instantiated} using the
- @command{guix home} command. The synopsis is:
- @example
- guix home @var{options}@dots{} @var{action} @var{file}
- @end example
- @var{file} must be the name of a file containing a
- @code{home-environment} declaration. @var{action} specifies how the
- home environment is instantiated, but there are few auxiliary actions
- which don't instantiate it. Currently the following values are
- supported:
- @table @code
- @item search
- Display available home service type definitions that match the given
- regular expressions, sorted by relevance:
- @cindex shell
- @cindex shell-profile
- @cindex bash
- @cindex zsh
- @example
- $ guix home search shell
- name: home-shell-profile
- location: gnu/home/services/shells.scm:100:2
- extends: home-files
- description: Create `~/.profile', which is used for environment initialization of POSIX compliant login shells.
- + This service type can be extended with a list of file-like objects.
- relevance: 6
- name: home-fish
- location: gnu/home/services/shells.scm:640:2
- extends: home-files home-profile
- description: Install and configure Fish, the friendly interactive shell.
- relevance: 3
- name: home-zsh
- location: gnu/home/services/shells.scm:290:2
- extends: home-files home-profile
- description: Install and configure Zsh.
- relevance: 1
- name: home-bash
- location: gnu/home/services/shells.scm:508:2
- extends: home-files home-profile
- description: Install and configure GNU Bash.
- relevance: 1
- @dots{}
- @end example
- As for @command{guix search}, the result is written in
- @code{recutils} format, which makes it easy to filter the output
- (@pxref{Top, GNU recutils databases,, recutils, GNU recutils manual}).
- @cindex container, for @command{guix home}
- @item container
- Spawn a shell in an isolated environment---a
- @dfn{container}---containing your home as specified by @var{file}.
- For example, this is how you would start an interactive shell in a
- container with your home:
- @example
- guix home container config.scm
- @end example
- This is a throw-away container where you can lightheartedly fiddle with
- files; any changes made within the container, any process started---all
- this disappears as soon as you exit that shell.
- As with @command{guix shell}, several options control that container:
- @table @option
- @item --network
- @itemx -N
- Enable networking within the container (it is disabled by default).
- @item --expose=@var{source}[=@var{target}]
- @itemx --share=@var{source}[=@var{target}]
- As with @command{guix shell}, make directory @var{source} of the host
- system available as @var{target} inside the container---read-only if you
- pass @option{--expose}, and writable if you pass @option{--share}
- (@pxref{Invoking guix shell, @option{--expose} and @option{--share}}).
- @end table
- Additionally, you can run a command in that container, instead of
- spawning an interactive shell. For instance, here is how you would
- check which Shepherd services are started in a throw-away home
- container:
- @example
- guix home container config.scm -- herd status
- @end example
- The command to run in the container must come after @code{--} (double
- hyphen).
- @cindex service type definition, editing
- @cindex editing, service type definition
- @item edit
- Edit or view the definition of the given Home service types.
- For example, the command below opens your editor, as specified by the
- @env{EDITOR} environment variable, on the definition of the
- @code{home-mcron} service type:
- @example
- guix home edit home-mcron
- @end example
- @item reconfigure
- Build the home environment described in @var{file}, and switch to it.
- Switching means that the activation script will be evaluated and (in
- basic scenario) symlinks to configuration files generated from
- @code{home-environment} declaration will be created in @file{~}. If the
- file with the same path already exists in home folder it will be moved
- to @file{~/@var{timestamp}-guix-home-legacy-configs-backup}, where @var{timestamp}
- is a current UNIX epoch time.
- @quotation Note
- It is highly recommended to run @command{guix pull} once before you run
- @command{guix home reconfigure} for the first time (@pxref{Invoking guix
- pull}).
- @end quotation
- This effects all the configuration specified in @var{file}. The command
- starts Shepherd services specified in @var{file} that are not currently
- running; if a service is currently running, this command will arrange
- for it to be upgraded the next time it is stopped (e.g.@: by @code{herd
- stop @var{service}} or @code{herd restart @var{service}}).
- This command creates a new generation whose number is one greater than
- the current generation (as reported by @command{guix home
- list-generations}). If that generation already exists, it will be
- overwritten. This behavior mirrors that of @command{guix package}
- (@pxref{Invoking guix package}).
- @cindex provenance tracking, of the home environment
- Upon completion, the new home is deployed under @file{~/.guix-home}.
- This directory contains @dfn{provenance meta-data}: the list of channels
- in use (@pxref{Channels}) and @var{file} itself, when available. You
- can view the provenance information by running:
- @example
- guix home describe
- @end example
- This information is useful should you later want to inspect how this
- particular generation was built. In fact, assuming @var{file} is
- self-contained, you can later rebuild generation @var{n} of your
- home environment with:
- @example
- guix time-machine \
- -C /var/guix/profiles/per-user/@var{USER}/guix-home-@var{n}-link/channels.scm -- \
- home reconfigure \
- /var/guix/profiles/per-user/@var{USER}/guix-home-@var{n}-link/configuration.scm
- @end example
- You can think of it as some sort of built-in version control! Your
- home is not just a binary artifact: @emph{it carries its own source}.
- @c @xref{Service Reference, @code{provenance-service-type}}, for more
- @c information on provenance tracking.
- @c @footnote{This action (and the related actions
- @c @code{switch-generation} and @code{roll-back}) are usable after the
- @c home environment is initialized.}.
- @item switch-generation
- @cindex home generations
- Switch to an existing home generation. This action atomically switches
- the home profile to the specified home generation.
- The target generation can be specified explicitly by its generation
- number. For example, the following invocation would switch to home
- generation 7:
- @example
- guix home switch-generation 7
- @end example
- The target generation can also be specified relative to the current
- generation with the form @code{+N} or @code{-N}, where @code{+3} means
- ``3 generations ahead of the current generation,'' and @code{-1} means
- ``1 generation prior to the current generation.'' When specifying a
- negative value such as @code{-1}, you must precede it with @code{--} to
- prevent it from being parsed as an option. For example:
- @example
- guix home switch-generation -- -1
- @end example
- This action will fail if the specified generation does not exist.
- @item roll-back
- @cindex rolling back
- Switch to the preceding home generation. This is the inverse
- of @command{reconfigure}, and it is exactly the same as invoking
- @command{switch-generation} with an argument of @code{-1}.
- @item delete-generations
- @cindex deleting home generations
- @cindex saving space
- Delete home generations, making them candidates for garbage collection
- (@pxref{Invoking guix gc}, for information on how to run the ``garbage
- collector'').
- This works in the same way as @samp{guix package --delete-generations}
- (@pxref{Invoking guix package, @option{--delete-generations}}). With no
- arguments, all home generations but the current one are deleted:
- @example
- guix home delete-generations
- @end example
- You can also select the generations you want to delete. The example below
- deletes all the home generations that are more than two months old:
- @example
- guix home delete-generations 2m
- @end example
- @item build
- Build the derivation of the home environment, which includes all the
- configuration files and programs needed. This action does not actually
- install anything.
- @item describe
- Describe the current home generation: its file name, as well as
- provenance information when available.
- To show installed packages in the current home generation's profile, the
- @code{--list-installed} flag is provided, with the same syntax that is
- used in @command{guix package --list-installed} (@pxref{Invoking guix
- package}). For instance, the following command shows a table of all the
- packages with ``emacs'' in their name that are installed in the current
- home generation's profile:
- @example
- guix home describe --list-installed=emacs
- @end example
- @item list-generations
- List a summary of each generation of the home environment available on
- disk, in a human-readable way. This is similar to the
- @option{--list-generations} option of @command{guix package}
- (@pxref{Invoking guix package}).
- Optionally, one can specify a pattern, with the same syntax that is used
- in @command{guix package --list-generations}, to restrict the list of
- generations displayed. For instance, the following command displays
- generations that are up to 10 days old:
- @example
- guix home list-generations 10d
- @end example
- The @code{--list-installed} flag may also be specified, with the same
- syntax that is used in @command{guix home describe}. This may be
- helpful if trying to determine when a package was added to the home
- profile.
- @item import
- Generate a @dfn{home environment} from the packages in the default
- profile and configuration files found in the user's home directory. The
- configuration files will be copied to the specified directory, and a
- @file{home-configuration.scm} will be populated with the home
- environment. Note that not every home service that exists is supported
- (@pxref{Home Services}).
- @example
- $ guix home import ~/guix-config
- guix home: '/home/alice/guix-config' populated with all the Home configuration files
- @end example
- @end table
- And there's more! @command{guix home} also provides the following
- sub-commands to visualize how the services of your home environment
- relate to one another:
- @table @code
- @cindex service extension graph, of a home environment
- @item extension-graph
- Emit to standard output the @dfn{service extension graph} of the home
- environment defined in @var{file} (@pxref{Service Composition}, for more
- information on service extensions). By default the output is in
- Dot/Graphviz format, but you can choose a different format with
- @option{--graph-backend}, as with @command{guix graph} (@pxref{Invoking
- guix graph, @option{--backend}}):
- The command:
- @example
- guix home extension-graph @var{file} | xdot -
- @end example
- shows the extension relations among services.
- @cindex Shepherd dependency graph, for a home environment
- @item shepherd-graph
- Emit to standard output the @dfn{dependency graph} of shepherd services
- of the home environment defined in @var{file}. @xref{Shepherd
- Services}, for more information and for an example graph.
- Again, the default output format is Dot/Graphviz, but you can pass
- @option{--graph-backend} to select a different one.
- @end table
- @var{options} can contain any of the common build options (@pxref{Common
- Build Options}). In addition, @var{options} can contain one of the
- following:
- @table @option
- @item --expression=@var{expr}
- @itemx -e @var{expr}
- Consider the home-environment @var{expr} evaluates to.
- This is an alternative to specifying a file which evaluates to a home
- environment.
- @item --allow-downgrades
- Instruct @command{guix home reconfigure} to allow system downgrades.
- Just like @command{guix system}, @command{guix home reconfigure}, by
- default, prevents you from downgrading your home to older or unrelated
- revisions compared to the channel revisions that were used to deploy
- it---those shown by @command{guix home describe}. Using
- @option{--allow-downgrades} allows you to bypass that check, at the risk
- of downgrading your home---be careful!
- @end table
- @node Documentation
- @chapter Documentation
- @cindex documentation, searching for
- @cindex searching for documentation
- @cindex Info, documentation format
- @cindex man pages
- @cindex manual pages
- In most cases packages installed with Guix come with documentation.
- There are two main documentation formats: ``Info'', a browsable
- hypertext format used for GNU software, and ``manual pages'' (or ``man
- pages''), the linear documentation format traditionally found on Unix.
- Info manuals are accessed with the @command{info} command or with Emacs,
- and man pages are accessed using @command{man}.
- You can look for documentation of software installed on your system by
- keyword. For example, the following command searches for information
- about ``TLS'' in Info manuals:
- @example
- $ info -k TLS
- "(emacs)Network Security" -- STARTTLS
- "(emacs)Network Security" -- TLS
- "(gnutls)Core TLS API" -- gnutls_certificate_set_verify_flags
- "(gnutls)Core TLS API" -- gnutls_certificate_set_verify_function
- @dots{}
- @end example
- @noindent
- The command below searches for the same keyword in man
- pages@footnote{The database searched by @command{man -k} is only created
- in profiles that contain the @code{man-db} package.}:
- @example
- $ man -k TLS
- SSL (7) - OpenSSL SSL/TLS library
- certtool (1) - GnuTLS certificate tool
- @dots {}
- @end example
- These searches are purely local to your computer so you have the
- guarantee that documentation you find corresponds to what you have
- actually installed, you can access it off-line, and your privacy is
- respected.
- Once you have these results, you can view the relevant documentation by
- running, say:
- @example
- $ info "(gnutls)Core TLS API"
- @end example
- @noindent
- or:
- @example
- $ man certtool
- @end example
- Info manuals contain sections and indices as well as hyperlinks like
- those found in Web pages. The @command{info} reader (@pxref{Top, Info
- reader,, info-stnd, Stand-alone GNU Info}) and its Emacs counterpart
- (@pxref{Misc Help,,, emacs, The GNU Emacs Manual}) provide intuitive key
- bindings to navigate manuals. @xref{Getting Started,,, info, Info: An
- Introduction}, for an introduction to Info navigation.
- @node Platforms
- @chapter Platforms
- The packages and systems built by Guix are intended, like most computer
- programs, to run on a CPU with a specific instruction set, and under a
- specific operating system. Those programs are often also targeting a
- specific kernel and system library. Those constraints are captured by
- Guix in @code{platform} records.
- @menu
- * platform Reference:: Detail of platform declarations.
- * Supported Platforms:: Description of the supported platforms.
- @end menu
- @node platform Reference
- @section @code{platform} Reference
- The @code{platform} data type describes a @dfn{platform}: an
- @acronym{ISA, instruction set architecture}, combined with an operating
- system and possibly additional system-wide settings such as the
- @acronym{ABI, application binary interface}.
- @deftp {Data Type} platform
- This is the data type representing a platform.
- @table @asis
- @item @code{target}
- This field specifies the platform's GNU triplet as a string
- (@pxref{Specifying Target Triplets, GNU configuration triplets,,
- autoconf, Autoconf}).
- @item @code{system}
- This string is the system type as it is known to Guix and passed,
- for instance, to the @option{--system} option of most commands.
- It usually has the form @code{"@var{cpu}-@var{kernel}"}, where
- @var{cpu} is the target CPU and @var{kernel} the target operating
- system kernel.
- It can be for instance @code{"aarch64-linux"} or @code{"armhf-linux"}.
- You will encounter system types when you perform native builds
- (@pxref{Native Builds}).
- @item @code{linux-architecture} (default: @code{#false})
- This optional string field is only relevant if the kernel is Linux. In
- that case, it corresponds to the ARCH variable used when building Linux,
- @code{"mips"} for instance.
- @item @code{glibc-dynamic-linker}
- This field is the name of the GNU C Library dynamic linker for the
- corresponding system, as a string. It can be
- @code{"/lib/ld-linux-armhf.so.3"}.
- @end table
- @end deftp
- @node Supported Platforms
- @section Supported Platforms
- The @code{(guix platforms @dots{})} modules export the following
- variables, each of which is bound to a @code{platform} record.
- @defvar armv7-linux
- Platform targeting ARM v7 CPU running GNU/Linux.
- @end defvar
- @defvar aarch64-linux
- Platform targeting ARM v8 CPU running GNU/Linux.
- @end defvar
- @defvar mips64-linux
- Platform targeting MIPS little-endian 64-bit CPU running GNU/Linux.
- @end defvar
- @defvar powerpc-linux
- Platform targeting PowerPC big-endian 32-bit CPU running GNU/Linux.
- @end defvar
- @defvar powerpc64le-linux
- Platform targeting PowerPC little-endian 64-bit CPU running GNU/Linux.
- @end defvar
- @defvar riscv64-linux
- Platform targeting RISC-V 64-bit CPU running GNU/Linux.
- @end defvar
- @defvar i686-linux
- Platform targeting x86 CPU running GNU/Linux.
- @end defvar
- @defvar x86_64-linux
- Platform targeting x86 64-bit CPU running GNU/Linux.
- @end defvar
- @defvar i686-mingw
- Platform targeting x86 CPU running Windows, with run-time support from
- MinGW.
- @end defvar
- @defvar x86_64-mingw
- Platform targeting x86 64-bit CPU running Windows, with run-time support
- from MinGW.
- @end defvar
- @defvar i586-gnu
- Platform targeting x86 CPU running GNU/Hurd (also referred to as
- ``GNU'').
- @end defvar
- @node System Images
- @chapter Creating System Images
- @cindex system images
- When it comes to installing Guix System for the first time on a new
- machine, you can basically proceed in three different ways. The first
- one is to use an existing operating system on the machine to run the
- @command{guix system init} command (@pxref{Invoking guix system}). The
- second one, is to produce an installation image (@pxref{Building the
- Installation Image}). This is a bootable system which role is to
- eventually run @command{guix system init}. Finally, the third option
- would be to produce an image that is a direct instantiation of the
- system you wish to run. That image can then be copied on a bootable
- device such as an USB drive or a memory card. The target machine would
- then directly boot from it, without any kind of installation procedure.
- The @command{guix system image} command is able to turn an operating
- system definition into a bootable image. This command supports
- different image types, such as @code{mbr-raw}, @code{iso9660} and
- @code{docker}. Any modern @code{x86_64} machine will probably be able
- to boot from an @code{iso9660} image. However, there are a few machines
- out there that require specific image types. Those machines, in general
- using @code{ARM} processors, may expect specific partitions at specific
- offsets.
- This chapter explains how to define customized system images and how to
- turn them into actual bootable images.
- @menu
- * image Reference:: Detail of image declarations.
- * Instantiate an Image:: How to instantiate an image record.
- * image-type Reference:: Detail of image types declaration.
- * Image Modules:: Definition of image modules.
- @end menu
- @node image Reference
- @section @code{image} Reference
- The @code{image} record, described right after, allows you to define a
- customized bootable system image.
- @deftp {Data Type} image
- This is the data type representing a system image.
- @table @asis
- @item @code{name} (default: @code{#false})
- The image name as a symbol, @code{'my-iso9660} for instance. The name
- is optional and it defaults to @code{#false}.
- @item @code{format}
- The image format as a symbol. The following formats are supported:
- @itemize
- @item @code{disk-image}, a raw disk image composed of one or multiple
- partitions.
- @item @code{compressed-qcow2}, a compressed qcow2 image composed of
- one or multiple partitions.
- @item @code{docker}, a Docker image.
- @item @code{iso9660}, an ISO-9660 image.
- @item @code{tarball}, a tar.gz image archive.
- @item @code{wsl2}, a WSL2 image.
- @end itemize
- @item @code{platform} (default: @code{#false})
- The @code{platform} record the image is targeting (@pxref{Platforms}),
- @code{aarch64-linux} for instance. By default, this field is set to
- @code{#false} and the image will target the host platform.
- @item @code{size} (default: @code{'guess})
- The image size in bytes or @code{'guess}. The @code{'guess} symbol,
- which is the default, means that the image size will be inferred based
- on the image content.
- @item @code{operating-system}
- The image's @code{operating-system} record that is instantiated.
- @item @code{partition-table-type} (default: @code{'mbr})
- The image partition table type as a symbol. Possible values are
- @code{'mbr} and @code{'gpt}. It default to @code{'mbr}.
- @item @code{partitions} (default: @code{'()})
- The image partitions as a list of @code{partition} records
- (@pxref{partition Reference}).
- @item @code{compression?} (default: @code{#true})
- Whether the image content should be compressed, as a boolean. It
- defaults to @code{#true} and only applies to @code{'iso9660} image
- formats.
- @item @code{volatile-root?} (default: @code{#true})
- Whether the image root partition should be made volatile, as a boolean.
- This is achieved by using a RAM backed file system (overlayfs) that is
- mounted on top of the root partition by the initrd. It defaults to
- @code{#true}. When set to @code{#false}, the image root partition is
- mounted as read-write partition by the initrd.
- @item @code{shared-store?} (default: @code{#false})
- Whether the image's store should be shared with the host system, as a
- boolean. This can be useful when creating images dedicated to virtual
- machines. When set to @code{#false}, which is the default, the image's
- @code{operating-system} closure is copied to the image. Otherwise, when
- set to @code{#true}, it is assumed that the host store will be made
- available at boot, using a @code{9p} mount for instance.
- @item @code{shared-network?} (default: @code{#false})
- Whether to use the host network interfaces within the image, as a
- boolean. This is only used for the @code{'docker} image format. It
- defaults to @code{#false}.
- @item @code{substitutable?} (default: @code{#true})
- Whether the image derivation should be substitutable, as a boolean. It
- defaults to @code{true}.
- @end table
- @end deftp
- @menu
- * partition Reference::
- @end menu
- @node partition Reference
- @subsection @code{partition} Reference
- In @code{image} record may contain some partitions.
- @deftp {Data Type} partition
- This is the data type representing an image partition.
- @table @asis
- @item @code{size} (default: @code{'guess})
- The partition size in bytes or @code{'guess}. The @code{'guess} symbol,
- which is the default, means that the partition size will be inferred
- based on the partition content.
- @item @code{offset} (default: @code{0})
- The partition's start offset in bytes, relative to the image start or
- the previous partition end. It defaults to @code{0} which means that
- there is no offset applied.
- @item @code{file-system} (default: @code{"ext4"})
- The partition file system as a string, defaulting to @code{"ext4"}. The
- supported values are @code{"vfat"}, @code{"fat16"}, @code{"fat32"} and
- @code{"ext4"}.
- @item @code{file-system-options} (default: @code{'()})
- The partition file system creation options that should be passed to the
- partition creation tool, as a list of strings. This is only supported
- when creating @code{"ext4"} partitions.
- See the @code{"extended-options"} man page section of the
- @code{"mke2fs"} tool for a more complete reference.
- @item @code{label}
- The partition label as a mandatory string, @code{"my-root"} for
- instance.
- @item @code{uuid} (default: @code{#false})
- The partition UUID as an @code{uuid} record (@pxref{File Systems}). By
- default it is @code{#false}, which means that the partition creation
- tool will attribute a random UUID to the partition.
- @item @code{flags} (default: @code{'()})
- The partition flags as a list of symbols. Possible values are
- @code{'boot} and @code{'esp}. The @code{'boot} flags should be set if
- you want to boot from this partition. Exactly one partition should have
- this flag set, usually the root one. The @code{'esp} flag identifies a
- UEFI System Partition.
- @item @code{initializer} (default: @code{#false})
- The partition initializer procedure as a gexp. This procedure is called
- to populate a partition. If no initializer is passed, the
- @code{initialize-root-partition} procedure from the @code{(gnu build
- image)} module is used.
- @end table
- @end deftp
- @node Instantiate an Image
- @section Instantiate an Image
- Let's say you would like to create an MBR image with three distinct
- partitions:
- @itemize
- @item The @acronym{ESP, EFI System Partition}, a partition of
- 40@tie{}MiB at offset 1024@tie{}KiB with a vfat file system.
- @item an ext4 partition of 50@tie{}MiB data file, and labeled ``data''.
- @item an ext4 bootable partition containing the @code{%simple-os}
- operating-system.
- @end itemize
- You would then write the following image definition in a
- @code{my-image.scm} file for instance.
- @lisp
- (use-modules (gnu)
- (gnu image)
- (gnu tests)
- (gnu system image)
- (guix gexp))
- (define MiB (expt 2 20))
- (image
- (format 'disk-image)
- (operating-system %simple-os)
- (partitions
- (list
- (partition
- (size (* 40 MiB))
- (offset (* 1024 1024))
- (label "GNU-ESP")
- (file-system "vfat")
- (flags '(esp))
- (initializer (gexp initialize-efi-partition)))
- (partition
- (size (* 50 MiB))
- (label "DATA")
- (file-system "ext4")
- (initializer #~(lambda* (root . rest)
- (mkdir root)
- (call-with-output-file
- (string-append root "/data")
- (lambda (port)
- (format port "my-data"))))))
- (partition
- (size 'guess)
- (label root-label)
- (file-system "ext4")
- (flags '(boot))
- (initializer (gexp initialize-root-partition))))))
- @end lisp
- Note that the first and third partitions use generic initializers
- procedures, initialize-efi-partition and initialize-root-partition
- respectively. The initialize-efi-partition installs a GRUB EFI loader
- that is loading the GRUB bootloader located in the root partition. The
- initialize-root-partition instantiates a complete system as defined by
- the @code{%simple-os} operating-system.
- You can now run:
- @example
- guix system image my-image.scm
- @end example
- to instantiate the @code{image} definition. That produces a disk image
- which has the expected structure:
- @example
- $ parted $(guix system image my-image.scm) print
- @dots{}
- Model: (file)
- Disk /gnu/store/yhylv1bp5b2ypb97pd3bbhz6jk5nbhxw-disk-image: 1714MB
- Sector size (logical/physical): 512B/512B
- Partition Table: msdos
- Disk Flags:
- Number Start End Size Type File system Flags
- 1 1049kB 43.0MB 41.9MB primary fat16 esp
- 2 43.0MB 95.4MB 52.4MB primary ext4
- 3 95.4MB 1714MB 1619MB primary ext4 boot
- @end example
- The size of the @code{boot} partition has been inferred to @code{1619MB}
- so that it is large enough to host the @code{%simple-os}
- operating-system.
- You can also use existing @code{image} record definitions and inherit
- from them to simplify the @code{image} definition. The @code{(gnu
- system image)} module provides the following @code{image} definition
- variables.
- @defvar efi-disk-image
- A MBR disk-image composed of two partitions: a 64 bits ESP partition and
- a ROOT boot partition. This image can be used on most @code{x86_64} and
- @code{i686} machines, supporting BIOS or UEFI booting.
- @end defvar
- @defvar efi32-disk-image
- Same as @code{efi-disk-image} but with a 32 bits EFI partition.
- @end defvar
- @defvar iso9660-image
- An ISO-9660 image composed of a single bootable partition. This image
- can also be used on most @code{x86_64} and @code{i686} machines.
- @end defvar
- @defvar docker-image
- A Docker image that can be used to spawn a Docker container.
- @end defvar
- Using the @code{efi-disk-image} we can simplify our previous
- @code{image} declaration this way:
- @lisp
- (use-modules (gnu)
- (gnu image)
- (gnu tests)
- (gnu system image)
- (guix gexp)
- (ice-9 match))
- (define MiB (expt 2 20))
- (define data
- (partition
- (size (* 50 MiB))
- (label "DATA")
- (file-system "ext4")
- (initializer #~(lambda* (root . rest)
- (mkdir root)
- (call-with-output-file
- (string-append root "/data")
- (lambda (port)
- (format port "my-data")))))))
- (image
- (inherit efi-disk-image)
- (operating-system %simple-os)
- (partitions
- (match (image-partitions efi-disk-image)
- ((esp root)
- (list esp data root)))))
- @end lisp
- This will give the exact same @code{image} instantiation but the
- @code{image} declaration is simpler.
- @node image-type Reference
- @section image-type Reference
- The @command{guix system image} command can, as we saw above, take a
- file containing an @code{image} declaration as argument and produce an
- actual disk image from it. The same command can also handle a file
- containing an @code{operating-system} declaration as argument. In that
- case, how is the @code{operating-system} turned into an image?
- That's where the @code{image-type} record intervenes. This record
- defines how to transform an @code{operating-system} record into an
- @code{image} record.
- @deftp {Data Type} image-type
- This is the data type representing an image-type.
- @table @asis
- @item @code{name}
- The image-type name as a mandatory symbol, @code{'efi32-raw} for
- instance.
- @item @code{constructor}
- The image-type constructor, as a mandatory procedure that takes an
- @code{operating-system} record as argument and returns an @code{image}
- record.
- @end table
- @end deftp
- There are several @code{image-type} records provided by the @code{(gnu
- system image)} and the @code{(gnu system images @dots{})} modules.
- @defvar mbr-raw-image-type
- Build an image based on the @code{mbr-disk-image} image.
- @end defvar
- @defvar efi-raw-image-type
- Build an image based on the @code{efi-disk-image} image.
- @end defvar
- @defvar efi32-raw-image-type
- Build an image based on the @code{efi32-disk-image} image.
- @end defvar
- @defvar qcow2-image-type
- Build an image based on the @code{mbr-disk-image} image but with the
- @code{compressed-qcow2} image format.
- @end defvar
- @defvar iso-image-type
- Build a compressed image based on the @code{iso9660-image} image.
- @end defvar
- @defvar uncompressed-iso-image-type
- Build an image based on the @code{iso9660-image} image but with the
- @code{compression?} field set to @code{#false}.
- @end defvar
- @defvar docker-image-type
- Build an image based on the @code{docker-image} image.
- @end defvar
- @defvar raw-with-offset-image-type
- Build an MBR image with a single partition starting at a @code{1024KiB}
- offset. This is useful to leave some room to install a bootloader in
- the post-MBR gap.
- @end defvar
- @defvar pinebook-pro-image-type
- Build an image that is targeting the Pinebook Pro machine. The MBR
- image contains a single partition starting at a @code{9MiB} offset. The
- @code{u-boot-pinebook-pro-rk3399-bootloader} bootloader will be
- installed in this gap.
- @end defvar
- @defvar rock64-image-type
- Build an image that is targeting the Rock64 machine. The MBR image
- contains a single partition starting at a @code{16MiB} offset. The
- @code{u-boot-rock64-rk3328-bootloader} bootloader will be installed in
- this gap.
- @end defvar
- @defvar novena-image-type
- Build an image that is targeting the Novena machine. It has the same
- characteristics as @code{raw-with-offset-image-type}.
- @end defvar
- @defvar pine64-image-type
- Build an image that is targeting the Pine64 machine. It has the same
- characteristics as @code{raw-with-offset-image-type}.
- @end defvar
- @defvar hurd-image-type
- Build an image that is targeting a @code{i386} machine running the Hurd
- kernel. The MBR image contains a single ext2 partitions with specific
- @code{file-system-options} flags.
- @end defvar
- @defvar hurd-qcow2-image-type
- Build an image similar to the one built by the @code{hurd-image-type}
- but with the @code{format} set to @code{'compressed-qcow2}.
- @end defvar
- @defvar wsl2-image-type
- Build an image for the @acronym{WSL2, Windows Subsystem for Linux 2}.
- It can be imported by running:
- @example
- wsl --import Guix ./guix ./wsl2-image.tar.gz
- wsl -d Guix
- @end example
- @end defvar
- So, if we get back to the @code{guix system image} command taking an
- @code{operating-system} declaration as argument. By default, the
- @code{mbr-raw-image-type} is used to turn the provided
- @code{operating-system} into an actual bootable image.
- To use a different @code{image-type}, the @code{--image-type} option can
- be used. The @code{--list-image-types} option will list all the
- supported image types. It turns out to be a textual listing of all the
- @code{image-types} variables described just above (@pxref{Invoking guix
- system}).
- @node Image Modules
- @section Image Modules
- Let's take the example of the Pine64, an ARM based machine. To be able
- to produce an image targeting this board, we need the following
- elements:
- @itemize
- @item An @code{operating-system} record containing at least
- an appropriate kernel (@code{linux-libre-arm64-generic}) and bootloader
- @code{u-boot-pine64-lts-bootloader}) for the Pine64.
- @item Possibly, an @code{image-type} record providing a way to
- turn an @code{operating-system} record to an @code{image} record
- suitable for the Pine64.
- @item An actual @code{image} that can be instantiated with the
- @command{guix system image} command.
- @end itemize
- The @code{(gnu system images pine64)} module provides all those
- elements: @code{pine64-barebones-os}, @code{pine64-image-type} and
- @code{pine64-barebones-raw-image} respectively.
- The module returns the @code{pine64-barebones-raw-image} in order for
- users to be able to run:
- @example
- guix system image gnu/system/images/pine64.scm
- @end example
- Now, thanks to the @code{pine64-image-type} record declaring the
- @code{'pine64-raw} @code{image-type}, one could also prepare a
- @code{my-pine.scm} file with the following content:
- @lisp
- (use-modules (gnu system images pine64))
- (operating-system
- (inherit pine64-barebones-os)
- (timezone "Europe/Athens"))
- @end lisp
- to customize the @code{pine64-barebones-os}, and run:
- @example
- $ guix system image --image-type=pine64-raw my-pine.scm
- @end example
- Note that there are other modules in the @code{gnu/system/images}
- directory targeting @code{Novena}, @code{Pine64}, @code{PinebookPro} and
- @code{Rock64} machines.
- @node Installing Debugging Files
- @chapter Installing Debugging Files
- @cindex debugging files
- Program binaries, as produced by the GCC compilers for instance, are
- typically written in the ELF format, with a section containing
- @dfn{debugging information}. Debugging information is what allows the
- debugger, GDB, to map binary code to source code; it is required to
- debug a compiled program in good conditions.
- This chapter explains how to use separate debug info when packages
- provide it, and how to rebuild packages with debug info when it's
- missing.
- @menu
- * Separate Debug Info:: Installing 'debug' outputs.
- * Rebuilding Debug Info:: Building missing debug info.
- @end menu
- @node Separate Debug Info
- @section Separate Debug Info
- The problem with debugging information is that is takes up a fair amount
- of disk space. For example, debugging information for the GNU C Library
- weighs in at more than 60 MiB@. Thus, as a user, keeping all the
- debugging info of all the installed programs is usually not an option.
- Yet, space savings should not come at the cost of an impediment to
- debugging---especially in the GNU system, which should make it easier
- for users to exert their computing freedom (@pxref{GNU Distribution}).
- Thankfully, the GNU Binary Utilities (Binutils) and GDB provide a
- mechanism that allows users to get the best of both worlds: debugging
- information can be stripped from the binaries and stored in separate
- files. GDB is then able to load debugging information from those files,
- when they are available (@pxref{Separate Debug Files,,, gdb, Debugging
- with GDB}).
- The GNU distribution takes advantage of this by storing debugging
- information in the @code{lib/debug} sub-directory of a separate package
- output unimaginatively called @code{debug} (@pxref{Packages with
- Multiple Outputs}). Users can choose to install the @code{debug} output
- of a package when they need it. For instance, the following command
- installs the debugging information for the GNU C Library and for GNU
- Guile:
- @example
- guix install glibc:debug guile:debug
- @end example
- GDB must then be told to look for debug files in the user's profile, by
- setting the @code{debug-file-directory} variable (consider setting it
- from the @file{~/.gdbinit} file, @pxref{Startup,,, gdb, Debugging with
- GDB}):
- @example
- (gdb) set debug-file-directory ~/.guix-profile/lib/debug
- @end example
- From there on, GDB will pick up debugging information from the
- @file{.debug} files under @file{~/.guix-profile/lib/debug}.
- Below is an alternative GDB script which is useful when working with
- other profiles. It takes advantage of the optional Guile integration in
- GDB. This snippet is included by default on Guix System in the
- @file{~/.gdbinit} file.
- @example
- guile
- (use-modules (gdb))
- (execute (string-append "set debug-file-directory "
- (or (getenv "GDB_DEBUG_FILE_DIRECTORY")
- "~/.guix-profile/lib/debug")))
- end
- @end example
- In addition, you will most likely want GDB to be able to show the source
- code being debugged. To do that, you will have to unpack the source
- code of the package of interest (obtained with @code{guix build
- --source}, @pxref{Invoking guix build}), and to point GDB to that source
- directory using the @code{directory} command (@pxref{Source Path,
- @code{directory},, gdb, Debugging with GDB}).
- @c XXX: keep me up-to-date
- The @code{debug} output mechanism in Guix is implemented by the
- @code{gnu-build-system} (@pxref{Build Systems}). Currently, it is
- opt-in---debugging information is available only for the packages with
- definitions explicitly declaring a @code{debug} output. To check
- whether a package has a @code{debug} output, use @command{guix package
- --list-available} (@pxref{Invoking guix package}).
- Read on for how to deal with packages lacking a @code{debug} output.
- @node Rebuilding Debug Info
- @section Rebuilding Debug Info
- @cindex debugging info, rebuilding
- As we saw above, some packages, but not all, provide debugging info in a
- @code{debug} output. What can you do when debugging info is missing?
- The @option{--with-debug-info} option provides a solution to that: it
- allows you to rebuild the package(s) for which debugging info is
- missing---and only those---and to graft those onto the application
- you're debugging. Thus, while it's not as fast as installing a
- @code{debug} output, it is relatively inexpensive.
- Let's illustrate that. Suppose you're experiencing a bug in Inkscape
- and would like to see what's going on in GLib, a library that's deep
- down in its dependency graph. As it turns out, GLib does not have a
- @code{debug} output and the backtrace GDB shows is all sadness:
- @example
- (gdb) bt
- #0 0x00007ffff5f92190 in g_getenv ()
- from /gnu/store/@dots{}-glib-2.62.6/lib/libglib-2.0.so.0
- #1 0x00007ffff608a7d6 in gobject_init_ctor ()
- from /gnu/store/@dots{}-glib-2.62.6/lib/libgobject-2.0.so.0
- #2 0x00007ffff7fe275a in call_init (l=<optimized out>, argc=argc@@entry=1, argv=argv@@entry=0x7fffffffcfd8,
- env=env@@entry=0x7fffffffcfe8) at dl-init.c:72
- #3 0x00007ffff7fe2866 in call_init (env=0x7fffffffcfe8, argv=0x7fffffffcfd8, argc=1, l=<optimized out>)
- at dl-init.c:118
- @end example
- To address that, you install Inkscape linked against a variant GLib that
- contains debug info:
- @example
- guix install inkscape --with-debug-info=glib
- @end example
- This time, debugging will be a whole lot nicer:
- @example
- $ gdb --args sh -c 'exec inkscape'
- @dots{}
- (gdb) b g_getenv
- Function "g_getenv" not defined.
- Make breakpoint pending on future shared library load? (y or [n]) y
- Breakpoint 1 (g_getenv) pending.
- (gdb) r
- Starting program: /gnu/store/@dots{}-profile/bin/sh -c exec\ inkscape
- @dots{}
- (gdb) bt
- #0 g_getenv (variable=variable@@entry=0x7ffff60c7a2e "GOBJECT_DEBUG") at ../glib-2.62.6/glib/genviron.c:252
- #1 0x00007ffff608a7d6 in gobject_init () at ../glib-2.62.6/gobject/gtype.c:4380
- #2 gobject_init_ctor () at ../glib-2.62.6/gobject/gtype.c:4493
- #3 0x00007ffff7fe275a in call_init (l=<optimized out>, argc=argc@@entry=3, argv=argv@@entry=0x7fffffffd088,
- env=env@@entry=0x7fffffffd0a8) at dl-init.c:72
- @dots{}
- @end example
- Much better!
- Note that there can be packages for which @option{--with-debug-info}
- will not have the desired effect. @xref{Package Transformation Options,
- @option{--with-debug-info}}, for more information.
- @node Using TeX and LaTeX
- @chapter Using @TeX{} and @LaTeX{}
- @cindex @TeX{} packages
- @cindex @LaTeX{} packages
- Guix provides packages for the @TeX{}, @LaTeX{}, ConTeXt, LuaTeX, and
- related typesetting systems, taken from the
- @uref{https://www.tug.org/texlive/, @TeX{} Live distribution}. However,
- because @TeX{} Live is so huge and because finding one's way in this
- maze is tricky, so this section provides some guidance on how to deploy
- the relevant packages to compile @TeX{} and @LaTeX{} documents.
- @TeX{} Live currently comes in two mutually exclusive flavors in Guix:
- @itemize
- @item
- The ``monolithic'' @code{texlive} package: it comes with @emph{every
- single @TeX{} Live package} (roughly 4,200), but it is huge---more than
- 4@tie{}GiB for a single package!
- @item
- A ``modular'' @TeX{} Live distribution, in which you only install the
- packages, always prefixed with @samp{texlive-}, you need.
- @end itemize
- So to insist, these two flavors cannot be combined@footnote{No rule
- without exception! As the monolithic @TeX{} Live does not contain the
- @command{biber} executable, it is okay to combine it with
- @code{texlive-biber}, which does.}. If in the modular setting your
- document does not compile, the solution is not to add the monolithic
- @code{texlive} package, but to add the set of missing packages from the
- modular distribution.
- Building a coherent system that provides all the essential tools and, at
- the same time, satisfies all of its internal dependencies can be
- a difficult task. It is therefore recommended to start with sets of
- packages, called @dfn{collections}, and @dfn{schemes}, the name for
- collections of collections. The following command lists available
- schemes and collections (@pxref{guix-search,, Invoking guix package}):
- @example
- guix search texlive-\(scheme\|collection\) | recsel -p name,description
- @end example
- If needed, you may then complete your system with individual packages,
- particularly when they belong to a large collection you're not otherwise
- interested in.
- For instance, the following manifest is a reasonable, yet frugal
- starting point for a French @LaTeX{} user:
- @lisp
- (specifications->manifest
- '("rubber"
- "texlive-scheme-basic"
- "texlive-collection-latexrecommended"
- "texlive-collection-fontsrecommended"
- "texlive-babel-french"
- ;; From "latexextra" collection.
- "texlive-tabularray"
- ;; From "binextra" collection.
- "texlive-texdoc"))
- @end lisp
- If you come across a document that does not compile in such a basic
- setting, the main difficulty is finding the missing packages. In this
- case, @command{pdflatex} and similar commands tend to fail with obscure
- error messages along the lines of:
- @example
- doc.tex: File `tikz.sty' not found.
- doc.tex:7: Emergency stop.
- @end example
- @noindent
- or, for a missing font:
- @example
- kpathsea: Running mktexmf phvr7t
- ! I can't find file `phvr7t'.
- @end example
- How do you determine what the missing package is? In the first case,
- you will find the answer by running:
- @example
- $ guix search texlive tikz
- name: texlive-pgf
- version: 59745
- @dots{}
- @end example
- In the second case, @command{guix search} turns up nothing. Instead,
- you can search the @TeX{} Live package database using the
- @command{tlmgr} command:
- @example
- $ tlmgr info phvr7t
- tlmgr: cannot find package phvr7t, searching for other matches:
- Packages containing `phvr7t' in their title/description:
- Packages containing files matching `phvr7t':
- helvetic:
- texmf-dist/fonts/tfm/adobe/helvetic/phvr7t.tfm
- texmf-dist/fonts/tfm/adobe/helvetic/phvr7tn.tfm
- texmf-dist/fonts/vf/adobe/helvetic/phvr7t.vf
- texmf-dist/fonts/vf/adobe/helvetic/phvr7tn.vf
- tex4ht:
- texmf-dist/tex4ht/ht-fonts/alias/adobe/helvetic/phvr7t.htf
- @end example
- @noindent
- The file is available in the @TeX{} Live @code{helvetic} package, which
- is known in Guix as @code{texlive-helvetic}. Quite a ride, but you
- found it!
- @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
- * Full-Source Bootstrap:: A Bootstrap worthy of GNU.
- * Preparing to Use the Bootstrap Binaries:: Building that what matters most.
- @end menu
- @node Full-Source Bootstrap
- @section The Full-Source 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
- @dfn{full-source bootstrap}. This bootstrap is rooted in
- @file{hex0-seed} from the @url{https://savannah.gnu.org/projects/stage0,
- Stage0} package. The hex0 program is minimalist assembler: it reads
- space-separated hexadecimal digits (nibbles) from a file, possibly
- including comments, and emits on standard output the bytes corresponding
- to those hexadecimal numbers. The source code of this initial hex0
- program is a file called
- @c XXX TODO: update to savannah url, once accepted there
- @url{https://github.com/oriansj/bootstrap-seeds/blob/master/POSIX/x86/hex0_x86.hex0,@file{hex0_x86.hex0}}
- and is written in the @code{hex0} language.
- Hex0 is self-hosting, which means that it can build itself:
- @example
- ./hex0-seed hex0_x86.hex0 hex0
- @end example
- Hex0 it is the ASCII-equivalent of the binary program and can be
- produced by doing something much like:
- @example
- sed 's/[;#].*$//g' hex0_x86.hex0 | xxd -r -p > hex0
- chmod +x hex0
- @end example
- It is because of this ASCII-binary equivalence that we can bless this
- initial 357-byte binary as source, and hence `full-source bootstrap''.
- The bootstrap then continues: @code{hex0} builds @code{hex1} and then on
- to @code{M0}, @code{hex2}, @code{M1}, @code{mescc-tools} and finally
- @code{M2-Planet}. Then, using @code{mescc-tools}, @code{M2-Planet} we
- build Mes (@pxref{Top, GNU Mes Reference Manual,, mes, GNU Mes}, a
- Scheme interpreter and C compiler in Scheme). From here on starts
- the more traditional @code{C}-based bootstrap of the GNU System.
- Another 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.
- 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-seeds|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}
- Work is ongoing to 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 Libera.Chat
- 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, it is first required to register a new platform as
- defined in the @code{(guix platform)} module. A platform is making the
- connection between a GNU triplet (@pxref{Specifying Target Triplets, GNU
- configuration triplets,, autoconf, Autoconf}), the equivalent
- @var{system} in Nix notation, the name of the
- @var{glibc-dynamic-linker}, and the corresponding Linux architecture
- name if applicable (@pxref{Platforms}).
- Once the bootstrap tarball 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:
|
