guix-cookbook.texi 160 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382138313841385138613871388138913901391139213931394139513961397139813991400140114021403140414051406140714081409141014111412141314141415141614171418141914201421142214231424142514261427142814291430143114321433143414351436143714381439144014411442144314441445144614471448144914501451145214531454145514561457145814591460146114621463146414651466146714681469147014711472147314741475147614771478147914801481148214831484148514861487148814891490149114921493149414951496149714981499150015011502150315041505150615071508150915101511151215131514151515161517151815191520152115221523152415251526152715281529153015311532153315341535153615371538153915401541154215431544154515461547154815491550155115521553155415551556155715581559156015611562156315641565156615671568156915701571157215731574157515761577157815791580158115821583158415851586158715881589159015911592159315941595159615971598159916001601160216031604160516061607160816091610161116121613161416151616161716181619162016211622162316241625162616271628162916301631163216331634163516361637163816391640164116421643164416451646164716481649165016511652165316541655165616571658165916601661166216631664166516661667166816691670167116721673167416751676167716781679168016811682168316841685168616871688168916901691169216931694169516961697169816991700170117021703170417051706170717081709171017111712171317141715171617171718171917201721172217231724172517261727172817291730173117321733173417351736173717381739174017411742174317441745174617471748174917501751175217531754175517561757175817591760176117621763176417651766176717681769177017711772177317741775177617771778177917801781178217831784178517861787178817891790179117921793179417951796179717981799180018011802180318041805180618071808180918101811181218131814181518161817181818191820182118221823182418251826182718281829183018311832183318341835183618371838183918401841184218431844184518461847184818491850185118521853185418551856185718581859186018611862186318641865186618671868186918701871187218731874187518761877187818791880188118821883188418851886188718881889189018911892189318941895189618971898189919001901190219031904190519061907190819091910191119121913191419151916191719181919192019211922192319241925192619271928192919301931193219331934193519361937193819391940194119421943194419451946194719481949195019511952195319541955195619571958195919601961196219631964196519661967196819691970197119721973197419751976197719781979198019811982198319841985198619871988198919901991199219931994199519961997199819992000200120022003200420052006200720082009201020112012201320142015201620172018201920202021202220232024202520262027202820292030203120322033203420352036203720382039204020412042204320442045204620472048204920502051205220532054205520562057205820592060206120622063206420652066206720682069207020712072207320742075207620772078207920802081208220832084208520862087208820892090209120922093209420952096209720982099210021012102210321042105210621072108210921102111211221132114211521162117211821192120212121222123212421252126212721282129213021312132213321342135213621372138213921402141214221432144214521462147214821492150215121522153215421552156215721582159216021612162216321642165216621672168216921702171217221732174217521762177217821792180218121822183218421852186218721882189219021912192219321942195219621972198219922002201220222032204220522062207220822092210221122122213221422152216221722182219222022212222222322242225222622272228222922302231223222332234223522362237223822392240224122422243224422452246224722482249225022512252225322542255225622572258225922602261226222632264226522662267226822692270227122722273227422752276227722782279228022812282228322842285228622872288228922902291229222932294229522962297229822992300230123022303230423052306230723082309231023112312231323142315231623172318231923202321232223232324232523262327232823292330233123322333233423352336233723382339234023412342234323442345234623472348234923502351235223532354235523562357235823592360236123622363236423652366236723682369237023712372237323742375237623772378237923802381238223832384238523862387238823892390239123922393239423952396239723982399240024012402240324042405240624072408240924102411241224132414241524162417241824192420242124222423242424252426242724282429243024312432243324342435243624372438243924402441244224432444244524462447244824492450245124522453245424552456245724582459246024612462246324642465246624672468246924702471247224732474247524762477247824792480248124822483248424852486248724882489249024912492249324942495249624972498249925002501250225032504250525062507250825092510251125122513251425152516251725182519252025212522252325242525252625272528252925302531253225332534253525362537253825392540254125422543254425452546254725482549255025512552255325542555255625572558255925602561256225632564256525662567256825692570257125722573257425752576257725782579258025812582258325842585258625872588258925902591259225932594259525962597259825992600260126022603260426052606260726082609261026112612261326142615261626172618261926202621262226232624262526262627262826292630263126322633263426352636263726382639264026412642264326442645264626472648264926502651265226532654265526562657265826592660266126622663266426652666266726682669267026712672267326742675267626772678267926802681268226832684268526862687268826892690269126922693269426952696269726982699270027012702270327042705270627072708270927102711271227132714271527162717271827192720272127222723272427252726272727282729273027312732273327342735273627372738273927402741274227432744274527462747274827492750275127522753275427552756275727582759276027612762276327642765276627672768276927702771277227732774277527762777277827792780278127822783278427852786278727882789279027912792279327942795279627972798279928002801280228032804280528062807280828092810281128122813281428152816281728182819282028212822282328242825282628272828282928302831283228332834283528362837283828392840284128422843284428452846284728482849285028512852285328542855285628572858285928602861286228632864286528662867286828692870287128722873287428752876287728782879288028812882288328842885288628872888288928902891289228932894289528962897289828992900290129022903290429052906290729082909291029112912291329142915291629172918291929202921292229232924292529262927292829292930293129322933293429352936293729382939294029412942294329442945294629472948294929502951295229532954295529562957295829592960296129622963296429652966296729682969297029712972297329742975297629772978297929802981298229832984298529862987298829892990299129922993299429952996299729982999300030013002300330043005300630073008300930103011301230133014301530163017301830193020302130223023302430253026302730283029303030313032303330343035303630373038303930403041304230433044304530463047304830493050305130523053305430553056305730583059306030613062306330643065306630673068306930703071307230733074307530763077307830793080308130823083308430853086308730883089309030913092309330943095309630973098309931003101310231033104310531063107310831093110311131123113311431153116311731183119312031213122312331243125312631273128312931303131313231333134313531363137313831393140314131423143314431453146314731483149315031513152315331543155315631573158315931603161316231633164316531663167316831693170317131723173317431753176317731783179318031813182318331843185318631873188318931903191319231933194319531963197319831993200320132023203320432053206320732083209321032113212321332143215321632173218321932203221322232233224322532263227322832293230323132323233323432353236323732383239324032413242324332443245324632473248324932503251325232533254325532563257325832593260326132623263326432653266326732683269327032713272327332743275327632773278327932803281328232833284328532863287328832893290329132923293329432953296329732983299330033013302330333043305330633073308330933103311331233133314331533163317331833193320332133223323332433253326332733283329333033313332333333343335333633373338333933403341334233433344334533463347334833493350335133523353335433553356335733583359336033613362336333643365336633673368336933703371337233733374337533763377337833793380338133823383338433853386338733883389339033913392339333943395339633973398339934003401340234033404340534063407340834093410341134123413341434153416341734183419342034213422342334243425342634273428342934303431343234333434343534363437343834393440344134423443344434453446344734483449345034513452345334543455345634573458345934603461346234633464346534663467346834693470347134723473347434753476347734783479348034813482348334843485348634873488348934903491349234933494349534963497349834993500350135023503350435053506350735083509351035113512351335143515351635173518351935203521352235233524352535263527352835293530353135323533353435353536353735383539354035413542354335443545354635473548354935503551355235533554355535563557355835593560356135623563356435653566356735683569357035713572357335743575357635773578357935803581358235833584358535863587358835893590359135923593359435953596359735983599360036013602360336043605360636073608360936103611361236133614361536163617361836193620362136223623362436253626362736283629363036313632363336343635363636373638363936403641364236433644364536463647364836493650365136523653365436553656365736583659366036613662366336643665366636673668366936703671367236733674367536763677367836793680368136823683368436853686368736883689369036913692369336943695369636973698369937003701370237033704370537063707370837093710371137123713371437153716371737183719372037213722372337243725372637273728372937303731373237333734373537363737373837393740374137423743374437453746374737483749375037513752375337543755375637573758375937603761376237633764376537663767376837693770377137723773377437753776377737783779378037813782378337843785378637873788378937903791379237933794379537963797379837993800380138023803380438053806380738083809381038113812381338143815381638173818381938203821382238233824382538263827382838293830383138323833383438353836383738383839384038413842384338443845384638473848384938503851385238533854385538563857385838593860386138623863386438653866386738683869387038713872387338743875387638773878387938803881388238833884388538863887388838893890389138923893389438953896389738983899390039013902390339043905390639073908390939103911391239133914391539163917391839193920392139223923392439253926392739283929393039313932393339343935393639373938393939403941394239433944394539463947394839493950395139523953395439553956395739583959396039613962396339643965396639673968396939703971397239733974397539763977397839793980398139823983398439853986398739883989399039913992399339943995399639973998399940004001400240034004400540064007400840094010401140124013401440154016401740184019402040214022402340244025402640274028402940304031403240334034403540364037403840394040404140424043404440454046404740484049405040514052405340544055405640574058405940604061406240634064406540664067406840694070407140724073407440754076407740784079408040814082408340844085408640874088408940904091409240934094409540964097409840994100410141024103410441054106410741084109411041114112411341144115411641174118411941204121412241234124412541264127412841294130413141324133413441354136413741384139414041414142414341444145414641474148414941504151415241534154415541564157415841594160416141624163416441654166416741684169417041714172417341744175417641774178417941804181418241834184418541864187418841894190419141924193419441954196419741984199420042014202420342044205420642074208420942104211421242134214421542164217421842194220422142224223422442254226422742284229423042314232423342344235423642374238423942404241424242434244424542464247424842494250425142524253425442554256425742584259426042614262426342644265426642674268426942704271427242734274427542764277427842794280428142824283428442854286428742884289429042914292429342944295429642974298429943004301430243034304430543064307430843094310431143124313431443154316431743184319432043214322432343244325432643274328432943304331433243334334433543364337433843394340434143424343434443454346434743484349435043514352435343544355435643574358435943604361436243634364436543664367436843694370437143724373437443754376437743784379438043814382438343844385438643874388438943904391439243934394439543964397439843994400440144024403440444054406440744084409441044114412441344144415441644174418441944204421442244234424442544264427442844294430443144324433443444354436443744384439444044414442444344444445444644474448444944504451445244534454445544564457445844594460446144624463446444654466446744684469447044714472447344744475447644774478447944804481448244834484448544864487448844894490449144924493449444954496449744984499450045014502450345044505450645074508450945104511451245134514451545164517451845194520452145224523452445254526452745284529453045314532453345344535453645374538453945404541454245434544454545464547454845494550455145524553455445554556455745584559456045614562456345644565456645674568456945704571457245734574457545764577457845794580458145824583458445854586458745884589459045914592459345944595459645974598459946004601460246034604460546064607460846094610461146124613461446154616461746184619462046214622462346244625462646274628462946304631463246334634463546364637463846394640464146424643
  1. \input texinfo
  2. @c -*-texinfo-*-
  3. @c %**start of header
  4. @setfilename guix-cookbook.info
  5. @documentencoding UTF-8
  6. @settitle GNU Guix Cookbook
  7. @c %**end of header
  8. @c Onion service for ci.guix.gnu.org.
  9. @set SUBSTITUTE-TOR-URL https://4zwzi66wwdaalbhgnix55ea3ab4pvvw66ll2ow53kjub6se4q2bclcyd.onion
  10. @copying
  11. Copyright @copyright{} 2019, 2022 Ricardo Wurmus@*
  12. Copyright @copyright{} 2019 Efraim Flashner@*
  13. Copyright @copyright{} 2019 Pierre Neidhardt@*
  14. Copyright @copyright{} 2020 Oleg Pykhalov@*
  15. Copyright @copyright{} 2020 Matthew Brooks@*
  16. Copyright @copyright{} 2020 Marcin Karpezo@*
  17. Copyright @copyright{} 2020 Brice Waegeneire@*
  18. Copyright @copyright{} 2020 André Batista@*
  19. Copyright @copyright{} 2020 Christine Lemmer-Webber@*
  20. Copyright @copyright{} 2021 Joshua Branson@*
  21. Copyright @copyright{} 2022, 2023 Maxim Cournoyer@*
  22. Copyright @copyright{} 2023 Ludovic Courtès
  23. Copyright @copyright{} 2023 Thomas Ieong
  24. Permission is granted to copy, distribute and/or modify this document
  25. under the terms of the GNU Free Documentation License, Version 1.3 or
  26. any later version published by the Free Software Foundation; with no
  27. Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
  28. copy of the license is included in the section entitled ``GNU Free
  29. Documentation License''.
  30. @end copying
  31. @dircategory System administration
  32. @direntry
  33. * Guix cookbook: (guix-cookbook). Tutorials and examples for GNU Guix.
  34. @end direntry
  35. @titlepage
  36. @title GNU Guix Cookbook
  37. @subtitle Tutorials and examples for using the GNU Guix Functional Package Manager
  38. @author The GNU Guix Developers
  39. @page
  40. @vskip 0pt plus 1filll
  41. @insertcopying
  42. @end titlepage
  43. @contents
  44. @c *********************************************************************
  45. @node Top
  46. @top GNU Guix Cookbook
  47. This document presents tutorials and detailed examples for GNU@tie{}Guix, a
  48. functional package management tool written for the GNU system. Please
  49. @pxref{Top,,, guix, GNU Guix reference manual} for details about the system,
  50. its API, and related concepts.
  51. @c TRANSLATORS: You can replace the following paragraph with information on
  52. @c how to join your own translation team and how to report issues with the
  53. @c translation.
  54. This manual is also available in French (@pxref{Top,,, guix-cookbook.fr,
  55. Livre de recettes de GNU Guix}), German (@pxref{Top,,,
  56. guix-cookbook.de, GNU-Guix-Kochbuch}) and Slovak (@pxref{Top,,,
  57. guix-cookbook.sk, Receptár GNU Guix}). If you would like to translate
  58. this document in your native language, consider joining
  59. @uref{https://translate.fedoraproject.org/projects/guix/documentation-cookbook,
  60. Weblate} (@pxref{Translating Guix,,, guix, GNU Guix reference
  61. manual}).
  62. @menu
  63. * Scheme tutorials:: Meet your new favorite language!
  64. * Packaging:: Packaging tutorials
  65. * System Configuration:: Customizing the GNU System
  66. * Containers:: Isolated environments and nested systems
  67. * Advanced package management:: Power to the users!
  68. * Environment management:: Control environment
  69. * Installing Guix on a Cluster:: High-performance computing.
  70. * Acknowledgments:: Thanks!
  71. * GNU Free Documentation License:: The license of this document.
  72. * Concept Index:: Concepts.
  73. @detailmenu
  74. --- The Detailed Node Listing ---
  75. Scheme tutorials
  76. * A Scheme Crash Course::
  77. Packaging
  78. * Packaging Tutorial:: A tutorial on how to add packages to Guix.
  79. Packaging Tutorial
  80. * A ``Hello World'' package::
  81. * Setup::
  82. * Extended example::
  83. * Other build systems::
  84. * Programmable and automated package definition::
  85. * Getting help::
  86. * Conclusion::
  87. * References::
  88. Setup
  89. * Local file::
  90. * Channels::
  91. * Direct checkout hacking::
  92. Programmable and automated package definition
  93. * Recursive importers::
  94. * Automatic update::
  95. * Inheritance::
  96. System Configuration
  97. * Auto-Login to a Specific TTY:: Automatically Login a User to a Specific TTY
  98. * Customizing the Kernel:: Creating and using a custom Linux kernel on Guix System.
  99. * Guix System Image API:: Customizing images to target specific platforms.
  100. * Using security keys:: How to use security keys with Guix System.
  101. * Dynamic DNS mcron job:: Job to update the IP address behind a DuckDNS host name.
  102. * Connecting to Wireguard VPN:: Connecting to a Wireguard VPN.
  103. * Customizing a Window Manager:: Handle customization of a Window manager on Guix System.
  104. * Running Guix on a Linode Server:: Running Guix on a Linode Server.
  105. * Running Guix on a Kimsufi Server:: Running Guix on a Kimsufi Server.
  106. * Setting up a bind mount:: Setting up a bind mount in the file-systems definition.
  107. * Getting substitutes from Tor:: Configuring Guix daemon to get substitutes through Tor.
  108. * Setting up NGINX with Lua:: Configuring NGINX web-server to load Lua modules.
  109. * Music Server with Bluetooth Audio:: Headless music player with Bluetooth output.
  110. Customizing a Window Manager
  111. * StumpWM::
  112. * Session lock::
  113. Session lock
  114. * Xorg::
  115. Containers
  116. * Guix Containers:: Perfectly isolated environments
  117. * Guix System Containers:: A system inside your system
  118. Guix System Containers
  119. * A Database Container::
  120. * Container Networking::
  121. Advanced package management
  122. * Guix Profiles in Practice:: Strategies for multiple profiles and manifests.
  123. Guix Profiles in Practice
  124. * Basic setup with manifests::
  125. * Required packages::
  126. * Default profile::
  127. * The benefits of manifests::
  128. * Reproducible profiles::
  129. Environment management
  130. * Guix environment via direnv:: Setup Guix environment with direnv
  131. Installing Guix on a Cluster
  132. * Setting Up a Head Node:: The node that runs the daemon.
  133. * Setting Up Compute Nodes:: Client nodes.
  134. * Cluster Network Access:: Dealing with network access restrictions.
  135. * Cluster Disk Usage:: Disk usage considerations.
  136. * Cluster Security Considerations:: Keeping the cluster secure.
  137. @end detailmenu
  138. @end menu
  139. @c *********************************************************************
  140. @node Scheme tutorials
  141. @chapter Scheme tutorials
  142. GNU@tie{}Guix is written in the general purpose programming language Scheme,
  143. and many of its features can be accessed and manipulated programmatically.
  144. You can use Scheme to generate package definitions, to modify them, to build
  145. them, to deploy whole operating systems, etc.
  146. Knowing the basics of how to program in Scheme will unlock many of the
  147. advanced features Guix provides --- and you don't even need to be an
  148. experienced programmer to use them!
  149. Let's get started!
  150. @menu
  151. * A Scheme Crash Course::
  152. @end menu
  153. @node A Scheme Crash Course
  154. @section A Scheme Crash Course
  155. @cindex Scheme, crash course
  156. Guix uses the Guile implementation of Scheme. To start playing with the
  157. language, install it with @code{guix install guile} and start a
  158. @dfn{REPL}---short for @uref{https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop,
  159. @dfn{read-eval-print loop}}---by running @code{guile} from the command line.
  160. Alternatively you can also run @code{guix shell guile -- guile}
  161. if you'd rather not have Guile installed in your user profile.
  162. In the following examples, lines show what you would type at the REPL;
  163. lines starting with ``@result{}'' show evaluation results, while lines
  164. starting with ``@print{}'' show things that get printed. @xref{Using Guile
  165. Interactively,,, guile, GNU Guile Reference Manual}, for more details on the
  166. REPL.
  167. @itemize
  168. @item
  169. Scheme syntax boils down to a tree of expressions (or @emph{s-expression} in
  170. Lisp lingo). An expression can be a literal such as numbers and strings, or a
  171. compound which is a parenthesized list of compounds and literals. @code{#true}
  172. and @code{#false} (abbreviated @code{#t} and @code{#f}) stand for the
  173. Booleans ``true'' and ``false'', respectively.
  174. Examples of valid expressions:
  175. @lisp
  176. "Hello World!"
  177. @result{} "Hello World!"
  178. 17
  179. @result{} 17
  180. (display (string-append "Hello " "Guix" "\n"))
  181. @print{} Hello Guix!
  182. @result{} #<unspecified>
  183. @end lisp
  184. @item
  185. This last example is a function call nested in another function call. When a
  186. parenthesized expression is evaluated, the first term is the function and the
  187. rest are the arguments passed to the function. Every function returns the
  188. last evaluated expression as its return value.
  189. @item
  190. Anonymous functions---@dfn{procedures} in Scheme parlance---are declared
  191. with the @code{lambda} term:
  192. @lisp
  193. (lambda (x) (* x x))
  194. @result{} #<procedure 120e348 at <unknown port>:24:0 (x)>
  195. @end lisp
  196. The above procedure returns the square of its argument. Since everything is
  197. an expression, the @code{lambda} expression returns an anonymous procedure,
  198. which can in turn be applied to an argument:
  199. @lisp
  200. ((lambda (x) (* x x)) 3)
  201. @result{} 9
  202. @end lisp
  203. Procedures are regular values just like numbers, strings, Booleans, and
  204. so on.
  205. @item
  206. Anything can be assigned a global name with @code{define}:
  207. @lisp
  208. (define a 3)
  209. (define square (lambda (x) (* x x)))
  210. (square a)
  211. @result{} 9
  212. @end lisp
  213. @item
  214. Procedures can be defined more concisely with the following syntax:
  215. @lisp
  216. (define (square x) (* x x))
  217. @end lisp
  218. @item
  219. A list structure can be created with the @code{list} procedure:
  220. @lisp
  221. (list 2 a 5 7)
  222. @result{} (2 3 5 7)
  223. @end lisp
  224. @item
  225. Standard procedures are provided by the @code{(srfi srfi-1)} module to
  226. create and process lists (@pxref{SRFI-1, list processing,, guile, GNU
  227. Guile Reference Manual}). Here are some of the most useful ones in
  228. action:
  229. @lisp
  230. (use-modules (srfi srfi-1)) ;import list processing procedures
  231. (append (list 1 2) (list 3 4))
  232. @result{} (1 2 3 4)
  233. (map (lambda (x) (* x x)) (list 1 2 3 4))
  234. @result{} (1 4 9 16)
  235. (delete 3 (list 1 2 3 4)) @result{} (1 2 4)
  236. (filter odd? (list 1 2 3 4)) @result{} (1 3)
  237. (remove even? (list 1 2 3 4)) @result{} (1 3)
  238. (find number? (list "a" 42 "b")) @result{} 42
  239. @end lisp
  240. Notice how the first argument to @code{map}, @code{filter},
  241. @code{remove}, and @code{find} is a procedure!
  242. @item
  243. @cindex S-expression
  244. The @dfn{quote} disables evaluation of a parenthesized expression, also
  245. called an S-expression or ``s-exp'': the first term is not called over
  246. the other terms (@pxref{Expression Syntax, quote,, guile, GNU Guile
  247. Reference Manual}). Thus it effectively returns a list of terms.
  248. @lisp
  249. '(display (string-append "Hello " "Guix" "\n"))
  250. @result{} (display (string-append "Hello " "Guix" "\n"))
  251. '(2 a 5 7)
  252. @result{} (2 a 5 7)
  253. @end lisp
  254. @item
  255. The @code{quasiquote} (@code{`}, a backquote) disables evaluation of a
  256. parenthesized expression until @code{unquote} (@code{,}, a comma)
  257. re-enables it. Thus it provides us with fine-grained control over what
  258. is evaluated and what is not.
  259. @lisp
  260. `(2 a 5 7 (2 ,a 5 ,(+ a 4)))
  261. @result{} (2 a 5 7 (2 3 5 7))
  262. @end lisp
  263. Note that the above result is a list of mixed elements: numbers, symbols (here
  264. @code{a}) and the last element is a list itself.
  265. @item
  266. @cindex G-expressions, syntax
  267. @cindex gexps, syntax
  268. @findex #~
  269. @findex #$
  270. @findex gexp
  271. @findex ungexp
  272. Guix defines a variant of S-expressions on steroids called
  273. @dfn{G-expressions} or ``gexps'', which come with a variant of
  274. @code{quasiquote} and @code{unquote}: @code{#~} (or @code{gexp}) and
  275. @code{#$} (or @code{ungexp}). They let you @emph{stage code for later
  276. execution}.
  277. For example, you'll encounter gexps in some package definitions where
  278. they provide code to be executed during the package build process. They
  279. look like this:
  280. @lisp
  281. (use-modules (guix gexp) ;so we can write gexps
  282. (gnu packages base)) ;for 'coreutils'
  283. ;; Below is a G-expression representing staged code.
  284. #~(begin
  285. ;; Invoke 'ls' from the package defined by the 'coreutils'
  286. ;; variable.
  287. (system* #$(file-append coreutils "/bin/ls") "-l")
  288. ;; Create this package's output directory.
  289. (mkdir #$output))
  290. @end lisp
  291. @xref{G-Expressions,,, guix, GNU Guix Reference Manual}, for more on
  292. gexps.
  293. @item
  294. Multiple variables can be named locally with @code{let} (@pxref{Local
  295. Bindings,,, guile, GNU Guile Reference Manual}):
  296. @lisp
  297. (define x 10)
  298. (let ((x 2)
  299. (y 3))
  300. (list x y))
  301. @result{} (2 3)
  302. x
  303. @result{} 10
  304. y
  305. @error{} In procedure module-lookup: Unbound variable: y
  306. @end lisp
  307. Use @code{let*} to allow later variable declarations to refer to earlier
  308. definitions.
  309. @lisp
  310. (let* ((x 2)
  311. (y (* x 3)))
  312. (list x y))
  313. @result{} (2 6)
  314. @end lisp
  315. @item
  316. @dfn{Keywords} are typically used to identify the named parameters of a
  317. procedure. They are prefixed by @code{#:} (hash, colon) followed by
  318. alphanumeric characters: @code{#:like-this}.
  319. @xref{Keywords,,, guile, GNU Guile Reference Manual}.
  320. @item
  321. The percentage @code{%} is typically used for read-only global variables in
  322. the build stage. Note that it is merely a convention, like @code{_} in C.
  323. Scheme treats @code{%} exactly the same as any other letter.
  324. @item
  325. Modules are created with @code{define-module} (@pxref{Creating Guile
  326. Modules,,, guile, GNU Guile Reference Manual}). For instance
  327. @lisp
  328. (define-module (guix build-system ruby)
  329. #:use-module (guix store)
  330. #:export (ruby-build
  331. ruby-build-system))
  332. @end lisp
  333. defines the module @code{guix build-system ruby} which must be located in
  334. @file{guix/build-system/ruby.scm} somewhere in the Guile load path. It
  335. depends on the @code{(guix store)} module and it exports two variables,
  336. @code{ruby-build} and @code{ruby-build-system}.
  337. @xref{Package Modules,,, guix, GNU Guix Reference Manual}, for info on
  338. modules that define packages.
  339. @end itemize
  340. @quotation Going further
  341. Scheme is a language that has been widely used to teach programming and
  342. you'll find plenty of material using it as a vehicle. Here's a
  343. selection of documents to learn more about Scheme:
  344. @itemize
  345. @item
  346. @uref{https://spritely.institute/static/papers/scheme-primer.html, @i{A
  347. Scheme Primer}}, by Christine Lemmer-Webber and the Spritely Institute.
  348. @item
  349. @uref{http://www.troubleshooters.com/codecorn/scheme_guile/hello.htm,
  350. @i{Scheme at a Glance}}, by Steve Litt.
  351. @item
  352. @c There used to be a copy at mitpress.mit.edu but it vanished.
  353. @uref{https://sarabander.github.io/sicp/,
  354. @i{Structure and Interpretation of Computer Programs}}, by Harold
  355. Abelson and Gerald Jay Sussman, with Julie Sussman. Colloquially known
  356. as ``SICP'', this book is a reference.
  357. You can also install it and read it from your computer:
  358. @example
  359. guix install sicp info-reader
  360. info sicp
  361. @end example
  362. @end itemize
  363. You'll find more books, tutorials and other resources at
  364. @url{https://schemers.org/}.
  365. @end quotation
  366. @c *********************************************************************
  367. @node Packaging
  368. @chapter Packaging
  369. @cindex packaging
  370. This chapter is dedicated to teaching you how to add packages to the
  371. collection of packages that come with GNU Guix. This involves writing package
  372. definitions in Guile Scheme, organizing them in package modules, and building
  373. them.
  374. @menu
  375. * Packaging Tutorial:: A tutorial on how to add packages to Guix.
  376. @end menu
  377. @node Packaging Tutorial
  378. @section Packaging Tutorial
  379. GNU Guix stands out as the @emph{hackable} package manager, mostly because it
  380. uses @uref{https://www.gnu.org/software/guile/, GNU Guile}, a powerful
  381. high-level programming language, one of the
  382. @uref{https://en.wikipedia.org/wiki/Scheme_%28programming_language%29, Scheme}
  383. dialects from the
  384. @uref{https://en.wikipedia.org/wiki/Lisp_%28programming_language%29, Lisp family}.
  385. Package definitions are also written in Scheme, which empowers Guix in some
  386. very unique ways, unlike most other package managers that use shell scripts or
  387. simple languages.
  388. @itemize
  389. @item
  390. Use functions, structures, macros and all of Scheme expressiveness for your
  391. package definitions.
  392. @item
  393. Inheritance makes it easy to customize a package by inheriting from it and
  394. modifying only what is needed.
  395. @item
  396. Batch processing: the whole package collection can be parsed, filtered and
  397. processed. Building a headless server with all graphical interfaces stripped
  398. out? It's possible. Want to rebuild everything from source using specific
  399. compiler optimization flags? Pass the @code{#:make-flags "..."} argument to
  400. the list of packages. It wouldn't be a stretch to think
  401. @uref{https://wiki.gentoo.org/wiki/USE_flag, Gentoo USE flags} here, but this
  402. goes even further: the changes don't have to be thought out beforehand by the
  403. packager, they can be @emph{programmed} by the user!
  404. @end itemize
  405. The following tutorial covers all the basics around package creation with Guix.
  406. It does not assume much knowledge of the Guix system nor of the Lisp language.
  407. The reader is only expected to be familiar with the command line and to have some
  408. basic programming knowledge.
  409. @menu
  410. * A ``Hello World'' package::
  411. * Setup::
  412. * Extended example::
  413. * Other build systems::
  414. * Programmable and automated package definition::
  415. * Getting help::
  416. * Conclusion::
  417. * References::
  418. @end menu
  419. @node A ``Hello World'' package
  420. @subsection A ``Hello World'' package
  421. The ``Defining Packages'' section of the manual introduces the basics of Guix
  422. packaging (@pxref{Defining Packages,,, guix, GNU Guix Reference Manual}). In
  423. the following section, we will partly go over those basics again.
  424. GNU@tie{}Hello is a dummy project that serves as an idiomatic example for
  425. packaging. It uses the GNU build system (@code{./configure && make && make
  426. install}). Guix already provides a package definition which is a perfect
  427. example to start with. You can look up its declaration with @code{guix edit
  428. hello} from the command line. Let's see how it looks:
  429. @lisp
  430. (define-public hello
  431. (package
  432. (name "hello")
  433. (version "2.10")
  434. (source (origin
  435. (method url-fetch)
  436. (uri (string-append "mirror://gnu/hello/hello-" version
  437. ".tar.gz"))
  438. (sha256
  439. (base32
  440. "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i"))))
  441. (build-system gnu-build-system)
  442. (synopsis "Hello, GNU world: An example GNU package")
  443. (description
  444. "GNU Hello prints the message \"Hello, world!\" and then exits. It
  445. serves as an example of standard GNU coding practices. As such, it supports
  446. command-line arguments, multiple languages, and so on.")
  447. (home-page "https://www.gnu.org/software/hello/")
  448. (license gpl3+)))
  449. @end lisp
  450. As you can see, most of it is rather straightforward. But let's review the
  451. fields together:
  452. @table @samp
  453. @item name
  454. The project name. Using Scheme conventions, we prefer to keep it
  455. lower case, without underscore and using dash-separated words.
  456. @item source
  457. This field contains a description of the source code origin. The
  458. @code{origin} record contains these fields:
  459. @enumerate
  460. @item The method, here @code{url-fetch} to download via HTTP/FTP, but other methods
  461. exist, such as @code{git-fetch} for Git repositories.
  462. @item The URI, which is typically some @code{https://} location for @code{url-fetch}. Here
  463. the special `mirror://gnu` refers to a set of well known locations, all of
  464. which can be used by Guix to fetch the source, should some of them fail.
  465. @item The @code{sha256} checksum of the requested file. This is essential to ensure
  466. the source is not corrupted. Note that Guix works with base32 strings,
  467. hence the call to the @code{base32} function.
  468. @end enumerate
  469. @item build-system
  470. This is where the power of abstraction provided by the Scheme language really
  471. shines: in this case, the @code{gnu-build-system} abstracts away the famous
  472. @code{./configure && make && make install} shell invocations. Other build
  473. systems include the @code{trivial-build-system} which does not do anything and
  474. requires from the packager to program all the build steps, the
  475. @code{python-build-system}, the @code{emacs-build-system}, and many more
  476. (@pxref{Build Systems,,, guix, GNU Guix Reference Manual}).
  477. @item synopsis
  478. It should be a concise summary of what the package does. For many packages a
  479. tagline from the project's home page can be used as the synopsis.
  480. @item description
  481. Same as for the synopsis, it's fine to re-use the project description from the
  482. homepage. Note that Guix uses Texinfo syntax.
  483. @item home-page
  484. Use HTTPS if available.
  485. @item license
  486. See @code{guix/licenses.scm} in the project source for a full list of
  487. available licenses.
  488. @end table
  489. Time to build our first package! Nothing fancy here for now: we will stick to a
  490. dummy @code{my-hello}, a copy of the above declaration.
  491. As with the ritualistic ``Hello World'' taught with most programming languages,
  492. this will possibly be the most ``manual'' approach. We will work out an ideal
  493. setup later; for now we will go the simplest route.
  494. Save the following to a file @file{my-hello.scm}.
  495. @lisp
  496. (use-modules (guix packages)
  497. (guix download)
  498. (guix build-system gnu)
  499. (guix licenses))
  500. (package
  501. (name "my-hello")
  502. (version "2.10")
  503. (source (origin
  504. (method url-fetch)
  505. (uri (string-append "mirror://gnu/hello/hello-" version
  506. ".tar.gz"))
  507. (sha256
  508. (base32
  509. "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i"))))
  510. (build-system gnu-build-system)
  511. (synopsis "Hello, Guix world: An example custom Guix package")
  512. (description
  513. "GNU Hello prints the message \"Hello, world!\" and then exits. It
  514. serves as an example of standard GNU coding practices. As such, it supports
  515. command-line arguments, multiple languages, and so on.")
  516. (home-page "https://www.gnu.org/software/hello/")
  517. (license gpl3+))
  518. @end lisp
  519. We will explain the extra code in a moment.
  520. Feel free to play with the different values of the various fields. If you
  521. change the source, you'll need to update the checksum. Indeed, Guix refuses to
  522. build anything if the given checksum does not match the computed checksum of the
  523. source code. To obtain the correct checksum of the package declaration, we
  524. need to download the source, compute the sha256 checksum and convert it to
  525. base32.
  526. Thankfully, Guix can automate this task for us; all we need is to provide the
  527. URI:
  528. @c TRANSLATORS: This is example shell output.
  529. @example sh
  530. $ guix download mirror://gnu/hello/hello-2.10.tar.gz
  531. Starting download of /tmp/guix-file.JLYgL7
  532. From https://ftpmirror.gnu.org/gnu/hello/hello-2.10.tar.gz...
  533. following redirection to `https://mirror.ibcp.fr/pub/gnu/hello/hello-2.10.tar.gz'...
  534. …10.tar.gz 709KiB 2.5MiB/s 00:00 [##################] 100.0%
  535. /gnu/store/hbdalsf5lpf01x4dcknwx6xbn6n5km6k-hello-2.10.tar.gz
  536. 0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i
  537. @end example
  538. In this specific case the output tells us which mirror was chosen.
  539. If the result of the above command is not the same as in the above snippet,
  540. update your @code{my-hello} declaration accordingly.
  541. Note that GNU package tarballs come with an OpenPGP signature, so you
  542. should definitely check the signature of this tarball with `gpg` to
  543. authenticate it before going further:
  544. @c TRANSLATORS: This is example shell output.
  545. @example sh
  546. $ guix download mirror://gnu/hello/hello-2.10.tar.gz.sig
  547. Starting download of /tmp/guix-file.03tFfb
  548. From https://ftpmirror.gnu.org/gnu/hello/hello-2.10.tar.gz.sig...
  549. following redirection to `https://ftp.igh.cnrs.fr/pub/gnu/hello/hello-2.10.tar.gz.sig'...
  550. ….tar.gz.sig 819B 1.2MiB/s 00:00 [##################] 100.0%
  551. /gnu/store/rzs8wba9ka7grrmgcpfyxvs58mly0sx6-hello-2.10.tar.gz.sig
  552. 0q0v86n3y38z17rl146gdakw9xc4mcscpk8dscs412j22glrv9jf
  553. $ gpg --verify /gnu/store/rzs8wba9ka7grrmgcpfyxvs58mly0sx6-hello-2.10.tar.gz.sig /gnu/store/hbdalsf5lpf01x4dcknwx6xbn6n5km6k-hello-2.10.tar.gz
  554. gpg: Signature made Sun 16 Nov 2014 01:08:37 PM CET
  555. gpg: using RSA key A9553245FDE9B739
  556. gpg: Good signature from "Sami Kerola <kerolasa@@iki.fi>" [unknown]
  557. gpg: aka "Sami Kerola (http://www.iki.fi/kerolasa/) <kerolasa@@iki.fi>" [unknown]
  558. gpg: WARNING: This key is not certified with a trusted signature!
  559. gpg: There is no indication that the signature belongs to the owner.
  560. Primary key fingerprint: 8ED3 96E3 7E38 D471 A005 30D3 A955 3245 FDE9 B739
  561. @end example
  562. You can then happily run
  563. @c TRANSLATORS: Do not translate this command
  564. @example sh
  565. $ guix package --install-from-file=my-hello.scm
  566. @end example
  567. You should now have @code{my-hello} in your profile!
  568. @c TRANSLATORS: Do not translate this command
  569. @example sh
  570. $ guix package --list-installed=my-hello
  571. my-hello 2.10 out
  572. /gnu/store/f1db2mfm8syb8qvc357c53slbvf1g9m9-my-hello-2.10
  573. @end example
  574. We've gone as far as we could without any knowledge of Scheme. Before moving
  575. on to more complex packages, now is the right time to brush up on your Scheme
  576. knowledge. @pxref{A Scheme Crash Course} to get up to speed.
  577. @node Setup
  578. @subsection Setup
  579. In the rest of this chapter we will rely on some basic Scheme
  580. programming knowledge. Now let's detail the different possible setups
  581. for working on Guix packages.
  582. There are several ways to set up a Guix packaging environment.
  583. We recommend you work directly on the Guix source checkout since it makes it
  584. easier for everyone to contribute to the project.
  585. But first, let's look at other possibilities.
  586. @menu
  587. * Local file::
  588. * Channels::
  589. * Direct checkout hacking::
  590. @end menu
  591. @node Local file
  592. @subsubsection Local file
  593. This is what we previously did with @samp{my-hello}. With the Scheme basics we've
  594. covered, we are now able to explain the leading chunks. As stated in @code{guix
  595. package --help}:
  596. @example
  597. -f, --install-from-file=FILE
  598. install the package that the code within FILE
  599. evaluates to
  600. @end example
  601. Thus the last expression @emph{must} return a package, which is the case in our
  602. earlier example.
  603. The @code{use-modules} expression tells which of the modules we need in the file.
  604. Modules are a collection of values and procedures. They are commonly called
  605. ``libraries'' or ``packages'' in other programming languages.
  606. @node Channels
  607. @subsubsection Channels
  608. @cindex channel
  609. Guix and its package collection can be extended through @dfn{channels}.
  610. A channel is a Git repository, public or not, containing @file{.scm}
  611. files that provide packages (@pxref{Defining Packages,,, guix, GNU Guix
  612. Reference Manual}) or services (@pxref{Defining Services,,, guix, GNU
  613. Guix Reference Manual}).
  614. How would you go about creating a channel? First, create a directory
  615. that will contain your @file{.scm} files, say @file{~/my-channel}:
  616. @example
  617. mkdir ~/my-channel
  618. @end example
  619. Suppose you want to add the @samp{my-hello} package we saw previously;
  620. it first needs some adjustments:
  621. @lisp
  622. (define-module (my-hello)
  623. #:use-module (guix licenses)
  624. #:use-module (guix packages)
  625. #:use-module (guix build-system gnu)
  626. #:use-module (guix download))
  627. (define-public my-hello
  628. (package
  629. (name "my-hello")
  630. (version "2.10")
  631. (source (origin
  632. (method url-fetch)
  633. (uri (string-append "mirror://gnu/hello/hello-" version
  634. ".tar.gz"))
  635. (sha256
  636. (base32
  637. "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i"))))
  638. (build-system gnu-build-system)
  639. (synopsis "Hello, Guix world: An example custom Guix package")
  640. (description
  641. "GNU Hello prints the message \"Hello, world!\" and then exits. It
  642. serves as an example of standard GNU coding practices. As such, it supports
  643. command-line arguments, multiple languages, and so on.")
  644. (home-page "https://www.gnu.org/software/hello/")
  645. (license gpl3+)))
  646. @end lisp
  647. Note that we have assigned the package value to an exported variable name with
  648. @code{define-public}. This is effectively assigning the package to the @code{my-hello}
  649. variable so that it can be referenced, among other as dependency of other
  650. packages.
  651. If you use @code{guix package --install-from-file=my-hello.scm} on the above file, it
  652. will fail because the last expression, @code{define-public}, does not return a
  653. package. If you want to use @code{define-public} in this use-case nonetheless, make
  654. sure the file ends with an evaluation of @code{my-hello}:
  655. @lisp
  656. ;; ...
  657. (define-public my-hello
  658. ;; ...
  659. )
  660. my-hello
  661. @end lisp
  662. This last example is not very typical.
  663. Now how do you make that package visible to @command{guix} commands so
  664. you can test your packages? You need to add the directory to the search
  665. path using the @option{-L} command-line option, as in these examples:
  666. @example
  667. guix show -L ~/my-channel my-hello
  668. guix build -L ~/my-channel my-hello
  669. @end example
  670. The final step is to turn @file{~/my-channel} into an actual channel,
  671. making your package collection seamlessly available @i{via} any
  672. @command{guix} command. To do that, you first need to make it a Git
  673. repository:
  674. @example
  675. cd ~/my-channel
  676. git init
  677. git add my-hello.scm
  678. git commit -m "First commit of my channel."
  679. @end example
  680. And that's it, you have a channel! From there on, you can add this
  681. channel to your channel configuration in
  682. @file{~/.config/guix/channels.scm} (@pxref{Specifying Additional
  683. Channels,,, guix, GNU Guix Reference Manual}); assuming you keep your
  684. channel local for now, the @file{channels.scm} would look something like
  685. this:
  686. @lisp
  687. (append (list (channel
  688. (name 'my-channel)
  689. (url (string-append "file://" (getenv "HOME")
  690. "/my-channel"))))
  691. %default-channels)
  692. @end lisp
  693. Next time you run @command{guix pull}, your channel will be picked up
  694. and the packages it defines will be readily available to all the
  695. @command{guix} commands, even if you do not pass @option{-L}. The
  696. @command{guix describe} command will show that Guix is, indeed, using
  697. both the @code{my-channel} and the @code{guix} channels.
  698. @xref{Creating a Channel,,, guix, GNU Guix Reference Manual}, for
  699. details.
  700. @node Direct checkout hacking
  701. @subsubsection Direct checkout hacking
  702. Working directly on the Guix project is recommended: it reduces the friction
  703. when the time comes to submit your changes upstream to let the community benefit
  704. from your hard work!
  705. Unlike most software distributions, the Guix repository holds in one place both
  706. the tooling (including the package manager) and the package definitions. This
  707. choice was made so that it would give developers the flexibility to modify the
  708. API without breakage by updating all packages at the same time. This reduces
  709. development inertia.
  710. Check out the official @uref{https://git-scm.com/, Git} repository:
  711. @example
  712. $ git clone https://git.savannah.gnu.org/git/guix.git
  713. @end example
  714. In the rest of this article, we use @samp{$GUIX_CHECKOUT} to refer to the location of
  715. the checkout.
  716. Follow the instructions in the manual (@pxref{Contributing,,, guix, GNU Guix
  717. Reference Manual}) to set up the repository environment.
  718. Once ready, you should be able to use the package definitions from the
  719. repository environment.
  720. Feel free to edit package definitions found in @samp{$GUIX_CHECKOUT/gnu/packages}.
  721. The @samp{$GUIX_CHECKOUT/pre-inst-env} script lets you use @samp{guix} over the package
  722. collection of the repository (@pxref{Running Guix Before It Is
  723. Installed,,, guix, GNU Guix Reference Manual}).
  724. @itemize
  725. @item
  726. Search packages, such as Ruby:
  727. @example
  728. $ cd $GUIX_CHECKOUT
  729. $ ./pre-inst-env guix package --list-available=ruby
  730. ruby 1.8.7-p374 out gnu/packages/ruby.scm:119:2
  731. ruby 2.1.6 out gnu/packages/ruby.scm:91:2
  732. ruby 2.2.2 out gnu/packages/ruby.scm:39:2
  733. @end example
  734. @item
  735. Build a package, here Ruby version 2.1:
  736. @example
  737. $ ./pre-inst-env guix build --keep-failed ruby@@2.1
  738. /gnu/store/c13v73jxmj2nir2xjqaz5259zywsa9zi-ruby-2.1.6
  739. @end example
  740. @item
  741. Install it to your user profile:
  742. @example
  743. $ ./pre-inst-env guix package --install ruby@@2.1
  744. @end example
  745. @item
  746. Check for common mistakes:
  747. @example
  748. $ ./pre-inst-env guix lint ruby@@2.1
  749. @end example
  750. @end itemize
  751. Guix strives at maintaining a high packaging standard; when contributing to the
  752. Guix project, remember to
  753. @itemize
  754. @item
  755. follow the coding style (@pxref{Coding Style,,, guix, GNU Guix Reference Manual}),
  756. @item
  757. and review the check list from the manual (@pxref{Submitting Patches,,, guix, GNU Guix Reference Manual}).
  758. @end itemize
  759. Once you are happy with the result, you are welcome to send your contribution to
  760. make it part of Guix. This process is also detailed in the manual. (@pxref{Contributing,,, guix, GNU Guix Reference Manual})
  761. It's a community effort so the more join in, the better Guix becomes!
  762. @node Extended example
  763. @subsection Extended example
  764. The above ``Hello World'' example is as simple as it goes. Packages can be more
  765. complex than that and Guix can handle more advanced scenarios. Let's look at
  766. another, more sophisticated package (slightly modified from the source):
  767. @lisp
  768. (define-module (gnu packages version-control)
  769. #:use-module ((guix licenses) #:prefix license:)
  770. #:use-module (guix utils)
  771. #:use-module (guix packages)
  772. #:use-module (guix git-download)
  773. #:use-module (guix build-system cmake)
  774. #:use-module (gnu packages compression)
  775. #:use-module (gnu packages pkg-config)
  776. #:use-module (gnu packages python)
  777. #:use-module (gnu packages ssh)
  778. #:use-module (gnu packages tls)
  779. #:use-module (gnu packages web))
  780. (define-public my-libgit2
  781. (let ((commit "e98d0a37c93574d2c6107bf7f31140b548c6a7bf")
  782. (revision "1"))
  783. (package
  784. (name "my-libgit2")
  785. (version (git-version "0.26.6" revision commit))
  786. (source (origin
  787. (method git-fetch)
  788. (uri (git-reference
  789. (url "https://github.com/libgit2/libgit2/")
  790. (commit commit)))
  791. (file-name (git-file-name name version))
  792. (sha256
  793. (base32
  794. "17pjvprmdrx4h6bb1hhc98w9qi6ki7yl57f090n9kbhswxqfs7s3"))
  795. (patches (search-patches "libgit2-mtime-0.patch"))
  796. (modules '((guix build utils)))
  797. ;; Remove bundled software.
  798. (snippet '(delete-file-recursively "deps"))))
  799. (build-system cmake-build-system)
  800. (outputs '("out" "debug"))
  801. (arguments
  802. `(#:tests? #true ; Run the test suite (this is the default)
  803. #:configure-flags '("-DUSE_SHA1DC=ON") ; SHA-1 collision detection
  804. #:phases
  805. (modify-phases %standard-phases
  806. (add-after 'unpack 'fix-hardcoded-paths
  807. (lambda _
  808. (substitute* "tests/repo/init.c"
  809. (("#!/bin/sh") (string-append "#!" (which "sh"))))
  810. (substitute* "tests/clar/fs.h"
  811. (("/bin/cp") (which "cp"))
  812. (("/bin/rm") (which "rm")))))
  813. ;; Run checks more verbosely.
  814. (replace 'check
  815. (lambda* (#:key tests? #:allow-other-keys)
  816. (when tests?
  817. (invoke "./libgit2_clar" "-v" "-Q"))))
  818. (add-after 'unpack 'make-files-writable-for-tests
  819. (lambda _ (for-each make-file-writable (find-files ".")))))))
  820. (inputs
  821. (list libssh2 http-parser python-wrapper))
  822. (native-inputs
  823. (list pkg-config))
  824. (propagated-inputs
  825. ;; These two libraries are in 'Requires.private' in libgit2.pc.
  826. (list openssl zlib))
  827. (home-page "https://libgit2.github.com/")
  828. (synopsis "Library providing Git core methods")
  829. (description
  830. "Libgit2 is a portable, pure C implementation of the Git core methods
  831. provided as a re-entrant linkable library with a solid API, allowing you to
  832. write native speed custom Git applications in any language with bindings.")
  833. ;; GPLv2 with linking exception
  834. (license license:gpl2))))
  835. @end lisp
  836. (In those cases were you only want to tweak a few fields from a package
  837. definition, you should rely on inheritance instead of copy-pasting everything.
  838. See below.)
  839. Let's discuss those fields in depth.
  840. @subsubsection @code{git-fetch} method
  841. Unlike the @code{url-fetch} method, @code{git-fetch} expects a @code{git-reference} which takes
  842. a Git repository and a commit. The commit can be any Git reference such as
  843. tags, so if the @code{version} is tagged, then it can be used directly. Sometimes
  844. the tag is prefixed with a @code{v}, in which case you'd use @code{(commit (string-append
  845. "v" version))}.
  846. To ensure that the source code from the Git repository is stored in a
  847. directory with a descriptive name, we use @code{(file-name (git-file-name name
  848. version))}.
  849. The @code{git-version} procedure can be used to derive the
  850. version when packaging programs for a specific commit, following the
  851. Guix contributor guidelines (@pxref{Version Numbers,,, guix, GNU Guix
  852. Reference Manual}).
  853. How does one obtain the @code{sha256} hash that's in there, you ask? By
  854. invoking @command{guix hash} on a checkout of the desired commit, along
  855. these lines:
  856. @example
  857. git clone https://github.com/libgit2/libgit2/
  858. cd libgit2
  859. git checkout v0.26.6
  860. guix hash -rx .
  861. @end example
  862. @command{guix hash -rx} computes a SHA256 hash over the whole directory,
  863. excluding the @file{.git} sub-directory (@pxref{Invoking guix hash,,,
  864. guix, GNU Guix Reference Manual}).
  865. In the future, @command{guix download} will hopefully be able to do
  866. these steps for you, just like it does for regular downloads.
  867. @subsubsection Snippets
  868. Snippets are quoted (i.e. non-evaluated) Scheme code that are a means of patching
  869. the source. They are a Guix-y alternative to the traditional @file{.patch} files.
  870. Because of the quote, the code in only evaluated when passed to the Guix daemon
  871. for building. There can be as many snippets as needed.
  872. Snippets might need additional Guile modules which can be imported from the
  873. @code{modules} field.
  874. @subsubsection Inputs
  875. There are 3 different input types. In short:
  876. @table @asis
  877. @item native-inputs
  878. Required for building but not runtime -- installing a package
  879. through a substitute won't install these inputs.
  880. @item inputs
  881. Installed in the store but not in the profile, as well as being
  882. present at build time.
  883. @item propagated-inputs
  884. Installed in the store and in the profile, as well as
  885. being present at build time.
  886. @end table
  887. @xref{package Reference,,, guix, GNU Guix Reference Manual} for more details.
  888. The distinction between the various inputs is important: if a dependency can be
  889. handled as an @emph{input} instead of a @emph{propagated input}, it should be done so, or
  890. else it ``pollutes'' the user profile for no good reason.
  891. For instance, a user installing a graphical program that depends on a
  892. command line tool might only be interested in the graphical part, so there is no
  893. need to force the command line tool into the user profile. The dependency is a
  894. concern to the package, not to the user. @emph{Inputs} make it possible to handle
  895. dependencies without bugging the user by adding undesired executable files (or
  896. libraries) to their profile.
  897. Same goes for @emph{native-inputs}: once the program is installed, build-time
  898. dependencies can be safely garbage-collected.
  899. It also matters when a substitute is available, in which case only the @emph{inputs}
  900. and @emph{propagated inputs} will be fetched: the @emph{native inputs} are not required to
  901. install a package from a substitute.
  902. @quotation Note
  903. You may see here and there snippets where package inputs are written
  904. quite differently, like so:
  905. @lisp
  906. ;; The "old style" for inputs.
  907. (inputs
  908. `(("libssh2" ,libssh2)
  909. ("http-parser" ,http-parser)
  910. ("python" ,python-wrapper)))
  911. @end lisp
  912. This is the ``old style'', where each input in the list is explicitly
  913. given a label (a string). It is still supported but we recommend using
  914. the style above instead. @xref{package Reference,,, guix, GNU Guix
  915. Reference Manual}, for more info.
  916. @end quotation
  917. @subsubsection Outputs
  918. Just like how a package can have multiple inputs, it can also produce multiple
  919. outputs.
  920. Each output corresponds to a separate directory in the store.
  921. The user can choose which output to install; this is useful to save space or
  922. to avoid polluting the user profile with unwanted executables or libraries.
  923. Output separation is optional. When the @code{outputs} field is left out, the
  924. default and only output (the complete package) is referred to as @code{"out"}.
  925. Typical separate output names include @code{debug} and @code{doc}.
  926. It's advised to separate outputs only when you've shown it's worth it: if the
  927. output size is significant (compare with @code{guix size}) or in case the package is
  928. modular.
  929. @subsubsection Build system arguments
  930. The @code{arguments} is a keyword-value list used to configure the build process.
  931. The simplest argument @code{#:tests?} can be used to disable the test suite when
  932. building the package. This is mostly useful when the package does not feature
  933. any test suite. It's strongly recommended to keep the test suite on if there is
  934. one.
  935. Another common argument is @code{:make-flags}, which specifies a list of flags to
  936. append when running make, as you would from the command line. For instance, the
  937. following flags
  938. @lisp
  939. #:make-flags (list (string-append "prefix=" (assoc-ref %outputs "out"))
  940. "CC=gcc")
  941. @end lisp
  942. translate into
  943. @example
  944. $ make CC=gcc prefix=/gnu/store/...-<out>
  945. @end example
  946. This sets the C compiler to @code{gcc} and the @code{prefix} variable (the installation
  947. directory in Make parlance) to @code{(assoc-ref %outputs "out")}, which is a build-stage
  948. global variable pointing to the destination directory in the store (something like
  949. @file{/gnu/store/...-my-libgit2-20180408}).
  950. Similarly, it's possible to set the configure flags:
  951. @lisp
  952. #:configure-flags '("-DUSE_SHA1DC=ON")
  953. @end lisp
  954. The @code{%build-inputs} variable is also generated in scope. It's an association
  955. table that maps the input names to their store directories.
  956. The @code{phases} keyword lists the sequential steps of the build system. Typically
  957. phases include @code{unpack}, @code{configure}, @code{build}, @code{install} and @code{check}. To know
  958. more about those phases, you need to work out the appropriate build system
  959. definition in @samp{$GUIX_CHECKOUT/guix/build/gnu-build-system.scm}:
  960. @lisp
  961. (define %standard-phases
  962. ;; Standard build phases, as a list of symbol/procedure pairs.
  963. (let-syntax ((phases (syntax-rules ()
  964. ((_ p ...) `((p . ,p) ...)))))
  965. (phases set-SOURCE-DATE-EPOCH set-paths install-locale unpack
  966. bootstrap
  967. patch-usr-bin-file
  968. patch-source-shebangs configure patch-generated-file-shebangs
  969. build check install
  970. patch-shebangs strip
  971. validate-runpath
  972. validate-documentation-location
  973. delete-info-dir-file
  974. patch-dot-desktop-files
  975. install-license-files
  976. reset-gzip-timestamps
  977. compress-documentation)))
  978. @end lisp
  979. Or from the REPL:
  980. @lisp
  981. (add-to-load-path "/path/to/guix/checkout")
  982. ,use (guix build gnu-build-system)
  983. (map first %standard-phases)
  984. @result{} (set-SOURCE-DATE-EPOCH set-paths install-locale unpack bootstrap patch-usr-bin-file patch-source-shebangs configure patch-generated-file-shebangs build check install patch-shebangs strip validate-runpath validate-documentation-location delete-info-dir-file patch-dot-desktop-files install-license-files reset-gzip-timestamps compress-documentation)
  985. @end lisp
  986. If you want to know more about what happens during those phases, consult the
  987. associated procedures.
  988. For instance, as of this writing the definition of @code{unpack} for the GNU build
  989. system is:
  990. @lisp
  991. (define* (unpack #:key source #:allow-other-keys)
  992. "Unpack SOURCE in the working directory, and change directory within the
  993. source. When SOURCE is a directory, copy it in a sub-directory of the current
  994. working directory."
  995. (if (file-is-directory? source)
  996. (begin
  997. (mkdir "source")
  998. (chdir "source")
  999. ;; Preserve timestamps (set to the Epoch) on the copied tree so that
  1000. ;; things work deterministically.
  1001. (copy-recursively source "."
  1002. #:keep-mtime? #true))
  1003. (begin
  1004. (if (string-suffix? ".zip" source)
  1005. (invoke "unzip" source)
  1006. (invoke "tar" "xvf" source))
  1007. (chdir (first-subdirectory "."))))
  1008. #true)
  1009. @end lisp
  1010. Note the @code{chdir} call: it changes the working directory to where the source was
  1011. unpacked.
  1012. Thus every phase following the @code{unpack} will use the source as a working
  1013. directory, which is why we can directly work on the source files.
  1014. That is to say, unless a later phase changes the working directory to something
  1015. else.
  1016. We modify the list of @code{%standard-phases} of the build system with the
  1017. @code{modify-phases} macro as per the list of specified modifications, which may have
  1018. the following forms:
  1019. @itemize
  1020. @item
  1021. @code{(add-before @var{phase} @var{new-phase} @var{procedure})}: Run @var{procedure} named @var{new-phase} before @var{phase}.
  1022. @item
  1023. @code{(add-after @var{phase} @var{new-phase} @var{procedure})}: Same, but afterwards.
  1024. @item
  1025. @code{(replace @var{phase} @var{procedure})}.
  1026. @item
  1027. @code{(delete @var{phase})}.
  1028. @end itemize
  1029. The @var{procedure} supports the keyword arguments @code{inputs} and @code{outputs}. Each
  1030. input (whether @emph{native}, @emph{propagated} or not) and output directory is referenced
  1031. by their name in those variables. Thus @code{(assoc-ref outputs "out")} is the store
  1032. directory of the main output of the package. A phase procedure may look like
  1033. this:
  1034. @lisp
  1035. (lambda* (#:key inputs outputs #:allow-other-keys)
  1036. (let ((bash-directory (assoc-ref inputs "bash"))
  1037. (output-directory (assoc-ref outputs "out"))
  1038. (doc-directory (assoc-ref outputs "doc")))
  1039. ;; ...
  1040. #true))
  1041. @end lisp
  1042. The procedure must return @code{#true} on success. It's brittle to rely on the return
  1043. value of the last expression used to tweak the phase because there is no
  1044. guarantee it would be a @code{#true}. Hence the trailing @code{#true} to ensure the right value
  1045. is returned on success.
  1046. @subsubsection Code staging
  1047. The astute reader may have noticed the quasi-quote and comma syntax in the
  1048. argument field. Indeed, the build code in the package declaration should not be
  1049. evaluated on the client side, but only when passed to the Guix daemon. This
  1050. mechanism of passing code around two running processes is called @uref{https://arxiv.org/abs/1709.00833, code staging}.
  1051. @subsubsection Utility functions
  1052. When customizing @code{phases}, we often need to write code that mimics the
  1053. equivalent system invocations (@code{make}, @code{mkdir}, @code{cp}, etc.)@: commonly used during
  1054. regular ``Unix-style'' installations.
  1055. Some like @code{chmod} are native to Guile.
  1056. @xref{,,, guile, Guile reference manual} for a complete list.
  1057. Guix provides additional helper functions which prove especially handy in the
  1058. context of package management.
  1059. Some of those functions can be found in
  1060. @samp{$GUIX_CHECKOUT/guix/guix/build/utils.scm}. Most of them mirror the behaviour
  1061. of the traditional Unix system commands:
  1062. @table @code
  1063. @item which
  1064. Like the @samp{which} system command.
  1065. @item find-files
  1066. Akin to the @samp{find} system command.
  1067. @item mkdir-p
  1068. Like @samp{mkdir -p}, which creates all parents as needed.
  1069. @item install-file
  1070. Similar to @samp{install} when installing a file to a (possibly
  1071. non-existing) directory. Guile has @code{copy-file} which works
  1072. like @samp{cp}.
  1073. @item copy-recursively
  1074. Like @samp{cp -r}.
  1075. @item delete-file-recursively
  1076. Like @samp{rm -rf}.
  1077. @item invoke
  1078. Run an executable. This should be used instead of @code{system*}.
  1079. @item with-directory-excursion
  1080. Run the body in a different working directory,
  1081. then restore the previous working directory.
  1082. @item substitute*
  1083. A ``@command{sed}-like'' function.
  1084. @end table
  1085. @xref{Build Utilities,,, guix, GNU Guix Reference Manual}, for more
  1086. information on these utilities.
  1087. @subsubsection Module prefix
  1088. The license in our last example needs a prefix: this is because of how the
  1089. @code{license} module was imported in the package, as @code{#:use-module ((guix licenses)
  1090. #:prefix license:)}. The Guile module import mechanism
  1091. (@pxref{Using Guile Modules,,, guile, Guile reference manual})
  1092. gives the user full control over namespacing: this is needed to avoid
  1093. clashes between, say, the
  1094. @samp{zlib} variable from @samp{licenses.scm} (a @emph{license} value) and the @samp{zlib} variable
  1095. from @samp{compression.scm} (a @emph{package} value).
  1096. @node Other build systems
  1097. @subsection Other build systems
  1098. What we've seen so far covers the majority of packages using a build system
  1099. other than the @code{trivial-build-system}. The latter does not automate anything
  1100. and leaves you to build everything manually. This can be more demanding and we
  1101. won't cover it here for now, but thankfully it is rarely necessary to fall back
  1102. on this system.
  1103. For the other build systems, such as ASDF, Emacs, Perl, Ruby and many more, the
  1104. process is very similar to the GNU build system except for a few specialized
  1105. arguments.
  1106. @xref{Build Systems,,, guix, GNU Guix Reference Manual}, for more
  1107. information on build systems, or check the source code in the
  1108. @samp{$GUIX_CHECKOUT/guix/build} and
  1109. @samp{$GUIX_CHECKOUT/guix/build-system} directories.
  1110. @node Programmable and automated package definition
  1111. @subsection Programmable and automated package definition
  1112. We can't repeat it enough: having a full-fledged programming language at hand
  1113. empowers us in ways that reach far beyond traditional package management.
  1114. Let's illustrate this with some awesome features of Guix!
  1115. @menu
  1116. * Recursive importers::
  1117. * Automatic update::
  1118. * Inheritance::
  1119. @end menu
  1120. @node Recursive importers
  1121. @subsubsection Recursive importers
  1122. You might find some build systems good enough that there is little to do at all
  1123. to write a package, to the point that it becomes repetitive and tedious after a
  1124. while. A @emph{raison d'être} of computers is to replace human beings at those
  1125. boring tasks. So let's tell Guix to do this for us and create the package
  1126. definition of an R package from CRAN (the output is trimmed for conciseness):
  1127. @example
  1128. $ guix import cran --recursive walrus
  1129. (define-public r-mc2d
  1130. ; ...
  1131. (license gpl2+)))
  1132. (define-public r-jmvcore
  1133. ; ...
  1134. (license gpl2+)))
  1135. (define-public r-wrs2
  1136. ; ...
  1137. (license gpl3)))
  1138. (define-public r-walrus
  1139. (package
  1140. (name "r-walrus")
  1141. (version "1.0.3")
  1142. (source
  1143. (origin
  1144. (method url-fetch)
  1145. (uri (cran-uri "walrus" version))
  1146. (sha256
  1147. (base32
  1148. "1nk2glcvy4hyksl5ipq2mz8jy4fss90hx6cq98m3w96kzjni6jjj"))))
  1149. (build-system r-build-system)
  1150. (propagated-inputs
  1151. (list r-ggplot2 r-jmvcore r-r6 r-wrs2))
  1152. (home-page "https://github.com/jamovi/walrus")
  1153. (synopsis "Robust Statistical Methods")
  1154. (description
  1155. "This package provides a toolbox of common robust statistical
  1156. tests, including robust descriptives, robust t-tests, and robust ANOVA.
  1157. It is also available as a module for 'jamovi' (see
  1158. <https://www.jamovi.org> for more information). Walrus is based on the
  1159. WRS2 package by Patrick Mair, which is in turn based on the scripts and
  1160. work of Rand Wilcox. These analyses are described in depth in the book
  1161. 'Introduction to Robust Estimation & Hypothesis Testing'.")
  1162. (license gpl3)))
  1163. @end example
  1164. The recursive importer won't import packages for which Guix already has package
  1165. definitions, except for the very first.
  1166. Not all applications can be packaged this way, only those relying on a select
  1167. number of supported systems. Read about the full list of importers in
  1168. the guix import section of the manual
  1169. (@pxref{Invoking guix import,,, guix, GNU Guix Reference Manual}).
  1170. @node Automatic update
  1171. @subsubsection Automatic update
  1172. Guix can be smart enough to check for updates on systems it knows. It can
  1173. report outdated package definitions with
  1174. @example
  1175. $ guix refresh hello
  1176. @end example
  1177. In most cases, updating a package to a newer version requires little more than
  1178. changing the version number and the checksum. Guix can do that automatically as
  1179. well:
  1180. @example
  1181. $ guix refresh hello --update
  1182. @end example
  1183. @node Inheritance
  1184. @subsubsection Inheritance
  1185. If you've started browsing the existing package definitions, you might have
  1186. noticed that a significant number of them have a @code{inherit} field:
  1187. @lisp
  1188. (define-public adwaita-icon-theme
  1189. (package (inherit gnome-icon-theme)
  1190. (name "adwaita-icon-theme")
  1191. (version "3.26.1")
  1192. (source (origin
  1193. (method url-fetch)
  1194. (uri (string-append "mirror://gnome/sources/" name "/"
  1195. (version-major+minor version) "/"
  1196. name "-" version ".tar.xz"))
  1197. (sha256
  1198. (base32
  1199. "17fpahgh5dyckgz7rwqvzgnhx53cx9kr2xw0szprc6bnqy977fi8"))))
  1200. (native-inputs (list `(,gtk+ "bin")))))
  1201. @end lisp
  1202. All unspecified fields are inherited from the parent package. This is very
  1203. convenient to create alternative packages, for instance with different source,
  1204. version or compilation options.
  1205. @node Getting help
  1206. @subsection Getting help
  1207. Sadly, some applications can be tough to package. Sometimes they need a patch to
  1208. work with the non-standard file system hierarchy enforced by the store.
  1209. Sometimes the tests won't run properly. (They can be skipped but this is not
  1210. recommended.) Other times the resulting package won't be reproducible.
  1211. Should you be stuck, unable to figure out how to fix any sort of packaging
  1212. issue, don't hesitate to ask the community for help.
  1213. See the @uref{https://www.gnu.org/software/guix/contact/, Guix homepage} for information on the mailing lists, IRC, etc.
  1214. @node Conclusion
  1215. @subsection Conclusion
  1216. This tutorial was a showcase of the sophisticated package management that Guix
  1217. boasts. At this point we have mostly restricted this introduction to the
  1218. @code{gnu-build-system} which is a core abstraction layer on which more advanced
  1219. abstractions are based.
  1220. Where do we go from here? Next we ought to dissect the innards of the build
  1221. system by removing all abstractions, using the @code{trivial-build-system}: this
  1222. should give us a thorough understanding of the process before investigating some
  1223. more advanced packaging techniques and edge cases.
  1224. Other features worth exploring are the interactive editing and debugging
  1225. capabilities of Guix provided by the Guile REPL@.
  1226. Those fancy features are completely optional and can wait; now is a good time
  1227. to take a well-deserved break. With what we've introduced here you should be
  1228. well armed to package lots of programs. You can get started right away and
  1229. hopefully we will see your contributions soon!
  1230. @node References
  1231. @subsection References
  1232. @itemize
  1233. @item
  1234. The @uref{https://www.gnu.org/software/guix/manual/en/html_node/Defining-Packages.html, package reference in the manual}
  1235. @item
  1236. @uref{https://gitlab.com/pjotrp/guix-notes/blob/master/HACKING.org, Pjotr’s hacking guide to GNU Guix}
  1237. @item
  1238. @uref{https://www.gnu.org/software/guix/guix-ghm-andreas-20130823.pdf, ``GNU Guix: Package without a scheme!''}, by Andreas Enge
  1239. @end itemize
  1240. @c *********************************************************************
  1241. @node System Configuration
  1242. @chapter System Configuration
  1243. Guix offers a flexible language for declaratively configuring your Guix
  1244. System. This flexibility can at times be overwhelming. The purpose of this
  1245. chapter is to demonstrate some advanced configuration concepts.
  1246. @pxref{System Configuration,,, guix, GNU Guix Reference Manual} for a complete
  1247. reference.
  1248. @menu
  1249. * Auto-Login to a Specific TTY:: Automatically Login a User to a Specific TTY
  1250. * Customizing the Kernel:: Creating and using a custom Linux kernel on Guix System.
  1251. * Guix System Image API:: Customizing images to target specific platforms.
  1252. * Using security keys:: How to use security keys with Guix System.
  1253. * Dynamic DNS mcron job:: Job to update the IP address behind a DuckDNS host name.
  1254. * Connecting to Wireguard VPN:: Connecting to a Wireguard VPN.
  1255. * Customizing a Window Manager:: Handle customization of a Window manager on Guix System.
  1256. * Running Guix on a Linode Server:: Running Guix on a Linode Server.
  1257. * Running Guix on a Kimsufi Server:: Running Guix on a Kimsufi Server.
  1258. * Setting up a bind mount:: Setting up a bind mount in the file-systems definition.
  1259. * Getting substitutes from Tor:: Configuring Guix daemon to get substitutes through Tor.
  1260. * Setting up NGINX with Lua:: Configuring NGINX web-server to load Lua modules.
  1261. * Music Server with Bluetooth Audio:: Headless music player with Bluetooth output.
  1262. @end menu
  1263. @node Auto-Login to a Specific TTY
  1264. @section Auto-Login to a Specific TTY
  1265. While the Guix manual explains auto-login one user to @emph{all} TTYs (
  1266. @pxref{auto-login to TTY,,, guix, GNU Guix Reference Manual}), some
  1267. might prefer a situation, in which one user is logged into one TTY with
  1268. the other TTYs either configured to login different users or no one at
  1269. all. Note that one can auto-login one user to any TTY, but it is
  1270. usually advisable to avoid @code{tty1}, which, by default, is used to
  1271. log warnings and errors.
  1272. Here is how one might set up auto login for one user to one tty:
  1273. @lisp
  1274. (define (auto-login-to-tty config tty user)
  1275. (if (string=? tty (mingetty-configuration-tty config))
  1276. (mingetty-configuration
  1277. (inherit config)
  1278. (auto-login user))
  1279. config))
  1280. (define %my-services
  1281. (modify-services %base-services
  1282. ;; @dots{}
  1283. (mingetty-service-type config =>
  1284. (auto-login-to-tty
  1285. config "tty3" "alice"))))
  1286. (operating-system
  1287. ;; @dots{}
  1288. (services %my-services))
  1289. @end lisp
  1290. One could also @code{compose} (@pxref{Higher-Order Functions,,, guile,
  1291. The Guile Reference Manual}) @code{auto-login-to-tty} to login multiple
  1292. users to multiple ttys.
  1293. Finally, here is a note of caution. Setting up auto login to a TTY,
  1294. means that anyone can turn on your computer and run commands as your
  1295. regular user.
  1296. However, if you have an encrypted root partition, and thus already need
  1297. to enter a passphrase when the system boots, auto-login might be a
  1298. convenient option.
  1299. @node Customizing the Kernel
  1300. @section Customizing the Kernel
  1301. Guix is, at its core, a source based distribution with substitutes
  1302. (@pxref{Substitutes,,, guix, GNU Guix Reference Manual}), and as such building
  1303. packages from their source code is an expected part of regular package
  1304. installations and upgrades. Given this starting point, it makes sense that
  1305. efforts are made to reduce the amount of time spent compiling packages, and
  1306. recent changes and upgrades to the building and distribution of substitutes
  1307. continues to be a topic of discussion within Guix.
  1308. The kernel, while not requiring an overabundance of RAM to build, does take a
  1309. rather long time on an average machine. The official kernel configuration, as
  1310. is the case with many GNU/Linux distributions, errs on the side of
  1311. inclusiveness, and this is really what causes the build to take such a long
  1312. time when the kernel is built from source.
  1313. The Linux kernel, however, can also just be described as a regular old
  1314. package, and as such can be customized just like any other package. The
  1315. procedure is a little bit different, although this is primarily due to the
  1316. nature of how the package definition is written.
  1317. The @code{linux-libre} kernel package definition is actually a procedure which
  1318. creates a package.
  1319. @lisp
  1320. (define* (make-linux-libre* version gnu-revision source supported-systems
  1321. #:key
  1322. (extra-version #f)
  1323. ;; A function that takes an arch and a variant.
  1324. ;; See kernel-config for an example.
  1325. (configuration-file #f)
  1326. (defconfig "defconfig")
  1327. (extra-options %default-extra-linux-options))
  1328. ...)
  1329. @end lisp
  1330. The current @code{linux-libre} package is for the 5.15.x series, and is
  1331. declared like this:
  1332. @lisp
  1333. (define-public linux-libre-5.15
  1334. (make-linux-libre* linux-libre-5.15-version
  1335. linux-libre-5.15-gnu-revision
  1336. linux-libre-5.15-source
  1337. '("x86_64-linux" "i686-linux" "armhf-linux" "aarch64-linux" "riscv64-linux")
  1338. #:configuration-file kernel-config))
  1339. @end lisp
  1340. Any keys which are not assigned values inherit their default value from the
  1341. @code{make-linux-libre} definition. When comparing the two snippets above,
  1342. notice the code comment that refers to @code{#:configuration-file}. Because of
  1343. this, it is not actually easy to include a custom kernel configuration from the
  1344. definition, but don't worry, there are other ways to work with what we do have.
  1345. There are two ways to create a kernel with a custom kernel configuration. The
  1346. first is to provide a standard @file{.config} file during the build process by
  1347. including an actual @file{.config} file as a native input to our custom
  1348. kernel. The following is a snippet from the custom @code{'configure} phase of
  1349. the @code{make-linux-libre} package definition:
  1350. @lisp
  1351. (let ((build (assoc-ref %standard-phases 'build))
  1352. (config (assoc-ref (or native-inputs inputs) "kconfig")))
  1353. ;; Use a custom kernel configuration file or a default
  1354. ;; configuration file.
  1355. (if config
  1356. (begin
  1357. (copy-file config ".config")
  1358. (chmod ".config" #o666))
  1359. (invoke "make" ,defconfig)))
  1360. @end lisp
  1361. Below is a sample kernel package. The @code{linux-libre} package is nothing
  1362. special and can be inherited from and have its fields overridden like any
  1363. other package:
  1364. @lisp
  1365. (define-public linux-libre/E2140
  1366. (package
  1367. (inherit linux-libre)
  1368. (native-inputs
  1369. `(("kconfig" ,(local-file "E2140.config"))
  1370. ,@@(alist-delete "kconfig"
  1371. (package-native-inputs linux-libre))))))
  1372. @end lisp
  1373. In the same directory as the file defining @code{linux-libre-E2140} is a file
  1374. named @file{E2140.config}, which is an actual kernel configuration file. The
  1375. @code{defconfig} keyword of @code{make-linux-libre} is left blank here, so the
  1376. only kernel configuration in the package is the one which was included in the
  1377. @code{native-inputs} field.
  1378. The second way to create a custom kernel is to pass a new value to the
  1379. @code{extra-options} keyword of the @code{make-linux-libre} procedure. The
  1380. @code{extra-options} keyword works with another function defined right below
  1381. it:
  1382. @lisp
  1383. (define %default-extra-linux-options
  1384. `(;; https://lists.gnu.org/archive/html/guix-devel/2014-04/msg00039.html
  1385. ("CONFIG_DEVPTS_MULTIPLE_INSTANCES" . #true)
  1386. ;; Modules required for initrd:
  1387. ("CONFIG_NET_9P" . m)
  1388. ("CONFIG_NET_9P_VIRTIO" . m)
  1389. ("CONFIG_VIRTIO_BLK" . m)
  1390. ("CONFIG_VIRTIO_NET" . m)
  1391. ("CONFIG_VIRTIO_PCI" . m)
  1392. ("CONFIG_VIRTIO_BALLOON" . m)
  1393. ("CONFIG_VIRTIO_MMIO" . m)
  1394. ("CONFIG_FUSE_FS" . m)
  1395. ("CONFIG_CIFS" . m)
  1396. ("CONFIG_9P_FS" . m)))
  1397. (define (config->string options)
  1398. (string-join (map (match-lambda
  1399. ((option . 'm)
  1400. (string-append option "=m"))
  1401. ((option . #true)
  1402. (string-append option "=y"))
  1403. ((option . #false)
  1404. (string-append option "=n")))
  1405. options)
  1406. "\n"))
  1407. @end lisp
  1408. And in the custom configure script from the `make-linux-libre` package:
  1409. @lisp
  1410. ;; Appending works even when the option wasn't in the
  1411. ;; file. The last one prevails if duplicated.
  1412. (let ((port (open-file ".config" "a"))
  1413. (extra-configuration ,(config->string extra-options)))
  1414. (display extra-configuration port)
  1415. (close-port port))
  1416. (invoke "make" "oldconfig")
  1417. @end lisp
  1418. So by not providing a configuration-file the @file{.config} starts blank, and
  1419. then we write into it the collection of flags that we want. Here's another
  1420. custom kernel:
  1421. @lisp
  1422. (define %macbook41-full-config
  1423. (append %macbook41-config-options
  1424. %file-systems
  1425. %efi-support
  1426. %emulation
  1427. (@@@@ (gnu packages linux) %default-extra-linux-options)))
  1428. (define-public linux-libre-macbook41
  1429. ;; XXX: Access the internal 'make-linux-libre*' procedure, which is
  1430. ;; private and unexported, and is liable to change in the future.
  1431. ((@@@@ (gnu packages linux) make-linux-libre*)
  1432. (@@@@ (gnu packages linux) linux-libre-version)
  1433. (@@@@ (gnu packages linux) linux-libre-gnu-revision)
  1434. (@@@@ (gnu packages linux) linux-libre-source)
  1435. '("x86_64-linux")
  1436. #:extra-version "macbook41"
  1437. #:extra-options %macbook41-config-options))
  1438. @end lisp
  1439. In the above example @code{%file-systems} is a collection of flags enabling
  1440. different file system support, @code{%efi-support} enables EFI support and
  1441. @code{%emulation} enables a x86_64-linux machine to act in 32-bit mode also.
  1442. @code{%default-extra-linux-options} are the ones quoted above, which had to be
  1443. added in since they were replaced in the @code{extra-options} keyword.
  1444. This all sounds like it should be doable, but how does one even know which
  1445. modules are required for a particular system? Two places that can be helpful
  1446. in trying to answer this question is the
  1447. @uref{https://wiki.gentoo.org/wiki/Handbook:AMD64/Installation/Kernel, Gentoo
  1448. Handbook} and the
  1449. @uref{https://www.kernel.org/doc/html/latest/admin-guide/README.html?highlight=localmodconfig,
  1450. documentation from the kernel itself}. From the kernel documentation, it
  1451. seems that @code{make localmodconfig} is the command we want.
  1452. In order to actually run @code{make localmodconfig} we first need to get and
  1453. unpack the kernel source code:
  1454. @example shell
  1455. tar xf $(guix build linux-libre --source)
  1456. @end example
  1457. Once inside the directory containing the source code run @code{touch .config}
  1458. to create an initial, empty @file{.config} to start with. @code{make
  1459. localmodconfig} works by seeing what you already have in @file{.config} and
  1460. letting you know what you're missing. If the file is blank then you're
  1461. missing everything. The next step is to run:
  1462. @example shell
  1463. guix shell -D linux-libre -- make localmodconfig
  1464. @end example
  1465. and note the output. Do note that the @file{.config} file is still empty.
  1466. The output generally contains two types of warnings. The first start with
  1467. "WARNING" and can actually be ignored in our case. The second read:
  1468. @example shell
  1469. module pcspkr did not have configs CONFIG_INPUT_PCSPKR
  1470. @end example
  1471. For each of these lines, copy the @code{CONFIG_XXXX_XXXX} portion into the
  1472. @file{.config} in the directory, and append @code{=m}, so in the end it looks
  1473. like this:
  1474. @example shell
  1475. CONFIG_INPUT_PCSPKR=m
  1476. CONFIG_VIRTIO=m
  1477. @end example
  1478. After copying all the configuration options, run @code{make localmodconfig}
  1479. again to make sure that you don't have any output starting with ``module''.
  1480. After all of these machine specific modules there are a couple more left that
  1481. are also needed. @code{CONFIG_MODULES} is necessary so that you can build and
  1482. load modules separately and not have everything built into the kernel.
  1483. @code{CONFIG_BLK_DEV_SD} is required for reading from hard drives. It is
  1484. possible that there are other modules which you will need.
  1485. This post does not aim to be a guide to configuring your own kernel however,
  1486. so if you do decide to build a custom kernel you'll have to seek out other
  1487. guides to create a kernel which is just right for your needs.
  1488. The second way to setup the kernel configuration makes more use of Guix's
  1489. features and allows you to share configuration segments between different
  1490. kernels. For example, all machines using EFI to boot have a number of EFI
  1491. configuration flags that they need. It is likely that all the kernels will
  1492. share a list of file systems to support. By using variables it is easier to
  1493. see at a glance what features are enabled and to make sure you don't have
  1494. features in one kernel but missing in another.
  1495. Left undiscussed however, is Guix's initrd and its customization. It is
  1496. likely that you'll need to modify the initrd on a machine using a custom
  1497. kernel, since certain modules which are expected to be built may not be
  1498. available for inclusion into the initrd.
  1499. @node Guix System Image API
  1500. @section Guix System Image API
  1501. Historically, Guix System is centered around an @code{operating-system}
  1502. structure. This structure contains various fields ranging from the
  1503. bootloader and kernel declaration to the services to install.
  1504. Depending on the target machine, that can go from a standard
  1505. @code{x86_64} machine to a small ARM single board computer such as the
  1506. Pine64, the image constraints can vary a lot. The hardware
  1507. manufacturers will impose different image formats with various partition
  1508. sizes and offsets.
  1509. To create images suitable for all those machines, a new abstraction is
  1510. necessary: that's the goal of the @code{image} record. This record
  1511. contains all the required information to be transformed into a
  1512. standalone image, that can be directly booted on any target machine.
  1513. @lisp
  1514. (define-record-type* <image>
  1515. image make-image
  1516. image?
  1517. (name image-name ;symbol
  1518. (default #f))
  1519. (format image-format) ;symbol
  1520. (target image-target
  1521. (default #f))
  1522. (size image-size ;size in bytes as integer
  1523. (default 'guess))
  1524. (operating-system image-operating-system ;<operating-system>
  1525. (default #f))
  1526. (partitions image-partitions ;list of <partition>
  1527. (default '()))
  1528. (compression? image-compression? ;boolean
  1529. (default #t))
  1530. (volatile-root? image-volatile-root? ;boolean
  1531. (default #t))
  1532. (substitutable? image-substitutable? ;boolean
  1533. (default #t)))
  1534. @end lisp
  1535. This record contains the operating-system to instantiate. The
  1536. @code{format} field defines the image type and can be @code{efi-raw},
  1537. @code{qcow2} or @code{iso9660} for instance. In the future, it could be
  1538. extended to @code{docker} or other image types.
  1539. A new directory in the Guix sources is dedicated to images definition. For now
  1540. there are four files:
  1541. @itemize @bullet
  1542. @item @file{gnu/system/images/hurd.scm}
  1543. @item @file{gnu/system/images/pine64.scm}
  1544. @item @file{gnu/system/images/novena.scm}
  1545. @item @file{gnu/system/images/pinebook-pro.scm}
  1546. @end itemize
  1547. Let's have a look to @file{pine64.scm}. It contains the
  1548. @code{pine64-barebones-os} variable which is a minimal definition of an
  1549. operating-system dedicated to the @b{Pine A64 LTS} board.
  1550. @lisp
  1551. (define pine64-barebones-os
  1552. (operating-system
  1553. (host-name "vignemale")
  1554. (timezone "Europe/Paris")
  1555. (locale "en_US.utf8")
  1556. (bootloader (bootloader-configuration
  1557. (bootloader u-boot-pine64-lts-bootloader)
  1558. (targets '("/dev/vda"))))
  1559. (initrd-modules '())
  1560. (kernel linux-libre-arm64-generic)
  1561. (file-systems (cons (file-system
  1562. (device (file-system-label "my-root"))
  1563. (mount-point "/")
  1564. (type "ext4"))
  1565. %base-file-systems))
  1566. (services (cons (service agetty-service-type
  1567. (agetty-configuration
  1568. (extra-options '("-L")) ; no carrier detect
  1569. (baud-rate "115200")
  1570. (term "vt100")
  1571. (tty "ttyS0")))
  1572. %base-services))))
  1573. @end lisp
  1574. The @code{kernel} and @code{bootloader} fields are pointing to packages
  1575. dedicated to this board.
  1576. Right below, the @code{pine64-image-type} variable is also defined.
  1577. @lisp
  1578. (define pine64-image-type
  1579. (image-type
  1580. (name 'pine64-raw)
  1581. (constructor (cut image-with-os arm64-disk-image <>))))
  1582. @end lisp
  1583. It's using a record we haven't talked about yet, the @code{image-type} record,
  1584. defined this way:
  1585. @lisp
  1586. (define-record-type* <image-type>
  1587. image-type make-image-type
  1588. image-type?
  1589. (name image-type-name) ;symbol
  1590. (constructor image-type-constructor)) ;<operating-system> -> <image>
  1591. @end lisp
  1592. The main purpose of this record is to associate a name to a procedure
  1593. transforming an @code{operating-system} to an image. To understand why
  1594. it is necessary, let's have a look to the command producing an image
  1595. from an @code{operating-system} configuration file:
  1596. @example
  1597. guix system image my-os.scm
  1598. @end example
  1599. This command expects an @code{operating-system} configuration but how
  1600. should we indicate that we want an image targeting a Pine64 board? We
  1601. need to provide an extra information, the @code{image-type}, by passing
  1602. the @code{--image-type} or @code{-t} flag, this way:
  1603. @example
  1604. guix system image --image-type=pine64-raw my-os.scm
  1605. @end example
  1606. This @code{image-type} parameter points to the @code{pine64-image-type}
  1607. defined above. Hence, the @code{operating-system} declared in
  1608. @code{my-os.scm} will be applied the @code{(cut image-with-os
  1609. arm64-disk-image <>)} procedure to turn it into an image.
  1610. The resulting image looks like:
  1611. @lisp
  1612. (image
  1613. (format 'disk-image)
  1614. (target "aarch64-linux-gnu")
  1615. (operating-system my-os)
  1616. (partitions
  1617. (list (partition
  1618. (inherit root-partition)
  1619. (offset root-offset)))))
  1620. @end lisp
  1621. which is the aggregation of the @code{operating-system} defined in
  1622. @code{my-os.scm} to the @code{arm64-disk-image} record.
  1623. But enough Scheme madness. What does this image API bring to the Guix user?
  1624. One can run:
  1625. @example
  1626. mathieu@@cervin:~$ guix system --list-image-types
  1627. The available image types are:
  1628. - unmatched-raw
  1629. - rock64-raw
  1630. - pinebook-pro-raw
  1631. - pine64-raw
  1632. - novena-raw
  1633. - hurd-raw
  1634. - hurd-qcow2
  1635. - qcow2
  1636. - iso9660
  1637. - uncompressed-iso9660
  1638. - tarball
  1639. - efi-raw
  1640. - mbr-raw
  1641. - docker
  1642. - wsl2
  1643. - raw-with-offset
  1644. - efi32-raw
  1645. @end example
  1646. and by writing an @code{operating-system} file based on
  1647. @code{pine64-barebones-os}, you can customize your image to your
  1648. preferences in a file (@file{my-pine-os.scm}) like this:
  1649. @lisp
  1650. (use-modules (gnu services linux)
  1651. (gnu system images pine64))
  1652. (let ((base-os pine64-barebones-os))
  1653. (operating-system
  1654. (inherit base-os)
  1655. (timezone "America/Indiana/Indianapolis")
  1656. (services
  1657. (cons
  1658. (service earlyoom-service-type
  1659. (earlyoom-configuration
  1660. (prefer-regexp "icecat|chromium")))
  1661. (operating-system-user-services base-os)))))
  1662. @end lisp
  1663. run:
  1664. @example
  1665. guix system image --image-type=pine64-raw my-pine-os.scm
  1666. @end example
  1667. or,
  1668. @example
  1669. guix system image --image-type=hurd-raw my-hurd-os.scm
  1670. @end example
  1671. to get an image that can be written directly to a hard drive and booted
  1672. from.
  1673. Without changing anything to @code{my-hurd-os.scm}, calling:
  1674. @example
  1675. guix system image --image-type=hurd-qcow2 my-hurd-os.scm
  1676. @end example
  1677. will instead produce a Hurd QEMU image.
  1678. @node Using security keys
  1679. @section Using security keys
  1680. @cindex 2FA, two-factor authentication
  1681. @cindex U2F, Universal 2nd Factor
  1682. @cindex security key, configuration
  1683. The use of security keys can improve your security by providing a second
  1684. authentication source that cannot be easily stolen or copied, at least
  1685. for a remote adversary (something that you have), to the main secret (a
  1686. passphrase -- something that you know), reducing the risk of
  1687. impersonation.
  1688. The example configuration detailed below showcases what minimal
  1689. configuration needs to be made on your Guix System to allow the use of a
  1690. Yubico security key. It is hoped the configuration can be useful for
  1691. other security keys as well, with minor adjustments.
  1692. @subsection Configuration for use as a two-factor authenticator (2FA)
  1693. To be usable, the udev rules of the system should be extended with
  1694. key-specific rules. The following shows how to extend your udev rules
  1695. with the @file{lib/udev/rules.d/70-u2f.rules} udev rule file provided by
  1696. the @code{libfido2} package from the @code{(gnu packages
  1697. security-token)} module and add your user to the @samp{"plugdev"} group
  1698. it uses:
  1699. @lisp
  1700. (use-package-modules ... security-token ...)
  1701. ...
  1702. (operating-system
  1703. ...
  1704. (users (cons* (user-account
  1705. (name "your-user")
  1706. (group "users")
  1707. (supplementary-groups
  1708. '("wheel" "netdev" "audio" "video"
  1709. "plugdev")) ;<- added system group
  1710. (home-directory "/home/your-user"))
  1711. %base-user-accounts))
  1712. ...
  1713. (services
  1714. (cons*
  1715. ...
  1716. (udev-rules-service 'fido2 libfido2 #:groups '("plugdev")))))
  1717. @end lisp
  1718. After re-configuring your system and re-logging in your graphical
  1719. session so that the new group is in effect for your user, you can verify
  1720. that your key is usable by launching:
  1721. @example
  1722. guix shell ungoogled-chromium -- chromium chrome://settings/securityKeys
  1723. @end example
  1724. and validating that the security key can be reset via the ``Reset your
  1725. security key'' menu. If it works, congratulations, your security key is
  1726. ready to be used with applications supporting two-factor authentication
  1727. (2FA).
  1728. @subsection Disabling OTP code generation for a Yubikey
  1729. @cindex disabling yubikey OTP
  1730. If you use a Yubikey security key and are irritated by the spurious OTP
  1731. codes it generates when inadvertently touching the key (e.g. causing you
  1732. to become a spammer in the @samp{#guix} channel when discussing from
  1733. your favorite IRC client!), you can disable it via the following
  1734. @command{ykman} command:
  1735. @example
  1736. guix shell python-yubikey-manager -- ykman config usb --force --disable OTP
  1737. @end example
  1738. Alternatively, you could use the @command{ykman-gui} command provided by
  1739. the @code{yubikey-manager-qt} package and either wholly disable the
  1740. @samp{OTP} application for the USB interface or, from the
  1741. @samp{Applications -> OTP} view, delete the slot 1 configuration, which
  1742. comes pre-configured with the Yubico OTP application.
  1743. @subsection Requiring a Yubikey to open a KeePassXC database
  1744. @cindex yubikey, keepassxc integration
  1745. The KeePassXC password manager application has support for Yubikeys, but
  1746. it requires installing a udev rules for your Guix System and some
  1747. configuration of the Yubico OTP application on the key.
  1748. The necessary udev rules file comes from the
  1749. @code{yubikey-personalization} package, and can be installed like:
  1750. @lisp
  1751. (use-package-modules ... security-token ...)
  1752. ...
  1753. (operating-system
  1754. ...
  1755. (services
  1756. (cons*
  1757. ...
  1758. (udev-rules-service 'yubikey yubikey-personalization))))
  1759. @end lisp
  1760. After reconfiguring your system (and reconnecting your Yubikey), you'll
  1761. then want to configure the OTP challenge/response application of your
  1762. Yubikey on its slot 2, which is what KeePassXC uses. It's easy to do so
  1763. via the Yubikey Manager graphical configuration tool, which can be
  1764. invoked with:
  1765. @example
  1766. guix shell yubikey-manager-qt -- ykman-gui
  1767. @end example
  1768. First, ensure @samp{OTP} is enabled under the @samp{Interfaces} tab,
  1769. then navigate to @samp{Applications -> OTP}, and click the
  1770. @samp{Configure} button under the @samp{Long Touch (Slot 2)} section.
  1771. Select @samp{Challenge-response}, input or generate a secret key, and
  1772. click the @samp{Finish} button. If you have a second Yubikey you'd like
  1773. to use as a backup, you should configure it the same way, using the
  1774. @emph{same} secret key.
  1775. Your Yubikey should now be detected by KeePassXC. It can be added to a
  1776. database by navigating to KeePassXC's @samp{Database -> Database
  1777. Security...} menu, then clicking the @samp{Add additional
  1778. protection...} button, then @samp{Add Challenge-Response}, selecting the
  1779. security key from the drop-down menu and clicking the @samp{OK} button
  1780. to complete the setup.
  1781. @node Dynamic DNS mcron job
  1782. @section Dynamic DNS mcron job
  1783. @cindex dynamic DNS, DDNS
  1784. If your @acronym{ISP, Internet Service Provider} only provides dynamic
  1785. IP addresses, it can be useful to setup a dynamic @acronym{DNS, Domain
  1786. Name System} (also known as @acronym{DDNS, Dynamic DNS}) service to
  1787. associate a static host name to a public but dynamic (often changing) IP
  1788. address. There are multiple existing services that can be used for
  1789. this; in the following mcron job, @url{https://duckdns.org, DuckDNS} is
  1790. used. It should also work with other dynamic DNS services that offer a
  1791. similar interface to update the IP address, such as
  1792. @url{https://freedns.afraid.org/}, with minor adjustments.
  1793. The mcron job is provided below, where @var{DOMAIN} should be
  1794. substituted for your own domain prefix, and the DuckDNS provided token
  1795. associated to @var{DOMAIN} added to the
  1796. @file{/etc/duckdns/@var{DOMAIN}.token} file.
  1797. @lisp
  1798. (define duckdns-job
  1799. ;; Update personal domain IP every 5 minutes.
  1800. #~(job '(next-minute (range 0 60 5))
  1801. #$(program-file
  1802. "duckdns-update"
  1803. (with-extensions (list guile-gnutls) ;required by (web client)
  1804. #~(begin
  1805. (use-modules (ice-9 textual-ports)
  1806. (web client))
  1807. (let ((token (string-trim-both
  1808. (call-with-input-file "/etc/duckdns/@var{DOMAIN}.token"
  1809. get-string-all)))
  1810. (query-template (string-append "https://www.duckdns.org/"
  1811. "update?domains=@var{DOMAIN}"
  1812. "&token=~a&ip=")))
  1813. (http-get (format #f query-template token))))))
  1814. "duckdns-update"
  1815. #:user "nobody"))
  1816. @end lisp
  1817. The job then needs to be added to the list of mcron jobs for your
  1818. system, using something like:
  1819. @lisp
  1820. (operating-system
  1821. (services
  1822. (cons* (service mcron-service-type
  1823. (mcron-configuration
  1824. (jobs (list duckdns-job ...))))
  1825. ...
  1826. %base-services)))
  1827. @end lisp
  1828. @node Connecting to Wireguard VPN
  1829. @section Connecting to Wireguard VPN
  1830. To connect to a Wireguard VPN server you need the kernel module to be
  1831. loaded in memory and a package providing networking tools that support
  1832. it (e.g. @code{wireguard-tools} or @code{network-manager}).
  1833. Here is a configuration example for Linux-Libre < 5.6, where the module
  1834. is out of tree and need to be loaded manually---following revisions of
  1835. the kernel have it built-in and so don't need such configuration:
  1836. @lisp
  1837. (use-modules (gnu))
  1838. (use-service-modules desktop)
  1839. (use-package-modules vpn)
  1840. (operating-system
  1841. ;; …
  1842. (services (cons (simple-service 'wireguard-module
  1843. kernel-module-loader-service-type
  1844. '("wireguard"))
  1845. %desktop-services))
  1846. (packages (cons wireguard-tools %base-packages))
  1847. (kernel-loadable-modules (list wireguard-linux-compat)))
  1848. @end lisp
  1849. After reconfiguring and restarting your system you can either use
  1850. Wireguard tools or NetworkManager to connect to a VPN server.
  1851. @subsection Using Wireguard tools
  1852. To test your Wireguard setup it is convenient to use @command{wg-quick}.
  1853. Just give it a configuration file @command{wg-quick up ./wg0.conf}; or
  1854. put that file in @file{/etc/wireguard} and run @command{wg-quick up wg0}
  1855. instead.
  1856. @quotation Note
  1857. Be warned that the author described this command as a: “[…] very quick
  1858. and dirty bash script […]”.
  1859. @end quotation
  1860. @subsection Using NetworkManager
  1861. Thanks to NetworkManager support for Wireguard we can connect to our VPN
  1862. using @command{nmcli} command. Up to this point this guide assumes that
  1863. you're using Network Manager service provided by
  1864. @code{%desktop-services}. Ortherwise you need to adjust your services
  1865. list to load @code{network-manager-service-type} and reconfigure your
  1866. Guix system.
  1867. To import your VPN configuration execute nmcli import command:
  1868. @example shell
  1869. # nmcli connection import type wireguard file wg0.conf
  1870. Connection 'wg0' (edbee261-aa5a-42db-b032-6c7757c60fde) successfully added
  1871. @end example
  1872. This will create a configuration file in
  1873. @file{/etc/NetworkManager/wg0.nmconnection}. Next connect to the
  1874. Wireguard server:
  1875. @example shell
  1876. $ nmcli connection up wg0
  1877. Connection successfully activated (D-Bus active path: /org/freedesktop/NetworkManager/ActiveConnection/6)
  1878. @end example
  1879. By default NetworkManager will connect automatically on system boot. To
  1880. change that behaviour you need to edit your config:
  1881. @example shell
  1882. # nmcli connection modify wg0 connection.autoconnect no
  1883. @end example
  1884. For more specific information about NetworkManager and wireguard
  1885. @uref{https://blogs.gnome.org/thaller/2019/03/15/wireguard-in-networkmanager/,see
  1886. this post by thaller}.
  1887. @node Customizing a Window Manager
  1888. @section Customizing a Window Manager
  1889. @cindex wm
  1890. @menu
  1891. * StumpWM::
  1892. * Session lock::
  1893. @end menu
  1894. @node StumpWM
  1895. @subsection StumpWM
  1896. @cindex stumpwm
  1897. You could install StumpWM with a Guix system by adding
  1898. @code{stumpwm} and optionally @code{`(,stumpwm "lib")}
  1899. packages to a system configuration file, e.g.@: @file{/etc/config.scm}.
  1900. An example configuration can look like this:
  1901. @lisp
  1902. (use-modules (gnu))
  1903. (use-package-modules wm)
  1904. (operating-system
  1905. ;; …
  1906. (packages (append (list sbcl stumpwm `(,stumpwm "lib"))
  1907. %base-packages)))
  1908. @end lisp
  1909. @cindex stumpwm fonts
  1910. By default StumpWM uses X11 fonts, which could be small or pixelated on
  1911. your system. You could fix this by installing StumpWM contrib Lisp
  1912. module @code{sbcl-ttf-fonts}, adding it to Guix system packages:
  1913. @lisp
  1914. (use-modules (gnu))
  1915. (use-package-modules fonts wm)
  1916. (operating-system
  1917. ;; …
  1918. (packages (append (list sbcl stumpwm `(,stumpwm "lib"))
  1919. sbcl-ttf-fonts font-dejavu %base-packages)))
  1920. @end lisp
  1921. Then you need to add the following code to a StumpWM configuration file
  1922. @file{~/.stumpwm.d/init.lisp}:
  1923. @lisp
  1924. (require :ttf-fonts)
  1925. (setf xft:*font-dirs* '("/run/current-system/profile/share/fonts/"))
  1926. (setf clx-truetype:+font-cache-filename+ (concat (getenv "HOME") "/.fonts/font-cache.sexp"))
  1927. (xft:cache-fonts)
  1928. (set-font (make-instance 'xft:font :family "DejaVu Sans Mono" :subfamily "Book" :size 11))
  1929. @end lisp
  1930. @node Session lock
  1931. @subsection Session lock
  1932. @cindex sessionlock
  1933. Depending on your environment, locking the screen of your session might come built in
  1934. or it might be something you have to set up yourself. If you use a desktop environment
  1935. like GNOME or KDE, it's usually built in. If you use a plain window manager like
  1936. StumpWM or EXWM, you might have to set it up yourself.
  1937. @menu
  1938. * Xorg::
  1939. @end menu
  1940. @node Xorg
  1941. @subsubsection Xorg
  1942. If you use Xorg, you can use the utility
  1943. @uref{https://www.mankier.com/1/xss-lock, xss-lock} to lock the screen of your session.
  1944. xss-lock is triggered by DPMS which since Xorg 1.8 is auto-detected and enabled if
  1945. ACPI is also enabled at kernel runtime.
  1946. To use xss-lock, you can simple execute it and put it into the background before
  1947. you start your window manager from e.g. your @file{~/.xsession}:
  1948. @example
  1949. xss-lock -- slock &
  1950. exec stumpwm
  1951. @end example
  1952. In this example, xss-lock uses @code{slock} to do the actual locking of the screen when
  1953. it determines it's appropriate, like when you suspend your device.
  1954. For slock to be allowed to be a screen locker for the graphical session, it needs to
  1955. be made setuid-root so it can authenticate users, and it needs a PAM service. This
  1956. can be achieved by adding the following service to your @file{config.scm}:
  1957. @lisp
  1958. (service screen-locker-services-type
  1959. (screen-locker-configuration
  1960. (name "slock")
  1961. (program (file-append slock "/bin/slock"))))
  1962. @end lisp
  1963. If you manually lock your screen, e.g. by directly calling slock when you want to lock
  1964. your screen but not suspend it, it's a good idea to notify xss-lock about this so no
  1965. confusion occurs. This can be done by executing @code{xset s activate} immediately
  1966. before you execute slock.
  1967. @node Running Guix on a Linode Server
  1968. @section Running Guix on a Linode Server
  1969. @cindex linode, Linode
  1970. To run Guix on a server hosted by @uref{https://www.linode.com, Linode},
  1971. start with a recommended Debian server. We recommend using the default
  1972. distro as a way to bootstrap Guix. Create your SSH keys.
  1973. @example
  1974. ssh-keygen
  1975. @end example
  1976. Be sure to add your SSH key for easy login to the remote server.
  1977. This is trivially done via Linode's graphical interface for adding
  1978. SSH keys. Go to your profile and click add SSH Key.
  1979. Copy into it the output of:
  1980. @example
  1981. cat ~/.ssh/<username>_rsa.pub
  1982. @end example
  1983. Power the Linode down.
  1984. In the Linode's Storage tab, resize the Debian disk to be smaller.
  1985. 30 GB free space is recommended. Then click "Add a disk", and fill
  1986. out the form with the following:
  1987. @itemize @bullet
  1988. @item
  1989. Label: "Guix"
  1990. @item
  1991. Filesystem: ext4
  1992. @item
  1993. Set it to the remaining size
  1994. @end itemize
  1995. In the Configurations tab, press "Edit" on the default Debian profile.
  1996. Under "Block Device Assignment" click "Add a Device". It should be
  1997. @file{/dev/sdc} and you can select the "Guix" disk. Save Changes.
  1998. Now "Add a Configuration", with the following:
  1999. @itemize @bullet
  2000. @item
  2001. Label: Guix
  2002. @item
  2003. Kernel:GRUB 2 (it's at the bottom! This step is @b{IMPORTANT!})
  2004. @item
  2005. Block device assignment:
  2006. @item
  2007. @file{/dev/sda}: Guix
  2008. @item
  2009. @file{/dev/sdb}: swap
  2010. @item
  2011. Root device: @file{/dev/sda}
  2012. @item
  2013. Turn off all the filesystem/boot helpers
  2014. @end itemize
  2015. Now power it back up, booting with the Debian configuration. Once it's
  2016. running, ssh to your server via @code{ssh
  2017. root@@@var{<your-server-IP-here>}}. (You can find your server IP address in
  2018. your Linode Summary section.) Now you can run the "install guix from
  2019. @pxref{Binary Installation,,, guix, GNU Guix}" steps:
  2020. @example
  2021. sudo apt-get install gpg
  2022. wget https://sv.gnu.org/people/viewgpg.php?user_id=15145 -qO - | gpg --import -
  2023. wget https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh
  2024. chmod +x guix-install.sh
  2025. ./guix-install.sh
  2026. guix pull
  2027. @end example
  2028. Now it's time to write out a config for the server. The key information
  2029. is below. Save the resulting file as @file{guix-config.scm}.
  2030. @lisp
  2031. (use-modules (gnu)
  2032. (guix modules))
  2033. (use-service-modules networking
  2034. ssh)
  2035. (use-package-modules admin
  2036. certs
  2037. package-management
  2038. ssh
  2039. tls)
  2040. (operating-system
  2041. (host-name "my-server")
  2042. (timezone "America/New_York")
  2043. (locale "en_US.UTF-8")
  2044. ;; This goofy code will generate the grub.cfg
  2045. ;; without installing the grub bootloader on disk.
  2046. (bootloader (bootloader-configuration
  2047. (bootloader
  2048. (bootloader
  2049. (inherit grub-bootloader)
  2050. (installer #~(const #true))))))
  2051. (file-systems (cons (file-system
  2052. (device "/dev/sda")
  2053. (mount-point "/")
  2054. (type "ext4"))
  2055. %base-file-systems))
  2056. (swap-devices (list "/dev/sdb"))
  2057. (initrd-modules (cons "virtio_scsi" ; Needed to find the disk
  2058. %base-initrd-modules))
  2059. (users (cons (user-account
  2060. (name "janedoe")
  2061. (group "users")
  2062. ;; Adding the account to the "wheel" group
  2063. ;; makes it a sudoer.
  2064. (supplementary-groups '("wheel"))
  2065. (home-directory "/home/janedoe"))
  2066. %base-user-accounts))
  2067. (packages (cons* nss-certs ;for HTTPS access
  2068. openssh-sans-x
  2069. %base-packages))
  2070. (services (cons*
  2071. (service dhcp-client-service-type)
  2072. (service openssh-service-type
  2073. (openssh-configuration
  2074. (openssh openssh-sans-x)
  2075. (password-authentication? #false)
  2076. (authorized-keys
  2077. `(("janedoe" ,(local-file "janedoe_rsa.pub"))
  2078. ("root" ,(local-file "janedoe_rsa.pub"))))))
  2079. %base-services)))
  2080. @end lisp
  2081. Replace the following fields in the above configuration:
  2082. @lisp
  2083. (host-name "my-server") ; replace with your server name
  2084. ; if you chose a linode server outside the U.S., then
  2085. ; use tzselect to find a correct timezone string
  2086. (timezone "America/New_York") ; if needed replace timezone
  2087. (name "janedoe") ; replace with your username
  2088. ("janedoe" ,(local-file "janedoe_rsa.pub")) ; replace with your ssh key
  2089. ("root" ,(local-file "janedoe_rsa.pub")) ; replace with your ssh key
  2090. @end lisp
  2091. The last line in the above example lets you log into the server as root
  2092. and set the initial root password (see the note at the end of this
  2093. recipe about root login). After you have done this, you may
  2094. delete that line from your configuration and reconfigure to prevent root
  2095. login.
  2096. Copy your ssh public key (eg: @file{~/.ssh/id_rsa.pub}) as
  2097. @file{@var{<your-username-here>}_rsa.pub} and put
  2098. @file{guix-config.scm} in the same directory. In a new terminal run
  2099. these commands.
  2100. @example
  2101. sftp root@@<remote server ip address>
  2102. put /path/to/files/<username>_rsa.pub .
  2103. put /path/to/files/guix-config.scm .
  2104. @end example
  2105. In your first terminal, mount the guix drive:
  2106. @example
  2107. mkdir /mnt/guix
  2108. mount /dev/sdc /mnt/guix
  2109. @end example
  2110. Due to the way we set up the bootloader section of the guix-config.scm,
  2111. only the grub configuration file will be installed. So, we need to copy
  2112. over some of the other GRUB stuff already installed on the Debian system:
  2113. @example
  2114. mkdir -p /mnt/guix/boot/grub
  2115. cp -r /boot/grub/* /mnt/guix/boot/grub/
  2116. @end example
  2117. Now initialize the Guix installation:
  2118. @example
  2119. guix system init guix-config.scm /mnt/guix
  2120. @end example
  2121. Ok, power it down!
  2122. Now from the Linode console, select boot and select "Guix".
  2123. Once it boots, you should be able to log in via SSH! (The server config
  2124. will have changed though.) You may encounter an error like:
  2125. @example
  2126. $ ssh root@@<server ip address>
  2127. @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
  2128. @ WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! @
  2129. @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
  2130. IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY!
  2131. Someone could be eavesdropping on you right now (man-in-the-middle attack)!
  2132. It is also possible that a host key has just been changed.
  2133. The fingerprint for the ECDSA key sent by the remote host is
  2134. SHA256:0B+wp33w57AnKQuHCvQP0+ZdKaqYrI/kyU7CfVbS7R4.
  2135. Please contact your system administrator.
  2136. Add correct host key in /home/joshua/.ssh/known_hosts to get rid of this message.
  2137. Offending ECDSA key in /home/joshua/.ssh/known_hosts:3
  2138. ECDSA host key for 198.58.98.76 has changed and you have requested strict checking.
  2139. Host key verification failed.
  2140. @end example
  2141. Either delete @file{~/.ssh/known_hosts} file, or delete the offending line
  2142. starting with your server IP address.
  2143. Be sure to set your password and root's password.
  2144. @example
  2145. ssh root@@<remote ip address>
  2146. passwd ; for the root password
  2147. passwd <username> ; for the user password
  2148. @end example
  2149. You may not be able to run the above commands at this point. If you
  2150. have issues remotely logging into your linode box via SSH, then you may
  2151. still need to set your root and user password initially by clicking on
  2152. the ``Launch Console'' option in your linode. Choose the ``Glish''
  2153. instead of ``Weblish''. Now you should be able to ssh into the machine.
  2154. Hooray! At this point you can shut down the server, delete the
  2155. Debian disk, and resize the Guix to the rest of the size.
  2156. Congratulations!
  2157. By the way, if you save it as a disk image right at this point, you'll
  2158. have an easy time spinning up new Guix images! You may need to
  2159. down-size the Guix image to 6144MB, to save it as an image. Then you
  2160. can resize it again to the max size.
  2161. @node Running Guix on a Kimsufi Server
  2162. @section Running Guix on a Kimsufi Server
  2163. @cindex kimsufi, Kimsufi, OVH
  2164. To run Guix on a server hosted by @uref{https://www.kimsufi.com/,
  2165. Kimsufi}, click on the netboot tab then select rescue64-pro and restart.
  2166. OVH will email you the credentials required to ssh into a Debian system.
  2167. Now you can run the "install guix from @pxref{Binary Installation,,,
  2168. guix, GNU Guix}" steps:
  2169. @example
  2170. wget https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh
  2171. chmod +x guix-install.sh
  2172. ./guix-install.sh
  2173. guix pull
  2174. @end example
  2175. Partition the drives and format them, first stop the raid array:
  2176. @example
  2177. mdadm --stop /dev/md127
  2178. mdadm --zero-superblock /dev/sda2 /dev/sdb2
  2179. @end example
  2180. Then wipe the disks and set up the partitions, we will create
  2181. a RAID 1 array.
  2182. @example
  2183. wipefs -a /dev/sda
  2184. wipefs -a /dev/sdb
  2185. parted /dev/sda --align=opt -s -m -- mklabel gpt
  2186. parted /dev/sda --align=opt -s -m -- \
  2187. mkpart bios_grub 1049kb 512MiB \
  2188. set 1 bios_grub on
  2189. parted /dev/sda --align=opt -s -m -- \
  2190. mkpart primary 512MiB -512MiB
  2191. set 2 raid on
  2192. parted /dev/sda --align=opt -s -m -- mkpart primary linux-swap 512MiB 100%
  2193. parted /dev/sdb --align=opt -s -m -- mklabel gpt
  2194. parted /dev/sdb --align=opt -s -m -- \
  2195. mkpart bios_grub 1049kb 512MiB \
  2196. set 1 bios_grub on
  2197. parted /dev/sdb --align=opt -s -m -- \
  2198. mkpart primary 512MiB -512MiB \
  2199. set 2 raid on
  2200. parted /dev/sdb --align=opt -s -m -- mkpart primary linux-swap 512MiB 100%
  2201. @end example
  2202. Create the array:
  2203. @example
  2204. mdadm --create /dev/md127 --level=1 --raid-disks=2 \
  2205. --metadata=0.90 /dev/sda2 /dev/sdb2
  2206. @end example
  2207. Now create file systems on the relevant partitions, first the boot
  2208. partitions:
  2209. @example
  2210. mkfs.ext4 /dev/sda1
  2211. mkfs.ext4 /dev/sdb1
  2212. @end example
  2213. Then the root partition:
  2214. @example
  2215. mkfs.ext4 /dev/md127
  2216. @end example
  2217. Initialize the swap partitions:
  2218. @example
  2219. mkswap /dev/sda3
  2220. swapon /dev/sda3
  2221. mkswap /dev/sdb3
  2222. swapon /dev/sdb3
  2223. @end example
  2224. Mount the guix drive:
  2225. @example
  2226. mkdir /mnt/guix
  2227. mount /dev/md127 /mnt/guix
  2228. @end example
  2229. Now is time to write an operating system declaration @file{os.scm} file;
  2230. here is a sample:
  2231. @lisp
  2232. (use-modules (gnu) (guix))
  2233. (use-service-modules networking ssh vpn virtualization sysctl admin mcron)
  2234. (use-package-modules ssh certs tls tmux vpn virtualization)
  2235. (operating-system
  2236. (host-name "kimsufi")
  2237. (bootloader (bootloader-configuration
  2238. (bootloader grub-bootloader)
  2239. (targets (list "/dev/sda" "/dev/sdb"))
  2240. (terminal-outputs '(console))))
  2241. ;; Add a kernel module for RAID-1 (aka. "mirror").
  2242. (initrd-modules (cons* "raid1" %base-initrd-modules))
  2243. (mapped-devices
  2244. (list (mapped-device
  2245. (source (list "/dev/sda2" "/dev/sdb2"))
  2246. (target "/dev/md127")
  2247. (type raid-device-mapping))))
  2248. (swap-devices
  2249. (list (swap-space
  2250. (target "/dev/sda3"))
  2251. (swap-space
  2252. (target "/dev/sdb3"))))
  2253. (issue
  2254. ;; Default contents for /etc/issue.
  2255. "\
  2256. This is the GNU system at Kimsufi. Welcome.\n")
  2257. (file-systems (cons* (file-system
  2258. (mount-point "/")
  2259. (device "/dev/md127")
  2260. (type "ext4")
  2261. (dependencies mapped-devices))
  2262. %base-file-systems))
  2263. (users (cons (user-account
  2264. (name "guix")
  2265. (comment "guix")
  2266. (group "users")
  2267. (supplementary-groups '("wheel"))
  2268. (home-directory "/home/guix"))
  2269. %base-user-accounts))
  2270. (sudoers-file
  2271. (plain-file "sudoers" "\
  2272. root ALL=(ALL) ALL
  2273. %wheel ALL=(ALL) ALL
  2274. guix ALL=(ALL) NOPASSWD:ALL\n"))
  2275. ;; Globally-installed packages.
  2276. (packages (cons* tmux nss-certs gnutls wireguard-tools %base-packages))
  2277. (services
  2278. (cons*
  2279. (service static-networking-service-type
  2280. (list (static-networking
  2281. (addresses (list (network-address
  2282. (device "enp3s0")
  2283. (value "@var{server-ip-address}/24"))))
  2284. (routes (list (network-route
  2285. (destination "default")
  2286. (gateway "@var{server-gateway}"))))
  2287. (name-servers '("213.186.33.99")))))
  2288. (service unattended-upgrade-service-type)
  2289. (service openssh-service-type
  2290. (openssh-configuration
  2291. (openssh openssh-sans-x)
  2292. (permit-root-login #f)
  2293. (authorized-keys
  2294. `(("guix" ,(plain-file "@var{ssh-key-name.pub}"
  2295. "@var{ssh-public-key-content}"))))))
  2296. (modify-services %base-services
  2297. (sysctl-service-type
  2298. config =>
  2299. (sysctl-configuration
  2300. (settings (append '(("net.ipv6.conf.all.autoconf" . "0")
  2301. ("net.ipv6.conf.all.accept_ra" . "0"))
  2302. %default-sysctl-settings))))))))
  2303. @end lisp
  2304. Don't forget to substitute the @var{server-ip-address},
  2305. @var{server-gateway}, @var{ssh-key-name} and
  2306. @var{ssh-public-key-content} variables with your own values.
  2307. The gateway is the last usable IP in your block so if you have a server
  2308. with an IP of @samp{37.187.79.10} then its gateway will be
  2309. @samp{37.187.79.254}.
  2310. Transfer your operating system declaration @file{os.scm} file on the
  2311. server via the @command{scp} or @command{sftp} commands.
  2312. Now all that is left is to install Guix with a @code{guix system init}
  2313. and restart.
  2314. However we first need to set up a chroot, because the root partition of
  2315. the rescue system is mounted on an aufs partition and if you try to
  2316. install Guix it will fail at the GRUB install step complaining about the
  2317. canonical path of "aufs".
  2318. Install packages that will be used in the chroot:
  2319. @example
  2320. guix install bash-static parted util-linux-with-udev coreutils guix
  2321. @end example
  2322. Then run the following to create directories needed for the chroot:
  2323. @example
  2324. cd /mnt && \
  2325. mkdir -p bin etc gnu/store root/.guix-profile/ root/.config/guix/current \
  2326. var/guix proc sys dev
  2327. @end example
  2328. Copy the host resolv.conf in the chroot:
  2329. @example
  2330. cp /etc/resolv.conf etc/
  2331. @end example
  2332. Mount block devices, the store and its database and the current guix config:
  2333. @example
  2334. mount --rbind /proc /mnt/proc
  2335. mount --rbind /sys /mnt/sys
  2336. mount --rbind /dev /mnt/dev
  2337. mount --rbind /var/guix/ var/guix/
  2338. mount --rbind /gnu/store gnu/store/
  2339. mount --rbind /root/.config/ root/.config/
  2340. mount --rbind /root/.guix-profile/bin/ bin
  2341. mount --rbind /root/.guix-profile root/.guix-profile/
  2342. @end example
  2343. Chroot in /mnt and install the system:
  2344. @example
  2345. chroot /mnt/ /bin/bash
  2346. guix system init /root/os.scm /guix
  2347. @end example
  2348. Finally, from the web user interface (UI), change @samp{netboot} to
  2349. @samp{boot to disk} and restart (also from the web UI).
  2350. Wait a few minutes and try to ssh with @code{ssh
  2351. guix@@@var{server-ip-address>} -i @var{path-to-your-ssh-key}}
  2352. You should have a Guix system up and running on Kimsufi;
  2353. congratulations!
  2354. @node Setting up a bind mount
  2355. @section Setting up a bind mount
  2356. To bind mount a file system, one must first set up some definitions
  2357. before the @code{operating-system} section of the system definition. In
  2358. this example we will bind mount a folder from a spinning disk drive to
  2359. @file{/tmp}, to save wear and tear on the primary SSD, without
  2360. dedicating an entire partition to be mounted as @file{/tmp}.
  2361. First, the source drive that hosts the folder we wish to bind mount
  2362. should be defined, so that the bind mount can depend on it.
  2363. @lisp
  2364. (define source-drive ;; "source-drive" can be named anything you want.
  2365. (file-system
  2366. (device (uuid "UUID goes here"))
  2367. (mount-point "/path-to-spinning-disk-goes-here")
  2368. (type "ext4"))) ;; Make sure to set this to the appropriate type for your drive.
  2369. @end lisp
  2370. The source folder must also be defined, so that guix will know it's not
  2371. a regular block device, but a folder.
  2372. @lisp
  2373. (define (%source-directory) "/path-to-spinning-disk-goes-here/tmp") ;; "source-directory" can be named any valid variable name.
  2374. @end lisp
  2375. Finally, inside the @code{file-systems} definition, we must add the
  2376. mount itself.
  2377. @lisp
  2378. (file-systems (cons*
  2379. ...<other drives omitted for clarity>...
  2380. source-drive ;; Must match the name you gave the source drive in the earlier definition.
  2381. (file-system
  2382. (device (%source-directory)) ;; Make sure "source-directory" matches your earlier definition.
  2383. (mount-point "/tmp")
  2384. (type "none") ;; We are mounting a folder, not a partition, so this type needs to be "none"
  2385. (flags '(bind-mount))
  2386. (dependencies (list source-drive)) ;; Ensure "source-drive" matches what you've named the variable for the drive.
  2387. )
  2388. ...<other drives omitted for clarity>...
  2389. ))
  2390. @end lisp
  2391. @node Getting substitutes from Tor
  2392. @section Getting substitutes from Tor
  2393. Guix daemon can use a HTTP proxy to get substitutes, here we are
  2394. configuring it to get them via Tor.
  2395. @quotation Warning
  2396. @emph{Not all} Guix daemon's traffic will go through Tor! Only
  2397. HTTP/HTTPS will get proxied; FTP, Git protocol, SSH, etc connections
  2398. will still go through the clearnet. Again, this configuration isn't
  2399. foolproof some of your traffic won't get routed by Tor at all. Use it
  2400. at your own risk.
  2401. Also note that the procedure described here applies only to package
  2402. substitution. When you update your guix distribution with
  2403. @command{guix pull}, you still need to use @command{torsocks} if
  2404. you want to route the connection to guix's git repository servers
  2405. through Tor.
  2406. @end quotation
  2407. Guix's substitute server is available as a Onion service, if you want
  2408. to use it to get your substitutes through Tor configure your system as
  2409. follow:
  2410. @lisp
  2411. (use-modules (gnu))
  2412. (use-service-module base networking)
  2413. (operating-system
  2414. (services
  2415. (cons
  2416. (service tor-service-type
  2417. (tor-configuration
  2418. (config-file (plain-file "tor-config"
  2419. "HTTPTunnelPort 127.0.0.1:9250"))))
  2420. (modify-services %base-services
  2421. (guix-service-type
  2422. config => (guix-configuration
  2423. (inherit config)
  2424. ;; ci.guix.gnu.org's Onion service
  2425. (substitute-urls
  2426. "@value{SUBSTITUTE-TOR-URL}")
  2427. (http-proxy "http://localhost:9250")))))))
  2428. @end lisp
  2429. This will keep a tor process running that provides a HTTP CONNECT tunnel
  2430. which will be used by @command{guix-daemon}. The daemon can use other
  2431. protocols than HTTP(S) to get remote resources, request using those
  2432. protocols won't go through Tor since we are only setting a HTTP tunnel
  2433. here. Note that @code{substitutes-urls} is using HTTPS and not HTTP or
  2434. it won't work, that's a limitation of Tor's tunnel; you may want to use
  2435. @command{privoxy} instead to avoid such limitations.
  2436. If you don't want to always get substitutes through Tor but using it just
  2437. some of the times, then skip the @code{guix-configuration}. When you
  2438. want to get a substitute from the Tor tunnel run:
  2439. @example
  2440. sudo herd set-http-proxy guix-daemon http://localhost:9250
  2441. guix build \
  2442. --substitute-urls=@value{SUBSTITUTE-TOR-URL} @dots{}
  2443. @end example
  2444. @node Setting up NGINX with Lua
  2445. @section Setting up NGINX with Lua
  2446. @cindex nginx, lua, openresty, resty
  2447. NGINX could be extended with Lua scripts.
  2448. Guix provides NGINX service with ability to load Lua module and specific
  2449. Lua packages, and reply to requests by evaluating Lua scripts.
  2450. The following example demonstrates system definition with configuration
  2451. to evaluate @file{index.lua} Lua script on HTTP request to
  2452. @uref{http://localhost/hello} endpoint:
  2453. @example
  2454. local shell = require "resty.shell"
  2455. local stdin = ""
  2456. local timeout = 1000 -- ms
  2457. local max_size = 4096 -- byte
  2458. local ok, stdout, stderr, reason, status =
  2459. shell.run([[/run/current-system/profile/bin/ls /tmp]], stdin, timeout, max_size)
  2460. ngx.say(stdout)
  2461. @end example
  2462. @lisp
  2463. (use-modules (gnu))
  2464. (use-service-modules #;… web)
  2465. (use-package-modules #;… lua)
  2466. (operating-system
  2467. ;; …
  2468. (services
  2469. ;; …
  2470. (service nginx-service-type
  2471. (nginx-configuration
  2472. (modules
  2473. (list
  2474. (file-append nginx-lua-module "/etc/nginx/modules/ngx_http_lua_module.so")))
  2475. (lua-package-path (list lua-resty-core
  2476. lua-resty-lrucache
  2477. lua-resty-signal
  2478. lua-tablepool
  2479. lua-resty-shell))
  2480. (lua-package-cpath (list lua-resty-signal))
  2481. (server-blocks
  2482. (list (nginx-server-configuration
  2483. (server-name '("localhost"))
  2484. (listen '("80"))
  2485. (root "/etc")
  2486. (locations (list
  2487. (nginx-location-configuration
  2488. (uri "/hello")
  2489. (body (list #~(format #f "content_by_lua_file ~s;"
  2490. #$(local-file "index.lua"))))))))))))))
  2491. @end lisp
  2492. @node Music Server with Bluetooth Audio
  2493. @section Music Server with Bluetooth Audio
  2494. @cindex mpd
  2495. @cindex music server, headless
  2496. @cindex bluetooth, ALSA configuration
  2497. MPD, the Music Player Daemon, is a flexible server-side application for
  2498. playing music. Client programs on different machines on the network ---
  2499. a mobile phone, a laptop, a desktop workstation --- can connect to it to
  2500. control the playback of audio files from your local music collection.
  2501. MPD decodes the audio files and plays them back on one or many outputs.
  2502. By default MPD will play to the default audio device. In the example
  2503. below we make things a little more interesting by setting up a headless
  2504. music server. There will be no graphical user interface, no Pulseaudio
  2505. daemon, and no local audio output. Instead we will configure MPD with
  2506. two outputs: a bluetooth speaker and a web server to serve audio streams
  2507. to any streaming media player.
  2508. Bluetooth is often rather frustrating to set up. You will have to pair
  2509. your Bluetooth device and make sure that the device is automatically
  2510. connected as soon as it powers on. The Bluetooth system service
  2511. returned by the @code{bluetooth-service} procedure provides the
  2512. infrastructure needed to set this up.
  2513. Reconfigure your system with at least the following services and
  2514. packages:
  2515. @lisp
  2516. (operating-system
  2517. ;; …
  2518. (packages (cons* bluez bluez-alsa
  2519. %base-packages))
  2520. (services
  2521. ;; …
  2522. (dbus-service #:services (list bluez-alsa))
  2523. (bluetooth-service #:auto-enable? #t)))
  2524. @end lisp
  2525. Start the @code{bluetooth} service and then use @command{bluetoothctl}
  2526. to scan for Bluetooth devices. Try to identify your Bluetooth speaker
  2527. and pick out its device ID from the resulting list of devices that is
  2528. indubitably dominated by a baffling smorgasbord of your neighbors' home
  2529. automation gizmos. This only needs to be done once:
  2530. @example
  2531. $ bluetoothctl
  2532. [NEW] Controller 00:11:22:33:95:7F BlueZ 5.40 [default]
  2533. [bluetooth]# power on
  2534. [bluetooth]# Changing power on succeeded
  2535. [bluetooth]# agent on
  2536. [bluetooth]# Agent registered
  2537. [bluetooth]# default-agent
  2538. [bluetooth]# Default agent request successful
  2539. [bluetooth]# scan on
  2540. [bluetooth]# Discovery started
  2541. [CHG] Controller 00:11:22:33:95:7F Discovering: yes
  2542. [NEW] Device AA:BB:CC:A4:AA:CD My Bluetooth Speaker
  2543. [NEW] Device 44:44:FF:2A:20:DC My Neighbor's TV
  2544. @dots{}
  2545. [bluetooth]# pair AA:BB:CC:A4:AA:CD
  2546. Attempting to pair with AA:BB:CC:A4:AA:CD
  2547. [CHG] Device AA:BB:CC:A4:AA:CD Connected: yes
  2548. [My Bluetooth Speaker]# [CHG] Device AA:BB:CC:A4:AA:CD UUIDs: 0000110b-0000-1000-8000-00xxxxxxxxxx
  2549. [CHG] Device AA:BB:CC:A4:AA:CD UUIDs: 0000110c-0000-1000-8000-00xxxxxxxxxx
  2550. [CHG] Device AA:BB:CC:A4:AA:CD UUIDs: 0000110e-0000-1000-8000-00xxxxxxxxxx
  2551. [CHG] Device AA:BB:CC:A4:AA:CD Paired: yes
  2552. Pairing successful
  2553. [CHG] Device AA:BB:CC:A4:AA:CD Connected: no
  2554. [bluetooth]#
  2555. [bluetooth]# trust AA:BB:CC:A4:AA:CD
  2556. [bluetooth]# [CHG] Device AA:BB:CC:A4:AA:CD Trusted: yes
  2557. Changing AA:BB:CC:A4:AA:CD trust succeeded
  2558. [bluetooth]#
  2559. [bluetooth]# connect AA:BB:CC:A4:AA:CD
  2560. Attempting to connect to AA:BB:CC:A4:AA:CD
  2561. [bluetooth]# [CHG] Device AA:BB:CC:A4:AA:CD RSSI: -63
  2562. [CHG] Device AA:BB:CC:A4:AA:CD Connected: yes
  2563. Connection successful
  2564. [My Bluetooth Speaker]# scan off
  2565. [CHG] Device AA:BB:CC:A4:AA:CD RSSI is nil
  2566. Discovery stopped
  2567. [CHG] Controller 00:11:22:33:95:7F Discovering: no
  2568. @end example
  2569. Congratulations, you can now automatically connect to your Bluetooth
  2570. speaker!
  2571. It is now time to configure ALSA to use the @emph{bluealsa} Bluetooth
  2572. module, so that you can define an ALSA pcm device corresponding to your
  2573. Bluetooth speaker. For a headless server using @emph{bluealsa} with a
  2574. fixed Bluetooth device is likely simpler than configuring Pulseaudio and
  2575. its stream switching behavior. We configure ALSA by crafting a custom
  2576. @code{alsa-configuration} for the @code{alsa-service-type}. The
  2577. configuration will declare a @code{pcm} type @code{bluealsa} from the
  2578. @code{bluealsa} module provided by the @code{bluez-alsa} package, and
  2579. then define a @code{pcm} device of that type for your Bluetooth speaker.
  2580. All that is left then is to make MPD send audio data to this ALSA
  2581. device. We also add a secondary MPD output that makes the currently
  2582. played audio files available as a stream through a web server on port
  2583. 8080. When enabled a device on the network could listen to the audio
  2584. stream by connecting any capable media player to the HTTP server on port
  2585. 8080, independent of the status of the Bluetooth speaker.
  2586. What follows is the outline of an @code{operating-system} declaration
  2587. that should accomplish the above-mentioned tasks:
  2588. @lisp
  2589. (use-modules (gnu))
  2590. (use-service-modules audio dbus sound #;… etc)
  2591. (use-package-modules audio linux #;… etc)
  2592. (operating-system
  2593. ;; …
  2594. (packages (cons* bluez bluez-alsa
  2595. %base-packages))
  2596. (services
  2597. ;; …
  2598. (service mpd-service-type
  2599. (mpd-configuration
  2600. (user "your-username")
  2601. (music-dir "/path/to/your/music")
  2602. (address "192.168.178.20")
  2603. (outputs (list (mpd-output
  2604. (type "alsa")
  2605. (name "MPD")
  2606. (extra-options
  2607. ;; Use the same name as in the ALSA
  2608. ;; configuration below.
  2609. '((device . "pcm.btspeaker"))))
  2610. (mpd-output
  2611. (type "httpd")
  2612. (name "streaming")
  2613. (enabled? #false)
  2614. (always-on? #true)
  2615. (tags? #true)
  2616. (mixer-type 'null)
  2617. (extra-options
  2618. '((encoder . "vorbis")
  2619. (port . "8080")
  2620. (bind-to-address . "192.168.178.20")
  2621. (max-clients . "0") ;no limit
  2622. (quality . "5.0")
  2623. (format . "44100:16:1"))))))))
  2624. (dbus-service #:services (list bluez-alsa))
  2625. (bluetooth-service #:auto-enable? #t)
  2626. (service alsa-service-type
  2627. (alsa-configuration
  2628. (pulseaudio? #false) ;we don't need it
  2629. (extra-options
  2630. #~(string-append "\
  2631. # Declare Bluetooth audio device type \"bluealsa\" from bluealsa module
  2632. pcm_type.bluealsa @{
  2633. lib \"" #$(file-append bluez-alsa "/lib/alsa-lib/libasound_module_pcm_bluealsa.so") "\"
  2634. @}
  2635. # Declare control device type \"bluealsa\" from the same module
  2636. ctl_type.bluealsa @{
  2637. lib \"" #$(file-append bluez-alsa "/lib/alsa-lib/libasound_module_ctl_bluealsa.so") "\"
  2638. @}
  2639. # Define the actual Bluetooth audio device.
  2640. pcm.btspeaker @{
  2641. type bluealsa
  2642. device \"AA:BB:CC:A4:AA:CD\" # unique device identifier
  2643. profile \"a2dp\"
  2644. @}
  2645. # Define an associated controller.
  2646. ctl.btspeaker @{
  2647. type bluealsa
  2648. @}
  2649. "))))))
  2650. @end lisp
  2651. Enjoy the music with the MPD client of your choice or a media player
  2652. capable of streaming via HTTP!
  2653. @c *********************************************************************
  2654. @node Containers
  2655. @chapter Containers
  2656. The kernel Linux provides a number of shared facilities that are
  2657. available to processes in the system. These facilities include a shared
  2658. view on the file system, other processes, network devices, user and
  2659. group identities, and a few others. Since Linux 3.19 a user can choose
  2660. to @emph{unshare} some of these shared facilities for selected
  2661. processes, providing them (and their child processes) with a different
  2662. view on the system.
  2663. A process with an unshared @code{mount} namespace, for example, has its
  2664. own view on the file system --- it will only be able to see directories
  2665. that have been explicitly bound in its mount namespace. A process with
  2666. its own @code{proc} namespace will consider itself to be the only
  2667. process running on the system, running as PID 1.
  2668. Guix uses these kernel features to provide fully isolated environments
  2669. and even complete Guix System containers, lightweight virtual machines
  2670. that share the host system's kernel. This feature comes in especially
  2671. handy when using Guix on a foreign distribution to prevent interference
  2672. from foreign libraries or configuration files that are available
  2673. system-wide.
  2674. @menu
  2675. * Guix Containers:: Perfectly isolated environments
  2676. * Guix System Containers:: A system inside your system
  2677. @end menu
  2678. @node Guix Containers
  2679. @section Guix Containers
  2680. The easiest way to get started is to use @command{guix shell} with the
  2681. @option{--container} option. @xref{Invoking guix shell,,, guix, GNU
  2682. Guix Reference Manual} for a reference of valid options.
  2683. The following snippet spawns a minimal shell process with most
  2684. namespaces unshared from the system. The current working directory is
  2685. visible to the process, but anything else on the file system is
  2686. unavailable. This extreme isolation can be very useful when you want to
  2687. rule out any sort of interference from environment variables, globally
  2688. installed libraries, or configuration files.
  2689. @example
  2690. guix shell --container
  2691. @end example
  2692. It is a bleak environment, barren, desolate. You will find that not
  2693. even the GNU coreutils are available here, so to explore this deserted
  2694. wasteland you need to use built-in shell commands. Even the usually
  2695. gigantic @file{/gnu/store} directory is reduced to a faint shadow of
  2696. itself.
  2697. @example sh
  2698. $ echo /gnu/store/*
  2699. /gnu/store/@dots{}-gcc-10.3.0-lib
  2700. /gnu/store/@dots{}-glibc-2.33
  2701. /gnu/store/@dots{}-bash-static-5.1.8
  2702. /gnu/store/@dots{}-ncurses-6.2.20210619
  2703. /gnu/store/@dots{}-bash-5.1.8
  2704. /gnu/store/@dots{}-profile
  2705. /gnu/store/@dots{}-readline-8.1.1
  2706. @end example
  2707. @cindex exiting a container
  2708. There isn't much you can do in an environment like this other than
  2709. exiting it. You can use @key{^D} or @command{exit} to terminate this
  2710. limited shell environment.
  2711. @cindex exposing directories, container
  2712. @cindex sharing directories, container
  2713. @cindex mapping locations, container
  2714. You can make other directories available inside of the container
  2715. environment; use @option{--expose=DIRECTORY} to bind-mount the given
  2716. directory as a read-only location inside the container, or use
  2717. @option{--share=DIRECTORY} to make the location writable. With an
  2718. additional mapping argument after the directory name you can control the
  2719. name of the directory inside the container. In the following example we
  2720. map @file{/etc} on the host system to @file{/the/host/etc} inside a
  2721. container in which the GNU coreutils are installed.
  2722. @example sh
  2723. $ guix shell --container --share=/etc=/the/host/etc coreutils
  2724. $ ls /the/host/etc
  2725. @end example
  2726. Similarly, you can prevent the current working directory from being
  2727. mapped into the container with the @option{--no-cwd} option. Another
  2728. good idea is to create a dedicated directory that will serve as the
  2729. container's home directory, and spawn the container shell from that
  2730. directory.
  2731. @cindex hide system libraries, container
  2732. @cindex avoid ABI mismatch, container
  2733. On a foreign system a container environment can be used to compile
  2734. software that cannot possibly be linked with system libraries or with
  2735. the system's compiler toolchain. A common use-case in a research
  2736. context is to install packages from within an R session. Outside of a
  2737. container environment there is a good chance that the foreign compiler
  2738. toolchain and incompatible system libraries are found first, resulting
  2739. in incompatible binaries that cannot be used by R. In a container shell
  2740. this problem disappears, as system libraries and executables simply
  2741. aren't available due to the unshared @code{mount} namespace.
  2742. Let's take a comprehensive manifest providing a comfortable development
  2743. environment for use with R:
  2744. @lisp
  2745. (specifications->manifest
  2746. (list "r-minimal"
  2747. ;; base packages
  2748. "bash-minimal"
  2749. "glibc-locales"
  2750. "nss-certs"
  2751. ;; Common command line tools lest the container is too empty.
  2752. "coreutils"
  2753. "grep"
  2754. "which"
  2755. "wget"
  2756. "sed"
  2757. ;; R markdown tools
  2758. "pandoc"
  2759. ;; Toolchain and common libraries for "install.packages"
  2760. "gcc-toolchain@@10"
  2761. "gfortran-toolchain"
  2762. "gawk"
  2763. "tar"
  2764. "gzip"
  2765. "unzip"
  2766. "make"
  2767. "cmake"
  2768. "pkg-config"
  2769. "cairo"
  2770. "libxt"
  2771. "openssl"
  2772. "curl"
  2773. "zlib"))
  2774. @end lisp
  2775. Let's use this to run R inside a container environment. For convenience
  2776. we share the @code{net} namespace to use the host system's network
  2777. interfaces. Now we can build R packages from source the traditional way
  2778. without having to worry about ABI mismatch or incompatibilities.
  2779. @example sh
  2780. $ guix shell --container --network --manifest=manifest.scm -- R
  2781. R version 4.2.1 (2022-06-23) -- "Funny-Looking Kid"
  2782. Copyright (C) 2022 The R Foundation for Statistical Computing
  2783. @dots{}
  2784. > e <- Sys.getenv("GUIX_ENVIRONMENT")
  2785. > Sys.setenv(GIT_SSL_CAINFO=paste0(e, "/etc/ssl/certs/ca-certificates.crt"))
  2786. > Sys.setenv(SSL_CERT_FILE=paste0(e, "/etc/ssl/certs/ca-certificates.crt"))
  2787. > Sys.setenv(SSL_CERT_DIR=paste0(e, "/etc/ssl/certs"))
  2788. > install.packages("Cairo", lib=paste0(getwd()))
  2789. @dots{}
  2790. * installing *source* package 'Cairo' ...
  2791. @dots{}
  2792. * DONE (Cairo)
  2793. The downloaded source packages are in
  2794. '/tmp/RtmpCuwdwM/downloaded_packages'
  2795. > library("Cairo", lib=getwd())
  2796. > # success!
  2797. @end example
  2798. Using container shells is fun, but they can become a little cumbersome
  2799. when you want to go beyond just a single interactive process. Some
  2800. tasks become a lot easier when they sit on the rock solid foundation of
  2801. a proper Guix System and its rich set of system services. The next
  2802. section shows you how to launch a complete Guix System inside of a
  2803. container.
  2804. @node Guix System Containers
  2805. @section Guix System Containers
  2806. The Guix System provides a wide array of interconnected system services
  2807. that are configured declaratively to form a dependable stateless GNU
  2808. System foundation for whatever tasks you throw at it. Even when using
  2809. Guix on a foreign distribution you can benefit from the design of Guix
  2810. System by running a system instance as a container. Using the same
  2811. kernel features of unshared namespaces mentioned in the previous
  2812. section, the resulting Guix System instance is isolated from the host
  2813. system and only shares file system locations that you explicitly
  2814. declare.
  2815. A Guix System container differs from the shell process created by
  2816. @command{guix shell --container} in a number of important ways. While
  2817. in a container shell the containerized process is a Bash shell process,
  2818. a Guix System container runs the Shepherd as PID 1. In a system
  2819. container all system services (@pxref{Services,,, guix, GNU Guix
  2820. Reference Manual}) are set up just as they would be on a Guix System in
  2821. a virtual machine or on bare metal---this includes daemons managed by
  2822. the GNU@tie{}Shepherd (@pxref{Shepherd Services,,, guix, GNU Guix
  2823. Reference Manual}) as well as other kinds of extensions to the operating
  2824. system (@pxref{Service Composition,,, guix, GNU Guix Reference Manual}).
  2825. The perceived increase in complexity of running a Guix System container
  2826. is easily justified when dealing with more complex applications that
  2827. have higher or just more rigid requirements on their execution
  2828. contexts---configuration files, dedicated user accounts, directories for
  2829. caches or log files, etc. In Guix System the demands of this kind of
  2830. software are satisfied through the deployment of system services.
  2831. @menu
  2832. * A Database Container::
  2833. * Container Networking::
  2834. @end menu
  2835. @node A Database Container
  2836. @subsection A Database Container
  2837. A good example might be a PostgreSQL database server. Much of the
  2838. complexity of setting up such a database server is encapsulated in this
  2839. deceptively short service declaration:
  2840. @lisp
  2841. (service postgresql-service-type
  2842. (postgresql-configuration
  2843. (postgresql postgresql-14)))
  2844. @end lisp
  2845. A complete operating system declaration for use with a Guix System
  2846. container would look something like this:
  2847. @lisp
  2848. (use-modules (gnu))
  2849. (use-package-modules databases)
  2850. (use-service-modules databases)
  2851. (operating-system
  2852. (host-name "container")
  2853. (timezone "Europe/Berlin")
  2854. (file-systems (cons (file-system
  2855. (device (file-system-label "does-not-matter"))
  2856. (mount-point "/")
  2857. (type "ext4"))
  2858. %base-file-systems))
  2859. (bootloader (bootloader-configuration
  2860. (bootloader grub-bootloader)
  2861. (targets '("/dev/sdX"))))
  2862. (services
  2863. (cons* (service postgresql-service-type
  2864. (postgresql-configuration
  2865. (postgresql postgresql-14)
  2866. (config-file
  2867. (postgresql-config-file
  2868. (log-destination "stderr")
  2869. (hba-file
  2870. (plain-file "pg_hba.conf"
  2871. "\
  2872. local all all trust
  2873. host all all 10.0.0.1/32 trust"))
  2874. (extra-config
  2875. '(("listen_addresses" "*")
  2876. ("log_directory" "/var/log/postgresql")))))))
  2877. (service postgresql-role-service-type
  2878. (postgresql-role-configuration
  2879. (roles
  2880. (list (postgresql-role
  2881. (name "test")
  2882. (create-database? #t))))))
  2883. %base-services)))
  2884. @end lisp
  2885. With @code{postgresql-role-service-type} we define a role ``test'' and
  2886. create a matching database, so that we can test right away without any
  2887. further manual setup. The @code{postgresql-config-file} settings allow
  2888. a client from IP address 10.0.0.1 to connect without requiring
  2889. authentication---a bad idea in production systems, but convenient for
  2890. this example.
  2891. Let's build a script that will launch an instance of this Guix System as
  2892. a container. Write the @code{operating-system} declaration above to a
  2893. file @file{os.scm} and then use @command{guix system container} to build
  2894. the launcher. (@pxref{Invoking guix system,,, guix, GNU Guix Reference
  2895. Manual}).
  2896. @example
  2897. $ guix system container os.scm
  2898. The following derivations will be built:
  2899. /gnu/store/@dots{}-run-container.drv
  2900. @dots{}
  2901. building /gnu/store/@dots{}-run-container.drv...
  2902. /gnu/store/@dots{}-run-container
  2903. @end example
  2904. Now that we have a launcher script we can run it to spawn the new system
  2905. with a running PostgreSQL service. Note that due to some as yet
  2906. unresolved limitations we need to run the launcher as the root user, for
  2907. example with @command{sudo}.
  2908. @example
  2909. $ sudo /gnu/store/@dots{}-run-container
  2910. system container is running as PID 5983
  2911. @dots{}
  2912. @end example
  2913. Background the process with @key{Ctrl-z} followed by @command{bg}. Note
  2914. the process ID in the output; we will need it to connect to the
  2915. container later. You know what? Let's try attaching to the container
  2916. right now. We will use @command{nsenter}, a tool provided by the
  2917. @code{util-linux} package:
  2918. @example
  2919. $ guix shell util-linux
  2920. $ sudo nsenter -a -t 5983
  2921. root@@container /# pgrep -a postgres
  2922. 49 /gnu/store/@dots{}-postgresql-14.4/bin/postgres -D /var/lib/postgresql/data --config-file=/gnu/store/@dots{}-postgresql.conf -p 5432
  2923. 51 postgres: checkpointer
  2924. 52 postgres: background writer
  2925. 53 postgres: walwriter
  2926. 54 postgres: autovacuum launcher
  2927. 55 postgres: stats collector
  2928. 56 postgres: logical replication launcher
  2929. root@@container /# exit
  2930. @end example
  2931. The PostgreSQL service is running in the container!
  2932. @node Container Networking
  2933. @subsection Container Networking
  2934. @cindex container networking
  2935. What good is a Guix System running a PostgreSQL database service as a
  2936. container when we can only talk to it with processes originating in the
  2937. container? It would be much better if we could talk to the database
  2938. over the network.
  2939. The easiest way to do this is to create a pair of connected virtual
  2940. Ethernet devices (known as @code{veth}). We move one of the devices
  2941. (@code{ceth-test}) into the @code{net} namespace of the container and
  2942. leave the other end (@code{veth-test}) of the connection on the host
  2943. system.
  2944. @example
  2945. pid=5983
  2946. ns="guix-test"
  2947. host="veth-test"
  2948. client="ceth-test"
  2949. # Attach the new net namespace "guix-test" to the container PID.
  2950. sudo ip netns attach $ns $pid
  2951. # Create the pair of devices
  2952. sudo ip link add $host type veth peer name $client
  2953. # Move the client device into the container's net namespace
  2954. sudo ip link set $client netns $ns
  2955. @end example
  2956. Then we configure the host side:
  2957. @example
  2958. sudo ip link set $host up
  2959. sudo ip addr add 10.0.0.1/24 dev $host
  2960. @end example
  2961. @dots{}and then we configure the client side:
  2962. @example
  2963. sudo ip netns exec $ns ip link set lo up
  2964. sudo ip netns exec $ns ip link set $client up
  2965. sudo ip netns exec $ns ip addr add 10.0.0.2/24 dev $client
  2966. @end example
  2967. At this point the host can reach the container at IP address 10.0.0.2,
  2968. and the container can reach the host at IP 10.0.0.1. This is all we
  2969. need to talk to the database server inside the container from the host
  2970. system on the outside.
  2971. @example
  2972. $ psql -h 10.0.0.2 -U test
  2973. psql (14.4)
  2974. Type "help" for help.
  2975. test=> CREATE TABLE hello (who TEXT NOT NULL);
  2976. CREATE TABLE
  2977. test=> INSERT INTO hello (who) VALUES ('world');
  2978. INSERT 0 1
  2979. test=> SELECT * FROM hello;
  2980. who
  2981. -------
  2982. world
  2983. (1 row)
  2984. @end example
  2985. Now that we're done with this little demonstration let's clean up:
  2986. @example
  2987. sudo kill $pid
  2988. sudo ip netns del $ns
  2989. sudo ip link del $host
  2990. @end example
  2991. @c *********************************************************************
  2992. @node Advanced package management
  2993. @chapter Advanced package management
  2994. Guix is a functional package manager that offers many features beyond
  2995. what more traditional package managers can do. To the uninitiated,
  2996. those features might not have obvious use cases at first. The purpose
  2997. of this chapter is to demonstrate some advanced package management
  2998. concepts.
  2999. @pxref{Package Management,,, guix, GNU Guix Reference Manual} for a complete
  3000. reference.
  3001. @menu
  3002. * Guix Profiles in Practice:: Strategies for multiple profiles and manifests.
  3003. @end menu
  3004. @node Guix Profiles in Practice
  3005. @section Guix Profiles in Practice
  3006. Guix provides a very useful feature that may be quite foreign to newcomers:
  3007. @emph{profiles}. They are a way to group package installations together and all users
  3008. on the same system are free to use as many profiles as they want.
  3009. Whether you're a developer or not, you may find that multiple profiles bring you
  3010. great power and flexibility. While they shift the paradigm somewhat compared to
  3011. @emph{traditional package managers}, they are very convenient to use once you've
  3012. understood how to set them up.
  3013. If you are familiar with Python's @samp{virtualenv}, you can think of a profile as a
  3014. kind of universal @samp{virtualenv} that can hold any kind of software whatsoever, not
  3015. just Python software. Furthermore, profiles are self-sufficient: they capture
  3016. all the runtime dependencies which guarantees that all programs within a profile
  3017. will always work at any point in time.
  3018. Multiple profiles have many benefits:
  3019. @itemize
  3020. @item
  3021. Clean semantic separation of the various packages a user needs for different contexts.
  3022. @item
  3023. Multiple profiles can be made available into the environment either on login
  3024. or within a dedicated shell.
  3025. @item
  3026. Profiles can be loaded on demand. For instance, the user can use multiple
  3027. shells, each of them running different profiles.
  3028. @item
  3029. Isolation: Programs from one profile will not use programs from the other, and
  3030. the user can even install different versions of the same programs to the two
  3031. profiles without conflict.
  3032. @item
  3033. Deduplication: Profiles share dependencies that happens to be the exact same.
  3034. This makes multiple profiles storage-efficient.
  3035. @item
  3036. Reproducible: when used with declarative manifests, a profile can be fully
  3037. specified by the Guix commit that was active when it was set up. This means
  3038. that the exact same profile can be
  3039. @uref{https://guix.gnu.org/blog/2018/multi-dimensional-transactions-and-rollbacks-oh-my/,
  3040. set up anywhere and anytime}, with just the commit information. See the
  3041. section on @ref{Reproducible profiles}.
  3042. @item
  3043. Easier upgrades and maintenance: Multiple profiles make it easy to keep
  3044. package listings at hand and make upgrades completely frictionless.
  3045. @end itemize
  3046. Concretely, here follows some typical profiles:
  3047. @itemize
  3048. @item
  3049. The dependencies of a project you are working on.
  3050. @item
  3051. Your favourite programming language libraries.
  3052. @item
  3053. Laptop-specific programs (like @samp{powertop}) that you don't need on a desktop.
  3054. @item
  3055. @TeX{}live (this one can be really useful when you need to install just one
  3056. package for this one document you've just received over email).
  3057. @item
  3058. Games.
  3059. @end itemize
  3060. Let's dive in the set up!
  3061. @menu
  3062. * Basic setup with manifests::
  3063. * Required packages::
  3064. * Default profile::
  3065. * The benefits of manifests::
  3066. * Reproducible profiles::
  3067. @end menu
  3068. @node Basic setup with manifests
  3069. @subsection Basic setup with manifests
  3070. A Guix profile can be set up @i{via} a @dfn{manifest}. A manifest is a
  3071. snippet of Scheme code that specifies the set of packages you want to
  3072. have in your profile; it looks like this:
  3073. @lisp
  3074. (specifications->manifest
  3075. '("package-1"
  3076. ;; Version 1.3 of package-2.
  3077. "package-2@@1.3"
  3078. ;; The "lib" output of package-3.
  3079. "package-3:lib"
  3080. ; ...
  3081. "package-N"))
  3082. @end lisp
  3083. @xref{Writing Manifests,,, guix, GNU Guix Reference Manual}, for
  3084. more information about the syntax.
  3085. We can create a manifest specification per profile and install them this way:
  3086. @example
  3087. GUIX_EXTRA_PROFILES=$HOME/.guix-extra-profiles
  3088. mkdir -p "$GUIX_EXTRA_PROFILES"/my-project # if it does not exist yet
  3089. guix package --manifest=/path/to/guix-my-project-manifest.scm --profile="$GUIX_EXTRA_PROFILES"/my-project/my-project
  3090. @end example
  3091. Here we set an arbitrary variable @samp{GUIX_EXTRA_PROFILES} to point to the directory
  3092. where we will store our profiles in the rest of this article.
  3093. Placing all your profiles in a single directory, with each profile getting its
  3094. own sub-directory, is somewhat cleaner. This way, each sub-directory will
  3095. contain all the symlinks for precisely one profile. Besides, ``looping over
  3096. profiles'' becomes obvious from any programming language (e.g.@: a shell script) by
  3097. simply looping over the sub-directories of @samp{$GUIX_EXTRA_PROFILES}.
  3098. Note that it's also possible to loop over the output of
  3099. @example
  3100. guix package --list-profiles
  3101. @end example
  3102. although you'll probably have to filter out @file{~/.config/guix/current}.
  3103. To enable all profiles on login, add this to your @file{~/.bash_profile} (or similar):
  3104. @example
  3105. for i in $GUIX_EXTRA_PROFILES/*; do
  3106. profile=$i/$(basename "$i")
  3107. if [ -f "$profile"/etc/profile ]; then
  3108. GUIX_PROFILE="$profile"
  3109. . "$GUIX_PROFILE"/etc/profile
  3110. fi
  3111. unset profile
  3112. done
  3113. @end example
  3114. Note to Guix System users: the above reflects how your default profile
  3115. @file{~/.guix-profile} is activated from @file{/etc/profile}, that latter being loaded by
  3116. @file{~/.bashrc} by default.
  3117. You can obviously choose to only enable a subset of them:
  3118. @example
  3119. for i in "$GUIX_EXTRA_PROFILES"/my-project-1 "$GUIX_EXTRA_PROFILES"/my-project-2; do
  3120. profile=$i/$(basename "$i")
  3121. if [ -f "$profile"/etc/profile ]; then
  3122. GUIX_PROFILE="$profile"
  3123. . "$GUIX_PROFILE"/etc/profile
  3124. fi
  3125. unset profile
  3126. done
  3127. @end example
  3128. When a profile is off, it's straightforward to enable it for an individual shell
  3129. without "polluting" the rest of the user session:
  3130. @example
  3131. GUIX_PROFILE="path/to/my-project" ; . "$GUIX_PROFILE"/etc/profile
  3132. @end example
  3133. The key to enabling a profile is to @emph{source} its @samp{etc/profile} file. This file
  3134. contains shell code that exports the right environment variables necessary to
  3135. activate the software contained in the profile. It is built automatically by
  3136. Guix and meant to be sourced.
  3137. It contains the same variables you would get if you ran:
  3138. @example
  3139. guix package --search-paths=prefix --profile=$my_profile"
  3140. @end example
  3141. Once again, see (@pxref{Invoking guix package,,, guix, GNU Guix Reference Manual})
  3142. for the command line options.
  3143. To upgrade a profile, simply install the manifest again:
  3144. @example
  3145. guix package -m /path/to/guix-my-project-manifest.scm -p "$GUIX_EXTRA_PROFILES"/my-project/my-project
  3146. @end example
  3147. To upgrade all profiles, it's easy enough to loop over them. For instance,
  3148. assuming your manifest specifications are stored in
  3149. @file{~/.guix-manifests/guix-$profile-manifest.scm}, with @samp{$profile} being the name
  3150. of the profile (e.g.@: "project1"), you could do the following in Bourne shell:
  3151. @example
  3152. for profile in "$GUIX_EXTRA_PROFILES"/*; do
  3153. guix package --profile="$profile" --manifest="$HOME/.guix-manifests/guix-$profile-manifest.scm"
  3154. done
  3155. @end example
  3156. Each profile has its own generations:
  3157. @example
  3158. guix package -p "$GUIX_EXTRA_PROFILES"/my-project/my-project --list-generations
  3159. @end example
  3160. You can roll-back to any generation of a given profile:
  3161. @example
  3162. guix package -p "$GUIX_EXTRA_PROFILES"/my-project/my-project --switch-generations=17
  3163. @end example
  3164. Finally, if you want to switch to a profile without inheriting from the
  3165. current environment, you can activate it from an empty shell:
  3166. @example
  3167. env -i $(which bash) --login --noprofile --norc
  3168. . my-project/etc/profile
  3169. @end example
  3170. @node Required packages
  3171. @subsection Required packages
  3172. Activating a profile essentially boils down to exporting a bunch of
  3173. environmental variables. This is the role of the @samp{etc/profile} within the
  3174. profile.
  3175. @emph{Note: Only the environmental variables of the packages that consume them will
  3176. be set.}
  3177. For instance, @samp{MANPATH} won't be set if there is no consumer application for man
  3178. pages within the profile. So if you need to transparently access man pages once
  3179. the profile is loaded, you've got two options:
  3180. @itemize
  3181. @item
  3182. Either export the variable manually, e.g.
  3183. @example
  3184. export MANPATH=/path/to/profile$@{MANPATH:+:@}$MANPATH
  3185. @end example
  3186. @item
  3187. Or include @samp{man-db} to the profile manifest.
  3188. @end itemize
  3189. The same is true for @samp{INFOPATH} (you can install @samp{info-reader}),
  3190. @samp{PKG_CONFIG_PATH} (install @samp{pkg-config}), etc.
  3191. @node Default profile
  3192. @subsection Default profile
  3193. What about the default profile that Guix keeps in @file{~/.guix-profile}?
  3194. You can assign it the role you want. Typically you would install the manifest
  3195. of the packages you want to use all the time.
  3196. Alternatively, you could keep it ``manifest-less'' for throw-away packages
  3197. that you would just use for a couple of days.
  3198. This way makes it convenient to run
  3199. @example
  3200. guix install package-foo
  3201. guix upgrade package-bar
  3202. @end example
  3203. without having to specify the path to a profile.
  3204. @node The benefits of manifests
  3205. @subsection The benefits of manifests
  3206. Manifests are a convenient way to keep your package lists around and, say,
  3207. to synchronize them across multiple machines using a version control system.
  3208. A common complaint about manifests is that they can be slow to install when they
  3209. contain large number of packages. This is especially cumbersome when you just
  3210. want get an upgrade for one package within a big manifest.
  3211. This is one more reason to use multiple profiles, which happen to be just
  3212. perfect to break down manifests into multiple sets of semantically connected
  3213. packages. Using multiple, small profiles provides more flexibility and
  3214. usability.
  3215. Manifests come with multiple benefits. In particular, they ease maintenance:
  3216. @itemize
  3217. @item
  3218. When a profile is set up from a manifest, the manifest itself is
  3219. self-sufficient to keep a ``package listing'' around and reinstall the profile
  3220. later or on a different system. For ad-hoc profiles, we would need to
  3221. generate a manifest specification manually and maintain the package versions
  3222. for the packages that don't use the default version.
  3223. @item
  3224. @code{guix package --upgrade} always tries to update the packages that have
  3225. propagated inputs, even if there is nothing to do. Guix manifests remove this
  3226. problem.
  3227. @item
  3228. When partially upgrading a profile, conflicts may arise (due to diverging
  3229. dependencies between the updated and the non-updated packages) and they can be
  3230. annoying to resolve manually. Manifests remove this problem altogether since
  3231. all packages are always upgraded at once.
  3232. @item
  3233. As mentioned above, manifests allow for reproducible profiles, while the
  3234. imperative @code{guix install}, @code{guix upgrade}, etc. do not, since they produce
  3235. different profiles every time even when they hold the same packages. See
  3236. @uref{https://issues.guix.gnu.org/issue/33285, the related discussion on the matter}.
  3237. @item
  3238. Manifest specifications are usable by other @samp{guix} commands. For example, you
  3239. can run @code{guix weather -m manifest.scm} to see how many substitutes are
  3240. available, which can help you decide whether you want to try upgrading today
  3241. or wait a while. Another example: you can run @code{guix pack -m manifest.scm} to
  3242. create a pack containing all the packages in the manifest (and their
  3243. transitive references).
  3244. @item
  3245. Finally, manifests have a Scheme representation, the @samp{<manifest>} record type.
  3246. They can be manipulated in Scheme and passed to the various Guix @uref{https://en.wikipedia.org/wiki/Api, APIs}.
  3247. @end itemize
  3248. It's important to understand that while manifests can be used to declare
  3249. profiles, they are not strictly equivalent: profiles have the side effect that
  3250. they ``pin'' packages in the store, which prevents them from being
  3251. garbage-collected (@pxref{Invoking guix gc,,, guix, GNU Guix Reference Manual})
  3252. and ensures that they will still be available at any point in
  3253. the future.
  3254. Let's take an example:
  3255. @enumerate
  3256. @item
  3257. We have an environment for hacking on a project for which there isn't a Guix
  3258. package yet. We build the environment using a manifest, and then run @code{guix
  3259. environment -m manifest.scm}. So far so good.
  3260. @item
  3261. Many weeks pass and we have run a couple of @code{guix pull} in the mean time.
  3262. Maybe a dependency from our manifest has been updated; or we may have run
  3263. @code{guix gc} and some packages needed by our manifest have been
  3264. garbage-collected.
  3265. @item
  3266. Eventually, we set to work on that project again, so we run @code{guix shell
  3267. -m manifest.scm}. But now we have to wait for Guix to build and install
  3268. stuff!
  3269. @end enumerate
  3270. Ideally, we could spare the rebuild time. And indeed we can, all we need is to
  3271. install the manifest to a profile and use @code{GUIX_PROFILE=/the/profile;
  3272. . "$GUIX_PROFILE"/etc/profile} as explained above: this guarantees that our
  3273. hacking environment will be available at all times.
  3274. @emph{Security warning:} While keeping old profiles around can be convenient, keep in
  3275. mind that outdated packages may not have received the latest security fixes.
  3276. @node Reproducible profiles
  3277. @subsection Reproducible profiles
  3278. To reproduce a profile bit-for-bit, we need two pieces of information:
  3279. @itemize
  3280. @item
  3281. a manifest,
  3282. @item
  3283. a Guix channel specification.
  3284. @end itemize
  3285. Indeed, manifests alone might not be enough: different Guix versions (or
  3286. different channels) can produce different outputs for a given manifest.
  3287. You can output the Guix channel specification with @samp{guix describe
  3288. --format=channels}.
  3289. Save this to a file, say @samp{channel-specs.scm}.
  3290. On another computer, you can use the channel specification file and the manifest
  3291. to reproduce the exact same profile:
  3292. @example
  3293. GUIX_EXTRA_PROFILES=$HOME/.guix-extra-profiles
  3294. GUIX_EXTRA=$HOME/.guix-extra
  3295. mkdir -p "$GUIX_EXTRA"/my-project
  3296. guix pull --channels=channel-specs.scm --profile="$GUIX_EXTRA/my-project/guix"
  3297. mkdir -p "$GUIX_EXTRA_PROFILES/my-project"
  3298. "$GUIX_EXTRA"/my-project/guix/bin/guix package --manifest=/path/to/guix-my-project-manifest.scm --profile="$GUIX_EXTRA_PROFILES"/my-project/my-project
  3299. @end example
  3300. It's safe to delete the Guix channel profile you've just installed with the
  3301. channel specification, the project profile does not depend on it.
  3302. @c *********************************************************************
  3303. @node Environment management
  3304. @chapter Environment management
  3305. Guix provides multiple tools to manage environment. This chapter
  3306. demonstrate such utilities.
  3307. @menu
  3308. * Guix environment via direnv:: Setup Guix environment with direnv
  3309. @end menu
  3310. @node Guix environment via direnv
  3311. @section Guix environment via direnv
  3312. Guix provides a @samp{direnv} package, which could extend shell after
  3313. directory change. This tool could be used to prepare a pure Guix
  3314. environment.
  3315. The following example provides a shell function for @file{~/.direnvrc}
  3316. file, which could be used from Guix Git repository in
  3317. @file{~/src/guix/.envrc} file to setup a build environment similar to
  3318. described in @pxref{Building from Git,,, guix, GNU Guix Reference
  3319. Manual}.
  3320. Create a @file{~/.direnvrc} with a Bash code:
  3321. @example
  3322. # Thanks <https://github.com/direnv/direnv/issues/73#issuecomment-152284914>
  3323. export_function()
  3324. @{
  3325. local name=$1
  3326. local alias_dir=$PWD/.direnv/aliases
  3327. mkdir -p "$alias_dir"
  3328. PATH_add "$alias_dir"
  3329. local target="$alias_dir/$name"
  3330. if declare -f "$name" >/dev/null; then
  3331. echo "#!$SHELL" > "$target"
  3332. declare -f "$name" >> "$target" 2>/dev/null
  3333. # Notice that we add shell variables to the function trigger.
  3334. echo "$name \$*" >> "$target"
  3335. chmod +x "$target"
  3336. fi
  3337. @}
  3338. use_guix()
  3339. @{
  3340. # Set GitHub token.
  3341. export GUIX_GITHUB_TOKEN="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  3342. # Unset 'GUIX_PACKAGE_PATH'.
  3343. export GUIX_PACKAGE_PATH=""
  3344. # Recreate a garbage collector root.
  3345. gcroots="$HOME/.config/guix/gcroots"
  3346. mkdir -p "$gcroots"
  3347. gcroot="$gcroots/guix"
  3348. if [ -L "$gcroot" ]
  3349. then
  3350. rm -v "$gcroot"
  3351. fi
  3352. # Miscellaneous packages.
  3353. PACKAGES_MAINTENANCE=(
  3354. direnv
  3355. git
  3356. git:send-email
  3357. git-cal
  3358. gnupg
  3359. guile-colorized
  3360. guile-readline
  3361. less
  3362. ncurses
  3363. openssh
  3364. xdot
  3365. )
  3366. # Environment packages.
  3367. PACKAGES=(help2man guile-sqlite3 guile-gcrypt)
  3368. # Thanks <https://lists.gnu.org/archive/html/guix-devel/2016-09/msg00859.html>
  3369. eval "$(guix environment --search-paths --root="$gcroot" --pure guix --ad-hoc $@{PACKAGES[@@]@} $@{PACKAGES_MAINTENANCE[@@]@} "$@@")"
  3370. # Predefine configure flags.
  3371. configure()
  3372. @{
  3373. ./configure --localstatedir=/var --prefix=
  3374. @}
  3375. export_function configure
  3376. # Run make and optionally build something.
  3377. build()
  3378. @{
  3379. make -j 2
  3380. if [ $# -gt 0 ]
  3381. then
  3382. ./pre-inst-env guix build "$@@"
  3383. fi
  3384. @}
  3385. export_function build
  3386. # Predefine push Git command.
  3387. push()
  3388. @{
  3389. git push --set-upstream origin
  3390. @}
  3391. export_function push
  3392. clear # Clean up the screen.
  3393. git-cal --author='Your Name' # Show contributions calendar.
  3394. # Show commands help.
  3395. echo "
  3396. build build a package or just a project if no argument provided
  3397. configure run ./configure with predefined parameters
  3398. push push to upstream Git repository
  3399. "
  3400. @}
  3401. @end example
  3402. Every project containing @file{.envrc} with a string @code{use guix}
  3403. will have predefined environment variables and procedures.
  3404. Run @command{direnv allow} to setup the environment for the first time.
  3405. @c *********************************************************************
  3406. @node Installing Guix on a Cluster
  3407. @chapter Installing Guix on a Cluster
  3408. @cindex cluster installation
  3409. @cindex high-performance computing, HPC
  3410. @cindex HPC, high-performance computing
  3411. Guix is appealing to scientists and @acronym{HPC, high-performance
  3412. computing} practitioners: it makes it easy to deploy potentially complex
  3413. software stacks, and it lets you do so in a reproducible fashion---you
  3414. can redeploy the exact same software on different machines and at
  3415. different points in time.
  3416. In this chapter we look at how a cluster sysadmin can install Guix for
  3417. system-wide use, such that it can be used on all the cluster nodes, and
  3418. discuss the various tradeoffs@footnote{This chapter is adapted from a
  3419. @uref{https://hpc.guix.info/blog/2017/11/installing-guix-on-a-cluster/,
  3420. blog post published on the Guix-HPC web site in 2017}.}.
  3421. @quotation Note
  3422. Here we assume that the cluster is running a GNU/Linux distro other than
  3423. Guix System and that we are going to install Guix on top of it.
  3424. @end quotation
  3425. @menu
  3426. * Setting Up a Head Node:: The node that runs the daemon.
  3427. * Setting Up Compute Nodes:: Client nodes.
  3428. * Cluster Network Access:: Dealing with network access restrictions.
  3429. * Cluster Disk Usage:: Disk usage considerations.
  3430. * Cluster Security Considerations:: Keeping the cluster secure.
  3431. @end menu
  3432. @node Setting Up a Head Node
  3433. @section Setting Up a Head Node
  3434. The recommended approach is to set up one @emph{head node} running
  3435. @command{guix-daemon} and exporting @file{/gnu/store} over NFS to
  3436. compute nodes.
  3437. Remember that @command{guix-daemon} is responsible for spawning build
  3438. processes and downloads on behalf of clients (@pxref{Invoking
  3439. guix-daemon,,, guix, GNU Guix Reference Manual}), and more generally
  3440. accessing @file{/gnu/store}, which contains all the package binaries
  3441. built by all the users (@pxref{The Store,,, guix, GNU Guix Reference
  3442. Manual}). ``Client'' here refers to all the Guix commands that users
  3443. see, such as @code{guix install}. On a cluster, these commands may be
  3444. running on the compute nodes and we'll want them to talk to the head
  3445. node's @code{guix-daemon} instance.
  3446. To begin with, the head node can be installed following the usual binary
  3447. installation instructions (@pxref{Binary Installation,,, guix, GNU Guix
  3448. Reference Manual}). Thanks to the installation script, this should be
  3449. quick. Once installation is complete, we need to make some adjustments.
  3450. Since we want @code{guix-daemon} to be reachable not just from the head
  3451. node but also from the compute nodes, we need to arrange so that it
  3452. listens for connections over TCP/IP. To do that, we'll edit the systemd
  3453. startup file for @command{guix-daemon},
  3454. @file{/etc/systemd/system/guix-daemon.service}, and add a
  3455. @code{--listen} argument to the @code{ExecStart} line so that it looks
  3456. something like this:
  3457. @example
  3458. ExecStart=/var/guix/profiles/per-user/root/current-guix/bin/guix-daemon --build-users-group=guixbuild --listen=/var/guix/daemon-socket/socket --listen=0.0.0.0
  3459. @end example
  3460. For these changes to take effect, the service needs to be restarted:
  3461. @example
  3462. systemctl daemon-reload
  3463. systemctl restart guix-daemon
  3464. @end example
  3465. @quotation Note
  3466. The @code{--listen=0.0.0.0} bit means that @code{guix-daemon} will
  3467. process @emph{all} incoming TCP connections on port 44146
  3468. (@pxref{Invoking guix-daemon,,, guix, GNU Guix Reference Manual}). This
  3469. is usually fine in a cluster setup where the head node is reachable
  3470. exclusively from the cluster's local area network---you don't want that
  3471. to be exposed to the Internet!
  3472. @end quotation
  3473. The next step is to define our NFS exports in
  3474. @uref{https://linux.die.net/man/5/exports,@file{/etc/exports}} by adding
  3475. something along these lines:
  3476. @example
  3477. /gnu/store *(ro)
  3478. /var/guix *(rw, async)
  3479. /var/log/guix *(ro)
  3480. @end example
  3481. The @file{/gnu/store} directory can be exported read-only since only
  3482. @command{guix-daemon} on the master node will ever modify it.
  3483. @file{/var/guix} contains @emph{user profiles} as managed by @code{guix
  3484. package}; thus, to allow users to install packages with @code{guix
  3485. package}, this must be read-write.
  3486. Users can create as many profiles as they like in addition to the
  3487. default profile, @file{~/.guix-profile}. For instance, @code{guix
  3488. package -p ~/dev/python-dev -i python} installs Python in a profile
  3489. reachable from the @code{~/dev/python-dev} symlink. To make sure that
  3490. this profile is protected from garbage collection---i.e., that Python
  3491. will not be removed from @file{/gnu/store} while this profile exists---,
  3492. @emph{home directories should be mounted on the head node} as well so
  3493. that @code{guix-daemon} knows about these non-standard profiles and
  3494. avoids collecting software they refer to.
  3495. It may be a good idea to periodically remove unused bits from
  3496. @file{/gnu/store} by running @command{guix gc} (@pxref{Invoking guix
  3497. gc,,, guix, GNU Guix Reference Manual}). This can be done by adding a
  3498. crontab entry on the head node:
  3499. @example
  3500. root@@master# crontab -e
  3501. @end example
  3502. @noindent
  3503. ... with something like this:
  3504. @example
  3505. # Every day at 5AM, run the garbage collector to make sure
  3506. # at least 10 GB are free on /gnu/store.
  3507. 0 5 * * 1 /usr/local/bin/guix gc -F10G
  3508. @end example
  3509. We're done with the head node! Let's look at compute nodes now.
  3510. @node Setting Up Compute Nodes
  3511. @section Setting Up Compute Nodes
  3512. First of all, we need compute nodes to mount those NFS directories that
  3513. the head node exports. This can be done by adding the following lines
  3514. to @uref{https://linux.die.net/man/5/fstab,@file{/etc/fstab}}:
  3515. @example
  3516. @var{head-node}:/gnu/store /gnu/store nfs defaults,_netdev,vers=3 0 0
  3517. @var{head-node}:/var/guix /var/guix nfs defaults,_netdev,vers=3 0 0
  3518. @var{head-node}:/var/log/guix /var/log/guix nfs defaults,_netdev,vers=3 0 0
  3519. @end example
  3520. @noindent
  3521. ... where @var{head-node} is the name or IP address of your head node.
  3522. From there on, assuming the mount points exist, you should be able to
  3523. mount each of these on the compute nodes.
  3524. Next, we need to provide a default @command{guix} command that users can
  3525. run when they first connect to the cluster (eventually they will invoke
  3526. @command{guix pull}, which will provide them with their ``own''
  3527. @command{guix} command). Similar to what the binary installation script
  3528. did on the head node, we'll store that in @file{/usr/local/bin}:
  3529. @example
  3530. mkdir -p /usr/local/bin
  3531. ln -s /var/guix/profiles/per-user/root/current-guix/bin/guix \
  3532. /usr/local/bin/guix
  3533. @end example
  3534. We then need to tell @code{guix} to talk to the daemon running on our
  3535. master node, by adding these lines to @code{/etc/profile}:
  3536. @example
  3537. GUIX_DAEMON_SOCKET="guix://@var{head-node}"
  3538. export GUIX_DAEMON_SOCKET
  3539. @end example
  3540. To avoid warnings and make sure @code{guix} uses the right locale, we
  3541. need to tell it to use locale data provided by Guix (@pxref{Application
  3542. Setup,,, guix, GNU Guix Reference Manual}):
  3543. @example
  3544. GUIX_LOCPATH=/var/guix/profiles/per-user/root/guix-profile/lib/locale
  3545. export GUIX_LOCPATH
  3546. # Here we must use a valid locale name. Try "ls $GUIX_LOCPATH/*"
  3547. # to see what names can be used.
  3548. LC_ALL=fr_FR.utf8
  3549. export LC_ALL
  3550. @end example
  3551. For convenience, @code{guix package} automatically generates
  3552. @file{~/.guix-profile/etc/profile}, which defines all the environment
  3553. variables necessary to use the packages---@code{PATH},
  3554. @code{C_INCLUDE_PATH}, @code{PYTHONPATH}, etc. Thus it's a good idea to
  3555. source it from @code{/etc/profile}:
  3556. @example
  3557. GUIX_PROFILE="$HOME/.guix-profile"
  3558. if [ -f "$GUIX_PROFILE/etc/profile" ]; then
  3559. . "$GUIX_PROFILE/etc/profile"
  3560. fi
  3561. @end example
  3562. Last but not least, Guix provides command-line completion notably for
  3563. Bash and zsh. In @code{/etc/bashrc}, consider adding this line:
  3564. @verbatim
  3565. . /var/guix/profiles/per-user/root/current-guix/etc/bash_completion.d/guix
  3566. @end verbatim
  3567. Voilà!
  3568. You can check that everything's in place by logging in on a compute node
  3569. and running:
  3570. @example
  3571. guix install hello
  3572. @end example
  3573. The daemon on the head node should download pre-built binaries on your
  3574. behalf and unpack them in @file{/gnu/store}, and @command{guix install}
  3575. should create @file{~/.guix-profile} containing the
  3576. @file{~/.guix-profile/bin/hello} command.
  3577. @node Cluster Network Access
  3578. @section Network Access
  3579. Guix requires network access to download source code and pre-built
  3580. binaries. The good news is that only the head node needs that since
  3581. compute nodes simply delegate to it.
  3582. It is customary for cluster nodes to have access at best to a
  3583. @emph{white list} of hosts. Our head node needs at least
  3584. @code{ci.guix.gnu.org} in this white list since this is where it gets
  3585. pre-built binaries from by default, for all the packages that are in
  3586. Guix proper.
  3587. Incidentally, @code{ci.guix.gnu.org} also serves as a
  3588. @emph{content-addressed mirror} of the source code of those packages.
  3589. Consequently, it is sufficient to have @emph{only}
  3590. @code{ci.guix.gnu.org} in that white list.
  3591. Software packages maintained in a separate repository such as one of the
  3592. various @uref{https://hpc.guix.info/channels, HPC channels} are of
  3593. course unavailable from @code{ci.guix.gnu.org}. For these packages, you
  3594. may want to extend the white list such that source and pre-built
  3595. binaries (assuming this-party servers provide binaries for these
  3596. packages) can be downloaded. As a last resort, users can always
  3597. download source on their workstation and add it to the cluster's
  3598. @file{/gnu/store}, like this:
  3599. @verbatim
  3600. GUIX_DAEMON_SOCKET=ssh://compute-node.example.org \
  3601. guix download http://starpu.gforge.inria.fr/files/starpu-1.2.3/starpu-1.2.3.tar.gz
  3602. @end verbatim
  3603. The above command downloads @code{starpu-1.2.3.tar.gz} @emph{and} sends
  3604. it to the cluster's @code{guix-daemon} instance over SSH.
  3605. Air-gapped clusters require more work. At the moment, our suggestion
  3606. would be to download all the necessary source code on a workstation
  3607. running Guix. For instance, using the @option{--sources} option of
  3608. @command{guix build} (@pxref{Invoking guix build,,, guix, GNU Guix
  3609. Reference Manual}), the example below downloads all the source code the
  3610. @code{openmpi} package depends on:
  3611. @example
  3612. $ guix build --sources=transitive openmpi
  3613. @dots{}
  3614. /gnu/store/xc17sm60fb8nxadc4qy0c7rqph499z8s-openmpi-1.10.7.tar.bz2
  3615. /gnu/store/s67jx92lpipy2nfj5cz818xv430n4b7w-gcc-5.4.0.tar.xz
  3616. /gnu/store/npw9qh8a46lrxiwh9xwk0wpi3jlzmjnh-gmp-6.0.0a.tar.xz
  3617. /gnu/store/hcz0f4wkdbsvsdky3c0vdvcawhdkyldb-mpfr-3.1.5.tar.xz
  3618. /gnu/store/y9akh452n3p4w2v631nj0injx7y0d68x-mpc-1.0.3.tar.gz
  3619. /gnu/store/6g5c35q8avfnzs3v14dzl54cmrvddjm2-glibc-2.25.tar.xz
  3620. /gnu/store/p9k48dk3dvvk7gads7fk30xc2pxsd66z-hwloc-1.11.8.tar.bz2
  3621. /gnu/store/cry9lqidwfrfmgl0x389cs3syr15p13q-gcc-5.4.0.tar.xz
  3622. /gnu/store/7ak0v3rzpqm2c5q1mp3v7cj0rxz0qakf-libfabric-1.4.1.tar.bz2
  3623. /gnu/store/vh8syjrsilnbfcf582qhmvpg1v3rampf-rdma-core-14.tar.gz
  3624. @end example
  3625. (In case you're wondering, that's more than 320@ MiB of
  3626. @emph{compressed} source code.)
  3627. We can then make a big archive containing all of this (@pxref{Invoking
  3628. guix archive,,, guix, GNU Guix Reference Manual}):
  3629. @verbatim
  3630. $ guix archive --export \
  3631. `guix build --sources=transitive openmpi` \
  3632. > openmpi-source-code.nar
  3633. @end verbatim
  3634. @dots{} and we can eventually transfer that archive to the cluster on
  3635. removable storage and unpack it there:
  3636. @verbatim
  3637. $ guix archive --import < openmpi-source-code.nar
  3638. @end verbatim
  3639. This process has to be repeated every time new source code needs to be
  3640. brought to the cluster.
  3641. As we write this, the research institutes involved in Guix-HPC do not
  3642. have air-gapped clusters though. If you have experience with such
  3643. setups, we would like to hear feedback and suggestions.
  3644. @node Cluster Disk Usage
  3645. @section Disk Usage
  3646. @cindex disk usage, on a cluster
  3647. A common concern of sysadmins' is whether this is all going to eat a lot
  3648. of disk space. If anything, if something is going to exhaust disk
  3649. space, it's going to be scientific data sets rather than compiled
  3650. software---that's our experience with almost ten years of Guix usage on
  3651. HPC clusters. Nevertheless, it's worth taking a look at how Guix
  3652. contributes to disk usage.
  3653. First, having several versions or variants of a given package in
  3654. @file{/gnu/store} does not necessarily cost much, because
  3655. @command{guix-daemon} implements deduplication of identical files, and
  3656. package variants are likely to have a number of common files.
  3657. As mentioned above, we recommend having a cron job to run @code{guix gc}
  3658. periodically, which removes @emph{unused} software from
  3659. @file{/gnu/store}. However, there's always a possibility that users will
  3660. keep lots of software in their profiles, or lots of old generations of
  3661. their profiles, which is ``live'' and cannot be deleted from the
  3662. viewpoint of @command{guix gc}.
  3663. The solution to this is for users to regularly remove old generations of
  3664. their profile. For instance, the following command removes generations
  3665. that are more than two-month old:
  3666. @example
  3667. guix package --delete-generations=2m
  3668. @end example
  3669. Likewise, it's a good idea to invite users to regularly upgrade their
  3670. profile, which can reduce the number of variants of a given piece of
  3671. software stored in @file{/gnu/store}:
  3672. @example
  3673. guix pull
  3674. guix upgrade
  3675. @end example
  3676. As a last resort, it is always possible for sysadmins to do some of this
  3677. on behalf of their users. Nevertheless, one of the strengths of Guix is
  3678. the freedom and control users get on their software environment, so we
  3679. strongly recommend leaving users in control.
  3680. @node Cluster Security Considerations
  3681. @section Security Considerations
  3682. @cindex security, on a cluster
  3683. On an HPC cluster, Guix is typically used to manage scientific software.
  3684. Security-critical software such as the operating system kernel and
  3685. system services such as @code{sshd} and the batch scheduler remain under
  3686. control of sysadmins.
  3687. The Guix project has a good track record delivering security updates in
  3688. a timely fashion (@pxref{Security Updates,,, guix, GNU Guix Reference
  3689. Manual}). To get security updates, users have to run @code{guix pull &&
  3690. guix upgrade}.
  3691. Because Guix uniquely identifies software variants, it is easy to see if
  3692. a vulnerable piece of software is in use. For instance, to check whether
  3693. the glibc@ 2.25 variant without the mitigation patch against
  3694. ``@uref{https://www.qualys.com/2017/06/19/stack-clash/stack-clash.txt,Stack
  3695. Clash}'', one can check whether user profiles refer to it at all:
  3696. @example
  3697. guix gc --referrers /gnu/store/…-glibc-2.25
  3698. @end example
  3699. This will report whether profiles exist that refer to this specific
  3700. glibc variant.
  3701. @c *********************************************************************
  3702. @node Acknowledgments
  3703. @chapter Acknowledgments
  3704. Guix is based on the @uref{https://nixos.org/nix/, Nix package manager},
  3705. which was designed and
  3706. implemented by Eelco Dolstra, with contributions from other people (see
  3707. the @file{nix/AUTHORS} file in Guix.) Nix pioneered functional package
  3708. management, and promoted unprecedented features, such as transactional
  3709. package upgrades and rollbacks, per-user profiles, and referentially
  3710. transparent build processes. Without this work, Guix would not exist.
  3711. The Nix-based software distributions, Nixpkgs and NixOS, have also been
  3712. an inspiration for Guix.
  3713. GNU@tie{}Guix itself is a collective work with contributions from a
  3714. number of people. See the @file{AUTHORS} file in Guix for more
  3715. information on these fine people. The @file{THANKS} file lists people
  3716. who have helped by reporting bugs, taking care of the infrastructure,
  3717. providing artwork and themes, making suggestions, and more---thank you!
  3718. This document includes adapted sections from articles that have
  3719. previously been published on the Guix blog at
  3720. @uref{https://guix.gnu.org/blog} and on the Guix-HPC blog at
  3721. @uref{https://hpc.guix.info/blog}.
  3722. @c *********************************************************************
  3723. @node GNU Free Documentation License
  3724. @appendix GNU Free Documentation License
  3725. @cindex license, GNU Free Documentation License
  3726. @include fdl-1.3.texi
  3727. @c *********************************************************************
  3728. @node Concept Index
  3729. @unnumbered Concept Index
  3730. @printindex cp
  3731. @bye
  3732. @c Local Variables:
  3733. @c ispell-local-dictionary: "american";
  3734. @c End: