diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/contributing.es.texi | 1016 | ||||
| -rw-r--r-- | doc/guix.es.texi | 26015 |
2 files changed, 27031 insertions, 0 deletions
diff --git a/doc/contributing.es.texi b/doc/contributing.es.texi new file mode 100644 index 0000000000..05299173b6 --- /dev/null +++ b/doc/contributing.es.texi @@ -0,0 +1,1016 @@ +@node Contribuir +@chapter Contribuir + +Este proyecto es un esfuerzo colaborativo, y ¡necesitamos su ayuda para que +crezca! Por favor, contacte con nosotras en @email{guix-devel@@gnu.org} y en +@code{#guix} en la red IRC Freenode. Estamos abiertas a ideas, informes de +errores, parches y cualquier cosa que pueda ser de ayuda para el +proyecto. Especialmente se agradece ayuda en empaquetamiento +(@pxref{Guías de empaquetamiento}). + +@cindex código de conducta, de contribuidoras +@cindex acuerdo de contribución +Queremos proporcionar un entorno cálido, amistoso y libre de acoso, para que +cualquiera pueda contribuir al máximo de sus capacidades. Para este fin +nuestro proyecto usa un ``Acuerdo de Contribución'', que fue adaptado de +@url{http://contributor-coventant.org}. Se puede encontrar una versión local +en el fichero @file{CODE-OF-CONDUCT} del árbol de fuentes. + +Las contribuidoras no están obligadas a usar su nombre legal en los parches +ni en la comunicación on-line; pueden usar cualquier nombre o seudónimo de +su elección. + +@menu +* Construcción desde Git:: Lo último y mejor. +* Ejecución de Guix antes de estar instalado:: Trucos de hacker. +* La configuración perfecta:: Las herramientas adecuadas. +* Guías de empaquetamiento:: Crecimiento de la distribución. +* Estilo de codificación:: Higiene de la contribuidora. +* Envío de parches:: Comparta su trabajo. +@end menu + +@node Construcción desde Git +@section Construcción desde Git + +Si quiere picar en el mismo Guix se recomienda usar la última versión del +repositorio Git: + +@example +git clone https://git.savannah.gnu.org/git/guix.git +@end example + +Cuando se compila Guix de una copia de trabajo local (checkout), se +requieren los siguientes paquetes, además de los mencionados en las +instrucciones de instalación (@pxref{Requisitos}). + +@itemize +@item @url{http://gnu.org/software/autoconf/, GNU Autoconf}; +@item @url{http://gnu.org/software/automake/, GNU Automake}; +@item @url{http://gnu.org/software/gettext/, GNU Gettext}; +@item @url{http://gnu.org/software/texinfo/, GNU Texinfo}; +@item @url{http://www.graphviz.org/, Graphviz}; +@item @url{http://www.gnu.org/software/help2man/, GNU Help2man (opcional)}. +@end itemize + +El modo más fácil de preparar un entorno de desarrollo para Guix es, por +supuesto, ¡usando Guix! Las siguientes órdenes inician un nuevo intérprete +donde todas las dependencias y las variables de entorno apropiadas están +listas para picar código en Guix: + +@example +guix environment guix +@end example + +@xref{Invocación de guix environment}, para más información sobre esa orden. Se +pueden añadir dependencias adicionales con la opción @option{--ad-hoc}: + +@example +guix environment guix --ad-hoc help2man git strace +@end example + +Ejecute @command{./bootstrap} para generar la infraestructura del sistema de +construcción usando Autoconf y Automake. Si obtiene un error como este: + +@example +configure.ac:46: error: possibly undefined macro: PKG_CHECK_MODULES +@end example + +@noindent +probablemente significa que Autoconf no pudo encontrar el fichero pkg.m4, +que proporciona pkg-config. Asegurese de que @file{pkg.m4} está +disponible. Lo mismo aplica para el conjunto de macros @file{guile.m4} que +proporciona Guile. Por ejemplo, si ha instalado Automake en +@file{/usr/local}, no va a buscar ficheros @file{.m4} en +@file{/usr/share}. En ese caso tiene que ejecutar la siguiente orden: + +@example +export ACLOCAL_PATH=/usr/share/aclocal +@end example + +@xref{Macro Search Path,,, automake, The GNU Automake Manual} para más +información. + +Entonces, ejecute @command{./configure} como siempre. Asegurese de pasar +@code{--localstatedir=@var{directorio}}, donde @var{directorio} es el valor +de @code{localstatedir} usado por su instalación actual (@pxref{El almacén}, +para información sobre esto). + +Finalmente, tiene que ejecutar @code{make check} para iniciar las pruebas +(@pxref{Ejecución de la batería de pruebas}). Si algo falla, eche un vistazo a las +instrucciones de instalación (@pxref{Instalación}) o envíe un mensaje---en +Inglés---a la @email{guix-devel@@gnu.org, lista de correo}. + + +@node Ejecución de Guix antes de estar instalado +@section Ejecución de Guix antes de estar instalado + +Para mantener un entorno de trabajo estable, encontrará útil probar los +cambios hechos en su copia de trabajo local sin instalarlos realmente. De +esa manera, puede distinguir entre su sombrero de ``usuaria final'' y el +traje de ``harapos''. + +Para dicho fin, todas las herramientas de línea de órdenes pueden ser usadas +incluso si no ha ejecutado @code{make install}. Para hacerlo, primero +necesita tener un entorno con todas las dependencias disponibles +(@pxref{Construcción desde Git}), y entonces añada al inicio de cada orden +@command{./pre-inst-env} (el guión @file{pre-inst-env} se encuentra en la +raíz del árbol de compilación de Guix, como en@footnote{La opción +@option{-E} a @command{sudo} asegura que @code{GUILE_LOAD_PATH} contiene la +información correcta para que @command{guix-daemon} y las herramientas que +usa puedan encontrar los módulos Guile que necesitan.}: + +@example +$ sudo -E ./pre-inst-env guix-daemon --build-users-group=guixbuild +$ ./pre-inst-env guix build hello +@end example + +@noindent +De manera similar, para una sesión de Guile que use los módulos Guix: + +@example +$ ./pre-inst-env guile -c '(use-modules (guix utils)) (pk (%current-system))' + +;;; ("x86_64-linux") +@end example + +@noindent +@cindex REPL +@cindex entorno interactivo +@dots{} y para un entorno interactivo (REPL) (@pxref{Using Guile +Interactively,,, guile, Guile Reference Manual}): + +@example +$ ./pre-inst-env guile +scheme@@(guile-user)> ,use(guix) +scheme@@(guile-user)> ,use(gnu) +scheme@@(guile-user)> (define serpientes + (fold-packages + (lambda (paquete lst) + (if (string-prefix? "python" + (package-name paquete)) + (cons paquete lst) + lst)) + '())) +scheme@@(guile-user)> (length serpientes) +$1 = 361 +@end example + +El guión @command{pre-inst-env} fija todas las variables de entorno +necesarias para permitir esto, incluyendo @env{PATH} y +@env{GUILE_LOAD_PATH}. + +Fíjese que la orden @command{./pre-inst-env guix pull} @emph{no} actualiza +el árbol de fuentes local; simplemente actualiza el enlace +@file{~/.config/guix/latest} (@pxref{Invocación de guix pull}). Ejecute +@command{git pull} si quiere actualizar su árbol de fuentes local. + + +@node La configuración perfecta +@section La configuración perfecta + +La configuración perfecta para hackear en Guix es básicamente la +configuración perfecta para hacerlo en Guile (@pxref{Using Guile in Emacs,,, +guile, Guile Reference Manual}). Primero, necesita más que un editor, +necesita @url{http://www.gnu.org/software/emacs, Emacs}, empoderado por el +maravilloso @url{http://nongnu.org/geiser, Geiser}. Para configurarlo, +ejecute: + +@example +guix package -i emacs guile emacs-geiser +@end example + +Geiser permite desarrollo incremental e interactivo dentro de Emacs: +compilación y evaluación de código dentro de los buffers, acceso a +documentación en línea (docstrings), completado dependiente del contexto, +@kbd{M-.} para saltar a la definición de un objeto, una consola interactiva +(REPL) para probar su código, y más (@pxref{Introducción,,, geiser, Geiser +User Manual}). Para desarrollar Guix adecuadamente, asegúrese de aumentar la +ruta de carga de Guile (load-path) para que encuentre los ficheros fuente de +su copia de trabajo: + +@lisp +;; @r{Suponiendo que la copia de trabajo de Guix está en ~/src/guix.} +(with-eval-after-load 'geiser-guile + (add-to-list 'geiser-guile-load-path "~/src/guix")) +@end lisp + +Para realmente editar el código, Emacs tiene un modo limpio para +Scheme. Pero además de eso, no debe perderse +@url{http://www.emacswiki.org/emacs/ParEdit, Paredit}. Provee de facilidades +para operar directamente en el árbol sintáctico como elevar una expresión S +o recubrirla, embeber o expulsar la siguiente expresión S, etc. + +@cindex fragmentos de código +@cindex plantillas +@cindex reducir la verborrea +También proporcionamos plantillas para los mensajes de revisión de git +comunes y definiciones de paquetes en el directorio +@file{etc/snippets}. Estas plantillas pueden ser usadas con +@url{http://joaotavora.github.io/yasnippet, YASnippet} para expandir +mnemotécnicos a fragmentos interactivos de texto. Puedes querer añadir el +directorio de fragmentos a la variable @var{yas-snippet-dirs} en Emacs. + +@lisp +;; @r{Suponiendo que la copia de trabajo de Guix está en ~/src/guix.} +(with-eval-after-load 'yasnippet + (add-to-list 'yas-snippet-dirs "~/src/guix/etc/snippets")) +@end lisp + +Los fragmentos de mensajes de la revisión dependen de +@url{https://magit.vc/, Magit} para mostrar los ficheros preparados. En la +edición del mensaje de la revisión teclee @code{add} seguido de @kbd{TAB} +(el tabulador) para insertar la plantilla del mensaje de la revisión de +adición de un paquete; teclee @code{update} seguido de @kbd{TAB} para +insertar una plantilla de actualización de un paquete; teclee @code{https} +seguido de @kbd{TAB} para insertar una plantilla para cambiar la URI de la +página de un paquete a HTTPS. + +El fragmento principal para @code{scheme-mode} es activado al teclear +@code{package...} seguido de @kbd{TAB}. Este fragmento también inserta el +lanzador @code{origin...} que puede ser expandido de nuevo. El fragmento +@code{origin} puede a su vez insertar otros identificadores de lanzado +terminando en @code{...}, que pueden ser expandidos de nuevo. + + +@node Guías de empaquetamiento +@section Guías de empaquetamiento + +@cindex paquetes, creación +La distribución GNU es reciente y puede no disponer de alguno de sus +paquetes favoritos. Esta sección describe cómo puede ayudar a hacer crecer +la distribución. + +Los paquetes de software libre habitualmente se distribuyen en forma de +@dfn{archivadores de código fuente}---típicamente ficheros @file{tar.gz} que +contienen todos los ficheros fuente. Añadir un paquete a la distribución +significa esencialmente dos cosas: añadir una @dfn{receta} que describe cómo +construir el paquete, la que incluye una lista de otros paquetes necesarios +para la construcción, y añadir @dfn{metadatos del paquete} junto a dicha +receta, como la descripción y la información de licencias. + +En Guix toda esta información está contenida en @dfn{definiciones de +paquete}. Las definiciones de paquete proporcionan una vista de alto nivel +del paquete. Son escritas usando la sintaxis del lenguaje de programación +Scheme; de hecho, definimos una variable por cada paquete enlazada a su +definición y exportamos esa variable desde un módulo (@pxref{Módulos de paquetes}). No obstante, un conocimiento profundo de Scheme @emph{no} es un +pre-requisito para la creación de paquetes. Para más información obre las +definiciones de paquetes, @pxref{Definición de paquetes}. + +Una vez que una definición de paquete está en su lugar, almacenada en un +fichero del árbol de fuentes de Guix, puede probarse usando la orden +@command{guix build} (@pxref{Invocación de guix build}). Por ejemplo, asumiendo +que el nuevo paquete se llama @code{gnuevo}, puede ejecutar esta orden desde +el árbol de construcción de Guix (@pxref{Ejecución de Guix antes de estar instalado}): + +@example +./pre-inst-env guix build gnuevo --keep-failed +@end example + +El uso de @code{--keep-failed} facilita la depuración de errores de +construcción ya que proporciona acceso al árbol de la construcción +fallida. Otra opción útil de línea de órdenes para la depuración es +@code{--log-file}, para acceder al log de construcción. + +Si el paquete resulta desconocido para la orden @command{guix}, puede ser +que el fichero fuente contenga un error de sintaxis, o no tenga una cláusula +@code{define-public} para exportar la variable del paquete. Para encontrar +el problema puede cargar el módulo desde Guile para obtener más información +sobre el error real: + +@example +./pre-inst-env guile -c '(use-modules (gnu packages gnuevo))' +@end example + +Una vez que se construya correctamente su paquete, por favor, envíenos un +parche (@pxref{Envío de parches}). En cualquier caso, si necesita ayuda +también estaremos felices de ayudarle. Una vez el parche se haya incorporado +al repositorio de Guix, el nuevo paquete se construye automáticamente en las +plataformas disponibles por @url{http://hydra.gnu.org/jobset/gnu/master, +nuestro sistema de integración continua}. + +@cindex servidor de sustituciones +Las usuarias pueden obtener la nueva definición de paquete ejecutando +simplemente @command{guix pull} (@pxref{Invocación de guix pull}). Cuando +@code{@value{SUBSTITUTE-SERVER}} ha terminado de construir el paquete, la +instalación del paquete descarga automáticamente los binarios desde allí +(@pxref{Sustituciones}). El único lugar donde la intervención humana es +necesaria es en la revisión y aplicación del parche. + + +@menu +* Libertad del software:: Qué puede entrar en la distribución. +* Nombrado de paquetes:: ¿Qué hay en un nombre? +* Versiones numéricas:: Cuando el nombre no es suficiente. +* Sinopsis y descripciones:: Ayudar a las usuarias a encontrar el paquete + adecuado. +* Módulos Python:: Un toque de comedia británica. +* Módulos Perl:: Pequeñas perlas. +* Paquetes Java:: La parada del café. +* Tipografías:: Amor por las letras. +@end menu + +@node Libertad del software +@subsection Libertad del software + +@c =========================================================================== +@c +@c This file was generated with po4a. Translate the source file. +@c +@c =========================================================================== +@c Adapted from http://www.gnu.org/philosophy/philosophy.html. +@cindex software libre +El sistema operativo GNU se ha desarrollado para que las usuarias puedan +ejercitar su libertad de computación. GNU es @dfn{software libre}, lo que +significa ue las usuarias tienen las +@url{http://www.gnu.org/philosophy/free-sw.html,cuatro libertades +esenciales}: para ejecutar el programa, para estudiar y modificar el +programa en la forma de código fuente, para redistribuir copias exactas y +para distribuir versiones modificadas. Los paquetes encontrados en la +distribución GNU proporcionan únicamente software que permite estas cuatro +libertades. + +Además, la distribución GNU sigue las +@url{http://www.gnu.org/distros/free-system-distribution-guidelines.html,directrices +de distribución de software libre}. Entre otras cosas, estas directrices +rechazan firmware no-libre, recomendaciones de software no-libre y el +tratamiento de formas de tratar con marcas registradas y patentes. + +Algunos paquetes originales, que serían de otra manera software libre, +contienen un subconjunto pequeño y opcional que viola estas directrices, por +ejemplo debido a que ese subconjunto sea en sí código no-libre. Cuando esto +sucede, las partes indeseadas son eliminadas con parches o fragmentos de +código en la forma @code{origin} del paquete (@pxref{Definición de paquetes}). De +este modo, @code{guix build --source} devuelve las fuentes ``liberadas'' en +vez de la versión original de las fuentes. + + +@node Nombrado de paquetes +@subsection Nombrado de paquetes + +@cindex nombre de paquete +Un paquete tiene realmente dos nombres asociados con él: Primero, el nombre +de la @emph{variable Scheme} asociada, que aparece después de +@code{define-public}. A través de este nombre, el paquete está disponible en +código Scheme, por ejemplo como entrada de otro paquete. Segundo, la cadena +en el campo @code{name} de la definición de paquete. Este nombre se usa por +las órdenes de gestión de paquetes como @command{guix package} y +@command{guix build}. + +Ambos normalmente son iguales y corresponden a la conversión a minúsculas +del nombre de proyecto elegido por sus creadoras, con los guiones bajos +sustituidos por guiones. Por ejemplo, GNUnet está disponible como +@code{gnunet}, y SDL_net como @code{sdl-net}. + +No añadimos prefijos @code{lib} para paquetes de bibliotecas, a menos que +sean parte del nombre oficial del proyecto. Pero vea @ref{Módulos Python} y +@ref{Módulos Perl} para reglas especiales que conciernen a los módulos de +los lenguajes Python y Perl. + +Los nombres de paquetes de tipografías se manejan de forma diferente, +@pxref{Tipografías}. + + +@node Versiones numéricas +@subsection Versiones numéricas + +@cindex versión de paquete +Normalmente empaquetamos únicamente la última versión de un proyecto dado de +software libre. Pero a veces, por ejemplo para versiones de bibliotecas +incompatibles, se necesitan dos (o más) versiones del mismo paquete. Estas +necesitan nombres diferentes para las variables Scheme. Usamos el nombre +como se define en @ref{Nombrado de paquetes} para la versión más reciente; las +versiones previas usan el mismo nombre, añadiendo un @code{-} y el prefijo +menor del número de versión que permite distinguir las dos versiones. + +El nombre dentro de la definición de paquete es el mismo para todas las +versiones de un paquete y no contiene ningún número de versión. + +Por ejemplo, las versiones 2.24.20 y 3.9.12 de GTK+ pueden empaquetarse como +sigue: + +@example +(define-public gtk+ + (package + (name "gtk+") + (version "3.9.12") + ...)) +(define-public gtk+-2 + (package + (name "gtk+") + (version "2.24.20") + ...)) +@end example +Si también deseásemos GTK+3.8.2, se empaquetaría como +@example +(define-public gtk+-3.8 + (package + (name "gtk+") + (version "3.8.2") + ...)) +@end example + +@c See <https://lists.gnu.org/archive/html/guix-devel/2016-01/msg00425.html>, +@c for a discussion of what follows. +@cindex número de versión, para revisiones de VCS +De manera ocasional, empaquetamos instantáneas del sistema de control de +versiones (VCS) de las desarrolladoras originales en vez de publicaciones +formales. Esto debería permanecer como algo excepcional, ya que son las +desarrolladoras originales quienes deben clarificar cual es la entrega +estable. No obstante, a veces es necesario. Por tanto, ¿qué deberíamos poner +en el campo @code{version}? + +Claramente, tenemos que hacer visible el identificador de la revisión en el +VCS en la cadena de versión, pero tamién debemos asegurarnos que la cadena +de versión incrementa monotónicamente de manera que @command{guix package +--upgrade} pueda determinar qué versión es más moderna. Ya que los +identificadores de revisión, notablemente en Git, no incrementan +monotónicamente, añadimos un número de revisión que se incrementa cada vez +que actualizamos a una nueva instantánea. La versión que resulta debería ser +así: + +@example +2.0.11-3.cabba9e + ^ ^ ^ + | | `-- ID de revisión original + | | + | `--- revisión del paquete Guix + | +última versión de publicación +@end example + +Es una buena idea recortar los identificadores de revisión en el campo +@code{version} a, digamos, 7 dígitos. Esto evita una molestia estética +(asumiendo que la estética tiene importancia aquí) así como problemas +relacionados con los límites del sistema operativo como la longitud máxima +de una cadena de ejecución #! (127 bytes en el núcleo Linux). Es mejor usar +el identificador de revisión completo en @code{origin}, no obstante, para +evitar ambigüedades. Una definición típica de paquete sería así: + +@example +(define mi-paquete + (let ((commit "c3f29bc928d5900971f65965feaae59e1272a3f7") + (revision "1")) ;Revisión Guix del paquete + (package + (version (git-version "0.9" revision commit)) + (source (origin + (method git-fetch) + (uri (git-reference + (url "git://example.org/mi-paquete.git") + (commit commit))) + (sha256 (base32 "1mbikn@dots{}")) + (file-name (git-file-name name version)))) + ;; @dots{} + ))) +@end example + +@node Sinopsis y descripciones +@subsection Sinopsis y descripciones + +@cindex descripción de paquete +@cindex sinopsis de paquete +Como hemos visto previamente, cada paquete en GNU@tie{}Guix incluye una +sinopsis y una descripción (@pxref{Definición de paquetes}). Las sinopsis y +descripciones son importantes: son en lo que @command{guix package --search} +busca, y una pieza crucial de información para ayudar a las usuarias a +determinar si un paquete dado cubre sus necesidades. Consecuentemente, las +empaquetadoras deben prestar atención a qué se incluye en ellas. + +Las sinopsis deben empezar con mayúscula y no deben terminar con punto. No +deben empezar con un artículo que habitualmente no aporta nada; por ejemplo, +se prefiere ``Herramienta para chiribizar'' sobre ``Una herramienta que +chiribiza ficheros''. La sinopsis debe decir qué es el paquete---por +ejemplo, ``Utilidades básicas GNU (ficheros, texto, shell)''---o para qué se +usa---por ejemplo, la sinopsis de GNU@tie{}grep es ``Imprime líneas que +aceptadas por un patrón''. + +Tenga en cuenta que las sinopsis deben tener un claro significado para una +audiencia muy amplia. Por ejemplo, ``Manipula la alineación en el formato +SAM'' puede tener sentido para una investigadora de bioinformática con +experiencia, pero puede ser de poca ayuda o incluso llevar a confusión a una +audiencia no-especializada. Es una buena idea proporcionar una sinopsis que +da una idea del dominio de aplicación del paquete. En ese ejemplo, esto +podría ser algo como ``Manipula la alineación de secuencias de +nucleótidos'', lo que esperablemente proporciona a la usuaria una mejor idea +sobre si esto es lo que está buscando. + +Las descripciones deben tener entre cinco y diez líneas. Use frases +completas, y evite usar acrónimos sin introducirlos previamente. Por favor +evite frases comerciales como ``líder mundial'', ``de potencia industrial'' +y ``siguiente generación'', y evite superlativos como ``el más +avanzado''---no son útiles para las usuarias que buscan un paquete e incluso +pueden sonar sospechosas. En vez de eso, intente ceñirse a los hechos, +mencionando casos de uso y características. + +@cindex marcado Texinfo, en descripciones de paquetes +Las descripciones pueden incluir marcado Texinfo, lo que es útil para +introducir ornamentos como @code{@@code} o @code{@@dfn}, listas de puntos o +enlaces (@pxref{Overview,,, texinfo, GNU Texinfo}). Por consiguiente, debe +ser cuidadosa cuando use algunos caracteres, por ejemplo @samp{@@} y llaves, +que son los caracteres especiales básicos en Texinfo (@pxref{Special +Characters,,, texinfo, GNU Texinfo}). Las interfaces de usuaria como +@command{guix package --show} se encargan de su correcta visualización. + +Las sinopsis y descripciones son traducidas por voluntarias +@uref{http://translationproject.org/domain/guix-packages.html, en +Translation Project} para que todas las usuarias posibles puedan leerlas en +su lengua nativa. Las interfaces de usuaria las buscan y las muestran en el +idioma especificado por la localización actual. + +Para permitir a @command{xgettext} extraerlas como cadenas traducibles, las +sinopsis y descripciones @emph{deben ser cadenas literales}. Esto significa +que no puede usar @code{string-append} o @code{format} para construir estas +cadenas: + +@lisp +(package + ;; @dots{} + (synopsis "Esto es traducible") + (description (string-append "Esto " "*no*" " es traducible."))) +@end lisp + +La traducción requiere mucho trabajo, por lo que, como empaquetadora, le +rogamos que ponga incluso más atención a sus sinopsis y descripciones ya que +cada cambio puede suponer trabajo adicional para las traductoras. Para +ayudarlas, es posible hacer recomendaciones o instrucciones insertando +comentarios especiales como este (@pxref{xgettext Invocation,,, gettext, GNU +Gettext}): + +@example +;; TRANSLATORS: "X11 resize-and-rotate" should not be translated. +(description "ARandR is designed to provide a simple visual front end +for the X11 resize-and-rotate (RandR) extension. @dots{}") +@end example + + +@node Módulos Python +@subsection Módulos Python + +@cindex python +Actualmente empaquetamos Python 2 y Python 3, bajo los nombres de variable +Scheme @code{python-2} y @code{python} como se explica en @ref{Versiones numéricas}. Para evitar confusiones y conflictos de nombres con otros +lenguajes de programación, parece deseable que el nombre de paquete para un +módulo Python contenga la palabra @code{python}. + +Algunos módulos son compatibles únicamente con una versión de Python, otros +con ambas. Si el paquete Foo compila sólo con Python 3, lo llamamos +@code{python-foo}; si compila sólo con Python 2, lo llamamos +@code{python2-foo}. Si es compatible con ambas versiones, creamos dos +paquetes con los nombres correspondientes. + +Si un proyecto ya contiene la palabra @code{python}, la eliminamos; por +ejemplo, el módulo python-dateutil se empaqueta con los nombres +@code{python-dateutil} y @code{python2-dateutil}. Si el nombre del proyecto +empieza con @code{py} (por ejemplo @code{pytz}), este se mantiene y el +prefijo es el especificado anteriormente.. + +@subsubsection Especificación de dependencias +@cindex entradas, para paquetes Python + +La información de dependencias para paquetes Python está disponible +habitualmente en el árbol de fuentes, con varios grados de precisión: en el +fichero @file{setup.py}, en @file{requirements.txt} o en @file{tox.ini}. + +Su misión, cuando escriba una receta para un paquete Python, es asociar +estas dependencias con el tipo apropiado de ``entrada'' (@pxref{Referencia de ``package'', inputs}). Aunque el importador de @code{pypi} normalmente hace un +buen trabajo (@pxref{Invocación de guix import}), puede querer comprobar la +siguiente lista para determinar qué dependencia va dónde. + +@itemize + +@item +Actualmente empaquetamos con @code{setuptools} y @code{pip} instalados como +Python 3.4 tiene por defecto. Por tanto no necesita especificar ninguno de +ellos como entrada. @command{guix lint} le avisará si lo hace. + +@item +Las dependencias Python requeridas en tiempo de ejecución van en +@code{propagated-inputs}. Típicamente están definidas con la palabra clave +@code{install_requires} en @file{setup.py}, o en el fichero +@file{requirements.txt}. + +@item +Los paquetes Python requeridos únicamente durante la construcción---por +ejemplo, aquellos listados con la palabra clave @code{setup_requires} en +@file{setup.py}---o únicamente para pruebas---por ejemplo, aquellos en +@code{tests_require}---van en @code{native-inputs}. La razón es que (1) no +necesitan ser propagados ya que no se requieren en tiempo de ejecución, y +(2) en un entorno de compilación cruzada lo que necesitamos es la entrada +``nativa''. + +Ejemplos son las bibliotecas de pruebas @code{pytest}, @code{mock} y +@code{nose}. Por supuesto, si alguno de estos paquetes también se necesita +en tiempo de ejecución, necesita ir en @code{propagated-inputs}. + +@item +Todo lo que no caiga en las categorías anteriores va a @code{inputs}, por +ejemplo programas o bibliotecas C requeridas para construir los paquetes +Python que contienen extensiones C. + +@item +Si un paquete Python tiene dependencias opcionales (@code{extras_require}), +queda en su mano decidir si las añade o no, en base a la relación +utilidad/sobrecarga (@pxref{Envío de parches, @command{guix size}}). + +@end itemize + + +@node Módulos Perl +@subsection Módulos Perl + +@cindex perl +Los programas ejecutables Perl se nombran como cualquier otro paquete, +mediante el uso del nombre oficial en minúsculas. Para paquetes Perl que +contienen una única clase, usamos el nombre en minúsculas de la clase, +substituyendo todas las ocurrencias de @code{::} por guiones y agregando el +prefijo @code{perl-}. Por tanto la clase @code{XML::Parser} se convierte en +@code{perl-xml-parser}. Los módulos que contienen varias clases mantienen su +nombre oficial en minúsculas y también se agrega @code{perl-} al +inicio. Dichos módulos tienden a tener la palabra @code{perl} en alguna +parte de su nombre, la cual se elimina en favor del prefijo. Por ejemplo, +@code{libwww-perl} se convierte en @code{perl-libwww}. + + +@node Paquetes Java +@subsection Paquetes Java + +@cindex java +Los programas Java ejecutables se nombran como cualquier otro paquete, +mediante el uso del nombre oficial en minúsculas. + +Para evitar confusión y colisiones de nombres con otros lenguajes de +programación, es deseable que el nombre del paquete para un paquete Java +contenga el prefijo @code{java-}. Si el proyecto ya tiene la palabra +@code{java}, eliminamos esta; por ejemplo, el paquete @code{ngsjaga} se +empaqueta bajo el nombre @code{java-ngs}. + +Para los paquetes Java que contienen una clase única o una jerarquía +pequeña, usamos el nombre de clase en minúsculas, substituyendo todas las +ocurrencias de @code{.} por guiones y agregando el prefijo @code{java-}. Por +tanto la clase @code{apache.commons.cli} se convierte en el paquete +@code{java-apache-commons-cli}. + + +@node Tipografías +@subsection Tipografías + +@cindex tipografías +Para tipografías que no se instalan generalmente por una usuaria para +propósitos tipográficos, o que se distribuyen como parte de un paquete de +software más grande, seguimos las reglas generales de empaquetamiento de +software; por ejemplo, esto aplica a las tipografías distribuidas como parte +del sistema X.Org o las tipografías que son parte de TeX Live. + +Para facilitar a las usuarias la búsqueda de tipografías, los nombres para +otros paquetes que contienen únicamente tipografías se construyen como +sigue, independientemente del nombre de paquete oficial. + +El nombre de un paquete que contiene únicamente una familia tipográfica +comienza con @code{font-}; seguido por el nombre de la tipografía y un guión +si la tipografía es conocida, y el nombre de la familia tipográfica, donde +los espacios se sustituyen por guiones (y como es habitual, todas las letras +mayúsculas se transforman a minúsculas). Por ejemplo, la familia de +tipografías Gentium de SIL se empaqueta bajo el nombre de +@code{font-sil-gentium}. + +Para un paquete que contenga varias familias tipográficas, el nombre de la +colección se usa en vez del nombre de la familia tipográfica. Por ejemplo, +las tipografías Liberation consisten en tres familias: Liberation Sans, +Liberation Serif y Liberation Mono. Estas se podrían empaquetar por separado +bajo los nombres @code{font-liberation-sans}, etcétera; pero como se +distribuyen de forma conjunta bajo un nombre común, preferimos empaquetarlas +conjuntamente como @code{font-liberation}. + +En el caso de que varios formatos de la misma familia o colección +tipográfica se empaqueten de forma separada, una forma corta del formato, +precedida por un guión, se añade al nombre del paquete. Usamos @code{-ttf} +para tipografías TrueType, @code{-otf} para tipografías OpenType y +@code{-type1} para tipografías Tipo 1 PostScript. + + +@node Estilo de codificación +@section Estilo de codificación + +En general nuestro código sigue los Estándares de codificación GNU +(@pxref{Top,,, standards, GNU Coding Standards}). No obstante, no dicen +mucho de Scheme, así que aquí están algunas reglas adicionales. + +@menu +* Paradigma de programación:: Cómo componer sus elementos. +* Módulos:: ¿Dónde almacenar su código? +* Tipos de datos y reconocimiento de patrones:: Implementación de + estructuras de datos. +* Formato del código:: Convenciones de escritura. +@end menu + +@node Paradigma de programación +@subsection Paradigma de programación + +El código scheme en Guix está escrito en un estilo puramente funcional. Una +excepción es el código que incluye entrada/salida, y procedimientos que +implementan conceptos de bajo nivel, como el procedimiento @code{memoize}. + +@node Módulos +@subsection Módulos + +Los módulos Guile que están destinados a ser usados en el lado del +constructor deben encontrarse en el espacio de nombres @code{(guix build +@dots{})}. No deben hacer referencia a otros módulos Guix o GNU. No +obstante, no hay problema en usar un módulo del lado del constructor en un +módulo ``del lado del cliente''. + +Los módulos que tratan con el sistema GNU más amplio deben estar en el +espacio de nombres @code{(gnu @dots{})} en vez de en @code{(guix @dots{})}. + +@node Tipos de datos y reconocimiento de patrones +@subsection Tipos de datos y reconocimiento de patrones + +La tendencia en el Lisp clásico es usar listas para representar todo, y +recorrerlas ``a mano'' usando @code{car}, @code{cdr}, @code{cadr} y +compañía. Hay varios problemas con este estilo, notablemente el hecho de que +es difícil de leer, propenso a errores y una carga para informes adecuados +de errores de tipado. + +El código de Guix debe definir tipos de datos apropiados (por ejemplo, +mediante el uso @code{define-record-type*}) en vez de abusar de las +listas. Además debe usarse el reconocimiento de patrones, vía el módulo de +Guile @code{(ice-9 match)}, especialmente cuando se analizan listas. + +@node Formato del código +@subsection Formato del código + +@cindex dar formato al código +@cindex estilo de codificación +Cuando escribimos código Scheme, seguimos la sabiduría común entre las +programadoras Scheme. En general, seguimos las +@url{http://mumble.net/~campbell/scheme/style.txt, Reglas de estilo Lisp de +Riastradh}. Este documento resulta que también describe las convenciones más +usadas en el código Guile. Está lleno de ideas y bien escrito, así que +recomendamos encarecidamente su lectura. + +Algunas formas especiales introducidas en Guix, como el macro +@code{substitute*} tienen reglas de indentación especiales. Estas están +definidas en el fichero @file{.dir-locals.el}, el cual Emacs usa +automáticamente. Fíjese que además Emacs-Guix proporciona el modo +@code{guix-devel-mode} que indenta y resalta adecuadamente el código de Guix +(@pxref{Desarrollo,,, emacs-guix, The Emacs-Guix Reference Manual}). + +@cindex indentación, de código +@cindex formato, de código +Si no usa Emacs, por favor asegúrese de que su editor conoce esas +reglas. Para indentar automáticamente una definición de paquete también +puede ejecutar: + +@example +./etc/indent-code.el gnu/packages/@var{fichero}.scm @var{paquete} +@end example + +@noindent +Esto indenta automáticamente la definición de @var{paquete} en +@file{gnu/packages/@var{fichero}.scm} ejecutando Emacs en modo de +procesamiento de lotes. Para indentar un fichero completo, omita el segundo +parámetro: + +@example +./etc/indent-code.el gnu/services/@var{fichero}.scm +@end example + +@cindex Vim, edición de código Scheme +Si está editando código con Vim, le recomendamos ejecutar @code{:set +autoindent} para que el código se indente automáticamente mientras +escribe. Adicionalmente, +@uref{https://www.vim.org/scripts/script.php?script_id=3998, +@code{paredit.vim}} puede ayudar a manejar todos estos paréntesis. + +Requerimos que todos los procedimientos del nivel superior tengan una cadena +de documentación. Este requisito puede relajarse para procedimientos simples +privados en el espacio de nombres @code{(guix build @dots{})} no obstante. + +Los procedimientos no deben tener más de cuatro parámetros posicionales. Use +parámetros con palabras clave para procedimientos que toman más de cuatro +parámetros. + + +@node Envío de parches +@section Envío de parches + +El desarrollo se lleva a cabo usando el sistema de control de versiones +distribuido Git. Por lo tanto, no es estrictamente necesario el acceso al +repositorio. Son bienvenidas las contribuciones en forma de parches como los +producidos por @code{git format-patch} enviadas a la lista de correo +@email{guix-patches@@gnu.org}. + +Esta lista de correo está respaldada por una instancia de Debbugs accesible +en @uref{https://bugs.gnu.org/guix-patches}, la cual nos permite mantener el +seguimiento de los envíos. A cada mensaje enviado a esa lista de correo se +le asigna un número de seguimiento; la gente puede realizar aportaciones +sobre el tema mediante el envío de correos electrónicos a +@code{@var{NNN}@@debbugs.gnu.org}, donde @var{NNN} es el número de +seguimiento (@pxref{Envío de una serie de parches}). + +Le rogamos que escriba los mensajes de revisiones en formato ChangeLog +(@pxref{Change Logs,,, standards, GNU Coding Standards}); puede comprobar la +historia de revisiones en busca de ejemplos. + +Antes de enviar un parche que añade o modifica una definición de un paquete, +por favor recorra esta lista de comprobaciones: + +@enumerate +@item +Si las autoras del paquete software proporcionan una firma criptográfica +para el archivo de la versión, haga un esfuerzo para verificar la +autenticidad del archivo. Para un fichero de firma GPG separado esto puede +hacerse con la orden @code{gpg --verify}. + +@item +Dedique algún tiempo a proporcionar una sinopsis y descripción adecuadas +para el paquete. @xref{Sinopsis y descripciones}, para algunas directrices. + +@item +Ejecute @code{guix lint @var{paquete}}, donde @var{paquete} es el nombre del +paquete nuevo o modificado, y corrija cualquier error del que informe +(@pxref{Invocación de guix lint}). + +@item +Asegurese de que el paquete compile en su plataforma, usando @code{guix +build @var{package}}. + +@item +También le recomendamos que pruebe a construir el paquete en otras +plataformas disponibles. Como puede no disponer de acceso a dichas +plataformas hardware físicamente, le recomendamos el uso de +@code{qemu-binfmt-service-type} para emularlas. Para activarlo, añada el +siguiente servicio a la lista de servicios en su configuración +@code{operating-system}: + +@example +(service qemu-binfmt-service-type + (qemu-binfmt-configuration + (platforms (lookup-qemu-platforms "arm" "aarch64" "mips64el")) + (guix-support? #t))) +@end example + +Una vez hecho esto, reconfigure su sistema. + +Enotonces podrá construir paquetes para diferentes plataformas mediante la +opción @code{--system}. Por ejemplo, para la construcción del paquete +"hello" para las arquitecturas armhf, aarch64 o mips64 ejecutaría las +siguientes órdenes, respectivamente: +@example +guix build --system=armhf-linux --rounds=2 hello +guix build --system=aarch64-linux --rounds=2 hello +guix build --system=mips64el-linux --rounds=2 hello +@end example + +@item +@cindex empaquetamientos +Asegurese de que el paquete no usa copias empaquetadas de software ya +disponible como paquetes separados. + +A veces, paquetes incluyen copias embebidas del código fuente de sus +dependencias para conveniencia de las usuarias. No obstante, como +distribución, queremos asegurar que dichos paquetes efectivamente usan la +copia que ya tenemos en la distribución si hay ya una. Esto mejora el uso de +recursos (la dependencia es construida y almacenada una sola vez), y permite +a la distribución hacer cambios transversales como aplicar actualizaciones +de seguridad para un software dado en un único lugar y que afecte a todo el +sistema---algo que esas copias embebidas impiden. + +@item +Eche un vistazo al perfil mostrado por @command{guix size} (@pxref{Invocación de guix size}). Esto le permitirá darse cuenta de referencias a otros paquetes +retenidas involuntariamente. También puede ayudar a determinar si se debe +dividir el paquete (@pxref{Paquetes con múltiples salidas}), y qué +dependencias opcionales deben usarse. En particular, evite añadir +@code{texlive} como una dependencia: debido a su tamaño extremo, use +@code{texlive-tiny} o @code{texlive-union}. + +@item +Para cambios importantes, compruebe que los paquetes dependientes (si +aplica) no se ven afectados por el cambio; @code{guix refresh +--list-dependent @var{package}} le ayudará a hacerlo (@pxref{Invocación de guix refresh}). + +@c See <https://lists.gnu.org/archive/html/guix-devel/2016-10/msg00933.html>. +@cindex estrategia de ramas +@cindex estrategia de planificación de reconstrucciones +En base al número de paquetes dependientes y, por tanto, del tamaño de la +reconstrucción inducida, los revisiones van a ramas separadas, según estas +líneas: + +@table @asis +@item 300 paquetes dependientes o menos +rama @code{master} (cambios no disruptivos). + +@item entre 300 y 1.200 paquetes dependientes +rama @code{staging} (cambios no disruptivos). Esta rama está pensada para +ser incorporada en @code{master} cada 3 semanas más o menos. Ramas temáticas +(por ejemplo, una actualización de la pila de GNOME) pueden ir en una rama +específica (digamos, @code{gnome-updates}). + +@item más de 1.200 paquetes dependientes +rama @code{core-updates} (puede incluir cambios mayores y potencialmente +disruptivos). Esta rama está pensada para ser incluida en @code{master} cada +2,5 más o menos. +@end table + +Todas estas ramas son @uref{https://hydra.gnu.org/project/gnu, seguidas por +nuestra granja de construcción} e incluidas en @code{master} una vez todo se +ha construido satisfactoriamente. Esto nos permite corregir errores antes de +que afecten a usuarias, y reducir la ventana durante la cual los binarios +preconstruidos no están disponibles. + +@c TODO: It would be good with badges on the website that tracks these +@c branches. Or maybe even a status page. +Generalmente, ramas distintas a @code{master} se consideran +@emph{congeladas} si ha habido una evaluación reciente, o hay una rama +@code{-next} correspondiente. Por favor, pregunte en la lista de correo o en +IRC si no está segura de dónde colocar un parche. + +@item +@cindex determinismo, del proceso de construcción +@cindex construcciones reproducibles, comprobar +Compruebe si el proceso de construcción de un paquete es determinista. Esto +significa típicamente comprobar si una construcción independiente del +paquete ofrece exactamente el mismo resultado que usted obtuvo, bit a bit. + +Una forma simple de hacerlo es construyendo el mismo paquete varias veces +seguidas en su máquina (@pxref{Invocación de guix build}): + +@example +guix build --rounds=2 mi-paquete +@end example + +Esto es suficiente una clase común de problemas de no-determinismo, como las +marcas de tiempo o salida generada aleatoriamente en el resultado de la +construcción. + +Otra opción es el uso de @command{guix challenge} (@pxref{Invocación de guix challenge}). Puede ejecutarse una vez la revisión del paquete haya sido +publicada y construida por @code{@value{SUBSTITUTE-SERVER}} para comprobar +si obtuvo el mismo resultado que usted. Mejor aún: encuentre otra máquina +que pueda construirla y ejecute @command{guix publish}. Ya que la máquina +remota es probablemente diferente a la suya, puede encontrar problemas de +no-determinismo relacionados con el hardware---por ejemplo, el uso de un +conjunto de instrucciones extendido diferente---o con el núcleo del sistema +operativo---por ejemplo, dependencias en @code{uname} o ficheros +@file{/proc}. + +@item +Cuando escriba documentación, por favor use construcciones neutrales de +género para referirse a la gente@footnote{NdT: En esta traducción se ha +optado por usar el femenino para referirse a @emph{personas}, ya que es el +género gramatical de dicha palabra. Aunque las construcciones impersonales +pueden adoptarse en la mayoría de casos, también pueden llegar a ser muy +artificiales en otros usos del castellano; en ocasiones son directamente +imposibles. Algunas construcciones que proponen la neutralidad de género +dificultan la lecura automática (-x), o bien dificultan la corrección +automática (-e), o bien aumentan significativamente la redundancia y reducen +del mismo modo la velocidad en la lectura (-as/os, -as y -os). No obstante, +la adopción del genero neutro heredado del latín, el que en castellano se ha +unido con el masculino, como construcción neutral de género se considera +inaceptable, ya que sería equivalente al ``it'' en inglés, nada más lejos de +la intención de las autoras originales del texto.}, como +@uref{https://en.wikipedia.org/wiki/Singular_they, singular ``they''@comma{} +``their''@comma{} ``them''} y demás. + +@item +Compruebe que su parche contiene únicamente un conjunto relacionado de +cambios. Agrupando cambios sin relación dificulta y ralentiza la revisión. + +Ejemplos de cambios sin relación incluyen la adición de varios paquetes, o +una actualización de un paquete junto a correcciones a ese paquete. + +@item +Por favor, siga nuestras reglas de formato de código, posiblemente +ejecutando el guión @command{etc/indent-code.el} para que lo haga +automáticamente por usted (@pxref{Formato del código}). + +@item +Cuando sea posible, use espejos en la URL de las fuentes (@pxref{Invocación de guix download}). Use URL fiables, no generadas. Por ejemplo, los archivos de +GitHub no son necesariamente idénticos de una generación a la siguiente, así +que en este caso es normalmente mejor clonar el repositorio. No use el campo +@command{name} en la URL: no es muy útil y si el nombre cambia, la URL +probablemente estará mal. + +@end enumerate + +Cuando publique un parche a la lista de correo, use @samp{[PATCH] @dots{}} +como el asunto. Puede usar su cliente de correo o la orden @command{git +send-email} (@pxref{Envío de una serie de parches}). Preferimos recibir los parches +en texto plano, ya sea en línea o como adjuntos MIME. Se le recomienda que +preste atención por si su cliente de correo cambia algo como los saltos de +línea o la indentación, lo que podría potencialmente romper los parches. + +Cuando un error es resuelto, por favor cierre el hilo enviando un correo a +@email{@var{NNN}-done@@debbugs.gnu.org}. + +@unnumberedsubsec Envío de una serie de parches +@anchor{Envío de una serie de parches} +@cindex series de parches +@cindex @code{git send-email} +@cindex @code{git-send-email} + +@c Debbugs bug: https://debbugs.gnu.org/db/15/15361.html +Cuando envíe una serie de parches (por ejemplo, usando @code{git +send-email}), por favor mande primero un mensaje a +@email{guix-patches@@gnu.org}, y después mande los parches siguientes a +@email{@var{NNN}@@debbugs.gnu.org} para asegurarse de que se mantienen +juntos. Véase @uref{https://debbugs.gnu.org/Advanced.html, la documentación +de Debbugs} para más información. diff --git a/doc/guix.es.texi b/doc/guix.es.texi new file mode 100644 index 0000000000..ece6073f99 --- /dev/null +++ b/doc/guix.es.texi @@ -0,0 +1,26015 @@ +\input texinfo +@c =========================================================================== +@c +@c This file was generated with po4a. Translate the source file. +@c +@c =========================================================================== +@c -*-texinfo-*- + +@c %**start of header +@setfilename guix.es.info +@documentencoding UTF-8 +@documentlanguage es +@frenchspacing on +@settitle Manual de referencia de GNU Guix +@c %**end of header + +@include version-es.texi + +@c Identifier of the OpenPGP key used to sign tarballs and such. +@set OPENPGP-SIGNING-KEY-ID 3CE464558A84FDC69DB40CFB090B11993D9AEBB5 +@set KEY-SERVER pool.sks-keyservers.net + +@c The official substitute server used by default. +@set SUBSTITUTE-SERVER ci.guix.es.info + +@copying +Copyright @copyright{} 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019 +Ludovic Courtès@* Copyright @copyright{} 2013, 2014, 2016 Andreas Enge@* +Copyright @copyright{} 2013 Nikita Karetnikov@* Copyright @copyright{} 2014, +2015, 2016 Alex Kost@* Copyright @copyright{} 2015, 2016 Mathieu Lirzin@* +Copyright @copyright{} 2014 Pierre-Antoine Rault@* Copyright @copyright{} +2015 Taylan Ulrich Bayırlı/Kammer@* Copyright @copyright{} 2015, 2016, 2017 +Leo Famulari@* Copyright @copyright{} 2015, 2016, 2017, 2018, 2019 Ricardo +Wurmus@* Copyright @copyright{} 2016 Ben Woodcroft@* Copyright @copyright{} +2016, 2017, 2018 Chris Marusich@* Copyright @copyright{} 2016, 2017, 2018, +2019 Efraim Flashner@* Copyright @copyright{} 2016 John Darrington@* +Copyright @copyright{} 2016, 2017 ng0@* Copyright @copyright{} 2016, 2017, +2018, 2019 Jan Nieuwenhuizen@* Copyright @copyright{} 2016 Julien Lepiller@* +Copyright @copyright{} 2016 Alex ter Weele@* Copyright @copyright{} 2016, +2017, 2018, 2019 Christopher Baines@* Copyright @copyright{} 2017, 2018 +Clément Lassieur@* Copyright @copyright{} 2017, 2018 Mathieu Othacehe@* +Copyright @copyright{} 2017 Federico Beffa@* Copyright @copyright{} 2017, +2018 Carlo Zancanaro@* Copyright @copyright{} 2017 Thomas Danckaert@* +Copyright @copyright{} 2017 humanitiesNerd@* Copyright @copyright{} 2017 +Christopher Allan Webber@* Copyright @copyright{} 2017, 2018 Marius Bakke@* +Copyright @copyright{} 2017 Hartmut Goebel@* Copyright @copyright{} 2017 +Maxim Cournoyer@* Copyright @copyright{} 2017, 2018 Tobias Geerinckx-Rice@* +Copyright @copyright{} 2017 George Clemmer@* Copyright @copyright{} 2017 +Andy Wingo@* Copyright @copyright{} 2017, 2018, 2019 Arun Isaac@* Copyright +@copyright{} 2017 nee@* Copyright @copyright{} 2018 Rutger Helling@* +Copyright @copyright{} 2018 Oleg Pykhalov@* Copyright @copyright{} 2018 Mike +Gerwitz@* Copyright @copyright{} 2018 Pierre-Antoine Rouby@* Copyright +@copyright{} 2018 Gábor Boskovits@* Copyright @copyright{} 2018 Florian +Pelz@* Copyright @copyright{} 2018 Laura Lazzati@* Copyright @copyright{} +2018 Alex Vong@* Copyright @copyright{} 2019 Miguel Ángel Arruga Vivas +(traducción)@* + +Se garantiza el permiso de copia, distribución y/o modificación de este +documento bajo los términos de la licencia de documentación libre de GNU +(GNU Free Documentation License), versión 1.3 o cualquier versión posterior +publicada por la Free Software Foundation; sin secciones invariantes, sin +textos de cubierta delantera ni trasera. Una copia de la licencia está +incluida en la sección titulada ``GNU Free Documentation License''. +@end copying + +@dircategory Administración del sistema +@direntry +* Guix: (guix.es). Gestión del software instalado y la + configuración del sistema. +* guix package: (guix.es)Llamar a guix package. Instalación, borrado y + actualización de paquetes. +* guix gc: (guix.es)Llamar a guix gc. Reclamar espacio de disco sin usar. +* guix pull: (guix.es)Llamar a guix pull. Actualización de la lista + disponible de paquetes. +* guix system: (guix.es)Llamar a guix system. Gestión de la configuración + del sistema operativo. +@end direntry + +@dircategory Desarrollo de software +@direntry +* guix environment: (guix.es)Llamar a guix environment. Construcción de + entornos de + desarrollo con + Guix. +* guix build: (guix.es)Llamar a guix build. Construcción de paquetes. +* guix pack: (guix.es)Llamar a guix pack. Creación de empaquetados + binarios. +@end direntry + +@titlepage +@title Manual de referencia de GNU Guix +@subtitle Uso del gestor de paquetes funcional GNU Guix. +@author Las desarrolladoras de GNU Guix + +@page +@vskip 0pt plus 1filll +Edición @value{EDITION} @* @value{UPDATED} @* + +@insertcopying +@end titlepage + +@contents + +@c ********************************************************************* +@node Top +@top GNU Guix + +Este documento describe GNU Guix versión @value{VERSION}, una herramienta +funcional de gestión de paquetes escrita para el sistema GNU. + +@c TRANSLATORS: You can replace the following paragraph with information on +@c how to join your own translation team and how to report issues with the +@c translation. +Este manual también está disponible en Inglés (@pxref{Top,,, guix, GNU Guix +Reference Manual}), en Francés (@pxref{Top,,, guix.fr, Manuel de référence +de GNU Guix}) y Alemán (@pxref{Top,,, guix.de, Referenzhandbuch zu GNU +Guix}). Si quiere traducirlo a su lengua nativa, considere unirse a +@uref{https://translationproject.org/domain/guix-manual.html, Translation +Project}. + +@menu +* Introducción:: ¿Qué es esto de Guix? +* Instalación:: Instalar Guix. +* Instalación del sistema:: Instalar el sistema operativo completo. +* Gestión de paquetes:: Instalación de paquetes, actualización, etc. +* Desarrollo:: Desarrollo de software asistido por Guix +* Interfaz programática:: Uso de Guix en Scheme. +* Utilidades:: Órdenes de gestión de paquetes. +* Configuración del sistema:: Configurar el sistema operativo. +* Documentación:: Navegar por los manuales de usuaria del + software. +* Instalación de ficheros de depuración:: Alimentación del depurador. +* Actualizaciones de seguridad:: Desplegar correcciones de seguridad + rápidamente. +* Lanzamiento inicial:: GNU/Linux construido de cero. +* Transportar:: Adaptación para otra plataforma o núcleo. +* Contribuir:: ¡Se necesita su ayuda! + +* Reconocimientos:: ¡Gracias! +* Licencia de documentación libre GNU:: La licencia de este manual. +* Índice de conceptos:: Conceptos. +* Índice programático:: Tipos de datos, funciones y variables. + +@detailmenu + --- La lista detallada de nodos --- + + + +Introducción + + + +* La forma de gestión de software de Guix:: Qué es especial. +* Distribución GNU:: Los paquetes y herramientas. + +Instalación + + + +* Instalación binaria:: ¡Poner Guix en funcionamiento en nada de + tiempo! +* Requisitos:: Software necesario para construir y ejecutar + Guix. +* Ejecución de la batería de pruebas:: Probar Guix. +* Preparación del daemon:: Preparar el entorno del daemon de + construcción. +* Invocación de guix-daemon:: Ejecutar el daemon de construcción. +* Configuración de la aplicación:: Configuración específica de la + aplicación. + +Preparación del daemon + + + +* Configuración del entorno de construcción:: Preparar el entorno aislado + de construcción. +* Configuración de delegación del daemon:: Delegar construcciones a + máquinas remotas. +* Soporte de SELinux:: Uso de una política SELinux para el daemon. + +Instalación del sistema + + + +* Limitaciones:: Qué puede esperar. +* Consideraciones sobre el hardware:: Hardware soportado. +* Instalación desde memoria USB y DVD:: Preparar el medio de instalación. +* Preparación para la instalación:: Red, particionado, etc. +* Instalación gráfica guiada:: Instalación gráfica fácil. +* Instalación manual:: Instalación manual para artistas del teclado. +* Tras la instalación del sistema:: Cuando la instalación ha finalizado + satisfactoriamente. +* Instalación de Guix en una máquina virtual:: El patio de recreo del + sistema Guix. +* Construcción de la imagen de instalación:: Cómo esto llega a ser. + +Instalación manual + + + +* Distribución de teclado y red y particionado:: Configuración inicial. +* Procedimiento de instalación:: Instalación. + +Gestión de paquetes + + + +* Características:: Cómo Guix dará brillo a su vida. +* Invocación de guix package:: Instalación de paquetes, borrado, etc. +* Sustituciones:: Descargar binarios pre-construidos. +* Paquetes con múltiples salidas:: Un único paquete de fuentes, + múltiples salidas. +* Invocación de guix gc:: Ejecutar el recolector de basura. +* Invocación de guix pull:: Obtener la última versión de Guix y la + distribución. +* Canales:: Personalizar el recolector de basura. +* Inferiores:: Interactuar con otra revisión de Guix. +* Invocación de guix describe:: Muestra información acerca de su + revisión de Guix. +* Invocación de guix archive:: Exportar e importar ficheros del almacén. + +Sustituciones + + + +* Servidor oficial de sustituciones.:: Una fuente particular de + sustituciones. +* Autorización de servidores de sustituciones:: Cómo habilitar o + deshabilitar + sustituciones. +* Verificación de sustituciones:: Cómo verifica las sustituciones Guix. +* Configuración de la pasarela.:: Cómo obtener sustituciones a través de + una pasarela. +* Fallos en las sustituciones:: Qué pasa cuando una sustitución falla. +* Sobre la confianza en binarios:: ¿Cómo puede usted confiar en esa masa + informe de datos binarios? + +Desarrollo + + + +* Invocación de guix environment:: Configurar entornos de desarrollo. +* Invocación de guix pack:: Creación de empaquetados de software. + +Interfaz programática + + + +* Módulos de paquetes:: Paquetes bajo el punto de vista del + programador. +* Definición de paquetes:: Definir nuevos paquetes. +* Sistemas de construcción:: Especificar como se construyen los paquetes. +* El almacén:: Manipular el almacén de paquetes. +* Derivaciones:: Interfaz de bajo nivel de las derivaciones de + los paquetes. +* La mónada del almacén:: Interfaz puramente funcional del almacén. +* Expresiones-G:: Manipular expresiones de construcción. +* Invocación de guix repl:: Enredar con Guix interactivamente. + +Definición de paquetes + + + +* Referencia de ``package'':: El tipo de datos de los paquetes. +* Referencia de ``origin'':: El tipo de datos de orígenes. + +Utilidades + + + +* Invocación de guix build:: Construir paquetes desde la línea de + órdenes. +* Invocación de guix edit:: Editar las definiciones de paquetes. +* Invocación de guix download:: Descargar un fichero e imprimir su hash. +* Invocación de guix hash:: Calcular el hash criptográfico de un fichero. +* Invocación de guix import:: Importar definiciones de paquetes. +* Invocación de guix refresh:: Actualizar definiciones de paquetes. +* Invocación de guix lint:: Encontrar errores en definiciones de paquetes. +* Invocación de guix size:: Perfilar el uso del disco. +* Invocación de guix graph:: Visualizar el grafo de paquetes. +* Invocación de guix publish:: Compartir sustituciones. +* Invocación de guix challenge:: Poner a prueba servidores de + sustituciones. +* Invocación de guix copy:: Copiar a y desde un almacén remoto. +* Invocación de guix container:: Aislamiento de procesos. +* Invocación de guix weather:: Comprobar la disponibilidad de + sustituciones. +* Invocación de guix processes:: Enumerar los procesos cliente. + +Invocación de @command{guix build} + + + +* Opciones comunes de construcción:: Opciones de construcción para la + mayoría de órdenes. +* Opciones de transformación de paquetes:: Crear variantes de paquetes. +* Opciones de construcción adicionales:: Opciones específicas de 'guix + build'. +* Depuración de fallos de construcción:: Experiencia de empaquetamiento + en la vida real. + +Configuración del sistema + + + +* Uso de la configuración del sistema:: Personalizar su sistema GNU. +* Referencia de ``operating-system'':: Detalle de las declaraciones de + sistema operativo. +* Sistemas de ficheros:: Configurar el montaje de sistemas de ficheros. +* Dispositivos traducidos:: Procesamiento extra de dispositivos de bloques. +* Cuentas de usuaria:: Especificar las cuentas de usuaria. +* Distribución de teclado:: Cómo interpreta el sistema las pulsaciones + del teclado. +* Localizaciones:: Configuración de idioma y convenciones + culturales. +* Servicios:: Especificar los servicios del sistema. +* Programas con setuid:: Programas que se ejecutan con privilegios de + root. +* Certificados X.509:: Verificar servidores HTTPS. +* Selector de servicios de nombres:: Configurar el selector de servicios de + nombres de libc. +* Disco en RAM inicial:: Arranque de Linux-Libre. +* Configuración del gestor de arranque:: Configurar el gestor de arranque. +* Invocación de guix system:: Instanciar una configuración del sistema. +* Ejecutar Guix en una máquina virtual:: Cómo ejecutar el sistema Guix en + una máquina virtual. +* Definición de servicios:: Añadir nuevas definiciones de servicios. + +Servicios + + + +* Servicios base:: Servicios esenciales del sistema. +* Ejecución de tareas programadas:: El servicio mcron. +* Rotación de logs:: El servicio rottlog. +* Servicios de red:: Configuración de red, daemon SSH, etc. +* Sistema X Window:: Interfaz gráfica. +* Servicios de impresión:: Soporte de impresoras locales y remotas. +* Servicios de escritorio:: D-Bus y servicios de escritorio. +* Servicios de sonido:: Servicios de ALSA y Pulseaudio. +* Servicios de bases de datos:: Bases de datos SQL, almacenes de + clave-valor, etc. +* Servicios de correo:: IMAP, POP3, SMTP y todo eso. +* Servicios de mensajería:: Servicios de mensajería. +* Servicios de telefonía:: Servicios de telefonía. +* Servicios de monitorización:: Servicios de monitorización. +* Servicios Kerberos:: Servicios Kerberos. +* Servicios Web:: Servidores Web. +* Servicios de certificados:: Certificados TLS via Let's Encrypt. +* Servicios DNS:: Demonios DNS. +* Servicios VPN:: Demonios VPN. +* Sistema de ficheros en red:: Servicios relacionados con NFS. +* Integración continua:: El servicio Cuirass. +* Servicios de gestión de energía:: Extender la vida de la batería. +* Servicios de audio:: El MPD. +* Servicios de virtualización:: Servicios de virtualización. +* Servicios de control de versiones:: Proporcionar acceso remoto a + repositorios Git. +* Servicios de juegos:: Servidores de juegos. +* Servicios misceláneos:: Otros servicios. + +Definición de servicios + + + +* Composición de servicios:: El modelo para la composición de servicios. +* Tipos de servicios y servicios:: Tipos y servicios +* Referencia de servicios:: Referencia de la API. +* Servicios de Shepherd:: Un tipo de servicio particular. + +@end detailmenu +@end menu + +@c ********************************************************************* +@node Introducción +@chapter Introducción + +@cindex propósito +GNU Guix@footnote{``Guix'' se pronuncia tal y como se escribe en castellano, +``gi:ks'' en el alfabeto fonético internacional (IPA).} es una herramienta +de gestión de paquetes y una distribucion del sistema GNU. Guix facilita a +usuarias sin privilegios la instalación, actualización o borrado de paquetes +de software, la vuelta a un conjunto de paquetes previo atómicamente, la +construcción de paquetes desde las fuentes, y ayuda de forma general en la +creación y mantenimiento de entornos software. + +@cindex Sistema Guix +@cindex GuixSD, ahora sistema Guix +@cindex Distribución de Sistema Guix, ahora sistema Guix +Puede instalar GNU@tie{}Guix sobre un sistema GNU/Linux existente, donde +complementará las herramientas disponibles sin interferencias +(@pxref{Instalación}), o puede usarse como un sistema operativo en sí +mismo, el @dfn{sistema@tie{}Guix}@footnote{Solíamos referirnos al sistema +Guix como ``Distribución de sistema Guix'' o ``GuixSD''. Ahora consideramos +que tiene más sentido agrupar todo bajo la etiqueta ``Guix'' ya que, después +de todo, el sistema Guix está inmediatamente disponible a través de la orden +@command{guix system}, ¡incluso cuando usa una distribución distinta por +debajo!}. @xref{Distribución GNU}. + +@menu +* La forma de gestión de software de Guix:: Qué es especial. +* Distribución GNU:: Los paquetes y herramientas. +@end menu + +@node La forma de gestión de software de Guix +@section La forma de gestión de software de Guix + +@cindex interfaces de usuaria +Guix proporciona una interfaz de gestión de paquetes de línea de ordenes +(@pxref{Gestión de paquetes}), un conjunto de utilidades de línea de órdenes +(@pxref{Utilidades}), así como interfaces programáticas Scheme +(@pxref{Interfaz programática}). +@cindex daemon de construcción +Su @dfn{daemon de construcción} es responsable de la construcción de +paquetes en delegación de las usuarias (@pxref{Preparación del daemon}) y de +la descarga de binarios preconstruidos de fuentes autorizadas +(@pxref{Sustituciones}) + +@cindex extensibilidad de la distribución +@cindex personalización, de paquetes +Guix incluye definiciones de paquetes para muchos paquetes GNU y no-GNU, +todos los cuales @uref{https://www.gnu.org/philosophy/free-sw.html, respetan +la libertad de computación de la usuaria}. Es @emph{extensible}: las +usuarias pueden escribir sus propias definiciones de paquetes +(@pxref{Definición de paquetes}) y hacerlas disponibles como módulos +independientes de paquetes (@pxref{Módulos de paquetes}). También es +@emph{personalizable}: las usuarias pueden @emph{derivar} definiciones de +paquetes especializadas de las existentes, inclusive desde la línea de +órdenes (@pxref{Opciones de transformación de paquetes}). + +@cindex gestión de paquetes funcional +@cindex aislamiento +En su implementación, Guix utiliza la disciplina de @dfn{gestión de paquetes +funcional} en la que Nix fue pionero (@pxref{Reconocimientos}). En Guix, el +proceso de construcción e instalación es visto como una @emph{función}, en +el sentido matemático. Dicha función toma entradas, como los guiones de +construcción, un compilador, unas bibliotecas y devuelve el paquete +instalado. Como función pura, su resultado únicamente depende de sus +entradas---por ejemplo, no puede hacer referencia a software o guiones que +no fuesen pasados explícitamente como entrada. Una función de construcción +siempre produce el mismo resultado cuando se le proporciona un conjunto de +entradas dado. No puede modificar el entorno del sistema que la ejecuta de +ninguna forma; por ejemplo, no puede crear, modificar o borrar archivos +fuera de sus directorios de construcción e instalación. Esto se consigue +ejecutando los procesos de construcción en entornos aislados (o +@dfn{contenedores}), donde únicamente sus entradas explícitas son visibles. + +@cindex almacén +El resultado de las funciones de construcción de paquetes es @dfn{almacenado +en la caché} en el sistema de ficheros, en un directorio especial llamado +@dfn{el almacén} (@pxref{El almacén}). Cada paquete se instala en un +directorio propio en el almacén---por defecto, bajo @file{/gnu/store}. El +nombre del directorio contiene el hash de todas las entradas usadas para +construir el paquete; por tanto, cambiar una entrada resulta en un nombre de +directorio distinto. + +Esta aproximación es el cimiento de las avanzadas características de Guix: +capacidad para la actualización transaccional y vuelta-atrás de paquetes, +instalación en el ámbito de la usuaria y recolección de basura de paquetes +(@pxref{Características}). + + +@node Distribución GNU +@section Distribución GNU + +@cindex Sistema Guix +Guix viene con una distribución del sistema GNU consistente en su totalidad +de software libre@footnote{El término ``libre'' aquí se refiere a la +@url{http://www.gnu.org/philosophy/free-sw.html,libertad proporcionada a las +usuarias de dicho software}.}. La distribución puede instalarse +independientemente (@pxref{Instalación del sistema}), pero también es posible +instalar Guix como un gestor de paquetes sobre un sistema GNU/Linux +existente (@pxref{Instalación}). Para distinguir entre las dos opciones, +nos referimos a la distribución independiente como el sistema@tie{}Guix. + +La distribución proporciona paquetes principales de GNU como GNU libc, GCC y +Binutils, así como muchas aplicaciones GNU y no-GNU. La lista completa de +paquetes disponibles puede navegarse +@url{http://www.gnu.org/software/guix/packages,en línea} o ejecutando +@command{guix package} (@pxref{Invocación de guix package}): + +@example +guix package --list-available +@end example + +Nuestro objetivo es proporcionar una distribución práctica con 100% software +libre basada en Linux y otras variantes de GNU, con un enfoque en la +promoción y la alta integración de componentes GNU, y un énfasis en +programas y herramientas que ayuden a las usuarias a ejercitar esa libertad. + +Actualmente hay paquetes disponibles para las siguientes plataformas: + +@table @code + +@item x86_64-linux +arquitectura @code{x86_64} de Intel/AMD, núcleo Linux-Libre; + +@item i686-linux +arquitectura de 32-bits Intel (IA32), núcleo Linux-Libre; + +@item armhf-linux +arquitectura ARMv7-A con coma flotante hardware, Thumb-2 y NEON, usando la +interfaz binaria de aplicaciones (ABI) EABI con coma flotante hardware, y el +núcleo Linux-Libre. + +@item aarch64-linux +procesadores de 64-bits ARMv8 little-endian, núcleo Linux-Libre. Está +actualmente en una fase experimental, con soporte +limitado. @xref{Contribuir}, para cómo ayudar. + +@item mips64el-linux +procesadores MIPS 64-bits little-endian, específicamente las series +Loongson, n32 ABI, y núcleo Linux-Libre. + +@end table + +Con el sistema@tie{}Guix, @emph{declara} todos los aspectos de la +configuración del sistema y Guix se hace cargo de instanciar la +configuración de manera transaccional, reproducible y sin estado global +(@pxref{Configuración del sistema}). El sistema Guix usa el núcleo Linux-libre, +el sistema de inicialización Shepherd (@pxref{Introducción,,, shepherd, The +GNU Shepherd Manual}), las conocidas utilidades y herramientas de +compilación GNU, así como el entorno gráfico o servicios del sistema de su +elección. + +El sistema Guix está disponible en todas las plataformas previas excepto +@code{mips64el-linux}. + +@noindent +Para información sobre el transporte a otras arquitecturas o núcleos, +@pxref{Transportar}. + +La construcción de esta distribución es un esfuerzo cooperativo, ¡y esta +invitada a unirse! @xref{Contribuir}, para información sobre cómo puede +ayudar. + + +@c ********************************************************************* +@node Instalación +@chapter Instalación + +@cindex instalar Guix + +@quotation Nota +Recomendamos el uso de este @uref{https://git.savannah.gnu.org/cgit/guix." +"git/plain/etc/guix-install.sh, guión de shell de instalación} para instalar +Guix sobre un sistema GNU/Linux en ejecución, de aquí en adelante referido +como una @dfn{distribución distinta}.@footnote{Esta sección está dedicada a +la instalación del gestor de paquetes, que puede realizarse sobre un sistema +GNU/Linux ya en ejecución. Si, en vez de eso, desdea instalar el sistema +operativo GNU completo, @pxref{Instalación del sistema}.} El guión automatiza la +descarga, instalación y configuración inicial de Guix. Debe ejecutarse como +la usuaria de administración root. +@end quotation + +@cindex distribución distinta +@cindex directorios relacionados con una distribución distinta +Cuando está instalado sobre una distribución distinta, GNU@tie{}Guix +complementa las herramientas disponibles sin interferencias. Sus datos +radican exclusivamente en dos directorios, normalmente @file{/gnu/store} y +@file{/var/guix}; otros ficheros en su sistema, como @file{/etc}, permanecen +intactos. + +Una vez instalado, Guix puede ser actualizado ejecutando @command{guix pull} +(@pxref{Invocación de guix pull}. + +Si prefiere realizar los pasos de instalación manualmente o desea +personalizarlos, puede encontrar útiles las siguientes +instrucciones. Describen los requisitos de software de Guix, así como su +instalación manual y la preparación para su uso. + +@menu +* Instalación binaria:: ¡Poner Guix en funcionamiento en nada de + tiempo! +* Requisitos:: Software necesario para construir y ejecutar + Guix. +* Ejecución de la batería de pruebas:: Probar Guix. +* Preparación del daemon:: Preparar el entorno del daemon de + construcción. +* Invocación de guix-daemon:: Ejecutar el daemon de construcción. +* Configuración de la aplicación:: Configuración específica de la + aplicación. +@end menu + +@node Instalación binaria +@section Instalación binaria + +@cindex instalar Guix desde binarios +@cindex guión del instalador +Esta sección describe cómo instalar Guix en un sistema arbitrario desde un +archivador autocontenido que proporciona los binarios para Guix y todas sus +dependencias. Esto es normalmente más rápido que una instalación desde las +fuentes, la cual es descrita en las siguientes secciones. El único requisito +es tener GNU@tie{}tar y Xz. + +La instalación consiste más o menos en los siguientes pasos: + +@enumerate +@item +@cindex descargar el binario de Guix +Descargue el archivador con los binarios de +@indicateurl{https://alpha.gnu.org/gnu/guix/guix-binary-@value{VERSION}.@var{sistema}.tar.xz}, +donde @var{sistema} es @code{x86_64-linux} para una máquina @code{x86_64} +que ejecute el núcleo Linux, etcétera. + +@c The following is somewhat duplicated in ``System Installation''. +Asegurese de descargar el fichero @file{.sig} asociado y de verificar la +autenticidad del archivador con él, más o menos así: + +@example +$ wget https://alpha.gnu.org/gnu/guix/guix-binary-@value{VERSION}.@var{sistema}.tar.xz.sig +$ gpg --verify guix-binary-@value{VERSION}.@var{sistema}.tar.xz.sig +@end example + +Si la orden falla porque no dispone de la clave pública necesaria, entonces +ejecute esta otra orden para importarla: + +@example +$ gpg --keyserver @value{KEY-SERVER} \ + --recv-keys @value{OPENPGP-SIGNING-KEY-ID} +@end example + +@noindent +@c end authentication part +y vuelva a ejecutar la orden @code{gpg --verify}. + +@item +Ahora necesita convertirse en la usuaria @code{root}. Dependiendo de su +distribución, puede que tenga que ejecutar @code{su -} o @code{sudo +-i}. Como @code{root}, ejecute: + +@example +# cd /tmp +# tar --warning=no-timestamp -xf \ + guix-binary-@value{VERSION}.@var{sistema}.tar.xz +# mv var/guix /var/ && mv gnu / +@end example + +Esto crea @file{/gnu/store} (@pxref{El almacén}) y @file{/var/guix}. El +último contiene un perfil listo para usar para @code{root} (vea el siguiente +paso). + +@emph{No} extraiga el archivador en un sistema Guix ya funcionando ya que +sobreescribiría sus propios ficheros esenciales. + +La opción @code{--warning=no-timestamp} asegura que GNU@tie{}tar no emite +avisos sobre ``marcas de tiempo imposibles'' (dichos avisos eran emitidos +por GNU@tie{}tar 1.26 y anteriores; las versiones recientes están +bien). Parten del hecho de que todos los ficheros en el archivador tienen su +tiempo de modificación fijado a cero (que significa el 1 de enero de +1970). Esto es hecho voluntariamente para asegurarse de que el contenido del +archivador es independiente de su fecha de creación, haciendolo por tanto +reproducible. + +@item +Ponga disponible el perfil en @file{~root/.config/guix/current}, que es +donde @command{guix pull} instalará las actualizaciones (@pxref{Invocación de guix pull}): + +@example +# mkdir -p ~root/.config/guix +# ln -sf /var/guix/profiles/per-user/root/current-guix \ + ~root/.config/guix/current +@end example + +Cargue @file{etc/profile} para aumentar @code{PATH} y otras variables de +entorno relevantes: + +@example +# GUIX_PROFILE="`echo ~root`/.config/guix/current" ; \ + source $GUIX_PROFILE/etc/profile +@end example + +@item +Cree el grupo y las cuentas de usuaria para las usuarias de construcción +como se explica a continuación (@pxref{Configuración del entorno de construcción}). + +@item +Ejecute el daemon, y configurelo para iniciarse automáticamente al arranque. + +Si su distribución anfitriona usa el sistema de inicio systemd, puede +conseguirlo con estas órdenes: + +@c Versions of systemd that supported symlinked service files are not +@c yet widely deployed, so we should suggest that users copy the service +@c files into place. +@c +@c See this thread for more information: +@c http://lists.gnu.org/archive/html/guix-devel/2017-01/msg01199.html + +@example +# cp ~root/.config/guix/current/lib/systemd/system/guix-daemon.service \ + /etc/systemd/system/ +# systemctl start guix-daemon && systemctl enable guix-daemon +@end example + +Si su distribución anfitriona usa el sistema de inicio Upstart: + +@example +# initctl reload-configuration +# cp ~root/.config/guix/current/lib/upstart/system/guix-daemon.conf \ + /etc/init/ +# start guix-daemon +@end example + +En otro caso, todavía puede iniciar el daemon manualmente con: + +@example +# ~root/.config/guix/current/bin/guix-daemon \ + --build-users-group=guixbuild +@end example + +@item +Haga accesible la orden @command{guix} a otras usuarias de la máquina, por +ejemplo con: + +@example +# mkdir -p /usr/local/bin +# cd /usr/local/bin +# ln -s /var/guix/profiles/per-user/root/current-guix/bin/guix +@end example + +Es también una buena idea poner disponible la versión Info de este manual +ahí: + +@example +# mkdir -p /usr/local/share/info +# cd /usr/local/share/info +# for i in /var/guix/profiles/per-user/root/current-guix/share/info/* ; + do ln -s $i ; done +@end example + +De este modo, asumiendo que @file{/usr/local/share/info} está en la ruta de +búsqueda, ejecutar @command{info guix.es} abrirá este manual (@pxref{Other +Info Directories,,, texinfo, GNU Texinfo}, para más detalles sobre cómo +cambiar la ruta de búsqueda de Info). + +@item +@cindex sustituciones, autorización de las mismas +Para usar sustituciones de @code{@value{SUBSTITUTE-SERVER}} o uno de sus +espejos (@pxref{Sustituciones}), debe autorizarlas: + +@example +# guix archive --authorize < \ + ~root/.config/guix/current/share/guix/@value{SUBSTITUTE-SERVER}.pub +@end example + +@item +Cada usuaria puede necesitar dar algunos pasos adicionales para prepar su +entorno de Guix para el uso, @pxref{Configuración de la aplicación}. +@end enumerate + +Voilà, ¡la instalación está completa! + +Puede confirmar que Guix está funcionando instalando un paquete de ejemplo +en su perfil de root: + +@example +# guix package -i hello +@end example + +El paquete @code{guix} debe permanecer disponible en el perfil de +@code{root}, o podría verse sujeto a la recolección de basura---en cuyo caso +se encontraría seriamente lastrada por la falta de la orden +@command{guix}. En otras palabras, no borre @code{guix} ejecutando +@code{guix package -r guix}. + +El archivador de la instalación binaria puede ser (re)producido y verificado +simplemente ejecutando la siguiente orden en el árbol de fuentes de Guix: + +@example +make guix-binary.@var{sistema}.tar.xz +@end example + +@noindent +...@: que a su vez ejecuta: + +@example +guix pack -s @var{sistema} --localstatedir \ + --profile-name=current-guix guix +@end example + +@xref{Invocación de guix pack}, para más información sobre esta útil herramienta. + +@node Requisitos +@section Requisitos + +Esta sección enumera los requisitos para construir Guix desde las +fuentes. El procedimiento de construcción de Guix es el mismo que el de otro +software GNU, y no está cubierto aquí. Por favor, eche un vistazo a los +ficheros @file{README} y @file{INSTALL} en el árbol de fuentes de Guix para +obtener detalles adicionales. + +@cindex página web oficial +GNU Guix está disponible para descarga desde su página web en +@url{http://www.gnu.org/software/guix/}. + +GNU Guix depende de los siguientes paquetes: + +@itemize +@item @url{http://gnu.org/software/guile/, GNU Guile}, versión 2.2.x; +@item @url{https://notabug.org/cwebber/guile-gcrypt, Guile-Gcrypt}, versión +0.1.0 o posterior; +@item +@uref{http://gnutls.org/, GnuTLS}, específicamente su API Guile +(@pxref{Guile Preparations, how to install the GnuTLS bindings for Guile,, +gnutls-guile, GnuTLS-Guile}); +@item +@uref{https://notabug.org/guile-sqlite3/guile-sqlite3, Guile-SQLite3}, +versión 0.1.0 o posterior; +@item +@c FIXME: Specify a version number once a release has been made. +@uref{https://gitlab.com/guile-git/guile-git, Guile-Git}, de agosto de 2017 +o posterior; +@item @uref{https://savannah.nongnu.org/projects/guile-json/, Guile-JSON}; +@item @url{http://zlib.net, zlib}; +@item @url{http://www.gnu.org/software/make/, GNU Make}. +@end itemize + +Las siguientes dependencias son opcionales: + +@itemize +@item +@c Note: We need at least 0.10.2 for 'channel-send-eof'. +Las características de delegación de construcciones (@pxref{Configuración de delegación del daemon}) y de @command{guix copy} (@pxref{Invocación de guix copy}) dependen de +@uref{https://github.com/artyom-poptsov/guile-ssh, Guile-SSH}, versión +0.10.2 o posterior. + +@item +Cuando @url{http://www.bzip.org, libbz2} está disponible, @command{guix +daemon} puede usarla para comprimir los log de construcción. +@end itemize + +A menos que se pasase @code{--disable-daemon} a @command{configure}, los +siguientes paquetes también son necesarios: + +@itemize +@item @url{http://gnupg.org/, GNU libgcrypt}; +@item @url{http://sqlite.org, SQLite 3}; +@item @url{http://gcc.gnu.org, g++ de GCC} con soporte para el +estándar C++11 +@end itemize + +@cindex directorio de estado +Cuando se configura Guix en un sistema que ya tiene una instalación de Guix, +asegurese de especificar el mismo directorio de estado que el de la +instalación existente usando la opción @code{--localstatedir} al guión +@command{configure} (@pxref{Directory Variables, @code{localstatedir},, +standards, GNU Coding Standards}). El guión @command{configure} le proteje +ante una mala configuración no deseada de @var{localstatedir} de modo que no +pueda corromper inadvertidamente su almacén (@pxref{El almacén}). + +@cindex Nix, compatibilidad +Cuando está disponible una instalación en funcionamiento del +@url{http://nixos.org/nix/, gestor de paquetes Nix}, puede a su vez +configurar Guix con @code{--disable-daemon}. En ese caso, Nix reemplaza las +tres dependencias anteriores. + +Guix es compatible con Nix, así que es posible compartir el mismo almacén +entre ambos. Para hacerlo debe pasar a @command{configure} no solo el mismo +valor de @code{--with-store-dir}, sino también el mismo valor de +@code{--localstatedir}. El último es esencial debido a que especifica la +base de datos donde se encuentran almacenados los metadatos del almacén, +entre otras cosas. Los valores predeterminados para Nix son +@code{--with-store-dir=/nix/store} y @code{--localstatedir=/nix/var}. Fíjese +que no se requiere @code{--disable-daemon} si su objetivo es compartir el +almacén con Nix. + +@node Ejecución de la batería de pruebas +@section Ejecución de la batería de pruebas + +@cindex batería de pruebas +Después de una ejecución exitosa de @command{configure} y @code{make}, es +una buena idea ejecutar la batería de pruebas. Puede ayudar a encontrar +problemas con la configuración o el entorno, o errores en el mismo Guix---e +informar de fallos en las pruebas es realmente una buena forma de ayudar a +mejorar el software. Para ejecutar la batería de pruebas, teclee: + +@example +make check +@end example + +Los casos de prueba pueden ejecutarse en paralelo: puede usar la opción +@code{-j} de GNU@tie{}make para acelerar las cosas. La primera ejecución +puede tomar algunos minutos en una máquina reciente; las siguientes +ejecuciones serán más rápidas puesto que el almacén creado para las pruebas +ya tendrá varias cosas en la caché. + +Tambien es posible ejecutar un subconjunto de las pruebas definiendo la +variable de makefile @code{TESTS} como en el ejemplo: + +@example +make check TESTS="tests/store.scm tests/cpio.scm" +@end example + +Por defecto, los resultados de las pruebas se muestran a nivel de +fichero. Para ver los detalles de cada caso de prueba individual, es posible +definir la variable de makefile @code{SCM_LOG_DRIVER_FLAGS} como en el +ejemplo: + +@example +make check TESTS="tests/base64.scm" SCM_LOG_DRIVER_FLAGS="--brief=no" +@end example + +En caso de fallo, le rogamos que envíe un correo a @email{bug-guix@@gnu.org} +y adjunte el fichero @file{test-suite.log}. Por favor, especifique la +versión de Guix usada así como los números de versión de las dependencias +(@pxref{Requisitos}) en su mensaje. + +Guix también viene como una batería de pruebas del sistema completo que +prueban instancias completas del sistema Guix. Se puede ejecutar únicamente +en sistemas donde Guix ya está instalado, usando: + +@example +make check-system +@end example + +@noindent +o, de nuevo, definiendo @code{TESTS} para seleccionar un subconjunto de las +pruebas a ejecutar: + +@example +make check-system TESTS="basic mcron" +@end example + +Estas pruebas de sistema están definidas en los módulos @code{(gnu tests +@dots{})}. Funcionan ejecutando el sistema operativo con una instrumentación +ligera en una máquina virtual (VM). Pueden ser computacionalmente intensivas +o bastante baratas, dependiendo de si hay sustituciones disponibles para sus +dependencias (@pxref{Sustituciones}). Algunas requieren mucho espacio de +almacenamiento para alojar las imágenes de la máquina virtual. + +De nuevo, en caso de fallos en las pruebas, le rogamos que envíe a +@email{bug-guix@@gnu.org} todos los detalles. + +@node Preparación del daemon +@section Preparación del daemon + +@cindex daemon +Operaciones como la construcción de un paquete o la ejecución del recolector +de basura son realizadas por un proceso especializado, el @dfn{daemon de +construcción}, en delegación de sus clientes. Únicamente el daemon puede +acceder al almacén y su base de datos asociada. Por tanto, cualquier +operación que manipula el almacén se realiza a través del daemon. Por +ejemplo, las herramientas de línea de órdenes como @command{guix package} y +@command{guix build} se comunican con el daemon (@i{via} llamadas a +procedimientos remotos) para indicarle qué hacer. + +Las siguientes secciones explican cómo preparar el entorno del daemon de +construcción. Véase tambien @ref{Sustituciones}, para información sobre cómo +permitir al daemon descargar binarios pre-construidos. + +@menu +* Configuración del entorno de construcción:: Preparar el entorno aislado + de construcción. +* Configuración de delegación del daemon:: Delegar construcciones a + máquinas remotas. +* Soporte de SELinux:: Uso de una política SELinux para el daemon. +@end menu + +@node Configuración del entorno de construcción +@subsection Configuración del entorno de construcción + +@cindex entorno de construcción +En una configuración multiusuaria estándar, Guix y su daemon---el programa +@command{guix-daemon}---son instalados por la administradora del sistema; +@file{/gnu/store} pertenece a @code{root} y @command{guix-daemon} se ejecuta +como @code{root}. Usuarias sin privilegios pueden usar las herramientas de +Guix para construir paquetes o acceder al almacén de otro modo, y el daemon +lo hará en delegación suya, asegurando que el almacén permanece en un estado +consistente, y permitiendo compartir entre usuarias los paquetes +construidos. + +@cindex usuarias de construcción +Mientras que @command{guix-daemon} se ejecuta como @code{root}, puede que no +desee que los procesos de construcción de paquetes se ejecuten como +@code{root} también, por razones de seguridad obvias. Para evitarlo, una +reserva especial de @dfn{usuarias de construcción} debe ser creada para ser +usada por los procesos de construcción iniciados por el daemon. Estas +usuarias de construcción no necesitan tener un shell ni un directorio home: +simplemente serán usadas cuando el daemon se deshaga de los privilegios de +@code{root} en los procesos de construcción. Tener varias de dichas usuarias +permite al daemon lanzar distintos procesos de construcción bajo UID +separados, lo que garantiza que no interferirán entre ellos---una +característica esencial ya que las construcciones se caracterizan como +funciones puras (@pxref{Introducción}). + +En un sistema GNU/Linux, una reserva de usuarias de construcción puede ser +creada así (usando la sintaxis de Bash y las órdenes de @code{shadow}): + +@c See http://lists.gnu.org/archive/html/bug-guix/2013-01/msg00239.html +@c for why `-G' is needed. +@example +# groupadd --system guixbuild +# for i in `seq -w 1 10`; + do + useradd -g guixbuild -G guixbuild \ + -d /var/empty -s `which nologin` \ + -c "Usuaria de construcción Guix $i" --system \ + guixbuilder$i; + done +@end example + +@noindent +El número de usuarias de construcción determina cuantos trabajos de +construcción se pueden ejecutar en paralelo, especificado por la opción +@option{--max-jobs} (@pxref{Invocación de guix-daemon, +@option{--max-jobs}}). Para usar @command{guix system vm} y las órdenes +relacionadas, puede necesitar añadir las usuarias de construcción al grupo +@code{kvm} para que puedan acceder a @file{/dev/kvm}, usando @code{-G +guixbuild,kvm} en vez de @code{-G guixbuild} (@pxref{Invocación de guix system}). + +El programa @code{guix-daemon} puede ser ejecutado entonces como @code{root} +con la siguiente orden@footnote{Si su máquina usa el sistema de inicio +systemd, copiando el fichero +@file{@var{prefix}/lib/systemd/system/guix-daemon.service} en +@file{/etc/systemd/system} asegurará que @command{guix-daemon} se arranca +automáticamente. De igual modo, si su máquina usa el sistema de inicio +Upstart, copie el fichero +@file{@var{prefix}/lib/upstart/system/guix-daemon.conf} en +@file{/etc/init}.}: + +@example +# guix-daemon --build-users-group=guixbuild +@end example + +@cindex chroot +@noindent +De este modo, el daemon inicia los procesos de construcción en un +``chroot'', bajo una de las usuarias @code{guixbuilder}. En GNU/Linux, por +defecto, el entorno ``chroot'' contiene únicamente: + +@c Keep this list in sync with libstore/build.cc! ----------------------- +@itemize +@item +un directorio @code{/dev} mínimo, creado en su mayor parte +independientemente del @code{/dev} del sistema anfitrión@footnote{``En su +mayor parte'', porque mientras el conjunto de ficheros que aparecen en +@code{/dev} es fijo, la mayor parte de estos ficheros solo pueden ser +creados si el sistema anfitrión los tiene.} + +@item +el directorio @code{/proc}; únicamente muestra los procesos del contenedor +ya que se usa un espacio de nombres de PID separado. + +@item +@file{/etc/passwd} con una entrada para la usuaria actual y una entrada para +la usuaria @file{nobody}; + +@item +@file{/etc/groups} con una entrada para el grupo de la usuaria; + +@item +@file{/etc/hosts} con una entrada que asocia @code{localhost} a +@code{127.0.0.1}; + +@item +un directorio @file{/tmp} con permisos de escritura. +@end itemize + +Puede influir en el directorio que el daemon utiliza para almacenar los +árboles de construcción @i{via} la variable de entorno @code{TMPDIR}. No +obstante, el árbol de construcción en el ``chroot'' siempre se llama +@file{/tmp/guix-build-@var{nombre}.drv-0}, donde @var{nombre} es el nombre +de la derivación---por ejemplo, @code{coreutils-8.24}. De este modo, el +valor de @code{TMPDIR} no se escapa a los entornos de construcción, lo que +evita discrepancias en caso de que los procesos de construcción capturen el +nombre de su árbol de construcción. + +@vindex http_proxy +El daemon también respeta la variable de entorno @code{http_proxy} para las +descargas HTTP que realiza, sea para derivaciones de salida fija +(@pxref{Derivaciones}) o para sustituciones (@pxref{Sustituciones}). + +Si está instalando Guix como una usuaria sin privilegios, es posible todavía +ejecutar @command{guix-daemon} siempre que pase @code{--disable-chroot}. No +obstante, los procesos de construcción no estarán aislados entre sí ni del +resto del sistema. Por tanto, los procesos de construcción pueden interferir +entre ellos y pueden acceder a programas, bibliotecas y otros ficheros +disponibles en el sistema---haciendo mucho más difícil verlos como funciones +@emph{puras}. + + +@node Configuración de delegación del daemon +@subsection Uso de la facilidad de descarga de trabajo + +@cindex delegando trabajo +@cindex hook de construcción +Cuando así se desee, el daemon de construcción puede @dfn{delegar} +construcciones de derivación a otras máquinas ejecutando Guix, usando el +@dfn{hook de construcción} @code{offload}@footnote{Esta característica está +únicamente disponible cuando +@uref{https://github.com/artyom-potsov/guile-ssh, Guile-SSH} está +presente.}. Cuando dicha característica es activada, una lista de máquinas +de construcción especificadas por la usuaria es leída de +@file{/etc/guix/machines.scm}; cada vez que se solicita una construcción, +por ejemplo via @code{guix build}, el daemon intenta delegarla a una de las +máquinas que satisfaga las condiciones de la derivación, en particular su +tipo de sistema---por ejemplo, @file{x86_64-linux}. Los prerrequisitos +restantes para la construcción son copiados por SSH a la máquina objetivo, +la cual procede con la construcción; con un resultado satisfactorio la(s) +salida(s) de la construcción son copiadas de vuelta a la máquina inicial. + +El fichero @file{/etc/guix/machines.scm} normalmente tiene un contenido de +este estilo: + +@example +(list (build-machine + (name "ochentayseis.example.org") + (system "x86_64-linux") + (host-key "ssh-ed25519 AAAAC3Nza@dots{}") + (user "rober") + (speed 2.)) ;¡increíblemente rápida! + + (build-machine + (name "mimips.example.org") + (system "mips64el-linux") + (host-key "ssh-rsa AAAAB3Nza@dots{}") + (user "alicia") + (private-key + (string-append (getenv "HOME") + "/.ssh/identidad-para-guix")))) +@end example + +@noindent +En el ejemplo anterior se especifica una lista de dos máquinas de +construcción, una para la arquitectura @code{x86_64} y otra para la +arquitectura @code{mips64el}. + +De hecho, este fichero es---¡sin sorpresa ninguna!---un fichero Scheme que +se evalúa cuando el hook @code{offload} se inicia. El valor que devuelve +debe ser una lista de objetos @code{build-machine}. Mientras que este +ejemplo muestra una lista fija de máquinas de construcción, una puede +imaginarse, digamos, el uso de DNS-SD para devolver una lista de máquinas de +construcción potenciales descubierta en la red local (@pxref{Introducción, +Guile-Avahi,, guile-avahi, Using Avahi in Guile Scheme Programs}). El tipo +de datos @code{build-machine} se detalla a continuación. + +@deftp {Tipo de datos} build-machine +Este tipo de datos representa las máquinas de construcción a las cuales el +daemon puede delegar construcciones. Los campos importantes son: + +@table @code + +@item name +El nombre de red de la máquina remota. + +@item system +El sistema de la máquina remota---por ejemplo, @code{"x86_64-linux"}. + +@item user +La cuenta de usuaria a usar cuando se conecte a la máquina remota por +SSH. Tenga en cuenta que el par de claves SSH @emph{no} debe estar protegido +por contraseña, para permitir ingresos al sistema no interactivos. + +@item host-key +Este campo debe contener la @dfn{clave pública de la máquina} de SSH en +formato OpenSSH. Es usado para autentificar la máquina cuando nos conectamos +a ella. Es una cadena larga más o menos así: + +@example +ssh-ed25519 AAAAC3NzaC@dots{}mde+UhL recordatorio@@example.org +@end example + +Si la máquina está ejecutando el daemon OpenSSH, @command{sshd}, la clave +pública de la máquina puede encontrarse en un fichero como +@file{/etc/ssh/ssh_host_ed25519_key.pub}. + +Si la máquina está ejecutando el daemon SSH GNU@tie{}lsh, @command{lshd}, la +clave de la máquina está en @file{/etc/lsh/host-key.pub} o un fichero +similar. Puede convertirse a formato OpenSSH usando @command{lsh-export-key} +(@pxref{Converting keys,,, lsh, LSH Manual}): + +@example +$ lsh-export-key --openssh < /etc/lsh/host-key.pub +ssh-rsa AAAAB3NzaC1yc2EAAAAEOp8FoQAAAQEAs1eB46LV@dots{} +@end example + +@end table + +Ciertos número de campos opcionales pueden ser especificados: + +@table @asis + +@item @code{port} (predeterminado: @code{22}) +Número de puerto del servidor SSH en la máquina. + +@item @code{private-key} (predeterminada: @file{~root/.ssh/id_rsa}) +El fichero de clave privada SSH usado para conectarse a la máquina, en +formato OpenSSH. Esta clave no debe estar protegida con una contraseña. + +Tenga en cuenta que el valor predeterminado es la clave privada @emph{de la +cuenta de root}. Asegurese de que existe si usa el valor predeterminado. + +@item @code{compression} (predeterminado: @code{"zlib@@openssh.com,zlib"}) +@itemx @code{compression-level} (predeterminado: @code{3}) +Los métodos de compresión y nivel de compresión a nivel SSH solicitados. + +Tenga en cuenta que la delegación de carga depende de la compresión SSH para +reducir el ancho de banda usado cuando se transfieren ficheros hacia y desde +máquinas de construcción. + +@item @code{daemon-socket} (predeterminado: @code{"/var/guix/daemon-socket/socket"}) +Nombre de fichero del socket de dominio Unix en el que @command{guix-daemon} +escucha en esa máquina. + +@item @code{parallel-builds} (predeterminadas: @code{1}) +El número de construcciones que pueden ejecutarse en paralelo en la máquina. + +@item @code{speed} (predeterminado: @code{1.0}) +Un ``factor de velocidad relativa''. El planificador de delegaciones tenderá +a preferir máquinas con un factor de velocidad mayor. + +@item @code{features} (predeterminadas: @code{'()}) +Una lista de cadenas denotando las características específicas permitidas +por la máquina. Un ejemplo es @code{"kvm"} para máquinas que tienen los +módulos KVM de Linux y las correspondientes características hardware. Las +derivaciones pueden solicitar las características por nombre, y entonces se +planificarán en las máquinas adecuadas. + +@end table +@end deftp + +El ejecutable @code{guix} debe estar en la ruta de búsqueda de las máquinas +de construcción. Puede comprobar si es el caso ejecutando: + +@example +ssh build-machine guix repl --version +@end example + +Hay una última cosa por hacer una vez @file{machines.scm} está en su +lugar. Como se ha explicado anteriormente, cuando se delega, los ficheros se +transfieren en ambas direcciones entre los almacenes de las máquinas. Para +que esto funcione, primero debe generar un par de claves en cada máquina +para permitir al daemon exportar los archivos firmados de ficheros en el +almacén (@pxref{Invocación de guix archive}): + +@example +# guix archive --generate-key +@end example + +@noindent +Cada máquina de construcción debe autorizar a la clave de la máquina maestra +para que acepte elementos del almacén que reciba de la maestra: + +@example +# guix archive --authorize < clave-publica-maestra.txt +@end example + +@noindent +Del mismo podo, la máquina maestra debe autorizar la clave de cada máquina +de construcción. + +Todo este lío con claves está ahí para expresar las mutuas relaciones de +confianza entre pares de la máquina maestra y las máquinas de +construcción. Concretamente, cuando la maestra recibe ficheros de una +máquina de construcción (y @i{vice versa}), su daemon de construcción puede +asegurarse de que son genuinos, no han sido modificados, y que están +firmados por una clave autorizada. + +@cindex prueba de delegación +Para comprobar si su configuración es operacional, ejecute esta orden en el +nodo maestro: + +@example +# guix offload test +@end example + +Esto intentará conectar con cada una de las máquinas de construcción +especificadas en @file{/etc/guix/machines.scm}, comprobará que GUile y los +módulos Guix están disponibles en cada máquina, intentará exportar a la +máquina e importar de ella, e informará de cualquier error en el proceso. + +Si quiere probar un fichero de máquinas diferente, simplemente especifiquelo +en la línea de órdenes: + +@example +# guix offload test otras-maquinas.scm +@end example + +Por último, puede probar un subconjunto de máquinas cuyos nombres coincidan +con una expresión regular así: + +@example +# guix offload test maquinas.scm '\.gnu\.org$' +@end example + +@cindex estado de delegación +Para mostrar la carga actual de todas las máquinas de construcción, ejecute +esta orden en el nodo principal: + +@example +# guix offload status +@end example + + +@node Soporte de SELinux +@subsection Soporte de SELinux + +@cindex SELinux, política del daemon +@cindex control de acceso mandatorio, SELinux +@cindex seguridad, guix-daemon +Guix incluye un fichero de política SELinux en @file{etc/guix-daemon.cil} +que puede ser instalado en un sistema donde SELinux está activado, para +etiquetar los ficheros Guix y especificar el comportamiento esperado del +daemon. Ya que el sistema Guix no proporciona una política base de SELinux, +la política del daemon no puede usarse en el sistema Guix. + +@subsubsection Instalación de la política de SELinux +@cindex SELinux, instalación de la política +Para instalar la política ejecute esta orden como root: + +@example +semodule -i etc/guix-daemon.cil +@end example + +Una vez hecho, vuelva a etiquetar el sistema de ficheros con +@code{restorecon} o con un mecanismo distinto que proporcione su sistema. + +Una vez la política está instalada, el sistema de ficheros ha sido +re-etiquetado, y el daemon ha sido reiniciado, debería ejecutarse en el +contexto @code{guix_daemon_t}. Puede confirmarlo con la siguiente orden: + +@example +ps -Zax | grep guix-daemon +@end example + +Monitorice los ficheros de log de SELinux mientras ejecuta una orden como +@code{guix build hello} para convencerse que SELinux permite todas las +operaciones necesarias. + +@subsubsection Limitaciones +@cindex SELinux, limitaciones + +Esta política no es perfecta. Aquí está una lista de limitaciones o +comportamientos extraños que deben ser considerados al desplegar la política +SELinux provista para el daemon Guix. + +@enumerate +@item +@code{guix_daemon_socket_t} no se usa realmente. Ninguna de las operaciones +del socket implica contextos que tengan algo que ver con +@code{guix_daemon_socket_t}. No hace daño tener esta etiqueta sin usar, pero +sería preferible definir reglas del socket únicamente para esta etiqueta. + +@item +@code{guix gc} no puede acceder enlaces arbitrarios a los perfiles. Por +diseño, la etiqueta del fichero del destino de un enlace simbólico es +independiente de la etiqueta de fichero del fichero en sí. Aunque todos los +perfiles bajo $localstatedir se etiquetan, los enlaces para estos perfiles +heredan la etiqueta del directorio en el que están. Para enlaces en el +directorio de la usuaria esto será @code{user_home_t}. Pero para los enlaces +del directorio de root, o @file{/tmp}, o del directorio del servidor HTTP, +etc., esto no funcionará. @code{guix gc} se verá incapacitado para leer y +seguir dichos enlaces. + +@item +La característica del daemon de esperar conexiones TCP puede que no funcione +más. Esto puede requerir reglas extra, ya que SELinux trata los sockets de +red de forma diferente a los ficheros. + +@item +Actualmente todos los ficheros con un nombre coincidente con la expresión +regular @code{/gnu/store.+-(gux-.+|profile)/bin/guix-daemon} tienen asignada +la etiqueta @code{guix_daemon_exec_t}; esto significa que @emph{cualquier} +fichero con ese nombre en cualquier perfil tendrá permitida la ejecución en +el dominio @code{guix_daemon_t}. Esto no es ideal. Una atacante podría +construir un paquete que proporcione este ejecutable y convencer a la +usuaria para instalarlo y ejecutarlo, lo que lo eleva al dominio +@code{guix_daemon_t}. Llegadas a este punto, SELinux no puede prevenir que +acceda a los ficheros permitidos para los procesos en dicho dominio. + +Podríamos generar una política mucho más restrictiva en tiempo de +instalación, de modo que solo el nombre @emph{exacto} del fichero del +ejecutable de @code{guix-daemon} actualmente instalado sea marcado como +@code{guix_daemon_exec_t}, en vez de usar una expresión regular amplia. La +desventaja es que root tendría que instalar o actualizar la política en +tiempo de instalación cada vez que se actualizase el paquete de Guix que +proporcione el ejecutable de @code{guix-daemon} realmente en ejecución. +@end enumerate + +@node Invocación de guix-daemon +@section Invocación de @command{guix-daemon} + +El programa @command{guix-daemon} implementa toda la funcionalidad para +acceder al almacén. Esto incluye iniciar procesos de construcción, ejecutar +el recolector de basura, comprobar la disponibilidad de un resultado de +construcción, etc. Normalmente se ejecuta como @code{root} así: + +@example +# guix-daemon --build-users-group=guixbuild +@end example + +@noindent +Para detalles obre como configurarlo, @pxref{Preparación del daemon}. + +@cindex chroot +@cindex contenedor, entorno de construcción +@cindex entorno de construcción +@cindex construcciones reproducibles +Por defecto, @command{guix-daemon} inicia los procesos de construcción bajo +distintos UIDs, tomados del grupo de construcción especificado con +@code{--build-users-group}. Además, cada proceso de construcción se ejecuta +en un entorno ``chroot'' que únicamente contiene el subconjunto del almacén +del que depende el proceso de construcción, como especifica su derivación +(@pxref{Interfaz programática, derivación}), más un conjunto específico de +directorios del sistema. Por defecto, estos directorios contienen +@file{/dev} y @file{/dev/pts}. Es más, sobre GNU/Linux, el entorno de +construcción es un @dfn{contenedor}: además de tener su propio árbol del +sistema de ficheros, tiene un espacio de nombres de montado separado, su +propio espacio de nombres de PID, de red, etc. Esto ayuda a obtener +construcciones reproducibles (@pxref{Características}). + +Cuando el daemon realiza una construcción en delegación de la usuaria, crea +un directorio de construcción bajo @file{/tmp} o bajo el directorio +especificado por su variable de entorno @code{TMPDIR}. Este directorio se +comparte con el contenedor durante toda la construcción, aunque dentro del +contenedor el árbol de construcción siempre se llama +@file{/tmp/guix-build-@var{nombre}.drv-0}. + +El directorio de construcción se borra automáticamente una vez completado el +proceso, a menos que la construcción fallase y se especificase en el cliente +@option{--keep-failed} (@pxref{Invocación de guix build, +@option{--keep-failed}}). + +El daemon espera conexiones y lanza un subproceso por sesión iniciada por +cada cliente (una de las sub-órdenes de @command{guix}). La orden +@command{guix processes} le permite tener una visión general de la actividad +de su sistema mostrando clientes y sesiones activas. @xref{Invocación de guix processes}, para más información. + +Se aceptan las siguientes opciones de línea de ordenes: + +@table @code +@item --build-users-group=@var{grupo} +Toma las usuarias de @var{grupo} para ejecutar los procesos de construcción +(@pxref{Preparación del daemon, build users}). + +@item --no-substitutes +@cindex sustituciones +No usa sustituciones para la construcción de productos. Esto es, siempre +realiza las construcciones localmente en vez de permitir la descarga de +binarios pre-construidos (@pxref{Sustituciones}). + +Cuando el daemon se ejecuta con @code{--no-substitutes}, los clientes aún +pueden activar explícitamente las sustituciones @i{via} la llamada de +procedimiento remoto @code{set-build-options} (@pxref{El almacén}). + +@item --substitute-urls=@var{urls} +@anchor{daemon-substitute-urls} +Considera @var{urls} la lista separada por espacios predeterminada de URLs +de sustituciones de fuentes. Cuando se omite esta opción, se usa +@indicateurl{https://@value{SUBSTITUTE-SERVER}}. + +Esto significa que las sustituciones puede ser descargadas de @var{urls}, +mientras estén firmadas por una firma de confianza (@pxref{Sustituciones}). + +@cindex hook de construcción +@item --no-build-hook +No usa el @dfn{hook de construcción}. + +El hook de construcción es un programa auxiliar que el daemon puede lanzar y +al cual envía las peticiones de construcción. Este mecanismo se utiliza para +delegar construcciones a otras máquinas (@pxref{Configuración de delegación del daemon}). + +@item --cache-failures +Almacena en la caché los fallos de construcción. Por defecto, únicamente las +construcciones satisfactorias son almacenadas en la caché. + +Cuando se usa esta opción, @command{guix gc --list-failures} puede usarse +para consultar el conjunto de elementos del almacén marcados como fallidos; +@command{guix gc --clear-failures} borra los elementos del almacén del +conjunto de fallos existentes en la caché. @xref{Invocación de guix gc}. + +@item --cores=@var{n} +@itemx -c @var{n} +Usa @var{n} núcleos de la CPU para construir cada derivación; @code{0} +significa tantos como haya disponibles. + +El valor predeterminado es @code{0}, pero puede ser sobreescrito por los +clientes, como la opción @code{--cores} de @command{guix build} +(@pxref{Invocación de guix build}). + +El efecto es definir la variable de entorno @code{NIX_BUILD_CORES} en el +proceso de construcción, el cual puede usarla para explotar el paralelismo +interno---por ejemplo, ejecutando @code{make -j$NIX_BUILD_CORES}. + +@item --max-jobs=@var{n} +@itemx -M @var{n} +Permite como máximo @var{n} trabajos de construcción en paralelo. El valor +predeterminado es @code{1}. Fijarlo a @code{0} significa que ninguna +construcción se realizará localmente; en vez de eso, el daemon delegará las +construcciones (@pxref{Configuración de delegación del daemon}), o simplemente fallará. + +@item --max-silent-time=@var{segundos} +Cuando la construcción o sustitución permanece en silencio más de +@var{segundos}, la finaliza e informa de un fallo de construcción. + +El valor predeterminado es @code{0}, que deshabilita el plazo. + +El valor especificado aquí puede ser sobreescrito por clientes +(@pxref{Opciones comunes de construcción, @code{--max-silent-time}}). + +@item --timeout=@var{segundos} +Del mismo modo, cuando el proceso de construcción o sustitución dura más de +@var{segundos}, lo termina e informa un fallo de construcción. + +El valor predeterminado es @code{0}, que deshabilita el plazo. + +El valor especificado aquí puede ser sobreescrito por los clientes +(@pxref{Opciones comunes de construcción, @code{--timeout}}). + +@item --rounds=@var{N} +Construye cada derivación @var{n} veces seguidas, y lanza un error si los +resultados de las construcciones consecutivas no son idénticos +bit-a-bit. Fíjese que esta configuración puede ser sobreescrita por clientes +como @command{guix build} (@pxref{Invocación de guix build}). + +Cuando se usa conjuntamente con @option{--keep-failed}, la salida que +difiere se mantiene en el almacén, bajo +@file{/gnu/store/@dots{}-check}. Esto hace fácil buscar diferencias entre +los dos resultados. + +@item --debug +Produce salida de depuración. + +Esto es útil para depurar problemas en el arranque del daemon, pero entonces +puede ser cambiado el comportamiento por los clientes, por ejemplo la opción +@code{--verbosity} de @command{guix build} (@pxref{Invocación de guix build}). + +@item --chroot-directory=@var{dir} +Añade @var{dir} al chroot de construcción. + +Hacer esto puede cambiar el resultado del proceso de construcción---por +ejemplo si usa dependencias opcionales, que se encuentren en @var{dir}, +cuando están disponibles, y no de otra forma. Por esa razón, no se +recomienda hacerlo. En vez de eso, asegurese que cada derivación declara +todas las entradas que necesita. + +@item --disable-chroot +Deshabilita las construcciones en un chroot. + +No se recomienda el uso de esta opción ya que, de nuevo, podría permitir a +los procesos de construcción ganar acceso a dependencias no declaradas. Es +necesario, no obstante, cuando @command{guix-daemon} se ejecuta bajo una +cuenta de usuaria sin privilegios. + +@item --log-compression=@var{tipo} +Comprime los logs de construcción de acuerdo a @var{tipo}, que puede ser +@code{gzip}, @code{bzip2} o @code{none}. + +A menos que se use @code{--lose-logs}, todos los log de construcción se +mantienen en @var{localstatedir}. Para ahorrar espacio, el daemon +automáticamente los comprime con bzip2 por defecto. + +@item --disable-deduplication +@cindex deduplicación +Deshabilita la ``deduplicación'' automática en el almacén. + +Por defecto, los ficheros se añaden al almacén ``deduplicados'' +automáticamente: si un nuevo fichero añadido es idéntico a otro que ya se +encuentra en el almacén, el daemon introduce el nuevo fichero como un enlace +duro al otro fichero. Esto puede reducir notablemente el uso del disco, a +expensas de una carga de entrada/salida ligeramente incrementada al +finalizar un proceso de construcción. Esta opción deshabilita esta +optimización. + +@item --gc-keep-outputs[=yes|no] +Determina si el recolector de basura (GC) debe mantener salidas de las +derivaciones vias. + +@cindex GC, raíces del recolector de basura +@cindex raíces del recolector de basura +Cuando se usa ``yes'', el recolector de basura mantendrá las salidas de +cualquier derivación viva disponible en el almacén---los ficheros +@code{.drv}. El valor predeterminado es ``no'', lo que significa que las +salidas de las derivaciones se mantienen únicamente si son alcanzables desde +alguna raíz del recolector de basura. @xref{Invocación de guix gc}, para más +información sobre las raices del recolector de basura. + +@item --gc-keep-derivations[=yes|no] +Determina si el recolector de basura (GC) debe mantener derivaciones +correspondientes a salidas vivas. + +Cuando se usa ``yes'', como es el caso predeterminado, el recolector de +basura mantiene derivaciones---es decir, ficheros @code{.drv}---mientras al +menos una de sus salidas está viva. Esto permite a las usuarias seguir la +pista de los orígenes de los elementos en el almacén. El uso de ``no'' aquí +ahorra un poco de espacio en disco. + +De este modo, usar @code{--gc-keep-derivations} con valor ``yes'' provoca +que la vitalidad fluya de salidas a derivaciones, y usar +@code{--gc-keep-outputs} con valor ``yes'' provoca que la vitalidad fluya de +derivaciones a salidas. Cuando ambas tienen valor ``yes'', el efecto es +mantener todos los prerrequisitos de construcción (las fuentes, el +compilador, las bibliotecas y otras herramientas de tiempo de construcción) +de los objetos vivos del almacén, independientemente de que esos +prerrequisitos sean alcanzables desde una raíz del recolector de +basura. Esto es conveniente para desarrolladoras ya que ahorra +reconstrucciones o descargas. + +@item --impersonate-linux-2.6 +En sistemas basados en Linux, suplanta a Linux 2.6. Esto significa que la +llamada del sistema @code{uname} del kernel indicará 2.6 como el número de +publicación. + +Esto puede ser útil para construir programas que (habitualmente de forma +incorrecta) dependen en el número de versión del núcleo. + +@item --lose-logs +No guarda logs de construcción. Por defecto se almacenan bajo +@code{@var{localstatedir}/guix/log}. + +@item --system=@var{sistema} +Asume @var{sistema} como el tipo actual de sistema. Por defecto es el par de +arquitectura/núcleo encontrado durante la configuración, como +@code{x86_64-linux}. + +@item --listen=@var{destino} +Escucha conexiones en @var{destino}. @var{destino} se interpreta como el +nombre del fichero del socket de dominio Unix si comienza on @code{/} (barra +a la derecha). En otro caso, @var{destino} se interpreta como un nombre de +máquina o un nombre de máquina y puerto a escuchar. Aquí van unos pocos +ejemplos: + +@table @code +@item --listen=/gnu/var/daemon +Escucha por conexiones en el socket de dominio Unix @file{/gnu/var/daemon}, +creandolo si es necesario. + +@item --listen=localhost +@cindex daemon, acceso remoto +@cindex acceso remoto al daemon +@cindex daemon, configuración en cluster +@cindex daemon, configuración en cluster +Escucha conexiones TCP en la interfaz de red correspondiente a +@code{localhost}, en el puerto 44146. + +@item --listen=128.0.0.42:1234 +Escucha conexiones TCP en la interfaz de red correspondiente a +@code{128.0.0.42}, en el puerto 1234. +@end table + +Esta opción puede repetirse múltiples veces, en cuyo caso +@command{guix-daemon} acepta conexiones en todos los destinos +especificados. Las usuarias pueden indicar a los clientes a qué destino +conectarse fijando la variable de entorno @code{GUIX_DAEMON_SOCKET} +(@pxref{El almacén, @code{GUIX_DAEMON_SOCKET}}). + +@quotation Nota +El protocolo del daemon @code{no está autentificado ni cifrado}. El uso de +@code{--listen=@var{dirección}} es aceptable en redes locales, como +clusters, donde únicamente los nodos de confianza pueden conectarse al +daemon de construcción. En otros casos donde el acceso remoto al daemon es +necesario, recomendamos usar sockets de dominio Unix junto a SSH. +@end quotation + +Cuando se omite @code{--listen}, @command{guix-daemon} escucha conexiones en +el socket de dominio Unix que se encuentra en +@file{@var{localstatedir}/guix/daemon-socket/socket}. +@end table + + +@node Configuración de la aplicación +@section Configuración de la aplicación + +@cindex distribución distinta +Cuando se usa Guix sobre una distribución GNU/Linux distinta al sistema +Guix---una @dfn{distribución distinta}---unos pocos pasos adicionales son +necesarios para tener todo preparado. Aquí están algunos de ellos. + +@subsection Localizaciones + +@anchor{locales-and-locpath} +@cindex localizaciones, cuando no se está en el sistema Guix +@vindex LOCPATH +@vindex GUIX_LOCPATH +Los paquetes instalados @i{via} Guix no usarán los datos de localización del +sistema anfitrión. En vez de eso, debe primero instalar uno de los paquetes +de localización disponibles con Guix y después definir la variable de +entorno @code{GUIX_LOCPATH}: + +@example +$ guix package -i glibc-locales +$ export GUIX_LOCPATH=$HOME/.guix-profile/lib/locale +@end example + +Fíjese que el paquete @code{glibc-locales} contiene datos para todas las +localizaciones que ofrece GNU@tie{}libc y pesa alrededor de +110@tie{}MiB. Alternativamente, @code{glibc-utf8-locales} es más pequeño +pero limitado a localizaciones UTF-8. + +La variable @code{GUIX_LOCPATH} juega un rol similar a @code{LOCPATH} +(@pxref{Locale Names, @code{LOCPATH},, libc, The GNU C Library Reference +Manual}). No obstante, hay dos diferencias importantes: + +@enumerate +@item +@code{GUIX_LOCPATH} es respetada únicamente por la libc dentro de Guix, y no +por la libc que proporcionan las distribuciones distintas. Por tanto, usar +@code{GUIX_LOCPATH} le permite asegurarse de que los programas de la +distribución distinta no cargarán datos de localización incompatibles. + +@item +libc añade un sufijo a cada entrada de @code{GUIX_LOCPATH} con @code{/X.Y}, +donde @code{X.Y} es la versión de libc---por ejemplo, @code{2.22}. Esto +significa que, en caso que su perfil Guix contenga una mezcla de programas +enlazados contra diferentes versiones de libc, cada versión de libc +únicamente intentará cargar datos de localización en el formato correcto. +@end enumerate + +Esto es importante porque el formato de datos de localización usado por +diferentes versiones de libc puede ser incompatible. + +@subsection Selector de servicios de nombres + +@cindex selector de servicios de nombres, glibc +@cindex NSS (selector de servicios de nombres), glibc +@cindex ncsd (daemon de caché del servicio de nombres) +@cindex daemon de caché del servicio de nombres (ncsd) +Cuando se usa Guix en una distribución distinta, @emph{recomendamos +encarecidamente} que el sistema ejecute el @dfn{daemon de caché del servicio +de nombres} de la biblioteca de C de GNU, @command{ncsd}, que debe escuchar +en el socket @file{/var/run/nscd/socket}. En caso de no hacerlo, las +aplicaciones instaladas con Guix pueden fallar al buscar nombres de máquinas +o cuentas de usuaria, o incluso pueden terminar abruptamente. Los siguientes +párrafos explican por qué. + +@cindex @file{nsswitch.conf} +La biblioteca de C de GNU implementa un @dfn{selector de servicios de +nombres} (NSS), que es un mecanismo extensible para ``búsquedas de nombres'' +en general: resolución de nombres de máquinas, cuentas de usuaria y más +(@pxref{Selector de servicios de nombres,,, libc, The GNU C Library Reference Manual}). + +@cindex Servicio de información de red (NIS) +@cindex NIS (servicio de información de red) +Al ser extensible, NSS permite el uso de @dfn{módulos}, los cuales +proporcionan nuevas implementaciones de búsqueda de nombres: por ejemplo, el +módulo @code{nss-mdns} permite la resolución de nombres de máquina +@code{.local}, el módulo @code{nis} permite la búsqueda de cuentas de +usuaria usando el servicio de información de red (NIS), etc. Estos +``servicios de búsqueda'' extra se configuran para todo el sistema en +@file{/etc/nsswitch.conf}, y todos los programas en ejecución respetan esta +configuración (@pxref{NSS Configuration File,,, libc, The GNU C Reference +Manual}). + +Cuando se realiza una búsqueda de nombres---por ejemplo, llamando a la +función @code{getaddrinfo} en C---las aplicaciones primero intentarán +conectar con nscd; en caso satisfactorio, nscd realiza la búsqueda de +nombres en delegación suya. Si nscd no está ejecutándose, entonces realizan +la búsqueda por ellas mismas, cargando los servicios de búsqueda de nombres +en su propio espacio de direcciones y ejecutándola. Estos servicios de +búsqueda de nombres---los ficheros @file{libnss_*.so}---son abiertos con +@code{dlopen}, pero pueden venir de la biblioteca de C del sistema, en vez +de la biblioteca de C contra la que la aplicación está enlazada (la +biblioteca de C que viene en Guix). + +Y aquí es donde está el problema: si su aplicación está enlazada contra la +biblioteca de C de Guix (digamos, glibc 2.24) e intenta cargar módulos de +otra biblioteca de C (digamos, @code{libnss_mdns.so} para glibc 2.22), +probablemente terminará abruptamente o sus búsquedas de nombres fallarán +inesperadamente. + +Ejecutar @command{nscd} en el sistema, entre otras ventajas, elimina este +problema de incompatibilidad binaria porque esos ficheros @code{libnss_*.so} +se cargan en el proceso @command{nscd}, no en la aplicación misma. + +@subsection Tipografías X11 + +@cindex tipografías +La mayoría de aplicaciones gráficas usan Fontconfig para encontrar y cargar +tipografías y realizar la renderización del lado del cliente X11. El paquete +@code{fontconfig} en Guix busca tipografías en @file{$HOME/.guix-profile} +por defecto. Por tanto, para permitir a aplicaciones gráficas instaladas con +Guix mostrar tipografías, tiene que instalar las tipografías también con +Guix. Paquetes esenciales de tipografías incluyen @code{gs-fonts}, +@code{font-dejavu} y @code{font-gnu-freefont-ttf}. + +Para mostrar texto escrito en lenguas chinas, Japonés o Coreano en +aplicaciones gráficas, considere instalar @code{font-adobe-source-han-sans} +o @code{font-wqy-zenhei}. La anterior tiene múltiples salidas, una por +familia de lengua (@pxref{Paquetes con múltiples salidas}). Por ejemplo, la +siguiente orden instala tipografías para lenguas chinas: + +@example +guix package -i font-adobe-source-han-sans:cn +@end example + +@cindex @code{xterm} +Programas más antiguos como @command{xterm} no usan Fontconfig sino que +dependen en el lado del servidor para realizar el renderizado de +tipografías. Dichos programas requieren especificar un nombre completo de +tipografía usando XLFD (Descripción lógica de tipografías X), como esta: + +@example +-*-dejavu sans-medium-r-normal-*-*-100-*-*-*-*-*-1 +@end example + +Para ser capaz de usar estos nombres completos para las tipografías TrueType +instaladas en su perfil Guix, necesita extender la ruta de fuentes del +servidor X: + +@c Note: 'xset' does not accept symlinks so the trick below arranges to +@c get at the real directory. See <https://bugs.gnu.org/30655>. +@example +xset +fp $(dirname $(readlink -f ~/.guix-profile/share/fonts/truetype/fonts.dir)) +@end example + +@cindex @code{xlsfonts} +Después de eso, puede ejecutar @code{xlsfonts} (del paquete @code{xlsfonts}) +para asegurarse que sus tipografías TrueType se enumeran aquí. + +@cindex @code{fc-cache} +@cindex caché de tipografías +Después de instalar tipografías puede tener que refrescar la caché de +tipografías para usarlas en las aplicaciones. Lo mismo aplica cuando las +aplicaciones instaladas vía Guix no parecen encontrar tipografías. Para +forzar la reconstrucción de la caché de tipografías ejecute @code{fc-cache +-f}. La orden @code{fc-cache} es proporcionada por el paquete +@code{fontconfig}. + +@subsection Certificados X.509 + +@cindex @code{nss-certs} +El paquete @code{nss-certs} proporciona certificados X.509, que permiten a +los programas verificar los servidores accedidos por HTTPS. + +Cuando se usa Guix en una distribución distinta, puede instalar este paquete +y definir las variables de entorno relevantes de modo que los paquetes sepan +dónde buscar los certificados. @xref{Certificados X.509}, para información +detallada. + +@subsection Paquetes Emacs + +@cindex @code{emacs} +Cuando instala paquetes Emacs con Guix, los ficheros elisp pueden estar +tanto en @file{$HOME/.guix-profile/share/emacs/site-lisp/} o en +subdirectorios de +@file{$HOME/.guix-profile/share/emacs/site-lisp/guix.d/}. El último +directorio existe porque potencialmente pueden existir miles de paquetes +Emacs, y almacenar todos sus ficheros en un directorio único puede no ser +confiable (por conflictos de nombres). Por lo que pensamos que usar un +directorio separado por cada paquete es una buena idea. Es muy similar a +cómo el sistema de paquetes de Emacs organiza la estructura de ficheros +(@pxref{Package Files,,, emacs, The GNU Emacs Manual}). + +Por defecto, Emacs (el instalado con Guix) ``sabe'' donde se alojan estos +paquetes, para que usted no tenga que realizar ninguna configuración. Si, +por alguna razón, desea evitar la carga automática de paquetes Emacs +instalados con Guix, puede hacerlo ejecutando Emacs con la opción +@code{--no-site-file} (@pxref{Init File,,, emacs, The GNU Emacs Manual}). + +@subsection La cadena de herramientas de GCC + +@cindex GCC +@cindex ld-wrapper + +Guix ofrece paquetes de compiladores individuales como @code{gcc}, pero si +necesita una cadena de herramientas completa para compilar y enlazar código +fuente lo que realmente desea es el paquete @code{gcc-toolchain}. Este +paquete proporciona una cadena de herramientas GCC para desarrollo C/C++, +incluyendo el mismo GCC, la biblioteca de C GNU (cabeceras y binarios, más +símbolos de desarrollo en la salida @code{debug}), Binutils y un +recubrimiento del enlazador. + +El propósito del recubrimiento es inspeccionar las opciones @code{-L} y +@code{-l} proporcionadas al enlazador, y los correspondientes parámetros +@code{-rpath}, y llamar al enlazador real con este nuevo conjunto de +parámetros. Puede instruir al recubrimiento para rechazar el enlace contra +bibliotecas que no se encuentren en el almacén fijando el valor de la +variable de entorno @code{GUIX_LD_WRAPPER_ALLOW_IMPURITIES} a @code{no}. + +@c TODO What else? + +@c ********************************************************************* +@node Instalación del sistema +@chapter Instalación del sistema + +@cindex instalación del sistema Guix +@cindex sistema Guix, instalación +Esta sección explica cómo instalar el sistema Guix en una máquina. Guix, +como gestor de paquetes, puede instalarse sobre un sistema GNU/Linux en +ejecución, @pxref{Instalación}. + +@ifinfo +@quotation Nota +@c This paragraph is for people reading this from tty2 of the +@c installation image. +Está leyendo esta documentación con un lector Info. Para obtener detalles +sobre su uso, presione la tecla @key{RET} (``retorno de carro'' o ``intro'') +en el siguiente enlace: @pxref{Top, Info reader,, info-stnd, Stand-alone GNU +Info}. Presione después @kbd{l} para volver aquí. + +De manera alternativa, ejecute @command{info info} en otro terminal para +mantener el manual disponible. +@end quotation +@end ifinfo + +@menu +* Limitaciones:: Qué puede esperar. +* Consideraciones sobre el hardware:: Hardware soportado. +* Instalación desde memoria USB y DVD:: Preparar el medio de instalación. +* Preparación para la instalación:: Red, particionado, etc. +* Instalación gráfica guiada:: Instalación gráfica fácil. +* Instalación manual:: Instalación manual para artistas del teclado. +* Tras la instalación del sistema:: Cuando la instalación ha finalizado + satisfactoriamente. +* Instalación de Guix en una máquina virtual:: El patio de recreo del + sistema Guix. +* Construcción de la imagen de instalación:: Cómo esto llega a ser. +@end menu + +@node Limitaciones +@section Limitaciones + +We consider Guix System to be ready for a wide range of ``desktop'' and +server use cases. The reliability guarantees it provides---transactional +upgrades and rollbacks, reproducibility---make it a solid foundation. + +Nevertheless, before you proceed with the installation, be aware of the +following noteworthy limitations applicable to version @value{VERSION}: + +@itemize +@item +No está implementada la funcionalidad del gestor de volúmenes lógicos (LVM). + +@item +Se proporcionan más y más servicios del sistema (@pxref{Servicios}), pero +pueden faltar algunos. + +@item +GNOME, Xfce, LXDE, and Enlightenment are available (@pxref{Servicios de escritorio}), as well as a number of X11 window managers. However, KDE is +currently missing. +@end itemize + +More than a disclaimer, this is an invitation to report issues (and success +stories!), and to join us in improving it. @xref{Contribuir}, for more +info. + + +@node Consideraciones sobre el hardware +@section Consideraciones sobre el hardware + +@cindex soporte de hardware en el sistema Guix +GNU@tie{}Guix se enfoca en respetar la libertad de computación de las +usuarias. Se construye sobre el núcleo Linux-libre, lo que significa que +únicamente funciona hardware para el que existen controladores y firmware +libres. Hoy en día, un amplio rango del hardware común funciona con +GNU/Linux-libre---desde teclados a tarjetas gráficas a escáneres y +controladoras Ethernet. Desafortunadamente, todavía hay áreas donde los +fabricantes de hardware deniegan a las usuarias el control de su propia +computación, y dicho hardware no funciona en el sistema Guix. + +@cindex WiFi, soporte hardware +One of the main areas where free drivers or firmware are lacking is WiFi +devices. WiFi devices known to work include those using Atheros chips +(AR9271 and AR7010), which corresponds to the @code{ath9k} Linux-libre +driver, and those using Broadcom/AirForce chips (BCM43xx with Wireless-Core +Revision 5), which corresponds to the @code{b43-open} Linux-libre driver. +Free firmware exists for both and is available out-of-the-box on Guix +System, as part of @code{%base-firmware} (@pxref{Referencia de ``operating-system'', +@code{firmware}}). + +@cindex RYF, Respeta Su Libertad +La @uref{https://www.fsf.org/, Fundación del Software Libre} patrocina +@uref{https://www.fsf.org/ryf, @dfn{Respeta Su Libertad}} (RYF), un programa +de certificación para productos hardware que respetan su libertad y su +privacidad y se aseguran de que usted tenga el control sobre su +dispositivo. Le recomendamos que compruebe la lista de dispositivos +certificados RYF. + +Otro recurso útil es el sitio web @uref{https://wwww.h-node.org/, +H-Node}. Contiene un catálogo de dispositivos hardware con información +acerca su funcionalidad con GNU/Linux. + + +@node Instalación desde memoria USB y DVD +@section Instalación desde memoria USB y DVD + +Se puede descargar una imagen de instalación ISO-9660 que puede ser escrita +en una memoria USB o grabada en un DVD desde +@indicateurl{https://alpha.gnu.org/gnu/guix/guix-system-install-@value{VERSION}.@var{sistema}.iso.xz}, +donde @var{sistema} es uno de los siguientes valores: + +@table @code +@item x86_64-linux +para un sistema GNU/Linux en CPUs compatibles con la arquitectura de 64-bits +de Intel/AMD. + +@item i686-linux +para un sistema GNU/Linux en CPUs compatibles con la arquitectura de 32-bits +de Intel. +@end table + +@c start duplication of authentication part from ``Binary Installation'' +Asegurese de descargar el fichero @file{.sig} asociado y de verificar la +autenticidad de la imagen contra él, más o menos así: + +@example +$ wget https://alpha.gnu.org/gnu/guix/guix-system-install-@value{VERSION}.@var{sistema}.iso.xz.sig +$ gpg --verify guix-system-install-@value{VERSION}.@var{sistema}.iso.xz.sig +@end example + +Si la orden falla porque no dispone de la clave pública necesaria, entonces +ejecute esta otra orden para importarla: + +@example +$ gpg --keyserver @value{KEY-SERVER} \ + --recv-keys @value{OPENPGP-SIGNING-KEY-ID} +@end example + +@noindent +@c end duplication +y vuelva a ejecutar la orden @code{gpg --verify}. + +Esta imagen contiene las herramientas necesarias para una instalación. Está +pensada ara ser copiada @emph{tal cual} a una memoria USB o DVD con espacio +suficiente. + +@unnumberedsubsec Copiado en una memoria USB + +Para copiar la imagen en una memoria USB, siga estos pasos: + +@enumerate +@item +Descomprima la imagen usando la orden @command{xz}: + +@example +xz -d guix-system-install-@value{VERSION}.@var{sistema}.iso.xz +@end example + +@item +Conecte una memoria USB de 1@tie{}GiB o más a su máquina, y determine su +nombre de dispositivo. Asumiendo que la memoria USB es @file{/dev/sdX} copie +la imagen con: + +@example +dd if=guix-system-install-@value{VERSION}.@var{sistema}.iso of=/dev/sdX +sync +@end example + +El acceso a @file{/dev/sdX} normalmente necesita privilegios de root. +@end enumerate + +@unnumberedsubsec Grabación en un DVD + +Para copiar la imagen a un DVD, siga estos pasos: + +@enumerate +@item +Descomprima la imagen usando la orden @command{xz}: + +@example +xz -d guix-system-install-@value{VERSION}.@var{sistema}.iso.xz +@end example + +@item +Introduzca un DVD escribible en su máquina, y determine el nombre del +dispositivo. Asumiendo que la unidad DVD es @file{/dev/srX}, copie la imagen +con: + +@example +growisofs -dvd-compat -Z /dev/srX=guix-system-install-@value{VERSION}.@var{sistema}.iso +@end example + +El acceso a @file{/dev/srX} normalmente necesita privilegios de root. +@end enumerate + +@unnumberedsubsec Arranque + +Una vez hecho esto, debe ser capaz de reiniciar el sistema y arrancar desde +la memoria USB o el DVD. Lo primero habitualmente requiere que introducirse +en la BIOS o en el menú de arranque UEFI, donde se puede seleccionar el +arranque desde la memoria USB. + +@xref{Instalación de Guix en una máquina virtual}, si, en vez de esto, desea instalar el +sistema Guix en una máquina virtual (VM). + + +@node Preparación para la instalación +@section Preparación para la instalación + +Una vez que haya arrancado, puede usar el instalador gráfico guiado, el cual +facilita la introducción al sistema (@pxref{Instalación gráfica guiada}). Alternativamente, si ya es está familiarizada con GNU/Linux +y desea más control que el que proporciona el instalador gráfico, puede +seleccionar el proceso de instalación ``manual'' (@pxref{Instalación manual}). + +El instalador gráfico está disponible en TTY1. Puede obtener consolas de +root en los TTY 3 a 6 pulsando @kbd{ctrl-alt-f3}, @kbd{ctrl-alt-f4}, +etc. TTY2 muestra esta documentación y se puede cambiar a dicha consola con +@kbd{ctrl-alt-f2}. La documentación es explorable usando las órdenes del +lector Info (@pxref{Top,,, info-stnd, Stand-alone GNU Info}). El sistema de +instalación ejecuta el daemon GPM para ratones, el cual le permite +seleccionar texto con el botón izquierdo y pegarlo con el botón central. + +@quotation Nota +La instalación requiere acceso a Internet de modo que cualquier dependencia +de su configuración de sistema no encontrada pueda ser descargada. Véase la +sección ``Red'' más adelante. +@end quotation + +@node Instalación gráfica guiada +@section Instalación gráfica guiada + +El instalador gráfico es una interfaz de usuaria basada en texto. Le guiará, +con cajas de diálogo, a través de los pasos necesarios para instalar el +sistema GNU@tie{}Guix. + +Las primeras cajas de diálogo le permiten configurar el sistema mientras lo +usa durante la instalación: puede seleccionar el idioma, la distribución del +teclado y configurar la red, la cual se usará durante la instalación. La +siguiente imagen muestra el diálogo de configuración de red. + +@image{images/installer-network,5in,, configuración de red en la instalación +gráfica} + +Los siguientes pasos le permitirán particionar su disco duro, como se +muestra en la siguiente imagen, elegir si se usarán o no sistemas de +ficheros cifrados, introducir el nombre de la máquina, la contraseña de root +y crear cuentas adicionales, entre otras cosas. + +@image{images/installer-partitions,5in,, particionado en la instalación +gráfica} + +Tenga en cuenta que, en cualquier momento, el instalador le permite salir de +la instalación actual y retomarla en un paso previo, como se muestra en la +siguiente imagen. + +@image{images/installer-resume,5in,, retomado del proceso de instalación} + +Una vez haya finalizado, el instalador produce una configuración de sistema +operativo y la muestra (@pxref{Uso de la configuración del sistema}). En este +punto puede pulsar ``OK'' y la instalación procederá. En caso de +finalización satisfactoria, puede reiniciar con el nuevo sistema y +disfrutarlo. ¡@xref{Tras la instalación del sistema} para ver cómo proceder a +continuación! + + +@node Instalación manual +@section Instalación manual + +Esta sección describe como podría instalar ``manualmente'' el sistema +GNU@tie{}Guix en su máquina. Esta opción requiere familiaridad con +GNU/Linux, con el shell y con las herramientas de administración comunes. Si +puensa que no es para usted, considere el uso del instalador gráfico guiado +(@pxref{Instalación gráfica guiada}). + +El sistema de instalación proporciona consolas de root en los terminales +virtuales (TTY) 3 a 6; pulse @kbd{ctrl-alt-f3}, @kbd{ctrl-alt-f4} y +sucesivas teclas para abrirlas. Incluye muchas herramientas comunes +necesarias para la instalación del sistema. Pero es también un sistema Guix +completo, lo que significa que puede instalar paquetes adicionales, en caso +de necesitarlos, mediante el uso de @command{guix package} (@pxref{Invocación de guix package}). + +@menu +* Distribución de teclado y red y particionado:: Configuración inicial. +* Procedimiento de instalación:: Instalación. +@end menu + +@node Distribución de teclado y red y particionado +@subsection Distribución de teclado, red y particionado + +Antes de instalar el sistema, puede desear ajustar la distribución del +teclado, configurar la red y particionar el disco duro deseado. Esta sección +le guiará durante este proceso. + +@subsubsection Distribución de teclado + +@cindex distribución de teclado +La imagen de instalación usa la distribución de teclado QWERTY de los +EEUU. Si desea cambiarla, puede usar la orden @command{loadkeys}. Por +ejemplo, la siguiente orden selecciona la distribución de teclado para el +castellano: + +@example +loadkeys es +@end example + +Véanse los ficheros bajo @file{/run/current-system/profile/share/keymaps} +para la obtención de una lista de distribuciones de teclado +disponibles. Ejecute @command{man loadkeys} para más información. + +@subsubsection Red + +Ejecute la siguiente orden para ver los nombres asignados a sus interfaces +de red: + +@example +ifconfig -a +@end example + +@noindent +@dots{} o, usando la orden específica de GNU/Linux @command{ip}: + +@example +ip a +@end example + +@c http://cgit.freedesktop.org/systemd/systemd/tree/src/udev/udev-builtin-net_id.c#n20 +El nombre de las interfaces de cable comienza con @samp{e}; por ejemplo, la +interfaz que corresponde a la primera controladora Ethernet en la placa se +llama @samp{eno1}. El nombre de las interfaces inalámbricas comienza con +@samp{w}, como @samp{w1p2s0}. + +@table @asis +@item Conexión por cable +Para configurar una red por cable ejecute la siguiente orden, substituyendo +@var{interfaz} con el nombre de la interfaz de cable que desea usar. + +@example +ifconfig @var{interfaz} up +@end example + +@item Conexión sin cable +@cindex sin cables +@cindex WiFi +Para configurar una red inalámbrica, puede crear un fichero de configuración +para la herramienta de configuración @command{wpa_supplicant} (su ruta no es +importante) usando uno de los editores de texto disponibles como +@command{nano}: + +@example +nano wpa_supplicant.conf +@end example + +Como un ejemplo, la siguiente plantilla puede colocarse en este fichero y +funcionará para muchas redes inalámbricas, siempre que se proporcione el +SSID y la contraseña reales de la red a la que se va a conectar: + +@example +network=@{ + ssid="@var{mi-ssid}" + key_mgmt=WPA-PSK + psk="la contraseña de la red" +@} +@end example + +Inicie el servicio inalámbrico y ejecutelo en segundo plano con la siguiente +orden (sustituya @var{interfaz} por el nombre de la interfaz de red que +desea usar): + +@example +wpa_supplicant -c wpa_supplicant.conf -i @var{interfaz} -B +@end example + +Ejecute @command{man wpa_supplicant} para más información. +@end table + +@cindex DHCP +En este punto, necesita obtener una dirección IP. En una red donde las +direcciones IP se asignan automáticamente mediante DHCP, puede ejecutar: + +@example +dhclient -v @var{interfaz} +@end example + +Intente hacer ping a un servidor para comprobar si la red está funcionando +correctamente: + +@example +ping -c 3 gnu.org +@end example + +Configurar el acceso por red es casi siempre un requisito debido a que la +imagen no contiene todo el software y las herramientas que puedan ser +necesarias. + +@cindex instalación por SSH +Si lo desea, puede continuar la instalación de forma remota iniciando un +servidor SSH: + +@example +herd start ssh-daemon +@end example + +Asegurese de fijar una contraseña con @command{passwd}, o configurar la +verificación de clave pública de OpenSSH para la introducción en el sistema. + +@subsubsection Particionado de discos + +A menos que se haya realizado previamente, el siguiente paso es el +particionado, y después dar formato a la/s partición/es deseadas. + +La imagen de instalación contiene varias herramientas de particionado, +incluyendo Parted (@pxref{Overview,,, parted, GNU Parted User Manual}), +@command{fdisk} y @command{cfdisk}. Ejecutelo y configure el mapa de +particiones deseado en su disco: + +@example +cfdisk +@end example + +Si su disco usa el formato de tabla de particiones GUID (GPT) y tiene +pensado instalar GRUB basado en BIOS (la opción predeterminada), asegurese +de tener una partición de arranque BIOS disponible (@pxref{BIOS +installation,,, grub, GNU GRUB manual}). + +@cindex EFI, instalación +@cindex UEFI, instalación +@cindex ESP, partición del sistema EFI +Si en vez de eso desea GRUB basado en EFI, se requiere una @dfn{Partición +del Sistema EFI} (ESP) con formato FAT32. Esta partición puede montarse en +@file{/boot/efi} y debe tener la opción @code{esp} activa. Por ejemplo, en +@command{parted}: + +@example +parted /dev/sda set 1 esp on +@end example + +@quotation Nota +@vindex grub-bootloader +@vindex grub-efi-bootloader +¿No esta segura si usar GRUB basado en EFI o en BIOS? Si el directorio +@file{/sys/firmware/efi} existe en la imagen de instalación, probablemente +debería realizar una instalación EFI, usando @code{grub-efi-bootloader}. En +otro caso, debe usar GRUB basado en BIOS, conocido como +@code{grub-bootloader}. @xref{Configuración del gestor de arranque}, para más +información sobre cargadores de arranque. +@end quotation + +Una vez haya terminado con el particionado de la unidad de disco deseada, +tiene que crear un sistema de ficheros en la o las particiónes +relevantes@footnote{Actualmente el sistema Guix únicamente permite sistemas +de ficheros ext4 y btrfs. En particular, el código que lee UUIDs del sistema +de ficheros y etiquetas únicamente funciona para dichos sistemas de +ficheros.}. Para la ESP, si tiene una y asumiendo que es @file{/dev/sda1}, +ejecute: + +@example +mkfs.fat -F32 /dev/sda1 +@end example + +Preferentemente, asigne una etiqueta a los sistemas de ficheros de modo que +pueda referirse a ellos de forma fácil y precisa en las declaraciones +@code{file-system} (@pxref{Sistemas de ficheros}). Esto se consigue habitualmente +con la opción @code{-L} de @command{mkfs.ext4} y las ordenes +relacionadas. Por tanto, asumiendo que la partición de la raíz es +@file{/dev/sda2}, se puede crear un sistema de ficheros con la etiqueta +@code{mi-raiz} de esta manera: + +@example +mkfs.ext4 -L mi-raiz /dev/sda2 +@end example + +@cindex disco cifrado +Si en vez de eso planea cifrar la partición raíz, puede usar las +herramientas Crypsetup/LUKS para hacerlo (véase @inlinefmtifelse{html, +@uref{https://linux.die.net/man/8/cryptsetup, @code{man cryptsetup}}, +@code{man cryptsetup}} para más información). Asumiendo que quiere almacenar +la partición raíz en @file{/dev/sda2}, la secuencia de ordenes sería más o +menos así: + +@example +cryptsetup luksFormat /dev/sda2 +cryptsetup open --type luks /dev/sda1 mi-particion +mkfs.ext4 -L mi-raiz /dev/mapper/mi-particion +@end example + +Una vez hecho esto, monte el sistema de ficheros deseado bajo @file{/mnt} +con una orden como (de nuevo, asumiendo que @code{mi-raiz} es la etiqueta +del sistema de ficheros raíz): + +@example +mount LABEL=mi-raiz /mnt +@end example + +Monte también cualquier otro sistema de ficheros que desee usar en el +sistema resultante relativamente a esta ruta. Si ha optado por +@file{/boot/efi} como el punto de montaje de EFI, por ejemplo, ahora debe +ser montada en @file{/mnt/boot/efi} para que @code{guix system init} pueda +encontrarla más adelante. + +Finalmente, si planea usar una o más particiones de intercambio +(@pxref{Memory Concepts, swap space,, libc, The GNU C Library Reference +Manual}), asegurese de inicializarla con @command{mkswap}. Asumiendo que +tuviese una partición de intercambio en @file{/dev/sda3}, ejecutaría: + +@example +mkswap /dev/sda3 +swapon /dev/sda3 +@end example + +De manera alternativa, puede usar un fichero de intercambio. Por ejemplo, +asumiendo que en el nuevo sistema desea usar el fichero +@file{/fichero-de-intercambio} como tal, ejecutaría@footnote{Este ejemplo +funcionará para muchos tipos de sistemas de ficheros (por ejemplo, ext4). No +obstante, para los sistemas de ficheros con mecanismos de +copia-durante-escritura (por ejemplo, btrfs) los pasos pueden diferir. Para +obtener más detalles, véanse las páginas de manual para @command{mkswap} y +@command{swapon}.}: + +@example +# Esto son 10GiB de espacio de intercambio. Ajuste "count" para +# cambiar el tamaño. +dd if=/dev/zero of=/mnt/swapfile bs=1MiB count=10240 +# Por seguridad, se mantiene el fichero únicamente legible y +# escribible por root. +chmod 600 /mnt/swapfile +mkswap /mnt/swapfile +swapon /mnt/swapfile +@end example + +Fijese que si ha cifrado la partición raíz y creado un fichero de +intercambio en su sistema de ficheros como se ha descrito anteriormente, el +cifrado también protege al fichero de intercambio, como a cualquier fichero +en dicho sistema de ficheros. + +@node Procedimiento de instalación +@subsection Procedimiento de instalación + +Con las particiones deseadas listas y la raíz deseada montada en +@file{/mnt}, estamos preparadas para empezar. Primero, ejecute: + +@example +herd start cow-store /mnt +@end example + +Esto activa la copia-durante-escritura en @file{/gnu/store}, de modo que los +paquetes que se añadan durante la fase de instalación se escriban en el +disco montado en @file{/mnt} en vez de permanecer en memoria. Esto es +necesario debido a que la primera fase de la orden @command{guix system +init} (vea más adelante) implica descargas o construcciones en +@file{/gnu/store}, el cual, inicialmente, está un sistema de ficheros en +memoria. + +Después debe editar un fichero y proporcionar la declaración de sistema +operativo a instalar. Para dicho fin, el sistema de instalación viene con +tres editores de texto. Recomendamos GNU nano (@pxref{Top,,, nano, GNU nano +Manual}), que permite el resaltado de sintaxis y correspondencia de +paréntesis; los otros editores son GNU Zile (un clon de Emacs) y nvi (un +clon del editor @command{vi} original de BSD). Le recomendamos +encarecidamente almacenar ese fichero en el sistema de ficheros raíz, +digamos, como @file{/mnt/etc/config.scm}. En caso de no hacerlo, habrá +perdido su configuración del sistema una vez arranque en el sistema recién +instalado. + +@xref{Uso de la configuración del sistema}, para hacerse una idea del fichero de +configuración. Las configuraciones de ejemplo mencionadas en esa sección +están disponibles bajo @file{/etc/configuration} en la imagen de +instalación. Por tanto, para empezar con una configuración del sistema que +proporcione un servidor gráfico (un sistema de ``escritorio''), puede +ejecutar algo parecido a estas órdenes: + +@example +# mkdir /mnt/etc +# cp /etc/configuration/desktop.scm /mnt/etc/config.scm +# nano /mnt/etc/config.scm +@end example + +Debe prestar atención a lo que su fichero de configuración contiene, y en +particular: + +@itemize +@item +Asegurese que la forma @code{bootloader-configuration} especifica la +localización deseada de la instalación de GRUB. Debe mencionar +@code{grub-bootloader} si está usando GRUB con el arranque antiguo, o +@code{grub-efi-bootloader} para sistemas más nuevos UEFI. Para los sistemas +antiguos, el campo @code{target} denomina un dispositivo, como +@code{/dev/sda}; para los sistemas UEFI denomina la ruta de una partición +EFI montada, como @code{/boot/efi}; asegurese de que la ruta está +actualmente montada y haya una entrada @code{file-system} especificada en su +configuración. + +@item +Asegurese que las etiquetas de su sistema de ficheros corresponden con el +valor de sus campos @code{device} respectivos en su configuración +@code{file-system}, asumiendo que su configuración @code{file-system} usa el +procedimiento @code{file-system-label} en su campo @code{device}. + +@item +Si hay particiones cifradas o en RAID, asegurese de añadir un campo +@code{mapped-devices} para describirlas (@pxref{Dispositivos traducidos}). +@end itemize + +Una vez haya terminado de preparar el fichero de configuración, el nuevo +sistema debe ser inicializado (recuerde que el sistema de ficheros raíz +deseado está montado bajo @file{/mnt}): + +@example +guix system init /mnt/etc/config.scm /mnt +@end example + +@noindent +Esto copia todos los ficheros necesarios e instala GRUB en @file{/dev/sdX}, +a menos que proporcione la opción @option{--no-bootloader}. Para más +información, @pxref{Invocación de guix system}. Esta orden puede desencadenar +descargas o construcciones de paquetes no encontrados, lo cual puede tomar +algún tiempo. + +Una vez que la orden se complete---¡y, deseablemente, de forma +satisfactoria!---puede ejecutar @command{reboot} y arrancar con el nuevo +sistema. La contraseña de @code{root} en el nuevo sistema está vacía +inicialmente; otras contraseñas de usuarias tienen que ser inicializadas +ejecutando la orden @command{passwd} como @code{root}, a menos que en su +configuración se especifique de otra manera (@pxref{user-account-password, +contraseñas de cuentas de usuaria}). ¡@xref{Tras la instalación del sistema} para +proceder a continuación! + + +@node Tras la instalación del sistema +@section Tras la instalación del sistema + +¡Éxito! ¡Ha arrancado en el sistema Guix! De ahora en adelante, puede +actualizar el sistema cuando quiera mediante la ejecución de, digamos: + +@example +guix pull +sudo guix system reconfigure /etc/config.scm +@end example + +@noindent +Esto construye una nueva generación del sistema con los últimos paquetes y +servicios (@pxref{Invocación de guix system}). Recomendamos realizarlo de manera +regular de modo que su sistema incluya las últimas actualizaciones de +seguridad (@pxref{Actualizaciones de seguridad}). + +@c See <https://lists.gnu.org/archive/html/guix-devel/2019-01/msg00268.html>. +@quotation Nota +@cindex sudo y @command{guix pull} +Tenga en cuenta que @command{sudo guix} ejecuta el ejecutable @command{guix} +de su usuaria y @emph{no} el de root, ya que @command{sudo} no altera +@code{PATH}. Para ejecutar explícitamente el ejecutable @command{guix} de +root, escriba @command{sudo -i guix @dots{}}. +@end quotation + +¡Unase a nosotras en @code{#guix} en la red IRC Freenode o en +@file{guix-devel@@gnu.org} para compartir su experiencia! + + +@node Instalación de Guix en una máquina virtual +@section Instalación de Guix en una máquina virtual + +@cindex máquina virtual, instalación del sistema Guix +@cindex servidor virtual privado (VPS) +@cindex VPS (servidor virtual privado) +Si desea instalar el sistema Guix en una máquina virtual (VM) o en un +servidor privado virtual (VPS) en vez de en su preciada máquina, esta +sección es para usted. + +Si quiere arrancar una VM @uref{http://qemu.org/,QEMU} para instalar el +sistema Guix en una imagen de disco, siga estos pasos: + +@enumerate +@item +Primero, obtenga y descomprima la imagen de instalación del sistema Guix +como se ha descrito previamente (@pxref{Instalación desde memoria USB y DVD}). + +@item +Cree una imagen de disco que contendrá el sistema instalado. Para crear una +imagen de disco con formato qcow2, use la orden @command{qemu-img}: + +@example +qemu-img create -f qcow2 guixsd.img 50G +@end example + +El fichero que obtenga será mucho menor de 50GB (típicamente menos de 1MB), +pero crecerá cuando el dispositivo de almacenamiento virtualizado se vaya +llenando. + +@item +Arranque la imagen de instalación USB en una máquina virtual: + +@example +qemu-system-x86_64 -m 1024 -smp 1 \ + -net user -net nic,model=virtio -boot menu=on \ + -drive file=guix-system-install-@value{VERSION}.@var{sistema}.iso \ + -drive file=guixsd.img +@end example + +El orden de las unidades importa. + +En la consola de la VM, pulse rápidamente la tecla @kbd{F12} para entrar al +menú de arranque. Pulse la tecla @kbd{2} y la tecla @kbd{RET} para confirmar +su selección. + +@item +Ahora es root en la VM, prosiga con el procedimiento de +instalación. @xref{Preparación para la instalación}, y siga las instrucciones. +@end enumerate + +Una vez complete la instalación, puede arrancar el sistema que está en la +imagen @file{guixsd.img}. @xref{Ejecutar Guix en una máquina virtual}, para información +sobre cómo hacerlo. + +@node Construcción de la imagen de instalación +@section Construcción de la imagen de instalación + +@cindex imagen de instalación +La imagen de instalación descrita anteriormente se construyó usando la orden +@command{guix system}, específicamente: + +@example +guix system disk-image --file-system-type=iso9660 \ + gnu/system/install.scm +@end example + +Eche un vistazo a @file{gnu/system/install.scm} en el árbol de fuentes, y +vea también @ref{Invocación de guix system} para más información acerca de la +imagen de instalación. + +@section Construcción de la imagen de instalación para placas ARM + +Muchas placas ARM necesitan una variante específica del cargador de arranque +@uref{http://www.denx.de/wiki/U-Boot/, U-Boot}. + +Si construye una imagen de disco y el cargador de arranque no está +disponible de otro modo (en otra unidad de arranque, etc.), es recomendable +construir una imagen que incluya el cargador, específicamente: + +@example +guix system disk-image --system=armhf-linux -e '((@@ (gnu system install) os-with-u-boot) (@@ (gnu system install) installation-os) "A20-OLinuXino-Lime2")' +@end example + +@code{A20-OLinuXino-Lime2} es el nombre de la placa. Si especifica una placa +no válida, una lista de placas posibles será mostrada. + +@c ********************************************************************* +@node Gestión de paquetes +@chapter Gestión de paquetes + +@cindex paquetes +El propósito de GNU Guix es permitir a las usuarias instalar, actualizar y +borrar fácilmente paquetes de software, sin tener que conocer acerca de sus +procedimientos de construcción o dependencias. Guix también va más allá de +este conjunto obvio de características. + +Este capítulo describe las principales características de Guix, así como las +herramientas de gestión de paquetes que ofrece. Junto a la interfaz de línea +de órdenes descrita a continuación (@pxref{Invocación de guix package, @code{guix +package}}, también puede usar la interfaz Emacs-Guix (@pxref{Top,,, +emacs-guix, The Emacs Guix Reference Manual}), tras la instalación del +paquete @code{emacs-guix} (ejecute la orden @kbd{M-x guix-help} para +iniciarse en su uso): + +@example +guix package -i emacs-guix +@end example + +@menu +* Características:: Cómo Guix dará brillo a su vida. +* Invocación de guix package:: Instalación de paquetes, borrado, etc. +* Sustituciones:: Descargar binarios pre-construidos. +* Paquetes con múltiples salidas:: Un único paquete de fuentes, + múltiples salidas. +* Invocación de guix gc:: Ejecutar el recolector de basura. +* Invocación de guix pull:: Obtener la última versión de Guix y la + distribución. +* Canales:: Personalizar el recolector de basura. +* Inferiores:: Interactuar con otra revisión de Guix. +* Invocación de guix describe:: Muestra información acerca de su + revisión de Guix. +* Invocación de guix archive:: Exportar e importar ficheros del almacén. +@end menu + +@node Características +@section Características + +Cuando se usa Guix, cada paquete se encuentra en el @dfn{almacén de +paquetes}, en su propio directorio---algo que se asemeja a +@file{/gnu/store/xxx-paquete-1.2}, donde @code{xxx} es una cadena en base32. + +En vez de referirse a estos directorios, las usuarias tienen su propio +@dfn{perfil}, el cual apunta a los paquetes que realmente desean usar. Estos +perfiles se almacenan en el directorio de cada usuaria, en +@code{$HOME/.guix-profile}. + +Por ejemplo, @code{alicia} instala GCC 4.7.2. Como resultado, +@file{/home/alicia/.guix-profile/bin/gcc} apunta a +@file{/gnu/store/@dots{}-gcc-4.7.2/bin/gcc}. Ahora, en la misma máquina, +@code{rober} ha instalado ya GCC 4.8.0. El perfil de @code{rober} +simplemente sigue apuntando a +@file{/gnu/store/@dots{}-gcc-4.8.0/bin/gcc}---es decir, ambas versiones de +GCC pueden coexistir en el mismo sistema sin ninguna interferencia. + +La orden @command{guix package} es la herramienta central para gestión de +paquetes (@pxref{Invocación de guix package}). Opera en los perfiles de usuaria, +y puede ser usada @emph{con privilegios de usuaria normal}. + +@cindex transacciones +La orden proporciona las operaciones obvias de instalación, borrado y +actualización. Cada invocación es en realidad una @emph{transacción}: o bien +la operación especificada se realiza satisfactoriamente, o bien nada +sucede. Por tanto, si el proceso @command{guix package} es finalizado +durante una transacción, o un fallo eléctrico ocurre durante la transacción, +el perfil de usuaria permanece en su estado previo, y permanece usable. + +Además, cualquier transacción de paquetes puede ser @emph{vuelta atrás}. Si, +por ejemplo, una actualización instala una nueva versión de un paquete que +resulta tener un error importante, las usuarias pueden volver a la instancia +previa de su perfil, de la cual se tiene constancia que funcionaba bien. De +igual modo, la configuración global del sistema en Guix está sujeta a +actualizaciones transaccionales y vuelta atrás (@pxref{Uso de la configuración del sistema}). + +Todos los paquetes en el almacén de paquetes pueden ser @emph{eliminados por +el recolector de basura}. Guix puede determinar qué paquetes están siendo +todavía referenciados por los perfiles de usuarias, y eliminar aquellos que, +de forma demostrable, no están referenciados (@pxref{Invocación de guix gc}). Las +usuarias pueden también borrar explícitamente generaciones antiguas de su +perfil para que los paquetes referenciados en ellas puedan ser recolectadas. + +@cindex reproducibilidad +@cindex construcciones reproducibles +Guix toma una aproximación @dfn{puramente funcional} en la gestión de +paquetes, como se describe en la introducción (@pxref{Introducción}). Cada +nombre de directorio de paquete en @file{/gnu/store} contiene un hash de +todas las entradas que fueron usadas para construir el paquete---compilador, +bibliotecas, guiones de construcción, etc. Esta correspondencia directa +permite a las usuarias asegurarse que una instalación dada de un paquete +corresponde al estado actual de su distribución. Esto también ayuda a +maximizar la @dfn{reproducibilidad de la construcción}: gracias al uso de +entornos aislados de construcción, una construcción dada probablemente +generará ficheros idénticos bit-a-bit cuando se realice en máquinas +diferentes (@pxref{Invocación de guix-daemon, container}). + +@cindex sustituciones +Estos cimientos permiten a Guix ofrecer @dfn{despliegues transparentes de +binarios/fuentes}. Cuando un binario pre-construido para un elemento de +@file{/gnu/store} está disponible para descarga de una fuente externa---una +@dfn{sustitución}, Guix simplemente lo descarga y desempaqueta; en otro caso +construye el paquete de las fuentes, localmente +(@pxref{Sustituciones}). Debido a que los resultados de construcción son +normalmente reproducibles bit-a-bit, las usuarias no tienen que confiar en +los servidores que proporcionan sustituciones: pueden forzar una +construcción local y @emph{retar} a las proveedoras (@pxref{Invocación de guix challenge}). + +El control sobre el entorno de construcción es una característica que +también es útil para desarrolladoras. La orden @command{guix environment} +permite a desarrolladoras de un paquete configurar rápidamente el entorno de +desarrollo correcto para su paquete, sin tener que instalar manualmente las +dependencias del paquete en su perfil (@pxref{Invocación de guix environment}). + +@cindex replicación, de entornos de software +@cindex seguimiento de procedencia, de artefactos de software +Todo Guix y sus definiciones de paquetes están bajo control de versiones, y +@command{guix pull} le permite ``viajar en el tiempo'' por la historia del +mismo Guix (@pxref{Invocación de guix pull}). Esto hace posible replicar una +instancia de Guix en una máquina diferente o en un punto posterior del +tiempo, lo que a su vez le permite @emph{replicar entornos de software +completos}, mientras que mantiene un preciso @dfn{seguimiento de la +procedencia} del software. + +@node Invocación de guix package +@section Invocación de @command{guix package} + +@cindex instalar paquetes +@cindex borrar paquetes +@cindex instalación de paquetes +@cindex borrado de paquetes +La orden @command{guix package} es la herramienta que permite a las usuarias +instalar, actualizar y borrar paquetes, así como volver a configuraciones +previas. Opera únicamente en el perfil propio de la usuaria, y funciona con +privilegios de usuaria normal (@pxref{Características}). Su sintaxis es: + +@example +guix package @var{opciones} +@end example +@cindex transacciones +Primariamente, @var{opciones} especifica las operaciones a ser realizadas +durante la transacción. Al completarse, un nuevo perfil es creado, pero las +@dfn{generaciones} previas del perfil permanecen disponibles, en caso de que +la usuaria quisiera volver atrás. + +Por ejemplo, para borrar @code{lua} e instalar @code{guile} y +@code{guile-cairo} en una única transacción: + +@example +guix package -r lua -i guile guile-cairo +@end example + +@command{guix package} también proporciona una @dfn{aproximación +declarativa}, donde la usuaria especifica el conjunto exacto de paquetes a +poner disponibles y la pasa a través de la opción @option{--manifest} +(@pxref{profile-manifest, @option{--manifest}}). + +@cindex perfil +Para cada usuaria, un enlace simbólico al perfil predeterminado de la +usuaria es creado en @file{$HOME/.guix-profile}. Este enlace simbólico +siempre apunta a la generación actual del perfil predeterminado de la +usuaria. Por lo tanto, las usuarias pueden añadir +@file{$HOME/.guix-profile/bin} a su variable de entorno @code{PATH}, y +demás. +@cindex rutas de búsqueda +Si no está usando la Distribución de Sistema Guix, considere añadir las +siguientes líneas a su @file{~/.bash_profile} (@pxref{Bash Startup Files,,, +bash, The GNU Bash Reference Manual}) de modo que los shell lanzados a +partir de entonces obtengan todas las definiciones de variables de entorno +correctas: + +@example +GUIX_PROFILE="$HOME/.guix-profile" ; \ +source "$HOME/.guix-profile/etc/profile" +@end example + +En una configuración multiusuaria, los perfiles de usuaria se almacenan en +un lugar registrado como una @dfn{raíz del sistema de ficheros}, a la que +apunta @file{$HOME/.guix-profile} (@pxref{Invocación de guix gc}). Ese directorio +normalmente es +@code{@var{localstatedir}/guix/profiles/per-user/@var{usuaria}}, donde +@var{localstatedir} es el valor pasado a @code{configure} como +@code{--localstatedir} y @var{usuaria} es el nombre de usuaria. El +directorio @file{per-user} se crea cuando se lanza @command{guix-daemon}, y +el subdirectorio @var{usuaria} es creado por @command{guix package}. + +Las @var{opciones} pueden ser las siguientes: + +@table @code + +@item --install=@var{paquete} @dots{} +@itemx -i @var{paquete} @dots{} +Instala los @var{paquete}s especificados. + +Cada @var{paquete} puede especificar un nombre simple de paquete, como por +ejemplo @code{guile}, o un nombre de paquete seguido por una arroba y el +número de versión, como por ejemplo @code{guile@@1.8.8} o simplemente +@code{guile@@1.8} (en el último caso la última versión con @code{1.8} como +prefijo es seleccionada). + +Si no se especifica un número de versión, la última versión disponible será +seleccionada. Además, @var{paquete} puede contener dos puntos, seguido por +el nombre de una de las salidas del paquete, como en @code{gcc:doc} o +@code{binutils@@2.22:lib} (@pxref{Paquetes con múltiples salidas}). Los +paquetes con el nombre correspondiente (y opcionalmente la versión) se +buscan entre los módulos de la distribución GNU (@pxref{Módulos de paquetes}). + +@cindex entradas propagadas +A veces los paquetes tienen @dfn{entradas propagadas}: estas son las +dependencias que se instalan automáticamente junto al paquete requerido +(@pxref{package-propagated-inputs, @code{propagated-inputs} in +@code{package} objects}, para información sobre las entradas propagadas en +las definiciones de paquete). + +@anchor{package-cmd-propagated-inputs} +Un ejemplo es la biblioteca GNU MPC: sus ficheros de cabecera C hacen +referencia a los de la biblioteca GNU MPFR, que a su vez hacen referencia a +los de la biblioteca GMP. Por tanto, cuando se instala MPC, las bibliotecas +MPFR y GMP también se instalan en el perfil; borrar MPC también borra MPFR y +GMP---a menos que también se hayan instalado explícitamente por la usuaria. + +Por otra parte, los paquetes a veces dependen de la definición de variables +de entorno para sus rutas de búsqueda (véase a continuación la explicación +de @code{--seach-paths}). Cualquier definición de variable de entorno que +falte o sea posiblemente incorrecta se informa aquí. + +@item --install-from-expression=@var{exp} +@itemx -e @var{exp} +Instala el paquete al que @var{exp} evalúa. + +@var{exp} debe ser una expresión Scheme que evalue a un objeto +@code{<package>}. Esta opción es notablemente útil para desambiguar entre +variantes con el mismo nombre que un paquete, con expresiones como @code{(@@ +(gnu packages base) guile-final)}. + +Fíjese que esta opción instala la primera salida del paquete especificado, +lo cual puede ser insuficiente cuando se necesita una salida específica de +un paquete con múltiples salidas. + +@item --install-from-file=@var{fichero} +@itemx -f @var{fichero} +Instala el paquete que resulta de evaluar el código en @var{fichero}. + +Como un ejemplo, @var{fichero} puede contener una definición como esta +(@pxref{Definición de paquetes}): + +@example +@verbatiminclude package-hello.scm +@end example + +Las desarrolladoras pueden encontrarlo útil para incluir un fichero +@file{guix.scm} in la raíz del árbol de fuentes de su proyecto que puede ser +usado para probar imágenes de desarrollo y crear entornos de desarrollo +reproducibles (@pxref{Invocación de guix environment}). + +@item --remove=@var{paquete} @dots{} +@itemx -r @var{paquete} @dots{} +Borra los @var{paquete}s especificados. + +Como en @code{--install}, cada @var{paquete} puede especificar un número de +versión y/o un nombre de salida además del nombre del paquete. Por ejemplo, +@code{-r glibc:debug} eliminaría la salida @code{debug} de @code{glibc}. + +@item --upgrade[=@var{regexp} @dots{}] +@itemx -u [@var{regexp} @dots{}] +@cindex actualizar paquetes +Actualiza todos los paquetes instalados. Si se especifica una o más +expresiones regular @var{regexp}, actualiza únicamente los paquetes +instalados cuyo nombre es aceptado por @var{regexp}. Véase también la opción +@code{--do-not-upgrade} más adelante. + +Tenga en cuenta que esto actualiza los paquetes a la última versión +encontrada en la distribución instalada actualmente. Para actualizar su +distribución, debe ejecutar regularmente @command{guix pull} +(@pxref{Invocación de guix pull}). + +@item --do-not-upgrade[=@var{regexp} @dots{}] +Cuando se usa junto a la opción @code{--upgrade}, @emph{no} actualiza ningún +paquete cuyo nombre sea aceptado por @var{regexp}. Por ejemplo, para +actualizar todos los paquetes en el perfil actual excepto aquellos que +contengan la cadena ``emacs'': + +@example +$ guix package --upgrade . --do-not-upgrade emacs +@end example + +@item @anchor{profile-manifest}--manifest=@var{fichero} +@itemx -m @var{fichero} +@cindex declaración del perfil +@cindex manifiesto del perfil +Crea una nueva generación del perfil desde el objeto de manifiesto devuelto +por el código Scheme en @var{fichero}. + +Esto le permite @emph{declarar} los contenidos del perfil en vez de +construirlo a través de una secuencia de @code{--install} y órdenes +similares. La ventaja es que @var{fichero} puede ponerse bajo control de +versiones, copiarse a máquinas diferentes para reproducir el mismo perfil, y +demás. + +@c FIXME: Add reference to (guix profile) documentation when available. +@var{fichero} debe devolver un objeto @dfn{manifest}, que es básicamente una +lista de paquetes: + +@findex packages->manifest +@example +(use-package-modules guile emacs) + +(packages->manifest + (list emacs + guile-2.0 + ;; Usa una salida específica del paquete. + (list guile-2.0 "debug"))) +@end example + +@findex specifications->manifest +En este ejemplo tenemos que conocer qué módulos definen las variables +@code{emacs} y @code{guile-2.0} para proporcionar la línea +@code{use-package-modules} correcta, lo cual puede ser complicado. En cambio +podemos proporcionar especificaciones regulares de paquetes y dejar a +@code{specifications->manifest} buscar los objetos de paquete +correspondientes así: + +@example +(specifications->manifest + '("emacs" "guile@@2.2" "guile@@2.2:debug")) +@end example + +@item --roll-back +@cindex vuelta atrás +@cindex deshacer transacciones +@cindex transacciones, deshaciendo +Vuelve a la @dfn{generación} previa del perfil---es decir, deshace la última +transacción. + +Cuando se combina con opciones como @code{--install}, la vuelta atrás ocurre +antes que cualquier acción. + +Cuando se vuelve atrás en la primera generación que realmente contiene +paquetes instalados, se hace que el perfil apunte a la @dfn{generación +cero}, la cual no contiene ningún fichero a excepción de sus propios +metadatos. + +Después de haber vuelto atrás, instalar, borrar o actualizar paquetes +sobreescribe las generaciones futuras previas. Por tanto, la historia de las +generaciones en un perfil es siempre linear. + +@item --switch-generation=@var{patrón} +@itemx -S @var{patrón} +@cindex generaciones +Cambia a una generación particular definida por el @var{patrón}. + +@var{patrón} puede ser tanto un número de generación como un número +prefijado con ``+'' o ``-''. Esto último significa: mueve atrás/hacia +delante el número especificado de generaciones. Por ejemplo, si quiere +volver a la última generación antes de @code{--roll-back}, use +@code{--switch-generation=+1}. + +La diferencia entre @code{--roll-back} y @code{--switch-generation=-1} es +que @code{--switch-generation} no creará una generación cero, así que si la +generación especificada no existe, la generación actual no se verá cambiada. + +@item --search-paths[=@var{tipo}] +@cindex rutas de búsqueda +Informa de variables de entorno, en sintaxis Bash, que pueden necesitarse +para usar el conjunto de paquetes instalado. Estas variables de entorno se +usan para especificar las @dfn{rutas de búsqueda} para ficheros usadas por +algunos de los paquetes. + +Por ejemplo, GCC necesita que las variables de entorno @code{CPATH} y +@code{LIBRARY_PATH} estén definidas para poder buscar cabeceras y +bibliotecas en el perfil de la usuaria (@pxref{Environment Variables,,, gcc, +Using the GNU Compiler Collection (GCC)}). Si GCC y, digamos, la biblioteca +de C están instaladas en el perfil, entonces @code{--search-paths} sugerirá +fijar dichas variables a @code{@var{perfil}/include} y +@code{@var{perfil}/lib} respectivamente. + +El caso de uso típico es para definir estas variables de entorno en el +shell: + +@example +$ eval `guix package --search-paths` +@end example + +@var{tipo} puede ser @code{exact}, @code{prefix} o @code{suffix}, lo que +significa que las definiciones de variables de entorno devueltas serán +respectivamente las configuraciones exactas, prefijos o sufijos del valor +actual de dichas variables. Cuando se omite, el valor predeterminado de +@var{tipo} es @code{exact}. + +Esta opción puede usarse para calcular las rutas de búsqueda +@emph{combinadas} de varios perfiles. Considere este ejemplo: + +@example +$ guix package -p foo -i guile +$ guix package -p bar -i guile-json +$ guix package -p foo -p bar --search-paths +@end example + +La última orden informa sobre la variable @code{GUILE_LOAD_PATH}, aunque, +tomada individualmente, ni @file{foo} ni @file{bar} hubieran llevado a esa +recomendación. + + +@item --profile=@var{perfil} +@itemx -p @var{perfil} +Usa @var{perfil} en vez del perfil predeterminado de la usuaria. + +@cindex colisiones, en un perfil +@cindex paquetes con colisiones en perfiles +@cindex colisiones del perfil +@item --allow-collisions +Permite colisiones de paquetes en el nuevo perfil. ¡Úselo bajo su propio +riesgo! + +Por defecto, @command{guix package} informa como un error las +@dfn{colisiones} en el perfil. Las colisiones ocurren cuando dos o más +versiones diferentes o variantes de un paquete dado se han seleccionado para +el perfil. + +@item --bootstrap +Use el Guile usado para el lanzamiento para construir el perfil. Esta opción +es util únicamente a las desarrolladoras de la distribución. + +@end table + +Además de estas acciones, @command{guix package} acepta las siguientes +opciones para consultar el estado actual de un perfil, o la disponibilidad +de paquetes: + +@table @option + +@item --search=@var{regexp} +@itemx -s @var{regexp} +@cindex buscar paquetes +Enumera los paquetes disponibles cuyo nombre, sinopsis o descripción +corresponde con @var{regexp} (sin tener en cuenta la capitalización), +ordenados por relevancia. Imprime todos los metadatos de los paquetes +coincidentes en formato @code{recutils} (@pxref{Top, GNU recutils +databases,, recutils, GNU recutils manual}). + +Esto permite extraer campos específicos usando la orden @command{recsel}, +por ejemplo: + +@example +$ guix package -s malloc | recsel -p name,version,relevance +name: jemalloc +version: 4.5.0 +relevance: 6 + +name: glibc +version: 2.25 +relevance: 1 + +name: libgc +version: 7.6.0 +relevance: 1 +@end example + +De manera similar, para mostrar el nombre de todos los paquetes disponibles +bajo los términos de la GNU@tie{}LGPL versión 3: + +@example +$ guix package -s "" | recsel -p name -e 'license ~ "LGPL 3"' +name: elfutils + +name: gmp +@dots{} +@end example + +Es también posible refinar los resultados de búsqueda usando varias opciones +@code{-s}. Por ejemplo, la siguiente orden devuelve un lista de juegos de +mesa (board en inglés): + +@example +$ guix package -s '\<board\>' -s game | recsel -p name +name: gnubg +@dots{} +@end example + +Si omitimos @code{-s game}, también obtendríamos paquetes de software que +tengan que ver con placas de circuitos impresos ("circuit board" en inglés); +borrar los signos mayor y menor alrededor de @code{board} añadiría paquetes +que tienen que ver con teclados (keyboard en inglés). + +Y ahora para un ejemplo más elaborado. La siguiente orden busca bibliotecas +criptográficas, descarta bibliotecas Haskell, Perl, Python y Ruby, e imprime +el nombre y la sinopsis de los paquetes resultantes: + +@example +$ guix package -s crypto -s library | \ + recsel -e '! (name ~ "^(ghc|perl|python|ruby)")' -p name,synopsis +@end example + +@noindent +@xref{Selection Expressions,,, recutils, GNU recutils manual}, para más +información en @dfn{expresiones de selección} para @code{recsel -e}. + +@item --show=@var{paquete} +Muestra los detalles del @var{paquete}, tomado de la lista disponible de +paquetes, en formato @code{recutils} (@pxref{Top, GNU recutils databases,, +recutils, GNU recutils manual}). + +@example +$ guix package --show=python | recsel -p name,version +name: python +version: 2.7.6 + +name: python +version: 3.3.5 +@end example + +Tambien puede especificar el nombre completo de un paquete para únicamente +obtener detalles sobre una versión específica: +@example +$ guix package --show=python@@3.4 | recsel -p name,version +name: python +version: 3.4.3 +@end example + + + +@item --list-installed[=@var{regexp}] +@itemx -I [@var{regexp}] +Enumera los paquetes actualmente instalados en el perfil especificado, con +los últimos paquetes instalados mostrados al final. Cuando se especifica +@var{regexp}, enumera únicamente los paquetes instalados cuyos nombres son +aceptados por @var{regexp}. + +Por cada paquete instalado, imprime los siguientes elementos, separados por +tabuladores: el nombre del paquete, la cadena de versión, la parte del +paquete que está instalada (por ejemplo, @code{out} para la salida +predeterminada, @code{include} para sus cabeceras, etc.), y la ruta de este +paquete en el almacén. + +@item --list-available[=@var{regexp}] +@itemx -A [@var{regexp}] +Enumera los paquetes disponibles actualmente en la distribución para este +sistema (@pxref{Distribución GNU}). Cuando se especifica @var{regexp}, +enumera únicamente paquetes instalados cuyo nombre coincide con +@var{regexp}. + +Por cada paquete, imprime los siguientes elementos separados por +tabuladores: su nombre, su cadena de versión, las partes del paquete +(@pxref{Paquetes con múltiples salidas}) y la dirección de las fuentes de su +definición. + +@item --list-generations[=@var{patrón}] +@itemx -l [@var{patrón}] +@cindex generaciones +Devuelve una lista de generaciones junto a sus fechas de creación; para cada +generación, muestra los paquetes instalados, con los paquetes instalados más +recientemente mostrados los últimos. Fíjese que la generación cero nunca se +muestra. + +Por cada paquete instalado, imprime los siguientes elementos, separados por +tabuladores: el nombre de un paquete, su cadena de versión, la parte del +paquete que está instalada (@pxref{Paquetes con múltiples salidas}), y la +ruta de este paquete en el almacén. + +Cuando se usa @var{patrón}, la orden devuelve únicamente las generaciones +que se ajustan al patrón. Patrones válidos incluyen: + +@itemize +@item @emph{Enteros y enteros separados por comas}. Ambos patrones denotan +números de generación. Por ejemplo, @code{--list-generations=1} devuelve la +primera. + +Y @code{--list-generations=1,8,2} devuelve las tres generaciones en el orden +especificado. No se permiten ni espacios ni una coma al final. + +@item @emph{Rangos}. @code{--list-generations=2..9} imprime +las generaciones especificadas y todas las intermedias. Fíjese que el inicio +de un rango debe ser menor a su fin. + +También es posible omitir el destino final. Por ejemplo, +@code{--list-generations=2..} devuelve todas las generaciones empezando por +la segunda. + +@item @emph{Duraciones}. Puede también obtener los últimos @emph{N}@tie{}días, semanas, +o meses pasando un entero junto a la primera letra de la duración. Por +ejemplo, @code{--list-generations=20d} enumera las generaciones que tienen +hasta 20 días de antigüedad. +@end itemize + +@item --delete-generations[=@var{patrón}] +@itemx -d [@var{patrón}] +Cuando se omite @var{patrón}, borra todas las generaciones excepto la +actual. + +Esta orden acepta los mismos patrones que +@option{--list-generations}. Cuando se especifica un @var{patrón}, borra las +generaciones coincidentes. Cuando el @var{patrón} especifica una duración, +las generaciones @emph{más antiguas} que la duración especificada son las +borradas. Por ejemplo, @code{--delete-generations=1m} borra las generaciones +de más de un mes de antigüedad. + +Si la generación actual entra en el patrón, @emph{no} es borrada. Tampoco la +generación cero es borrada nunca. + +Fíjese que borrar generaciones previene volver atrás a +ellas. Consecuentemente esta orden debe ser usada con cuidado. + +@end table + +Finalmente, ya que @command{guix package} puede lanzar procesos de +construcción en realidad, acepta todas las opciones comunes de construcción +(@pxref{Opciones comunes de construcción}). También acepta opciones de transformación de +paquetes, como @option{--with-source} (@pxref{Opciones de transformación de paquetes}). No obstante, fíjese que las transformaciones del paquete se +pierden al actualizar; para preservar las transformaciones entre +actualizaciones, debe definir su propia variante del paquete en un módulo +Guile y añadirlo a @code{GUIX_PACKAGE_PATH} (@pxref{Definición de paquetes}). + +@node Sustituciones +@section Sustituciones + +@cindex sustituciones +@cindex binarios pre-construidos +Guix permite despliegues transparentes de fuentes/binarios, lo que significa +que puede tanto construir cosas localmente, como descargar elementos +preconstruidos de un servidor, o ambas. Llamamos a esos elementos +preconstruidos @dfn{sustituciones}---son sustituciones de los resultados de +construcciones locales. En muchos casos, descargar una sustitución es mucho +más rápido que construirla localmente. + +Las sustituciones pueden ser cualquier cosa que resulte de una construcción +de una derivación (@pxref{Derivaciones}). Por supuesto, en el caso común, son +paquetes binarios preconstruidos, pero los archivos de fuentes, por ejemplo, +que también resultan de construcciones de derivaciones, pueden estar +disponibles como sustituciones. + +@menu +* Servidor oficial de sustituciones.:: Una fuente particular de + sustituciones. +* Autorización de servidores de sustituciones:: Cómo habilitar o + deshabilitar + sustituciones. +* Verificación de sustituciones:: Cómo verifica las sustituciones Guix. +* Configuración de la pasarela.:: Cómo obtener sustituciones a través de + una pasarela. +* Fallos en las sustituciones:: Qué pasa cuando una sustitución falla. +* Sobre la confianza en binarios:: ¿Cómo puede usted confiar en esa masa + informe de datos binarios? +@end menu + +@node Servidor oficial de sustituciones. +@subsection Servidor oficial de sustituciones. + +@cindex hydra +@cindex granja de construcción +El servidor @code{@value{SUBSTITUTE-SERVER}} es una fachada a una granja de +construcción oficial que construye paquetes de Guix continuamente para +algunas arquitecturas, y los pone disponibles como sustituciones. Esta es la +fuente predeterminada de sustituciones; puede ser forzada a cambiar pasando +la opción @option{--substitute-urls} bien a @command{guix-daemon} +(@pxref{daemon-substitute-urls,, @code{guix-daemon --substitute-urls}}) o +bien a herramientas cliente como @command{guix package} +(@pxref{client-substitute-urls,, client @option{--substitute-urls} option}). + +Las URLs de sustituciones pueden ser tanto HTTP como HTTPS. Se recomienda +HTTPS porque las comunicaciones están cifradas; de modo contrario, usar HTTP +hace visibles todas las comunicaciones para alguien que las intercepte, +quien puede usar la información obtenida para determinar, por ejemplo, si su +sistema tiene vulnerabilidades de seguridad sin parchear. + +Las sustituciones de la granja de construcción oficial están habilitadas por +defecto cuando se usa la Distribución de sistema Guix (@pxref{Distribución GNU}). No obstante, están deshabilitadas por defecto cuando se usa +Guix en una distribución anfitriona, a menos que las haya habilitado +explícitamente via uno de los pasos recomendados de instalación +(@pxref{Instalación}). Los siguientes párrafos describen como habilitar o +deshabilitar sustituciones para la granja oficial de construcción; el mismo +procedimiento puede usarse para habilitar sustituciones de cualquier otro +servidor que las proporcione. + +@node Autorización de servidores de sustituciones +@subsection Autorización de servidores de sustituciones + +@cindex seguridad +@cindex sustituciones, autorización de las mismas +@cindex listas de control de acceso (ACL), para sustituciones +@cindex ACL (listas de control de acceso), para sustituciones +Para permitir a Guix descargar sustituciones de +@code{@value{SUBSTITUTE-SERVER}} o un espejo suyo, debe añadir su clave +pública a la lista de control de acceso (ACL) de las importaciones de +archivos, mediante el uso de la orden @command{guix archive} +(@pxref{Invocación de guix archive}). Hacerlo implica que confía que +@code{@value{SUBSTITUTE-SERVER}} no ha sido comprometido y proporciona +sustituciones genuinas. + +La clave pública para @code{@value{SUBSTITUTE-SERVER}} se instala junto a +Guix, en @code{@var{prefijo}/share/guix/@value{SUBSTITUTE-SERVER}.pub}, +donde @var{prefijo} es el prefij de instalación de Guix. Si ha instalado +Guix desde las fuentes, debe asegurarse de que comprobó la firma GPG de +@file{guix-@value{VERSION}.tar.gz}, el cual contiene el fichero de clave +pública. Una vez hecho, puede ejecutar algo así: + +@example +# guix archive --authorize < @var{prefijo}/share/guix/@value{SUBSTITUTE-SERVER}.pub +@end example + +@quotation Nota +De manera similar, el fichero @file{hydra.gnu.org.pub} contiene la clave +pública para una granja de construcción independiente que también es parte +del proyecto, la cual se puede encontrar en +@indicateurl{https://mirror.hydra.gnu.org}. +@end quotation + +Una vez esté autorizada, la salida de una orden como @code{guix build} +debería cambiar de algo como: + +@example +$ guix build emacs --dry-run +The following derivations would be built: + /gnu/store/yr7bnx8xwcayd6j95r2clmkdl1qh688w-emacs-24.3.drv + /gnu/store/x8qsh1hlhgjx6cwsjyvybnfv2i37z23w-dbus-1.6.4.tar.gz.drv + /gnu/store/1ixwp12fl950d15h2cj11c73733jay0z-alsa-lib-1.0.27.1.tar.bz2.drv + /gnu/store/nlma1pw0p603fpfiqy7kn4zm105r5dmw-util-linux-2.21.drv +@dots{} +@end example + +@noindent +a algo así: + +@example +$ guix build emacs --dry-run +112.3 MB would be downloaded: + /gnu/store/pk3n22lbq6ydamyymqkkz7i69wiwjiwi-emacs-24.3 + /gnu/store/2ygn4ncnhrpr61rssa6z0d9x22si0va3-libjpeg-8d + /gnu/store/71yz6lgx4dazma9dwn2mcjxaah9w77jq-cairo-1.12.16 + /gnu/store/7zdhgp0n1518lvfn8mb96sxqfmvqrl7v-libxrender-0.9.7 +@dots{} +@end example + +@noindent +Esto indica que las sustituciones de @code{@value{SUBSTITUTE-SERVER}} son +usables y serán descargadas, cuando sea posible, para construcciones +futuras. + +@cindex sustituciones, cómo deshabilitarlas +El mecanismo de sustituciones puede ser deshabilitado globalmente ejecutando +@code{guix-daemon} con @code{--no-subsitutes} (@pxref{Invocación de guix-daemon}). También puede ser deshabilitado temporalmente pasando la +opción @code{--no-substitutes} a @command{guix package}, @command{guix +build} y otras herramientas de línea de órdenes. + +@node Verificación de sustituciones +@subsection Verificación de sustituciones + +@cindex firmas digitales +Guix detecta y emite errores cuando se intenta usar una sustitución que ha +sido adulterado. Del mismo modo, ignora las sustituciones que no están +firmadas, o que no están firmadas por una de las firmas enumeradas en la +ACL. + +No obstante hay una excepción: si un servidor no autorizado proporciona +sustituciones que son @emph{idénticas bit-a-bit} a aquellas proporcionadas +por un servidor autorizado, entonces el servidor no autorizado puede ser +usado para descargas. Por ejemplo, asumiendo que hemos seleccionado dos +servidores de sustituciones con esta opción: + +@example +--substitute-urls="https://a.example.org https://b.example.org" +@end example + +@noindent +@cindex construcciones reproducibles +Si la ACL contiene únicamente la clave para @code{b.example.org}, y si +@code{a.example.org} resulta que proporciona @emph{exactamente las mismas} +sustituciones, Guix descargará sustituciones de @code{a.example.org} porque +viene primero en la lista y puede ser considerado un espejo de +@code{b.example.org}. En la práctica, máquinas de construcción +independientes producen habitualmente los mismos binarios, gracias a las +construcciones reproducibles bit-a-bit (véase a continuación). + +Cuando se usa HTTPS, el certificado X.509 del servidor @emph{no} se valida +(en otras palabras, el servidor no está verificado), lo contrario del +comportamiento habitual de los navegadores Web. Esto es debido a que Guix +verifica la información misma de las sustituciones, como se ha explicado +anteriormente, lo cual nos concierne (mientras que los certificados X.509 +tratan de verificar las conexiones entre nombres de dominio y claves +públicas). + +@node Configuración de la pasarela. +@subsection Configuración de la pasarela. + +@vindex http_proxy +Las sustituciones se descargan por HTTP o HTTPS. La variable de entorno +@code{http_proxy} puede ser incluida en el entorno de @command{guix-daemon} +y la respeta para las descargas de sustituciones. Fíjese que el valor de +@code{http_proxy} en el entorno en que @command{guix build}, @command{guix +package} y otras aplicaciones cliente se ejecuten @emph{no tiene ningún +efecto}. + +@node Fallos en las sustituciones +@subsection Fallos en las sustituciones + +Incluso cuando una sustitución de una derivación está disponible, a veces el +intento de sustitución puede fallar. Esto puede suceder por varias razones: +el servidor de sustituciones puede estar desconectado, la sustitución puede +haber sido borrada, la conexión puede interrumpirse, etc. + +Cuando las sustituciones están activadas y una sustitución para una +derivación está disponible, pero el intento de sustitución falla, Guix +intentará construir la derivación localmente dependiendo si se proporcionó +la opción @code{--fallback} (@pxref{fallback-option,, common build option +@code{--fallback}}). Específicamente, si no se pasó @code{--fallback}, no se +realizarán construcciones locales, y la derivación se considera se considera +fallida. No obstante, si se pasó @code{--fallback}, Guix intentará construir +la derivación localmente, y el éxito o fracaso de la derivación depende del +éxito o fracaso de la construcción local. Fíjese que cuando las +sustituciones están deshabilitadas o no hay sustituciones disponibles para +la derivación en cuestión, la construcción local se realizará +@emph{siempre}, independientemente de si se pasó la opción +@code{--fallback}. + +Para hacerse una idea de cuantas sustituciones hay disponibles en este +momento, puede intentar ejecutar la orden @command{guix weather} +(@pxref{Invocación de guix weather}). Esta orden proporciona estadísticas de las +sustituciones proporcionadas por un servidor. + +@node Sobre la confianza en binarios +@subsection Sobre la confianza en binarios + +@cindex confianza, de binarios pre-construidos +Hoy en día, el control individual sobre nuestra propia computación está a +merced de instituciones, empresas y grupos con suficiente poder y +determinación para subvertir la infraestructura de computación y explotar +sus vulnerabilidades. Mientras que usar las sustituciones de +@code{@value{SUBSTITUTE-SERVER}} puede ser conveniente, recomendamos a las +usuarias también construir sus paquetes, o incluso mantener su propia granja +de construcción, de modo que @code{@value{SUBSTITUTE-SERVER}} sea un +objetivo menos interesante. Una manera de ayudar es publicando el software +que construya usando @command{guix publish} de modo que otras tengan otro +servidor más como opción para descargar sustituciones (@pxref{Invocación de guix publish}). + +Guix tiene los cimientos para maximizar la reproducibilidad de las +construcciones (@pxref{Características}). En la mayor parte de los casos, +construcciones independientes de un paquete o derivación dada deben emitir +resultados idénticos bit a bit. Por tanto, a través de un conjunto diverso +de construcciones independientes de paquetes, podemos reforzar la integridad +de nuestros sistemas. La orden @command{guix challenge} intenta ayudar a las +usuarias en comprobar servidores de sustituciones, y asiste a las +desarrolladoras encontrando construcciones no deterministas de paquetes +(@pxref{Invocación de guix challenge}). Similarmente, la opción @option{--check} +de @command{guix build} permite a las usuarias si las sustituciones +previamente instaladas son genuinas reconstruyendolas localmente +(@pxref{build-check, @command{guix build --check}}). + +En el futuro, queremos que Guix permita la publicación y obtención de +binarios hacia/desde otras usuarias, entre pares (P2P). En caso de +interesarle hablar sobre este proyecto, unase a nosotras en +@email{guix-devel@@gnu.org}. + +@node Paquetes con múltiples salidas +@section Paquetes con múltiples salidas + +@cindex paquetes de salida múltiple +@cindex salidas del paquete +@cindex salidas + +Habitualmente, los paquetes definidos en Guix tienen una @dfn{salida} +única---es decir, el paquete de fuentes proporcionará exactamente un +directorio en el almacén. Cuando se ejecuta @command{guix package -i glibc}, +se instala la salida predeterminada del paquete GNU libc; la salida +predeterminada se llama @code{out}, pero su nombre puede omitirse como se +mostró en esta orden. En este caso particular, la salida predeterminada de +@code{glibc} contiene todos ficheros de cabecera C, bibliotecas dinámicas, +bibliotecas estáticas, documentación Info y otros ficheros auxiliares. + +A veces es más apropiado separar varios tipos de ficheros producidos por un +paquete único de fuentes en salidas separadas. Por ejemplo, la biblioteca C +GLib (usada por GTK+ y paquetes relacionados) instala más de 20 MiB de +documentación de referencia como páginas HTML. Para ahorrar espacio para +usuarias que no la necesiten, la documentación va a una salida separada, +llamada @code{doc}. Para instalar la salida principal de GLib, que contiene +todo menos la documentación, se debe ejecutar: + +@example +guix package -i glib +@end example + +@cindex documentación +La orden que instala su documentación es: + +@example +guix package -i glib:doc +@end example + +Algunos paquetes instalan programas con diferentes ``huellas de +dependencias''. Por ejemplo, el paquete WordNet instala tanto herramientas +de línea de órdenes como interfaces gráficas de usuaria (IGU). Las primeras +dependen únicamente de la biblioteca de C, mientras que las últimas dependen +en Tcl/Tk y las bibliotecas de X subyacentes. En este caso, dejamos las +herramientas de línea de órdenes en la salida predeterminada, mientras que +las IGU están en una salida separada. Esto permite a las usuarias que no +necesitan una IGU ahorrar espacio. La orden @command{guix size} puede ayudar +a exponer estas situaciones (@pxref{Invocación de guix size}). @command{guix +graph} también puede ser útil (@pxref{Invocación de guix graph}). + +Hay varios de estos paquetes con salida múltiple en la distribución +GNU. Otros nombres de salida convencionales incluyen @code{lib} para +bibliotecas y posiblemente ficheros de cabecera, @code{bin} para programas +independientes y @code{debug} para información de depuración +(@pxref{Instalación de ficheros de depuración}). La salida de los paquetes se enumera +en la tercera columna del resultado de @command{guix package +--list-available} (@pxref{Invocación de guix package}). + + +@node Invocación de guix gc +@section Invocación de @command{guix gc} + +@cindex recolector de basura +@cindex espacio en disco +Los paquetes instalados, pero no usados, pueden ser @dfn{recolectados}. La +orden @command{guix gc} permite a las usuarias ejecutar explícitamente el +recolector de basura para reclamar espacio del directorio +@file{/gnu/store}---¡borrar ficheros o directorios manualmente puede dañar +el almacén sin reparación posible! + +@cindex GC, raíces del recolector de basura +@cindex raíces del recolector de basura +El recolector de basura tiene un conjunto de @dfn{raíces} conocidas: +cualquier fichero en @file{/gnu/store} alcanzable desde una raíz se +considera @dfn{vivo} y no puede ser borrado; cualquier otro fichero se +considera @dfn{muerto} y puede ser borrado. El conjunto de raíces del +recolector de basura (``raíces del GC'' para abreviar) incluye los perfiles +predeterminados de las usuarias; por defecto los enlaces bajo +@file{/var/guix/gcroots} representan dichas raíces. Por ejemplo, nuevas +raíces del GC pueden añadirse con @command{guix build --root} +(@pxref{Invocación de guix build}). La orden @command{guix gc --list-roots} las +enumera. + +Antes de ejecutar @code{guix gc --collect-garbage} para liberar espacio, +habitualmente es útil borrar generaciones antiguas de los perfiles de +usuaria; de ese modo, las construcciones antiguas de paquetes referenciadas +por dichas generaciones puede ser reclamada. Esto se consigue ejecutando +@code{guix package --delete-generations} (@pxref{Invocación de guix package}). + +Nuestra recomendación es ejecutar una recolección de basura periódicamente, +o cuando tenga poco espacio en el disco. Por ejemplo, para garantizar que al +menos 5@tie{}GB están disponibles en su disco, simplemente ejecute: + +@example +guix gc -F 5G +@end example + +Es completamente seguro ejecutarla como un trabajo periódico no-interactivo +(@pxref{Ejecución de tareas programadas}, para la configuración de un trabajo de ese +tipo). La ejecución de @command{guix gc} sin ningún parámetro recolectará +tanta basura como se pueda, pero eso es no es normalmente conveniente: puede +encontrarse teniendo que reconstruir o volviendo a bajar software que está +``muerto'' desde el punto de vista del recolector pero que es necesario para +construir otras piezas de software---por ejemplo, la cadena de herramientas +de compilación. + +La orden @command{guix gc} tiene tres modos de operación: puede ser usada +para recolectar ficheros muertos (predeterminado), para borrar ficheros +específicos (la opción @code{--delete}), para mostrar información sobre la +recolección de basura o para consultas más avanzadas. Las opciones de +recolección de basura son las siguientes: + +@table @code +@item --collect-garbage[=@var{min}] +@itemx -C [@var{min}] +Recolecta basura---es decir, ficheros no alcanzables de @file{/gnu/store} y +subdirectorios. Esta operación es la predeterminada cuando no se especifican +opciones. + +Cuando se proporciona @var{min}, para una vez que @var{min} bytes han sido +recolectados. @var{min} puede ser un número de bytes, o puede incluir una +unidad como sufijo, como @code{MiB} para mebibytes y @code{GB} para +gigabytes (@pxref{Block size, size specifications,, coreutils, GNU +Coreutils}). + +Cuando se omite @var{min}, recolecta toda la basura. + +@item --free-space=@var{libre} +@itemx -F @var{libre} +Recolecta basura hasta que haya espacio @var{libre} bajo @file{/gnu/store}, +si es posible: @var{libre} denota espacio de almacenamiento, por ejemplo +@code{500MiB}, como se ha descrito previamente. + +Cuando @var{libre} o más está ya disponible en @file{/gnu/store}, no hace +nada y sale inmediatamente. + +@item --delete-generations[=@var{duración}] +@itemx -d [@var{duración}] +Antes de comenzar el proceso de recolección de basura, borra todas las +generaciones anteriores a @var{duración}, para todos los perfiles de la +usuaria; cuando se ejecuta como root esto aplica a los perfiles de +@emph{todas las usuarias}. + +Por ejemplo, esta orden borra todas las generaciones de todos sus perfiles +que tengan más de 2 meses de antigüedad (excepto generaciones que sean las +actuales), y una vez hecho procede a liberar espacio hasta que al menos 10 +GiB estén disponibles: + +@example +guix gc -d 2m -F 10G +@end example + +@item --delete +@itemx -D +Intenta borrar todos los ficheros del almacén y directorios especificados +como parámetros. Esto falla si alguno de los ficheros no están en el +almacén, o todavía están vivos. + +@item --list-failures +Enumera los elementos del almacén correspondientes a construcciones fallidas +existentes en la caché. + +Esto no muestra nada a menos que el daemon se haya ejecutado pasando +@option{--cache-failures} (@pxref{Invocación de guix-daemon, +@option{--cache-failures}}). + +@item --list-roots +Enumera las raices del recolector de basura poseidas por la usuaria; cuando +se ejecuta como root, enumera @emph{todas} las raices del recolector de +basura. + +@item --clear-failures +Borra los elementos especificados del almacén de la caché de construcciones +fallidas. + +De nuevo, esta opción únicamente tiene sentido cuando el daemon se inicia +con @option{--cache-failures}. De otro modo, no hace nada. + +@item --list-dead +Muestra la lista de ficheros y directorios muertos todavía presentes en el +almacén---es decir, ficheros y directorios que ya no se pueden alcanzar +desde ninguna raíz. + +@item --list-live +Muestra la lista de ficheros y directorios del almacén vivos. + +@end table + +Además, las referencias entre los ficheros del almacén pueden ser +consultadas: + +@table @code + +@item --references +@itemx --referrers +@cindex dependencias de un paquete +Enumera las referencias (o, respectivamente, los referentes) de los ficheros +del almacén pasados como parámetros. + +@item --requisites +@itemx -R +@cindex clausura +Enumera los requistos los ficheros del almacén pasados como parámetros. Los +requisitos incluyen los mismos ficheros del almacén, sus referencias, las +referencias de estas, recursivamente. En otras palabras, la lista devuelta +es la @dfn{clausura transitiva} de los ficheros del almacén. + +@xref{Invocación de guix size}, para una herramienta que perfila el tamaño de la +clausura de un elemento. @xref{Invocación de guix graph}, para una herramienta de +visualización del grafo de referencias. + +@item --derivers +@cindex derivación +Devuelve la/s derivación/es que conducen a los elementos del almacén dados +(@pxref{Derivaciones}). + +Por ejemplo, esta orden: + +@example +guix gc --derivers `guix package -I ^emacs$ | cut -f4` +@end example + +@noindent +devuelve el/los fichero/s @file{.drv} que conducen al paquete @code{emacs} +instalado en su perfil. + +Fíjese que puede haber cero ficheros @file{.drv} encontrados, por ejemplo +porque estos ficheros han sido recolectados. Puede haber más de un fichero +@file{.drv} encontrado debido a derivaciones de salida fija. +@end table + +Por último, las siguientes opciones le permiten comprobar la integridad del +almacén y controlar el uso del disco. + +@table @option + +@item --verify[=@var{opciones}] +@cindex integridad, del almacén +@cindex comprobación de integridad +Verifica la integridad del almacén. + +Por defecto, comprueba que todos los elementos del almacén marcados como +válidos en la base de datos del daemon realmente existen en +@file{/gnu/store}. + +Cuando se proporcionan, @var{opciones} debe ser una lista separada por comas +que contenga uno o más valores @code{contents} and @code{repair}. + +Cuando se usa @option{--verify=contents}, el daemon calcula el hash del +contenido de cada elemento del almacén y lo compara contra el hash de su +base de datos. Las incongruencias se muestran como corrupciones de +datos. Debido a que recorre @emph{todos los ficheros del almacén}, esta +orden puede tomar mucho tiempo, especialmente en sistemas con una unidad de +disco lenta. + +@cindex reparar el almacén +@cindex corrupción, recuperarse de +El uso de @option{--verify=repair} o @option{--verify=contents,repair} hace +que el daemon intente reparar elementos corruptos del almacén obteniendo +sustituciones para dichos elementos (@pxref{Sustituciones}). Debido a que la +reparación no es atómica, y por tanto potencialmente peligrosa, está +disponible únicamente a la administradora del sistema. Una alternativa +ligera, cuando sabe exactamente qué elementos del almacén están corruptos, +es @command{guix build --repair} (@pxref{Invocación de guix build}). + +@item --optimize +@cindex deduplicación +Optimiza el almacén sustituyendo ficheros idénticos por enlaces duros---esto +es la @dfn{deduplicación}. + +El daemon realiza la deduplicación después de cada construcción +satisfactoria o importación de archivos, a menos que se iniciase con +@code{--disable-deduplication} (@pxref{Invocación de guix-daemon, +@code{--disable-deduplication}}). Por tanto, esta opción es útil +primariamente cuando el daemon se estaba ejecutando con +@code{--disable-deduplication}. + +@end table + +@node Invocación de guix pull +@section Invocación de @command{guix pull} + +@cindex actualizar Guix +@cindex actualizar la versión de Guix +@cindex @command{guix pull} +@cindex pull +Los paquetes se instalan o actualizan con la última versión disponible en la +distribución disponible actualmente en su máquina local. Para actualizar +dicha distribución, junto a las herramientas de Guix, debe ejecutar +@command{guix pull}: esta orden descarga el último código fuente de Guix y +descripciones de paquetes, y lo despliega. El código fuente se descarga de +un repositorio @uref{https://git-scm.com, Git}, por defecto el repositorio +oficial de GNU@tie{}Guix, lo que no obstante puede ser personalizado. + +Una vez completada, @command{guix package} usará paquetes y versiones de +paquetes de esta copia recién obtenida de Guix. No solo eso, sino que todas +las órdenes de Guix y los módulos Scheme también se tomarán de la última +versión. Nuevas sub-órdenes @command{guix} incorporadas por la actualización +también estarán disponibles. + +Cualquier usuaria puede actualizar su copia de Guix usando @command{guix +pull}, y el efecto está limitado a la usuaria que ejecutó @command{guix +pull}. Por ejemplo, cuando la usuaria @code{root} ejecuta @command{guix +pull}, esto no tiene ningún efecto en la versión del Guix que la usuaria +@code{alicia} ve, y viceversa. + +El resultado de ejecutar @command{guix pull} es un @dfn{perfil} disponible +bajo @file{~/.config/guix/current} conteniendo el último Guix. Por tanto, +asegurese de añadirlo al inicio de sus rutas de búsqueda de modo que use la +última versión, de modo similar para el manual Info(@pxref{Documentación}). + +@example +export PATH="$HOME/.config/guix/current/bin:$PATH" +export INFOPATH="$HOME/.config/guix/current/share/info:$INFOPATH" +@end example + +Las opciones @code{--list-generations} o @code{-l} enumeran las generaciones +pasadas producidas por @command{guix pull}, junto a detalles de su +procedencia: + +@example +$ guix pull -l +Generation 1 Jun 10 2018 00:18:18 + guix 65956ad + repository URL: https://git.savannah.gnu.org/git/guix.git + branch: origin/master + commit: 65956ad3526ba09e1f7a40722c96c6ef7c0936fe + +Generation 2 Jun 11 2018 11:02:49 + guix e0cc7f6 + repository URL: https://git.savannah.gnu.org/git/guix.git + branch: origin/master + commit: e0cc7f669bec22c37481dd03a7941c7d11a64f1d + 2 new packages: keepalived, libnfnetlink + 6 packages upgraded: emacs-nix-mode@@2.0.4, + guile2.0-guix@@0.14.0-12.77a1aac, guix@@0.14.0-12.77a1aac, + heimdal@@7.5.0, milkytracker@@1.02.00, nix@@2.0.4 + +Generation 3 Jun 13 2018 23:31:07 (current) + guix 844cc1c + repository URL: https://git.savannah.gnu.org/git/guix.git + branch: origin/master + commit: 844cc1c8f394f03b404c5bb3aee086922373490c + 28 new packages: emacs-helm-ls-git, emacs-helm-mu, @dots{} + 69 packages upgraded: borg@@1.1.6, cheese@@3.28.0, @dots{} +@end example + +@ref{Invocación de guix describe, @command{guix describe}}, para otras formas de +describir el estado actual de Guix. + +El perfil @code{~/.config/guix/current} funciona como cualquier otro perfil +creado por @command{guix package} (@pxref{Invocación de guix package}). Esto es, +puede enumerar generaciones, volver a una generación previa---es decir, el +Guix anterior---y más: + +@example +$ guix package -p ~/.config/guix/current --roll-back +switched from generation 3 to 2 +$ guix package -p ~/.config/guix/current --delete-generations=1 +deleting /var/guix/profiles/per-user/carlos/current-guix-1-link +@end example + +La orden @command{guix pull} se invoca habitualmente sin parámetros, pero +permite las siguientes opciones: + +@table @code +@item --url=@var{url} +@itemx --commit=@var{revisión} +@itemx --branch=@var{rama} +Download code for the @code{guix} channel from the specified @var{url}, at +the given @var{commit} (a valid Git commit ID represented as a hexadecimal +string), or @var{branch}. + +@cindex @file{channels.scm}, fichero de configuración +@cindex fichero de configuración de canales +Estas opciones se proporcionan por conveniencia, pero también puede +especificar su configuración en el fichero +@file{~/.config/guix/channels.scm} o usando la opción @option{--channels} +(vea más adelante). + +@item --channels=@var{fichero} +@itemx -C @var{fichero} +Lee la lista de canales de @var{fichero} en vez de +@file{~/.config/guix/channels.scm}. @var{fichero} debe contener código +Scheme que evalue a una lista de objetos channel. @xref{Canales}, para más +información. + +@item --news +@itemx -N +Display the list of packages added or upgraded since the previous +generation. + +This is the same information as displayed upon @command{guix pull} +completion, but without ellipses; it is also similar to the output of +@command{guix pull -l} for the last generation (see below). + +@item --list-generations[=@var{patrón}] +@itemx -l [@var{patrón}] +Enumera todas las generaciones de @file{~/.config/guix/current} o, si se +proporciona un @var{patrón}, el subconjunto de generaciones que correspondan +con el @var{patrón}. La sintaxis de @var{patrón} es la misma que @code{guix +package --list-generations} (@pxref{Invocación de guix package}). + +@ref{Invocación de guix describe}, para una forma de mostrar información sobre +únicamente la generación actual. + +@item --profile=@var{perfil} +@itemx -p @var{perfil} +Usa @var{perfil} en vez de @file{~/.config/guix/current}. + +@item --dry-run +@itemx -n +Muestra qué revisión/es del canal serían usadas y qué se construiría o +sustituiría, sin efectuar ninguna acción real. + +@item --system=@var{sistema} +@itemx -s @var{sistema} +Intenta construir paquetes para @var{sistema}---por ejemplo, +@code{x86_64-linux}---en vez del tipo de sistema de la máquina de +construcción. + +@item --verbose +Produce salida prolija, escribiendo los logs de construcción por la salida +de error estándar. + +@item --bootstrap +Use el Guile usado para el lanzamiento para construir el último Guix. Esta +opción es útil para las desarrolladoras de Guix únicamente. +@end table + +El mecanismo de @dfn{canales} le permite instruir a @command{guix pull} de +qué repositorio y rama obtener los datos, así como repositorios +@emph{adicionales} que contengan módulos de paquetes que deben ser +desplegados. @xref{Canales}, para más información. + +Además, @command{guix pull} acepta todas las opciones de construcción +comunes (@pxref{Opciones comunes de construcción}). + +@node Canales +@section Canales + +@cindex channels +@cindex @file{channels.scm}, fichero de configuración +@cindex fichero de configuración de canales +@cindex @command{guix pull}, fichero de configuración +@cindex configuración de @command{guix pull} +Guix y su colección de paquetes son actualizados ejecutando @command{guix +pull} (@pxref{Invocación de guix pull}). Por defecto @command{guix pull} descarga +y despliega el mismo Guix del repositorio oficial de GNU@tie{}Guix. Esto +puede ser personalizado definiendo @dfn{canales} en el fichero +@file{~/.config/guix/channels.scm}. Un canal especifica una URL y una rama +de un repositorio Git para ser desplegado, y @command{guix pull} puede ser +instruido para tomar los datos de uno o más canales. En otras palabras, los +canales se pueden usar para @emph{personalizar} y para @emph{extender} Guix, +como vemos a continuación. + +@subsection Uso de un canal de Guix personalizado + +El canal llamado @code{guix} especifica de donde el mismo Guix---sus +herramientas de línea de órdenes y su colección de paquetes---debe ser +descargado. Por ejemplo, suponga que quiere actualizar de su propia copia +del repositorio Guix en @code{example.org}, y específicamente la rama +@code{super-hacks}, para ello puede escribir en +@code{~/.config/guix/channels.scm} esta especificación: + +@lisp +;; Le dice a 'guix pull' que use mi propio repositorio. +(list (channel + (name 'guix) + (url "https://example.org/mi-guix.git") + (branch "super-hacks"))) +@end lisp + +@noindent +De aquí en adelante, @command{guix pull} obtendrá el código de la rama +@code{super-hacks} del repositorio en @code{example.org}. + +@subsection Especificación de canales adicionales + +@cindex extender la colección de paquetes (canales) +@cindex paquetes personales (canales) +@cindex canales, para paquetes personales +También puede especificar @emph{canales adicionales} de los que obtener +datos. Digamos que tiene un montón de variaciones personalizadas de paquetes +que piensa que no tiene mucho sentido contribuir al proyecto Guix, pero +quiere tener esos paquetes disponibles transparentemente en su línea de +órdenes. Primero escribiría módulos que contengan esas definiciones de +paquete (@pxref{Módulos de paquetes}), los mantendría en un repositorio Git, y +entonces usted y cualquier otra persona podría usarlos como un canal +adicional del que obtener paquetes. Limpio, ¿no? + +@c What follows stems from discussions at +@c <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=22629#134> as well as +@c earlier discussions on guix-devel@gnu.org. +@quotation Aviso +Antes de que, querida usuaria, grite---``¡Guau, esto es @emph{la +caña}!''---y publique su canal personal al mundo, nos gustaría compartir +algunas palabras de precaución: + +@itemize +@item +Antes de publicar un canal, por favor considere contribuir sus definiciones +de paquete al propio Guix (@pxref{Contribuir}). Guix como proyecto es +abierto a software libre de todo tipo, y los paquetes en el propio Guix +están disponibles para todas las usuarias de Guix y se benefician del +proceso de gestión de calidad del proyecto. + +@item +Cuando mantiene definiciones de paquete fuera de Guix, nosotras, las +desarrolladoras de Guix, consideramos que @emph{la carga de la +compatibilidad cae de su lado}. Recuerde que los módulos y definiciones de +paquetes son solo código Scheme que usa varias interfaces programáticas +(APIs). Queremos mantener la libertad de cambiar dichas interfaces para +seguir mejorando Guix, posiblemente en formas que pueden romper su +canal. Nunca cambiamos las interfaces gratuitamente, pero @emph{no} vamos +tampoco a congelar las interfaces. + +@item +Corolario: si está usando un canal externo y el canal se rompe, por favor +@emph{informe del problema a las autoras del canal}, no al proyecto Guix. +@end itemize + +¡Ha quedado advertida! Habiendo dicho esto, creemos que los canales externos +son una forma práctica de ejercitar su libertad para aumentar la colección +de paquetes de Guix y compartir su mejoras, que son pilares básicos del +@uref{https://www.gnu.org/philosophy/free-sw.html, software libre}. Por +favor, envíenos un correo a @email{guix-devel@@gnu.org} si quiere hablar +sobre esto. +@end quotation + +Para usar un canal, escriba en @code{~/.config/guix/channels.scm} para +instruir a @command{guix pull} para obtener datos de él @emph{además} de los +canales Guix predeterminados: + +@vindex %default-channels +@lisp +;; Añade mis paquetes personales a aquellos que Guix provee. +(cons (channel + (name 'mis-paquetes-personales) + (url "https://example.org/paquetes-personales.git")) + %default-channels) +@end lisp + +@noindent +Fíjese que el fragmento previo es (¡como siempre!)@: código Scheme; usamos +@code{cons} para añadir un canal a la lista de canales a la que la variable +@code{%default-channels} hace referencia (@pxref{Pairs, @code{cons} and +lists,, guile, GNU Guile Reference Manual}). Con el fichero en este lugar, +@command{guix pull} no solo construye Guix sino también los módulos de +paquetes de su propio repositorio. El resultado en +@file{~/.config/guix/current} es la unión de Guix con sus propios módulos de +paquetes: + +@example +$ guix pull --list-generations +@dots{} +Generation 19 Aug 27 2018 16:20:48 + guix d894ab8 + repository URL: https://git.savannah.gnu.org/git/guix.git + branch: master + commit: d894ab8e9bfabcefa6c49d9ba2e834dd5a73a300 + mis-paquetes-personales dd3df5e + repository URL: https://example.org/paquetes-personales.git + branch: master + commit: dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb + 11 new packages: mi-gimp, mi-emacs-con-cosas, @dots{} + 4 packages upgraded: emacs-racket-mode@@0.0.2-2.1b78827, @dots{} +@end example + +@noindent +La salida de @command{guix pull} previa muestra que la generación@tie{}19 +incluye tanto Guix como paquetes del canal +@code{mis-paquetes-personales}. Entre los paquetes nuevos y actualizados que +son enumerados, algunos como @code{mi-gimp} y @code{mi-emacs-con-cosas} +pueden venir de @code{mis-paquetes-personales}, mientras que otros vienen +del canal predeterminado de Guix. + +Para crear uncanal, cree un repositorio Git que contenga sus propios módulos +de paquetes y haga que esté disponible. El repositorio puede contener +cualquier cosa, pero un canal útil contendrá módulos Guile que exportan +paquetes. Una vez comience a usar un canal, Guix se comportará como si el +directorio raíz del repositorio Git de dicho canal hubiese sido añadido a la +ruta de carga de Guile (@pxref{Load Paths,,, guile, GNU Guile Reference +Manual}). Por ejemplo, si su canal contiene un fichero en +@file{mis-paquetes/mis-herramientas.scm} que define un módulo, entonces +dicho módulo estará disponible bajo el nombre @code{(mis-paquetes +mis-herramientas)}, y podrá usarlo como cualquier otro módulo +(@pxref{Módulos,,, guile, GNU Guile Reference Manual}). + +@cindex dependencias, canales +@cindex metadatos, canales +@subsection Declaración de dependencias de canales + +Las autoras de canales pueden decidir aumentar una colección de paquetes +proporcionada por otros canales. Pueden declarar su canal como dependiente +de otros canales en el fichero de metadatos @file{.guix-channel}, que debe +encontrarse en la raíz del repositorio del canal. + +Este fichero de metadatos debe contener una expresión-S simple como esta: + +@lisp +(channel + (version 0) + (dependencies + (channel + (name una-coleccion) + (url "https://example.org/primera-coleccion.git")) + (channel + (name otra-coleccion) + (url "https://example.org/segunda-coleccion.git") + (branch "pruebas")))) +@end lisp + +En el ejemplo previo, este canal se declara como dependiente de otros dos +canales, que se obtendrán de manera automática. Los módulos proporcionados +por el canal se compilarán en un entorno donde los módulos de todos estos +canales declarados estén disponibles. + +De cara a la confianza proporcionada y el esfuerzo que supondrá su +mantenimiento, debería evitar depender de canales que no controle, y debería +intentar minimizar el número de dependencias. + +@subsection Replicación de Guix + +@cindex clavar, canales +@cindex replicar Guix +@cindex reproducibilidad, de Guix +La salida de @command{guix pull --list-generations} previa muestra +precisamente qué revisiones se usaron para construir esta instancia de +Guix. Por tanto podemos replicarla, digamos, en otra máquina, proporcionando +una especificaciones de canales en @file{~/.config/guix/channels.scm} que +está ``clavada'' en estas revisiones: + +@lisp +;; Despliega unas revisiones específicas de mis canales de interés. +(list (channel + (name 'guix) + (url "https://git.savannah.gnu.org/git/guix.git") + (commit "d894ab8e9bfabcefa6c49d9ba2e834dd5a73a300")) + (channel + (name 'mis-paquetes-personales) + (url "https://example.org/paquetes-personales.git") + (branch "dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb"))) +@end lisp + +La orden @command{guix describe --format=channels} puede incluso generar +esta lista de canales directamente (@pxref{Invocación de guix describe}). + +En este punto las dos máquinas ejecutan @emph{exactamente el mismo Guix}, +con acceso a @emph{exactamente los mismos paquetes}. La salida de +@command{guix build gimp} en una máquina debe ser exactamente la misma, bit +a bit, que la salida de la misma orden en la otra máquina. Esto también +significa que ambas máquinas tienen acceso a todo el código fuente de Guix +y, transitiamente, a todo el código fuente de cada paquete que define. + +Esto le proporciona superpoderes, permitiendole seguir la pista de la +procedencia de los artefactos binarios con un grano muy fino, y reproducir +entornos de software a su voluntad---un tipo de capacidad de +``meta-reproducibilidad'', si lo desea. @xref{Inferiores}, para otro modo de +tomar ventaja de estos superpoderes. + +@node Inferiores +@section Inferiores + +@c TODO: Remove this once we're more confident about API stability. +@quotation Nota +La funcionalidad descrita aquí es una ``versión de evaluación tecnológica'' +en la versión @value{VERSION}. Como tal, la interfaz está sujeta a cambios. +@end quotation + +@cindex inferiores +@cindex composición de revisiones de Guix +A veces necesita mezclar paquetes de revisiones de la revisión de Guix que +está ejecutando actualmente con paquetes disponibles en una revisión +diferente. Los @dfn{inferiores} de Guix le permiten conseguirlo componiendo +diferentes revisiones de Guix de modo arbitrario. + +@cindex paquetes inferiores +Técnicamente, un ``inferior'' es esencialmente un proceso Guix separado +conectado con su Guix principal a través de una sesión interactiva +(@pxref{Invocación de guix repl}). El módulo @code{(guix inferior)} le permite +crear inferiores y comunicarse con ellos. También proporciona una interfaz +de alto nivel para buscar y manipular los paquetes que un inferior +proporciona---@dfn{paquetes de inferiores}. + +Cuando se combina con los canales (@pxref{Canales}), los inferiores +proporcionan una forma simple de interactuar con una revisión separada de +Guix. Por ejemplo, asumamos que desea instalar en su perfil el paquete +@code{guile} actual, junto al paquete @code{guile-json} como existía en una +revisión más antigua de Guix---quizá porque las versiones nuevas de +@code{guile-json} tienen un API incompatible y quiere ejecutar su código +contra la API antigua. Para hacerlo, puede escribir un manifiesto para +usarlo con @code{guix package --manifest} (@pxref{Invocación de guix package}); +en dicho manifiesto puede crear un inferior para esa versión antigua de Guix +que le interesa, y buscará el paquete @code{guile-json} en el inferior: + +@lisp +(use-modules (guix inferior) (guix channels) + (srfi srfi-1)) ;para 'first' + +(define channels + ;; Esta es la revisión antigua de donde queremos + ;; extraer guile-json. + (list (channel + (name 'guix) + (url "https://git.savannah.gnu.org/git/guix.git") + (commit + "65956ad3526ba09e1f7a40722c96c6ef7c0936fe")))) + +(define inferior + ;; Un inferior que representa la revisión previa. + (inferior-for-channels channels)) + +;; Ahora crea un manifiesto con el paquete "guile" actual +;; y el antiguo paquete "guile-json". +(packages->manifest + (list (first (lookup-inferior-packages inferior "guile-json")) + (specification->package "guile"))) +@end lisp + +En su primera ejecución, @command{guix package --manifest} puede tener que +construir el canal que especificó antes de crear el inferior; las siguientes +ejecuciones serán mucho más rápidas porque la revisión de Guix estará en la +caché. + +El módulo @code{(guix inferior)} proporciona los siguientes procedimientos +para abrir un inferior: + +@deffn {Procedimiento Scheme} inferior-for-channels @var{canales} @ + [#:cache-directory] [#:ttl] +Devuelve un inferior para @var{canales}, una lista de canales. Usa la caché +en @var{cache-directory}, donde las entradas pueden ser reclamadas después +de @var{ttl} segundos. Este procedimiento abre una nueva conexión al daemon +de construcción. + +Como efecto secundario, este procedimiento puede construir o sustituir +binarios para @var{canales}, lo cual puede tomar cierto tiempo. +@end deffn + +@deffn {Procedimiento Scheme} open-inferior @var{directorio} @ + [#:command "bin/guix"] +Abre el Guix inferior en @var{directorio}, ejecutando +@code{@var{directorio}/@var{command} repl} o su equivalente. Devuelve +@code{#f} si el inferior no pudo ser ejecutado. +@end deffn + +@cindex paquetes inferiores +Los procedimientos enumerados a continuación le permiten obtener y manipular +paquetes de inferiores. + +@deffn {Procedimiento Scheme} inferior-packages @var{inferior} +Devuelve la lista de paquetes conocida por @var{inferior}. +@end deffn + +@deffn {Procedimiento Scheme} lookup-inferior-packages @var{inferior} @var{nombre} @ + [@var{versión}] +Devuelve la lista ordenada de paquetes del inferior que corresponden con +@var{nombre} en @var{inferior}, con los números de versión más altos +primero. Si @var{versión} tiene un valor verdadero, devuelve únicamente +paquetes con un número de versión cuyo prefijo es @var{versión}. +@end deffn + +@deffn {Procedimiento Scheme} inferior-package? @var{obj} +Devuelve verdadero si @var{obj} es un paquete inferior. +@end deffn + +@deffn {Procedimiento Scheme} inferior-package-name @var{paquete} +@deffnx {Procedimiento Scheme} inferior-package-version @var{paquete} +@deffnx {Procedimiento Scheme} inferior-package-synopsis @var{paquete} +@deffnx {Procedimiento Scheme} inferior-package-description @var{paquete} +@deffnx {Procedimiento Scheme} inferior-package-home-page @var{paquete} +@deffnx {Procedimiento Scheme} inferior-package-location @var{paquete} +@deffnx {Procedimiento Scheme} inferior-package-inputs @var{paquete} +@deffnx {Procedimiento Scheme} inferior-package-native-inputs @var{paquete} +@deffnx {Procedimiento Scheme} inferior-package-propagated-inputs @var{paquete} +@deffnx {Procedimiento Scheme} inferior-package-transitive-propagated-inputs @var{paquete} +@deffnx {Procedimiento Scheme} inferior-package-native-search-paths @var{paquete} +@deffnx {Procedimiento Scheme} inferior-package-transitive-native-search-paths @var{paquete} +@deffnx {Procedimiento Scheme} inferior-package-search-paths @var{paquete} +Estos procedimientos son la contraparte de los accesos a los registros de +pquete (@pxref{Referencia de ``package''}). La mayor parte funcionan interrogando al +inferior del que @var{paquete} viene, por lo que el inferior debe estar vivo +cuando llama a dichos procedimientos. +@end deffn + +Los paquetes de inferiores pueden ser usados transparentemente como +cualquier otro paquete u objeto-tipo-fichero en expresiones-G +(@pxref{Expresiones-G}). También se manejan transparentemente por el +procedimiento @code{packages->manifest}, el cual se usa habitualmente en los +manifiestos (@pxref{Invocación de guix package, the @option{--manifest} option of +@command{guix package}}). Por tanto puede insertar un paquete de inferior +prácticamente en cualquier lugar que pueda insertar un paquete normal: en +manifiestos, en el campo @code{packages} de su declaración +@code{operating-system}, etcétera. + +@node Invocación de guix describe +@section Invocación de @command{guix describe} + +@cindex reproducibilidad +@cindex replicar Guix +A menudo desea responder a preguntas como: ``¿Qué revisión de Guix estoy +usando?'' o ``¿Qué canales estoy usando?'' Esto es una información muy útil +en muchas situaciones: si quiere @emph{replicar} un entorno en una máquina +diferente o cuenta de usuaria, si desea informar de un error o determinar +qué cambio en los canales que usa lo causó, o si quiere almacenar el estado +de su sistema por razones de reproducibilidad. La orden @command{guix +describe} responde a estas preguntas. + +Cuando se ejecuta desde un @command{guix} bajado con @command{guix pull}, +@command{guix describe} muestra el/los canal/es desde el/los que se +construyó, incluyendo la URL de su repositorio y los IDs de las revisiones +(@pxref{Canales}): + +@example +$ guix describe +Generation 10 Sep 03 2018 17:32:44 (current) + guix e0fa68c + repository URL: https://git.savannah.gnu.org/git/guix.git + branch: master + commit: e0fa68c7718fffd33d81af415279d6ddb518f727 +@end example + +Si está familiarizado con el sistema de control de versiones Git, esto es +similar a @command{git describe}; la salida también es similar a la de +@command{guix pull --list-generations}, pero limitada a la generación actual +(@pxref{Invocación de guix pull, the @option{--list-generations} option}). Debido +a que el ID de revisión Git mostrado antes refiere sin ambigüedades al +estado de Guix, esta información es todo lo necesario para describir la +revisión de Guix que usa, y también para replicarla. + +Para facilitar la replicación de Guix, también se le puede solicitar a +@command{guix describe} devolver una lista de canales en vez de la +descripción legible por humanos mostrada antes: + +@example +$ guix describe -f channels +(list (channel + (name 'guix) + (url "https://git.savannah.gnu.org/git/guix.git") + (commit + "e0fa68c7718fffd33d81af415279d6ddb518f727"))) +@end example + +@noindent +Puede almacenar esto en un fichero y pasarselo a @command{guix pull -C} en +otra máquina o en un momento futuro, lo cual instanciará @emph{esta revisión +exacta de Guix} (@pxref{Invocación de guix pull, the @option{-C} option}). De +aquí en adelante, ya que puede desplegar la misma revisión de Guix, puede +también @emph{replicar un entorno completo de software}. Nosotras +humildemente consideramos que esto es @emph{impresionante}, ¡y esperamos que +le guste a usted también! + +Los detalles de las opciones aceptadas por @command{guix describe} son las +siguientes: + +@table @code +@item --format=@var{formato} +@itemx -f @var{formato} +Produce salida en el @var{formato} especificado, uno de: + +@table @code +@item human +produce salida legible por humanos; +@item channels +produce una lista de especificaciones de canales que puede ser pasada a +@command{guix pull -C} o instalada como @file{~/.config/guix/channels.scm} +(@pxref{Invocación de guix pull}); +@item json +@cindex JSON +produce una lista de especificaciones de canales en formato JSON; +@item recutils +produce una lista de especificaciones de canales en formato Recutils. +@end table + +@item --profile=@var{perfil} +@itemx -p @var{perfil} +Muestra información acerca del @var{perfil}. +@end table + +@node Invocación de guix archive +@section Invocación de @command{guix archive} + +@cindex @command{guix archive} +@cindex archive +La orden @command{guix archive} permite a las usuarias @dfn{exportar} +ficheros del almacén en un único archivador, e @dfn{importarlos} +posteriormente en una máquina que ejecute Guix. En particular, permite que +los ficheros del almacén sean transferidos de una máquina al almacén de otra +máquina. + +@quotation Nota +Si está buscando una forma de producir archivos en un formato adecuado para +herramientas distintas a Guix, @pxref{Invocación de guix pack}. +@end quotation + +@cindex exportar elementos del almacén +Para exportar ficheros del almacén como un archivo por la salida estándar, +ejecute: + +@example +guix archive --export @var{opciones} @var{especificaciones}... +@end example + +@var{especificaciones} deben ser o bien nombres de ficheros del almacén o +especificaciones de paquetes, como las de @command{guix package} +(@pxref{Invocación de guix package}). Por ejemplo, la siguiente orden crea un +archivo que contiene la salida @code{gui} del paquete @code{git} y la salida +principal de @code{emacs}: + +@example +guix archive --export git:gui /gnu/store/...-emacs-24.3 > great.nar +@end example + +Si los paquetes especificados no están todavía construidos, @command{guix +archive} los construye automáticamente. El proceso de construcción puede +controlarse mediante las opciones de construcción comunes (@pxref{Opciones comunes de construcción}). + +Para transferir el paquete @code{emacs} a una máquina conectada por SSH, se +ejecutaría: + +@example +guix archive --export -r emacs | ssh otra-maquina guix archive --import +@end example + +@noindent +De manera similar, un perfil de usuaria completo puede transferirse de una +máquina a otra de esta manera: + +@example +guix archive --export -r $(readlink -f ~/.guix-profile) | \ + ssh otra-maquina guix-archive --import +@end example + +@noindent +No obstante, fíjese que, en ambos ejemplos, todo @code{emacs} y el perfil +como también todas sus dependencias son transferidas (debido a la +@code{-r}), independiente de lo que estuviese ya disponible en el almacén de +la máquina objetivo. La opción @code{--missing} puede ayudar a esclarecer +qué elementos faltan en el almacén objetivo. La orden @command{guix copy} +simplifica y optimiza este proceso completo, así que probablemente es lo que +debería usar en este caso (@pxref{Invocación de guix copy}). + +@cindex nar, formato de archivo +@cindex archivo normalizado (nar) +Los archivos se almacenan en el formato de ``archivo normalizado'' o +``nar'', el cual es comparable a `tar' en el espíritu, pero con diferencias +que lo hacen más apropiado para nuestro propósito. Primero, en vez de +almacenar todos los metadatos Unix de cada fichero, el formato nar solo +menciona el tipo de fichero (normal, directorio o enlace simbólico); los +permisos Unix y el par propietario/grupo se descartan. En segundo lugar, el +orden en el cual las entradas de directorios se almacenan siempre siguen el +orden de los nombres de ficheros de acuerdo a la ordenación de cadenas en la +localización C. Esto hace la producción del archivo completamente +determinista. + +@c FIXME: Add xref to daemon doc about signatures. +Durante la exportación, el daemon firma digitalmente los contenidos del +archivo, y la firma digital se adjunta. Durante la importación, el daemon +verifica la firma y rechaza la importación en caso de una firma inválida o +si la clave firmante no está autorizada. + +Las opciones principales son: + +@table @code +@item --export +Exporta los ficheros del almacén o paquetes (véase más adelante). Escribe el +archivo resultante a la salida estándar. + +Las dependencias @emph{no} están incluidas en la salida, a menos que se use +@code{--recursive}. + +@item -r +@itemx --recursive +Cuando se combina con @code{--export}, instruye a @command{guix archive} +para incluir las dependencias de los elementos dados en el archivo. Por +tanto, el archivo resultante está auto-contenido: contiene la clausura de +los elementos exportados del almacén. + +@item --import +Lee un archivo de la entrada estándar, e importa los ficheros enumerados +allí en el almacén. La operación se aborta si el archivo tiene una firma +digital no válida, o si está firmado por una clave pública que no está entre +las autorizadas (vea @code{--authorize} más adelante). + +@item --missing +Lee una lista de nombres de ficheros del almacén de la entrada estándar, uno +por línea, y escribe en la salida estándar el subconjunto de estos ficheros +que faltan en el almacén. + +@item --generate-key[=@var{parámetros}] +@cindex firmar, archivos +Genera un nuevo par de claves para el daemon. Esto es un prerrequisito antes +de que los archivos puedan ser exportados con @code{--export}. Tenga en +cuenta que esta operación normalmente toma tiempo, ya que se necesita +obtener suficiente entropía para generar un par de claves. + +El par de claves generado se almacena típicamente bajo @file{/etc/guix}, en +@file{signing-key.pub} (clave pública) y @file{signing-key.sec} (clave +privada, que se debe mantener secreta). Cuando @var{parámetros} se omite, se +genera una clave ECDSA usando la curva Ed25519, o, en versiones de Libgcrypt +previas a la 1.6.0, es una clave RSA de 4096 bits. De manera alternativa, +los @var{parámetros} pueden especificar parámetros @code{genkey} adecuados +para Libgcrypt (@pxref{General public-key related Functions, +@code{gcry_pk_genkey},, gcrypt, The Libgcrypt Reference Manual}). + +@item --authorize +@cindex autorizar, archivos +Autoriza importaciones firmadas con la clave pública pasada por la entrada +estándar. La clave pública debe estar en el ``formato avanzado de +expresiones-s''---es decir, el mismo formato que el fichero +@file{signing-key.pub}. + +La lista de claves autorizadas se mantiene en el fichero editable por +personas @file{/etc/guix/acl}. El fichero contiene +@url{http://people.csail.mit.edu/rivest/Sexp.text, ``expresiones-s en +formato avanzado''} y está estructurado como una lista de control de acceso +en el formato @url{http://theworld.com/~cme/spki.txt, Infraestructura Simple +de Clave Pública (SPKI)}. + +@item --extract=@var{directorio} +@itemx -x @var{directorio} +Lee un único elemento del archivo como es ofrecido por los servidores de +sustituciones (@pxref{Sustituciones}) y lo extrae a @var{directorio}. Esta es +una operación de bajo nivel necesitada únicamente para casos muy concretos; +véase a continuación. + +Por ejemplo, la siguiente orden extrae la sustitución de Emacs ofrecida por +@code{@value{SUBSTITUTE-SERVER}} en @file{/tmp/emacs}: + +@example +$ wget -O - \ + https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-emacs-24.5 \ + | bunzip2 | guix archive -x /tmp/emacs +@end example + +Los archivos de un único elemento son diferentes de los archivos de +múltiples elementos producidos por @command{guix archive --export}; +contienen un único elemento del almacén, y @emph{no} embeben una firma. Por +tanto esta operación @emph{no} verifica la firma y su salida debe +considerarse insegura. + +El propósito primario de esta operación es facilitar la inspección de los +contenidos de un archivo que provenga probablemente de servidores de +sustituciones en los que no se confía. + +@end table + + +@c ********************************************************************* +@node Desarrollo +@chapter Desarrollo + +@cindex desarrollo de software +Si es una desarrolladora de software, Guix le proporciona herramientas que +debería encontrar útiles---independientemente del lenguaje en el que +desarrolle actualmente. Esto es sobre lo que trata este capítulo. + +La orden @command{guix environment} proporciona una manera conveniente de +configurar un @dfn{entorno de desarrollo} que contenga todas las +dependencias y herramientas necesarias para trabajar en el paquete de +software de su elección. La orden @command{guix pack} le permite crear +@dfn{aplicaciones empaquetadas} que pueden ser distribuidas con facilidad a +usuarias que no usen Guix. + +@menu +* Invocación de guix environment:: Configurar entornos de desarrollo. +* Invocación de guix pack:: Creación de empaquetados de software. +@end menu + +@node Invocación de guix environment +@section Invocación de @command{guix environment} + +@cindex entornos de construcción reproducibles +@cindex entornos de desarrollo +@cindex @command{guix environment} +@cindex entorno, entorno de construcción de paquetes +El propósito de @command{guix environment} es ayudar a las hackers en la +creación de entornos de desarrollo reproducibles sin modificar los paquetes +de su perfil. La herramienta @command{guix environment} toma uno o más +paquetes, construye todas sus entradas y crea un entorno shell para usarlos. + +La sintaxis general es: + +@example +guix environment @var{opciones} @var{paquete}@dots{} +@end example + +El ejemplo siguiente lanza un nuevo shell preparado para el desarrollo de +GNU@tie{}Guile: + +@example +guix environment guile +@end example + +Si las dependencias necesarias no están construidas todavía, @command{guix +environment} las construye automáticamente. El entorno del nuevo shell es +una versión aumentada del entorno en el que @command{guix environment} se +ejecutó. Contiene las rutas de búsqueda necesarias para la construcción del +paquete proporcionado añadidas a las variables ya existentes. Para crear un +entorno ``puro'', donde las variables de entorno previas no existen, use la +opción @code{--pure}@footnote{Las usuarias habitualmente aumentan de forma +incorrecta las variables de entorno como @code{PATH} en su fichero +@file{~/.bashrc}. Como consecuencia, cuando @code{guix environment} se +ejecuta, Bash puede leer @file{~/.bashrc}, por tanto introduciendo +``impurezas'' en esas variables de entorno. Es un error definir dichas +variables de entorno en @file{~/.bashrc}; en vez de ello deben definirse en +@file{.bash_profile}, el cual es únicamente cargado por el shell de ingreso +al sistema. @xref{Bash Startup Files,,, bash, The GNU Bash Reference +Manual}, para detalles sobre los ficheros de inicio de Bash.}. + +@vindex GUIX_ENVIRONMENT +@command{guix environment} define la variable @code{GUIX_ENVIRONMENT} en el +shell que lanza; su valor es el nombre de fichero del perfil para este +entorno. Esto permite a las usuarias, digamos, definir un prompt para +entornos de desarrollo en su @file{.bashrc} (@pxref{Bash Startup Files,,, +bash, The GNU Bash Reference Manual}): + +@example +if [ -n "$GUIX_ENVIRONMENT" ] +then + export PS1="\u@@\h \w [dev]\$ " +fi +@end example + +@noindent +...@: o para explorar el perfil: + +@example +$ ls "$GUIX_ENVIRONMENT/bin" +@end example + +Adicionalmente, más de un paquete puede ser especificado, en cuyo caso se +usa la unión de las entradas de los paquetes proporcionados. Por ejemplo, la +siguiente orden lanza un shell donde todas las dependencias tanto de Guile +como de Emacs están disponibles: + +@example +guix environment guile emacs +@end example + +A veces no se desea una sesión interactiva de shell. Una orden arbitraria +puede invorcarse usando el valor @code{--} para separar la orden del resto +de los parámetros: + +@example +guix environment guile -- make -j4 +@end example + +En otras situaciones, es más conveniente especificar una lista de paquetes +necesarios en el entorno. Por ejemplo, la siguiente orden ejecuta +@command{python} desde un entorno que contiene Python@tie{}2.7 y NumPy: + +@example +guix environment --ad-hoc python2-numpy python-2.7 -- python +@end example + +Más allá, se pueden desear las dependencias de un paquete y también algunos +paquetes adicionales que no son dependencias ni en tiempo de construcción ni +en el de ejecución, pero son útiles no obstante para el desarrollo. Por esta +razón, la opción @code{--ad-hoc} es posicional. Los paquetes que aparecen +antes de @code{--ad-hoc} se interpretan como paquetes cuyas dependencias se +añadirán al entorno. Los paquetes que aparecen después se interpretan como +paquetes que se añadirán directamente al entorno. Por ejemplo, la siguiente +orden crea un entorno de desarrollo Guix que incluye adicionalmente Git y +strace: + +@example +guix environment guix --ad-hoc git strace +@end example + +En ocasiones es deseable aislar el entorno tanto como sea posible, para +obtener la máxima pureza y reproducibilidad. En particular, cuando se usa +Guix en una distribución anfitriona que no es el sistema Guix, es deseable +prevenir acceso a @file{/usr/bin} y otros recursos del sistema desde el +entorno de desarrollo. Por ejemplo, la siguiente orden lanza un REPL Guile +en un ``contenedor'' donde únicamente el almacén y el directorio actual +están montados: + +@example +guix environment --ad-hoc --container guile -- guile +@end example + +@quotation Nota +La opción @code{--container} requiere Linux-libre 3.19 o más nuevo. +@end quotation + +Las opciones disponibles se resumen a continuación. + +@table @code +@item --root=@var{fichero} +@itemx -r @var{fichero} +@cindex entorno persistente +@cindex raíz del recolector de basura, para entornos +Hace que @var{fichero} sea un enlace simbólico al perfil para este entorno, +y lo registra como una raíz del recolector de basura. + +Esto es útil si desea proteger su entorno de la recolección de basura, +hacerlo ``persistente''. + +Cuando se omite esta opción, el entorno se protege de la recolección de +basura únicamente por la duración de la sesión @command{guix +environment}. Esto significa que la siguiente vez que vuelva a crear el +mismo entorno, puede tener que reconstruir o volver a descargar +paquetes. @xref{Invocación de guix gc}, para más información sobre las raices del +recolector de basura. + +@item --expression=@var{expr} +@itemx -e @var{expr} +Crea un entorno para el paquete o lista de paquetes a los que evalúa +@var{expr}. + +Por ejemplo, ejecutando: + +@example +guix environment -e '(@@ (gnu packages maths) petsc-openmpi)' +@end example + +inicia un shell con el entorno para esta variante específica del paquete +PETSc. + +Ejecutar: + +@example +guix environment --ad-hoc -e '(@@ (gnu) %base-packages)' +@end example + +inicia un shell con todos los paquetes básicos del sistema disponibles. + +Las órdenes previas usan únicamente la salida predeterminada de los paquetes +dados. Para seleccionar otras salidas, tuplas de dos elementos pueden ser +especificadas: + +@example +guix environment --ad-hoc -e '(list (@@ (gnu packages bash) bash) "include")' +@end example + +@item --load=@var{fichero} +@itemx -l @var{fichero} +Crea un entorno para el paquete o la lista de paquetes a la que el código en +@var{fichero} evalúa. + +Como un ejemplo, @var{fichero} puede contener una definición como esta +(@pxref{Definición de paquetes}): + +@example +@verbatiminclude environment-gdb.scm +@end example + +@item --manifest=@var{fichero} +@itemx -m @var{fichero} +Crea un entorno para los paquetes contenidos en el objeto manifest devuelto +por el código Scheme en @var{file}. + +Esto es similar a la opción del mismo nombre en @command{guix package} +(@pxref{profile-manifest, @option{--manifest}}) y usa los mismos ficheros de +manifiesto. + +@item --ad-hoc +Incluye todos los paquetes especificados en el entorno resultante, como si +un paquete @i{ad hoc} hubiese sido definido con ellos como entradas. Esta +opción es útil para la creación rápida un entorno sin tener que escribir una +expresión de paquete que contenga las entradas deseadas. + +Por ejemplo, la orden: + +@example +guix environment --ad-hoc guile guile-sdl -- guile +@end example + +ejecuta @command{guile} en un entorno donde están disponibles Guile y +Guile-SDL. + +Fíjese que este ejemplo solicita implícitamente la salida predeterminada de +@code{guile} y @code{guile-sdl}, pero es posible solicitar una salida +específica---por ejemplo, @code{glib:bin} solicita la salida @code{bin} de +@code{glib} (@pxref{Paquetes con múltiples salidas}). + +Esta opción puede componerse con el comportamiento predeterminado de +@command{guix environment}. Los paquetes que aparecen antes de +@code{--ad-hoc} se interpretan como paquetes cuyas dependencias se añadirán +al entorno, el comportamiento predefinido. Los paquetes que aparecen después +se interpretan como paquetes a añadir directamente al entorno. + +@item --pure +Olvida las variables de entorno existentes cuando se construye un nuevo +entorno, excepto aquellas especificadas con @option{--preserve} (véase más +adelante). Esto tiene el efecto de crear un entorno en el que las rutas de +búsqueda únicamente contienen las entradas del paquete. + +@item --preserve=@var{regexp} +@itemx -E @var{regexp} +Cuando se usa junto a @option{--pure}, preserva las variables de entorno que +corresponden con @var{regexp}---en otras palabras, las pone en una lista de +variables de entorno que deben preservarse. Esta opción puede repetirse +varias veces. + +@example +guix environment --pure --preserve=^SLURM --ad-hoc openmpi @dots{} \ + -- mpirun @dots{} +@end example + +Este ejemplo ejecuta @command{mpirun} en un contexto donde las únicas +variables de entorno definidas son @code{PATH}, variables de entorno cuyo +nombre empiece con @code{SLURM}, así como las variables ``preciosas'' +habituales (@code{HOME}, @code{USER}, etc.). + +@item --search-paths +Muestra las definiciones de variables de entorno que componen el entorno. + +@item --system=@var{sistema} +@itemx -s @var{sistema} +Intenta construir para @var{sistema}---por ejemplo, @code{i686-linux}. + +@item --container +@itemx -C +@cindex container +Ejecuta la @var{orden} en un contenedor aislado. El directorio actual fuera +del contenedor es asociado al interior del contenedor. Adicionalmente, a +menos que se fuerce con @code{--user}, un directorio de prueba de la usuaria +se crea de forma que coincida con el directorio actual de la usuaria, y +@file{/etc/passwd} se configura adecuadamente. + +El proceso lanzado se ejecuta como el usuario actual fuera del +contenedor. Dentro del contenedor, tiene el mismo UID y GID que el usuario +actual, a menos que se proporcione @option{--user} (véase más adelante). + +@item --network +@itemx -N +Para contenedores, comparte el espacio de nombres de red con el sistema +anfitrión. Los contenedores creados sin esta opción únicamente tienen acceso +a la red local. + +@item --link-profile +@itemx -P +Para contenedores, enlaza el perfil del entorno a @file{~/.guix-profile} +dentro del contenedor. Es equivalente a la ejecución de @command{ln -s +$GUIX_ENVIRONMENT ~/.guix-profile} dentro del contenedor. El enlace fallará +e interrumpirá el entorno si el directorio ya existe, lo cual será +probablemente el caso si @command{guix environment} se invocó en el +directorio de la usuaria. + +Determinados paquetes se configuran para buscar en @code{~/.guix-profile} +ficheros de configuración y datos;@footnote{Por ejemplo, el paquete +@code{fontconfig} inspecciona @file{~/.guix-profile/share/fonts} en busca de +nuevas tipografías.} @code{--link-profile} permite a estos programas operar +de la manera esperada dentro del entorno. + +@item --user=@var{usuaria} +@itemx -u @var{usuaria} +Para contenedores, usa el nombre de usuaria @var{usuaria} en vez de la +actual. La entrada generada en @file{/etc/passwd} dentro del contenedor +contendrá el nombre @var{usuaria}; su directorio será +@file{/home/@var{usuaria}} y ningún dato GECOS de la usuaria se copiará. Más +aún, el UID y GID dentro del contenedor son 1000. @var{usuaria} no debe +existir en el sistema. + +Adicionalmente, cualquier ruta compartida o expuesta (véanse @code{--share} +y @code{--expose} respectivamente) cuyo destino esté dentro de la carpeta +actual de la usuaria será reasociada en relación a +@file{/home/@var{usuaria}}; esto incluye la relación automática del +directorio de trabajo actual. + +@example +# expondrá las rutas /home/foo/ddt, /home/foo/prueba y /home/foo/objetivo +cd $HOME/ddt +guix environment --container --user=foo \ + --expose=$HOME/prueba \ + --expose=/tmp/objetivo=$HOME/objetivo +@end example + +Mientras esto limita el escape de la identidad de la usuaria a través de las +rutas de sus directorios y cada uno de los campos de usuaria, esto es +únicamente un componente útil de una solución de privacidad/anonimato más +amplia---no una solución completa. + +@item --expose=@var{fuente}[=@var{destino}] +Para contenedores, expone el sistema de ficheros @var{fuente} del sistema +anfitrión como un sistema de ficheros de solo-lectura @var{destino} dentro +del contenedor. Si no se especifica @var{destino}, @var{fuente} se usa como +el punto de montaje en el contenedor. + +El ejemplo a continuación lanza una sesión interactiva de Guile en un +contenedor donde el directorio principal de la usuaria es accesible en modo +solo-lectura a través del directorio @file{/intercambio}: + +@example +guix environment --container --expose=$HOME=/intercambio --ad-hoc guile -- guile +@end example + +@item --share=@var{fuente}[=@var{destino}] +Para contenedores, comparte el sistema de ficheros @var{fuente} del sistema +anfitrión como el sistema de ficheros @var{destino} con permisos de +escritura dentro del contenedor. Si no se especifica @var{destino}, +@var{fuente} se usa como punto de montaje en el contenedor. + +El siguiente ejemplo lanza un entorno interactivo Guile en un contenedor en +el que el directorio principal de la usuaria está disponible para tanto +lectura como escritura via el directorio @file{/intercambio}: + +@example +guix environment --container --share=$HOME=/intercambio --ad-hoc guile -- guile +@end example +@end table + +Además, @command{guix environment} acepta todas las opciones comunes de +construcción que permite @command{guix build} (@pxref{Opciones comunes de construcción}) +así como las opciones de transformación de paquetes (@pxref{Opciones de transformación de paquetes}). + +@node Invocación de guix pack +@section Invocación de @command{guix pack} + +De manera ocasional querrá dar software a gente que (¡todavía!) no tiene la +suerte de usar Guix. Usted les diría que ejecuten @command{guix package -i +@var{algo}}, pero eso no es posible en este caso. Aquí es donde viene +@command{guix pack}. + +@quotation Nota +Si está buscando formas de intercambiar binarios entre máquinas que ya +ejecutan Guix, @pxref{Invocación de guix copy}, @ref{Invocación de guix publish}, y +@ref{Invocación de guix archive}. +@end quotation + +@cindex pack +@cindex empaquetado +@cindex aplicación empaquetada +@cindex empaquetado de software +La orden @command{guix pack} crea un @dfn{paquete} reducido o +@dfn{empaquetado de software}: crea un archivador tar u otro tipo que +contiene los binarios del software en el que está interesada y todas sus +dependencias. El archivo resultante puede ser usado en una máquina que no +tiene Guix, y la gente puede ejecutar exactamente los mismos binarios que +usted tiene con Guix. El paquete en sí es creado de forma reproducible +bit-a-bit, para que cualquiera pueda verificar que realmente contiene los +resultados de construcción que pretende distribuir. + +Por ejemplo, para crear un empaquetado que contenga Guile, Emacs, Geiser y +todas sus dependencias, puede ejecutar: + +@example +$ guix pack guile emacs geiser +@dots{} +/gnu/store/@dots{}-pack.tar.gz +@end example + +El resultado aquí es un archivador tar que contiene un directorio de +@file{/gnu/store} con todos los paquetes relevantes. El archivador +resultante contiene un @dfn{perfil} con los tres paquetes de interés; el +perfil es el mismo que se hubiera creado por @command{guix package -i}. Este +es el mecanismo usado para crear el propio archivador de binarios separado +de Guix (@pxref{Instalación binaria}). + +Las usuarias de este empaquetad tendrán que ejecutar +@file{/gnu/store/@dots{}-profile/bin/guile} para ejecutar guile, lo que +puede resultar inconveniente. Para evitarlo, puede crear, digamos, un enlace +simbólico @file{/opt/gnu/bin} al perfil: + +@example +guix pack -S /opt/gnu/bin=bin guile emacs geiser +@end example + +@noindent +De este modo, las usuarias pueden escribir alegremente +@file{/opt/gnu/bin/guile} y disfrutar. + +@cindex binarios relocalizables, con @command{guix pack} +¿Qué pasa se la receptora de su paquete no tiene privilegios de root en su +máquina y por lo tanto no puede desempaquetarlo en la raíz del sistema de +ficheros? En ese caso, lo que usted desea es usar la opción +@code{--relocatable} (véase a continuación). Esta opción produce +@dfn{binarios relocalizables}, significando que pueden ser colocados en +cualquier lugar de la jerarquía del sistema de ficheros: en el ejemplo +anterior, las usuarias pueden desempaquetar el archivador en su directorio +de usuaria y ejecutar directamente @file{./opt/gnu/bin/guile}. + +@cindex Docker, construir una imagen con guix pack +De manera alternativa, puede producir un empaquetado en el formato de imagen +Docker usando la siguiente orden: + +@example +guix pack -f docker guile emacs geiser +@end example + +@noindent +El resultado es un archivador tar que puede ser pasado a la orden +@command{docker load}. Véase la +@uref{https://docs.docker.com/engine/reference/commandline/load/, +documentación de Docker} para más información. + +@cindex Singularity, construir una imagen con guix pack +@cindex SquashFS, construir una imagen con guix pack +Otra opción más es producir una imagen SquashFS con la siguiente orden: + +@example +guix pack -f squashfs guile emacs geiser +@end example + +@noindent +El resultado es una imagen de sistema de ficheros SquashFS que puede ser o +bien montada, o bien usada directamente como una imagen contenedora de +sistemas de ficheros con el @uref{http://singularity.lbl.gov, entorno de +ejecución de contenedores Singularity}, usando órdenes como +@command{singularity shell} o @command{singularity exec}. + +Varias opciones de la línea de órdenes le permiten personalizar su +empaquetado: + +@table @code +@item --format=@var{formato} +@itemx -f @var{formato} +Produce un empaquetado en el @var{formato} específico. + +Los formatos disponibles son: + +@table @code +@item tarball +Es el formato predeterminado. Produce un archivador que contiene todos los +binarios y enlaces simbólicos especificados. + +@item docker +Produce un archivador que sigue la +@uref{https://github.com/docker/docker/blob/master/image/spec/v1.2.md, +especificación de imágenes Docker}. + +@item squashfs +Produce una imagen SquashFS que contiene todos los binarios y enlaces +simbólicos especificados, así como puntos de montaje vacíos para sistemas de +ficheros virtuales como procfs. +@end table + +@cindex binarios reposicionables +@item --relocatable +@itemx -R +Produce @dfn{binarios reposicionables}---es decir, binarios que se pueden +posicionar en cualquier lugar de la jerarquía del sistema de ficheros, y +ejecutarse desde allí. + +When this option is passed once, the resulting binaries require support for +@dfn{user namespaces} in the kernel Linux; when passed +@emph{twice}@footnote{Here's a trick to memorize it: @code{-RR}, which adds +PRoot support, can be thought of as the abbreviation of ``Really +Relocatable''. Neat, isn't it?}, relocatable binaries fall to back to PRoot +if user namespaces are unavailable, and essentially work anywhere---see +below for the implications. + +Por ejemplo, si crea un empaquetado que contiene Bash con:< + +@example +guix pack -RR -S /mybin=bin bash +@end example + +@noindent +...@: puede copiar ese empaquetado a una máquina que no tiene Guix, y desde +su directorio, como una usuaria normal, ejecutar: + +@example +tar xf pack.tar.gz +./mibin/sh +@end example + +@noindent +En ese shell, si escribe @code{ls /gnu/store}, notará que @file{/gnu/store} +muestra y contiene todas las dependencias de @code{bash}, ¡incluso cuando la +máquina no tiene el directorio @file{/gnu/store}! Esto es probablemente el +modo más simple de desplegar software construido en Guix en una máquina +no-Guix. + +@quotation Nota +No obstante hay un punto a tener en cuenta: esta técnica descansa en la +característica de @dfn{espacios de nombres de usuaria} del núcleo Linux, la +cual permite a usuarias no privilegiadas montar o cambiar la raíz. Versiones +antiguas de Linux no los implementan, y algunas distribuciones GNU/Linux los +deshabilitan. + +Para producir binarios reposicionables que funcionen incluso en ausencia de +espacios de nombre de usuaria, proporcione @option{--relocatable} o +@option{-R} @emph{dos veces}. En ese caso, los binarios intentarán el uso de +espacios de nombres de usuaria y usarán PRoot si no es posible. + +El programa @uref{https://proot-me.github.io/, PRoot} proporciona el soporte +necesario para la virtualización del sistema de ficheros. Lo consigue +mediante el uso de la llamada al sistema @code{ptrace} en el programa en +ejecución. Esta aproximación tiene la ventaja de funcionar sin soporte +especial en el núcleo, pero incurre en una sobrecarga en el tiempo de +ejecución cada vez que se realiza una llamada al sistema. +@end quotation + +@item --expression=@var{expr} +@itemx -e @var{expr} +Considera el paquete al que evalúa @var{expr} + +Esto tiene el mismo propósito que la opción del mismo nombre en +@command{guix build} (@pxref{Opciones de construcción adicionales, @code{--expression} +in @command{guix build}}). + +@item --manifest=@var{fichero} +@itemx -m @var{fichero} +Usa los paquetes contenidos en el objeto manifest devuelto por el código +Scheme en @var{file}. + +Esto tiene un propósito similar al de la opción del mismo nombre en +@command{guix package} (@pxref{profile-manifest, @option{--manifest}}) y usa +los mismos ficheros de manifiesto. Esto le permite definir una colección de +paquetes una vez y usarla tanto para crear perfiles como para crear archivos +en máquinas que no tienen instalado Guix. Fíjese que puede especificar +@emph{o bien} un fichero de manifiesto @emph{o bien} una lista de paquetes, +pero no ambas. + +@item --system=@var{sistema} +@itemx -s @var{sistema} +Intenta construir paquetes para @var{sistema}---por ejemplo, +@code{x86_64-linux}---en vez del tipo de sistema de la máquina de +construcción. + +@item --target=@var{tripleta} +@cindex compilación cruzada +Compilación cruzada para la @var{tripleta}, que debe ser una tripleta GNU +válida, cómo @code{"mips64el-linux-gnu"} (@pxref{Specifying target triplets, +GNU configuration triplets,, autoconf, Autoconf}). + +@item --compression=@var{herramienta} +@itemx -C @var{herramienta} +Comprime el archivador resultante usando @var{herramienta}---un valor que +puede ser @code{gzip}, @code{bzip2}, @code{xz}, @code{lzip} o @code{none} +para no usar compresión. + +@item --symlink=@var{spec} +@itemx -S @var{spec} +Añade los enlaces simbólicos especificados por @var{spec} al +empaquetado. Esta opción puede aparecer varias veces. + +La forma de @var{spec} es @code{@var{fuente}=@var{destino}}, donde +@var{fuente} es el enlace simbólico que será creado y @var{destino} es el +destino del enlace simbólico. + +Por ejemplo, @code{-S /opt/gnu/bin=bin} crea un enlace simbólico +@file{/opt/gnu/bin} apuntando al subdirectorio @file{bin} del perfil. + +@item --save-provenance +Save provenance information for the packages passed on the command line. +Provenance information includes the URL and commit of the channels in use +(@pxref{Canales}). + +Provenance information is saved in the +@file{/gnu/store/@dots{}-profile/manifest} file in the pack, along with the +usual package metadata---the name and version of each package, their +propagated inputs, and so on. It is useful information to the recipient of +the pack, who then knows how the pack was (supposedly) obtained. + +This option is not enabled by default because, like timestamps, provenance +information contributes nothing to the build process. In other words, there +is an infinity of channel URLs and commit IDs that can lead to the same +pack. Recording such ``silent'' metadata in the output thus potentially +breaks the source-to-binary bitwise reproducibility property. + +@item --localstatedir +@itemx --profile-name=@var{nombre} +Incluye el ``directorio de estado local'', @file{/var/guix}, en el +empaquetado resultante, y notablemente el perfil +@file{/var/guix/profiles/per-user/root/@var{nombre}}---por defecto +@var{nombre} es @code{guix-profile}, que corresponde con +@file{~root/.guix-profile}. + +@file{/var/guix} contiene la base de datos del almacén (@pxref{El almacén}) +así como las raíces del recolector de basura (@pxref{Invocación de guix gc}). Proporcionarlo junto al empaquetado significa que el almacén está +``completo'' y Guix puede trabajar con él; no proporcionarlo significa que +el almacén está ``muerto'': no se pueden añadir o borrar nuevos elementos +después de la extracción del empaquetado. + +Un caso de uso para esto es el archivador tar autocontenido de binarios de +Guix (@pxref{Instalación binaria}). + +@item --bootstrap +Usa los binarios del lanzamiento para construir el empaquetado. Esta opción +es útil únicamente a las desarrolladoras de Guix. +@end table + +Además, @command{guix pack} acepta todas las opciones comunes de +construcción (@pxref{Opciones comunes de construcción}) y todas las opciones de +transformación de paquetes (@pxref{Opciones de transformación de paquetes}). + + +@c ********************************************************************* +@node Interfaz programática +@chapter Interfaz programática + +GNU Guix proporciona viarias interfaces programáticas Scheme (APIs) para +definir, construir y consultar paquetes. La primera interfaz permite a las +usuarias escribir definiciones de paquetes a alto nivel. Estas definiciones +referencian conceptos familiares de empaquetamiento, como el nombre y la +versión de un paquete, su sistema de construcción y sus dependencias. Estas +definiciones se pueden convertir en acciones concretas de construcción. + +Las acciones de construcción son realizadas por el daemon Guix, en +delegación de las usuarias. En una configuración estándar, el daemon tiene +acceso de escritura al almacén---el directorio @file{/gnu/store}---mientras +que las usuarias no. En la configuración recomendada el daemon también +realiza las construcciones en chroots, bajo usuarias específicas de +construcción, para minimizar la interferencia con el resto del sistema. + +@cindex derivación +Las APIs de nivel más bajo están disponibles para interactuar con el daemon +y el almacén. Para instruir al daemon para realizar una acción de +construcción, las usuarias realmente proporcionan una @dfn{derivación}. Una +derivación es una representación de bajo nivel de las acciones de +construcción a tomar, y el entorno en el que deberían suceder---las +derivaciones son a las definiciones de paquetes lo que es el ensamblador a +los programas en C. El término ``derivación'' viene del hecho de que los +resultados de la construcción @emph{derivan} de ellas. + +Este capítulo describe todas estas APIs en orden, empezando por las +definiciones de alto nivel de paquetes. + +@menu +* Módulos de paquetes:: Paquetes bajo el punto de vista del + programador. +* Definición de paquetes:: Definir nuevos paquetes. +* Sistemas de construcción:: Especificar como se construyen los paquetes. +* El almacén:: Manipular el almacén de paquetes. +* Derivaciones:: Interfaz de bajo nivel de las derivaciones de + los paquetes. +* La mónada del almacén:: Interfaz puramente funcional del almacén. +* Expresiones-G:: Manipular expresiones de construcción. +* Invocación de guix repl:: Enredar con Guix interactivamente. +@end menu + +@node Módulos de paquetes +@section Módulos de paquetes + +Desde un punto de vista programático, las definiciones de paquetes de la +distribución GNU se proporcionan por módulos Guile en el espacio de nombres +@code{(gnu packages @dots{})}@footnote{Fíjese que los paquetes bajo el +espacio de nombres de módulo @code{(gnu packages @dots{})} no son +necesariamente ``paquetes GNU''. Este esquema de nombrado de módulos sigue +la convención habitual de Guile para el nombrado de módulos: @code{gnu} +significa que estos módulos se distribuyen como parte del sistema GNU, y +@code{packages} identifica módulos que definen paquetes.} (@pxref{Módulos, +Guile modules,, guile, GNU Guile Reference Manual}). Por ejemplo, el módulo +@code{(gnu packages emacs)} exporta una variable con nombre @code{emacs}, +que está asociada a un objeto @code{<package>} (@pxref{Definición de paquetes}). + +El espacio de nombres de módulos @code{(gnu packages @dots{})} se recorre +automáticamente en busca de paquetes en las herramientas de línea de +ordenes. Por ejemplo, cuando se ejecuta @code{guix package -i emacs}, todos +los módulos @code{(gnu packages @dots{})} son procesados hasta encontrar uno +que exporte un objeto de paquete cuyo nombre sea @code{emacs}. Esta búsqueda +de paquetes se implementa en el módulo @code{(gnu packages)}. + +@cindex personalización, de paquetes +@cindex ruta de búsqueda de módulos de paquetes +Las usuarias pueden almacenar definiciones de paquetes en módulos con +nombres diferentes---por ejemplo, @code{(mis-paquetes +emacs)}@footnote{Fíjese que el nombre de fichero y el nombre de módulo deben +coincidir. Por ejemplo, el módulo @code{(mis-paquetes emacs)} debe +almacenarse en el fichero @file{mis-paquetes/emacs.scm} en relación con la +ruta de carga especificada con @option{--load-path} o +@code{GUIX_PACKAGE_PATH}. @xref{Modules and the File System,,, guile, GNU +Guile Reference Manual}, para obtener detalles.}. Existen dos maneras de +hacer visibles estas definiciones de paquetes a las interfaces de usuaria: + +@enumerate +@item +Mediante la adición del directorio que contiene sus módulos de paquetes a la +ruta de búsqueda con la opción @code{-L} de @command{guix package} y otras +órdenes (@pxref{Opciones comunes de construcción}), o usando la variable de entorno +@code{GUIX_PACKAGE_PATH} descrita más adelante. + +@item +Mediante la definición de un @dfn{canal} y la configuración de @command{guix +pull} de manera que se actualice desde él. Un canal es esencialmente un +repositorio Git que contiene módulos de paquetes. @xref{Canales}, para más +información sobre cómo definir y usar canales. +@end enumerate + +@code{GUIX_PACKAGE_PATH} funciona de forma similar a otras variables de +rutas de búsqueda: + +@defvr {Variable de entorno} GUIX_PACKAGE_PATH +Es una lista separada por dos puntos de directorios en los que se buscarán +módulos de paquetes adicionales. Los directorios enumerados en esta variable +tienen preferencia sobre los propios módulos de la distribución. +@end defvr + +La distribución es @dfn{auto-contenida} y completamente @dfn{basada en el +lanzamiento inicial}: cada paquete se construye basado únicamente en otros +paquetes de la distribución. La raíz de este grafo de dependencias es un +pequeño conjunto de @dfn{binarios del lanzamiento inicial}, proporcionados +por el módulo @code{(gnu packages bootstrap)}. Para más información sobre el +lanzamiento inicial, @pxref{Lanzamiento inicial}. + +@node Definición de paquetes +@section Definición de paquetes + +La interfaz de alto nivel de las definiciones de paquetes está implementada +en los módulos @code{(guix packages)} y @code{(guix build-system)}. Como un +ejemplo, la definición de paquete, o @dfn{receta}, para el paquete GNU Hello +es como sigue: + +@example +(define-module (gnu packages hello) + #:use-module (guix packages) + #:use-module (guix download) + #:use-module (guix build-system gnu) + #:use-module (guix licenses) + #:use-module (gnu packages gawk)) + +(define-public hello + (package + (name "hello") + (version "2.10") + (source (origin + (method url-fetch) + (uri (string-append "mirror://gnu/hello/hello-" version + ".tar.gz")) + (sha256 + (base32 + "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i")))) + (build-system gnu-build-system) + (arguments '(#:configure-flags '("--enable-silent-rules"))) + (inputs `(("gawk" ,gawk))) + (synopsis "Hello, GNU world: An example GNU package") + (description "Guess what GNU Hello prints!") + (home-page "http://www.gnu.org/software/hello/") + (license gpl3+))) +@end example + +@noindent +Sin ser una experta en Scheme---pero conociendo un poco de inglés---, la +lectora puede haber supuesto el significado de varios campos aquí. Esta +expresión asocia la variable @code{hello} al objeto @code{<package>}, que +esencialmente es un registro (@pxref{SRFI-9, Scheme records,, guile, GNU +Guile Reference Manual}). Este objeto de paquete puede ser inspeccionado +usando los procedimientos encontrados en el módulo @code{(guix packages)}; +por ejemplo, @code{(package-name hello)} +devuelve---¡sorpresa!---@code{"hello"}. + +Con suerte, puede que sea capaz de importar parte o toda la definición del +paquete de su interés de otro repositorio, usando la orden @code{guix +import} (@pxref{Invocación de guix import}). + +En el ejemplo previo, @var{hello} se define en un módulo para ella, +@code{(gnu packages hello)}. Técnicamente, esto no es estrictamente +necesario, pero es conveniente hacerlo: todos los paquetes definidos en +módulos bajo @code{(gnu packages @dots{})} se reconocen automáticamente en +las herramientas de línea de órdenes (@pxref{Módulos de paquetes}). + +Hay unos pocos puntos que merece la pena destacar de la definición de +paquete previa: + +@itemize +@item +El campo @code{source} del paquete es un objeto @code{<origin>} +(@pxref{Referencia de ``origin''}, para la referencia completa). Aquí se usa el +método @code{url-fetch} de @code{(guix download)}, lo que significa que la +fuente es un fichero a descargar por FTP o HTTP. + +El prefijo @code{mirror://gnu} instruye a @code{url-fetch} para usar uno de +los espejos GNU definidos en @code{(guix download)}. + +El campo @code{sha256} especifica el hash SHA256 esperado del fichero +descargado. Es obligatorio, y permite a Guix comprobar la integridad del +fichero. La forma @code{(base32 @dots{})} introduce la representación base32 +del hash. Puede obtener esta información con @code{guix download} +(@pxref{Invocación de guix download}) y @code{guix hash} (@pxref{Invocación de guix hash}). + +@cindex parches +Cuando sea necesario, la forma @code{origin} también puede tener un campo +@code{patches} con la lista de parches a ser aplicados, y un campo +@code{snippet} con una expresión Scheme para modificar el código fuente. + +@item +@cindex Sistema de construcción GNU +El campo @code{build-system} especifica el procedimiento de construcción del +paquete (@pxref{Sistemas de construcción}). Aquí, @var{gnu-build-system} representa el +familiar sistema de construcción GNU, donde los paquetes pueden +configurarse, construirse e instalarse con la secuencia de ordenes habitual +@code{./configure && make && make check && make install}. + +@item +El campo @code{arguments} especifica las opciones para el sistema de +construcción (@pxref{Sistemas de construcción}). Aquí son interpretadas por +@var{gnu-build-system} como una petición de ejecutar @file{configure} con la +opción @code{--enable-silent-rules}. + +@cindex quote +@cindex creación de literales +@findex ' +@findex quote +¿Qué son estas comillas simples (@code{'})? Son sintaxis Scheme para +introducir una lista literal; @code{'} es sinónimo de +@code{quote}. @xref{Expression Syntax, quoting,, guile, GNU Guile Reference +Manual}, para más detalles. Aquí el valor del campo @code{arguments} es una +lista de parámetros pasada al sistema de construcción, como con @code{apply} +(@pxref{Fly Evaluation, @code{apply},, guile, GNU Guile Reference Manual}). + +La secuencia almohadilla-dos puntos (@code{#:}) define una @dfn{palabra +clave} Scheme (@pxref{Keywords,,, guile, GNU Guile Reference Manual}), y +@code{#:configure-flags} es una palabra clave usada para pasar un parámetro +nominal al sistema de construcción (@pxref{Coding With Keywords,,, guile, +GNU Guile Reference Manual}). + +@item +El campo @code{inputs} especifica las entradas al proceso de +construcción---es decir, dependencias de tiempo de construcción o ejecución +del paquete. Aquí, definimos una entrada llamada @code{"gawk"}, cuyo valor +es el de la variable @var{gawk}; @var{gawk} en sí apunta a un objeto +@code{<package>}. + +@cindex acento grave (quasiquote) +@findex ` +@findex quasiquote +@cindex coma (unquote) +@findex , +@findex unquote +@findex ,@@ +@findex unquote-splicing +De nuevo, @code{`} (un acento grave, sinónimo de @code{quasiquote}) nos +permite introducir una lista literal en el campo @code{inputs}, mientras que +@code{,} (una coma, sinónimo de @code{unquote}) nos permite insertar un +valor en dicha lista (@pxref{Expression Syntax, unquote,, guile, GNU Guile +Reference Manual}). + +Fíjese que no hace falta que GCC, Coreutils, Bash y otras herramientas +esenciales se especifiquen como entradas aquí. En vez de eso, +@var{gnu-build-system} se hace cargo de asegurar que están presentes +(@pxref{Sistemas de construcción}). + +No obstante, cualquier otra dependencia debe ser especificada en el campo +@code{inputs}. Las dependencias no especificadas aquí simplemente no estarán +disponibles para el proceso de construcción, provocando posiblemente un +fallo de construcción. +@end itemize + +@xref{Referencia de ``package''}, para una descripción completa de los campos +posibles. + +Una vez la definición de paquete esté en su lugar, el paquete puede ser +construido realmente usando la herramienta de línea de órdenes @code{guix +build} (@pxref{Invocación de guix build}), pudiendo resolver cualquier fallo de +construcción que encuentre (@pxref{Depuración de fallos de construcción}). Puede volver +a la definición del paquete fácilmente usando la orden @command{guix edit} +(@pxref{Invocación de guix edit}). @xref{Guías de empaquetamiento}, para más +información sobre cómo probar definiciones de paquetes, y @ref{Invocación de guix lint}, para información sobre cómo comprobar la consistencia del estilo de +una definición. +@vindex GUIX_PACKAGE_PATH +Por último, @pxref{Canales}, para información sobre cómo extender la +distribución añadiendo sus propias definiciones de paquetes en un ``canal''. + +Finalmente, la actualización de la definición con una nueva versión oficial +puede ser automatizada parcialmente por la orden @command{guix refresh} +(@pxref{Invocación de guix refresh}). + +Tras el telón, una derivación correspondiente al objeto @code{<package>} es +calculada mediante el procedimiento @code{package-derivation}. Esta +derivación es almacenada en un fichero @code{.drv} bajo +@file{/gnu/store}. Las acciones de construcción que prescribe pueden +entonces llevarse a cabo usando el procedimiento @code{build-derivations} +(@pxref{El almacén}). + +@deffn {Procedimiento Scheme} package-derivation @var{almacén} @var{paquete} [@var{sistema}] +Devuelve el objeto @code{<derivation>} del @var{paquete} pra el +@var{sistema} (@pxref{Derivaciones}). + +@var{paquete} debe ser un objeto @code{<package>} válido, y @var{sistema} +debe ser una cadena que denote el tipo de sistema objetivo---por ejemplo, +@code{"x86_64-linux"} para un sistema GNU x86_64 basado en +Linux. @var{almacén} debe ser una conexión al daemon, que opera en el +almacén (@pxref{El almacén}). +@end deffn + +@noindent +@cindex compilación cruzada +De manera similar, es posible calcular una derivación que construye de forma +cruzada un paquete para otro sistema: + +@deffn {Procedimiento Scheme} package-cross-derivation @var{almacén} @ + @var{paquete} @var{plataforma} [@var{sistema}] +Devuelve el objeto @code{<derivation>} de @var{paquete} compilado de forma +cruzada desde @var{sistema} a @var{plataforma}. + +@var{plataforma} debe ser una tripleta GNU válida que denote el hardware y +sistema operativo objetivo, como @code{"mips64el-linux-gnu"} +(@pxref{Configuration Names, GNU configuration triplets,, configure, GNU +Configure and Build System}). +@end deffn + +@cindex transformación de paquetes +@cindex reescritura de la entrada +@cindex reescritura del árbol de dependencias +Los paquetes se pueden manipular de forma arbitraria. Un ejemplo de +transformación útil es la @dfn{reescritura de entradas}, donde el árbol de +dependencias de un paquete se reescribe reemplazando entradas específicas +por otras: + +@deffn {Procedimiento Scheme} package-input-rewriting @var{reemplazos} @ + [@var{nombre-reescrito}] +Devuelve un procedimiento que, cuando se le pasa un paquete, reemplaza sus +dependencias directas e indirectas (pero no sus entradas implícitas) de +acuerdo a @var{reemplazos}. @var{reemplazos} es una lista de pares de +paquetes; el primer elemento de cada par es el paquete a reemplazar, el +segundo es el reemplazo. + +Opcionalmente, @var{nombre-reescrito} es un procedimiento de un parámetro +que toma el nombre del paquete y devuelve su nuevo nombre tras la +reescritura. +@end deffn + +@noindent +Considere este ejemplo: + +@example +(define libressl-en-vez-de-openssl + ;; Esto es un procedimiento para reemplazar OPENSSL + ;; por LIBRESSL, recursivamente. + (package-input-rewriting `((,openssl . ,libressl)))) + +(define git-con-libressl + (libressl-en-vez-de-openssl git)) +@end example + +@noindent +Aquí primero definimos un procedimiento de reescritura que substituye +@var{openssl} por @var{libressl}. Una vez hecho esto, lo usamos para definir +una @dfn{variante} del paquete @var{git} que usa @var{libressl} en vez de +@var{openssl}. Esto es exactamente lo que hace la opción de línea de órdenes +@option{--with-input} (@pxref{Opciones de transformación de paquetes, +@option{--with-input}}). + +The following variant of @code{package-input-rewriting} can match packages +to be replaced by name rather than by identity. + +@deffn {Procedimiento Scheme} package-input-rewriting/spec @var{reemplazos} +Return a procedure that, given a package, applies the given +@var{replacements} to all the package graph (excluding implicit inputs). +@var{replacements} is a list of spec/procedures pair; each spec is a package +specification such as @code{"gcc"} or @code{"guile@@2"}, and each procedure +takes a matching package and returns a replacement for that package. +@end deffn + +The example above could be rewritten this way: + +@example +(define libressl-en-vez-de-openssl + ;; Reemplaza todos los paquetes llamados "openssl" con LibreSSL. + (package-input-rewriting/spec `(("openssl" . ,(const libressl))))) +@end example + +The key difference here is that, this time, packages are matched by spec and +not by identity. In other words, any package in the graph that is called +@code{openssl} will be replaced. + +Un procedimiento más genérico para reescribir el grafo de dependencias de un +paquete es @code{package-mapping}: acepta cambios arbitrarios sobre nodos +del grafo. + +@deffn {Scheme Procedure} package-mapping @var{proc} [@var{cortar?}] +Devuelve un procedimiento que, dado un paquete, aplica @var{proc} a todos +los paquetes de los que depende y devuelve el paquete resultante. El +procedimiento para la recursión cuando @var{cortar?} devuelve verdadero para +un paquete dado. +@end deffn + +@menu +* Referencia de ``package'':: El tipo de datos de los paquetes. +* Referencia de ``origin'':: El tipo de datos de orígenes. +@end menu + + +@node Referencia de ``package'' +@subsection Referencia de @code{package} + +Esta sección resume todas las opciones disponibles en declaraciones +@code{package} (@pxref{Definición de paquetes}). + +@deftp {Tipo de datos} package +Este es el tipo de datos que representa la receta de un paquete. + +@table @asis +@item @code{name} +El nombre del paquete, como una cadena. + +@item @code{version} +La versión del paquete, como una cadena. + +@item @code{source} +Un objeto que determina cómo se debería obtener el código fuente del +paquete. La mayor parte del tiempo, es un objeto @code{origin}, que denota +un fichero obtenido de Internet (@pxref{Referencia de ``origin''}). También puede +ser cualquier otro objeto ``tipo-fichero'' como @code{local-file}, que +denota un fichero del sistema local de ficheros (@pxref{Expresiones-G, +@code{local-file}}). + +@item @code{build-system} +El sistema de construcción que debe ser usado para construir el paquete +(@pxref{Sistemas de construcción}). + +@item @code{arguments} (predeterminados: @code{'()}) +Los parámetros que deben ser pasados al sistema de construcción. Es una +lista que normalmente contiene una secuencia de pares de palabra clave y +valor. + +@item @code{inputs} (predeterminadas: @code{'()}) +@itemx @code{native-inputs} (predeterminadas: @code{'()}) +@itemx @code{propagated-inputs} (predeterminadas: @code{'()}) +@cindex entradas, de paquetes +Estos campos enumeran las dependencias del paquete. Cada uno es una lista de +tuplas, donde cada tupla tiene una etiqueta para la entrada (una cadena) +como su primer elemento, un paquete, origen o derivación como su segundo +elemento, y opcionalmente el nombre de la salida que debe ser usada, cuyo +valor predeterminado es @code{"out"} (@pxref{Paquetes con múltiples salidas}, para más información sobre salidas de paquetes). Por ejemplo, la +lista siguiente especifica tres entradas: + +@example +`(("libffi" ,libffi) + ("libunistring" ,libunistring) + ("glib:bin" ,glib "bin")) ;la salida "bin" de Glib +@end example + +@cindex compilación cruzada, dependencias de paquetes +La distinción entre @code{native-inputs} y @code{inputs} es necesaria cuando +se considera la compilación cruzada. Cuando se compila cruzadamente, las +dependencias enumeradas en @code{inputs} son construidas para la +arquitectura @emph{objetivo}; de modo contrario, las dependencias enumeradas +en @code{native-inputs} se construyen para la arquitectura de la máquina de +@emph{construcción}. + +@code{native-inputs} se usa típicamente para enumerar herramientas +necesarias en tiempo de construcción, pero no en tiempo de ejecución, como +Autoconf, Automake, pkg-config, Gettext o Bison. @command{guix lint} puede +informar de probables errores en este área (@pxref{Invocación de guix lint}). + +@anchor{package-propagated-inputs} +Por último, @code{propagated-inputs} es similar a @code{inputs}, pero los +paquetes especificados se instalarán automáticamente junto al paquete al que +pertenecen (@pxref{package-cmd-propagated-inputs, @command{guix package}}, +para información sobre cómo @command{guix package} maneja las entradas +propagadas). + +Por ejemplo esto es necesario cuando una biblioteca C/C++ necesita cabeceras +de otra biblioteca para compilar, o cuando un fichero pkg-config se refiere +a otro @i{via} su campo @code{Requires}. + +Otro ejemplo donde @code{propagated-inputs} es útil es en lenguajes que +carecen de la facilidad de almacenar la ruta de búsqueda de tiempo de +ejecución de la misma manera que el campo @code{RUNPATH} de los ficheros +ELF; esto incluye Guile, Python, Perl y más. Para asegurarse que las +bibliotecas escritas en esos lenguajes puedan encontrar en tiempo de +ejecución el código de las bibliotecas de las que dependen, las dependencias +de tiempo de ejecución deben enumerarse en @code{propagated-inputs} en vez +de en @code{inputs}. + +@item @code{outputs} (predeterminada: @code{'("out")}) +La lista de nombres de salidas del paquete. @xref{Paquetes con múltiples salidas}, para usos típicos de salidas adicionales. + +@item @code{native-search-paths} (predeterminadas: @code{'()}) +@itemx @code{search-paths} (predeterminadas: @code{'()}) +Una lista de objetos @code{search-path-specification} describiendo las +variables de entorno de rutas de búsqueda respetadas por el paquete. + +@item @code{replacement} (predeterminado: @code{1.0}) +Esto debe ser o bien @code{#f} o bien un objeto package que será usado como +@dfn{reemplazo} para ete paquete. @xref{Actualizaciones de seguridad, injertos}, para +más detalles. + +@item @code{synopsis} +Una descripción en una línea del paquete. + +@item @code{description} +Una descripción más elaborada del paquete. + +@item @code{license} +@cindex licencia, de paquetes +La licencia del paquete; un valor de @code{(guix licenses)}, o una lista de +dichos valores. + +@item @code{home-page} +La URL de la página principal del paquete, como una cadena. + +@item @code{supported-systems} (predeterminados: @code{%supported-systems}) +La lista de sistemas en los que se mantiene el paquete, como cadenas de la +forma @code{arquitectura-núcleo}, por ejemplo @code{"x86_64-linux"}. + +@item @code{maintainers} (predeterminadas: @code{'()}) +La lista de responsables del paquete, como objetos @code{maintainer}. + +@item @code{location} (predeterminada: la localización de los fuentes de la forma @code{package}) +La localización de las fuentes del paquete. Es útil forzar su valor cuando +se hereda de otro paquete, en cuyo caso este campo no se corrige +automáticamente. +@end table +@end deftp + +@deffn {Scheme Syntax} this-package +When used in the @emph{lexical scope} of a package field definition, this +identifier resolves to the package being defined. + +The example below shows how to add a package as a native input of itself +when cross-compiling: + +@example +(package + (name "guile") + ;; ... + + ;; When cross-compiled, Guile, for example, depends on + ;; a native version of itself. Add it here. + (native-inputs (if (%current-target-system) + `(("self" ,this-package)) + '()))) +@end example + +It is an error to refer to @code{this-package} outside a package definition. +@end deffn + +@node Referencia de ``origin'' +@subsection Referencia de @code{origin} + +Esta sección resume todas las opciones disponibles en declaraciones +@code{origin} (@pxref{Definición de paquetes}). + +@deftp {Tipo de datos} origin +Este es el tipo de datos que representa un origen de código fuente. + +@table @asis +@item @code{uri} +Un objeto que contiene el URI de las fuentes. El tipo de objeto depende del +valor de @code{method} (véase a continuación). Por ejemplo, cuando se usa el +método @var{url-fetch} de @code{(guix download)}, los valores válidos de +@code{uri} son: una cadena que contiene una URL, o una lista de cadenas. + +@item @code{method} +Un procedimiento que maneja el URI. + +Algunos ejemplos son: + +@table @asis +@item @var{url-fetch} de @code{(guix download)} +descarga un fichero de la URL HTTP, HTTPS o FTP especificada en el campo +@code{uri}; + +@vindex git-fetch +@item @var{git-fetch} de @code{(guix git-download)} +clona el repositorio de control de versiones Git, y prepara la revisión +especificada en el campo @code{uri} como un objeto @code{git-reference}; una +referencia @code{git-reference} tiene esta forma: + +@example +(git-reference + (url "git://git.debian.org/git/pkg-shadow/shadow") + (commit "v4.1.5.1")) +@end example +@end table + +@item @code{sha256} +Un vector de bytes que contiene el hash SHA-256 de las fuentes. Típicamente +la forma @code{base32} se usa aquí para generar el vector de bytes de una +cadena en base-32. + +Puede obtener esta información usando @code{guix download} (@pxref{Invocación de guix download}) o @code{guix hash} (@pxref{Invocación de guix hash}). + +@item @code{file-name} (predeterminado: @code{#f}) +El nombre de fichero bajo el que el código fuente se almacenará. Cuando este +es @code{#f}, un valor predeterminado sensato se usará en la mayor parte de +casos. En caso de que las fuentes se obtengan de una URL, el nombre de +fichero de la URL se usará. Para copias de trabajo de sistemas de control de +versiones, se recomienda proporcionar el nombre de fichero explícitamente ya +que el predeterminado no es muy descriptivo. + +@item @code{patches} (predeterminados: @code{'()}) +Una lista de nombres de ficheros, orígenes u objetos tipo-fichero +(@pxref{Expresiones-G, objetos tipo-fichero}) apuntando a parches que deben +ser aplicados a las fuentes. + +La lista de parches debe ser incondicional. En particular, no puede depender +del varlo de @code{%current-system} o @code{%current-target-system}. + +@item @code{snippet} (predeterminado: @code{#f}) +Una expresión-G (@pxref{Expresiones-G}) o expresión-S que se ejecutará en el +directorio de fuentes. Esta es una forma conveniente de modificar el +software, a veces más que un parche. + +@item @code{patch-flags} (predeterminadas: @code{'("-p1")}) +Una lista de opciones de línea de órdenes que deberían ser pasadas a la +orden @code{patch}. + +@item @code{patch-inputs} (predeterminada: @code{#f}) +Paquetes o derivaciones de entrada al proceso de aplicación de los +parches. Cuando es @code{#f}, se proporciona el conjunto habitual de +entradas necesarias para la aplicación de parches, como GNU@tie{}Patch. + +@item @code{modules} (predeterminados: @code{'()}) +Una lista de módulos Guile que debe ser cargada durante el proceso de +aplicación de parches y mientras se ejecuta el código del campo +@code{snippet}. + +@item @code{patch-guile} (predeterminado: @code{#f}) +El paquete Guile que debe ser usado durante la aplicación de parches. Cuando +es @code{#f} se usa un valor predeterminado. +@end table +@end deftp + + +@node Sistemas de construcción +@section Sistemas de construcción + +@cindex sistema de construcción +Cada definición de paquete especifica un @dfn{sistema de construcción} y +parámetros para dicho sistema de construcción (@pxref{Definición de paquetes}). Este campo @code{build-system} representa el procedimiento de +construcción del paquete, así como las dependencias implícitas de dicho +procedimiento de construcción. + +Los sistemas de construcción son objetos @code{<build-system>}. La interfaz +para crear y manipularlos se proporciona en el módulo @code{(guix +build-system)}, y otros módulos exportan sistemas de construcción reales. + +@cindex bag (representación de paquetes de bajo nivel) +En su implementación, los sistemas de construcción primero compilan los +objetos package a objetos @dfn{bag}. Una bolsa (traducción de @dfn{bag}) es +como un paquete, pero con menos ornamentos---en otras palabras, una bolsa es +una representación a un nivel más bajo de un paquete, que contiene todas las +entradas de dicho paquete, incluyendo algunas implícitamente añadidas por el +sistema de construcción. Esta representación intermedia se compila entonces +a una derivación (@pxref{Derivaciones}). + +Los sistemas de construcción aceptan una lista opcional de +@dfn{parámetros}. En las definiciones de paquete, estos son pasados @i{vía} +el campo @code{arguments} (@pxref{Definición de paquetes}). Normalmente son +parámetros con palabras clave (@pxref{Optional Arguments, keyword arguments +in Guile,, guile, GNU Guile Reference Manual}). El valor de estos parámetros +normalmente se evalúa en la @dfn{capa de construcción}---es decir, por un +proceso Guile lanzado por el daemon (@pxref{Derivaciones}). + +El sistema de construcción principal es @var{gnu-build-system}, el cual +implementa el procedimiento estándar de construcción para GNU y muchos otros +paquetes. Se proporciona por el módulo @code{(guix build-system gnu)}. + +@defvr {Variable Scheme} gnu-build-system +@var{gnu-build-system} representa el sistema de construcción GNU y sus +variantes (@pxref{Configuration, configuration and makefile conventions,, +standards, GNU Coding Standards}). + +@cindex fases de construcción +En resumen, los paquetes que lo usan se configuran, construyen e instalan +con la habitual secuencia de órdenes @code{./configure && make && make check +&& make install}. En la práctica, algunos pasos adicionales son necesarios +habitualmente. Todos estos pasos se dividen en @dfn{fases} separadas, +notablemente@footnote{Rogamos que se inspeccionen los módulos @code{(guix +build gnu-build-system)} para más detalles sobre las fases de construcción}: + +@table @code +@item unpack +Extrae el archivador tar de la fuente, y cambia el directorio actual al +directorio recién extraído. Si la fuente es realmente un directorio, lo +copia al árbol de construcción y entra en ese directorio. + +@item patch-source-shebangs +Sustituye secuencias ``#!'' encontradas al inicio de los ficheros de fuentes +para que hagan referencia a los nombres correctos de ficheros del +almacén. Por ejemplo, esto cambia @code{#!/bin/sh} por +@code{#!/gnu/store/@dots{}-bash-4.3/bin/sh}. + +@item configure +Ejecuta el guión @file{configure} con algunas opciones predeterminadas, como +@code{--prefix=/gnu/store/@dots{}}, así como las opciones especificadas por +el parámetro @code{#:configure-flags}. + +@item build +Ejecuta @code{make} con la lista de opciones especificadas en +@code{#:make-flags}. Si el parámetro @code{#:parallel-build?} es verdadero +(por defecto), construye con @code{make -j}. + +@item check +Ejecuta @code{make check}, u otro objetivo especificado con +@code{#:test-target}, a menos que se pasase @code{#:tests? #f}. Si el +parámetro @code{#:parallel-tests?} es verdadero (por defecto), ejecuta +@code{make check -j}. + +@item install +Ejecuta @code{make install} con las opciones enumeradas en +@code{#:make-flags}. + +@item patch-shebangs +Sustituye las secuencias ``#!'' en los ficheros ejecutables instalados. + +@item strip +Extrae los símbolos de depuración de ficheros ELF (a menos que el valor de +@code{#:strip-binaries?} sea falso), copiandolos a la salida @code{debug} +cuando esté disponible (@pxref{Instalación de ficheros de depuración}). +@end table + +@vindex %standard-phases +El módulo del lado de construcción @code{(guix build gnu-build-system)} +define @var{%standard-phases} como la lista predeterminada de fases de +construcción. @var{%standard-phases} es una lista de pares +símbolo/procedimiento, donde el procedimiento implementa la fase real. + +La lista de fases usadas para un paquete particular se puede cambiar con el +parámetro @code{#:phases}. Por ejemplo, pasar: + +@example +#:phases (modify-phases %standard-phases (delete 'configure)) +@end example + +significa que todas las fases descritas anteriormente serán usadas, excepto +la fase @code{configure}. + +Además, este sistema de construcción asegura que el entorno ``estándar'' +para paquetes GNU está disponible. Esto incluye herramientas como GCC, libc, +Coreutils, Bash, Make, Diffutils, grep y sed (vea el módulo @code{(guix +build system gnu)} para una lista completa). A estas las llamamos las +@dfn{entradas implícitas} de un paquete, porque las definiciones de paquete +no las mencionan. +@end defvr + +Se han definido otros objetos @code{<build-system>} para implementar otras +convenciones y herramientas usadas por paquetes de software libre. Heredan +la mayor parte de @var{gnu-build-system}, y se diferencian principalmente en +el conjunto de entradas implícitamente añadidas al proceso de construcción, +y en la lista de fases ejecutadas. Algunos de estos sistemas de construcción +se enumeran a continuación. + +@defvr {Variable Scheme} ant-build-system +@code{(guix build-system ant)} exporta esta variable. Implementa el +procedimiento de construcción de paquetes Java que pueden construirse con +@url{http://ant.apache.org/, la herramienta de construcción Ant}. + +Añade tanto @code{ant} como el @dfn{kit de desarrollo Java} (JDK), que +proporciona el paquete @code{icedtea}, al conjunto de entradas. Se pueden +especificar paquetes diferentes con los parámetros @code{#:ant} y +@code{#:jdk}, respectivamente. + +Cuando el paquete original no proporciona un fichero Ant apropiado, el +parámetro @code{#:jar-name} puede usarse para generar un fichero de +construcción Ant @file{build.xml} mínimo con tareas para construir el +archivo jar especificado. En este caso, el parámetro @code{#:source-dir} se +puede usar para especificar el subdirectorio de fuentes, con ``src'' como +valor predeterminado. + +El parámetro @code{#:main-class} puede usarse con el fichero de construcción +Ant mínimo para especificar la clase main del archivo jar producido. Esto +permite ejecutar el archivo jar. El parámetro @code{#:test-include} puede +usarse para especificar la lista de tests junit a ejecutar. El valor +predeterminado es @code{(list "**/*Test.java")}. @code{#:test-exclude} puede +usarse para desactivar algunas pruebas. Su valor predeterminado es +@code{(list "**/Abstract*.java")} ya que las clases abstractas no se pueden +ejecutar como pruebas. + +El parámetro @code{#:build-target} se puede usar para especificar la tarea +Ant que debe ser ejecutada durante la fase @code{build}. Por defecto se +ejecuta la tarea ``jar''. + +@end defvr + +@defvr {Variable Scheme} androd-ndk-build-system +@cindex distribución Android +@cindex Sistema de construcción NDK de Android +Esta variable es exportada por @code{(guix build-system +android-ndk)}. Implementa un procedimiento de construcción para paquetes +Android NDK (kit de desarrollo nativo) usando un proceso de construcción +específico de Guix. + +El sistema de construcción asume que los paquetes instalan sus ficheros de +interfaz pública (cabeceras) en el subdirectorio "include" de la salida +"out" y sus bibliotecas en el subdirectorio "lib" de la salida "out". + +También se asume que la unión de todas las dependencias de un paquete no +tiene ficheros en conflicto. + +En este momento no funciona la compilación cruzada - por lo que las +bibliotecas y los ficheros de cabecera se asumen que son locales. + +@end defvr + +@defvr {Variable Scheme} asdf-build-system/source +@defvrx {Variable Scheme} asdf-build-system/sbcl +@defvrx {Variable Scheme} asdf-build-system/ecl + +Estas variables, exportadas por @code{(guix build-system asdf)}, implementan +procedimientos de construcción para paquetes Common Lisp usando +@url{https://common-lisp.net/project/asdf, ``ASDF'''}. ASDF es una utilidad +de definición de sistema para programas y bibliotecas Common Lisp. + +El sistema @code{asdf-build-system/source} instala los paquetes en forma de +fuentes, y puede ser cargado usando cualquier implementación common lisp, +vía ASDF. Los otros, como @code{asdf-build-system/sbcl}, instalan sistemas +binarios en el formato entendido por una implementación particular. Estos +sistemas de construcción también pueden usarse para producir programas +ejecutables, o imágenes lisp que contengan un conjunto precargado de +paquetes. + +El sistema de construcción usa convenciones de nombres. Para paquetes +binarios, el paquete debería estar prefijado con la implementación lisp, +como @code{sbcl-} para @code{asdf-build-system/sbcl}. + +Adicionalmente, el paquete de fuentes correspondiente debe etiquetarse +usando la misma convención que los paquetes python (vea @ref{Módulos Python}), usando el prefijo @code{cl-}. + +Para paquetes binarios, cada sistema debe definirse como un paquete Guix. Si +el campo @code{origin} de un paquete contiene varios sistemas, las +variaciones del paquete pueden crearse para construir todos los +sistemas. Los paquetes de fuentes, los cuales usan +@code{asdf-build-system/source}, pueden contener varios sistemas. + +Para crear programa ejecutables e imágenes, se pueden usar los +procedimientos del lado de construcción @code{build-program} y +@code{build-image}. Deben llamarse en la fase de construcción después de la +fase @code{create-symlinks}, de modo que el sistema recién construido pueda +ser usado dentro de la imagen resultante. @code{build-program} necesita una +lista de expresiones Common Lisp a través del parámetro +@code{#:entry-prgogram}. + +Si el sistema no está definido en su propio fichero @code{.asd} del mismo +nombre, entonces se debe usar el parámetro @code{#:asd-file} para +especificar el fichero en el que se define el sistema. Más allá, si el +paquete define un sistema para sus pruebas en su fichero separado, se +cargará antes de la ejecución de las pruebas si se especifica el parámetro +@code{#:test-asd-file}. Si no se especifica, se probarán si existen los +ficheros @code{<sistema>-tests.asd}, @code{<system>-test.asd}, +@code{tests.asd} y @code{test.asd}. + +Si por alguna razón el paquete debe ser nombrado de una forma diferente a la +sugerida por las convenciones de nombres, el parámetro +@code{#:asd-system-name} puede usarse para especificar el nombre del +sistema. + +@end defvr + +@defvr {Variable Scheme} cargo-build-system +@cindex lenguaje de programación Rust +@cindex Cargo (sistema de construcción de Rust) +Esta variable se exporta en @code{(guix build-system cargo)}. Permite la +construcción de paquetes usando Cargo, la herramienta de construcción del +@uref{https://www.rust-lang.org, lenguaje de programación Rust}. + +En su fase @code{configure}, este sistema de construcción substituye las +dependencias especificadas en el fichero @file{Cargo.toml} con entradas a +los paquetes Guix. La fase @code{install} instala los binarios, y también +instala el código fuente y el fichero @file{Cargo.toml}. +@end defvr + +@cindex Clojure (lenguaje de programación) +@cindex sistema de construcción simple de Clojure +@defvr {Variable Scheme} clojure-build-system +Esta variable se exporta en @code{(guix build-system clojure)}. Implementa +un procedimiento de construcción simple para paquetes +@uref{https://clojure.org/, Clojure} usando directamente @code{compile} en +Clojure. La compilación cruzada no está disponible todavía. + +Añade @code{clojure}, @code{icedtea} y @code{zip} al conjunto de +entradas. Se pueden especificar paquetes diferentes con los parámetros +@code{#:clojure}, @code{#:jdk} y @code{#:zip}, respectivamente. + +Una lista de directorios de fuentes, directorios de pruebas y nombres de jar +pueden especificarse con los parámetros @code{#:source-dirs}, +@code{#:test-dirs} y @code{#:jar-names}, respectivamente. El directorio de +compilación y la clase principal pueden especificarse con los parámetros +@code{#:compile-dir} y @code{#:main-class}, respectivamente. Otros +parámetros se documentan más adelante. + +Este sistema de construcción es una extensión de @var{ant-build-system}, +pero con las siguientes fases cambiadas: + +@table @code + +@item build +Esta fase llama @code{compile} en Clojure para compilar los ficheros de +fuentes y ejecuta @command{jar} para crear archivadores jar tanto de +ficheros de fuentes y compilados de acuerdo con las listas de inclusión y +exclusión especificadas en @code{#:aot-include} y @code{#:aot-exclude}, +respectivamente. La lista de exclusión tiene prioridad sobre la de +inclusión. Estas listas consisten en símbolos que representan bibliotecas +Clojure o la palabra clave especial @code{#:all} que representa todas las +bibliotecas encontradas en los directorios de fuentes. El parámetro +@code{#:omit-source?} determina si las fuentes deben incluirse en los +archivadores jar. + +@item check +Esta fase ejecuta las pruebas de acuerdo a las listas de inclusión y +exclusión especificadas en @code{#:test-include} y @code{#:test-exclude}, +respectivamente. Sus significados son análogos a los de @code{#:aot-include} +y @code{#:aot-exclude}, excepto que la palabra clave especial @code{#:all} +designa ahora a todas las bibliotecas Clojure encontradas en los directorios +de pruebas. El parámetro @code{#:tests?} determina si se deben ejecutar las +pruebas. + +@item install +Esta fase instala todos los archivadores jar construidos previamente. +@end table + +Además de las previas, este sistema de construcción contiene una fase +adicional: + +@table @code + +@item install-doc +Esta fase instala todos los ficheros de nivel superior con un nombre que +corresponda con @var{%doc-regex}. Una expresión regular diferente se puede +especificar con el parámetro @code{#:doc-regex}. Todos los ficheros dentro +(recursivamente) de los directorios de documentación especificados en +@code{#:doc-dirs} se instalan también. +@end table +@end defvr + +@defvr {Variable Scheme} cmake-build-system +Esta variable se exporta en @code{(guix build-system cmake)}. Implementa el +procedimiento de construcción para paquetes que usen la +@url{http://www.cmake.org, herramienta de construcción CMake}. + +Automáticamente añade el paquete @code{cmake} al conjunto de entradas. El +paquete usado se puede especificar con el parámetro @code{#:cmake}. + +El parámetro @code{#:configure-flags} se toma como una lista de opciones a +pasar a @command{cmake}. El parámetro @code{#:build-type} especifica en +términos abstractos las opciones pasadas al compilador; su valor +predeterminado es @code{"RelWithDebInfo"} (quiere decir ``modo de entrega +con información de depuración''), lo que aproximadamente significa que el +código se compila con @code{-O2 -g}, lo cual es el caso predeterminado en +paquetes basados en Autoconf. +@end defvr + +@defvr {Variable Scheme} dune-build-system +This variable is exported by @code{(guix build-system dune)}. It supports +builds of packages using @uref{https://dune.build/, Dune}, a build tool for +the OCaml programming language. It is implemented as an extension of the +@code{ocaml-build-system} which is described below. As such, the +@code{#:ocaml} and @code{#:findlib} parameters can be passed to this build +system. + +Automáticamente añade el paquete @code{dune} al conjunto de entradas. El +paquete usado se puede especificar con el parámetro @code{#:dune}. + +There is no @code{configure} phase because dune packages typically don't +need to be configured. The @code{#:build-flags} parameter is taken as a +list of flags passed to the @code{dune} command during the build. + +The @code{#:jbuild?} parameter can be passed to use the @code{jbuild} +command instead of the more recent @code{dune} command while building a +package. Its default value is @code{#f}. + +The @code{#:package} parameter can be passed to specify a package name, +which is useful when a package contains multiple packages and you want to +build only one of them. This is equivalent to passing the @code{-p} +argument to @code{dune}. +@end defvr + +@defvr {Variable Scheme} go-build-system +Esta variable se exporta en @code{(guix build-system go)}. Implementa el +procedimiento de construcción para paquetes Go usando los +@url{https://golang.org/cmd/go/#hdr-Compile_packages_and_dependencies, +mecanismos de construcción de Go} estándares. + +Se espera que la usuaria proporcione un valor para el parámetro +@code{#:import-path} y, en algunos caso, @code{#:unpack-path}. La +@url{https://golang.org/doc/code.html#ImportPaths, ruta de importación} +corresponde a la ruta del sistema de ficheros esperada por los guiones de +construcción del paquete y los paquetes referenciados, y proporciona una +forma de referenciar un paquete Go unívocamente. Está basado típicamente en +una combinación de la URI remota del paquete de ficheros de fuente y la +estructura jerárquica del sistema de ficheros. En algunos casos, necesitará +desempaquetar el código fuente del paquete en una estructura de directorios +diferente a la indicada en la ruta de importación, y @code{#:unpack-path} +debe usarse en dichos casos. + +Los paquetes que proporcionan bibliotecas Go deben instalar su código fuente +en la salida de la construcción. El parámetro @code{#:install-source?}, cuyo +valor por defecto es @code{#t}, controla si se instalará o no el código +fuente. Puede proporcionarse @code{#f} en paquetes que proporcionan +únicamente ficheros ejecutables. +@end defvr + +@defvr {Variable Scheme} glib-or-gtk-build-system +Esta variable se exporta en @code{(guix build-system glib-or-gtk)}. Está +pensada para usarse con paquetes que usan GLib o GTK+. + +Este sistema de construcción añade las siguientes dos fases a las definidas +en @var{gnu-build-system}: + +@table @code +@item glib-or-gtk-wrap +La fase @code{glib-or-gtk-wrap} se asegura de que los programas en +@file{bin/} son capaces de encontrar los ``esquemas'' GLib y los +@uref{https://developer.gnome.org/gtk3/stable/gtk-running.html, módulos +GTK+}. Esto se consigue recubriendo los programas en guiones de lanzamiento +que establecen apropiadamente las variables de entorno @code{GTK_PATH}. + +Es posible excluir salidas específicas del paquete del proceso de +recubrimiento enumerando sus nombres en el parámetro +@code{#:glib-org-gtk-wrap-excluded-outputs}. Esto es útil cuando se sabe que +una salida no contiene binarios GLib o GTK+, y cuando empaquetar +gratuitamente añadiría una dependencia de dicha salida en GLib y GTK+. + +@item glib-or-gtk-compile-schemas +La fase @code{glib-or-gtk-compile-schemas} se asegura que todos los +@uref{https://developer.gnome.org/gio/stable/glib-compile-schemas.html, +esquemas GSettings} o GLib se compilan. La compilación la realiza el +programa @command{glib-compile-schemas}. Lo proporciona el paquete +@code{glib:bin} que se importa automáticamente por el sistema de +construcción. El paquete @code{glib} que proporciona +@command{glib-compile-schemas} puede especificarse con el parámetro +@code{#:glib}. +@end table + +Ambas fases se ejecutan tras la fase @code{install}. +@end defvr + +@defvr {Variable Scheme} guile-build-system +Este sistema de construcción es para paquetes Guile que consisten +exclusivamente en código Scheme y son tan simples que no tienen ni siquiera +un fichero Makefile, menos un guión @file{configure}. Compila código Scheme +usando @command{guild compile} (@pxref{Compilation,,, guile, GNU Guile +Reference Manual}) e instala los ficheros @file{.scm} y @file{.go} en el +lugar correcto. También instala documentación. + +Este sistema de construcción permite la compilación cruzada usando la opción +@code{--target} de @command{guild compile}. + +Los paquetes construidos con @code{guile-build-system} deben proporcionar un +paquete Guile en su campo @code{native-inputs}. +@end defvr + +@defvr {Variable Scheme} minify-build-system +Esta variable se exporta en @code{(guix build-system minify)}. Implementa un +procedimiento de minificación para paquetes JavaScript simples. + +Añade @code{uglify-js} al conjunto de entradas y lo utiliza para comprimir +todos los ficheros JavaScript en el directorio @file{src}. Un paquete de +minificación diferente puede especificarse con el parámetro +@code{#:uglify-js}, pero se espera que el paquete escriba el código +minificado en la salida estándar. + +Cuando los ficheros JavaScript de entrada no se encuentran en el directorio +@file{src}, el parámetro @code{#:javascript-files} puede usarse para +especificar una lista de nombres de fichero que proporcionar al minificador. +@end defvr + +@defvr {Variable Scheme} ocaml-build-system +Esta variable se exporta en @code{(guix build-system ocaml)}. Implementa un +procedimiento de construcción para paquetes @uref{https://ocaml.org, OCaml}, +que consiste en seleccionar el conjunto correcto de órdenes a ejecutar para +cada paquete. Los paquetes OCaml pueden esperar la ejecución de muchas +ordenes diferentes. Este sistema de construcción probará algunas de ellas. + +Cuando el paquete tiene un fichero @file{setup.ml} presente en el nivel +superior, se ejecuta @code{ocaml setup.ml -configure}, @code{ocaml setup.ml +-build} y @code{ocaml setup.ml -install}. El sistema de construcción asumirá +que este fichero se generó con @uref{http://oasis.forge.ocamlcore.org/ +OASIS} y se encargará de establecer el prefijo y la habilitación de las +pruebas si no están deshabilitadas. Puede pasar opciones de configuración y +construcción con @code{#:configure-flags} y @code{#:build-flags}, +respectivamente. El parámetro @code{#:test-flags} puede usarse para cambiar +el conjunto de opciones usadas para activar las pruebas. El parámetro +@code{#:use-make?} puede usarse para ignorar este sistema en las fases de +construcción e instalación. + +Cuando el paquete tiene un fichero @file{configure}, se asume que es un +guión de configuración hecho a mano que necesita un formato de parámetros +diferente a los del sistema @code{gnu-build-system}. Puede añadir más +opciones con el parámetro @code{#:configure-flags}. + +Cuando el paquete tiene un fichero @file{Makefile} (o @code{#:use-make?} es +@code{#t}), será usado y se pueden proporcionar más opciones para las fases +de construcción y e instalación con el parámetro @code{#:make-flags}. + +Por último, algunos paquetes no tienen estos ficheros y usan unas +localizaciones de algún modo estándares para su sistema de construcción. En +este caso, el sistema de construcción ejecutará @code{ocaml pkg/pkg.ml} o +@code{ocaml pkg/build.ml} y se hará cargo de proporcionar la ruta del módulo +findlib necesario. Se pueden pasar opciones adicionales con el parámetro +@code{#:build-flags}. De la instalación se hace cargo +@command{opam-installer}. En este caso, el paquete @code{opam} debe añadirse +al campo @code{native-inputs} de la definición del paquete. + +Fíjese que la mayoría de los paquetes OCaml asumen su instalación en el +mismo directorio que OCaml, que no es el comportamiento deseado en guix. En +particular, intentarán instalar ficheros @file{.so} en su directorio de +módulos, normalmente lo adecuado puesto que es el directorio del compilador +de OCaml. No obstante, en guix estas bibliotecas no se pueden encontrar allí +y usamos @code{CAML_LD_LIBRARY_PATH}. Esta variable apunta a +@file{lib/ocaml/site-lib/stubslibs} y allí es donde las bibliotecas +@file{.so} deben instalarse. +@end defvr + +@defvr {Variable Scheme} python-build-system +Esta variable se exporta en @code{(guix build-system python)}. Implementa el +procedimiento más o menos estándar de construcción usado por paquetes +Python, que consiste en la ejecución de @code{python setup.py build} y +@code{python setup.py install --prefix=/gnu/store/@dots{}}. + +Para que instalan programas independientes Python bajo @code{bin/}, se +encarga de envolver dichos programas de modo que su variable de entorno +@code{PYTHONPATH} apunte a las bibliotecas Python de las que dependen. + +Se puede especificar el paquete Python usado para llevar a cabo la +construcción con el parámetro @code{#:python}. Esta es habitualmente una +forma de forzar la construcción de un paquete para una versión específica +del intérprete Python, lo que puede ser necesario si el paquete es +compatible únicamente con una versión del intérprete. + +Por defecto guix llama a @code{setup.py} bajo el control de +@code{setuptools} de manera similar a @command{pip}. Algunos paquetes no son +compatibles con setuptools (y pip), por lo que puede deshabilitar esta +configuración estableciendo el parámetro @code{#:use-setuptools} a +@code{#f}. +@end defvr + +@defvr {Variable Scheme} perl-build-system +Esta variable se exporta en @code{(guix build-system perl)}. Implementa el +procedimiento de construcción estándar para paquetes Perl, lo que o bien +consiste en la ejecución de @code{perl Build.PL +--prefix=/gnu/store/@dots{}}, seguido de @code{Build} y @code{Build +install}; o en la ejecución de @code{perl Makefile.PL +PREFIX=/gnu/store/@dots{}}, seguida de @code{make} y @code{make install}, +dependiendo de si @code{Build.PL} o @code{Makefile.PL} están presentes en la +distribución del paquete. El primero tiene preferencia si existen tanto +@code{Build.PL} como @code{Makefile.PL} en la distribución del paquete. Esta +preferencia puede invertirse especificando @code{#t} en el parámetro +@code{#:make-maker?}. + +La invocación inicial de @code{perl Makefile.PL} o @code{perl Build.PL} pasa +a su vez las opciones especificadas por los parámetros +@code{#:make-maker-flags} o @code{#:module-build-flags}, respectivamente. + +El paquete Perl usado puede especificarse con @code{#:perl}. +@end defvr + +@defvr {Variable Scheme} r-build-system +Esta variable se exporta en @code{(guix build-system r)}. Implementa el +procedimiento de construcción usados por paquetes +@uref{http://r-project.org, R}, lo que esencialmente es poco más que la +ejecución de @code{R CMD INSTALL --library=/gnu/store/@dots{}} en un entorno +donde @code{R_LIBS_SITE} contiene las rutas de todos los paquetes R de +entrada. Las pruebas se ejecutan tras la instalación usando la función R +@code{tools::testInstalledPackage}. +@end defvr + +@defvr {Variable Scheme} rakudo-build-system +This variable is exported by @code{(guix build-system rakudo)} It implements +the build procedure used by @uref{https://rakudo.org/, Rakudo} for +@uref{https://perl6.org/, Perl6} packages. It installs the package to +@code{/gnu/store/@dots{}/NAME-VERSION/share/perl6} and installs the +binaries, library files and the resources, as well as wrap the files under +the @code{bin/} directory. Tests can be skipped by passing @code{#f} to the +@code{tests?} parameter. + +Which rakudo package is used can be specified with @code{rakudo}. Which +perl6-tap-harness package used for the tests can be specified with +@code{#:prove6} or removed by passing @code{#f} to the @code{with-prove6?} +parameter. Which perl6-zef package used for tests and installing can be +specified with @code{#:zef} or removed by passing @code{#f} to the +@code{with-zef?} parameter. +@end defvr + +@defvr {Variable Scheme} texlive-build-system +Esta variable se exporta en @code{(guix build-system texlive)}. Se usa para +construir paquetes TeX en modo de procesamiento de lotes con el motor +especificado. El sistema de construcción fija la variable @code{TEXINPUTS} +para encontrar todos los ficheros de fuentes TeX en las entradas. + +Por defecto ejecuta @code{luatex} en todos los ficheros que terminan en +@code{ins}. Un motor y formato diferente puede especificarse con el +parámetro @code{#:tex-format}. Los diferentes objetivos de construcción +pueden especificarse con el parámetro @code{#:build-targets}, que espera una +lista de nombres de fichero. El sistema de construcción añade únicamente +@code{texlive-bin} y @code{texlive-latex-base} (ambos desde @code{(gnu +packages tex)} a las entradas. Ambos pueden forzarse con los parámetros +@code{#:texlive-bin} y @code{#:texlive-latex-base} respectivamente. + +El parámetro @code{#:tex-directory} le dice al sistema de construcción dónde +instalar los ficheros construidos bajo el árbol texmf. +@end defvr + +@defvr {Variable Scheme} ruby-build-system +Esta variable se exporta en @code{(guix build-system ruby)}. Implementa el +procedimiento de construcción de RubyGems usado por los paquetes Ruby, que +implica la ejecución de @code{gem build} seguida de @code{gem install}. + +El campo @code{source} de un paquete que usa este sistema de construcción +típicamente se refiere a un archivo gem, ya que este es el formato usado por +las desarrolladoras Ruby cuando publican su software. El sistema de +construcción desempaqueta el archivo gem, potencialmente parchea las +fuentes, ejecuta la batería de pruebas, vuelve a empaquetar el archivo gem y +lo instala. Adicionalmente, directorios y archivadores tar pueden +referenciarse para permitir la construcción de archivos gem no publicados +desde Git o un archivador tar de publicación de fuentes tradicional. + +Se puede especificar el paquete Ruby usado mediante el parámetro +@code{#:ruby}. Una lista de opciones adicionales pueden pasarse a la orden +@command{gem} en el parámetro @code{#:gem-flags}. +@end defvr + +@defvr {Variable Scheme} waf-build-system +Esta variable se exporta en @code{(guix build-system waf)}. Implementa un +procedimiento de construcción alrededor del guión @code{waf}. Las fases +comunes---@code{configure}, @code{build} y @code{install}---se implementan +pasando sus nombres como parámetros al guión @code{waf}. + +El guión @code{waf} es ejecutado por el intérprete Python. El paquete Python +usado para la ejecución puede ser especificado con el parámetro +@code{#:python}. +@end defvr + +@defvr {Variable Scheme} scons-build-system +Esta variable se exporta en @code{(guix build-system scons)}. Implementa en +procedimiento de construcción usado por la herramienta de construcción de +software SCons. Este sistema de construcción ejecuta @code{scons} para +construir el paquete, @code{scons test} para ejecutar las pruebas y después +@code{scons install} para instalar el paquete. + +Las opciones adicionales a pasar a @code{scons} se pueden especificar con el +parámetro @code{#:scons-flags}. La versión de Python usada para ejecutar +SCons puede especificarse seleccionando el paquete SCons apropiado con el +parámetro @code{#:scons}. +@end defvr + +@defvr {Variable Scheme} haskell-build-system +Esta variable se exporta en @code{(guix build-system haskell)}. Implementa +el procedimiento de construcción Cabal usado por paquetes Haskell, el cual +implica la ejecución de @code{runhaskell Setup.hs configure +--prefix=/gnu/store/@dots{}} y @code{runhaskell Setup.hs build}. En vez de +instalar el paquete ejecutando @code{runhaskell Setup.hs install}, para +evitar el intento de registro de bibliotecas en el directorio de +solo-lectura del compilador en el almacén, el sistema de construcción usa +@code{runhaskell Setup.hs copy}, seguido de @code{runhaskell Setup.hs +register}. Además, el sistema de construcción genera la documentación del +paquete ejecutando @code{runhaskell Setup.hs haddock}, a menos que se pasase +@code{#:haddock? #f}. Parámetros opcionales de Haddock pueden proporcionarse +con la ayuda del parámetro @code{#:haddock-flags}. Si el fichero +@code{Setup.hs} no es encontrado, el sistema de construcción busca +@code{Setup.lhs} a su vez. + +El compilador Haskell usado puede especificarse con el parámetro +@code{#:haskell} cuyo valor predeterminado es @code{ghc}. +@end defvr + +@defvr {Variable Scheme} dub-build-system +Esta variable se exporta en @code{(guix build-system dub)}. Implementa el +procedimiento de construcción Dub usado por los paquetes D, que implica la +ejecución de @code{dub build} y @code{dub run}. La instalación se lleva a +cabo con la copia manual de los ficheros. + +El compilador D usado puede ser especificado con el parámetro @code{#:ldc} +cuyo valor predeterminado es @code{ldc}. +@end defvr + +@defvr {Variable Scheme} emacs-build-system +Esta variable se exporta en @code{(guix build-system emacs)}. Implementa un +procedimiento de instalación similar al propio sistema de empaquetado de +Emacs (@pxref{Packages,,, emacs, The GNU Emacs Manual}). + +Primero crea el fichero @code{@var{paquete}-autoloads.el}, tras lo que +compila todos los ficheros Emacs Lisp. De manera diferente al sistema de +paquetes de Emacs, los ficheros de documentación Info se mueven al +directorio estándar de documentación y se borra el fichero @file{dir}. Cada +paquete se instala en su propio directorio bajo +@file{share/emacs/site-lisp/guix.d}. +@end defvr + +@defvr {Variable Scheme} font-build-system +Esta variable se exporta en @code{(guix build-system font)}. Implementa un +procedimiento de instalación para paquetes de fuentes donde las proveedoras +originales proporcionan ficheros de tipografía TrueType, OpenType, etc.@: +precompilados que simplemente necesitan copiarse en su lugar. Copia los +ficheros de tipografías a las localizaciones estándar en el directorio de +salida. +@end defvr + +@defvr {Variable Scheme} meson-build-system +Esta variable se exporta en @code{(guix build-system meson)}. Implementa el +procedimiento de construcción para paquetes que usan +@url{http://mesonbuild.com, Meson} como su sistema de construcción. + +Añade Meson y @uref{https://ninja-build.org/, Ninja} al conjunto de +entradas, y pueden cambiarse con los parámetros @code{#:meson} y +@code{#:ninja} en caso necesario. La versión de Meson predeterminada es +@code{meson-for-build}, la cual es especial puesto que no limpia el +@code{RUNPATH} de los binarios y bibliotecas durante la instalación. + +Este sistema de construcción es una extensión de @var{gnu-build-system}, +pero con las siguientes fases cambiadas por otras específicas para Meson. + +@table @code + +@item configure +Esta fase ejecuta @code{meson} con las opciones especificadas en +@code{#:configure-flags}. La opción @code{--build-type} siempre se fija a +@code{plain} a menos que se especifique algo distinto en +@code{#:build-type}. + +@item build +Esta fase ejecuta @code{ninja} para construir el paquete en paralelo por +defecto, pero esto puede cambiarse con @code{#:parallel-build?}. + +@item check +Esta fase ejecuta @code{ninja} con el objetivo especificado en +@code{#:test-target}, cuyo valor predeterminado es @code{"test"}. + +@item install +Esta fase ejecuta @code{ninja install} y no puede cambiarse. +@end table + +Aparte de estas, el sistema de ejecución también añade las siguientes fases: + +@table @code + +@item fix-runpath +Esta fase se asegura de que todos los binarios pueden encontrar las +bibliotecas que necesitan. Busca las bibliotecas necesarias en +subdirectorios del paquete en construcción, y añade estas a @code{RUNPATH} +en caso necesario. También elimina referencias a bibliotecas introducidas en +la fase de construcción por @code{meson-for-build}, como las dependencias de +las pruebas, que no se necesitan realmente para la ejecución del programa. + +@item glib-or-gtk-wrap +Esta fase es la fase proporcionada por @code{glib-or-gtk-build-system}, y no +está activa por defecto. Puede activarse con @code{#:glib-or-gtk}. + +@item glib-or-gtk-compile-schemas +Esta fase es la fase proporcionada por @code{glib-or-gtk-build-system}, y no +está activa por defecto. Puede activarse con @code{#:glib-or-gtk}. +@end table +@end defvr + +@defvr {Scheme Variable} linux-module-build-system +@var{linux-module-build-system} allows building Linux kernel modules. + +@cindex fases de construcción +This build system is an extension of @var{gnu-build-system}, but with the +following phases changed: + +@table @code + +@item configure +This phase configures the environment so that the Linux kernel's Makefile +can be used to build the external kernel module. + +@item build +This phase uses the Linux kernel's Makefile in order to build the external +kernel module. + +@item install +This phase uses the Linux kernel's Makefile in order to install the external +kernel module. +@end table + +It is possible and useful to specify the Linux kernel to use for building +the module (in the "arguments" form of a package using the +linux-module-build-system, use the key #:linux to specify it). +@end defvr + +Por último, para paquetes que no necesiten nada tan sofisticado se +proporciona un sistema de construcción ``trivial''. Es trivial en el sentido +de que no proporciona prácticamente funcionalidad: no incorpora entradas +implícitas y no tiene una noción de fases de construcción. + +@defvr {Variable Scheme} trivial-build-system +Esta variable se exporta en @code{(guix build-system trivial)}. + +Este sistema de construcción necesita un parámetro @code{#:builder}. Este +parámetro debe ser una expresión Scheme que construya la(s) salida(s) del +paquete---como en @code{build-expression->derivation} (@pxref{Derivaciones, +@code{build-expression->derivation}}). +@end defvr + +@node El almacén +@section El almacén + +@cindex almacén +@cindex elementos del almacén +@cindex rutas del almacén + +Conceptualmente, el @dfn{almacén} es el lugar donde se almacenan las +derivaciones cuya construcción fue satisfactoria---por defecto, +@file{/gnu/store}. Los subdirectorios en el almacén se denominan +@dfn{elementos del almacén} o @dfn{rutas del almacén} en ocasiones. El +almacén tiene una base de datos asociada que contiene información como las +rutas del almacén a las que referencia cada ruta del almacén, y la lista de +elementos @emph{válidos} del almacén---los resultados de las construcciones +satisfactorias. Esta base de datos reside en +@file{@var{localstatedir}/guix/db}, donde @var{localstatedir} es el +directorio de estado especificado @i{vía} @option{--localstatedir} en tiempo +de configuración, normalmente @file{/var}. + +El almacén @emph{siempre} es accedido a través del daemon en delegación de +sus clientes (@pxref{Invocación de guix-daemon}). Para manipular el almacén, los +clientes se conectan al daemon por un socket de dominio Unix, le envían +peticiones y leen el resultado---esto son llamadas a procedimientos remotos, +o RPC. + +@quotation Nota +Las usuarias @emph{nunca} deben modificar ficheros directamente bajo el +directorio @file{/gnu/store}. Esto llevaría a inconsistencias y rompería las +premisas de inmutabilidad del modelo funcional de Guix +(@pxref{Introducción}). + +@xref{Invocación de guix gc, @command{guix gc --verify}}, para información sobre +cómo comprobar la integridad del almacén e intentar recuperarse de +modificaciones accidentales. +@end quotation + +El módulo @code{(guix store)} proporciona procedimientos para conectarse al +daemon y realizar RPCs. Estos se describen más adelante. Por defecto, +@code{open-connection}, y por tanto todas las órdenes @command{guix}, se +conectan al daemon local o a la URI especificada en la variable de entorno +@code{GUIX_DAEMON_SOCKET}. + +@defvr {Variable de entorno} GUIX_DAEMON_SOCKET +Cuando se ha definido, el valor de esta variable debe ser un nombre de +fichero o una URI designando el punto de conexión del daemon. Cuando es un +nombre de fichero, denota un socket de dominio Unix al que +conectarse. Además de nombres de ficheros, los esquemas de URI aceptados +son: + +@table @code +@item file +@itemx unix +Estos son equivalentes a los sockets de dominio +Unix. @code{file:///var/guix/daemon-socket/socket} es equivalente a +@file{/var/guix/daemon-socket/socket}. + +@item guix +@cindex daemon, acceso remoto +@cindex acceso remoto al daemon +@cindex daemon, configuración en cluster +@cindex daemon, configuración en cluster +Estas URI denotan conexiones sobre TCP/IP, sin cifrado ni verificación de la +máquina remota. La URI debe especificar el nombre de máquina y opcionalmente +un número de puerto (por defecto se usa el puerto 44146): + +@example +guix://principal.guix.example.org:1234 +@end example + +Esta configuración es apropiada para redes locales, como clusters, donde +únicamente los nodos de confianza pueden conectarse al daemon de +construcción en @code{principal.guix.example.org}. + +La opción @code{--listen} de @command{guix-daemon} puede usarse para +indicarle que escuche conexiones TCP (@pxref{Invocación de guix-daemon, +@code{--listen}}). + +@item ssh +@cindex acceso SSH a los daemons de construcción +Estas URI le permiten conectarse a un daemon remoto sobre SSH@footnote{Esta +característica necesita Guile-SSH (@pxref{Requisitos}).}. Una URL típica +debería ser algo así: + +@example +ssh://carlos@@guix.example.org:22 +@end example + +Como con @command{guix copy}, se tienen en cuenta los ficheros habituales de +configuración del cliente OpenSSH (@pxref{Invocación de guix copy}). +@end table + +Esquemas URI adicionales pueden ser aceptados en el futuro. + +@c XXX: Remove this note when the protocol incurs fewer round trips +@c and when (guix derivations) no longer relies on file system access. +@quotation Nota +La conexión con daemon de construcción remotos se considera experimental en +@value{VERSION}. Por favor, contacte con nosotras para compartir cualquier +problema o sugerencias que pueda tener (@pxref{Contribuir}). +@end quotation +@end defvr + +@deffn {Procedimiento Scheme} open-connection [@var{uri}] [#:reserve-space? #t] +Abre una conexión al daemon a través del socket de dominio Unix apuntado por +@var{uri} (una cadena). Cuando @var{reserve-space?} es verdadero, le indica +que reserve un poco de espacio extra en el sistema de ficheros de modo que +el recolector de basura pueda operar incluso cuando el disco se +llene. Devuelve un objeto servidor. + +El valor por defecto de @var{uri} es @var{%default-socket-path}, que ese la +ruta esperada según las opciones pasadas a @code{configure}. +@end deffn + +@deffn {Procedimiento Scheme} close-connection @var{servidor} +Cierra la conexión al @var{servidor}. +@end deffn + +@defvr {Variable Scheme} current-build-output-port +Esta variable está enlazada a un parámetro SRFI-39, que referencia al puerto +donde los logs de construcción y error enviados por el daemon deben +escribirse. +@end defvr + +Los procedimientos que realizan RPCs toman todos como primer parámetro un +objeto servidor. + +@deffn {Procedimiento Scheme} valid-path? @var{servidor} @var{ruta} +@cindex elementos inválidos del almacén +Devuelve @code{#t} cuando @var{ruta} designa un elemento válido del almacén +y @code{#f} en otro caso (un elemento no-válido puede existir en el disco +pero aun así no ser válido, por ejemlo debido a que es el resultado de una +construcción interumpida o fallida). + +Una condición @code{&store-protocol-error} se eleva si @var{ruta} no +contiene como prefijo el directorio del almacén (@file{/gnu/store}). +@end deffn + +@deffn {Procedimiento Scheme} add-text-to-store @var{servidor} @var{nombre} @var{texto} [@var{referencias}] +Añade @var{texto} bajo el fichero @var{nombre} en el almacén, y devuelve su +ruta en el almacén. @var{referencias} es la lista de rutas del almacén +referenciadas por la ruta del almacén resultante. +@end deffn + +@deffn {Procedimiento Scheme} build-derivations @var{servidor} @var{derivaciones} +Construye @var{derivaciones} (una lista de objetos @code{<derivation>} o +rutas de derivaciones) y devuelve el control cuando se termina de +construirlas. Devuelve @code{#t} en caso de éxito. +@end deffn + +Fijese que el módulo @code{(guix monads)} proporciona una mónada así como +versiones monádicas de los procedimientos previos, con el objetivo de hacer +más conveniente el trabajo con código que accede al almacén (@pxref{La mónada del almacén}). + +@c FIXME +@i{Esta sección actualmente está incompleta.} + +@node Derivaciones +@section Derivaciones + +@cindex derivaciones +Las acciones de construcción a bajo nivel y el entorno en el que se realizan +se representan mediante @dfn{derivaciones}. Una derivación contiene las +siguientes piezas de información: + +@itemize +@item +Las salidas de la derivación---las derivaciones producen al menos un fichero +o directorio en el almacén, pero pueden producir más. + +@item +@cindex tiempo de construcción, dependencias +@cindex dependencias, tiempo de construcción +Las entradas de las derivaciones---es decir, sus dependencias de tiempo de +construcción---, que pueden ser otras derivaciones o simples ficheros en el +almacén (parches, guiones de construcción, etc.). + +@item +El tipo de sistema objetivo de la derivación---por ejemplo, +@code{x86_64-linux}. + +@item +El nombre de fichero del guión de construcción en el almacén, junto a los +parámetros que se le deben pasar. + +@item +Una lista de variables de entorno a ser definidas. + +@end itemize + +@cindex ruta de derivación +Las derivaciones permiten a los clientes del daemon comunicar acciones de +construcción al almacén. Existen en dos formas: como una representación en +memoria, tanto en el lado del cliente como el del daemon, y como ficheros en +el almacén cuyo nombre termina en @code{.drv}---estos ficheros se conocen +como @dfn{rutas de derivación}. Las rutas de derivación pueden pasarse al +procedimiento @code{build-derivations} para realizar las acciones de +construcción que prescriben (@pxref{El almacén}). + +@cindex derivaciones de salida fija +Operaciones como la descarga de ficheros y las instantáneas de un control de +versiones para las cuales el hash del contenido esperado se conoce +previamente se modelan como @dfn{derivaciones de salida fija}. Al contrario +que las derivaciones normales, las salidas de una derivación de salida fija +son independientes de sus entradas---por ejemplo, la descarga del código +fuente produce el mismo resultado independientemente del método de descarga +y las herramientas usadas. + +@cindex references +@cindex tiempo de ejecución, dependencias +@cindex dependencias, tiempo de ejecución +The outputs of derivations---i.e., the build results---have a set of +@dfn{references}, as reported by the @code{references} RPC or the +@command{guix gc --references} command (@pxref{Invocación de guix gc}). +References are the set of run-time dependencies of the build results. +References are a subset of the inputs of the derivation; this subset is +automatically computed by the build daemon by scanning all the files in the +outputs. + +El módulo @code{(guix derivations)} proporciona una representación de +derivaciones como objetos Scheme, junto a procedimientos para crear y +manipular de otras formas derivaciones. La primitiva de más bajo nivel para +crear una derivación es el procedimiento @code{derivation}: + +@deffn {Procedimiento Scheme} derivation @var{almacén} @var{nombre} @var{constructor} @ + @var{args} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @ + [#:recursive? #f] [#:inputs '()] [#:env-vars '()] @ + [#:system (%current-system)] [#:references-graphs #f] @ + [#:allowed-references #f] [#:disallowed-references #f] @ + [#:leaked-env-vars #f] [#:local-build? #f] @ + [#:substitutable? #t] [#:properties '()] +Construye una derivación con los parámetros proporcionados, y devuelve el +objeto @code{<derivation>} resultante. + +Cuando se proporcionan @var{hash} y @var{hash-algo}, una @dfn{derivación de +salida fija} se crea---es decir, una cuyo resultado se conoce de antemano, +como la descarga de un fichero. Si, además, @var{recursive?} es verdadero, +entonces la salida fijada puede ser un fichero ejecutable o un directorio y +@var{hash} debe ser el hash de un archivador que contenga esta salida. + +Cuando @var{references-graphs} es verdadero, debe ser una lista de pares de +nombre de fichero/ruta del almacén. En ese caso, el grafo de referencias de +cada ruta del almacén se exporta en el entorno de construcción del fichero +correspondiente, en un formato de texto simple. + +Cuando @var{allowed-references} es verdadero, debe ser una lista de +elementos del almacén o salidas a las que puede hacer referencia la salida +de la derivación. Del mismo modo, @var{disallowed-references}, en caso de +ser verdadero, debe ser una lista de cosas a las que las salidas @emph{no} +pueden hacer referencia. + +Cuando @var{leaked-env-vars} es verdadero, debe ser una lista de cadenas que +denoten variables de entorno que se permite ``escapar'' del entorno del +daemon al entorno de construcción. Esto es únicamente aplicable a +derivaciones de salida fija---es decir, cuando @var{hash} es verdadero. El +uso principal es permitir que variables como @code{http_proxy} sean pasadas +a las derivaciones que descargan ficheros. + +Cuando @var{local-build?} es verdadero, declara que la derivación no es una +buena candidata para delegación y debe ser construida localmente +(@pxref{Configuración de delegación del daemon}). Este es el caso para pequeñas derivaciones +donde los costes de transferencia de datos sobrepasarían los beneficios. + +Cuando @var{substitutable?} es falso, declara que las sustituciones de la +salida de la derivación no deben usarse (@pxref{Sustituciones}). Esto es útil, +por ejemplo, cuando se construyen paquetes que capturan detalles sobre el +conjunto de instrucciones de la CPU anfitriona. + +@var{properties} debe ser una lista asociada que describe ``propiedades'' de +la derivación. Debe mantenerse tal cual, sin interpretar, en la derivación. +@end deffn + +@noindent +Esto es un ejemplo con un guión de shell como constructor, asumiendo que +@var{almacén} es una conexión abierta al daemon, @var{bash} apunta al +ejecutable Bash en el almacén: + +@lisp +(use-modules (guix utils) + (guix store) + (guix derivations)) + +(let ((constructor ; añade el guión de Bash al almacén + (add-text-to-store store "mi-constructor.sh" + "echo hola mundo > $out\n" '()))) + (derivation almacen "foo" + bash `("-e" ,builder) + #:inputs `((,bash) (,constructor)) + #:env-vars '(("HOME" . "/sindirectorio")))) +@result{} #<derivation /gnu/store/@dots{}-foo.drv => /gnu/store/@dots{}-foo> +@end lisp + +Como puede suponerse, el uso directo de esta primitiva es algo +enrevesado. Una mejor aproximación es escribir guiones de construcción en +Scheme, ¡por supuesto! La mejor forma de hacerlo es escribir el código de +construcción como una ``expresión-G'', y pasarla a +@code{gexp->derivation}. Para más información, @pxref{Expresiones-G}. + +En otros tiempos, @code{gexp->derivation} no existía y la creación de +derivaciones con código de construcción escrito en Scheme se conseguía con +@code{build-expression->derivation}, documentada más adelante. Este +procedimiento está ahora obsoleto en favor del procedimiento +@code{gexp->derivation} mucho más conveniente. + +@deffn {Procedimiento Scheme} build-expression->derivation @var{almacén} @ + @var{nombre} @var{exp} @ + [#:system (%current-system)] [#:inputs '()] @ + [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @ + [#:recursive? #f] [#:env-vars '()] [#:modules '()] @ + [#:references-graphs #f] [#:allowed-references #f] @ + [#:disallowed-references #f] @ + [#:local-build? #f] [#:substitutable? #t] [#:guile-for-build #f] +Devuelve una derivación que ejecuta la expresión Scheme @var{exp} como un +constructor para la derivación @var{nombre}. @var{inputs} debe ser una lista +de tupletas @code{(nombre ruta-drv sub-drv)}; cuando @var{sub-drv} se omite, +se asume @code{"out"}. @var{modules} es una lista de nombres de módulos +Guile de la ruta actual de búsqueda a copiar en el almacén, compilados, y +poner a disposición en la ruta de carga durante la ejecución de +@var{exp}---por ejemplo, @code{((guix build utils) (guix build +gnu-build-system))}. + +@var{exp} se evalúa en un entorno donde @code{%outputs} está asociada a una +lista de pares salida/ruta, y donde @code{%build-inputs} está asociada a una +lista de pares cadena/ruta-de-salida que provienen de @var{inputs}. De +manera opcional, @var{env-vars} es una lista de pares de cadenas que +especifican el nombre y el valor de las variables de entorno visibles al +constructor. El constructor termina pasando el resultado de @var{exp} a +@code{exit}; por tanto, cuando @var{exp} devuelve @code{#f}, la construcción +se considera fallida. + +@var{exp} se construye usando @var{guile-for-build} (una derivación). Cuando +@var{guile-for-build} se omite o es @code{#f}, el valor del fluido +@code{%guile-for-build} se usa en su lugar. + +Véase el procedimiento @code{derivation} para el significado de +@var{references-graphs}, @var{allowed-references}, +@var{disallowed-references}, @var{local-build?} y @var{substitutable?}. +@end deffn + +@noindent +Aquí está un ejemplo de derivación de salida única que crea un directorio +que contiene un fichero: + +@lisp +(let ((constructor '(let ((salida (assoc-ref %outputs "out"))) + (mkdir salida) ; crea /gnu/store/@dots{}-goo + (call-with-output-file (string-append salida "/prueba") + (lambda (p) + (display '(hola guix) p)))))) + (build-expression->derivation almacen "goo" constructor)) + +@result{} #<derivation /gnu/store/@dots{}-goo.drv => @dots{}> +@end lisp + + +@node La mónada del almacén +@section La mónada del almacén + +@cindex mónada + +Los procedimientos que operan en el almacén descritos en la sección previa +toman todos una conexión abierta al daemon de construcción en su primer +parámetro. Aunque el modelo subyacente es funcional, tienen o bien efectos +secundarios o dependen del estado actual del almacén. + +Lo anterior es inconveniente: la conexión al daemon de construcción tiene +que proporcionarse en todas estas funciones, haciendo imposible la +composición de funciones que no toman ese parámetro con funciones que sí lo +hacen. Lo último puede ser problemático: ya que las operaciones del almacén +tienen efectos secundarios y/o dependen del estado externo, deben ser +secuenciadas de manera adecuada. + +@cindex valores monádicos +@cindex funciones monádicas +Aquí es donde entra en juego el módulo @code{(guix monads)}. Este módulo +proporciona un entorno para trabajar con @dfn{mónadas}, y una mónada +particularmente útil para nuestros usos, la @dfn{mónada del almacén}. Las +mónadas son una construcción que permite dos cosas: asociar ``contexto'' con +valores (en nuestro caso, el contexto es el almacén), y la construcción de +secuencias de computaciones (aquí computaciones incluye accesos al +almacén). Los valores en una mónada---valores que transportan este contexto +adicional---se llaman @dfn{valores monádicos}; los procedimientos que +devuelven dichos valores se llaman @dfn{procedimientos monádicos}. + +Considere este procedimiento ``normal'': + +@example +(define (enlace-sh almacen) + ;; Devuelve una derivación que enlaza el ejecutable 'bash'. + (let* ((drv (package-derivation store bash)) + (out (derivation->output-path drv)) + (sh (string-append out "/bin/bash"))) + (build-expression->derivation store "sh" + `(symlink ,sh %output)))) +@end example + +Mediante el uso de @code{(guix monads)} y @code{(guix gexp)}, puede +reescribirse como una función monádica: + +@example +(define (enlace-sh) + ;; Lo mismo, pero devuelve un valor monádico. + (mlet %store-monad ((drv (package->derivation bash))) + (gexp->derivation "sh" + #~(symlink (string-append #$drv "/bin/bash") + #$output)))) +@end example + +Hay varias cosas a tener en cuenta en la segunda versión: el parámetro +@code{store} ahora es implícito y es ``hilado en las llamadas a los +procedimientos monádicos @code{package->derivation} y +@code{gexp->derivation}, y el valor monádico devuelto por +@code{package->derivation} es @dfn{asociado} mediante el uso de @code{mlet} +en vez de un simple @code{let}. + +Al final, la llamada a @code{package->derivation} puede omitirse ya que +tendrá lugar implícitamente, como veremos más adelante +(@pxref{Expresiones-G}): + +@example +(define (enlace-sh) + (gexp->derivation "sh" + #~(symlink (string-append #$bash "/bin/bash") + #$output))) +@end example + +@c See +@c <https://syntaxexclamation.wordpress.com/2014/06/26/escaping-continuations/> +@c for the funny quote. +La ejecución del procedimiento monádico @code{enlace-para-sh} no tiene +ningún efecto. Como alguien dijo una vez, ``sales de una mónada como sales +de un edificio en llamas: corriendo'' (run en inglés). Por tanto, para salir +de la mónada y obtener el efecto deseado se debe usar @code{run-with-store}: + +@example +(run-with-store (open-connection) (enlace-sh)) +@result{} /gnu/store/...-enlace-para-sh +@end example + +Fíjese que el módulo @code{(guix monad-repl)} extiende la sesión interactiva +de Guile con nuevos ``meta-comandos'' para facilitar el trabajo con +procedimientos monádicos: @code{run-in-store} y @code{enter-store-monad}. El +primero se usa para ``ejecutar'' un valor monádico único a través del +almacén: + +@example +scheme@@(guile-user)> ,run-in-store (package->derivation hello) +$1 = #<derivation /gnu/store/@dots{}-hello-2.9.drv => @dots{}> +@end example + +El último entra en un entorno interactivo recursivo, donde todos los valores +devueltos se ejecutan automáticamente a través del almacén: + +@example +scheme@@(guile-user)> ,enter-store-monad +store-monad@@(guile-user) [1]> (package->derivation hello) +$2 = #<derivation /gnu/store/@dots{}-hello-2.9.drv => @dots{}> +store-monad@@(guile-user) [1]> (text-file "foo" "Hello!") +$3 = "/gnu/store/@dots{}-foo" +store-monad@@(guile-user) [1]> ,q +scheme@@(guile-user)> +@end example + +@noindent +Fijese que los valores no-monádicos no pueden devolverse en el entorno +interactivo @code{store-monad}. + +Las formas sintácticas principales para tratar con mónadas en general se +proporcionan por el módulo @code{(guix monads)} y se describen a +continuación. + +@deffn {Sintaxis Scheme} with-monad @var{mónada} @var{cuerpo} ... +Evalua cualquier forma @code{>>=} o @code{return} en @var{cuerpo} como +estando en @var{mónada}. +@end deffn + +@deffn {Sintaxis Scheme} return @var{val} +Devuelve el valor monádico que encapsula @var{val}. +@end deffn + +@deffn {Sintaxis Scheme} >>= @var{mval} @var{mproc} ... +@dfn{Asocia} el valor monádico @var{mval}, pasando su ``contenido'' a los +procedimientos monádicos @var{mproc}@dots{}@footnote{Esta operación es +habitualmente conocida como ``bind'' (asociación), pero ese nombre denota un +procedimiento no relacionado en Guile. Por tanto usamos este símbolo en +cierto modo críptico heredado del lenguaje Haskell.}. Puede haber un +@var{mproc} o varios, como en este ejemplo: + +@example +(run-with-state + (with-monad %state-monad + (>>= (return 1) + (lambda (x) (return (+ 1 x))) + (lambda (x) (return (* 2 x))))) + 'un-estado) + +@result{} 4 +@result{} un-estado +@end example +@end deffn + +@deffn {Sintaxis Scheme} mlet @var{mónada} ((@var{var} @var{mval}) ...) @ + @var{cuerpo} ... +@deffnx {Sintaxis Scheme} mlet* @var{mónada} ((@var{var} @var{mval}) ...) @ + @var{cuerpo} ... Asocia las variables @var{var} a los valores monádicos +@var{mval} en @var{cuerpo}, el cual es una secuencia de expresiones. Como +con el operador bind, esto puede pensarse como el ``desempaquetado'' del +valor crudo no-monádico dentro del ámbito del @var{cuerpo}. La forma +(@var{var} -> @var{val}) asocia @var{var} al valor ``normal'' @var{val}, +como en @code{let}. Las operaciones de asociación ocurren en secuencia de +izquierda a derecha. La última expresión de @var{cuerpo} debe ser una +expresión monádica, y su resultado se convertirá en el resultado de +@code{mlet} o @code{mlet*} cuando se ejecute en la @var{mónada}. + +@code{mlet*} es a @code{mlet} lo que @code{let*} es a @code{let} +(@pxref{Local Bindings,,, guile, GNU Guile Reference Manual}). +@end deffn + +@deffn {Sistema Scheme} mbegin @var{mónada} @var{mexp} ... +Asocia @var{mexp} y las siguientes expresiones monádicas en secuencia, +devolviendo el resultado de la última expresión. Cada expresión en la +secuencia debe ser una expresión monádica. + +Esto es similar a @code{mlet}, excepto que los valores devueltos por las +expresiones monádicas se ignoran. En ese sentido el funcionamiento es +análogo a @code{begin} pero aplicado a expresiones monádicas. +@end deffn + +@deffn {Sistema Scheme} mwhen @var{condición} @var{mexp0} @var{mexp*} ... +Cuando @var{condición} es verdadero, evalúa la secuencia de expresiones +monádicas @var{mexp0}..@var{mexp*} como dentro de @code{mbegin}. Cuando +@var{condición} es falso, devuelve @code{*unespecified*} en la mónada +actual. Todas las expresiones en la secuencia deben ser expresiones +monádicas. +@end deffn + +@deffn {Sistema Scheme} munless @var{condición} @var{mexp0} @var{mexp*} ... +Cuando @var{condición} es falso, evalúa la secuencia de expresiones +monádicas @var{mexp0}..@var{mexp*} como dentro de @code{mbegin}. Cuando +@var{condición} es verdadero, devuelve @code{*unespecified*} en la mónada +actual. Todas las expresiones en la secuencia deben ser expresiones +monádicas. +@end deffn + +@cindex mónada de estado +El módulo @code{(guix monads)} proporciona la @dfn{mónada de estado}, que +permite que un valor adicional---el estado---sea @emph{hilado} a través de +las llamadas a procedimientos monádicos. + +@defvr {Variable Scheme} %state-monad +La mónada de estado. Procedimientos en la mónada de estado pueden acceder y +cambiar el estado hilado. + +Considere el siguiente ejemplo. El procedimiento @code{cuadrado} devuelve un +valor en la mónada de estado. + +@example +(define (cuadrado x) + (mlet %state-monad ((count (current-state))) + (mbegin %state-monad + (set-current-state (+ 1 count)) + (return (* x x))))) + +(run-with-state (sequence %state-monad (map cuadrado (iota 3))) 0) +@result{} (0 1 4) +@result{} 3 +@end example + +Cuando se ``ejecuta'' a través de @var{%state-monad}, obtenemos un valor +adicional de estado, que ese el número de llamadas a @code{cuadrado}. +@end defvr + +@deffn {Procedimiento monádico} current-state +Devuelve el estado actual como un valor monádico. +@end deffn + +@deffn {Procedimiento monádico} set-current-state @var{valor} +Establece el estado actual a @var{valor} y devuelve el estado previo como un +valor monádico. +@end deffn + +@deffn {Procedimiento monádico} state-push @var{valor} +Apila @var{valor} al estado actual, que se asume que es una lista, y +devuelve el estado previo como un valor monádico. +@end deffn + +@deffn {Procedimiento monádico} state-pop +Desapila un valor del estado actual y lo devuelve como un valor monádico. El +estado se asume que es una lista. +@end deffn + +@deffn {Procedimiento Scheme} run-with-state @var{mval} [@var{estado}] +Ejecuta un valor monádico @var{mval} comenzando con @var{estado} como el +estado inicial. Devuelve dos valores: el valor resultante y el estado +resultante. +@end deffn + +La interfaz principal a la mónada del almacén, proporcionada por el módulo +@code{(guix store)}, es como sigue. + +@defvr {Variable Scheme} %store-monad +La mónada del almacén---un alias para @var{%state-monad}. + +Los valores en la mónada del almacén encapsulan los accesos al +almacén. Cuando su efecto es necesario, un valor de la mónada del almacén +será ``evaluado'' pasandolo al procedimiento @code{run-with-store} (vea más +adelante). +@end defvr + +@deffn {Procedimiento Scheme} run-with-store @var{almacén} @var{mval} [#:guile-for-build] [#:system (%current-system)] +Ejecuta @var{mval}, un valor monádico en la mónada del almacén, en +@var{almacén}, una conexión abierta al almacén. +@end deffn + +@deffn {Procedimiento monádico} text-file @var{nombre} @var{texto} [@var{referencias}] +Devuelve como un valor monádico el nombre absoluto del fichero en el almacén +del fichero que contiene @var{ŧexto}, una cadena. @var{referencias} es una +lista de elementos del almacén a los que el fichero de texto referencia; su +valor predeterminado es la lista vacía. +@end deffn + +@deffn {Procedimiento monádico} binary-file @var{nombre} @var{datos} [@var{referencias}] +Devuelve como un valor monádico el nombre absoluto del fichero en el almacén +del fichero que contiene @var{datos}, un vector de bytes. @var{referencias} +es una lista de elementos del almacén a los que el fichero binario +referencia; su valor predeterminado es la lista vacía. +@end deffn + +@deffn {Procedimiento monádico} interned-file @var{fichero} [@var{nombre}] @ + [#:recursive? #t] [#:select? (const #t)] +Devuelve el nombre del @var{fichero} una vez internado en el almacén. Usa +@var{nombre} como su nombre del almacén, o el nombre base de @var{fichero} +si @var{nombre} se omite. + +Cuando @var{recursive?} es verdadero, los contenidos del @var{fichero} se +añaden recursivamente; si @var{fichero} designa un fichero plano y +@var{recursive?} es verdadero, sus contenidos se añaden, y sus bits de +permisos se mantienen. + +Cuando @var{recursive?} es verdadero, llama a @code{(@var{select?} +@var{fichero} @var{stat})} por cada entrada del directorio, donde +@var{fichero} es el nombre absoluto de fichero de la entrada y @var{stat} es +el resultado de @code{lstat}; excluyendo las entradas para las cuales +@var{select?} no devuelve verdadero. + +El ejemplo siguiente añade un fichero al almacén, bajo dos nombres +diferentes: + +@example +(run-with-store (open-connection) + (mlet %store-monad ((a (interned-file "README")) + (b (interned-file "README" "LEGU-MIN"))) + (return (list a b)))) + +@result{} ("/gnu/store/rwm@dots{}-README" "/gnu/store/44i@dots{}-LEGU-MIN") +@end example + +@end deffn + +El módulo @code{(guix packages)} exporta los siguientes procedimientos +monádicos relacionados con paquetes: + +@deffn {Procedimiento monádico} package-file @var{paquete} [@var{fichero}] @ + [#:system (%current-system)] [#:target #f] @ + [#:output "out"] +Devuelve como un valor monádico el nombre absoluto de fichero de +@var{fichero} dentro del directorio de salida @var{output} del +@var{paquete}. Cuando se omite @var{fichero}, devuelve el nombre del +directorio de salida @var{output} del @var{paquete}. Cuando @var{target} es +verdadero, se usa como una tripleta de compilación cruzada. +@end deffn + +@deffn {Procedimiento monádico} package->derivation @var{paquete} [@var{sistema}] +@deffnx {Procedimiento monádico} package->cross-derivation @var{paquete} @ + @var{objetivo} [@var{sistema}] +Versión monádica de @code{package-derivation} y +@code{package-cross-derivation} (@pxref{Definición de paquetes}). +@end deffn + + +@node Expresiones-G +@section Expresiones-G + +@cindex expresión-G +@cindex escape de código de construcción +Por tanto tenemos ``derivaciones'', que representan una secuencia de +acciones de construcción a realizar para producir un elemento en el almacén +(@pxref{Derivaciones}). Estas acciones de construcción se llevan a cabo +cuando se solicita al daemon construir realmente la derivación; se ejecutan +por el daemon en un contenedor (@pxref{Invocación de guix-daemon}). + +@cindex estratos de código +No debería ser ninguna sorpresa que nos guste escribir estas acciones de +construcción en Scheme. Cuando lo hacemos, terminamos con dos @dfn{estratos} +de código Scheme@footnote{El término @dfn{estrato} en este contexto se debe +a Manuel Serrano et al.@: en el contexto de su trabajo en Hop. Oleg +Kiselyov, quien ha escrito profundos +@url{http://okmij.org/ftp/meta-programming/#meta-scheme, ensayos sobre el +tema}, se refiere a este tipo de generación de código como separación en +etapas o @dfn{staging}.}: el ``código anfitrión''---código que define +paquetes, habla al daemon, etc.---y el ``código de construcción''---código +que realmente realiza las acciones de construcción, como la creación de +directorios, la invocación de @command{make}, etc. + +Para describir una derivación y sus acciones de construcción, típicamente se +necesita embeber código de construcción dentro del código anfitrión. Se +resume en la manipulación de código de construcción como datos, y la +homoiconicidad de Scheme---el código tiene representación directa como +datos---es útil para ello. Pero necesitamos más que el mecanismo normal de +@code{quasiquote} en Scheme para construir expresiones de construcción. + +El módulo @code{(guix gexp)} implementa las @dfn{expresiones-G}, una forma +de expresiones-S adaptada para expresiones de construcción. Las +expresiones-G, o @dfn{gexps}, consiste esencialmente en tres formas +sintácticas: @code{gexp}, @code{ungexp} y @code{ungexp-splicing} (o +simplemente: @code{#~}, @code{#$} y @code{#$@@}), que son comparables a +@code{quasiquote}, @code{unquote} y @code{unquote-splicing}, respectivamente +(@pxref{Expression Syntax, @code{quasiquote},, guile, GNU Guile Reference +Manual}). No obstante, hay importantes diferencias: + +@itemize +@item +Las expresiones-G están destinadas a escribirse en un fichero y ser +ejecutadas o manipuladas por otros procesos. + +@item +Cuando un objeto de alto nivel como un paquete o una derivación se expande +dentro de una expresión-G, el resultado es el mismo que la introducción de +su nombre de fichero de salida. + +@item +Las expresiones-G transportan información acerca de los paquetes o +derivaciones que referencian, y estas referencias se añaden automáticamente +como entradas al proceso de construcción que las usa. +@end itemize + +@cindex bajada de nivel, de objetos de alto nivel en expresiones-G +Este mecanismo no se limita a objetos de paquete ni derivación: pueden +definirse @dfn{compiladores} capaces de ``bajar el nivel'' de otros objetos +de alto nivel a derivaciones o ficheros en el almacén, de modo que esos +objetos puedan introducirse también en expresiones-G. Por ejemplo, un tipo +útil de objetos de alto nivel que pueden insertarse en una expresión-G son +los ``objetos tipo-fichero'', los cuales facilitan la adición de ficheros al +almacén y su referencia en derivaciones y demás (vea @code{local-file} y +@code{plain-file} más adelante). + +Para ilustrar la idea, aquí está un ejemplo de expresión-G: + +@example +(define exp-construccion + #~(begin + (mkdir #$output) + (chdir #$output) + (symlink (string-append #$coreutils "/bin/ls") + "enumera-ficheros"))) +@end example + +Esta expresión-G puede pasarse a @code{gexp->derivation}; obtenemos una +derivación que construye un directorio que contiene exactamente un enlace +simbólico a @file{/gnu/store/@dots{}-coreutils-8.22/bin/ls}: + +@example +(gexp->derivation "la-cosa" exp-construccion) +@end example + +Como se puede esperar, la cadena @code{"/gnu/store/@dots{}-coreutils-8.22"} +se sustituye por la referencia al paquete @var{coreutils} en el código de +construcción real, y @var{coreutils} se marca automáticamente como una +entrada a la derivación. Del mismo modo, @code{#$output} (equivalente a +@code{(ungexp output)}) se reemplaza por una cadena que contiene el nombre +del directorio de la salida de la derivación. + +@cindex compilación cruzada +En un contexto de compilación cruzada, es útil distinguir entre referencias +a construcciones @emph{nativas} del paquete---que pueden ejecutarse en el +sistema anfitrión---de referencias de compilaciones cruzadas de un +paquete. Para dicho fin, @code{#+} tiene el mismo papel que @code{#$}, pero +es una referencia a una construcción nativa del paquete: + +@example +(gexp->derivation "vi" + #~(begin + (mkdir #$output) + (system* (string-append #+coreutils "/bin/ln") + "-s" + (string-append #$emacs "/bin/emacs") + (string-append #$output "/bin/vi"))) + #:target "mips64el-linux-gnu") +@end example + +@noindent +En el ejemplo previo, se usa la construcción nativa de @var{coreutils}, de +modo que @command{ln} pueda realmente ejecutarse en el anfitrión; pero se +hace referencia a la construcción de compilación cruzada de @var{emacs}. + +@cindex módulos importados, para expresiones-G +@findex with-imported-modules +Otra característica de las expresiones-G son los @dfn{módulos importados}: a +veces deseará ser capaz de usar determinados módulos Guile del ``entorno +anfitrión'' en la expresión-G, de modo que esos módulos deban ser importados +en el ``entorno de construcción''. La forma @code{with-imported-modules} le +permite expresarlo: + +@example +(let ((build (with-imported-modules '((guix build utils)) + #~(begin + (use-modules (guix build utils)) + (mkdir-p (string-append #$output "/bin")))))) + (gexp->derivation "directorio-vacio" + #~(begin + #$build + (display "éxito!\n") + #t))) +@end example + +@noindent +En este ejemplo, el módulo @code{(guix build utils)} se incorpora +automáticamente dentro del entorno de construcción aislado de nuestra +expresión-G, de modo que @code{(use-modules (guix build utils))} funciona +como se espera. + +@cindex clausura de módulos +@findex source-module-closure +De manera habitual deseará que la @emph{clausura} del módulo se importe---es +decir, el módulo en sí y todos los módulos de los que depende---en vez del +módulo únicamente; si no se hace, cualquier intento de uso del módulo +fallará porque faltan módulos dependientes. El procedimiento +@code{source-module-closure} computa la clausura de un módulo mirando en las +cabeceras de sus ficheros de fuentes, lo que es útil en este caso: + +@example +(use-modules (guix modules)) ;para 'source-module-closure' + +(with-imported-modules (source-module-closure + '((guix build utils) + (gnu build vm))) + (gexp->derivation "algo-con-maq-virtuales" + #~(begin + (use-modules (guix build utils) + (gnu build vm)) + @dots{}))) +@end example + +@cindex extensiones, para expresiones G +@findex with-extensions +De la misma manera, a veces deseará importar no únicamente módulos puros de +Scheme, pero también ``extensiones'' como enlaces Guile a bibliotecas C u +otros paquetes ``completos''. Si, digamos, necesitase el paquete +@code{guile-json} disponible en el lado de construcción, esta sería la forma +de hacerlo: + +@example +(use-modules (gnu packages guile)) ;para 'guile-json' + +(with-extensions (list guile-json) + (gexp->derivation "algo-con-json" + #~(begin + (use-modules (json)) + @dots{}))) +@end example + +La forma sintáctica para construir expresiones-G se resume a continuación. + +@deffn {Sintaxis Scheme} #~@var{exp} +@deffnx {Sintaxis Scheme} (gexp @var{exp}) +Devuelve una expresión-G que contiene @var{exp}. @var{exp} puede contener +una o más de las siguientes formas: + +@table @code +@item #$@var{obj} +@itemx (ungexp @var{obj}) +Introduce una referencia a @var{obj}. @var{obj} puede tener uno de los tipos +permitidos, por ejemplo un paquete o derivación, en cuyo caso la forma +@code{ungexp} se substituye por el nombre de fichero de su salida---por +ejemplo, @code{"/gnu/store/@dots{}-coreutils-8.22}. + +Si @var{obj} es una lista, se recorre y las referencias a objetos permitidos +se substituyen de manera similar. + +Si @var{obj} es otra expresión-G, su contenido se inserta y sus dependencias +se añaden a aquellas de la expresión-G que la contiene. + +Si @var{obj} es otro tipo de objeto, se inserta tal cual es. + +@item #$@var{obj}:@var{salida} +@itemx (ungexp @var{obj} @var{salida}) +Como la forma previa, pero referenciando explícitamente la @var{salida} de +@var{obj}---esto es útil cuando @var{obj} produce múltiples salidas +(@pxref{Paquetes con múltiples salidas}). + +@item #+@var{obj} +@itemx #+@var{obj}:salida +@itemx (ungexp-native @var{obj}) +@itemx (ungexp-native @var{obj} @var{salida}) +Lo mismo que @code{ungexp}, pero produce una referencia a la construcción +@emph{nativa} de @var{obj} cuando se usa en un contexto de compilación +cruzada. + +@item #$output[:@var{salida}] +@itemx (ungexp output [@var{salida}]) +Inserta una referencia a la salida de la derivación @var{salida}, o a la +salida principal cuando @var{salida} se omite. + +Esto únicamente tiene sentido para expresiones-G pasadas a +@code{gexp->derivation}. + +@item #$@@@var{lst} +@itemx (ungexp-splicing @var{lst}) +Lo mismo que la forma previa, pero expande el contenido de la lista +@var{lst} como parte de la lista que la contiene. + +@item #+@@@var{lst} +@itemx (ungexp-native-splicing @var{lst}) +Lo mismo que la forma previa, pero hace referencia a las construcciones +nativas de los objetos listados en @var{lst}. + +@end table + +Las expresiones-G creadas por @code{gexp} o @code{#~} son objetos del tipo +@code{gexp?} en tiempo de ejecución (vea más adelante). +@end deffn + +@deffn {Sintaxis Scheme} with-imported-modules @var{módulos} @var{cuerpo}@dots{} +Marca las expresiones-G definidas en el @var{cuerpo}@dots{} como si +requiriesen @var{módulos} en su entorno de ejecución. + +Cada elemento en @var{módulos} puede ser el nombre de un módulo, como +@code{(guix build utils)}, o puede ser el nombre de un módulo, seguido de +una flecha, seguido de un objeto tipo-fichero: + +@example +`((guix build utils) + (guix gcrypt) + ((guix config) => ,(scheme-file "config.scm" + #~(define-module @dots{})))) +@end example + +@noindent +En el ejemplo previo, los dos primeros módulos se toman de la ruta de +búsqueda, y el último se crea desde el objeto tipo-fichero proporcionado. + +Esta forma tiene ámbito @emph{léxico}: tiene efecto en las expresiones-G +definidas en @var{cuerpo}@dots{}, pero no en aquellas definidas, digamos, en +procedimientos llamados por @var{cuerpo}@dots{}. +@end deffn + +@deffn {Sintaxis Scheme} with-extensions @var{extensiones} @var{cuerpo}@dots{} +Marca que las expresiones definidas en @var{cuerpo}@dots{} requieren +@var{extensiones} en su entorno de construcción y +ejecución. @var{extensiones} es típicamente una lista de objetos de paquetes +como los que se definen en el módulo @code{(gnu packages guile)}. + +De manera concreta, los paquetes listados en @var{extensiones} se añaden a +la ruta de carga mientras se compilan los módulos importados en +@var{cuerpo}@dots{}; también se añaden a la ruta de carga en la expresión-G +devuelta por @var{cuerpo}@dots{}. +@end deffn + +@deffn {Procedimiento Scheme} gexp? @var{obj} +Devuelve @code{#t} si @var{obj} es una expresión-G. +@end deffn + +Las expresiones-G están destinadas a escribirse en disco, tanto en código +que construye alguna derivación, como en ficheros planos en el almacén. Los +procedimientos monádicos siguientes le permiten hacerlo (@pxref{La mónada del almacén}, para más información sobre mónadas). + +@deffn {Procedimiento monádico} gexp->derivation @var{nombre} @var{exp} @ + [#:system (%current-system)] [#:target #f] [#:graft? #t] @ + [#:hash #f] [#:hash-algo #f] @ + [#:recursive? #f] [#:env-vars '()] [#:modules '()] @ + [#:module-path @var{%load-path}] @ + [#:effective-version "2.2"] @ + [#:references-graphs #f] [#:allowed-references #f] @ + [#:disallowed-references #f] @ + [#:leaked-env-vars #f] @ + [#:script-name (string-append @var{name} "-builder")] @ + [#:deprecation-warnings #f] @ + [#:local-build? #f] [#:substitutable? #t] @ + [#:properties '()] [#:guile-for-build #f] +Devuelve una derivación @var{nombre} que ejecuta @var{exp} (una expresión-G) +con @var{guile-for-build} (una derivación) en el sistema @var{system}; +@var{exp} se almacena en un fichero llamado @var{script-name}. Cuando +@var{target} es verdadero, se usa como la tripleta de compilación cruzada +para paquetes a los que haga referencia @var{exp}. + +@var{modules} está obsoleto en favor de @code{with-imported-modules}. Su +significado es hacer que los módulos @var{modules} estén disponibles en el +contexto de evaluación de @var{exp}; @var{modules} es una lista de nombres +de módulos Guile buscados en @var{module-path} para ser copiados al almacén, +compilados y disponibles en la ruta de carga durante la ejecución de +@var{exp}---por ejemplo, @code{((guix build utils) (gui build +gnu-build-system))}. + +@var{effective-version} determina la cadena a usar cuando se añaden las +extensiones de @var{exp} (vea @code{with-extensions}) a la ruta de +búsqueda---por ejemplo, @code{"2.2"}. + +@var{graft?} determina si los paquetes a los que @var{exp} hace referencia +deben ser injertados cuando sea posible. + +Cuando @var{references-graphs} es verdadero, debe ser una lista de tuplas de +una de las formas siguientes: + +@example +(@var{nombre-fichero} @var{paquete}) +(@var{nombre-fichero} @var{paquete} @var{salida}) +(@var{nombre-fichero} @var{derivación}) +(@var{nombre-fichero} @var{derivación} @var{salida}) +(@var{nombre-fichero} @var{elemento-almacén}) +@end example + +El lado derecho de cada elemento de @var{references-graphs} se convierte +automáticamente en una entrada del proceso de construcción de @var{exp}. En +el entorno de construcción, cada @var{nombre-fichero} contiene el grafo de +referencias del elemento correspondiente, en un formato de texto simple. + +@var{allowed-references} debe ser o bien @code{#f} o una lista de nombres y +paquetes de salida. En el último caso, la lista denota elementos del almacén +a los que el resultado puede hacer referencia. Cualquier referencia a otro +elemento del almacén produce un error de construcción. De igual manera con +@var{disallowed-references}, que enumera elementos a los que las salidas no +deben hacer referencia. + +@var{deprecation-warnings} determina si mostrar avisos de obsolescencia +durante la compilación de los módulos. Puede ser @code{#f}, @code{#t} o +@code{'detailed}. + +El resto de parámetros funcionan como en @code{derivation} +(@pxref{Derivaciones}). +@end deffn + +@cindex objetos tipo-fichero +Los procedimientos @code{local-file}, @code{plain-file}, +@code{computed-file}, @code{program-file} y @code{scheme-file} a +continuación devuelven @dfn{objetos tipo-fichero}. Esto es, cuando se +expanden en una expresión-G, estos objetos dirigen a un fichero en el +almacén. Considere esta expresión-G: + +@example +#~(system* #$(file-append glibc "/sbin/nscd") "-f" + #$(local-file "/tmp/mi-nscd.conf")) +@end example + +El efecto aquí es el ``internamiento'' de @file{/tmp/mi-nscd.conf} mediante +su copia al almacén. Una vez expandida, por ejemplo @i{vía} +@code{gexp->derivation}, la expresión-G hace referencia a la copia bajo +@file{/gnu/store}; por tanto, la modificación o el borrado del fichero en +@file{/tmp} no tiene ningún efecto en lo que la expresión-G +hace. @code{plain-file} puede usarse de manera similar; se diferencia en que +el contenido del fichero se proporciona directamente como una cadena. + +@deffn {Procedimiento Scheme} local-file @var{fichero} [@var{nombre}] @ + [#:recursive? #f] [#:select? (const #t)] +Devuelve un objeto que representa el fichero local @var{fichero} a añadir al +almacén; este objeto puede usarse en una expresión-G. Si @var{fichero} es un +nombre de fichero relativo, se busca de forma relativa al fichero fuente +donde esta forma aparece. @var{fichero} se añadirá al almacén bajo +@var{nombre}---por defecto el nombre base de @var{fichero}. + +Cuando @var{recursive?} es verdadero, los contenidos del @var{fichero} se +añaden recursivamente; si @var{fichero} designa un fichero plano y +@var{recursive?} es verdadero, sus contenidos se añaden, y sus bits de +permisos se mantienen. + +Cuando @var{recursive?} es verdadero, llama a @code{(@var{select?} +@var{fichero} @var{stat})} por cada entrada del directorio, donde +@var{fichero} es el nombre absoluto de fichero de la entrada y @var{stat} es +el resultado de @code{lstat}; excluyendo las entradas para las cuales +@var{select?} no devuelve verdadero. + +Esta es la contraparte declarativa del procedimiento monádico +@code{interned-file} (@pxref{La mónada del almacén, @code{interned-file}}). +@end deffn + +@deffn {Procedimiento Scheme} plain-file @var{nombre} @var{contenido} +Devuelve un objeto que representa un fichero de texto llamado @var{nombre} +con el @var{contenido} proporcionado (una cadena o un vector de bytes) para +ser añadido al almacén. + +Esta es la contraparte declarativa de @code{text-file}. +@end deffn + +@deffn {Procedimiento Scheme} computed-file @var{nombre} @var{gexp} @ + [#:options '(#:local-build? #t)] +Devuelve un objeto que representa el elemento del almacén @var{nombre}, un +fichero o un directorio computado por @var{gexp}. @var{options} es una lista +de parámetros adicionales a pasar a @code{gexp->derivation}. + +Esta es la contraparte declarativa de @code{gexp->derivation}. +@end deffn + +@deffn {Procedimiento monádico} gexp->script @var{nombre} @var{exp} @ + [#:guile (default-guile)] [#:module-path %load-path] +Devuelve un guión ejecutable @var{nombre} que ejecuta @var{exp} usando +@var{guile}, con los módulos importados por @var{exp} en su ruta de +búsqueda. Busca los módulos de @var{exp} en @var{module-path}. + +El ejemplo siguiente construye un guión que simplemente invoca la orden +@command{ls}: + +@example +(use-modules (guix gexp) (gnu packages base)) + +(gexp->script "enumera-ficheros" + #~(execl #$(file-append coreutils "/bin/ls") + "ls")) +@end example + +Cuando se ejecuta a través del almacén (@pxref{La mónada del almacén, +@code{run-with-store}}), obtenemos una derivación que produce un fichero +ejecutable @file{/gnu/store/@dots{}-enumera-ficheros} más o menos así: + +@example +#!/gnu/store/@dots{}-guile-2.0.11/bin/guile -ds +!# +(execl "/gnu/store/@dots{}-coreutils-8.22"/bin/ls" "ls") +@end example +@end deffn + +@deffn {Procedimiento Scheme} program-file @var{nombre} @var{exp} @ + [#:guile #f] [#:module-path %load-path] +Devuelve un objeto que representa el elemento ejecutable del almacén +@var{nombre} que ejecuta @var{gexp}. @var{guile} es el paquete Guile usado +para ejecutar el guión. Los módulos importados por @var{gexp} se buscan en +@var{module-path}. + +Esta es la contraparte declarativa de @code{gexp->script}. +@end deffn + +@deffn {Procedimiento monádico} gexp->file @var{nombre} @var{exp} @ + [#:set-load-path? #t] [#:module-path %load-path] @ + [#:splice? #f] @ + [#:guile (default-guile)] +Devuelve una derivación que construye un fichero @var{nombre} que contiene +@var{exp}. Cuando @var{splice?} es verdadero, se considera que @var{exp} es +una lista de expresiones que deben ser expandidas en el fichero resultante. + +Cuando @var{set-load-path} es verdadero, emite código en el fichero +resultante para establecer @code{%load-path} y @code{%load-compiled-path} de +manera que respeten los módulos importados por @var{exp}. Busca los módulos +de @var{exp} en @var{module-path}. + +El fichero resultante hace referencia a todas las dependencias de @var{exp} +o a un subconjunto de ellas. +@end deffn + +@deffn {Procedimiento Scheme} scheme-file @var{nombre} @var{exp} [#:splice? #f] +Devuelve un objeto que representa el fichero Scheme @var{nombre} que +contiene @var{exp}. + +Esta es la contraparte declarativa de @code{gexp->file}. +@end deffn + +@deffn {Procedimiento monádico} text-file* @var{nombre} @var{texto} @dots{} +Devuelve como un valor monádico una derivación que construye un fichero de +texto que contiene todo @var{texto}. @var{texto} puede ser una lista de, +además de cadenas, objetos de cualquier tipo que pueda ser usado en +expresiones-G: paquetes, derivaciones, ficheros locales, objetos, etc. El +fichero del almacén resultante hace referencia a todos ellos. + +Esta variante debe preferirse sobre @code{text-file} cuando el fichero a +crear haga referencia a elementos del almacén. Esto es el caso típico cuando +se construye un fichero de configuración que embebe nombres de ficheros del +almacén, como este: + +@example +(define (perfil.sh) + ;; Devuelve el nombre de un guión shell en el almacén + ;; que establece la variable de entorno 'PATH' + (text-file* "perfil.sh" + "export PATH=" coreutils "/bin:" + grep "/bin:" sed "/bin\n")) +@end example + +En este ejemplo, el fichero @file{/gnu/store/@dots{}-perfil.sh} resultante +hará referencia a @var{coreutils}, @var{grep} y @var{sed}, por tanto +evitando que se recolecten como basura durante su tiempo de vida. +@end deffn + +@deffn {Procedimiento Scheme} mixed-text-file @var{nombre} @var{texto} @dots{} +Devuelve un objeto que representa el fichero del almacén @var{nombre} que +contiene @var{texto}. @var{texto} es una secuencia de cadenas y objetos +tipo-fichero, como en: + +@example +(mixed-text-file "perfil" + "export PATH=" coreutils "/bin:" grep "/bin") +@end example + +Esta es la contraparte declarativa de @code{text-file*}. +@end deffn + +@deffn {Procedimiento Scheme} file-union @var{nombre} @var{ficheros} +Devuelve un @code{<computed-file>} que construye un directorio que contiene +todos los @var{ficheros}. Cada elemento en @var{ficheros} debe ser una lista +de dos elementos donde el primer elemento es el nombre de fichero a usar en +el nuevo directorio y el segundo elemento es una expresión-G que denota el +fichero de destino. Aquí está un ejemplo: + +@example +(file-union "etc" + `(("hosts" ,(plain-file "hosts" + "127.0.0.1 localhost")) + ("bashrc" ,(plain-file "bashrc" + "alias ls='ls --color=auto'")))) +@end example + +Esto emite un directorio @code{etc} que contiene estos dos ficheros. +@end deffn + +@deffn {Procedimiento Scheme} directory-union @var{nombre} @var{cosas} +Devuelve un directorio que es la unión de @var{cosas}, donde @var{cosas} es +una lista de objetos tipo-fichero que denotan directorios. Por ejemplo: + +@example +(directory-union "guile+emacs" (list guile emacs)) +@end example + +emite un directorio que es la unión de los paquetes @code{guile} y +@code{emacs}. +@end deffn + +@deffn {Procedimientos Scheme} file-append @var{obj} @var{sufijo} @dots{} +Devuelve un objeto tipo-fichero que se expande a la concatenación de +@var{obj} y @var{sufijo}, donde @var{obj} es un objeto que se puede bajar de +nivel y cada @var{sufijo} es una cadena. + +Como un ejemplo, considere esta expresión-G: + +@example +(gexp->script "ejecuta-uname" + #~(system* #$(file-append coreutils + "/bin/uname"))) +@end example + +El mismo efecto podría conseguirse con: + +@example +(gexp->script "ejecuta-uname" + #~(system* (string-append #$coreutils + "/bin/uname"))) +@end example + +Hay una diferencia no obstante: en el caso de @code{file-append}, el guión +resultante contiene una ruta absoluta de fichero como una cadena, mientras +que en el segundo caso, el guión resultante contiene una expresión +@code{(string-append @dots{})} para construir el nombre de fichero @emph{en +tiempo de ejecución}. +@end deffn + + +Por supuesto, además de expresiones-G embebidas en código ``anfitrión'', hay +también módulos que contienen herramientas de construcción. Para clarificar +que están destinados para su uso en el estrato de construcción, estos +módulos se mantienen en el espacio de nombres @code{(guix build @dots{})}. + +@cindex bajada de nivel, de objetos de alto nivel en expresiones-G +Internamente, los objetos de alto nivel se @dfn{bajan de nivel}, usando su +compilador, a derivaciones o elementos del almacén. Por ejemplo, bajar de +nivel un paquete emite una derivación, y bajar de nivel un @var{plain-file} +emite un elemento del almacén. Esto se consigue usando el procedimiento +monádico @code{lower-object}. + +@deffn {Procedimiento monádico} lower-object @var{obj} [@var{sistema}] @ + [#:target #f] +Devuelve como un valor en @var{%store-monad} la derivación o elemento del +almacén que corresponde a @var{obj} en @var{sistema}, compilando de manera +cruzada para @var{target} si @var{target} es verdadero. @var{obj} debe ser +un objeto que tiene asociado un compilador de expresiones-G, como +@code{<package>}. +@end deffn + +@node Invocación de guix repl +@section Invocación de @command{guix repl} + +@cindex REPL, bucle de lectura-evaluación-impresión +La orden @command{guix repl} lanza un @dfn{bucle de +lectura-evaluación-impresión} Guile (REPL) para programación interactiva +(@pxref{Using Guile Interactively,,, guile, GNU Guile Reference +Manual}). Comparado a simplemente lanzar la orden @command{guile}, +@command{guix repl} garantiza que todos los módulos Guix y todas sus +dependencias están disponibles en la ruta de búsqueda. Puede usarla de esta +manera: + +@example +$ guix repl +scheme@@(guile-user)> ,use (gnu packages base) +scheme@@(guile-user)> coreutils +$1 = #<package coreutils@@8.29 gnu/packages/base.scm:327 3e28300> +@end example + +@cindex inferiores +Además, @command{guix repl} implementa un protocolo del REPL simple legible +por máquinas para su uso por @code{(guix inferior)}, una facilidad para +interactuar con @dfn{inferiores}, procesos separados que ejecutan una +revisión de Guix potencialmente distinta. + +Las opciones disponibles son las siguientes: + +@table @code +@item --type=@var{tipo} +@itemx -t @var{tipo} +Inicia un REPL del @var{TIPO} dado, que puede ser uno de los siguientes: + +@table @code +@item guile +Es el predeterminado, y lanza una sesión interactiva Guile estándar con +todas las características. +@item machine +Lanza un REPL que usa el protocolo legible por máquinas. Este es el +protocolo con el que el módulo @code{(guix inferior)} se comunica. +@end table + +@item --listen=@var{destino} +Por defecto, @command{guix repl} lee de la entrada estándar y escribe en la +salida estándar. Cuando se pasa esta opción, en vez de eso escuchará las +conexiones en @var{destino}. Estos son ejemplos de opciones válidas: + +@table @code +@item --listen=tcp:37146 +Acepta conexiones locales por el puerto 37146. + +@item --listen=unix:/tmp/socket +Acepta conexiones a través del socket de dominio Unix @file{/tmp/socket}. +@end table +@end table + +@c ********************************************************************* +@node Utilidades +@chapter Utilidades + +Esta sección describe las utilidades de línea de órdenes de Guix. Algunas de +ellas están orientadas principalmente para desarrolladoras y usuarias que +escriban definiciones de paquetes nuevas, mientras que otras son útiles de +manera más general. Complementan la interfaz programática Scheme de Guix de +modo conveniente. + +@menu +* Invocación de guix build:: Construir paquetes desde la línea de + órdenes. +* Invocación de guix edit:: Editar las definiciones de paquetes. +* Invocación de guix download:: Descargar un fichero e imprimir su hash. +* Invocación de guix hash:: Calcular el hash criptográfico de un fichero. +* Invocación de guix import:: Importar definiciones de paquetes. +* Invocación de guix refresh:: Actualizar definiciones de paquetes. +* Invocación de guix lint:: Encontrar errores en definiciones de paquetes. +* Invocación de guix size:: Perfilar el uso del disco. +* Invocación de guix graph:: Visualizar el grafo de paquetes. +* Invocación de guix publish:: Compartir sustituciones. +* Invocación de guix challenge:: Poner a prueba servidores de + sustituciones. +* Invocación de guix copy:: Copiar a y desde un almacén remoto. +* Invocación de guix container:: Aislamiento de procesos. +* Invocación de guix weather:: Comprobar la disponibilidad de + sustituciones. +* Invocación de guix processes:: Enumerar los procesos cliente. +@end menu + +@node Invocación de guix build +@section Invocación de @command{guix build} + +@cindex construcción de paquetes +@cindex @command{guix build} +La orden @command{guix build} construye paquetes o derivaciones y sus +dependencias, e imprime las rutas del almacén resultantes. Fíjese que no +modifica el perfil de la usuaria---este es el trabajo de la orden +@command{guix package} (@pxref{Invocación de guix package}). Por tanto, es útil +principalmente para las desarrolladoras de la distribución. + +La sintaxis general es: + +@example +guix build @var{opciones} @var{paquete-o-derivación}@dots{} +@end example + +Como ejemplo, la siguiente orden construye las últimas versiones de Emacs y +Guile, muestra sus log de construcción, y finalmente muestra los directorios +resultantes: + +@example +guix build emacs guile +@end example + +De forma similar, la siguiente orden construye todos los paquetes +disponibles: + +@example +guix build --quiet --keep-going \ + `guix package -A | cut -f1,2 --output-delimiter=@@` +@end example + +@var{paquete-o-derivación} puede ser tanto el nombre de un paquete que se +encuentra en la distribución de software como @code{coreutils} o +@code{coreutils@@8.20}, o una derivación como +@file{/gnu/store/@dots{}-coreutils-8.19.drv}. En el primer caso, el paquete +de nombre (y opcionalmente versión) correspondiente se busca entre los +módulos de la distribución GNU (@pxref{Módulos de paquetes}). + +De manera alternativa, la opción @code{--expression} puede ser usada para +especificar una expresión Scheme que evalúa a un paquete; esto es útil para +la desambiguación entre varios paquetes del mismo nombre o si se necesitan +variaciones del paquete. + +Puede haber cero o más @var{opciones}. Las opciones disponibles se describen +en la subsección siguiente. + +@menu +* Opciones comunes de construcción:: Opciones de construcción para la + mayoría de órdenes. +* Opciones de transformación de paquetes:: Crear variantes de paquetes. +* Opciones de construcción adicionales:: Opciones específicas de 'guix + build'. +* Depuración de fallos de construcción:: Experiencia de empaquetamiento + en la vida real. +@end menu + +@node Opciones comunes de construcción +@subsection Opciones comunes de construcción + +Un número de opciones que controlan el proceso de construcción son comunes a +@command{guix build} y otras órdenes que pueden lanzar construcciones, como +@command{guix package} o @command{guix archive}. Son las siguientes: + +@table @code + +@item --load-path=@var{directorio} +@itemx -L @var{directorio} +Añade @var{directorio} al frente de la ruta de búsqueda de módulos de +paquetes (@pxref{Módulos de paquetes}). + +Esto permite a las usuarias definir sus propios paquetes y hacerlos visibles +a las herramientas de línea de órdenes. + +@item --keep-failed +@itemx -K +Mantiene los árboles de construcción de las construcciones fallidas. Por +tanto, si una construcción falla, su árbol de construcción se mantiene bajo +@file{/tmp}, en un directorio cuyo nombre se muestra al final del log de +construcción. Esto es útil cuando se depuran problemas en la +construcción. @xref{Depuración de fallos de construcción}, para trucos y consejos sobre +cómo depurar problemas en la construcción. + +Esta opción no tiene efecto cuando se conecta a un daemon remoto con una URI +@code{guix://} (@pxref{El almacén, the @code{GUIX_DAEMON_SOCKET} variable}). + +@item --keep-going +@itemx -k +Seguir adelante cuando alguna de las derivaciones de un fallo durante la +construcción; devuelve una única vez todas las construcciones que se han +completado o bien han fallado. + +El comportamiento predeterminado es parar tan pronto una de las derivaciones +especificadas falle. + +@item --dry-run +@itemx -n +No construye las derivaciones. + +@anchor{fallback-option} +@item --fallback +Cuando la sustitución de un binario preconstruido falle, intenta la +construcción local de paquetes (@pxref{Fallos en las sustituciones}). + +@item --substitute-urls=@var{urls} +@anchor{client-substitute-urls} +Considera @var{urls} la lista separada por espacios de URLs de fuentes de +sustituciones, anulando la lista predeterminada de URLs de +@command{guix-daemon} (@pxref{daemon-substitute-urls,, @command{guix-daemon +URLs}}). + +Significa que las sustituciones puede ser descargadas de @var{urls}, +mientras que estén firmadas por una clave autorizada por la administradora +del sistema (@pxref{Sustituciones}). + +Cuando @var{urls} es la cadena vacía, las sustituciones están efectivamente +deshabilitadas. + +@item --no-substitutes +No usa sustituciones para la construcción de productos. Esto es, siempre +realiza las construcciones localmente en vez de permitir la descarga de +binarios pre-construidos (@pxref{Sustituciones}). + +@item --no-grafts +No ``injerta'' paquetes. En la práctica esto significa que las +actualizaciones de paquetes disponibles como injertos no se +aplican. @xref{Actualizaciones de seguridad}, para más información sobre los injertos. + +@item --rounds=@var{n} +Construye cada derivación @var{n} veces seguidas, y lanza un error si los +resultados de las construcciones consecutivas no son idénticos bit-a-bit. + +Esto es útil para la detección de procesos de construcción +no-deterministas. Los procesos de construcción no-deterministas son un +problema puesto que prácticamente imposibilitan a las usuarias la +@emph{verificación} de la autenticidad de binarios proporcionados por +terceras partes. @xref{Invocación de guix challenge}, para más sobre esto. + +Fíjese que, actualmente, los resultados de las construcciones discordantes +no se mantienen, por lo que debe que investigar manualmente en caso de un +error---por ejemplo, mediante la extracción de uno de los resultados con +@code{guix archive --export} (@pxref{Invocación de guix archive}), seguida de una +reconstrucción, y finalmente la comparación de los dos resultados. + +@item --no-build-hook +No intenta delegar construcciones a través del ``hook de construcción'' del +daemon (@pxref{Configuración de delegación del daemon}). Es decir, siempre realiza las +construcciones de manera local en vez de delegando construcciones a máquinas +remotas. + +@item --max-silent-time=@var{segundos} +Cuando la construcción o sustitución permanece en silencio más de +@var{segundos}, la finaliza e informa de un fallo de construcción. + +Por defecto, se respeta la configuración del daemon (@pxref{Invocación de guix-daemon, @code{--max-silent-time}}). + +@item --timeout=@var{segundos} +Del mismo modo, cuando el proceso de construcción o sustitución dura más de +@var{segundos}, lo termina e informa un fallo de construcción. + +Por defecto, se respeta la configuración del daemon (@pxref{Invocación de guix-daemon, @code{--timeout}}). + +@c Note: This option is actually not part of %standard-build-options but +@c most programs honor it. +@cindex verbosity, of the command-line tools +@cindex logs de construcción, nivel de descripción +@item -v @var{nivel} +@itemx --verbosity=@var{nivel} +Use the given verbosity @var{level}, an integer. Choosing 0 means that no +output is produced, 1 is for quiet output, and 2 shows all the build log +output on standard error. + +@item --cores=@var{n} +@itemx -c @var{n} +Permite usar @var{n} núcleos de la CPU para la construcción. El valor +especial @code{0} significa usar tantos como núcleos haya en la CPU. + +@item --max-jobs=@var{n} +@itemx -M @var{n} +Permite como máximo @var{n} trabajos de construcción en +paralelo. @xref{Invocación de guix-daemon, @code{--max-jobs}}, para detalles +acerca de esta opción y la opción equivalente de @command{guix-daemon}. + +@item --debug=@var{nivel} +Produce debugging output coming from the build daemon. @var{level} must be +an integer between 0 and 5; higher means more verbose output. Setting a +level of 4 or more may be helpful when debugging setup issues with the build +daemon. + +@end table + +Tras las cortinas, @command{guix build} es esencialmente una interfaz al +procedimiento @code{package-derivation} del módulo @code{(guix packages)}, y +al procedimiento @code{build-derivations} del módulo @code{(guix +derivations)}. + +Además de las opciones proporcionadas explícitamente en la línea de órdenes, +@command{guix build} y otras órdenes @command{guix} que permiten la +construcción respetan el contenido de la variable de entorno +@code{GUIX_BUILD_OPTIONS}. + +@defvr {Variable de entorno} GUIX_BUILD_OPTIONS +Las usuarias pueden definir esta variable para que contenga una lista de +opciones de línea de órdenes que se usarán automáticamente por @command{guix +build} y otras órdenes @command{guix} que puedan realizar construcciones, +como en el ejemplo siguiente: + +@example +$ export GUIX_BUILD_OPTIONS="--no-substitutes -c 2 -L /foo/bar" +@end example + +Estas opciones se analizan independientemente, y el resultado se añade a +continuación de las opciones de línea de órdenes. +@end defvr + + +@node Opciones de transformación de paquetes +@subsection Opciones de transformación de paquetes + +@cindex variaciones de paquetes +Otro conjunto de opciones de línea de órdenes permitidas por @command{guix +build} y también @command{guix package} son las @dfn{opciones de +transformación de paquetes}. Son opciones que hacen posible la definición de +@dfn{variaciones de paquetes}---por ejemplo, paquetes construidos con un +código fuente diferente. Es una forma conveniente de crear paquetes +personalizados al vuelo sin tener que escribir las definiciones de las +variaciones del paquete (@pxref{Definición de paquetes}). + +@table @code + +@item --with-source=@var{fuente} +@itemx --with-source=@var{paquete}=@var{fuente} +@itemx --with-source=@var{paquete}@@@var{versión}=@var{fuente} +Usa @var{fuente} como la fuente de @var{paquete}, y @var{versión} como su +número de versión. @var{fuente} debe ser un nombre de fichero o una URL, +como en @command{guix download} (@pxref{Invocación de guix download}). + +Cuando se omite @var{paquete}, se toma el nombre de paquete especificado en +la línea de ordenes que coincide con el nombre base de @var{fuente}---por +ejemplo, si @var{fuente} fuese @code{/src/guile-2.0.10.tar.gz}, el paquete +correspondiente sería @code{guile}. + +Del mismo modo, si se omite @var{versión}, la cadena de versión se deduce de +@var{đuente}; en el ejemplo previo sería @code{2.0.10}. + +Esta opción permite a las usuarias probar versiones del paquete distintas a +las proporcionadas en la distribución. El ejemplo siguiente descarga +@file{ed-1.7.tar.gz} de un espejo GNU y lo usa como la fuente para el +paquete @code{ed}: + +@example +guix build ed --with-source=mirror://gnu/ed/ed-1.7.tar.gz +@end example + +Como desarrolladora, @code{--with-source} facilita la prueba de versiones +candidatas para la publicación: + +@example +guix build guile --with-source=../guile-2.0.9.219-e1bb7.tar.xz +@end example + +@dots{} o la construcción desde una revisión en un entorno limpio: + +@example +$ git clone git://git.sv.gnu.org/guix.git +$ guix build guix --with-source=guix@@1.0=./guix +@end example + +@item --with-input=@var{paquete}=@var{reemplazo} +Substituye dependencias de @var{paquete} por dependencias de +@var{reemplazo}. @var{paquete} debe ser un nombre de paquete, y +@var{reemplazo} debe ser una especificación de paquete como @code{guile} o +@code{guile@@1.8}. + +Por ejemplo, la orden siguiente construye Guix, pero substituye su +dependencia de la versión estable actual de Guile con una dependencia en la +versión antigua de Guile, @code{guile@@2.0}: + +@example +guix build --with-input=guile=guile@@2.0 guix +@end example + +Esta sustitución se realiza de forma recursiva y en profundidad. Por lo que +en este ejemplo, tanto @code{guix} como su dependencia @code{guile-json} +(que también depende de @code{guile}) se reconstruyen contra +@code{guile@@2.0}. + +Se implementa usando el procedimiento Scheme @code{package-input-rewriting} +(@pxref{Definición de paquetes, @code{package-input-rewriting}}). + +@item --with-graft=@var{paquete}=@var{reemplazo} +Es similar a @code{--with-input} pero con una diferencia importante: en vez +de reconstruir la cadena de dependencias completa, @var{reemplazo} se +construye y se @dfn{injerta} en los binarios que inicialmente hacían +referencia a @var{paquete}. @xref{Actualizaciones de seguridad}, para más información +sobre injertos. + +Por ejemplo, la orden siguiente injerta la versión 3.5.4 de GnuTLS en Wget y +todas sus dependencias, substituyendo las referencias a la versión de GnuTLS +que tienen actualmente: + +@example +guix build --with-graft=gnutls=gnutls@@3.5.4 wget +@end example + +Esta opción tiene la ventaja de ser mucho más rápida que la reconstrucción +de todo. Pero hay una trampa: funciona si y solo si @var{paquete} y +@var{reemplazo} son estrictamente compatibles---por ejemplo, si proporcionan +una biblioteca, la interfaz binaria de aplicación (ABI) de dichas +bibliotecas debe ser compatible. Si @var{reemplazo} es incompatible de +alguna manera con @var{paquete}, el paquete resultante puede no ser +usable. ¡Úsela con precaución! + +@item --with-git-url=@var{paquete}=@var{url} +@cindex Git, usar la última revisión +@cindex última revisión, construcción +Build @var{package} from the latest commit of the @code{master} branch of +the Git repository at @var{url}. Git sub-modules of the repository are +fetched, recursively. + +For example, the following command builds the NumPy Python library against +the latest commit of the master branch of Python itself: + +@example +guix build python-numpy \ + --with-git-url=python=https://github.com/python/cpython +@end example + +This option can also be combined with @code{--with-branch} or +@code{--with-commit} (see below). + +@cindex integración continua +Obviously, since it uses the latest commit of the given branch, the result +of such a command varies over time. Nevertheless it is a convenient way to +rebuild entire software stacks against the latest commit of one or more +packages. This is particularly useful in the context of continuous +integration (CI). + +Checkouts are kept in a cache under @file{~/.cache/guix/checkouts} to speed +up consecutive accesses to the same repository. You may want to clean it up +once in a while to save disk space. + +@item --with-branch=@var{paquete}=@var{rama} +Build @var{package} from the latest commit of @var{branch}. If the +@code{source} field of @var{package} is an origin with the @code{git-fetch} +method (@pxref{Referencia de ``origin''}) or a @code{git-checkout} object, the +repository URL is taken from that @code{source}. Otherwise you have to use +@code{--with-git-url} to specify the URL of the Git repository. + +For instance, the following command builds @code{guile-sqlite3} from the +latest commit of its @code{master} branch, and then builds @code{guix} +(which depends on it) and @code{cuirass} (which depends on @code{guix}) +against this specific @code{guile-sqlite3} build: + +@example +guix build --with-branch=guile-sqlite3=master cuirass +@end example + +@item --with-commit=@var{paquete}=@var{revisión} +This is similar to @code{--with-branch}, except that it builds from +@var{commit} rather than the tip of a branch. @var{commit} must be a valid +Git commit SHA1 identifier. +@end table + +@node Opciones de construcción adicionales +@subsection Opciones de construcción adicionales + +Las opciones de línea de ordenes presentadas a continuación son específicas +de @command{guix build}. + +@table @code + +@item --quiet +@itemx -q +Build quietly, without displaying the build log; this is equivalent to +@code{--verbosity=0}. Upon completion, the build log is kept in @file{/var} +(or similar) and can always be retrieved using the @option{--log-file} +option. + +@item --file=@var{fichero} +@itemx -f @var{fichero} +Construye el paquete, derivación u otro objeto tipo-fichero al que evalúa el +código en @var{fichero} (@pxref{Expresiones-G, file-like objects}). + +Como un ejemplo, @var{fichero} puede contener una definición como esta +(@pxref{Definición de paquetes}): + +@example +@verbatiminclude package-hello.scm +@end example + +@item --expression=@var{expr} +@itemx -e @var{expr} +Construye el paquete o derivación al que @var{expr} evaulua. + +Por ejemplo, @var{expr} puede ser @code{(@@ (gnu packages guile) +guile-1.8)}, que designa sin ambigüedad a esta variante específica de la +versión 1.8 de Guile. + +De manera alternativa, @var{expr} puede ser una expresión-G, en cuyo caso se +usa como un programa de construcción pasado a @code{gexp->derivation} +(@pxref{Expresiones-G}). + +Por último, @var{expr} puede hacer referencia a un procedimiento mónadico +sin parámetros (@pxref{La mónada del almacén}). El procedimiento debe devolver una +derivación como un valor monádico, el cual después se pasa a través de +@code{run-with-store}. + +@item --source +@itemx -S +Construye las derivaciones de las fuentes de los paquetes, en vez de los +paquetes mismos. + +Por ejemplo, @code{guix build -S gcc} devuelve algo como +@file{/gnu/store/@dots{}-gcc-4.7.2.tar.bz2}, el cual es el archivador tar de +fuentes de GCC. + +El archivador tar devuelto es el resultado de aplicar cualquier parche y +fragmento de código en el origen (campo @code{origin}) del paquete +(@pxref{Definición de paquetes}). + +@item --sources +Obtiene y devuelve las fuentes de @var{paquete-o-derivación} y todas sus +dependencias, recursivamente. Esto es útil para obtener una copia local de +todo el código fuente necesario para construir los @var{paquetes}, +permitiendole construirlos llegado el momento sin acceso a la red. Es una +extensión de la opción @code{--source} y puede aceptar uno de los siguientes +valores opcionales como parámetro: + +@table @code +@item package +Este valor hace que la opción @code{--sources} se comporte de la misma +manera que la opción @code{--source}. + +@item all +Construye las derivaciones de las fuentes de todos los paquetes, incluyendo +cualquier fuente que pueda enumerarse como entrada (campo +@code{inputs}). Este es el valor predeterminado. + +@example +$ guix build --sources tzdata +The following derivations will be built: + /gnu/store/@dots{}-tzdata2015b.tar.gz.drv + /gnu/store/@dots{}-tzcode2015b.tar.gz.drv +@end example + +@item transitive +Construye las derivaciones de fuentes de todos los paquetes, así como todas +las entradas transitivas de los paquetes. Esto puede usarse, por ejemplo, +para obtener las fuentes de paquetes para una construcción posterior sin +conexión a la red. + +@example +$ guix build --sources=transitive tzdata +The following derivations will be built: + /gnu/store/@dots{}-tzcode2015b.tar.gz.drv + /gnu/store/@dots{}-findutils-4.4.2.tar.xz.drv + /gnu/store/@dots{}-grep-2.21.tar.xz.drv + /gnu/store/@dots{}-coreutils-8.23.tar.xz.drv + /gnu/store/@dots{}-make-4.1.tar.xz.drv + /gnu/store/@dots{}-bash-4.3.tar.xz.drv +@dots{} +@end example + +@end table + +@item --system=@var{sistema} +@itemx -s @var{sistema} +Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of the +system type of the build host. The @command{guix build} command allows you +to repeat this option several times, in which case it builds for all the +specified systems; other commands ignore extraneous @option{-s} options. + +@quotation Nota +La opción @code{--system} es para compilación @emph{nativa} y no debe +confundirse con la compilación cruzada. Véase @code{--target} más adelante +para información sobre compilación cruzada. +@end quotation + +Un ejemplo de uso de esta opción es en sistemas basados en Linux, que pueden +emular diferentes personalidades. Por ejemplo, pasar +@code{--system=i686-linux} en un sistema @code{x86_64-linux} o +@code{--system=armhf-linux} en un sistema @code{aarch64-linux} le permite +construir paquetes en un entorno de 32-bits completo. + +@quotation Nota +La construcción para un sistema @code{armhf-linux} está habilitada +incondicionalmente en máquinas @code{aarch64-linux}, aunque determinados +procesadores aarch64 no permiten esta funcionalidad, notablemente el +ThunderX. +@end quotation + +De manera similar, cuando la emulación transparente con QEMU y +@code{binfmt_misc} está habilitada (@pxref{Servicios de virtualización, +@code{qemu-binfmt-service-type}}), puede construir para cualquier sistema +para el que un manejador QEMU de @code{binfmt_misc} esté instalado. + +Las construcciones para un sistema distinto al de la máquina que usa pueden +delegarse también a una máquina remota de la arquitectura +correcta. @xref{Configuración de delegación del daemon}, para más información sobre +delegación. + +@item --target=@var{tripleta} +@cindex compilación cruzada +Compilación cruzada para la @var{tripleta}, que debe ser una tripleta GNU +válida, cómo @code{"mips64el-linux-gnu"} (@pxref{Specifying target triplets, +GNU configuration triplets,, autoconf, Autoconf}). + +@anchor{build-check} +@item --check +@cindex determinismo, comprobación +@cindex reproducibilidad, comprobación +Reconstruye @var{paquete-o-derivación}, que ya está disponible en el +almacén, y emite un error si los resultados de la construcción no son +idénticos bit-a-bit. + +Este mecanismo le permite comprobar si sustituciones previamente instaladas +son genuinas (@pxref{Sustituciones}), o si el resultado de la construcción de +un paquete es determinista. @xref{Invocación de guix challenge}, para más +información de referencia y herramientas. + +Cuando se usa conjuntamente con @option{--keep-failed}, la salida que +difiere se mantiene en el almacén, bajo +@file{/gnu/store/@dots{}-check}. Esto hace fácil buscar diferencias entre +los dos resultados. + +@item --repair +@cindex reparar elementos del almacén +@cindex corrupción, recuperarse de +Intenta reparar los elementos del almacén especificados, si están corruptos, +volviendo a descargarlos o reconstruyendolos. + +Esta operación no es atómica y por lo tanto está restringida a @code{root}. + +@item --derivations +@itemx -d +Devuelve las rutas de derivación, no las rutas de salida, de los paquetes +proporcionados. + +@item --root=@var{fichero} +@itemx -r @var{fichero} +@cindex GC, añadir raíces +@cindex raíces del recolector de basura, añadir +Hace que @var{fichero} sea un enlace simbólico al resultado, y lo registra +como una raíz del recolector de basura. + +Consecuentemente, los resultados de esta invocación de @command{guix build} +se protegen de la recolección de basura hasta que @var{fichero} se +elimine. Cuando se omite esa opción, los resultados son candidatos a la +recolección de basura en cuanto la construcción se haya +completado. @xref{Invocación de guix gc}, para más sobre las raíces del +recolector de basura. + +@item --log-file +@cindex logs de construcción, acceso +Devuelve los nombres de ficheros o URL de los log de construcción para el +@var{paquete-o-derivación} proporcionado, o emite un error si no se +encuentran los log de construcción. + +Esto funciona independientemente de cómo se especificasen los paquetes o +derivaciones. Por ejemplo, las siguientes invocaciones son equivalentes: + +@example +guix build --log-file `guix build -d guile` +guix build --log-file `guix build guile` +guix build --log-file guile +guix build --log-file -e '(@@ (gnu packages guile) guile-2.0)' +@end example + +Si un log no está disponible localmente, y a menos que se proporcione +@code{--no-substitutes}, la orden busca el log correspondiente en uno de los +servidores de sustituciones (como se especificaron con +@code{--substitute-urls}). + +Por lo que dado el caso, imaginese que desea ver el log de construcción de +GDB en MIPS, pero realmente está en una máquina @code{x86_64}: + +@example +$ guix build --log-file gdb -s mips64el-linux +https://@value{SUBSTITUTE-SERVER}/log/@dots{}-gdb-7.10 +@end example + +¡Puede acceder libremente a una biblioteca inmensa de log de construcción! +@end table + +@node Depuración de fallos de construcción +@subsection Depuración de fallos de construcción + +@cindex fallos de construcción, depuración +Cuando esté definiendo un paquete nuevo (@pxref{Definición de paquetes}), +probablemente se encuentre que dedicando algún tiempo a depurar y afinar la +construcción hasta obtener un resultado satisfactorio. Para hacerlo, tiene +que lanzar manualmente las órdenes de construcción en un entorno tan similar +como sea posible al que el daemon de construcción usa. + +Para ello, la primera cosa a hacer es usar la opción @option{--keep-failed} +o @option{-K} de @command{guix build}, lo que mantiene el árbol de la +construcción fallida en @file{/tmp} o el directorio que especificase con +@code{TMPDIR} (@pxref{Invocación de guix build, @code{--keep-failed}}). + +De ahí en adelante, puede usar @command{cd} para ir al árbol de la +construcción fallida y cargar el fichero @file{environment-variables}, que +contiene todas las definiciones de variables de entorno que existían cuando +la construcción falló. Digamos que está depurando un fallo en la +construcción del paquete @code{foo}; una sesión típica sería así: + +@example +$ guix build foo -K +@dots{} @i{build fails} +$ cd /tmp/guix-build-foo.drv-0 +$ source ./environment-variables +$ cd foo-1.2 +@end example + +Ahora puede invocar órdenes (casi) como si fuese el daemon y encontrar los +errores en su proceso de construcción. + +A veces ocurre que, por ejemplo, las pruebas de un paquete pasan cuando las +ejecuta manualmente pero fallan cuando el daemon las ejecuta. Esto puede +suceder debido a que el daemon construye dentro de contenedores donde, al +contrario que en nuestro entorno previo, el acceso a la red no está +disponible, @file{/bin/sh} no existe, etc. (@pxref{Configuración del entorno de construcción}). + +En esos casos, puede tener que inspeccionar el proceso de construcción desde +un contenedor similar al creado por el daemon de construcción: + +@example +$ guix build -K foo +@dots{} +$ cd /tmp/guix-build-foo.drv-0 +$ guix environment --no-grafts -C foo --ad-hoc strace gdb +[env]# source ./environment-variables +[env]# cd foo-1.2 +@end example + +Aquí, @command{guix environment -C} crea un contenedor y lanza un shell +nuevo en él (@pxref{Invocación de guix environment}). El fragmento +@command{--ad-hoc strace gdb} añade las ordenes @command{strace} y +@command{gdb} al contenedor, las cuales pueden resultar útiles durante la +depuración. La opción @option{--no-grafts} asegura que obtenemos exactamente +el mismo entorno, con paquetes sin injertos (@pxref{Actualizaciones de seguridad}, para +más información sobre los injertos). + +Para acercarnos más al contenedor usado por el daemon de construcción, +podemos eliminar @file{/bin/sh}: + +@example +[env]# rm /bin/sh +@end example + +(No se preocupe, es inocuo: todo esto ocurre en el contenedor de usar y +tirar creado por @command{guix environment}). + +La orden @command{strace} probablemente no esté en la ruta de búsqueda, pero +podemos ejecutar: + +@example +[env]# $GUIX_ENVIRONMENT/bin/strace -f -o log make check +@end example + +De este modo, no solo habrá reproducido las variables de entorno que usa el +daemon, también estará ejecutando el proceso de construcción en un +contenedor similar al usado por el daemon. + + +@node Invocación de guix edit +@section Invocación de @command{guix edit} + +@cindex @command{guix edit} +@cindex definición de paquete, edición +¡Tantos paquetes, tantos ficheros de fuentes! La orden @command{guix edit} +facilita la vida de las usuarias y empaquetadoras apuntando su editor al +fichero de fuentes que contiene la definición de los paquetes +especificados. Por ejemplo: + +@example +guix edit gcc@@4.9 vim +@end example + +@noindent +lanza el programa especificado en la variable de entorno @code{VISUAL} o en +@code{EDITOR} para ver la receta de GCC@tie{}4.9.3 y la de Vim. + +Si está usando una copia de trabajo de Git de Guix (@pxref{Construcción desde Git}), o ha creado sus propios paquetes en @code{GUIX_PACKAGE_PATH} +(@pxref{Módulos de paquetes}), será capaz de editar las recetas de los +paquetes. En otros casos, podrá examinar las recetas en modo de lectura +únicamente para paquetes actualmente en el almacén. + + +@node Invocación de guix download +@section Invocación de @command{guix download} + +@cindex @command{guix download} +@cindex descargando las fuentes de paquetes +Durante la escritura de una definición de paquete, las desarrolladoras +típicamente tienen que descargar un archivador tar de fuentes, calcular su +hash SHA256 y escribir ese hash en la definición del paquete +(@pxref{Definición de paquetes}). La herramienta @command{guix download} ayuda +con esta tarea: descarga un fichero de la URI proporcionada, lo añade al +almacén e imprime tanto su nombre de fichero en el almacén como su hash +SHA256. + +El hecho de que el fichero descargado se añada al almacén ahorra ancho de +banda: cuando el desarrollador intenta construir el paquete recién definido +con @command{guix build}, el archivador de fuentes no tiene que descargarse +de nuevo porque ya está en el almacén. También es una forma conveniente de +conservar ficheros temporalmente, que pueden ser borrados en un momento dado +(@pxref{Invocación de guix gc}). + +La orden @command{guix download} acepta las mismas URI que las usadas en las +definiciones de paquetes. En particular, permite URI @code{mirror://}. Las +URI @code{https} (HTTP sobre TLS) se aceptan @emph{cuando} el enlace Guile +con GnuTLS está disponible en el entorno de la usuaria; cuando no está +disponible se emite un error. @xref{Guile Preparations, how to install the +GnuTLS bindings for Guile,, gnutls-guile, GnuTLS-Guile}, para más +información. + +@command{guix download} verifica los certificados del servidor HTTPS +cargando las autoridades X.509 del directorio al que apunta la variable de +entorno @code{SSL_CERT_DIR} (@pxref{Certificados X.509}), a menos que se use +@option{--no-check-certificate}. + +Las siguientes opciones están disponibles: + +@table @code +@item --format=@var{fmt} +@itemx -f @var{fmt} +Escribe el hash en el formato especificado por @var{fmt}. Para más +información sobre los valores aceptados en @var{fmt}, @pxref{Invocación de guix hash}. + +@item --no-check-certificate +No valida los certificados X.509 de los servidores HTTPS. + +Cuando se usa esta opción, no tiene @emph{absolutamente ninguna garantía} de +que está comunicando con el servidor responsable de la URL auténtico, lo que +le hace vulnerables a ataques de intercepción (``man-in-the-middle''). + +@item --output=@var{fichero} +@itemx -o @var{fichero} +Almacena el fichero descargado en @var{fichero} en vez de añadirlo al +almacén. +@end table + +@node Invocación de guix hash +@section Invocación de @command{guix hash} + +@cindex @command{guix hash} +La orden @command{guix hash} calcula el hash SHA256 de un fichero. Es +principalmente una conveniente herramienta para cualquiera que contribuya a +la distribución: calcula el hash criptográfico de un fichero, que puede +usarse en la definición de un paquete (@pxref{Definición de paquetes}). + +La sintaxis general es: + +@example +guix hash @var{opciones} @var{fichero} +@end example + +Cuando @var{fichero} es @code{-} (un guión), @command{guix hash} calcula el +hash de los datos leídos por la entrada estándar. @command{guix hash} tiene +las siguientes opciones: + +@table @code + +@item --format=@var{fmt} +@itemx -f @var{fmt} +Escribe el hash en el formato especificado por @var{fmt}. + +Los formatos disponibles son: @code{nix-base32}, @code{base32}, +@code{base16} (se puede usar también @code{hex} y @code{hexadecimal}). + +Si no se especifica la opción @option{--format}, @command{guix hash} +mostrará el hash en @code{nix-base32}. Esta representación es la usada en +las definiciones de paquetes. + +@item --recursive +@itemx -r +Calcula el hash de @var{fichero} recursivamente. + +@c FIXME: Replace xref above with xref to an ``Archive'' section when +@c it exists. +Es este caso el hash se calcula en un archivador que contiene @var{fichero}, +incluyendo su contenido si es un directorio. Algunos de los metadatos de +@var{fichero} son parte del archivador; por ejemplo, cuando @var{fichero} es +un fichero normal, el hash es diferente dependiendo de si @var{fichero} es +ejecutable o no. Los metadatos como las marcas de tiempo no influyen en el +hash (@pxref{Invocación de guix archive}). + +@item --exclude-vcs +@itemx -x +Cuando se combina con @option{--recursive}, excluye los directorios del +sistema de control de versiones (@file{.bzr}, @file{.git}, @file{.hg}, +etc.). + +@vindex git-fetch +Como un ejemplo, así es como calcularía el hash de una copia de trabajo Git, +lo cual es útil cuando se usa el método @code{git-fetch} (@pxref{Referencia de ``origin''}): + +@example +$ git clone http://example.org/foo.git +$ cd foo +$ guix hash -rx . +@end example +@end table + +@node Invocación de guix import +@section Invocación de @command{guix import} + +@cindex importar paquetes +@cindex importación de un paquete +@cindex conversión de un paquete +@cindex Invocación de @command{guix import} +La orden @command{guix import} es útil para quienes desean añadir un paquete +a la distribución con el menor trabajo posible---una demanda legítima. La +orden conoce algunos repositorios de los que puede ``importar'' metadatos de +paquetes. El resultado es una definición de paquete, o una plantilla de +ella, en el formato que conocemos (@pxref{Definición de paquetes}). + +La sintaxis general es: + +@example +guix import @var{importador} @var{opciones}@dots{} +@end example + +@var{importador} especifica la fuente de la que se importan los metadatos +del paquete, @var{opciones} especifica un identificador de paquete y otras +opciones específicas del @var{importador}. Actualmente, los ``importadores'' +disponibles son: + +@table @code +@item gnu +Importa los metadatos del paquete GNU seleccionado. Proporciona una +plantilla para la última versión de dicho paquete GNU, incluyendo el hash de +su archivador tar de fuentes, y su sinopsis y descripción canónica. + +Información adicional como las dependencias del paquete y su licencia deben +ser deducidas manualmente. + +Por ejemplo, la siguiente orden devuelve una definición de paquete para +GNU@tie{}Hello. + +@example +guix import gnu hello +@end example + +Las opciones específicas de línea de ordenes son: + +@table @code +@item --key-download=@var{política} +Como en @code{guix refresh}, especifica la política de tratamiento de las +claves OpenPGP no encontradas cuando se verifica la firma del +paquete. @xref{Invocación de guix refresh, @code{--key-download}}. +@end table + +@item pypi +@cindex pypi +Importa metadatos desde el @uref{https://pypi.python.org/, índice de +paquetes Python (PyPI)}. La información se toma de la descripción con +formato JSON disponible en @code{pypi.python.org} y habitualmente incluye +toda la información relevante, incluyendo las dependencias del paquete. Para +una máxima eficiencia, se recomienda la instalación de la utilidad +@command{unzip}, de manera que el importador pueda extraer los archivos +wheel de Python y obtener datos de ellos. + +La siguiente orden importa los meta-datos para el paquete de Python +@code{itsdangerous}: + +@example +guix import pypi itsdangerous +@end example + +@table @code +@item --recursive +@itemx -r +Recorre el grafo de dependencias del paquete original proporcionado +recursivamente y genera expresiones de paquete para todos aquellos paquetes +que no estén todavía en Guix. +@end table + +@item gem +@cindex gem +Importa metadatos desde @uref{https://rubygems.org/, RubyGems}. La +información se extrae de la descripción en formato JSON disponible en +@code{rubygems.org} e incluye la información más relevante, incluyendo las +dependencias en tiempo de ejecución. Hay algunos puntos a tener en cuenta, +no obstante. Los metadatos no distinguen entre sinopsis y descripción, por +lo que se usa la misma cadena para ambos campos. Adicionalmente, los +detalles de las dependencias no-Ruby necesarias para construir extensiones +nativas no está disponible y se deja como ejercicio a la empaquetadora. + +La siguiente orden importa los meta-datos para el paquete de Ruby +@code{rails}: + +@example +guix import gem rails +@end example + +@table @code +@item --recursive +@itemx -r +Recorre el grafo de dependencias del paquete original proporcionado +recursivamente y genera expresiones de paquete para todos aquellos paquetes +que no estén todavía en Guix. +@end table + +@item cpan +@cindex CPAN +Importa metadatos desde @uref{https://www.metacpan.org/, MetaCPAN}. La +información se extrae de la descripción en formato JSON disponible a través +del @uref{https://fastapi.metacpan.org/, API de MetaCPAN} e incluye la +información más relevante, como las dependencias de otros módulos. La +información de la licencia debe ser comprobada atentamente. Si Perl está +disponible en el almacén, se usará la utilidad @code{corelist} para borrar +los módulos básicos de la lista de dependencias. + +La siguiente orden importa los metadatos del módulo Perl +@code{Acme::Boolean}: + +@example +guix import cpan Acme::Boolean +@end example + +@item cran +@cindex CRAN +@cindex Bioconductor +Importa metadatos desde @uref{https://cran.r-project.org/, CRAN}, el +repositorio central para el @uref{http://r-project.org, entorno estadístico +y gráfico GNU@tie{}R}. + +La información se extrae del fichero @code{DESCRIPTION} del paquete. + +La siguiente orden importa los metadatos del paquete de R @code{Cairo}: + +@example +guix import cran Cairo +@end example + +Cuando se añade @code{--recursive}, el importador recorrerá el grafo de +dependencias del paquete original proporcionado recursivamente y generará +expresiones de paquetes para todos aquellos que no estén todavía en Guix. + +Cuando se agrega @code{--archive=bioconductor}, los metadatos se importan de +@uref{https://www.bioconductor.org, Bioconductor}, un repositorio de +paquetes R para el análisis y comprensión de datos genéticos de alto caudal +en bioinformática. + +La información se extrae del fichero @code{DESCRIPTION} del paquete +publicado en la interfaz web del repositorio SVN de Bioconductor. + +La siguiente orden importa los metadatos del paquete de R +@code{GenomicRanges}: + +@example +guix import cran --archive=bioconductor GenomicRanges +@end example + +@item texlive +@cindex Tex Live +@cindex CTAN +Importa metadatos desde @uref{http://www.ctan.org/, CTAN}, la completa red +de archivos TeX para paquetes TeX que son parte de la +@uref{https://www.tug.org/texlive/, distribución TeX Live}. + +La información del paquete se obtiene a través del API XML proporcionado por +CTAN, mientras que el código fuente se descarga del repositorio SVN del +proyecto TeX Live. Se hace porque CTAN no guarda archivos con versiones. + +La siguiente orden importa los metadatos del paquete de TeX @code{fontspec}: + +@example +guix import texlive fontspec +@end example + +Cuando se añade @code{--archive=DIRECTORIO}, el código fuente no se descarga +del subdirectorio @file{latex} del árbol @file{texmf-dist/source} en el +repositorio SVN de Tex Live, sino de el directorio especificado bajo la +misma raíz. + +La siguiente orden importa los metadatos del paquete @code{ifxetex} de CTAN +mientras que obtiene las fuentes del directorio @file{texmf/source/generic}: + +@example +guix import texlive --archive=generic ifxetex +@end example + +@item json +@cindex JSON, importación +Importa metadatos de paquetes desde un fichero JSON local. Considere el +siguiente ejemplo de definición de paquete en formato JSON: + +@example +@{ + "name": "hello", + "version": "2.10", + "source": "mirror://gnu/hello/hello-2.10.tar.gz", + "build-system": "gnu", + "home-page": "https://www.gnu.org/software/hello/", + "synopsis": "Hello, GNU world: An example GNU package", + "description": "GNU Hello prints a greeting.", + "license": "GPL-3.0+", + "native-inputs": ["gcc@@6"] +@} +@end example + +Los nombres de los campos son los mismos que para el registro +@code{<package>} (@xref{Definición de paquetes}). Las referencias a otros +paquetes se proporcionan como listas JSON de cadenas de especificación de +paquete entrecomilladas como @code{guile} o @code{guile@@2.0}. + +El importador también permite una definición de fuentes más explícita usando +los campos comunes de los registros @code{<origin>}: + +@example +@{ + @dots{} + "source": @{ + "method": "url-fetch", + "uri": "mirror://gnu/hello/hello-2.10.tar.gz", + "sha256": @{ + "base32": "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i" + @} + @} + @dots{} +@} +@end example + +La siguiente orden importa los metadatos desde el fichero JSON +@code{hello.json} y devuelve una expresión de ``package'': + +@example +guix import json hello.json +@end example + +@item nix +Importa metadatos desde una copia local de las fuentes de la +@uref{http://nixos.org/nixpkgs/, distribución Nixpkgs}@footnote{Esto depende +de la orden @command{nix-instantiate} de @uref{http://nixos.org/nix/, +Nix}.}. Las definiciones de paquete en Nixpkgs típicamente están escritas en +una mezcla de lenguaje Nix y código Bash. Esta orden únicamente importa la +estructura de alto nivel del paquete escrita en lenguaje Nix. Normalmente +incluye todos los campos básicos de una definición de paquete. + +Cuando se importa un paquete GNU, la sinopsis y la descripción se +substituyen por la variante canónica oficial. + +Habitualmente, tendrá que ejecutar primero: + +@example +export NIX_REMOTE=daemon +@end example + +@noindent +de modo que @command{nix-instantiate} no intente abrir la base de datos Nix. + +Como un ejemplo, la orden siguiente importa la definición de paquete de +LibreOffice (más precisamente, importa la definición del paquete asociado al +atributo de nivel superior @code{libreoffice}): + +@example +guix import nix ~/path/to/nixpkgs libreoffice +@end example + +@item hackage +@cindex hackage +Importa metadatos desde el archivo central de paquetes de la comunidad +Haskell @uref{https://hackage.haskell.org/, Hackage}. La información se +obtiene de ficheros Cabal e incluye toda la información relevante, +incluyendo las dependencias del paquete. + +Las opciones específicas de línea de ordenes son: + +@table @code +@item --stdin +@itemx -s +Lee un fichero Cabal por la entrada estándar. +@item --no-test-dependencies +@itemx -t +No incluye las dependencias necesarias únicamente para las baterías de +pruebas. +@item --cabal-environment=@var{alist} +@itemx -e @var{alist} +@var{alist} es una lista asociativa Scheme que define el entorno en el que +los condicionales Cabal se evalúan. Los valores aceptados son: @code{os}, +@code{arch}, @code{impl} y una cadena que representa el nombre de la +condición. El valor asociado a la condición tiene que ser o bien el símbolo +@code{true} o bien @code{false}. Los valores predeterminados asociados a las +claves @code{os}, @code{arch} y @code{impl} son @samp{linux}, @samp{x86_64} +y @samp{ghc}, respectivamente. +@item --recursive +@itemx -r +Recorre el grafo de dependencias del paquete original proporcionado +recursivamente y genera expresiones de paquete para todos aquellos paquetes +que no estén todavía en Guix. +@end table + +La siguiente orden importa los metadatos de la última versión del paquete +Haskell @code{HTTP} sin incluir las dependencias de las pruebas y +especificando la opción @samp{network-uri} con valor @code{false}: + +@example +guix import hackage -t -e "'((\"network-uri\" . false))" HTTP +@end example + +Se puede especificar opcionalmente una versión específica del paquete +añadiendo al nombre del paquete una arroba y el número de versión como en el +siguiente ejemplo: + +@example +guix import hackage mtl@@2.1.3.1 +@end example + +@item stackage +@cindex stackage +El importador @code{stackage} es un recubrimiento sobre el de +@code{hackage}. Toma un nombre de paquete, busca la versión de paquete +incluida en una publicación de la versión de mantenimiento extendido (LTS) +@uref{https://www.stackage.org, Stackage} y usa el importador @code{hackage} +para obtener sus metadatos. Fíjese que es su decisión seleccionar una +publicación LTS compatible con el compilador GHC usado en Guix. + +Las opciones específicas de línea de ordenes son: + +@table @code +@item --no-test-dependencies +@itemx -t +No incluye las dependencias necesarias únicamente para las baterías de +pruebas. +@item --lts-version=@var{versión} +@itemx -l @var{versión} +@var{versión} es la versión LTS de publicación deseada. Si se omite se usa +la última publicación. +@item --recursive +@itemx -r +Recorre el grafo de dependencias del paquete original proporcionado +recursivamente y genera expresiones de paquete para todos aquellos paquetes +que no estén todavía en Guix. +@end table + +La siguiente orden importa los metadatos del paquete Haskell @code{HTTP} +incluido en la versión de publicación LTS de Stackage 7.18: + +@example +guix import stackage --lts-version=7.18 HTTP +@end example + +@item elpa +@cindex elpa +Importa metadatos desde el repositorio de archivos de paquetes Emacs Lisp +(ELPA) (@pxref{Packages,,, emacs, The GNU Emacs Manual}). + +Las opciones específicas de línea de ordenes son: + +@table @code +@item --archive=@var{repo} +@itemx -a @var{repo} +@var{repo} identifica el repositorio de archivos del que obtener la +información. Actualmente los repositorios disponibles y sus identificadores +son: +@itemize - +@item +@uref{http://elpa.gnu.org/packages, GNU}, seleccionado con el identificador +@code{gnu}. Es el predeterminado. + +Los paquetes de @code{elpa.gnu.org} están firmados con una de las claves que +contiene el anillo de claves GnuPG en +@file{share/emacs/25.1/etc/package-keyring.gpg} (o similar) en el paquete +@code{emacs} (@pxref{Package Installation, ELPA package signatures,, emacs, +The GNU Emacs Manual}). + +@item +@uref{http://stable.melpa.org/packages, MELPA-Stable}, seleccionado con el +identificador @code{melpa-stable}. + +@item +@uref{http://melpa.org/packages, MELPA}, seleccionado con el identificador +@code{melpa}. +@end itemize + +@item --recursive +@itemx -r +Recorre el grafo de dependencias del paquete original proporcionado +recursivamente y genera expresiones de paquete para todos aquellos paquetes +que no estén todavía en Guix. +@end table + +@item crate +@cindex crate +Importa metadatos desde el repositorio de paquetes Rust +@uref{https://crates.io, crates.io}. + +@item opam +@cindex OPAM +@cindex OCaml +Importa metadatos desde el repositorio de paquetes +@uref{https://opam.ocaml.org/, OPAM} usado por la comunidad OCaml. +@end table + +La estructura del código de @command{guix import} es modular. Sería útil +tener más importadores para otros formatos de paquetes, y su ayuda es +bienvenida aquí (@pxref{Contribuir}). + +@node Invocación de guix refresh +@section Invocación de @command{guix refresh} + +@cindex @command{guix refresh} +La principal audiencia de @command{guix refresh} son desarrolladoras de la +distribución de software GNU. Por defecto, informa de cualquier paquete +proporcionado por la distribución que esté anticuado comparado con la última +versión oficial, de esta manera: + +@example +$ guix refresh +gnu/packages/gettext.scm:29:13: gettext would be upgraded from 0.18.1.1 to 0.18.2.1 +gnu/packages/glib.scm:77:12: glib would be upgraded from 2.34.3 to 2.37.0 +@end example + +De manera alternativa, se pueden especificar los paquetes a considerar, en +cuyo caso se emite un aviso para paquetes que carezcan de actualizador: + +@example +$ guix refresh coreutils guile guile-ssh +gnu/packages/ssh.scm:205:2: warning: no updater for guile-ssh +gnu/packages/guile.scm:136:12: guile would be upgraded from 2.0.12 to 2.0.13 +@end example + +@command{guix refresh} navega por los repositorios oficiales de cada paquete +y determina el número de versión mayor entre las publicaciones +encontradas. La orden sabe cómo actualizar tipos específicos de paquetes: +paquetes GNU, paquetes ELPA, etc.---vea la documentación de @option{--type} +más adelante. Hay muchos paquetes, no obstante, para los que carece de un +método para determinar si está disponible una versión oficial posterior. No +obstante, el mecanismo es extensible, ¡no tenga problema en contactarnos +para añadir un método nuevo! + +@table @code + +@item --recursive +Consider the packages specified, and all the packages upon which they +depend. + +@example +$ guix refresh --recursive coreutils +gnu/packages/acl.scm:35:2: warning: no updater for acl +gnu/packages/m4.scm:30:12: info: 1.4.18 is already the latest version of m4 +gnu/packages/xml.scm:68:2: warning: no updater for expat +gnu/packages/multiprecision.scm:40:12: info: 6.1.2 is already the latest version of gmp +@dots{} +@end example + +@end table + +A veces el nombre oficial es diferente al nombre de paquete usado en Guix, y +@command{guix refresh} necesita un poco de ayuda. La mayor parte de los +actualizadores utilizan la propiedad @code{upstream-name} en las +definiciones de paquetes, que puede usarse para obtener dicho efecto: + +@example +(define-public network-manager + (package + (name "network-manager") + ;; @dots{} + (properties '((upstream-name . "NetworkManager"))))) +@end example + +Cuando se proporciona @code{--update}, modifica los ficheros de fuentes de +la distribución para actualizar los números de versión y hash de los +archivadores tar de fuentes en las recetas de los paquetes (@pxref{Definición de paquetes}). Esto se consigue con la descarga del último archivador de +fuentes del paquete y su firma OpenPGP asociada, seguida de la verificación +del archivador descargado y su firma mediante el uso de @command{gpg}, y +finalmente con el cálculo de su hash. Cuando la clave pública usada para +firmar el archivador no se encuentra en el anillo de claves de la usuaria, +se intenta automáticamente su obtención desde un servidor de claves +públicas; cuando se encuentra, la clave se añade al anillo de claves de la +usuaria; en otro caso, @command{guix refresh} informa de un error. + +Se aceptan las siguientes opciones: + +@table @code + +@item --expression=@var{expr} +@itemx -e @var{expr} +Considera el paquete al que evalúa @var{expr} + +Es útil para hacer una referencia precisa de un paquete concreto, como en +este ejemplo: + +@example +guix refresh -l -e '(@@@@ (gnu packages commencement) glibc-final)' +@end example + +Esta orden enumera los paquetes que dependen de la libc ``final'' +(esencialmente todos los paquetes). + +@item --update +@itemx -u +Actualiza los ficheros fuente de la distribución (recetas de paquetes) en su +lugar. Esto se ejecuta habitualmente desde una copia de trabajo del árbol de +fuentes de Guix (@pxref{Ejecución de Guix antes de estar instalado}): + +@example +$ ./pre-inst-env guix refresh -s non-core -u +@end example + +@xref{Definición de paquetes}, para más información sobre la definición de +paquetes. + +@item --select=[@var{subconjunto}] +@itemx -s @var{subconjunto} +Selecciona todos los paquetes en @var{subconjunto}, o bien @code{core} o +bien @code{non-core}. + +El subconjunto @code{core} hace referencia a todos los paquetes en el núcleo +de la distribución---es decir, paquetes que se usan para construir ``todo lo +demás''. Esto incluye GCC, libc, Binutils, Bash, etc. Habitualmente, cambiar +uno de esos paquetes en la distribución conlleva la reconstrucción de todos +los demás. Por tanto, esas actualizaciones son una inconveniencia para las +usuarias en términos de tiempo de construcción o ancho de banda usado por la +actualización. + +El subconjunto @code{non-core} hace referencia a los paquetes restantes. Es +típicamente útil en casos donde una actualización de paquetes básicos no +sería conveniente. + +@item --manifest=@var{fichero} +@itemx -m @var{fichero} +Selecciona todos los paquetes del manifiesto en @var{fichero}. Es útil para +comprobar si algún paquete del manifiesto puede actualizarse. + +@item --type=@var{actualizador} +@itemx -t @var{actualizador} +Selecciona únicamente paquetes manejados por @var{actualizador} (puede ser +una lista separada por comas de actualizadores). Actualmente, +@var{actualizador} puede ser: + +@table @code +@item gnu +el actualizador de paquetes GNU; +@item gnome +el actualizador para paquetes GNOME; +@item kde +el actualizador para paquetes KDE; +@item xorg +el actualizador para paquetes X.org; +@item kernel.org +el actualizador para paquetes alojados en kernel.org; +@item elpa +el actualizador para paquetes @uref{http://elpa.gnu.org/, ELPA}; +@item cran +el actualizador para paquetes @uref{https://cran.r-project.org/, CRAN}; +@item bioconductor +el actualizador para paquetes R @uref{https://www.bioconductor.org/, +Bioconductor}; +@item cpan +el actualizador para paquetes @uref{http://www.cpan.org/, CPAN}; +@item pypi +el actualizador para paquetes @uref{https://pypi.python.org, PyPI}. +@item gem +el actualizador para paquetes @uref{https://rubygems.org, RubyGems}. +@item github +el actualizador para paquetes @uref{https://github.com, GitHub}. +@item hackage +el actualizador para paquetes @uref{https://hackage.haskell.org, Hackage}. +@item stackage +el actualizador para paquetes @uref{https://www.stackage.org, Stackage}. +@item crate +el actualizador para paquetes @uref{https://crates.io, Crates}. +@item launchpad +el actualizador para paquetes @uref{https://launchpad.net, Launchpad}. +@end table + +Por ejemplo, la siguiente orden únicamente comprueba actualizaciones de +paquetes Emacs alojados en @code{elpa.gnu.org} y actualizaciones de paquetes +CRAN: + +@example +$ guix refresh --type=elpa,cran +gnu/packages/statistics.scm:819:13: r-testthat would be upgraded from 0.10.0 to 0.11.0 +gnu/packages/emacs.scm:856:13: emacs-auctex would be upgraded from 11.88.6 to 11.88.9 +@end example + +@end table + +Además, @command{guix refresh} puede recibir uno o más nombres de paquetes, +como en este ejemplo: + +@example +$ ./pre-inst-env guix refresh -u emacs idutils gcc@@4.8 +@end example + +@noindent +La orden previa actualiza específicamente los paquetes @code{emacs} y +@code{idutils}. La opción @code{--select} no tendría efecto en este caso. + +Cuando se considera la actualización de un paquete, a veces es conveniente +conocer cuantos paquetes se verían afectados por la actualización y su +compatibilidad debería comprobarse. Para ello la siguiente opción puede +usarse cuando se proporcionan uno o más nombres de paquete a @command{guix +refresh}: + +@table @code + +@item --list-updaters +@itemx -L +Enumera los actualizadores disponibles y finaliza (vea la opción previa +@option{--type}). + +Para cada actualizador, muestra la fracción de paquetes que cubre; al final +muestra la fracción de paquetes cubiertos por todos estos actualizadores. + +@item --list-dependent +@itemx -l +Enumera los paquetes de nivel superior dependientes que necesitarían una +reconstrucción como resultado de la actualización de uno o más paquetes. + +@xref{Invocación de guix graph, el tipo @code{reverse-package} de @command{guix +graph}}, para información sobre cómo visualizar la lista de paquetes que +dependen de un paquete. + +@end table + +Sea consciente de que la opción @code{--list-dependent} únicamente +@emph{aproxima} las reconstrucciones necesarias como resultado de una +actualización. Más reconstrucciones pueden ser necesarias bajo algunas +circunstancias. + +@example +$ guix refresh --list-dependent flex +Building the following 120 packages would ensure 213 dependent packages are rebuilt: +hop@@2.4.0 geiser@@0.4 notmuch@@0.18 mu@@0.9.9.5 cflow@@1.4 idutils@@4.6 @dots{} +@end example + +La orden previa enumera un conjunto de paquetes que puede ser construido +para comprobar la compatibilidad con una versión actualizada del paquete +@code{flex}. + +@table @code + +@item --list-transitive +Enumera todos los paquetes de los que uno o más paquetes dependen. + +@example +$ guix refresh --list-transitive flex +flex@@2.6.4 depends on the following 25 packages: perl@@5.28.0 help2man@@1.47.6 +bison@@3.0.5 indent@@2.2.10 tar@@1.30 gzip@@1.9 bzip2@@1.0.6 xz@@5.2.4 file@@5.33 @dots{} +@end example + +@end table + +La orden previa enumera un conjunto de paquetes que, en caso de cambiar, +causarían la reconstrucción de @code{flex}. + +Las siguientes opciones pueden usarse para personalizar la operación de +GnuPG: + +@table @code + +@item --gpg=@var{orden} +Use @var{orden} como la orden de GnuPG 2.x. Se busca @var{orden} en +@code{PATH}. + +@item --keyring=@var{fichero} +Usa @var{fichero} como el anillo de claves para claves de +proveedoras. @var{fichero} debe estar en el @dfn{formato keybox}. Los +ficheros Keybox normalmente tienen un nombre terminado en @file{.kbx} y +GNU@tie{}Privacy Guard (GPG) puede manipular estos ficheros (@pxref{kbxutil, +@command{kbxutil},, gnupg, Using the GNU Privacy Guard}, para información +sobre una herramienta para manipular ficheros keybox). + +Cuando se omite esta opción, @command{guix refresh} usa +@file{~/.config/guix/upstream/trustedkeys.kbx} como el anillo de claves para +las firmas de proveedoras. Las firmas OpenPGP son comprobadas contra claves +de este anillo; las claves que falten son descargadas a este anillo de +claves también (véase @option{--key-download} a continuación). + +Puede exportar claves de su anillo de claves GPG predeterminado en un +fichero keybox usando órdenes como esta: + +@example +gpg --export rms@@gnu.org | kbxutil --import-openpgp >> mianillo.kbx +@end example + +Del mismo modo, puede obtener claves de un archivo keybox específico así: + +@example +gpg --no-default-keyring --keyring mianillo.kbx \ + --recv-keys @value{OPENPGP-SIGNING-KEY-ID} +@end example + +@ref{GPG Configuration Options, @option{--keyring},, gnupg, Using the GNU +Privacy Guard}, para más información sobre la opción @option{--keyring} de +GPG. + +@item --key-download=@var{política} +Maneja las claves no encontradas de acuerdo a la @var{política}, que puede +ser una de: + +@table @code +@item always +Siempre descarga las claves OpenPGP no encontradas del servidor de claves, y +las añade al anillo de claves GnuPG de la usuaria. + +@item never +Nunca intenta descargar claves OpenPGP no encontradas. Simplemente propaga +el error. + +@item interactive +Cuando se encuentra un paquete firmado por una clave OpenPGP desconocida, +pregunta a la usuaria si descargarla o no. Este es el comportamiento +predeterminado. +@end table + +@item --key-server=@var{dirección} +Use @var{dirección} como el servidor de claves OpenPGP cuando se importa una +clave pública. + +@end table + +The @code{github} updater uses the @uref{https://developer.github.com/v3/, +GitHub API} to query for new releases. When used repeatedly e.g.@: when +refreshing all packages, GitHub will eventually refuse to answer any further +API requests. By default 60 API requests per hour are allowed, and a full +refresh on all GitHub packages in Guix requires more than this. +Authentication with GitHub through the use of an API token alleviates these +limits. To use an API token, set the environment variable +@code{GUIX_GITHUB_TOKEN} to a token procured from +@uref{https://github.com/settings/tokens} or otherwise. + + +@node Invocación de guix lint +@section Invocación de @command{guix lint} + +@cindex @command{guix lint} +@cindex paquete, comprobación de errores +La orden @command{guix lint} sirve para ayudar a las desarrolladoras de +paquetes a evitar errores comunes y usar un estilo consistente. Ejecuta un +número de comprobaciones en un conjunto de paquetes proporcionado para +encontrar errores comunes en sus definiciones. Los @dfn{comprobadores} +disponibles incluyen (véase @code{--list-checkers} para una lista completa): + +@table @code +@item synopsis +@itemx description +Valida ciertas reglas tipográficas y de estilo en la descripción y sinopsis +de cada paquete. + +@item inputs-should-be-native +Identifica entradas que probablemente deberían ser entradas nativas. + +@item source +@itemx home-page +@itemx mirror-url +@itemx github-url +@itemx source-file-name +Comprueba las URL @code{home-page} y @code{source} e informa aquellas que no +sean válidas. Sugiere una URL @code{mirror://} cuando sea aplicable. Si la +URL @code{source} redirecciona a una URL GitHub, recomienda el uso de la URL +GitHub. Comprueba que el nombre de fichero de las fuentes es significativo, +por ejemplo que no es simplemente un número de versión o revisión git, sin +un nombre @code{file-name} declarado (@pxref{Referencia de ``origin''}). + +@item source-unstable-tarball +Parse the @code{source} URL to determine if a tarball from GitHub is +autogenerated or if it is a release tarball. Unfortunately GitHub's +autogenerated tarballs are sometimes regenerated. + +@item cve +@cindex vulnerabilidades de seguridad +@cindex CVE, vulnerabilidades y exposiciones comunes +Informa de vulnerabilidades encontradas en las bases de datos de +vulnerabilidades y exposiciones comunes (CVE) del año actual y el pasado +@uref{https://nvd.nist.gov/download.cfm#CVE_FEED, publicadas por el NIST de +EEUU}. + +Para ver información acerca de una vulnerabilidad particular, visite páginas +como: + +@itemize +@item +@indicateurl{https://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-YYYY-ABCD} +@item +@indicateurl{https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-YYYY-ABCD} +@end itemize + +@noindent +donde @code{CVE-YYYY-ABCD} es el identificador CVE---por ejemplo, +@code{CVE-2015-7554}. + +Las desarrolladoras de paquetes pueden especificar en las recetas del +paquete el nombre y versión en la @uref{https://nvd.nist.gov/cpe.cfm, +plataforma común de enumeración (CPE)} del paquete cuando difieren del +nombre o versión que usa Guix, como en este ejemplo: + +@example +(package + (name "grub") + ;; @dots{} + ;; CPE llama a este paquete "grub2". + (properties '((cpe-name . "grub2") + (cpe-version . "2.3"))) +@end example + +@c See <http://www.openwall.com/lists/oss-security/2017/03/15/3>. +Algunas entradas en la base de datos CVE no especifican a qué versión del +paquete hacen referencia, y por lo tanto ``permanecen visibles'' para +siempre. Las desarrolladoras de paquetes que encuentren alertas CVE y +verifiquen que pueden ignorarse, pueden declararlas como en este ejemplo: + +@example +(package + (name "t1lib") + ;; @dots{} + ;; Estas alertas de CVE no aplican y pueden ignorarse + ;; con seguridad. + (properties `((lint-hidden-cve . ("CVE-2011-0433" + "CVE-2011-1553" + "CVE-2011-1554" + "CVE-2011-5244"))))) +@end example + +@item formatting +Avisa de problemas de formato obvios en el código fuente: espacios en blanco +al final de las líneas, uso de tabuladores, etc. +@end table + +La sintaxis general es: + +@example +guix lint @var{opciones} @var{paquete}@dots{} +@end example + +Si no se proporciona ningún paquete en la linea de órdenes, todos los +paquetes se comprueban. Las @var{opciones} pueden ser cero o más de las +siguientes: + +@table @code +@item --list-checkers +@itemx -l +Enumera y describe todos los comprobadores disponibles que se ejecutarán +sobre los paquetes y finaliza. + +@item --checkers +@itemx -c +Habilita únicamente los comprobadores especificados en una lista separada +por comas que use los nombres devueltos por @code{--list-checkers}. + +@end table + +@node Invocación de guix size +@section Invocación de @command{guix size} + +@cindex tamaño +@cindex tamaño del paquete +@cindex clausura +@cindex @command{guix size} +La orden @command{guix size} ayuda a las desarrolladoras de paquetes a +perfilar el uso de disco de los paquetes. Es fácil pasar por encima el +impacto que produce añadir una dependencia adicional a un paquete, o el +impacto del uso de una salida única para un paquete que puede ser dividido +fácilmente (@pxref{Paquetes con múltiples salidas}). Estos son los problemas +típicos que @command{guix size} puede resaltar. + +Se le pueden proporcionar una o más especificaciones de paquete como +@code{gcc@@4.8} o @code{guile:debug}, o un nombre de fichero en el +almacén. Considere este ejemplo: + +@example +$ guix size coreutils +store item total self +/gnu/store/@dots{}-gcc-5.5.0-lib 60.4 30.1 38.1% +/gnu/store/@dots{}-glibc-2.27 30.3 28.8 36.6% +/gnu/store/@dots{}-coreutils-8.28 78.9 15.0 19.0% +/gnu/store/@dots{}-gmp-6.1.2 63.1 2.7 3.4% +/gnu/store/@dots{}-bash-static-4.4.12 1.5 1.5 1.9% +/gnu/store/@dots{}-acl-2.2.52 61.1 0.4 0.5% +/gnu/store/@dots{}-attr-2.4.47 60.6 0.2 0.3% +/gnu/store/@dots{}-libcap-2.25 60.5 0.2 0.2% +total: 78.9 MiB +@end example + +@cindex clausura +Los elementos del almacén enumerados aquí constituyen la @dfn{clausura +transitiva} de Coreutils---es decir, Coreutils y todas sus dependencias, +recursivamente---como sería devuelto por: + +@example +$ guix gc -R /gnu/store/@dots{}-coreutils-8.23 +@end example + +Aquí la salida muestra tres columnas junto a los elementos del almacén. La +primera columna, etiquetada ``total'', muestra el tamaño en mebibytes (MiB) +de la clausura del elemento del almacén---es decir, su propio tamaño sumado +al tamaño de todas sus dependencias. La siguiente columna, etiquetada +``self'', muestra el tamaño del elemento en sí. La última columna muestra la +relación entre el tamaño del elemento en sí frente al espacio ocupado por +todos los elementos enumerados. + +En este ejemplo, vemos que la clausura de Coreutils ocupa 79@tie{}MiB, cuya +mayor parte son libc y las bibliotecas auxiliares de GCC para tiempo de +ejecución. (Que libc y las bibliotecas de GCC representen una fracción +grande de la clausura no es un problema en sí, puesto que siempre están +disponibles en el sistema de todas maneras). + +Cuando los paquetes pasados a @command{guix size} están disponibles en el +almacén@footnote{Más precisamente, @command{guix size} busca la variante +@emph{sin injertos} de los paquetes, como el devuelto por @code{guix build +@var{paquete} --no-grafts}. @xref{Actualizaciones de seguridad}, para información sobre +injertos.} consultando al daemon para determinar sus dependencias, y mide su +tamaño en el almacén, de forma similar a @command{du -ms --apparent-size} +(@pxref{du invocation,,, coreutils, GNU Coreutils}). + +Cuando los paquetes proporcionados @emph{no} están en el almacén, +@command{guix size} informa en base de las sustituciones disponibles +(@pxref{Sustituciones}). Esto hace posible perfilar el espacio en disco +incluso de elementos del almacén que no están en el disco, únicamente +disponibles de forma remota. + +Puede especificar también varios nombres de paquetes: + +@example +$ guix size coreutils grep sed bash +store item total self +/gnu/store/@dots{}-coreutils-8.24 77.8 13.8 13.4% +/gnu/store/@dots{}-grep-2.22 73.1 0.8 0.8% +/gnu/store/@dots{}-bash-4.3.42 72.3 4.7 4.6% +/gnu/store/@dots{}-readline-6.3 67.6 1.2 1.2% +@dots{} +total: 102.3 MiB +@end example + +@noindent +En este ejemplo vemos que la combinación de los cuatro paquetes toma +102.3@tie{}MiB en total, lo cual es mucho menos que la suma de cada +clausura, ya que tienen muchas dependencias en común. + +Las opciones disponibles son: + +@table @option + +@item --substitute-urls=@var{urls} +Usa la información de sustituciones de +@var{urls}. @xref{client-substitute-urls, la misma opción en @code{guix +build}}. + +@item --sort=@var{clave} +Ordena las líneas de acuerdo a @var{clave}, una de las siguientes opciones: + +@table @code +@item self +el tamaño de cada elemento (predeterminada); +@item clausura +el tamaño total de la clausura del elemento. +@end table + +@item --map-file=@var{fichero} +Escribe un mapa gráfico del uso del disco en formato PNG en el +@var{fichero}. + +Para el ejemplo previo, el mapa tiene esta pinta: + +@image{images/coreutils-size-map,5in,, mapa del uso del disco de Coreutils +producido por @command{guix size}} + +Esta opción necesita que la biblioteca +@uref{http://wingolog.org/software/guile-charting/, Guile-Charting} esté +instalada y visible en la ruta de búsqueda de módulos Guile. Cuando no es el +caso, @command{guix size} produce un error al intentar cargarla. + +@item --system=@var{sistema} +@itemx -s @var{sistema} +Considera paquetes para @var{sistema}---por ejemplo, @code{x86_64-linux}. + +@end table + +@node Invocación de guix graph +@section Invocación de @command{guix graph} + +@cindex GAD (DAG en Inglés) +@cindex @command{guix graph} +@cindex dependencias de un paquete +Los paquetes y sus dependencias forman un @dfn{grafo}, específicamente un +grafo acíclico dirigido (GAD, DAG en Inglés). Puede hacerse difícil +rápidamente tener un modelo mental del GAD del paquete, por lo que la orden +@command{guix graph} proporciona una representación virtual del GAD. Por +defecto, @command{guix graph} emite una representación en GAD en el formato +de entrada de @uref{http://graphviz.org/,Graphviz}, por lo que su salida +puede ser pasada directamente a la herramienta @command{dot} de +Graphviz. También puede emitir una página HTMP con código JavaScript +embebido para mostrar un ``diagrama de acorde'' en un navegador Web, usando +la biblioteca @uref{https://d3js.org/, d3.js}, o emitir consultas Cypher +para construir un grafo en una base de datos de grafos que acepte el +lenguaje de consultas @uref{http://www.opencypher.org/, openCypher}. La +sintaxis general es: + +@example +guix graph @var{opciones} @var{paquete}@dots{} +@end example + +Por ejemplo, la siguiente orden genera un fichero PDF que representa el GAD +para GNU@tie{}Core Utilities, mostrando sus dependencias en tiempo de +construcción: + +@example +guix graph coreutils | dot -Tpdf > gad.pdf +@end example + +La salida es algo así: + +@image{images/coreutils-graph,2in,,Grafo de dependencias de GNU Coreutils} + +Bonito y pequeño grafo, ¿no? + +¡Pero hay más de un grafo! El grafo previo es conciso: es el grafo de los +objetos package, omitiendo las entradas implícitas como GCC, libc, grep, +etc. Es habitualmente útil tener un grafo conciso así, pero a veces una +puede querer ver más detalles. @command{guix graph} implementa varios tipos +de grafos, permitiendole seleccionar el nivel de detalle: + +@table @code +@item package +Este es el tipo por defecto usado en el ejemplo previo. Muestra el GAD de +objetos package, excluyendo dependencias implícitas. Es conciso, pero deja +fuera muchos detalles. + +@item reverse-package +Esto muestra el GAD @emph{inverso} de paquetes. Por ejemplo: + +@example +guix graph --type=reverse-package ocaml +@end example + +...@: yields the graph of packages that @emph{explicitly} depend on OCaml +(if you are also interested in cases where OCaml is an implicit dependency, +see @code{reverse-bag} below.) + +Fíjese que esto puede producir grafos inmensos para los paquetes básicos. Si +todo lo que quiere saber es el número de paquetes que dependen de uno +determinado, use @command{guix refresh --list-dependent} (@pxref{Invocación de guix refresh, @option{--list-dependent}}). + +@item bag-emerged +Este es el GAD del paquete, @emph{incluyendo} entradas implícitas. + +Por ejemplo, la siguiente orden: + +@example +guix graph --type=bag-emerged coreutils | dot -Tpdf > gad.pdf +@end example + +...@: emite este grafo más grande: + +@image{images/coreutils-bag-graph,,5in,Grafo de dependencias detallado de +GNU Coreutils} + +En la parte inferior del grafo, vemos todas las entradas implícitas de +@var{gnu-build-system} (@pxref{Sistemas de construcción, @code{gnu-build-system}}). + +Ahora bien, fijese que las dependencias de estas entradas implícitas---es +decir, las @dfn{dependencias del lanzamiento inicial} +(@pxref{Lanzamiento inicial})---no se muestran aquí para mantener una salida +concisa. + +@item bag +Similar a @code{bag-emerged}, pero esta vez incluye todas las dependencias +del lanzamiento inicial. + +@item bag-with-origins +Similar a @code{bag}, pero también muestra los orígenes y sus dependencias. + +@item reverse-bag +This shows the @emph{reverse} DAG of packages. Unlike +@code{reverse-package}, it also takes implicit dependencies into account. +For example: + +@example +guix graph -t reverse-bag dune +@end example + +@noindent +...@: yields the graph of all packages that depend on Dune, directly or +indirectly. Since Dune is an @emph{implicit} dependency of many packages +@i{via} @code{dune-build-system}, this shows a large number of packages, +whereas @code{reverse-package} would show very few if any. + +@item derivación +Esta es la representación más detallada: muestra el GAD de derivaciones +(@pxref{Derivaciones}) y elementos simples del almacén. Comparada con las +representaciones previas, muchos nodos adicionales son visibles, incluyendo +los guiones de construcción, parches, módulos Guile, etc. + +Para este tipo de grafo, también es posible pasar un nombre de fichero +@file{.drv} en vez del nombre del paquete, como en: + +@example +guix graph -t derivation `guix system build -d mi-configuracion.scm` +@end example + +@item module +Este es el grafo de los @dfn{módulos de paquete} (@pxref{Módulos de paquetes}). Por ejemplo, la siguiente orden muestra el grafo para el módulo +de paquetes que define el paquete @code{guile}: + +@example +guix graph -t module guile | dot -Tpdf > grafo-del-modulo.pdf +@end example +@end table + +Todos los tipos previos corresponden a las @emph{dependencias durante la +construcción}. El grafo siguiente representa las @emph{dependencias en +tiempo de ejecución}: + +@table @code +@item references +Este es el grafo de @dfn{referencias} de la salida de un paquete, como lo +devuelve @command{guix gc --references} (@pxref{Invocación de guix gc}). + +Si la salida del paquete proporcionado no está disponible en el almacén, +@command{guix graph} intenta obtener la información de dependencias desde +las sustituciones. + +Aquí también puede proporcionar un nombre de fichero del almacén en vez de +un nombre de paquete. Por ejemplo, la siguiente orden produce el grafo de +referencias de su perfil (¡el cuál puede ser grande!): + +@example +guix graph -t references `readlink -f ~/.guix-profile` +@end example + +@item referrers +Este es el grafo de @dfn{referentes} de la salida de un paquete, como lo +devuelve @command{guix gc --referrers} (@pxref{Invocación de guix gc}). + +Depende exclusivamente de información en su almacén. Por ejemplo, supongamos +que la versión actual de Inkscape está disponible en 10 perfiles en su +máquina; @command{guix graph -t referrers inkscape} mostrará un grafo cuya +raíz es Inkscape y con esos 10 perfiles enlazados a ella. + +Puede ayudar a determinar qué impide que un elemento del almacén sea +recolectado. + +@end table + +Las opciones disponibles son las siguientes: + +@table @option +@item --type=@var{tipo} +@itemx -t @var{tipo} +Produce un grafo de salida de @var{tipo}, donde @var{tipo} debe ser uno de +los valores enumerados previamente. + +@item --list-types +Enumera los tipos de grafos implementados. + +@item --backend=@var{motor} +@itemx -b @var{motor} +Produce un grafo usando el @var{motor} seleccionado. + +@item --list-backends +Enumera los motores de grafos implementados. + +Actualmente, los motores disponibles son Graphviz y d3.js. + +@item --expression=@var{expr} +@itemx -e @var{expr} +Considera el paquete al que evalúa @var{expr} + +Es útil para hacer una referencia precisa de un paquete concreto, como en +este ejemplo: + +@example +guix graph -e '(@@@@ (gnu packages commencement) gnu-make-final)' +@end example + +@item --system=@var{sistema} +@itemx -s @var{sistema} +Muestra el grafo para @var{sistema}---por ejemplo, @code{i686-linux}. + +El grafo de dependencias del paquete es altamente independiente de la +arquitectura, pero existen algunas partes dependientes de la arquitectura +que esta opción le permite visualizar. +@end table + + + +@node Invocación de guix publish +@section Invocación de @command{guix publish} + +@cindex @command{guix publish} +El propósito de @command{guix publish} es permitir a las usuarias compartir +fácilmente su almacén con otras, quienes pueden usarlo como servidor de +sustituciones (@pxref{Sustituciones}). + +Cuando @command{guix publish} se ejecuta, lanza un servidor HTTP que permite +a cualquiera que tenga acceso a través de la red obtener sustituciones de +él. Esto significa que cualquier máquina que ejecute Guix puede actuar como +si fuese una granja de construcción, ya que la interfaz HTTP es compatible +con Hydra, el software detrás de la granja de construcción +@code{@value{SUBSTITUTE-SERVER}}. + +Por seguridad, cada sustitución se firma, permitiendo a las receptoras +comprobar su autenticidad e integridad (@pxref{Sustituciones}). Debido a que +@command{guix publish} usa la clave de firma del sistema, que es únicamente +legible por la administradora del sistema, debe iniciarse como root; la +opción @code{--user} hace que renuncie a sus privilegios tan pronto como sea +posible. + +El par claves de firma debe generarse antes de ejecutar @command{guix +publish}, usando @command{guix archive --generate-key} (@pxref{Invocación de guix archive}). + +La sintaxis general es: + +@example +guix publish @var{opciones}@dots{} +@end example + +La ejecución de @command{guix publish} sin ningún parámetro adicional +lanzará un servidor HTTP en el puerto 8080: + +@example +guix publish +@end example + +Una vez el servidor de publicación ha sido autorizado (@pxref{Invocación de guix archive}), el daemon puede descargar sustituciones de él: + +@example +guix-daemon --substitute-urls=http://example.org:8080 +@end example + +Por defecto, @command{guix publish} comprime los archivos al vuelo cuando es +necesario. Este modo ``al vuelo'' es conveniente ya que no necesita +configuración y está disponible inmediatamente. No obstante, cuando se +proporciona servicio a muchos clientes, se recomienda usar la opción +@option{--cache}, que habilita el almacenamiento en caché de los archivos +antes de enviarlos a los clientes---véase a continuación para más +detalles. La orden @command{guix weather} proporciona una forma fácil de +comprobar lo que proporciona un servidor (@pxref{Invocación de guix weather}). + +Además @command{guix publish} también sirve como un espejo de acceso por +contenido a ficheros de fuentes a los que los registros @code{origin} hacen +referencia (@pxref{Referencia de ``origin''}). Por ejemplo, si asumimos que +@command{guix publish} se ejecuta en @code{example.org}, la siguiente URL +devuelve directamente el fichero @file{hello-2.10.tar.gz} con el hash SHA256 +proporcionado (representado en formato @code{nix-base32}, @pxref{Invocación de guix hash}). + +@example +http://example.org/file/hello-2.10.tar.gz/sha256/0ssi1@dots{}ndq1i +@end example + +Obviamente estas URL funcionan solamente para ficheros que se encuentran en +el almacén; en otros casos devuelven un 404 (``No encontrado''). + +@cindex logs de construcción, publicación +Los log de construcción están disponibles desde URL @code{/log} como: + +@example +http://example.org/log/gwspk@dots{}-guile-2.2.3 +@end example + +@noindent +Cuando @command{guix-daemon} está configurado para almacenar comprimidos los +log de construcción, como sucede de forma predeterminada (@pxref{Invocación de guix-daemon}), las URL @code{/log} devuelven los log igualmente comprimidos, +con un @code{Content-Type} adecuado y/o una cabecera +@code{Content-Encoding}. Recomendamos ejecutar @command{guix-daemon} con +@code{--log-compression=gzip} ya que los navegadores Web pueden extraer el +contenido automáticamente, lo cual no es el caso con la compresión bzip2. + +Las siguientes opciones están disponibles: + +@table @code +@item --port=@var{puerto} +@itemx -p @var{puerto} +Escucha peticiones HTTP en @var{puerto}. + +@item --listen=@var{dirección} +Escucha en la interfaz de red de la @var{dirección}. El comportamiento +predeterminado es aceptar conexiones de cualquier interfaz. + +@item --user=@var{usuaria} +@itemx -u @var{usuaria} +Cambia los privilegios a los de @var{usuaria} tan pronto como sea +posible---es decir, una vez el socket del servidor esté abierto y la clave +de firma haya sido leída. + +@item --compression[=@var{nivel}] +@itemx -C [@var{nivel}] +Comprime los datos con el @var{nivel} dado. Cuando el @var{nivel} es cero, +deshabilita la compresión. El rango 1 a 9 corresponde a distintos niveles de +compresión gzip: 1 es el más rápido, y 9 es el mejor (intensivo a nivel de +CPU). El valor predeterminado es 3. + +A menos que se use @option{--cache}, la compresión ocurre al vuelo y los +flujos comprimidos no se almacenan en caché. Por tanto, para reducir la +carga en la máquina que ejecuta @command{guix publish}, puede ser una buena +idea elegir un nivel de compresión bajo, ejecutar @command{guix publish} +detrás de un proxy con caché o usar @option{--cache}. El uso de +@option{--cache} tiene la ventaja de que permite a @command{guix publish} +añadir la cabecera HTTP @code{Content-Length} a sus respuestas. + +@item --cache=@var{directorio} +@itemx -c @var{directorio} +Almacena en caché los archivos y metadatos (URL @code{.narinfo}) en +@var{directorio} y únicamente proporciona archivos que están en la caché. + +Cuando se omite esta opción, los archivos y metadatos se crean al +vuelo. Esto puede reducir el ancho de banda disponible, especialmente cuando +la compresión está habilitada, ya que se puede llegar al límite de la +CPU. Otra desventaja del modo predeterminado es que la longitud de los +archivos no se conoce con anterioridad, por lo que @command{guix publish} no +puede añadir la cabecera HTTP @code{Content-Length} a sus respuestas, lo que +a su vez previene que los clientes conozcan la cantidad de datos a +descargar. + +De manera contraria, cuando se usa @option{--cache}, la primera petición de +un elemento del almacén (a través de una URL @code{.narinfo}) devuelve 404 e +inicia un proceso en segundo plano para @dfn{cocinar} el archivo---calcular +su @code{.narinfo} y comprimirlo, en caso necesario. Una vez el archivo está +alojado en la caché de @var{directorio}, las siguientes peticiones obtendrán +un resultado satisfactorio y se ofrecerá el contenido directamente desde la +caché, lo que garantiza que los clientes obtienen el mejor ancho de banda +posible. + +El proceso de ``cocinado'' se realiza por hilos de trabajo. Por defecto, se +crea un hilo por núcleo de la CPU, pero puede ser personalizado. Véase +@option{--workers} a continuación. + +Cuando se usa @option{--ttl}, las entradas en caché se borran +automáticamente cuando hayan expirado. + +@item --workers=@var{N} +Cuando se usa @option{--cache}, solicita la creación de @var{N} hilos de +trabajo para ``cocinar'' archivos. + +@item --ttl=@var{ttl} +Produce cabeceras HTTP @code{Cache-Control} que anuncian un tiempo-de-vida +(TTL) de @var{ttl}. @var{ttl} debe indicar una duración: @code{5d} significa +5 días, @code{1m} significa un mes, etc. + +Esto permite a la usuaria de Guix mantener información de sustituciones en +la caché durante @var{ttl}. No obstante, fíjese que @code{guix publish} no +garantiza en sí que los elementos del almacén que proporciona de hecho +permanezcan disponibles hasta que @var{ttl} expire. + +Adicionalmente, cuando se usa @option{--cache}, las entradas en caché que no +hayan sido accedidas en @var{ttl} y no tengan un elemento correspondiente en +el almacén pueden ser borradas. + +@item --nar-path=@var{ruta} +Usa @var{ruta} como el prefijo para las URL de los archivos ``nar'' +(@pxref{Invocación de guix archive, archivadores normalizados}). + +Por defecto, los archivos nar se proporcionan en una URL como +@code{/nar/gzip/@dots{}-coreutils-8.25}. Esta opción le permite cambiar la +parte @code{/nar} por @var{ruta}. + +@item --public-key=@var{fichero} +@itemx --private-key=@var{fichero} +Usa los @var{fichero}s específicos como el par de claves pública y privada +usadas para firmar los elementos del almacén publicados. + +Los ficheros deben corresponder al mismo par de claves (la clave privada se +usa para la firma y la clave pública simplemente se anuncia en los metadatos +de la firma). Deben contener claves en el formato canónico de expresiones-S +como el producido por @command{guix archive --generate-key} (@pxref{Invocación de guix archive}). Por defecto, se usan @file{/etc/guix/signing-key.pub} y +@file{/etc/guix/signing-key.sec}. + +@item --repl[=@var{puerto}] +@itemx -r [@var{puerto}] +Lanza un servidor REPL Guile (@pxref{REPL Servers,,, guile, GNU Guile +Reference Manual}) en @var{puerto} (37146 por defecto). Esto se usa +principalmente para la depuración de un servidor @command{guix publish} en +ejecución. +@end table + +Habilitar @command{guix publish} en el sistema Guix consiste en solo una +línea: simplemente instancie un servicio @code{guix-publish-service-type} en +el campo @code{services} de su declaración del sistema operativo +@code{operating-system} (@pxref{guix-publish-service-type, +@code{guix-publish-service-type}}) + +Si en vez de eso ejecuta Guix en una distribución distinta, siga estas +instrucciones: + +@itemize +@item +Si su distribución anfitriona usa el sistema de inicio systemd: + +@example +# ln -s ~root/.guix-profile/lib/systemd/system/guix-publish.service \ + /etc/systemd/system/ +# systemctl start guix-publish && systemctl enable guix-publish +@end example + +@item +Si su distribución anfitriona usa el sistema de inicio Upstart: + +@example +# ln -s ~root/.guix-profile/lib/upstart/system/guix-publish.conf /etc/init/ +# start guix-publish +@end example + +@item +En otro caso, proceda de forma similar con el sistema de inicio de su +distribución. +@end itemize + +@node Invocación de guix challenge +@section Invocación de @command{guix challenge} + +@cindex construcciones reproducibles +@cindex construcciones verificables +@cindex @command{guix challenge} +@cindex reto (challenge) +¿Los binarios que proporciona este servidor realmente corresponden al código +fuente que dice construir? ¿Es determinista el proceso de construcción de un +paquete? Estas son las preguntas que la orden @command{guix challenge} +intenta responder. + +La primera es obviamente una cuestión importante: antes de usar un servidor +de sustituciones (@pxref{Sustituciones}), es importante haber +@emph{verificado} que proporciona los binarios correctos, y por tanto +@emph{ponerlo a prueba}@footnote{NdT: challenge en inglés.}. La segunda es +lo que permite la primera: si las construcciones de los paquetes son +deterministas, construcciones independientes deberían emitir el mismo +resultado, bit a bit; si el servidor proporciona un binario diferente al +obtenido localmente, o bien está corrupto o bien tiene intenciones +perniciosas. + +Sabemos que el hash que se muestra en los nombres de fichero en +@file{/gnu/store} es el hash de todas las entradas del proceso que construyó +el fichero o directorio---compiladores, bibliotecas, guiones de +construcción, etc. (@pxref{Introducción}). Asumiendo procesos de +construcción deterministas, un nombre de fichero del almacén debe +corresponder exactamente a una salida de construcción. @command{guix +challenge} comprueba si existe, realmente, una asociación unívoca comparando +la salida de la construcción de varias construcciones independientes de +cualquier elemento del almacén proporcionado. + +La salida de la orden muestra algo así: + +@smallexample +$ guix challenge --substitute-urls="https://@value{SUBSTITUTE-SERVER} https://guix.example.org" +updating list of substitutes from 'https://@value{SUBSTITUTE-SERVER}'... 100.0% +updating list of substitutes from 'https://guix.example.org'... 100.0% +/gnu/store/@dots{}-openssl-1.0.2d contents differ: + local hash: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q + https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-openssl-1.0.2d: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q + https://guix.example.org/nar/@dots{}-openssl-1.0.2d: 1zy4fmaaqcnjrzzajkdn3f5gmjk754b43qkq47llbyak9z0qjyim +/gnu/store/@dots{}-git-2.5.0 contents differ: + local hash: 00p3bmryhjxrhpn2gxs2fy0a15lnip05l97205pgbk5ra395hyha + https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-git-2.5.0: 069nb85bv4d4a6slrwjdy8v1cn4cwspm3kdbmyb81d6zckj3nq9f + https://guix.example.org/nar/@dots{}-git-2.5.0: 0mdqa9w1p6cmli6976v4wi0sw9r4p5prkj7lzfd1877wk11c9c73 +/gnu/store/@dots{}-pius-2.1.1 contents differ: + local hash: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax + https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-pius-2.1.1: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax + https://guix.example.org/nar/@dots{}-pius-2.1.1: 1cy25x1a4fzq5rk0pmvc8xhwyffnqz95h2bpvqsz2mpvlbccy0gs + +@dots{} + +6,406 store items were analyzed: + - 4,749 (74.1%) were identical + - 525 (8.2%) differed + - 1,132 (17.7%) were inconclusive +@end smallexample + +@noindent +En este ejemplo, @command{guix challenge} primero recorre el almacén para +determinar el conjunto de derivaciones construidas localmente---en oposición +a elementos del almacén que fueron descargados de un servidor de +sustituciones---y consulta a todos los servidores de sustituciones. Una vez +hecho informa de los elementos del almacén para los cuales los servidores +obtuvieron un resultado diferente de el obtenido en la construcción local. + +@cindex no-determinismo, en la construcción de paquetes +Como un ejemplo, @code{guix.example.org} siempre obtiene una respuesta +diferente. Por otro modo, @code{@value{SUBSTITUTE-SERVER}} coincide con las +construcciones locales, excepto en el caso de Git. Esto puede indicar que el +proceso de construcción de Git no es determinista, lo que significa que su +salida varia en función de varias cosas que Guix no controla completamente, +aunque la construcción de paquetes se realice en entornos aislados +(@pxref{Características}). Las fuentes más comunes de indeterminismo incluyen la +adición de marcas de tiempo en los resultados de la construcción, la +inclusión de números aleatorios y las enumeraciones de directorios ordenadas +por número de nodos-i. Véase @uref{https://reproducible-builds.org/docs/} +para más información. + +Para encontrar cuál es el problema con este binario Git, podemos hacer algo +parecido a esto (@pxref{Invocación de guix archive}): + +@example +$ wget -q -O - https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-git-2.5.0 \ + | guix archive -x /tmp/git +$ diff -ur --no-dereference /gnu/store/@dots{}-git.2.5.0 /tmp/git +@end example + +Esta orden muestra la diferencia entre los ficheros resultantes de la +construcción local y los ficheros resultantes de la construcción en +@code{@value{SUBSTITUTE-SERVER}} (@pxref{Overview, Comparing and Merging +Files,, diffutils, Comparing and Merging Files}). La orden @command{diff} +funciona muy bien en ficheros de texto. Cuando ficheros binarios difieren, +una opción mejor es @uref{https://diffoscope.org/,Diffoscope}, una +herramienta que ayuda en la visualización de diferencias en todo tipo de +ficheros. + +Una vez haya realizado este trabajo, puede determinar si las diferencias son +debidas a un procedimiento de construcción no-determinista o a un servidor +con intenciones ocultas. Intentamos duramente eliminar las fuentes de +indeterminismo en los paquetes para facilitar la verificación de +sustituciones, pero por supuesto es un proceso que implica no solo a Guix, +sino a una gran parte de la comunidad del software libre. Entre tanto, +@command{guix challenge} es una herramienta para ayudar a afrontar el +problema. + +Si esta escribiendo paquetes para Guix, le recomendamos que compruebe si +@code{@value{SUBSTITUTE-SERVER}} y otros servidores de sustituciones +obtienen el mismo resultado de construcción que el obtenido por usted: + +@example +$ guix challenge @var{paquete} +@end example + +@noindent +donde @var{paquete} es una especificación de paquete como @code{guile@@2.0} +o @code{glibc:debug}. + +La sintaxis general es: + +@example +guix challenge @var{opciones} [@var{paquetes}@dots{}] +@end example + +Cuando se encuentra una diferencia entre el hash de un elemento construido +localmente y el proporcionado por un servidor de sustituciones; o entre las +sustituciones proporcionadas por distintos servidores, esto es mostrado como +en el ejemplo previo y el valor de salida es 2 (otros valores no-cero de la +salida denominan otros tipos de error). + +La única opción de importancia es: + +@table @code + +@item --substitute-urls=@var{urls} +Considera @var{urls} la lista separada por espacios de URL de fuentes de +sustituciones con las que realizar la comparación. + +@item --verbose +@itemx -v +Muestra detalles sobre coincidencias (contenidos idénticos) además de +información sobre las discrepancias. + +@end table + +@node Invocación de guix copy +@section Invocación de @command{guix copy} + +@cindex copiar, elementos del almacén, por SSH +@cindex SSH, copiar elementos del almacén +@cindex compartir elementos del almacén entre máquinas +@cindex transferir elementos del almacén entre máquinas +La orden @command{guix copy} copia elementos del almacén de una máquina al +de otra a través de una conexión de shell seguro (SSH)@footnote{Esta orden +únicamente está disponible cuando ha encontrado +Guile-SSH. @xref{Requisitos}, para detalles.}. Por ejemplo, la siguiente +orden copia el paquete @code{coreutils}, el perfil de la usuaria y todas sus +dependencias a @var{dirección}, ingresando en el sistema como @var{usuaria}: + +@example +guix copy --to=@var{usuaria}@@@var{dirección} \ + coreutils `readlink -f ~/.guix-profile` +@end example + +Si alguno de los elementos del almacén a copiar ya están presentes en +@var{dirección}, no se envían realmente. + +La siguiente orden obtiene @code{libreoffice} y @code{gimp} de +@var{dirección}, asumiendo que estén disponibles allí: + +@example +guix copy --from=@var{dirección} libreoffice gimp +@end example + +La conexión SSH se establece usando el cliente Guile-SSH, que es compatible +con OpenSSH: tiene en cuenta @file{~/.ssh/known_hosts} y +@file{~/.ssh/config}, y usa el agente SSH para la identificación. + +La clave usada para firmar los elementos enviados debe estar aceptada por la +máquina remota. Del mismo modo, la clave usada por la máquina remota para +firmar los elementos recibidos debe estar en @file{/etc/guix/acl} de modo +que sea aceptada por su propio daemon. @xref{Invocación de guix archive}, para +más información sobre la verificación de elementos del almacén. + +La sintaxis general es: + +@example +guix copy [--to=@var{spec}|--from=@var{spec}] @var{elementos}@dots{} +@end example + +Siempre debe especificar una de las siguientes opciones: + +@table @code +@item --to=@var{spec} +@itemx --from=@var{spec} +Especifica la máquina a la que mandar o desde la que recibir. @var{spec} +debe ser una especificación SSH como @code{example.org}, +@code{carlos@@example.org}, or @code{carlos@@example.org:2222}. +@end table + +Los @var{elementos} pueden ser tanto nombres de paquetes, como @code{gimp}, +como elementos del almacén, como @file{/gnu/store/@dots{}-idutils-4.6}. + +Cuando se especifica el nombre del paquete a enviar, primero se construye si +es necesario, a menos que se use @option{--dry-run}. Se aceptan las opciones +comunes de construcción (@pxref{Opciones comunes de construcción}). + + +@node Invocación de guix container +@section Invocación de @command{guix container} +@cindex container +@cindex @command{guix container} +@quotation Nota +En la versión @value{VERSION}, esta herramienta es experimental. La interfaz +está sujeta a cambios radicales en el futuro. +@end quotation + +El propósito de @command{guix container} es la manipulación de procesos en +ejecución dentro de entornos aislados, normalmente conocido como un +``contenedor'', típicamente creado por las órdenes @command{guix +environment} (@pxref{Invocación de guix environment}) y @command{guix system +container} (@pxref{Invocación de guix system}). + +La sintaxis general es: + +@example +guix container @var{acción} @var{opciones}@dots{} +@end example + +@var{acción} especifica la operación a realizar con el contenedor, y +@var{opcines} especifica los parámetros específicos del contexto para la +acción. + +Las siguientes acciones están disponibles: + +@table @code +@item exec +Ejecute una orden en el contexto de un contenedor en ejecución. + +La sintaxis es: + +@example +guix container exec @var{pid} @var{programa} @var{parámetros}@dots{} +@end example + +@var{pid} especifica el ID del proceso del contenedor en +ejecución. @var{programa} especifica el nombre del fichero ejecutable dentro +del sistema de ficheros raíz del contenedor. @var{parámetros} son opciones +adicionales que se pasarán a @var{programa}. + +La siguiente orden lanza un shell interactivo de ingreso al sistema dentro +de un contenedor del sistema, iniciado por @command{guix system container}, +y cuyo ID de proceso es 9001: + +@example +guix container exec 9001 /run/current-system/profile/bin/bash --login +@end example + +Fíjese que el @var{pid} no puede ser el proceso creador del contenedor. Debe +ser el PID 1 del contenedor o uno de sus procesos hijos. + +@end table + +@node Invocación de guix weather +@section Invocación de @command{guix weather} + +De manera ocasional tendrá un mal día al no estar las sustituciones +disponibles y le toque construir los paquetes a usted misma +(@pxref{Sustituciones}). La orden @command{guix weather} informa de la +disponibilidad de sustituciones en los servidores especificados de modo que +pueda tener una idea sobre cómo será su día hoy. A veces puede ser una +información útil como usuaria, pero es principalmente útil para quienes +ejecuten @command{guix publish} (@pxref{Invocación de guix publish}). + +@cindex estadísticas, para sustituciones +@cindex disponibilidad de sustituciones +@cindex disponibilidad de sustituciones +@cindex weather, disponibilidad de sustituciones +Esta es una ejecución de ejemplo: + +@example +$ guix weather --substitute-urls=https://guix.example.org +computing 5,872 package derivations for x86_64-linux... +looking for 6,128 store items on https://guix.example.org.. +updating list of substitutes from 'https://guix.example.org'... 100.0% +https://guix.example.org + 43.4% substitutes available (2,658 out of 6,128) + 7,032.5 MiB of nars (compressed) + 19,824.2 MiB on disk (uncompressed) + 0.030 seconds per request (182.9 seconds in total) + 33.5 requests per second + + 9.8% (342 out of 3,470) of the missing items are queued + 867 queued builds + x86_64-linux: 518 (59.7%) + i686-linux: 221 (25.5%) + aarch64-linux: 128 (14.8%) + build rate: 23.41 builds per hour + x86_64-linux: 11.16 builds per hour + i686-linux: 6.03 builds per hour + aarch64-linux: 6.41 builds per hour +@end example + +@cindex integración continua, estadísticas +As you can see, it reports the fraction of all the packages for which +substitutes are available on the server---regardless of whether substitutes +are enabled, and regardless of whether this server's signing key is +authorized. It also reports the size of the compressed archives (``nars'') +provided by the server, the size the corresponding store items occupy in the +store (assuming deduplication is turned off), and the server's throughput. +The second part gives continuous integration (CI) statistics, if the server +supports it. In addition, using the @option{--coverage} option, +@command{guix weather} can list ``important'' package substitutes missing on +the server (see below). + +Para conseguirlo, @command{guix weather} consulta los metadatos HTTP(S) +(@dfn{narinfo}s) de todos los elementos relevantes del almacén. Como +@command{guix challenge}, ignora las firmas en esas sustituciones, lo cual +es inocuo puesto que la orden únicamente obtiene estadísticas y no puede +instalar esas sustituciones. + +Entre otras cosas, es posible consultar tipos específicos de sistema y +conjuntos específicos de paquetes. Las opciones disponibles se enumeran a +continuación. + +@table @code +@item --substitute-urls=@var{urls} +@var{urls} es la lista separada por espacios de URL de servidores de +sustituciones a consultar. Cuando se omite esta opción, el conjunto +predeterminado de servidores de sustituciones es el consultado. + +@item --system=@var{sistema} +@itemx -s @var{sistema} +Consulta sustituciones para @var{sistema}---por ejemplo, +@code{aarch64-linux}. Esta opción se puede repetir, en cuyo caso +@command{guix weather} consultará las sustituciones para varios tipos de +sistema. + +@item --manifest=@var{fichero} +En vez de consultar las sustituciones de todos los paquetes, consulta +únicamente los especificados en @var{fichero}. @var{fichero} debe contener +un @dfn{manifiesto}, como el usado en la opción @code{-m} de @command{guix +package} (@pxref{Invocación de guix package}). + +@item --coverage[=@var{numero}] +@itemx -c [@var{numero}] +Report on substitute coverage for packages: list packages with at least +@var{count} dependents (zero by default) for which substitutes are +unavailable. Dependent packages themselves are not listed: if @var{b} +depends on @var{a} and @var{a} has no substitutes, only @var{a} is listed, +even though @var{b} usually lacks substitutes as well. The result looks +like this: + +@example +$ guix weather --substitute-urls=https://ci.guix.es.info -c 10 +computing 8,983 package derivations for x86_64-linux... +looking for 9,343 store items on https://ci.guix.es.info... +updating substitutes from 'https://ci.guix.es.info'... 100.0% +https://ci.guix.es.info + 64.7% substitutes available (6,047 out of 9,343) +@dots{} +2502 packages are missing from 'https://ci.guix.es.info' for 'x86_64-linux', among which: + 58 kcoreaddons@@5.49.0 /gnu/store/@dots{}-kcoreaddons-5.49.0 + 46 qgpgme@@1.11.1 /gnu/store/@dots{}-qgpgme-1.11.1 + 37 perl-http-cookiejar@@0.008 /gnu/store/@dots{}-perl-http-cookiejar-0.008 + @dots{} +@end example + +What this example shows is that @code{kcoreaddons} and presumably the 58 +packages that depend on it have no substitutes at @code{ci.guix.es.info}; +likewise for @code{qgpgme} and the 46 packages that depend on it. + +If you are a Guix developer, or if you are taking care of this build farm, +you'll probably want to have a closer look at these packages: they may +simply fail to build. +@end table + +@node Invocación de guix processes +@section Invocación de @command{guix processes} + +La orden @command{guix processes} puede ser útil a desarrolladoras y +administradoras de sistemas, especialmente en máquinas multiusuaria y en +granjas de construcción: enumera las sesiones actuales (conexiones al +daemon), así como información sobre los procesos envueltos@footnote{Las +sesiones remotas, cuando @command{guix-daemon} se ha iniciado con +@option{--listen} especificando un punto de conexión TCP, @emph{no} son +enumeradas.}. A continuación puede verse un ejemplo de la información que +devuelve: + +@example +$ sudo guix processes +SessionPID: 19002 +ClientPID: 19090 +ClientCommand: guix environment --ad-hoc python + +SessionPID: 19402 +ClientPID: 19367 +ClientCommand: guix publish -u guix-publish -p 3000 -C 9 @dots{} + +SessionPID: 19444 +ClientPID: 19419 +ClientCommand: cuirass --cache-directory /var/cache/cuirass @dots{} +LockHeld: /gnu/store/@dots{}-perl-ipc-cmd-0.96.lock +LockHeld: /gnu/store/@dots{}-python-six-bootstrap-1.11.0.lock +LockHeld: /gnu/store/@dots{}-libjpeg-turbo-2.0.0.lock +ChildProcess: 20495: guix offload x86_64-linux 7200 1 28800 +ChildProcess: 27733: guix offload x86_64-linux 7200 1 28800 +ChildProcess: 27793: guix offload x86_64-linux 7200 1 28800 +@end example + +En este ejemplo vemos que @command{guix-daemon} tiene tres clientes: +@command{guix environment}, @command{guix publish} y la herramienta de +integración continua Cuirass; sus identificadores de proceso (PID) se +muestran en el campo @code{ClientPID}. El campo @code{SessionPID} +proporciona el PID del subproceso de @command{guix-daemon} de cada sesión en +particular. + +El campo @code{LockHeld} muestra qué elementos del almacén están bloqueados +actualmente por cada sesión, lo que corresponde a elementos del almacén en +construcción o sustitución (el campo @code{LockHeld} no se muestra cuando +@command{guix processes} no se ejecutó como root). Por último, mediante el +campo @code{ChildProcess} entendemos que esas tres construcciones están +siendo delegadas (@pxref{Configuración de delegación del daemon}). + +La salida está en formato Recutils por lo que podemos usar la útil orden +@command{recsel} para seleccionar sesiones de interés (@pxref{Selection +Expressions,,, recutils, GNU recutils manual}). Como un ejemplo, la +siguiente orden muestra la línea de órdenes y el PID del cliente que inició +la construcción de un paquete Perl: + +@example +$ sudo guix processes | \ + recsel -p ClientPID,ClientCommand -e 'LockHeld ~ "perl"' +ClientPID: 19419 +ClientCommand: cuirass --cache-directory /var/cache/cuirass @dots{} +@end example + + +@node Configuración del sistema +@chapter Configuración del sistema + +@cindex configuración del sistema +La Distribución de Sistema Guix permite un mecanismo de configuración del +sistema completo consistente. Con esto queremos decir que todos los aspectos +de la configuración global del sistema---como los servicios disponibles, la +zona horaria y la configuración de localización, las cuentas de +usuarias---se declaran en un lugar único. Dicha @dfn{configuración del +sistema} puede ser @dfn{instanciada}---es decir, hecha efectiva. + +@c Yes, we're talking of Puppet, Chef, & co. here. ↑ +Una de las ventajas de poner toda la configuración del sistema bajo el +control de Guix es que permite actualizaciones transaccionales del sistema, +y hace posible volver a una instanciación previa del sistema, en caso de que +haya algún problema con la nueva (@pxref{Características}). Otra ventaja es que +hace fácil replicar exactamente la misma configuración entre máquinas +diferentes, o en diferentes momentos, sin tener que utilizar herramientas de +administración adicionales sobre las propias herramientas del sistema. + +Esta sección describe este mecanismo. Primero nos enfocaremos en el punto de +vista de la administradora del sistema---explicando cómo se configura e +instancia el sistema. Después mostraremos cómo puede extenderse este +mecanismo, por ejemplo para añadir nuevos servicios del sistema. + +@menu +* Uso de la configuración del sistema:: Personalizar su sistema GNU. +* Referencia de ``operating-system'':: Detalle de las declaraciones de + sistema operativo. +* Sistemas de ficheros:: Configurar el montaje de sistemas de ficheros. +* Dispositivos traducidos:: Procesamiento extra de dispositivos de bloques. +* Cuentas de usuaria:: Especificar las cuentas de usuaria. +* Distribución de teclado:: Cómo interpreta el sistema las pulsaciones + del teclado. +* Localizaciones:: Configuración de idioma y convenciones + culturales. +* Servicios:: Especificar los servicios del sistema. +* Programas con setuid:: Programas que se ejecutan con privilegios de + root. +* Certificados X.509:: Verificar servidores HTTPS. +* Selector de servicios de nombres:: Configurar el selector de servicios de + nombres de libc. +* Disco en RAM inicial:: Arranque de Linux-Libre. +* Configuración del gestor de arranque:: Configurar el gestor de arranque. +* Invocación de guix system:: Instanciar una configuración del sistema. +* Ejecutar Guix en una máquina virtual:: Cómo ejecutar el sistema Guix en + una máquina virtual. +* Definición de servicios:: Añadir nuevas definiciones de servicios. +@end menu + +@node Uso de la configuración del sistema +@section Uso de la configuración del sistema + +El sistema operativo se configura proporcionando una declaración +@code{operating-system} en un fichero que pueda ser proporcionado a la orden +@command{guix system} (@pxref{Invocación de guix system}). Una configuración +simple, con los servicios predeterminados del sistema, el núcleo Linux-Libre +predeterminado, un disco de RAM inicial y un cargador de arranque puede ser +como sigue: + +@findex operating-system +@lisp +@include os-config-bare-bones.texi +@end lisp + +Este ejemplo debería ser auto-descriptivo. Algunos de los campos definidos +anteriormente, como @code{host-name} y @code{bootloader}, son +necesarios. Otros como @code{packages} y @code{services}, pueden omitirse, +en cuyo caso obtienen un valor por defecto. + +Más adelante se muestran los efectos de algunos de los campos más +importantes (@pxref{Referencia de ``operating-system''}, para detalles acerca de +todos los campos disponibles), y cómo @dfn{instanciar} el sistema operativo +usando @command{guix system}. + +@unnumberedsubsec Cargador de arranque + +@cindex arranque obsoleto, en máquinas Intel +@cindex arranque por BIOS, en máquinas Intel +@cindex arranque UEFI +@cindex arranque EFI +El campo @code{bootloader} describe el método que será usado para arrancar +su sistema. Las máquinas basadas en procesadores Intel pueden arrancar en el +``obsoleto'' modo BIOS, como en el ejemplo previo. No obstante, máquinas más +recientes usan la @dfn{Interfaz Unificada Extensible de Firmware} (UEFI) +para arrancar. En ese caso, el capo @code{bootloader} debe contener algo +parecido a esto: + +@example +(bootloader-configuration + (bootloader grub-efi-bootloader) + (target "/boot/efi")) +@end example + +@xref{Configuración del gestor de arranque}, para más información sobre las opciones de +configuración disponibles. + +@unnumberedsubsec Paquetes visibles globalmente + +@vindex %base-packages +El campo @code{packages} enumera los paquetes que serán visibles globalmente +en el sistema, para todas las cuentas de usuaria---es decir, en la variable +de entorno @code{PATH} de cada usuaria---además de los perfiles por usuaria +(@pxref{Invocación de guix package}). La variable @var{%base-packages} +proporciona todas las herramientas esperadas para tareas básicas y de +administración---incluyendo las utilidades básicas GNU, las herramientas de +red GNU, el editor de texto ligero GNU Zile, @command{find}, @command{grep}, +etc. El ejemplo previo se añade GNU@tie{}Screen a estos, tomado del módulo +@code{(gnu packages screen)} (@pxref{Módulos de paquetes}). La sintaxis +@code{(list package output)} puede usarse para añadir una salida específica +de un paquete: + +@lisp +(use-modules (gnu packages)) +(use-modules (gnu packages dns)) + +(operating-system + ;; ... + (packages (cons (list bind "utils") + %base-packages))) +@end lisp + +@findex specification->package +Referirse a los paquetes por nombre de variable, como antes a @code{bind}, +tiene la ventaja de evitar ambigüedades; también permite que errores +tipográficos y demás obtengan un diagnóstico directo como ``variables sin +definir''. La parte problemática es que se necesita conocer qué módulo +define qué paquete, y aumentar adecuadamente la línea de +@code{use-package-modules}. Para evitar esto, se puede usar el procedimiento +@code{specification->package} del módulo @code{(gnu packages)}, que devuelve +el mejor paquete para un nombre dado, o nombre y versión: + +@lisp +(use-modules (gnu packages)) + +(operating-system + ;; ... + (packages (append (map specification->package + '("tcpdump" "htop" "gnupg@@2.0")) + %base-packages))) +@end lisp + +@unnumberedsubsec Servicios del sistema + +@cindex services +@vindex %base-services +The @code{services} field lists @dfn{system services} to be made available +when the system starts (@pxref{Servicios}). The @code{operating-system} +declaration above specifies that, in addition to the basic services, we want +the OpenSSH secure shell daemon listening on port 2222 (@pxref{Servicios de red, @code{openssh-service-type}}). Under the hood, +@code{openssh-service-type} arranges so that @command{sshd} is started with +the right command-line options, possibly with supporting configuration files +generated as needed (@pxref{Definición de servicios}). + +@cindex personalización, de servicios +@findex modify-services +De manera ocasional, en vez de usar los servicios básicos tal y como vienen, +puede querer personalizarlos. Para hacerlo, use @code{modify-services} +(@pxref{Referencia de servicios, @code{modify-services}}) para modificar la lista. + +Por ejemplo, supongamos que quiere modificar @code{guix-daemon} y Mingetty +(el punto de acceso al sistema por consola) en la lista @var{%base-services} +(@pxref{Servicios base, @code{%base-services}}). Para hacerlo, puede escribir +lo siguiente en su declaración de sistema operativo: + +@lisp +(define %mis-servicios + ;; Mi propia lista de servicios + (modify-services %base-services + (guix-service-type config => + (guix-configuration + (inherit config) + (use-substitutes? #f) + (extra-options '("--gc-keep-derivations")))) + (mingetty-service-type config => + (mingetty-configuration + (inherit config))))) + +(operating-system + ;; @dots{} + (services %mis-servicios)) +@end lisp + +Esto modifica la configuración---es decir, los parámetros de los +servicios---de la instancia @code{guix-service-type}, y de todas las +instancias de @code{mingetty-service-type} en la lista +@var{%base-services}. Observe cómo se consigue: primero, enlazamos la +configuración actual al identificador @code{config} en el @var{cuerpo}, y +entonces escribimos el @var{cuerpo} de manera que evalue a la configuración +deseada. En particular, fíjese como se usa @code{inherit} para crear una +nueva configuración que tiene los mismos valores que la configuración +antigua, pero con unas pocas modificaciones. + +@cindex disco cifrado +La configuración para un uso típico de ``escritorio'', con una partición de +raíz cifrada, el servidor gráfico X11, GNOME y Xfce (las usuarias pueden +escoger cual de estos entornos de escritorio usarán en la pantalla de inicio +de sesión pulsando @kbd{F1}), gestión de red, gestión de energía y más, +podría ser así: + +@lisp +@include os-config-desktop.texi +@end lisp + +Un sistema gráfico con una selección de gestores de ventanas ligeros en vez +de entornos de escritorio completos podría ser así: + +@lisp +@include os-config-lightweight-desktop.texi +@end lisp + +Este ejemplo se refiere al sistema de ficheros @file{/boot/efi} por su UUID +@code{1234-ABCD}. Substituya este UUID con el UUID correcto en su sistema, +como el devuelto por la orden @command{blkid}. + +@xref{Servicios de escritorio}, para la lista exacta de servicios proporcionados +por @var{%desktop-services}. @xref{Certificados X.509}, para información +sobre el paquete @code{nss-certs} usado aquí. + +De nuevo, @var{%desktop-services} es simplemente una lista de objetos de +servicios. Si desea borrar servicios de aquí, puede hacerlo usando +procedimientos de filtrado de listas (@pxref{SRFI-1 Filtering and +Partitioning,,, guile, GNU Guile Reference Manual}). Por ejemplo, la +siguiente expresión devuelve una lista que contiene todos los servicios en +@var{%desktop-services} excepto el servicio Avahi: + +@example +(remove (lambda (service) + (eq? (service-kind service) avahi-service-type)) + %desktop-services) +@end example + +@unnumberedsubsec Instanciación del sistema + +Asumiendo que la declaración de @code{operating-system} se encuentra en el +fichero @file{my-conf-del-sistema.scm}, la orden @command{guix system +mi-conf-del-sistema.scm} instancia esa configuración, y la convierte en la +entrada predeterminada de GRUB en el arranque (@pxref{Invocación de guix system}). + +La manera habitual de cambiar la configuración del sistema es actualizar +este fichero y volver a ejecutar @command{guix system reconfigure}. Nunca se +deberían tocar los ficheros en @file{/etc} o ejecutar órdenes que modifiquen +el estado del sistema como @command{useradd} o @command{grub-install}. De +hecho, debe evitarlo ya que no únicamente anularía su garantía sino que +también le impediría volver a una versión previa de su sistema, en caso de +necesitarlo. + +@cindex vuelta-atrás, del sistema operativo +Hablando de vuelta atrás, cada vez que ejecuta @command{guix system +reconfigure} se crea una nueva @dfn{generación} del sistema---sin modificar +o borrar generaciones previas. Las generaciones previas tienen una entrada +en el menú del cargador de arranque, permitiendole arrancarlas en caso de +que algo funcionase mal en las últimas generaciones. Tranquilizador, ¿no? La +orden @command{guix system list-generations} enumera las generaciones del +sistema disponibles en el disco. Es también posible volver a una versión +previa con las órdenes @command{guix system roll-back} y @command{guix +system switch-generation}. + +Aunque la orden @command{guix system reconfigure} no modificará las +generaciones previas, debe tener cuidado cuando la generación actual no es +la última (por ejemplo, después de invocar @command{guix system roll-back}), +ya que la operación puede sobreescribir una generación posterior +(@pxref{Invocación de guix system}). + +@unnumberedsubsec La interfaz programática + +A nivel Scheme, el grueso de una declaración @code{operating-system} se +instancia con el siguiente procedimiento monádico (@pxref{La mónada del almacén}): + +@deffn {Procedimiento monádico} operating-system-derivation so +Devuelve una derivación que construye @var{so}, un objeto +@code{operating-system} (@pxref{Derivaciones}). + +La salida de la derivación es un único directorio que hace referencia a +todos los paquetes, ficheros de configuración y otros ficheros auxiliares +necesarios para instanciar @var{so}. +@end deffn + +This procedure is provided by the @code{(gnu system)} module. Along with +@code{(gnu services)} (@pxref{Servicios}), this module contains the guts of +Guix System. Make sure to visit it! + + +@node Referencia de ``operating-system'' +@section Referencia de @code{operating-system} + +Esta sección resume todas las opciones disponibles en las declaraciones de +@code{operating-system} (@pxref{Uso de la configuración del sistema}). + +@deftp {Tipo de datos} operating-system +Este es el tipo de datos que representa la configuración del sistema +operativo. Con ello queremos decir toda la configuración global del sistema, +no la configuración específica de las usuarias (@pxref{Uso de la configuración del sistema}). + +@table @asis +@item @code{kernel} (predeterminado: @code{linux-libre}) +El objeto del paquete del núcleo del sistema operativo +usado@footnote{Actualmente únicamente está disponible el núcleo +Linux-libre. En el futuro será posible usar GNU@tie{}Hurd.}. + +@item @code{kernel-arguments} (default: @code{'("quiet")}) +Lista de cadenas o expresiones-G que representan parámetros adicionales a +pasar en la línea de órdenes del núcleo---por ejemplo, +@code{("console=ttyS0")}. + +@item @code{bootloader} +El objeto de configuración del cargador de arranque del +sistema. @xref{Configuración del gestor de arranque}. + +@item @code{label} +This is the label (a string) as it appears in the bootloader's menu entry. +The default label includes the kernel name and version. + +@item @code{keyboard-layout} (predeterminada: @code{#f}) +This field specifies the keyboard layout to use in the console. It can be +either @code{#f}, in which case the default keyboard layout is used (usually +US English), or a @code{<keyboard-layout>} record. + +This keyboard layout is in effect as soon as the kernel has booted. For +instance, it is the keyboard layout in effect when you type a passphrase if +your root file system is on a @code{luks-device-mapping} mapped device +(@pxref{Dispositivos traducidos}). + +@quotation Nota +This does @emph{not} specify the keyboard layout used by the bootloader, nor +that used by the graphical display server. @xref{Configuración del gestor de arranque}, +for information on how to specify the bootloader's keyboard layout. @xref{Sistema X Window}, for information on how to specify the keyboard layout used by the X +Window System. +@end quotation + +@item @code{initrd-modules} (predeterminados: @code{%base-initrd-modules}) +@cindex initrd +@cindex disco inicial de RAM +La lista de módulos del núcleo Linux que deben estar disponibles en el disco +inicial de RAM. @xref{Disco en RAM inicial}. + +@item @code{initrd} (predeterminado: @code{base-initrd}) +Un procedimiento que devuelve un disco inicial de RAM para el núcleo +Linux. Este campo se proporciona para permitir personalizaciones de bajo +nivel y no debería ser necesario para un uso habitual. @xref{Disco en RAM inicial}. + +@item @code{firmware} (predeterminado: @code{%base-firmware}) +@cindex firmware +Lista de paquetes de firmware que pueden ser cargados por el núcleo del +sistema operativo. + +El valor predeterminado incluye el firmware necesario para dispositivos WiFi +basados en Atheros y Broadcom (módulos Linux-libre @code{ath9k} y +@code{b43-open}, respectivamente). @xref{Consideraciones sobre el hardware}, para más +información sobre hardware soportado. + +@item @code{host-name} +El nombre de la máquina. + +@item @code{hosts-file} +@cindex el fichero hosts +Un objeto tipo-fichero (@pxref{Expresiones-G, objetos tipo-fichero}) para +ser usado como @file{/etc/hosts} (@pxref{Host Names,,, libc, The GNU C +Library Reference Manual}). El predeterminado es un fichero con entradas +para @code{localhost} y @var{host-name}. + +@item @code{mapped-devices} (predeterminados: @code{'()}) +Una lista de dispositivos traducidos. @xref{Dispositivos traducidos}. + +@item @code{file-systems} +Una lista de sistemas de ficheros. @xref{Sistemas de ficheros}. + +@item @code{swap-devices} (predeterminados: @code{'()}) +@cindex dispositivos de intercambio +Una lista de cadenas que identifiquen dispositivos o ficheros a usar como +``espacio de intercambio'' (@pxref{Memory Concepts,,, libc, The GNU C +Library Reference Manual}). Por ejemplo @code{'("/dev/sda3")} o +@code{'("/fichero-intercambio")}. Es posible especificar un fichero de +intercambio en un sistema de ficheros en un dispositivo traducido, siempre +que la traducción y el sistema de ficheros se especifiquen +también. @xref{Dispositivos traducidos} y @ref{Sistemas de ficheros}. + +@item @code{users} (predeterminadas: @code{%base-user-accounts}) +@itemx @code{groups} (predeterminados: @var{%base-groups}) +Lista de cuentas de usuaria y grupos. @xref{Cuentas de usuaria}. + +Si la lista de @code{usuarias} carece de una cuenta de usuaria con +UID@tie{}0, una cuenta ``root'' con UID@tie{}0 se añade automáticamente. + +@item @code{skeletons} (predeterminados: @code{(default-skeletons)}) +Una lista de tuplas de nombre de fichero de destino/objeto tipo-fichero +(@pxref{Expresiones-G, objetos tipo-fichero}). Estos son los ficheros de +esqueleto que se añadirán al directorio de las cuentas de usuaria que se +creen. + +Por ejemplo, un valor válido puede parecer algo así: + +@example +`((".bashrc" ,(plain-file "bashrc" "echo Hola\n")) + (".guile" ,(plain-file "guile" + "(use-modules (ice-9 readline)) + (activate-readline)"))) +@end example + +@item @code{issue} (predeterminado: @var{%default-issue}) +Una cadena que denota el contenido del fichero @file{/etc/issue}, que se +muestra cuando las usuarias ingresan al sistema en una consola de texto. + +@item @code{packages} (predeterminados: @var{%base-packages}) +El conjunto de paquetes instalados en el perfil global, que es accesible en +@file{/run/current-system/profile}. + +El conjunto predeterminado incluye utilidades básicas y es una buena +práctica instalar utilidades no-básicas en los perfiles de las usuarias +(@pxref{Invocación de guix package}). + +@item @code{timezone} +Una cadena que identifica la zona horaria---por ejemplo, +@code{"Europe/Paris"}. + +Puede ejecutar la orden @command{tzselect} para encontrar qué cadena de zona +horaria corresponde con su región. Elegir una zona horaria no válida provoca +un fallo en @command{guix system}. + +@item @code{locale} (predeterminado: @code{"en_US.utf8"}) +El nombre de la localización predeterminada (@pxref{Locale Names,,, libc, +The GNU C Library Reference Manual}). @xref{Localizaciones}, para más información. + +@item @code{locale-definitions} (predeterminadas: @var{%default-locale-definitions}) +La lista de definiciones de localizaciones a compilar y que puede ser usada +en tiempo de ejecución. @xref{Localizaciones}. + +@item @code{locale-libcs} (predeterminadas: @code{(list @var{glibc})}) +La lista de paquetes GNU@tie{}libc cuyos datos de localización y +herramientas son usadas para las definiciones de +localizaciones. @xref{Localizaciones}, para consideraciones de compatibilidad que +justifican esta opción. + +@item @code{name-service-switch} (predeterminado: @var{%default-nss}) +Configuración del selector de servicios de nombres de libc (NSS)---un objeto +@code{<name-service-switch>}. @xref{Selector de servicios de nombres}, para detalles. + +@item considera +Una lista de objetos service denotando los servicios del +sistema. @xref{Servicios}. + +@cindex servicios esenciales +@item @code{essential-services} (predeterminados: ...) +The list of ``essential services''---i.e., things like instances of +@code{system-service-type} and @code{host-name-service-type} (@pxref{Referencia de servicios}), which are derived from the operating system definition itself. +As a user you should @emph{never} need to touch this field. + +@item @code{pam-services} (predeterminados: @code{(base-pam-services)}) +@cindex PAM +@cindex módulos de verificación conectables +@c FIXME: Add xref to PAM services section. +Servicios de los @dfn{módulos de verificación conectables} (PAM) de Linux. + +@item @code{setuid-programs} (predeterminados: @var{%setuid-programs}) +Lista de expresiones-G con valores de cadena que denotan los programas +setuid. @xref{Programas con setuid}. + +@item @code{sudoers-file} (predeterminado: @var{%sudoers-specification}) +@cindex fichero sudoers +El contenido de @file{/etc/sudoers} como un objeto tipo-fichero +(@pxref{Expresiones-G, @code{local-file} y @code{plain-file}}). + +Este fichero especifica qué usuarias pueden usar la orden @command{sudo}, lo +que se les permite hacer y qué privilegios pueden obtener. El comportamiento +predefinido es que únicamente @code{root} y los miembros del grupo +@code{wheel} pueden usar @code{sudo}. + +@end table + +@deffn {Scheme Syntax} this-operating-system +When used in the @emph{lexical scope} of an operating system field +definition, this identifier resolves to the operating system being defined. + +The example below shows how to refer to the operating system being defined +in the definition of the @code{label} field: + +@example +(use-modules (gnu) (guix)) + +(operating-system + ;; ... + (label (package-full-name + (operating-system-kernel this-operating-system)))) +@end example + +It is an error to refer to @code{this-operating-system} outside an operating +system definition. +@end deffn + +@end deftp + +@node Sistemas de ficheros +@section Sistemas de ficheros + +La lista de sistemas de ficheros que deben montarse se especifica en el +campo @code{file-systems} de la declaración del sistema operativo +(@pxref{Uso de la configuración del sistema}). Cada sistema de ficheros se +declara usando la forma @code{file-system}, como en el siguiente ejemplo: + +@example +(file-system + (mount-point "/home") + (device "/dev/sda3") + (type "ext4")) +@end example + +Como es habitual, algunos de los campos son obligatorios---aquellos +mostrados en el ejemplo previo---mientras que otros pueden omitirse. Se +describen a continuación. + +@deftp {Tipo de datos} file-system +Objetos de este tipo representan los sistemas de ficheros a +montar. Contienen los siguientes campos: + +@table @asis +@item @code{type} +Este campo es una cadena que especifica el tipo de sistema de ficheros---por +ejemplo, @code{"ext4"}. + +@item @code{mount-point} +Designa la ruta donde el sistema de ficheros debe montarse. + +@item @code{device} +Nombra la ``fuente'' del sistema de ficheros. Puede ser una de estas tres +opciones: una etiqueta de sistema de ficheros, un UUID de sistema de +ficheros o el nombre de un nodo @file{/dev}. Las etiquetas y UUID ofrecen +una forma de hacer referencia a sistemas de ficheros sin codificar su nombre +de dispositivo actual@footnote{Fijese que, aunque es tentador usa +@file{/dev/disk/by-uuid} y nombres de dispositivo similares para obtener el +mismo resultado, no es lo recomendado: estos nodo especiales de dispositivos +se crean por el daemon udev y puede no estar disponible cuando el +dispositivo sea montado.}. + +@findex file-system-label +Las etiquetas del sistema de ficheros se crean mediante el uso del +procedimiento @code{file-system-label}, los UUID se crean mediante el uso de +@code{uuid} y los nodos @file{/dev} son simples cadenas. A continuación se +proporciona un ejemplo de un sistema de ficheros al que se hace referencia +mediante su etiqueta, como es mostrada por la orden @command{e2label}: + +@example +(file-system + (mount-point "/home") + (type "ext4") + (device (file-system-label "mi-home"))) +@end example + +@findex uuid +Los UUID se convierten dede su representación en forma de cadena (como se +muestra con la orden @command{tune2fs -l}) mediante el uso de la forma +@code{uuid}@footnote{La forma @code{uuid} espera un UUID de 16 bytes como se +define en la @uref{https://tools.ietf.org/html/rfc4122, RFC@tie{}4122}. Este +es el formato de UUID que usan la familia de sistemas de ficheros ext2 y +otros, pero es diferente de los ``UUID'' de los sistemas de ficheros FAT, +por ejemplo.}, como sigue: + +@example +(file-system + (mount-point "/home") + (type "ext4") + (device (uuid "4dab5feb-d176-45de-b287-9b0a6e4c01cb"))) +@end example + +Cuando la fuente de un sistema de ficheros es un dispositivo traducido +(@pxref{Dispositivos traducidos}), su campo @code{device} @emph{debe} hacer +referencia al nombre del dispositivo traducido---por ejemplo, +@file{"/dev/mapper/particion-raiz"}. Esto es necesario para que el sistema +sepa que el montaje del sistema de ficheros depende del establecimiento de +la traducción de dispositivos correspondiente. + +@item @code{flags} (predeterminadas: @code{'()}) +Una lista de símbolos que denotan opciones del montaje. Las opciones +reconocidas incluyen @code{read-only} (modo de sólo lectura), +@code{bind-mount} (montaje enlazado), @code{no-dev} (prohibición del acceso +a ficheros especiales), @code{no-suid} (ignora los bits setuid y setgid) y +@code{no-exec} (prohibición de la ejecución de programas). + +@item @code{options} (predeterminadas: @code{#f}) +Esto es o bien @code{#f}, o bien una cadena que contiene opciones de +montaje. + +@item @code{mount?} (predeterminado: @code{#t}) +Este valor indica si debe montarse el sistema de ficheros automáticamente al +iniciar el sistema. Cuando se establece como @code{#f}, el sistema de +ficheros tiene una entrada en @file{/etc/fstab} (el cual es leído por la +orden @command{mount}) pero no se montará automáticamente. + +@item @code{needed-for-boot?} (predeterminado: @code{#f}) +Este valor lógico indica si el sistema de ficheros es necesario para el +arranque. Si es verdadero, el sistema de ficheros se monta al cargar el +disco inicial de RAM (initrd). Este es siempre el caso, por ejemplo, para el +sistema de ficheros raíz. + +@item @code{check?} (predeterminado: @code{#t}) +Este valor lógico indica si el sistema de ficheros se debe comprobar en +busca de errores antes de montarse. + +@item @code{create-mount-point?} (predeterminado: @code{#f}) +Cuando es verdadero, el punto de montaje es creado si no existía +previamente. + +@item @code{dependencies} (predeterminadas: @code{'()}) +Una lista de objetos @code{<file-system>} o @code{<mapped-device>} que +representan sistemas de ficheros que deben montarse o dispositivos +traducidos que deben abrirse antes (y desmontarse o cerrarse después) que el +declarado. + +Como ejemplo, considere la siguiente jerarquía de montajes: +@file{/sys/fs/cgroup} es una dependencia de @file{/sys/fs/cgroup/cpu} y +@file{/sys/fs/cgroup/memory}. + +Otro ejemplo es un sistema de ficheros que depende de un dispositivo +traducido, por ejemplo una partición cifrada (@pxref{Dispositivos traducidos}). +@end table +@end deftp + +El módulo @code{(gnu system file-systems)} exporta las siguientes variables +útiles. + +@defvr {Variable Scheme} %base-file-systems +Estos son los sistemas de ficheros esenciales que se necesitan en sistemas +normales, como @var{%pseudo-terminal-file-system} y @var{%immutable-store} +(véase a continuación). Las declaraciones de sistemas operativos deben +contener siempre estos al menos. +@end defvr + +@defvr {Variable Scheme} %pseudo-terminal-file-systems +El sistema de ficheros que debe montarse como @file{/dev/pts}. Permite la +creación de @dfn{pseudoterminales} a través de @code{openpty} y funciones +similares (@pxref{Pseudo-Terminals,,, libc, The GNU C Library Reference +Manual}). Los pseudoterminales son usados por emuladores de terminales como +@command{xterm}. +@end defvr + +@defvr {Variable Scheme} %shared-memory-file-system +Este sistema de ficheros se monta como @file{/dev/shm} y se usa para +permitir el uso de memoria compartida entre procesos (@pxref{Memory-mapped +I/O, @code{shm_open},, libc, The GNU C Library Reference Manual}). +@end defvr + +@defvr {Variable Scheme} %immutable-store +Este sistema de ficheros crea un montaje enlazado (``bind-mount'') de +@file{/gnu/store}, permitiendo solo el acceso de lectura para todas las +usuarias incluyendo a @code{root}. Esto previene modificaciones accidentales +por software que se ejecuta como @code{root} o por las administradoras del +sistema. + +El daemon sí es capaz de escribir en el almacén: vuelve a montar +@file{/gnu/store} en modo lectura-escritura en su propio ``espacio de +nombres''. +@end defvr + +@defvr {Variable Scheme} %binary-format-file-system +El sistema de ficheros @code{binfmt_misc}, que permite que el manejo de +tipos de ficheros ejecutables arbitrarios se delegue al espacio de +usuaria. Necesita la carga del módulo del núcleo @code{binfmt.ko}. +@end defvr + +@defvr {Variable Scheme} %fuse-control-file-system +El sistema de ficheros @code{fusectl}, que permite a usuarias sin +privilegios montar y desmontar sistemas de ficheros de espacio de usuaria +FUSE. Necesita la carga del módulo del núcleo @code{fuse.ko}. +@end defvr + +@node Dispositivos traducidos +@section Dispositivos traducidos + +@cindex traducción de dispositivos +@cindex dispositivos traducidos +El núcleo Linux tiene una noción de @dfn{traducción de dispositivos}: un +dispositivo de bloques, como una partición de disco duro, puede +@dfn{traducirse} en otro dispositivo, habitualmente en @code{/dev/mapper/}, +con un procesamiento adicional sobre los datos que fluyen a través de +ella@footnote{Fíjese que GNU@tie{}Hurd no diferencia entre el concepto de un +``dispositivo traducido'' y el de un sistema de ficheros: ambos se reducen a +@emph{traducir} operaciones de entrada/salida realizadas en un fichero a +operaciones en su almacenamiento subyacente. Por tanto, Hurd implementa +dispositivos traducidos, como sistemas de ficheros, usando el mecanismo +genérico de @dfn{traducción} (@pxref{Translators,,, hurd, The GNU Hurd +Reference Manual}).}. Un ejemplo típico es la traducción de dispositivos +para el cifrado: todas las escrituras en el dispositivo traducido se cifran, +y todas las lecturas se descifran, de forma transparente. Guix extiende esta +noción considerando cualquier dispositivo o conjunto de dispositivos que son +@dfn{transformados} de alguna manera para crear un nuevo dispositivo; por +ejemplo, los dispositivos RAID se obtienen @dfn{ensamblando} otros +dispositivos, como discos duros o particiones, en uno nuevo que se comporta +como una partición. Otros ejemplos, todavía no implementados, son los +volúmenes lógicos LVM. + +Los dispositivos traducidos se declaran mediante el uso de la forma +@code{mapped-device}, definida a continuación; ejemplos más adelante. + +@deftp {Tipo de datos} mapped-device +Objetos de este tipo representan traducciones de dispositivo que se llevarán +a cabo cuando el sistema arranque. + +@table @code +@item source +Puede ser tanto una cadena que especifica el nombre de un dispositivo de +bloques a traducir, como @code{"/dev/sda3"}, o una lista de dichas cadenas +cuando varios dispositivos necesitan ser ensamblados para crear uno nuevo. + +@item target +Esta cadena especifica el nombre del dispositivo traducido resultante. Para +traductores del núcleo como dispositivos de cifrado del tipo +@code{luks-device-mapping}, especificar @code{"mi-particion"} produce la +creación del dispositivo @code{"/dev/mapper/mi-particion"}. Para +dispositivos RAID de tipo @code{raid-device-mapping}, el nombre del +dispositivo completo como @code{"/dev/md0"} debe ser proporcionado. + +@item type +Debe ser un objeto @code{mapped-device-kind}, que especifica cómo +@var{source} se traduce a @var{target}. +@end table +@end deftp + +@defvr {Variable Scheme} luks-device-mapping +Define el cifrado de bloques LUKS mediante el uso de la orden +@command{cryptsetup} del paquete del mismo nombre. Depende del módulo +@code{dm-crypt} del núcleo Linux. +@end defvr + +@defvr {Variable Scheme} raid-device-mapping +Define un dispositivo RAID, el cual se ensambla mediante el uso de la orden +@code{mdadm} del paquete del mismo nombre. Requiere la carga del módulo del +núcleo Linux para el nivel RAID apropiado, como @code{raid456} para RAID-4, +RAID-5 o RAID-6, o @code{raid10} para RAID-10. +@end defvr + +@cindex cifrado de disco +@cindex LUKS +El siguiente ejemplo especifica una traducción de @file{/dev/sda3} a +@file{/dev/mapper/home} mediante el uso de LUKS---la +@url{https://gitlab.com/cryptsetup/cryptsetup,configuración de claves +unificada de Linux}, un mecanismo estándar para cifrado de disco. El +dispositivo @file{/dev/mapper/home} puede usarse entonces como el campo +@code{device} de una declaración @code{file-system} (@pxref{Sistemas de ficheros}). + +@example +(mapped-device + (source "/dev/sda3") + (target "home") + (type luks-device-mapping)) +@end example + +De manera alternativa, para independizarse de la numeración de dispositivos, +puede obtenerse el UUID LUKS (@dfn{identificador único}) del dispositivo +fuente con una orden así: + +@example +cryptsetup luksUUID /dev/sda3 +@end example + +y usarlo como sigue: + +@example +(mapped-device + (source (uuid "cb67fc72-0d54-4c88-9d4b-b225f30b0f44")) + (target "home") + (type luks-device-mapping)) +@end example + +@cindex cifrado del intercambio +También es deseable cifrar el espacio de intercambio, puesto que el espacio +de intercambio puede contener información sensible. Una forma de conseguirlo +es usar un fichero de intercambio en un sistema de ficheros en un +dispositivo traducido a través del cifrado LUKS. @xref{Preparación para la instalación,,Particionado del disco}, para un ejemplo. + +Un dispositivo RAID formado por las particiones @file{/dev/sda1} y +@file{/dev/sdb1} puede declararse como se muestra a continuación: + +@example +(mapped-device + (source (list "/dev/sda1" "/dev/sdb1")) + (target "/dev/md0") + (type raid-device-mapping)) +@end example + +El dispositivo @file{/dev/md0} puede usarse entonces como el campo +@code{device} de una declaración @code{file-system} (@pxref{Sistemas de ficheros}). Fíjese que no necesita proporcionar el nivel RAID; se selecciona +durante la creación inicial y formato del dispositivo RAID y después se +determina automáticamente. + + +@node Cuentas de usuaria +@section Cuentas de usuaria + +@cindex usuarias +@cindex cuentas +@cindex cuentas de usuaria +Los grupos y cuentas de usuaria se gestionan completamente a través de la +declaración @code{operating-system}. Se especifican con las formas +@code{user-account} y @code{user-group}: + +@example +(user-account + (name "alicia") + (group "users") + (supplementary-groups '("wheel" ;permite usar sudo, etc. + "audio" ;tarjeta de sonido + "video" ;dispositivos de vídeo como cámaras + "cdrom")) ;el veterano CD-ROM + (comment "hermana de Roberto") + (home-directory "/home/alicia")) +@end example + +Durante el arranque o tras la finalización de @command{guix system +reconfigure}, el sistema se asegura de que únicamente las cuentas de usuaria +y grupos especificados en la declaración @code{operating-system} existen, y +con las propiedades especificadas. Por tanto, la creación o modificación de +cuentas o grupos realizadas directamente invocando órdenes como +@command{useradd} se pierden al reconfigurar o reiniciar el sistema. Esto +asegura que el sistema permanece exactamente como se declaró. + +@deftp {Tipo de datos} user-account +Objetos de este tipo representan cuentas de usuaria. Los siguientes miembros +pueden ser especificados: + +@table @asis +@item @code{name} +El nombre de la cuenta de usuaria. + +@item @code{group} +@cindex grupos +Este es el nombre (una cadena) o identificador (un número) del grupo de +usuarias al que esta cuenta pertenece. + +@item @code{supplementary-groups} (predeterminados: @code{'()}) +Opcionalmente, esto puede definirse como una lista de nombres de grupo a los +que esta cuenta pertenece. + +@item @code{uid} (predeterminado: @code{#f}) +Este es el ID de usuaria para esta cuenta (un número), o @code{#f}. En el +último caso, un número es seleccionado automáticamente por el sistema cuando +la cuenta es creada. + +@item @code{comment} (predeterminado: @code{""}) +Un comentario sobre la cuenta, como el nombre completo de la propietaria. + +@item @code{home-directory} +Este es el nombre del directorio de usuaria de la cuenta. + +@item @code{create-home-directory?} (predeterminado: @code{#t}) +Indica si el directorio de usuaria de esta cuenta debe ser creado si no +existe todavía. + +@item @code{shell} (predeterminado: Bash) +Esto es una expresión-G denotando el nombre de fichero de un programa que +será usado como shell (@pxref{Expresiones-G}). + +@item @code{system?} (predeterminado: @code{#f}) +Este valor lógico indica si la cuenta es una cuenta ``del sistema''. Las +cuentas del sistema se tratan a veces de forma especial; por ejemplo, los +gestores gráficos de inicio no las enumeran. + +@anchor{user-account-password} +@cindex contraseña, para cuentas de usuaria +@item @code{password} (predeterminada: @code{#f}) +Normalmente debería dejar este campo a @code{#f}, inicializar la contraseña +de usuaria como @code{root} con la orden @command{passwd}, y entonces dejar +a las usuarias cambiarla con @command{passwd}. Las contraseñas establecidas +con @command{passwd} son, por supuesto, preservadas entre reinicios y +reconfiguraciones. + +If you @emph{do} want to set an initial password for an account, then this +field must contain the encrypted password, as a string. You can use the +@code{crypt} procedure for this purpose: + +@example +(user-account + (name "charlie") + (group "users") + + ;; Specify a SHA-512-hashed initial password. + (password (crypt "InitialPassword!" "$6$abc"))) +@end example + +@quotation Nota +The hash of this initial password will be available in a file in +@file{/gnu/store}, readable by all the users, so this method must be used +with care. +@end quotation + +@xref{Passphrase Storage,,, libc, The GNU C Library Reference Manual}, for +more information on password encryption, and @ref{Encryption,,, guile, GNU +Guile Reference Manual}, for information on Guile's @code{crypt} procedure. + +@end table +@end deftp + +@cindex grupos +Las declaraciones de grupos son más simples incluso: + +@example +(user-group (name "estudiantes")) +@end example + +@deftp {Tipo de datos} user-group +Este tipo es para grupos de usuarias. Hay únicamente unos pocos campos: + +@table @asis +@item @code{name} +En nombre del grupo. + +@item @code{id} (predeterminado: @code{#f}) +El identificador del grupo (un número). Si es @code{#f}, un nuevo número es +reservado automáticamente cuando se crea el grupo. + +@item @code{system?} (predeterminado: @code{#f}) +Este valor booleano indica si el grupo es un grupo ``del sistema''. Los +grupos del sistema tienen identificadores numéricos bajos. + +@item @code{password} (predeterminada: @code{#f}) +¿Qué? ¿Los grupos de usuarias pueden tener una contraseña? Bueno, +aparentemente sí. A menos que sea @code{#f}, este campo especifica la +contraseña del grupo. + +@end table +@end deftp + +Por conveniencia, una variable contiene una lista con todos los grupos de +usuarias básicos que se puede esperar: + +@defvr {Variable Scheme} %base-groups +Esta es la lista de grupos de usuarias básicos que las usuarias y/o los +paquetes esperan que estén presentes en el sistema. Esto incluye grupos como +``root'', ``wheel'' y ``users'', así como grupos usados para controlar el +acceso a dispositivos específicos como ``audio'', ``disk'' y ``cdrom''. +@end defvr + +@defvr {Variable Scheme} %base-user-accounts +Esta es la lista de cuentas de usuaria básicas que los programas pueden +esperar encontrar en un sistema GNU/Linux, como la cuenta ``nobody''. + +Fíjese que la cuenta de ``root'' no se incluye aquí. Es un caso especial y +se añade automáticamente esté o no especificada. +@end defvr + +@node Distribución de teclado +@section Distribución de teclado + +@cindex distribución de teclado +@cindex mapa del teclas +To specify what each key of your keyboard does, you need to tell the +operating system what @dfn{keyboard layout} you want to use. The default, +when nothing is specified, is the US English QWERTY layout for 105-key PC +keyboards. However, German speakers will usually prefer the German QWERTZ +layout, French speakers will want the AZERTY layout, and so on; hackers +might prefer Dvorak or bépo, and they might even want to further customize +the effect of some of the keys. This section explains how to get that done. + +@cindex distribución de teclado, definición +There are three components that will want to know about your keyboard +layout: + +@itemize +@item +The @emph{bootloader} may want to know what keyboard layout you want to use +(@pxref{Configuración del gestor de arranque, @code{keyboard-layout}}). This is useful +if you want, for instance, to make sure that you can type the passphrase of +your encrypted root partition using the right layout. + +@item +The @emph{operating system kernel}, Linux, will need that so that the +console is properly configured (@pxref{Referencia de ``operating-system'', +@code{keyboard-layout}}). + +@item +The @emph{graphical display server}, usually Xorg, also has its own idea of +the keyboard layout (@pxref{Sistema X Window, @code{keyboard-layout}}). +@end itemize + +Guix allows you to configure all three separately but, fortunately, it +allows you to share the same keyboard layout for all three components. + +@cindex XKB, distribuciones de teclado +Keyboard layouts are represented by records created by the +@code{keyboard-layout} procedure of @code{(gnu system keyboard)}. Following +the X Keyboard extension (XKB), each layout has four attributes: a name +(often a language code such as ``fi'' for Finnish or ``jp'' for Japanese), +an optional variant name, an optional keyboard model name, and a possibly +empty list of additional options. In most cases the layout name is all you +care about. Here are a few example: + +@example +;; The German QWERTZ layout. Here we assume a standard +;; "pc105" keyboard model. +(keyboard-layout "de") + +;; The bépo variant of the French layout. +(keyboard-layout "fr" "bepo") + +;; The Catalan layout. +(keyboard-layout "es" "cat") + +;; The Latin American Spanish layout. In addition, the +;; "Caps Lock" key is used as an additional "Ctrl" key, +;; and the "Menu" key is used as a "Compose" key to enter +;; accented letters. +(keyboard-layout "latam" + #:options '("ctrl:nocaps" "compose:menu")) + +;; The Russian layout for a ThinkPad keyboard. +(keyboard-layout "ru" #:model "thinkpad") + +;; The "US international" layout, which is the US layout plus +;; dead keys to enter accented characters. This is for an +;; Apple MacBook keyboard. +(keyboard-layout "us" "intl" #:model "macbook78") +@end example + +See the @file{share/X11/xkb} directory of the @code{xkeyboard-config} +package for a complete list of supported layouts, variants, and models. + +@cindex distribución de teclado, configuración +Let's say you want your system to use the Turkish keyboard layout throughout +your system---bootloader, console, and Xorg. Here's what your system +configuration would look like: + +@findex set-xorg-configuration +@lisp +;; Using the Turkish layout for the bootloader, the console, +;; and for Xorg. + +(operating-system + ;; ... + (keyboard-layout (keyboard-layout "tr")) ;for the console + (bootloader (bootloader-configuration + (bootloader grub-efi-bootloader) + (target "/boot/efi") + (keyboard-layout keyboard-layout))) ;for GRUB + (services (cons (set-xorg-configuration + (xorg-configuration ;for Xorg + (keyboard-layout keyboard-layout))) + %desktop-services))) +@end lisp + +In the example above, for GRUB and for Xorg, we just refer to the +@code{keyboard-layout} field defined above, but we could just as well refer +to a different layout. The @code{set-xorg-configuration} procedure +communicates the desired Xorg configuration to the graphical log-in manager, +by default GDM. + +We've discussed how to specify the @emph{default} keyboard layout of your +system when it starts, but you can also adjust it at run time: + +@itemize +@item +If you're using GNOME, its settings panel has a ``Region & Language'' entry +where you can select one or more keyboard layouts. + +@item +Under Xorg, the @command{setxkbmap} command (from the same-named package) +allows you to change the current layout. For example, this is how you would +change the layout to US Dvorak: + +@example +setxkbmap us dvorak +@end example + +@item +The @code{loadkeys} command changes the keyboard layout in effect in the +Linux console. However, note that @code{loadkeys} does @emph{not} use the +XKB keyboard layout categorization described above. The command below loads +the French bépo layout: + +@example +loadkeys fr-bepo +@end example +@end itemize + +@node Localizaciones +@section Localizaciones + +@cindex localización +Una @dfn{localización} define convenciones culturales para una lengua y +región del mundo particular (@pxref{Localizaciones,,, libc, The GNU C Library +Reference Manual}). Cada localización tiene un nombre que típicamente tiene +la forma de @code{@var{lengua}_@var{territorio}.@var{codificación}}---por +ejemplo, @code{fr_LU.utf8} designa la localización para la lengua francesa, +con las convenciones culturales de Luxemburgo, usando la codificación UTF-8. + +@cindex definición de localización +Normalmente deseará especificar la localización predeterminada para la +máquina usando el campo @code{locale} de la declaración +@code{operating-system} (@pxref{Referencia de ``operating-system'', @code{locale}}). + +La localización seleccionada es automáticamente añadida a las +@dfn{definiciones de localización} conocidas en el sistema si es necesario, +con su codificación inferida de su nombre---por ejemplo, se asume que +@code{bo_CN.utf8} usa la codificación @code{UTF-8}. Definiciones de +localización adicionales pueden ser especificadas en el campo +@code{locale-definitions} de @code{operating-system}---esto es util, por +ejemplo, si la codificación no puede ser inferida del nombre de la +localización. El conjunto predeterminado de definiciones de localización +incluye algunas localizaciones ampliamente usadas, pero no todas las +disponibles, para ahorrar espacio. + +Por ejemplo, para añadir la localización del frisio del norte para Alemania, +el valor de dicho campo puede ser: + +@example +(cons (locale-definition + (name "fy_DE.utf8") (source "fy_DE")) + %default-locale-definitions) +@end example + +De mismo modo, para ahorrar espacio, se puede desear que +@code{locale-definitions} contenga únicamente las localizaciones que son +realmente usadas, como en: + +@example +(list (locale-definition + (name "ja_JP.eucjp") (source "ja_JP") + (charset "EUC-JP"))) +@end example + +@vindex LOCPATH +Las definiciones de localización compiladas están disponibles en +@file{/run/current-system/locale/X.Y}, donde @code{X.Y} es la versión de +libc, que es la ruta donde la GNU@tie{}libc contenida en Guix buscará los +datos de localización. Esto puede ser sobreescrito usando la variable de +entorno @code{LOCPATH} (@pxref{locales-and-locpath, @code{LOCPATH} and +locale packages}). + +La forma @code{locale-definition} es proporcionada por el módulo @code{(gnu +system locale)}. Los detalles se proporcionan a continuación. + +@deftp {Tipo de datos} locale-definition +Este es el tipo de datos de una definición de localización. + +@table @asis + +@item @code{name} +El nombre de la localización. @xref{Locale Names,,, libc, The GNU C Library +Reference Manual}, para más información sobre nombres de localizaciones. + +@item @code{source} +El nombre de la fuente para dicha localización. Esto típicamente es la parte +@code{@var{idioma}_@var{territorio}} del nombre de localización. + +@item @code{charset} (predeterminado: @code{"UTF-8"}) +La ``codificación de caracteres'' o ``conjunto de caracteres'' para dicha +localización, @uref{http://www.iana.org/assignments/character-sets, como se +define por IANA}. + +@end table +@end deftp + +@defvr {Variable Scheme} %default-locale-definitions +Una lista de localizaciones UTF-8 usadas de forma común, usada como valor +predeterminado del campo @code{locale-definitions} en las declaraciones +@code{operating-system}. + +@cindex nombre de localización +@cindex codificación normalizada en los nombres de localizaciones +Estas definiciones de localizaciones usan la @dfn{codificación normalizada} +para el fragmento tras el punto en el nombre (@pxref{Using gettextized +software, normalized codeset,, libc, The GNU C Library Reference +Manual}). Por lo que por ejemplo es válido @code{uk_UA.utf8} pero @emph{no}, +digamos, @code{uk_UA.UTF-8}. +@end defvr + +@subsection Consideraciones sobre la compatibilidad de datos de localización + +@cindex incompatibilidad, de datos de localización +Las declaraciones @code{operating-system} proporcionan un campo +@code{locale-libcs} para especificar los paquetes GNU@tie{}libc que se +usarán para compilar las declaraciones de localizaciones +(@pxref{Referencia de ``operating-system''}). ``¿Por qué debo preocuparme?'', puede +preguntarse. Bueno, sucede que el formato binario de los datos de +localización es ocasionalmente incompatible de una versión de libc a otra. + +@c See <https://sourceware.org/ml/libc-alpha/2015-09/msg00575.html> +@c and <https://lists.gnu.org/archive/html/guix-devel/2015-08/msg00737.html>. +Por ejemplo, un programa enlazado con la versión 2.21 de libc no puede leer +datos de localización producidos con libc 2.22; peor aún, ese programa +@emph{aborta} en vez de simplemente ignorar los datos de localización +incompatibles@footnote{Las versiones 2.23 y posteriores de GNU@tie{}libc +simplemente ignorarán los datos de localización incompatibles, lo cual ya es +un avance.}. De manera similar, un programa enlazado con libc 2.22 puede +leer la mayor parte, pero no todo, de los datos de localización de libc 2.21 +(específicamente, los datos @code{LC_COLLATE} son incompatibles); por tanto +las llamadas a @code{setlocale} pueden fallar, pero los programas no +abortarán. + +El ``problema'' con Guix es que las usuarias tienen mucha libertad: pueden +elegir cuando e incluso si actualizar el software en sus perfiles, y pueden +estar usando una versión de libc diferente de la que la administradora del +sistema usó para construir los datos de localización comunes a todo el +sistema. + +Por suerte, las usuarias sin privilegios también pueden instalar sus propios +datos de localización y definir @var{GUIX_LOCPATH} adecuadamente +(@pxref{locales-and-locpath, @code{GUIX_LOCPATH} y paquetes de +localizaciones}). + +No obstante, es mejor si los datos de localización globales del sistema en +@file{/run/current-system/locale} se construyen para todas las versiones de +libc realmente en uso en el sistema, de manera que todos los programas +puedan acceder a ellos---esto es especialmente crucial en un sistema +multiusuaria. Para hacerlo, la administradora puede especificar varios +paquetes libc en el campo @code{locale-libcs} de @code{operating-system}: + +@example +(use-package-modules base) + +(operating-system + ;; @dots{} + (locale-libcs (list glibc-2.21 (canonical-package glibc)))) +@end example + +Este ejemplo llevaría a un sistema que contiene definiciones de localización +tanto para libc 2.21 como para la versión actual de libc en +@file{/run/current-system/locale}. + + +@node Servicios +@section Servicios + +@cindex servicios del sistema +Una parte importante de la preparación de una declaración +@code{operating-system} es listar los @dfn{servicios del sistema} y su +configuración (@pxref{Uso de la configuración del sistema}). Los servicios del +sistema típicamente son daemon lanzados cuando el sistema arrancha, u otras +acciones necesarias en ese momento---por ejemplo, configurar el acceso de +red. + +Guix has a broad definition of ``service'' (@pxref{Composición de servicios}), +but many services are managed by the GNU@tie{}Shepherd (@pxref{Servicios de Shepherd}). On a running system, the @command{herd} command allows you to +list the available services, show their status, start and stop them, or do +other specific operations (@pxref{Jump Start,,, shepherd, The GNU Shepherd +Manual}). For example: + +@example +# herd status +@end example + +La orden previa, ejecutada como @code{root}, enumera los servicios +actualmente definidos. La orden @command{herd doc} muestra una sinopsis del +servicio proporcionado y sus acciones asociadas: + +@example +# herd doc nscd +Run libc's name service cache daemon (nscd). + +# herd doc nscd action invalidate +invalidate: Invalidate the given cache--e.g., 'hosts' for host name lookups. +@end example + +Las ordenes internas @command{start}, @command{stop} y @command{restart} +tienen el efecto de arrancar, parar y reiniciar el servicio, +respectivamente. Por ejemplo, las siguientes órdenes paran el servicio nscd +y reinician el servidor gráfico Xorg: + +@example +# herd stop nscd +Service nscd has been stopped. +# herd restart xorg-server +Service xorg-server has been stopped. +Service xorg-server has been started. +@end example + +Las siguientes secciones documentan los servicios disponibles, comenzando +con los servicios básicos, que pueden ser usados en una declaración +@code{operating-system}. + +@menu +* Servicios base:: Servicios esenciales del sistema. +* Ejecución de tareas programadas:: El servicio mcron. +* Rotación de logs:: El servicio rottlog. +* Servicios de red:: Configuración de red, daemon SSH, etc. +* Sistema X Window:: Interfaz gráfica. +* Servicios de impresión:: Soporte de impresoras locales y remotas. +* Servicios de escritorio:: D-Bus y servicios de escritorio. +* Servicios de sonido:: Servicios de ALSA y Pulseaudio. +* Servicios de bases de datos:: Bases de datos SQL, almacenes de + clave-valor, etc. +* Servicios de correo:: IMAP, POP3, SMTP y todo eso. +* Servicios de mensajería:: Servicios de mensajería. +* Servicios de telefonía:: Servicios de telefonía. +* Servicios de monitorización:: Servicios de monitorización. +* Servicios Kerberos:: Servicios Kerberos. +* Servicios LDAP:: Servicios LDAP. +* Servicios Web:: Servidores Web. +* Servicios de certificados:: Certificados TLS via Let's Encrypt. +* Servicios DNS:: Demonios DNS. +* Servicios VPN:: Demonios VPN. +* Sistema de ficheros en red:: Servicios relacionados con NFS. +* Integración continua:: El servicio Cuirass. +* Servicios de gestión de energía:: Extender la vida de la batería. +* Servicios de audio:: El MPD. +* Servicios de virtualización:: Servicios de virtualización. +* Servicios de control de versiones:: Proporcionar acceso remoto a + repositorios Git. +* Servicios de juegos:: Servidores de juegos. +* Servicios misceláneos:: Otros servicios. +@end menu + +@node Servicios base +@subsection Servicios base + +El módulo @code{(gnu services base)} proporciona definiciones para los +servicios básicos que se esperan en el sistema. Los servicios exportados por +este módulo se enumeran a continuación. + +@defvr {Variable Scheme} %base-services +Esta variable contiene una lista de servicios básicos (@pxref{Tipos de servicios y servicios}, para más información sobre los objetos servicio) que se +pueden esperar en el sistema: un servicio de ingreso al sistema (mingetty) +en cada tty, syslogd, el daemon de la caché del servicio de nombres (nscd), +el gestor de dispositivos udev, y más. + +Este es el valor predeterminado del campo @code{services} de las +declaraciones @code{operating-system}. De manera habitual, cuando se +personaliza el sistema, es deseable agregar servicios a +@var{%base-services}, de esta forma: + +@example +(append (list (service avahi-service-type) + (service openssh-service-type)) + %base-services) +@end example +@end defvr + +@defvr {Variable Scheme} special-files-service-type +El servicio que establece ``ficheros especiales'' como @file{/bin/sh}; una +instancia suya es parte de @code{%base-services}. + +El valor asociado con servicios @code{special-file-service-type} debe ser +una lista de tuplas donde el primer elemento es el ``fichero especial'' y el +segundo elemento es su destino. El valor predeterminado es: + +@cindex @file{/bin/sh} +@cindex @file{sh}, en @file{/bin} +@example +`(("/bin/sh" ,(file-append @var{bash} "/bin/sh"))) +@end example + +@cindex @file{/usr/bin/env} +@cindex @file{env}, en @file{/usr/bin} +Si quiere añadir, digamos, @code{/usr/bin/env} a su sistema, puede cambiar +su valor por: + +@example +`(("/bin/sh" ,(file-append @var{bash} "/bin/sh")) + ("/usr/bin/env" ,(file-append @var{coreutils} "/bin/env"))) +@end example + +Ya que es parte de @code{%base-services}, puede usar @code{modify-services} +para personalizar el conjunto de ficheros especiales (@pxref{Referencia de servicios, @code{modify-services}}). Pero una forma simple de añadir un +fichero especial es usar el procedimiento @code{extra-special-file} (véase a +continuación). +@end defvr + +@deffn {Procedimiento Scheme} extra-special-file @var{fichero} @var{destino} +Usa @var{destino} como el ``fichero especial'' @var{fichero}. + +Por ejemplo, la adición de las siguientes líneas al campo @code{services} de +su declaración de sistema operativo genera @file{/usr/bin/env} como un +enlace simbólico: + +@example +(extra-special-file "/usr/bin/env" + (file-append coreutils "/bin/env")) +@end example +@end deffn + +@deffn {Procedimiento Scheme} host-name-service @var{nombre} +Devuelve un servicio que establece el nombre de máquina a @var{nombre}. +@end deffn + +@deffn {Procedimiento Scheme} login-service @var{config} +Devuelve un servicio para ejecutar el ingreso al sistema de acuerdo con +@var{config}, un objeto @code{<login-configuration>}, que especifica el +mensaje del día, entre otras cosas. +@end deffn + +@deftp {Tipo de datos} login-configuration +Este es el tipo de datos que representa la configuración del ingreso al +sistema. + +@table @asis + +@item @code{motd} +@cindex mensaje del día +Un objeto tipo-fichero que contiene el ``mensaje del día''. + +@item @code{allow-empty-passwords?} (predeterminado: @code{#t}) +Permite contraseñas vacías por defecto para que las primeras usuarias puedan +ingresar en el sistema cuando la cuenta de ``root'' está recién creada. + +@end table +@end deftp + +@deffn {Procedimiento Scheme} mingetty-service @var{config} +Devuelve un servicio para ejecutar mingetty de acuerdo con @var{config}, un +objeto @code{<mingetty-configuration>}, que especifica el tty a ejecutar +entre otras cosas. +@end deffn + +@deftp {Tipo de datos} mingetty-configuration +Este es el tipo de datos que representa la configuración de Mingetty, el +cual proporciona la implementación predeterminada de ingreso al sistema en +las consolas virtuales. + +@table @asis + +@item @code{tty} +El sistema de la consola en la que se ejecuta este Mingetty---por ejemplo, +@code{"tty1"}. + +@item @code{auto-login} (predeterminado: @code{#f}) +Cuando sea verdadero, este campo debe ser una cadena que denote el nombre de +usuaria bajo el cual el sistema ingresa automáticamente. Cuando es +@code{#f}, se deben proporcionar un nombre de usuaria y una contraseña para +ingresar en el sistema. + +@item @code{login-program} (predeterminado: @code{#f}) +Debe ser @code{#f}, en cuyo caso se usa el programa predeterminado de +ingreso al sistema (@command{login} de las herramientas Shadow), o una +expresión-G que determine el nombre del programa de ingreso al sistema. + +@item @code{login-pause?} (predeterminado: @code{#f}) +Cuando es @code{#t} en conjunción con @var{auto-login}, la usuaria deberá +presionar una tecla para lanzar el shell de ingreso al sistema. + +@item @code{mingetty} (predeterminado: @var{mingetty}) +El paquete Mingetty usado. + +@end table +@end deftp + +@deffn {Procedure Scheme} agetty-service @var{config} +Devuelve un servicio para ejecutar agetty de acuerdo con @var{config}, un +objeto @code{<agetty-configuration>}, que especifica el tty a ejecutar entre +otras cosas.< +@end deffn + +@deftp {Tipo de datos} agetty-configuration +Este es el tipo de datos que representa la configuración de agetty, que +implementa el ingreso al sistema en las consolas virtuales y serie. Véase la +página de manual @code{agetty(8)} para más información. + +@table @asis + +@item @code{tty} +The name of the console this agetty runs on, as a string---e.g., +@code{"ttyS0"}. This argument is optional, it will default to a reasonable +default serial port used by the kernel Linux. + +For this, if there is a value for an option @code{agetty.tty} in the kernel +command line, agetty will extract the device name of the serial port from it +and use that. + +If not and if there is a value for an option @code{console} with a tty in +the Linux command line, agetty will extract the device name of the serial +port from it and use that. + +In both cases, agetty will leave the other serial device settings (baud rate +etc.)@: alone---in the hope that Linux pinned them to the correct values. + +@item @code{baud-rate} (predeterminado: @code{#f}) +A string containing a comma-separated list of one or more baud rates, in +descending order. + +@item @code{term} (predeterminado: @code{#f}) +A string containing the value used for the @code{TERM} environment variable. + +@item @code{eight-bits?} (predeterminado: @code{#f}) +When @code{#t}, the tty is assumed to be 8-bit clean, and parity detection +is disabled. + +@item @code{auto-login} (predeterminado: @code{#f}) +When passed a login name, as a string, the specified user will be logged in +automatically without prompting for their login name or password. + +@item @code{no-reset?} (predeterminado: @code{#f}) +When @code{#t}, don't reset terminal cflags (control modes). + +@item @code{host} (predeterminado: @code{#f}) +This accepts a string containing the "login_host", which will be written +into the @file{/var/run/utmpx} file. + +@item @code{remote?} (predeterminado: @code{#f}) +When set to @code{#t} in conjunction with @var{host}, this will add an +@code{-r} fakehost option to the command line of the login program specified +in @var{login-program}. + +@item @code{flow-control?} (predeterminado: @code{#f}) +When set to @code{#t}, enable hardware (RTS/CTS) flow control. + +@item @code{no-issue?} (predeterminado: @code{#f}) +When set to @code{#t}, the contents of the @file{/etc/issue} file will not +be displayed before presenting the login prompt. + +@item @code{init-string} (predeterminada: @code{#f}) +This accepts a string that will be sent to the tty or modem before sending +anything else. It can be used to initialize a modem. + +@item @code{no-clear?} (predeterminado: @code{#f}) +When set to @code{#t}, agetty will not clear the screen before showing the +login prompt. + +@item @code{login-program} (predeterminado: (file-append shadow "/bin/login")) +This must be either a gexp denoting the name of a log-in program, or unset, +in which case the default value is the @command{login} from the Shadow tool +suite. + +@item @code{local-line} (predeterminado: @code{#f}) +Control the CLOCAL line flag. This accepts one of three symbols as +arguments, @code{'auto}, @code{'always}, or @code{'never}. If @code{#f}, the +default value chosen by agetty is @code{'auto}. + +@item @code{extract-baud?} (predeterminado: @code{#f}) +When set to @code{#t}, instruct agetty to try to extract the baud rate from +the status messages produced by certain types of modems. + +@item @code{skip-login?} (predeterminado: @code{#f}) +When set to @code{#t}, do not prompt the user for a login name. This can be +used with @var{login-program} field to use non-standard login systems. + +@item @code{no-newline?} (predeterminado: @code{#f}) +When set to @code{#t}, do not print a newline before printing the +@file{/etc/issue} file. + +@c Is this dangerous only when used with login-program, or always? +@item @code{login-options} (predeterminadas: @code{#f}) +This option accepts a string containing options that are passed to the login +program. When used with the @var{login-program}, be aware that a malicious +user could try to enter a login name containing embedded options that could +be parsed by the login program. + +@item @code{login-pause} (predeterminada: @code{#f}) +When set to @code{#t}, wait for any key before showing the login prompt. +This can be used in conjunction with @var{auto-login} to save memory by +lazily spawning shells. + +@item @code{chroot} (predeterminado: @code{#f}) +Change root to the specified directory. This option accepts a directory +path as a string. + +@item @code{hangup?} (predeterminado: @code{#f}) +Use the Linux system call @code{vhangup} to do a virtual hangup of the +specified terminal. + +@item @code{keep-baud?} (predeterminado: @code{#f}) +When set to @code{#t}, try to keep the existing baud rate. The baud rates +from @var{baud-rate} are used when agetty receives a @key{BREAK} character. + +@item @code{timeout} (predeterminado: @code{#f}) +When set to an integer value, terminate if no user name could be read within +@var{timeout} seconds. + +@item @code{detect-case?} (predeterminado: @code{#f}) +When set to @code{#t}, turn on support for detecting an uppercase-only +terminal. This setting will detect a login name containing only uppercase +letters as indicating an uppercase-only terminal and turn on some +upper-to-lower case conversions. Note that this will not support Unicode +characters. + +@item @code{wait-cr?} (predeterminado: @code{#f}) +When set to @code{#t}, wait for the user or modem to send a carriage-return +or linefeed character before displaying @file{/etc/issue} or login prompt. +This is typically used with the @var{init-string} option. + +@item @code{no-hints?} (predeterminado: @code{#f}) +When set to @code{#t}, do not print hints about Num, Caps, and Scroll locks. + +@item @code{no-hostname?} (predeterminado: @code{#f}) +By default, the hostname is printed. When this option is set to @code{#t}, +no hostname will be shown at all. + +@item @code{long-hostname?} (predeterminado: @code{#f}) +By default, the hostname is only printed until the first dot. When this +option is set to @code{#t}, the fully qualified hostname by +@code{gethostname} or @code{getaddrinfo} is shown. + +@item @code{erase-characters} (predeterminado: @code{#f}) +This option accepts a string of additional characters that should be +interpreted as backspace when the user types their login name. + +@item @code{kill-characters} (predeterminado: @code{#f}) +This option accepts a string that should be interpreted to mean "ignore all +previous characters" (also called a "kill" character) when the types their +login name. + +@item @code{chdir} (predeterminado: @code{#f}) +This option accepts, as a string, a directory path that will be changed to +before login. + +@item @code{delay} (predeterminado: @code{#f}) +This options accepts, as an integer, the number of seconds to sleep before +opening the tty and displaying the login prompt. + +@item @code{nice} (predeterminado: @code{#f}) +This option accepts, as an integer, the nice value with which to run the +@command{login} program. + +@item @code{extra-options} (predeterminadas: @code{'()}) +This option provides an "escape hatch" for the user to provide arbitrary +command-line arguments to @command{agetty} as a list of strings. + +@end table +@end deftp + +@deffn {Procedimiento Scheme} kmscon-service-type @var{config} +Return a service to run +@uref{https://www.freedesktop.org/wiki/Software/kmscon,kmscon} according to +@var{config}, a @code{<kmscon-configuration>} object, which specifies the +tty to run, among other things. +@end deffn + +@deftp {Tipo de datos} kmscon-configuration +Este es el tipo de datos que representa la configuración de Kmscon, que +implementa el ingreso al sistema en consolas virtuales. + +@table @asis + +@item @code{virtual-terminal} +El sistema de la consola en la que se ejecuta este Kmscon---por ejemplo, +@code{"tty1"}. + +@item @code{login-program} (predeterminado: @code{#~(string-append #$shadow "/bin/login")}) +A gexp denoting the name of the log-in program. The default log-in program +is @command{login} from the Shadow tool suite. + +@item @code{login-arguments} (predeterminados: @code{'("-p")}) +A list of arguments to pass to @command{login}. + +@item @code{auto-login} (predeterminado: @code{#f}) +When passed a login name, as a string, the specified user will be logged in +automatically without prompting for their login name or password. + +@item @code{hardware-acceleration?} (predeterminado: #f) +Determina si se usará aceleración hardware. + +@item @code{kmscon} (predeterminado: @var{kmscon}) +El paquete Kmscon usado. + +@end table +@end deftp + +@cindex daemon de caché del servicio de nombres +@cindex nscd +@deffn {Procedimiento Scheme} nscd-service [@var{configuración}] [#:glibc glibc] @ + [#:name-services '()] +Devuelve un servicio que ejecuta el daemon de la caché del servicio de +nombres (nscd) con la @var{configuración} proporcionada---un objeto +@code{<nscd-configuration>}. @xref{Selector de servicios de nombres}, para un ejemplo. + +Por conveniencia, el servicio ncsd de Shepherd proporciona las siguientes +acciones: + +@table @code +@item invalidate +@cindex invalidación de caché, nscd +@cindex nscd, invalidación de caché +Esto invalida la caché dada. Por ejemplo, ejecutar: + +@example +herd invalidate nscd hosts +@end example + +@noindent +invalida la caché de búsqueda de nombres de máquinas de nscd. + +@item statistics +Ejecutar @command{herd statistics nscd} muestra información del uso nscd y +la caché. +@end table + +@end deffn + +@defvr {Variable Scheme} %nscd-default-configuration +This is the default @code{<nscd-configuration>} value (see below) used by +@code{nscd-service}. It uses the caches defined by +@var{%nscd-default-caches}; see below. +@end defvr + +@deftp {Tipo de datos} nscd-configuration +Este tipo de datos representa la configuración del daemon de caché del +servicio de nombres (nscd). + +@table @asis + +@item @code{name-services} (predeterminados: @code{'()}) +List of packages denoting @dfn{name services} that must be visible to the +nscd---e.g., @code{(list @var{nss-mdns})}. + +@item @code{glibc} (predeterminada: @var{glibc}) +Package object denoting the GNU C Library providing the @command{nscd} +command. + +@item @code{log-file} (predeterminado: @code{"/var/log/nscd.log"}) +Name of the nscd log file. This is where debugging output goes when +@code{debug-level} is strictly positive. + +@item @code{debug-level} (predeterminado: @code{0}) +Integer denoting the debugging levels. Higher numbers mean that more +debugging output is logged. + +@item @code{caches} (predeterminadas: @var{%nscd-default-caches}) +List of @code{<nscd-cache>} objects denoting things to be cached; see below. + +@end table +@end deftp + +@deftp {Tipo de datos} nscd-cache +Tipo de datos que representa una base de datos de caché de nscd y sus +parámetros. + +@table @asis + +@item @code{base de datos} +This is a symbol representing the name of the database to be cached. Valid +values are @code{passwd}, @code{group}, @code{hosts}, and @code{services}, +which designate the corresponding NSS database (@pxref{NSS Basics,,, libc, +The GNU C Library Reference Manual}). + +@item @code{positive-time-to-live} +@itemx @code{negative-time-to-live} (predeterminado: @code{20}) +A number representing the number of seconds during which a positive or +negative lookup result remains in cache. + +@item @code{check-files?} (predeterminado: @code{#t}) +Whether to check for updates of the files corresponding to @var{database}. + +For instance, when @var{database} is @code{hosts}, setting this flag +instructs nscd to check for updates in @file{/etc/hosts} and to take them +into account. + +@item @code{persistent?} (predeterminada: @code{#t}) +Whether the cache should be stored persistently on disk. + +@item @code{shared?} (predeterminado: @code{#t}) +Whether the cache should be shared among users. + +@item @code{max-database-size} (predeterminado: 32@tie{}MiB) +Maximum size in bytes of the database cache. + +@c XXX: 'suggested-size' and 'auto-propagate?' seem to be expert +@c settings, so leave them out. + +@end table +@end deftp + +@defvr {Variable Scheme} %nscd-default-caches +List of @code{<nscd-cache>} objects used by default by +@code{nscd-configuration} (see above). + +It enables persistent and aggressive caching of service and host name +lookups. The latter provides better host name lookup performance, +resilience in the face of unreliable name servers, and also better +privacy---often the result of host name lookups is in local cache, so +external name servers do not even need to be queried. +@end defvr + +@anchor{syslog-configuration-type} +@cindex syslog +@cindex logging +@deftp {Tipo de datos} syslog-configuration +Este tipo de datos representa la configuración del daemon syslog. + +@table @asis +@item @code{syslogd} (predeterminado: @code{#~(string-append #$inetutils "/libexec/syslogd")}) +El daemon syslog usado. + +@item @code{config-file} (predeterminado: @code{%default-syslog.conf}) +El fichero de configuración de syslog usado. + +@end table +@end deftp + +@anchor{syslog-service} +@cindex syslog +@deffn {Procedimiento Scheme} syslog-service @var{config} +Return a service that runs a syslog daemon according to @var{config}. + +@xref{syslogd invocation,,, inetutils, GNU Inetutils}, para más información +sobre la sintaxis del fichero de configuración. +@end deffn + +@defvr {Variable Scheme} guix-service-type +This is the type of the service that runs the build daemon, +@command{guix-daemon} (@pxref{Invocación de guix-daemon}). Its value must be a +@code{guix-configuration} record as described below. +@end defvr + +@anchor{guix-configuration-type} +@deftp {Tipo de datos} guix-configuration +This data type represents the configuration of the Guix build daemon. +@xref{Invocación de guix-daemon}, for more information. + +@table @asis +@item @code{guix} (predeterminado: @var{guix}) +El paquete Guix usado. + +@item @code{build-group} (predeterminado: @code{"guixbuild"}) +El nombre del grupo de las cuentas de usuarias de construcción. + +@item @code{build-accounts} (predeterminadas: @code{10}) +Número de cuentas de usuarias de construcción a crear. + +@item @code{authorize-key?} (predeterminado: @code{#t}) +@cindex sustituciones, autorización de las mismas +Determina si se autoriza las claves de sustituciones listadas en +@code{authorized-keys}---predeterminada la de +@code{@value{SUBSTITUTE-SERVER}} (@pxref{Sustituciones}). + +@vindex %default-authorized-guix-keys +@item @code{authorized-keys} (predeterminadas: @var{%default-authorized-guix-keys}) +La lista de ficheros de claves autorizadas para importaciones de archivos, +como una lista de expresiones-G que evalúan a cadenas (@pxref{Invocación de guix archive}). Por defecto, contiene las de @code{@value{SUBSTITUTE-SERVER}} +(@pxref{Sustituciones}). + +@item @code{use-substitutes?} (predeterminado: @code{#t}) +Determina si se usarán sustituciones. + +@item @code{substitute-urls} (predeterminado: @var{%default-substitute-urls}) +La lista de URLs donde se buscarán sustituciones por defecto. + +@item @code{max-silent-time} (predeterminado: @code{0}) +@itemx @code{timeout} (predeterminado: @code{0}) +The number of seconds of silence and the number of seconds of activity, +respectively, after which a build process times out. A value of zero +disables the timeout. + +@item @code{log-compression} (predeterminado: @code{'bzip2}) +El tipo de compresión usado en los log de construcción---o bien @code{gzip}, +o bien @code{bzip2} o @code{none}. + +@item @code{extra-options} (predeterminadas: @code{'()}) +Lista de opciones de línea de órdenes adicionales para +@command{guix-daemon}. + +@item @code{log-file} (predeterminado: @code{"/var/log/guix-daemon.log"}) +Fichero al que se escriben la salida estándar y la salida estándar de error +de @command{guix-daemon}. + +@item @code{http-proxy} (predeterminado: @code{#f}) +El proxy HTTP que se usa para la descarga de derivaciones de salida fija y +sustituciones. + +@item @code{tmpdir} (predeterminado: @code{#f}) +Una ruta de directorio donde @command{guix-daemon} realiza las +construcciones. + +@end table +@end deftp + +@deffn {Procedimiento Scheme} udev-service [#:udev @var{eudev} #:rules @code{'()}] +Run @var{udev}, which populates the @file{/dev} directory dynamically. udev +rules can be provided as a list of files through the @var{rules} variable. +The procedures @var{udev-rule} and @var{file->udev-rule} from @code{(gnu +services base)} simplify the creation of such rule files. +@end deffn + +@deffn {Procedimiento Scheme} udev-rule [@var{nombre-fichero} @var{contenido}] +Devuelve un fichero de reglas de udev con nombre @var{nombre-fichero} que +contiene las reglas definidas en el literal @var{contenido}. + +En el ejemplo siguiente se define una regla para un dispositivo USB que será +almacenada en el fichero @file{90-usb-cosa.rules}. Esta regla ejecuta un +script cuando se detecta un dispositivo USB con un identificador de producto +dado. + +@example +(define %regla-ejemplo-udev + (udev-rule + "90-usb-cosa.rules" + (string-append "ACTION==\"add\", SUBSYSTEM==\"usb\", " + "ATTR@{product@}==\"Ejemplo\", " + "RUN+=\"/ruta/al/ejecutable\""))) +@end example + +The @command{herd rules udev} command, as root, returns the name of the +directory containing all the active udev rules. +@end deffn + +Here we show how the default @var{udev-service} can be extended with it. + +@example +(operating-system + ;; @dots{} + (services + (modify-services %desktop-services + (udev-service-type config => + (udev-configuration (inherit config) + (rules (append (udev-configuration-rules config) + (list %regla-ejemplo-udev)))))))) +@end example + +@deffn {Procedimiento Scheme} file->udev-rule [@var{nombre-fichero} @var{fichero}] +Devuelve un fichero de udev con nombre @var{nombre-fichero} que contiene las +reglas definidas en @var{fichero}, un objeto tipo-fichero. + +El ejemplo siguiente muestra cómo podemos usar un fichero de reglas +existente. + +@example +(use-modules (guix download) ;para url-fetch + (guix packages) ;para origin + ;; @dots{}) + +(define %reglas-android-udev + (file->udev-rule + "51-android-udev.rules" + (let ((version "20170910")) + (origin + (method url-fetch) + (uri (string-append "https://raw.githubusercontent.com/M0Rf30/" + "android-udev-rules/" version "/51-android.rules")) + (sha256 + (base32 "0lmmagpyb6xsq6zcr2w1cyx9qmjqmajkvrdbhjx32gqf1d9is003")))))) +@end example +@end deffn + +Adicionalmente, las definiciones de paquete Gui pueden ser incluidas en +@var{rules} para extender las reglas udev con las definiciones encontradas +bajo su subdirectorio @file{lib/udev/rules.d}. En vez del ejemplo previo de +@var{file->udev-rule}, podíamos haber usado el paquete +@var{android-udev-rules} que existe en Guix en el módulo @code{(gnu packages +android)}. + +El siguiente ejemplo muestra cómo usar el paquete @var{android-udev-rules} +para que la herramienta de Android @command{adb} pueda detectar dispositivos +sin privilegios de root. También detalla como crear el grupo +@code{adbusers}, el cual se requiere para el funcionamiento correcto de las +reglas definidas dentro del paquete @var{android-udev-rules}. Para crear tal +grupo, debemos definirlo tanto como parte de @var{supplementary-groups} de +la declaración de nuestra cuenta de usuaria @var{user-account}, así como en +el campo @var{groups} del registro @var{operating-system}. + +@example +(use-modules (gnu packages android) ;para android-udev-rules + (gnu system shadow) ;para user-group + ;; @dots{}) + +(operating-system + ;; @dots{} + (users (cons (user-acount + ;; @dots{} + (supplementary-groups + '("adbusers" ;para adb + "wheel" "netdev" "audio" "video")) + ;; @dots{}))) + + (groups (cons (user-group (system? #t) (name "adbusers")) + %base-groups)) + + ;; @dots{} + + (services + (modify-services %desktop-services + (udev-service-type + config => + (udev-configuration (inherit config) + (rules (cons android-udev-rules + (udev-configuration-rules config)))))))) +@end example + +@defvr {Variable Scheme} urandom-seed-service-type +Save some entropy in @var{%random-seed-file} to seed @file{/dev/urandom} +when rebooting. It also tries to seed @file{/dev/urandom} from +@file{/dev/hwrng} while booting, if @file{/dev/hwrng} exists and is +readable. +@end defvr + +@defvr {Variable Scheme} %random-seed-file +This is the name of the file where some random bytes are saved by +@var{urandom-seed-service} to seed @file{/dev/urandom} when rebooting. It +defaults to @file{/var/lib/random-seed}. +@end defvr + +@cindex ratón +@cindex gpm +@defvr {Variable Scheme} gpm-service-type +This is the type of the service that runs GPM, the @dfn{general-purpose +mouse daemon}, which provides mouse support to the Linux console. GPM +allows users to use the mouse in the console, notably to select, copy, and +paste text. + +The value for services of this type must be a @code{gpm-configuration} (see +below). This service is not part of @var{%base-services}. +@end defvr + +@deftp {Tipo de datos} gpm-configuration +Tipo de datos que representa la configuración de GPM. + +@table @asis +@item @code{opciones} (predeterminadas: @code{%default-gpm-options}) +Command-line options passed to @command{gpm}. The default set of options +instruct @command{gpm} to listen to mouse events on @file{/dev/input/mice}. +@xref{Command Line,,, gpm, gpm manual}, for more information. + +@item @code{gpm} (predeterminado: @code{gpm}) +El paquete GPM usado. + +@end table +@end deftp + +@anchor{guix-publish-service-type} +@deffn {Variable Scheme} guix-publish-service-type +This is the service type for @command{guix publish} (@pxref{Invocación de guix publish}). Its value must be a @code{guix-configuration} object, as +described below. + +This assumes that @file{/etc/guix} already contains a signing key pair as +created by @command{guix archive --generate-key} (@pxref{Invocación de guix archive}). If that is not the case, the service will fail to start. +@end deffn + +@deftp {Tipo de datos} guix-publish-configuration +Tipo de datos que representa la configuración del servicio @code{guix +publish}. + +@table @asis +@item @code{guix} (predeterminado: @code{guix}) +El paquete Guix usado. + +@item @code{port} (predeterminado: @code{80}) +El puerto TCP en el que se esperan conexiones. + +@item @code{host} (predeterminado: @code{"localhost"}) +The host (and thus, network interface) to listen to. Use @code{"0.0.0.0"} +to listen on all the network interfaces. + +@item @code{compression-level} (predeterminado: @code{3}) +The gzip compression level at which substitutes are compressed. Use +@code{0} to disable compression altogether, and @code{9} to get the best +compression ratio at the expense of increased CPU usage. + +@item @code{nar-path} (predeterminado: @code{"nar"}) +The URL path at which ``nars'' can be fetched. @xref{Invocación de guix publish, +@code{--nar-path}}, for details. + +@item @code{cache} (predeterminado: @code{#f}) +When it is @code{#f}, disable caching and instead generate archives on +demand. Otherwise, this should be the name of a directory---e.g., +@code{"/var/cache/guix/publish"}---where @command{guix publish} caches +archives and meta-data ready to be sent. @xref{Invocación de guix publish, +@option{--cache}}, for more information on the tradeoffs involved. + +@item @code{workers} (predeterminado: @code{#f}) +When it is an integer, this is the number of worker threads used for +caching; when @code{#f}, the number of processors is used. @xref{Invocación de guix publish, @option{--workers}}, for more information. + +@item @code{ttl} (predeterminado: @code{#f}) +When it is an integer, this denotes the @dfn{time-to-live} in seconds of the +published archives. @xref{Invocación de guix publish, @option{--ttl}}, for more +information. +@end table +@end deftp + +@anchor{rngd-service} +@deffn {Procedimiento Scheme} rngd-service [#:rng-tools @var{rng-tools}] @ + [#:device "/dev/hwrng"] Return a service that runs the @command{rngd} +program from @var{rng-tools} to add @var{device} to the kernel's entropy +pool. The service will fail if @var{device} does not exist. +@end deffn + +@anchor{pam-limits-service} +@cindex límites por sesión +@cindex ulimit +@cindex prioridad +@cindex tiempo real +@cindex jackd +@deffn {Procedimiento Scheme} pam-limits-service [#:limits @code{'()}] + +Return a service that installs a configuration file for the +@uref{http://linux-pam.org/Linux-PAM-html/sag-pam_limits.html, +@code{pam_limits} module}. The procedure optionally takes a list of +@code{pam-limits-entry} values, which can be used to specify @code{ulimit} +limits and nice priority limits to user sessions. + +The following limits definition sets two hard and soft limits for all login +sessions of users in the @code{realtime} group: + +@example +(pam-limits-service + (list + (pam-limits-entry "@@realtime" 'both 'rtprio 99) + (pam-limits-entry "@@realtime" 'both 'memlock 'unlimited))) +@end example + +The first entry increases the maximum realtime priority for non-privileged +processes; the second entry lifts any restriction of the maximum address +space that can be locked in memory. These settings are commonly used for +real-time audio systems. +@end deffn + +@node Ejecución de tareas programadas +@subsection Ejecución de tareas programadas + +@cindex cron +@cindex mcron +@cindex scheduling jobs +The @code{(gnu services mcron)} module provides an interface to +GNU@tie{}mcron, a daemon to run jobs at scheduled times (@pxref{Top,,, +mcron, GNU@tie{}mcron}). GNU@tie{}mcron is similar to the traditional Unix +@command{cron} daemon; the main difference is that it is implemented in +Guile Scheme, which provides a lot of flexibility when specifying the +scheduling of jobs and their actions. + +The example below defines an operating system that runs the +@command{updatedb} (@pxref{Invoking updatedb,,, find, Finding Files}) and +the @command{guix gc} commands (@pxref{Invocación de guix gc}) daily, as well as +the @command{mkid} command on behalf of an unprivileged user (@pxref{mkid +invocation,,, idutils, ID Database Utilities}). It uses gexps to introduce +job definitions that are passed to mcron (@pxref{Expresiones-G}). + +@lisp +(use-modules (guix) (gnu) (gnu services mcron)) +(use-package-modules base idutils) + +(define trabajo-updatedb + ;; Ejecuta 'updatedb' a las 3AM cada día. Aquí escribimos + ;; las acciones del trabajo como un procedimiento Scheme. + #~(job '(next-hour '(3)) + (lambda () + (execl (string-append #$findutils "/bin/updatedb") + "updatedb" + "--prunepaths=/tmp /var/tmp /gnu/store")))) + +(define trabajo-recolector-basura + ;; Recolecta basura 5 minutos después de media noche, + ;; todos los días. La acción del trabajo es una orden + ;; del shell. + #~(job "5 0 * * *" ;sintaxis de Vixie cron + "guix gc -F 1G")) + +(define trabajo-idutils + ;; Actualiza el índice de la base de datos como "carlos" a las + ;; 12:15 y a las 19:15. Esto se ejecuta desde su directorio. + #~(job '(next-minute-from (next-hour '(12 19)) '(15)) + (string-append #$idutils "/bin/mkid src") + #:user "carlos")) + +(operating-system + ;; @dots{} + (services (cons (service mcron-service-type + (mcron-configuration + (jobs (list trabajo-recolector-basura + trabajo-updatedb + trabajo-idutils)))) + %base-services))) +@end lisp + +@xref{Guile Syntax, mcron job specifications,, mcron, GNU@tie{}mcron}, for +more information on mcron job specifications. Below is the reference of the +mcron service. + +On a running system, you can use the @code{schedule} action of the service +to visualize the mcron jobs that will be executed next: + +@example +# herd schedule mcron +@end example + +@noindent +The example above lists the next five tasks that will be executed, but you +can also specify the number of tasks to display: + +@example +# herd schedule mcron 10 +@end example + +@defvr {Variable Scheme} mcron-service-type +This is the type of the @code{mcron} service, whose value is an +@code{mcron-configuration} object. + +This service type can be the target of a service extension that provides it +additional job specifications (@pxref{Composición de servicios}). In other +words, it is possible to define services that provide additional mcron jobs +to run. +@end defvr + +@deftp {Tipo de datos} mcron-configuration +Tipo de datos que representa la configuración de mcron. + +@table @asis +@item @code{mcron} (predeterminado: @var{mcron}) +El paquete mcron usado. + +@item @code{jobs} +This is a list of gexps (@pxref{Expresiones-G}), where each gexp corresponds +to an mcron job specification (@pxref{Syntax, mcron job specifications,, +mcron, GNU@tie{}mcron}). +@end table +@end deftp + + +@node Rotación de logs +@subsection Rotación de logs + +@cindex rottlog +@cindex rotación de logs +@cindex logging +Log files such as those found in @file{/var/log} tend to grow endlessly, so +it's a good idea to @dfn{rotate} them once in a while---i.e., archive their +contents in separate files, possibly compressed. The @code{(gnu services +admin)} module provides an interface to GNU@tie{}Rot[t]log, a log rotation +tool (@pxref{Top,,, rottlog, GNU Rot[t]log Manual}). + +The example below defines an operating system that provides log rotation +with the default settings, for commonly encountered log files. + +@lisp +(use-modules (guix) (gnu)) +(use-service-modules admin mcron) +(use-package-modules base idutils) + +(operating-system + ;; @dots{} + (services (cons (service rottlog-service-type) + %base-services))) +@end lisp + +@defvr {Variable Scheme} rottlog-service-type +This is the type of the Rottlog service, whose value is a +@code{rottlog-configuration} object. + +Other services can extend this one with new @code{log-rotation} objects (see +below), thereby augmenting the set of files to be rotated. + +This service type can define mcron jobs (@pxref{Ejecución de tareas programadas}) to +run the rottlog service. +@end defvr + +@deftp {Tipo de datos} rottlog-configuration +Tipo de datos que representa la configuración de rottlog. + +@table @asis +@item @code{rottlog} (predeterminado: @code{rottlog}) +El paquete Rottlog usado. + +@item @code{rc-file} (predeterminado: @code{(file-append rottlog "/etc/rc")}) +The Rottlog configuration file to use (@pxref{Mandatory RC Variables,,, +rottlog, GNU Rot[t]log Manual}). + +@item @code{rotations} (predeterminadas: @code{%default-rotations}) +A list of @code{log-rotation} objects as defined below. + +@item @code{jobs} +This is a list of gexps where each gexp corresponds to an mcron job +specification (@pxref{Ejecución de tareas programadas}). +@end table +@end deftp + +@deftp {Tipo de datos} log-rotation +Tipo de datos que representa la rotación de un grupo de ficheros de log. + +Taking an example from the Rottlog manual (@pxref{Period Related File +Examples,,, rottlog, GNU Rot[t]log Manual}), a log rotation might be defined +like this: + +@example +(log-rotation + (frequency 'daily) + (files '("/var/log/apache/*")) + (options '("storedir apache-archives" + "rotate 6" + "notifempty" + "nocompress"))) +@end example + +La lista de campos es como sigue: + +@table @asis +@item @code{frequency} (predeterminada: @code{'weekly}) +La frecuencia de rotación de logs, un símbolo. + +@item @code{files} +La lista de ficheros o patrones extendidos de fichero a rotar. + +@item @code{options} (predeterminadas: @code{'()}) +The list of rottlog options for this rotation (@pxref{Configuration +parameters,,, rottlog, GNU Rot[t]lg Manual}). + +@item @code{post-rotate} (predeterminado: @code{#f}) +Either @code{#f} or a gexp to execute once the rotation has completed. +@end table +@end deftp + +@defvr {Variable Scheme} %default-rotations +Specifies weekly rotation of @var{%rotated-files} and a couple of other +files. +@end defvr + +@defvr {Variable Scheme} %rotated-files +The list of syslog-controlled files to be rotated. By default it is: +@code{'("/var/log/messages" "/var/log/secure")}. +@end defvr + +@node Servicios de red +@subsection Servicios de red + +El módulo @code{(gnu services networking)} proporciona servicios para +configurar la interfaz de red. + +@cindex DHCP, servicio de red +@defvr {Variable Scheme} dhcp-client-service-type +This is the type of services that run @var{dhcp}, a Dynamic Host +Configuration Protocol (DHCP) client, on all the non-loopback network +interfaces. Its value is the DHCP client package to use, @code{isc-dhcp} by +default. +@end defvr + +@deffn {Procedimiento Scheme} dhcpd-service-type +This type defines a service that runs a DHCP daemon. To create a service of +this type, you must supply a @code{<dhcpd-configuration>}. For example: + +@example +(service dhcpd-service-type + (dhcpd-configuration + (config-file (local-file "mi-dhcpd.conf")) + (interfaces '("enp0s25")))) +@end example +@end deffn + +@deftp {Tipo de datos} dhcpd-configuration +@table @asis +@item @code{package} (predeterminado: @code{isc-dhcp}) +The package that provides the DHCP daemon. This package is expected to +provide the daemon at @file{sbin/dhcpd} relative to its output directory. +The default package is the @uref{http://www.isc.org/products/DHCP, ISC's +DHCP server}. +@item @code{config-file} (predeterminado: @code{#f}) +The configuration file to use. This is required. It will be passed to +@code{dhcpd} via its @code{-cf} option. This may be any ``file-like'' +object (@pxref{Expresiones-G, file-like objects}). See @code{man +dhcpd.conf} for details on the configuration file syntax. +@item @code{version} (predeterminada: @code{"4"}) +The DHCP version to use. The ISC DHCP server supports the values ``4'', +``6'', and ``4o6''. These correspond to the @code{dhcpd} program options +@code{-4}, @code{-6}, and @code{-4o6}. See @code{man dhcpd} for details. +@item @code{run-directory} (predeterminado: @code{"/run/dhcpd"}) +The run directory to use. At service activation time, this directory will +be created if it does not exist. +@item @code{pid-file} (predeterminado: @code{"/run/dhcpd/dhcpd.pid"}) +The PID file to use. This corresponds to the @code{-pf} option of +@code{dhcpd}. See @code{man dhcpd} for details. +@item @code{interfaces} (predeterminadas: @code{'()}) +The names of the network interfaces on which dhcpd should listen for +broadcasts. If this list is not empty, then its elements (which must be +strings) will be appended to the @code{dhcpd} invocation when starting the +daemon. It may not be necessary to explicitly specify any interfaces here; +see @code{man dhcpd} for details. +@end table +@end deftp + +@defvr {Variable Scheme} static-networking-service-type +@c TODO Document <static-networking> data structures. +This is the type for statically-configured network interfaces. +@end defvr + +@deffn {Procedimiento Scheme} static-networking-service @var{interfaz} @var{ip} @ + [#:netmask #f] [#:gateway #f] [#:name-servers @code{'()}] @ [#:requirement +@code{'(udev)}] Return a service that starts @var{interface} with address +@var{ip}. If @var{netmask} is true, use it as the network mask. If +@var{gateway} is true, it must be a string specifying the default network +gateway. @var{requirement} can be used to declare a dependency on another +service before configuring the interface. + +This procedure can be called several times, one for each network interface +of interest. Behind the scenes what it does is extend +@code{static-networking-service-type} with additional network interfaces to +handle. + +Por ejemplo: + +@example +(static-networking-service "eno1" "192.168.1.82" + #:gateway "192.168.1.2" + #:name-servers '("192.168.1.2")) +@end example +@end deffn + +@cindex wicd +@cindex sin cables +@cindex WiFi +@cindex gestión de red +@deffn {Procedimiento Scheme} wicd-service [#:wicd @var{wicd}] +Return a service that runs @url{https://launchpad.net/wicd,Wicd}, a network +management daemon that aims to simplify wired and wireless networking. + +This service adds the @var{wicd} package to the global profile, providing +several commands to interact with the daemon and configure networking: +@command{wicd-client}, a graphical user interface, and the +@command{wicd-cli} and @command{wicd-curses} user interfaces. +@end deffn + +@cindex ModemManager + +@defvr {Variable Scheme} modem-manager-service-type +This is the service type for the +@uref{https://wiki.gnome.org/Projects/ModemManager, ModemManager} +service. The value for this service type is a +@code{modem-manager-configuration} record. + +Este servicio es parte de @code{%desktop-services} (@pxref{Servicios de escritorio}). +@end defvr + +@deftp {Tipo de datos} modem-manager-configuration +Tipo de datos que representa la configuración de ModemManager. + +@table @asis +@item @code{modem-manager} (predeterminado: @code{modem-manager}) +El paquete de ModemManager usado. + +@end table +@end deftp + +@cindex NetworkManager + +@defvr {Variable Scheme} network-manager-service-type +This is the service type for the +@uref{https://wiki.gnome.org/Projects/NetworkManager, NetworkManager} +service. The value for this service type is a +@code{network-manager-configuration} record. + +Este servicio es parte de @code{%desktop-services} (@pxref{Servicios de escritorio}). +@end defvr + +@deftp {Tipo de datos} network-manager-configuration +Tipo de datos que representa la configuración de NetworkManager. + +@table @asis +@item @code{network-manager} (predeterminado: @code{network-manager}) +El paquete de NetworkManager usado. + +@item @code{dns} (predeterminado: @code{"default"}) +Processing mode for DNS, which affects how NetworkManager uses the +@code{resolv.conf} configuration file. + +@table @samp +@item default +NetworkManager will update @code{resolv.conf} to reflect the nameservers +provided by currently active connections. + +@item dnsmasq +NetworkManager will run @code{dnsmasq} as a local caching nameserver, using +a "split DNS" configuration if you are connected to a VPN, and then update +@code{resolv.conf} to point to the local nameserver. + +@item none +NetworkManager will not modify @code{resolv.conf}. +@end table + +@item @code{vpn-plugins} (predeterminados: @code{'()}) +This is the list of available plugins for virtual private networks (VPNs). +An example of this is the @code{network-manager-openvpn} package, which +allows NetworkManager to manage VPNs @i{via} OpenVPN. + +@end table +@end deftp + +@cindex Connman +@deffn {Variable Scheme} connman-service-type +This is the service type to run @url{https://01.org/connman,Connman}, a +network connection manager. + +Its value must be an @code{connman-configuration} record as in this example: + +@example +(service connman-service-type + (connman-configuration + (disable-vpn? #t))) +@end example + +See below for details about @code{connman-configuration}. +@end deffn + +@deftp {Tipo de datos} connman-configuration +Tipo de datos que representa la configuración de connman. + +@table @asis +@item @code{connman} (predeterminado: @var{connman}) +El paquete connman usado. + +@item @code{disable-vpn?} (predeterminado: @code{#f}) +Cuando es verdadero, deshabilita el módulo vpn de connman. +@end table +@end deftp + +@cindex WPA Supplicant +@defvr {Variable Scheme} wpa-supplicant-service-type +This is the service type to run @url{https://w1.fi/wpa_supplicant/,WPA +supplicant}, an authentication daemon required to authenticate against +encrypted WiFi or ethernet networks. +@end defvr + +@deftp {Tipo de datos} wpa-supplicant-configuration +Tipo de datos que representa la configuración de WPA Supplicant. + +Toma los siguientes parámetros: + +@table @asis +@item @code{wpa-supplicant} (predeterminado: @code{wpa-supplicant}) +El paquete de WPA Supplicant usado. + +@item @code{dbus?} (predeterminado: @code{#t}) +Si se escuchan o no peticiones en D-Bus. + +@item @code{pid-file} (predeterminado: @code{"/var/run/wpa_supplicant.pid"}) +Dónde se almacena el fichero con el PID. + +@item @code{interface} (predeterminado: @code{#f}) +If this is set, it must specify the name of a network interface that WPA +supplicant will control. + +@item @code{config-file} (predeterminado: @code{#f}) +Fichero de configuración opcional usado. + +@item @code{extra-options} (predeterminadas: @code{'()}) +Lista de parámetros adicionales a pasar al daemon en la línea de órdenes. +@end table +@end deftp + +@cindex iptables +@defvr {Variable Scheme} iptables-service-type +This is the service type to set up an iptables configuration. iptables is a +packet filtering framework supported by the Linux kernel. This service +supports configuring iptables for both IPv4 and IPv6. A simple example +configuration rejecting all incoming connections except those to the ssh +port 22 is shown below. + +@lisp +(service iptables-service-type + (iptables-configuration + (ipv4-rules (plain-file "iptables.rules" "*filter +:INPUT ACCEPT +:FORWARD ACCEPT +:OUTPUT ACCEPT +-A INPUT -p tcp --dport 22 -j ACCEPT +-A INPUT -j REJECT --reject-with icmp-port-unreachable +COMMIT +")) + (ipv6-rules (plain-file "ip6tables.rules" "*filter +:INPUT ACCEPT +:FORWARD ACCEPT +:OUTPUT ACCEPT +-A INPUT -p tcp --dport 22 -j ACCEPT +-A INPUT -j REJECT --reject-with icmp6-port-unreachable +COMMIT +")))) +@end lisp +@end defvr + +@deftp {Tipo de datos} iptables-configuration +El tipo de datos que representa la configuración de iptables. + +@table @asis +@item @code{iptables} (predeterminado: @code{iptables}) +The iptables package that provides @code{iptables-restore} and +@code{ip6tables-restore}. +@item @code{ipv4-rules} (predeterminado: @code{%iptables-accept-all-rules}) +The iptables rules to use. It will be passed to @code{iptables-restore}. +This may be any ``file-like'' object (@pxref{Expresiones-G, file-like +objects}). +@item @code{ipv6-rules} (predeterminadas: @code{%iptables-accept-all-rules}) +The ip6tables rules to use. It will be passed to @code{ip6tables-restore}. +This may be any ``file-like'' object (@pxref{Expresiones-G, file-like +objects}). +@end table +@end deftp + +@cindex NTP (protocolo de tiempo de red), servicio +@cindex reloj de tiempo real +@defvr {Variable Scheme} ntp-service-type +This is the type of the service running the @uref{http://www.ntp.org, +Network Time Protocol (NTP)} daemon, @command{ntpd}. The daemon will keep +the system clock synchronized with that of the specified NTP servers. + +The value of this service is an @code{ntpd-configuration} object, as +described below. +@end defvr + +@deftp {Tipo de datos} ntp-configuration +Este es el tipo de datos para la configuración del servicio NTP. + +@table @asis +@item @code{servers} (predeterminados: @code{%ntp-servers}) +This is the list of servers (host names) with which @command{ntpd} will be +synchronized. + +@item @code{allow-large-adjustment?} (predeterminado: @code{#f}) +This determines whether @command{ntpd} is allowed to make an initial +adjustment of more than 1,000 seconds. + +@item @code{ntp} (predeterminado: @code{ntp}) +El paquete NTP usado. +@end table +@end deftp + +@defvr {Variable Scheme} %ntp-servers +List of host names used as the default NTP servers. These are servers of +the @uref{https://www.ntppool.org/en/, NTP Pool Project}. +@end defvr + +@cindex OpenNTPD +@deffn {Procedimiento Scheme} openntpd-service-type +Run the @command{ntpd}, the Network Time Protocol (NTP) daemon, as +implemented by @uref{http://www.openntpd.org, OpenNTPD}. The daemon will +keep the system clock synchronized with that of the given servers. + +@example +(service + openntpd-service-type + (openntpd-configuration + (listen-on '("127.0.0.1" "::1")) + (sensor '("udcf0 correction 70000")) + (constraint-from '("www.gnu.org")) + (constraints-from '("https://www.google.com/")) + (allow-large-adjustment? #t))) + +@end example +@end deffn + +@deftp {Tipo de datos} openntpd-configuration +@table @asis +@item @code{openntpd} (predeterminado: @code{(file-append openntpd "/sbin/ntpd")}) +El ejecutable openntpd usado. +@item @code{listen-on} (predeterminadas: @code{'("127.0.0.1" "::1")}) +Una lista de direcciones IP o nombres de máquina en los que el daemon ntpd +debe escuchar conexiones. +@item @code{query-from} (predeterminadas: @code{'()}) +Una lista de direcciones IP locales que el daemon ntpd debe usar para +consultas salientes. +@item @code{sensor} (predeterminados: @code{'()}) +Specify a list of timedelta sensor devices ntpd should use. @code{ntpd} +will listen to each sensor that acutally exists and ignore non-existant +ones. See @uref{https://man.openbsd.org/ntpd.conf, upstream documentation} +for more information. +@item @code{server} (predeterminadas: @var{%ntp-servers}) +Specify a list of IP addresses or hostnames of NTP servers to synchronize +to. +@item @code{servers} (predeterminados: @code{'()}) +Specify a list of IP addresses or hostnames of NTP pools to synchronize to. +@item @code{constraint-from} (predeterminado: @code{'()}) +@code{ntpd} can be configured to query the ‘Date’ from trusted HTTPS servers +via TLS. This time information is not used for precision but acts as an +authenticated constraint, thereby reducing the impact of unauthenticated NTP +man-in-the-middle attacks. Specify a list of URLs, IP addresses or +hostnames of HTTPS servers to provide a constraint. +@item @code{constraints-from} (predeterminadas: @code{'()}) +As with constraint from, specify a list of URLs, IP addresses or hostnames +of HTTPS servers to provide a constraint. Should the hostname resolve to +multiple IP addresses, @code{ntpd} will calculate a median constraint from +all of them. +@item @code{allow-large-adjustment?} (predeterminado: @code{#f}) +Determines if @code{ntpd} is allowed to make an initial adjustment of more +than 180 seconds. +@end table +@end deftp + +@cindex inetd +@deffn {Variable Scheme} inetd-service-type +This service runs the @command{inetd} (@pxref{inetd invocation,,, inetutils, +GNU Inetutils}) daemon. @command{inetd} listens for connections on internet +sockets, and lazily starts the specified server program when a connection is +made on one of these sockets. + +The value of this service is an @code{inetd-configuration} object. The +following example configures the @command{inetd} daemon to provide the +built-in @command{echo} service, as well as an smtp service which forwards +smtp traffic over ssh to a server @code{smtp-server} behind a gateway +@code{hostname}: + +@example +(service + inetd-service-type + (inetd-configuration + (entries (list + (inetd-entry + (name "echo") + (socket-type 'stream) + (protocol "tcp") + (wait? #f) + (user "root")) + (inetd-entry + (node "127.0.0.1") + (name "smtp") + (socket-type 'stream) + (protocol "tcp") + (wait? #f) + (user "root") + (program (file-append openssh "/bin/ssh")) + (arguments + '("ssh" "-qT" "-i" "/ruta/a/la/clave_ssh" + "-W" "smtp-server:25" "usuaria@@máquina"))))) +@end example + +See below for more details about @code{inetd-configuration}. +@end deffn + +@deftp {Tipo de datos} inetd-configuration +Tipo de datos que representa la configuración de @command{inetd}. + +@table @asis +@item @code{program} (predeterminado: @code{(file-append inetutils "/libexec/inetd")}) +El ejecutable @command{inetd} usado. + +@item @code{entries} (predeterminadas: @code{'()}) +A list of @command{inetd} service entries. Each entry should be created by +the @code{inetd-entry} constructor. +@end table +@end deftp + +@deftp {Tipo de datos} inetd-entry +Data type representing an entry in the @command{inetd} configuration. Each +entry corresponds to a socket where @command{inetd} will listen for +requests. + +@table @asis +@item @code{node} (predeterminado: @code{#f}) +Optional string, a comma-separated list of local addresses @command{inetd} +should use when listening for this service. @xref{Configuration file,,, +inetutils, GNU Inetutils} for a complete description of all options. +@item @code{name} +A string, the name must correspond to an entry in @code{/etc/services}. +@item @code{socket-type} +One of @code{'stream}, @code{'dgram}, @code{'raw}, @code{'rdm} or +@code{'seqpacket}. +@item @code{protocol} +A string, must correspond to an entry in @code{/etc/protocols}. +@item @code{wait?} (predeterminado: @code{#t}) +Whether @command{inetd} should wait for the server to exit before listening +to new service requests. +@item @code{user} +A string containing the user (and, optionally, group) name of the user as +whom the server should run. The group name can be specified in a suffix, +separated by a colon or period, i.e.@: @code{"user"}, @code{"user:group"} or +@code{"user.group"}. +@item @code{program} (predeterminado: @code{"internal"}) +The server program which will serve the requests, or @code{"internal"} if +@command{inetd} should use a built-in service. +@item @code{arguments} (predeterminados: @code{'()}) +A list strings or file-like objects, which are the server program's +arguments, starting with the zeroth argument, i.e.@: the name of the program +itself. For @command{inetd}'s internal services, this entry must be +@code{'()} or @code{'("internal")}. +@end table + +@xref{Configuration file,,, inetutils, GNU Inetutils} for a more detailed +discussion of each configuration field. +@end deftp + +@cindex Tor +@defvr {Variable Scheme} tor-service-type +This is the type for a service that runs the @uref{https://torproject.org, +Tor} anonymous networking daemon. The service is configured using a +@code{<tor-configuration>} record. By default, the Tor daemon runs as the +@code{tor} unprivileged user, which is a member of the @code{tor} group. + +@end defvr + +@deftp {Tipo de datos} tor-configuration +@table @asis +@item @code{tor} (predeterminado: @code{tor}) +The package that provides the Tor daemon. This package is expected to +provide the daemon at @file{bin/tor} relative to its output directory. The +default package is the @uref{https://www.torproject.org, Tor Project's} +implementation. + +@item @code{config-file} (predeterminado: @code{(plain-file "empty" "")}) +The configuration file to use. It will be appended to a default +configuration file, and the final configuration file will be passed to +@code{tor} via its @code{-f} option. This may be any ``file-like'' object +(@pxref{Expresiones-G, file-like objects}). See @code{man tor} for details +on the configuration file syntax. + +@item @code{hidden-services} (predeterminados: @code{'()}) +The list of @code{<hidden-service>} records to use. For any hidden service +you include in this list, appropriate configuration to enable the hidden +service will be automatically added to the default configuration file. You +may conveniently create @code{<hidden-service>} records using the +@code{tor-hidden-service} procedure described below. + +@item @code{socks-socket-type} (predeterminado: @code{'tcp}) +The default socket type that Tor should use for its SOCKS socket. This must +be either @code{'tcp} or @code{'unix}. If it is @code{'tcp}, then by +default Tor will listen on TCP port 9050 on the loopback interface (i.e., +localhost). If it is @code{'unix}, then Tor will listen on the UNIX domain +socket @file{/var/run/tor/socks-sock}, which will be made writable by +members of the @code{tor} group. + +If you want to customize the SOCKS socket in more detail, leave +@code{socks-socket-type} at its default value of @code{'tcp} and use +@code{config-file} to override the default by providing your own +@code{SocksPort} option. +@end table +@end deftp + +@cindex servicio oculto +@deffn {Procedimiento Scheme} tor-hidden-service @var{nombre} @var{relación} +Define un @dfn{servicio oculto} Tor llamado @var{nombre} y que implementa la +@var{¶elación}. @var{relación} es una lista de tuplas puerto/máquina, como: + +@example + '((22 "127.0.0.1:22") + (80 "127.0.0.1:8080")) +@end example + +En este ejemplo, el puerto 22 del servicio oculto se asocia con el puerto 22 +local, y el puerto 80 se asocia con el puerto 8080 local. + +Esto crea un directorio @file{/var/lib/tor/hidden-services/@var{nombre}}, +donde el fichero @file{hostname} contiene el nombre de máquina @code{.onion} +para el servicio oculto. + +Véase @uref{https://www.torproject.org/docs/tor-hidden-service.html.en, la +documentación del proyecto Tor} para más información. +@end deffn + +El módulo @code{(gnu services rsync)} proporciona los siguientes servicios: + +You might want an rsync daemon if you have files that you want available so +anyone (or just yourself) can download existing files or upload new files. + +@deffn {Variable Scheme} rsync-service-type +This is the type for the @uref{https://rsync.samba.org, rsync} rsync daemon, +@command{rsync-configuration} record as in this example: + +@example +(service rsync-service-type) +@end example + +See below for details about @code{rsync-configuration}. +@end deffn + +@deftp {Tipo de datos} rsync-configuration +Tipo de datos que representa la configuración para @code{rsync-service}. + +@table @asis +@item @code{package} (predeterminado: @var{rsync}) +Paquete @code{rsync} usado. + +@item @code{port-number} (predeterminado: @code{873}) +TCP port on which @command{rsync} listens for incoming connections. If port +is less than @code{1024} @command{rsync} needs to be started as the +@code{root} user and group. + +@item @code{pid-file} (predeterminado: @code{"/var/run/rsyncd/rsyncd.pid"}) +Name of the file where @command{rsync} writes its PID. + +@item @code{lock-file} (predeterminado: @code{"/var/run/rsyncd/rsyncd.lock"}) +Name of the file where @command{rsync} writes its lock file. + +@item @code{log-file} (predeterminado: @code{"/var/log/rsyncd.log"}) +Name of the file where @command{rsync} writes its log file. + +@item @code{use-chroot?} (predeterminado: @var{#t}) +Whether to use chroot for @command{rsync} shared directory. + +@item @code{share-path} (predeterminado: @file{/srv/rsync}) +Location of the @command{rsync} shared directory. + +@item @code{share-comment} (predeterminado: @code{"Rsync share"}) +Comment of the @command{rsync} shared directory. + +@item @code{read-only?} (predeterminado: @var{#f}) +Read-write permissions to shared directory. + +@item @code{timeout} (predeterminado: @code{300}) +I/O timeout in seconds. + +@item @code{user} (predeterminada: @var{"root"}) +Propietaria del proceso @code{rsync}. + +@item @code{group} (predeterminado: @var{"root"}) +Grupo del proceso @code{rsync}. + +@item @code{uid} (predeterminado: @var{"rsyncd"}) +Nombre o ID de usuaria bajo la cual se efectúan las transferencias desde y +hacia el módulo cuando el daemon se ejecuta como @code{root}. + +@item @code{gid} (predeterminado: @var{"rsyncd"}) +Nombre o ID de grupo que se usa cuando se accede al módulo. + +@end table +@end deftp + +Es más, @code{(gnu services ssh)} proporciona los siguientes servicios. +@cindex SSH +@cindex servidor SSH + +@deffn {Procedimiento Scheme} lsh-service [#:host-key "/etc/lsh/host-key"] @ + [#:daemonic? #t] [#:interfaces '()] [#:port-number 22] @ + [#:allow-empty-passwords? #f] [#:root-login? #f] @ + [#:syslog-output? #t] [#:x11-forwarding? #t] @ + [#:tcp/ip-forwarding? #t] [#:password-authentication? #t] @ + [#:public-key-authentication? #t] [#:initialize? #t] +Ejecuta el programa @command{lshd} de @var{lsh} para escuchar en el puerto +@var{port-number}. @var{host-key} debe designar a un fichero que contiene la +clave de la máquina, y que sea legible únicamente por root. + +When @var{daemonic?} is true, @command{lshd} will detach from the +controlling terminal and log its output to syslogd, unless one sets +@var{syslog-output?} to false. Obviously, it also makes lsh-service depend +on existence of syslogd service. When @var{pid-file?} is true, +@command{lshd} writes its PID to the file called @var{pid-file}. + +When @var{initialize?} is true, automatically create the seed and host key +upon service activation if they do not exist yet. This may take long and +require interaction. + +When @var{initialize?} is false, it is up to the user to initialize the +randomness generator (@pxref{lsh-make-seed,,, lsh, LSH Manual}), and to +create a key pair with the private key stored in file @var{host-key} +(@pxref{lshd basics,,, lsh, LSH Manual}). + +When @var{interfaces} is empty, lshd listens for connections on all the +network interfaces; otherwise, @var{interfaces} must be a list of host names +or addresses. + +@var{allow-empty-passwords?} specifies whether to accept log-ins with empty +passwords, and @var{root-login?} specifies whether to accept log-ins as +root. + +The other options should be self-descriptive. +@end deffn + +@cindex SSH +@cindex servidor SSH +@deffn {Variable Scheme} openssh-service-type +This is the type for the @uref{http://www.openssh.org, OpenSSH} secure shell +daemon, @command{sshd}. Its value must be an @code{openssh-configuration} +record as in this example: + +@example +(service openssh-service-type + (openssh-configuration + (x11-forwarding? #t) + (permit-root-login 'without-password) + (authorized-keys + `(("alicia" ,(local-file "alicia.pub")) + ("rober" ,(local-file "rober.pub")))))) +@end example + +See below for details about @code{openssh-configuration}. + +This service can be extended with extra authorized keys, as in this example: + +@example +(service-extension openssh-service-type + (const `(("carlos" + ,(local-file "carlos.pub"))))) +@end example +@end deffn + +@deftp {Tipo de datos} openssh-configuration +Este es el registro de configuración para @command{sshd} de OpenSSH. + +@table @asis +@item @code{pid-file} (predeterminado: @code{"/var/run/sshd.pid"}) +Name of the file where @command{sshd} writes its PID. + +@item @code{port-number} (predeterminado: @code{22}) +TCP port on which @command{sshd} listens for incoming connections. + +@item @code{permit-root-login} (predeterminado: @code{#f}) +This field determines whether and when to allow logins as root. If +@code{#f}, root logins are disallowed; if @code{#t}, they are allowed. If +it's the symbol @code{'without-password}, then root logins are permitted but +not with password-based authentication. + +@item @code{allow-empty-passwords?} (predeterminado: @code{#f}) +When true, users with empty passwords may log in. When false, they may not. + +@item @code{password-authentication?} (predeterminado: @code{#t}) +When true, users may log in with their password. When false, they have +other authentication methods. + +@item @code{public-key-authentication?} (predeterminado: @code{#t}) +When true, users may log in using public key authentication. When false, +users have to use other authentication method. + +Authorized public keys are stored in @file{~/.ssh/authorized_keys}. This is +used only by protocol version 2. + +@item @code{x11-forwarding?} (predeterminado: @code{#f}) +When true, forwarding of X11 graphical client connections is enabled---in +other words, @command{ssh} options @option{-X} and @option{-Y} will work. + +@item @code{allow-agent-forwarding?} (predeterminado: @code{#t}) +Whether to allow agent forwarding. + +@item @code{allow-tcp-forwarding?} (predeterminado: @code{#t}) +Whether to allow TCP forwarding. + +@item @code{gateway-ports?} (predeterminado: @code{#f}) +Whether to allow gateway ports. + +@item @code{challenge-response-authentication?} (predeterminado: @code{#f}) +Specifies whether challenge response authentication is allowed (e.g.@: via +PAM). + +@item @code{use-pam?} (predeterminado: @code{#t}) +Enables the Pluggable Authentication Module interface. If set to @code{#t}, +this will enable PAM authentication using +@code{challenge-response-authentication?} and +@code{password-authentication?}, in addition to PAM account and session +module processing for all authentication types. + +Because PAM challenge response authentication usually serves an equivalent +role to password authentication, you should disable either +@code{challenge-response-authentication?} or +@code{password-authentication?}. + +@item @code{print-last-log?} (predeterminado: @code{#t}) +Especifica si @command{sshd} debe imprimir la fecha y hora del último +ingreso al sistema de la usuaria cuando una usuaria ingresa +interactivamente. + +@item @code{subsystems} (predeterminados: @code{'(("sftp" "internal-sftp"))}) +Configures external subsystems (e.g.@: file transfer daemon). + +This is a list of two-element lists, each of which containing the subsystem +name and a command (with optional arguments) to execute upon subsystem +request. + +The command @command{internal-sftp} implements an in-process SFTP server. +Alternately, one can specify the @command{sftp-server} command: +@example +(service openssh-service-type + (openssh-configuration + (subsystems + `(("sftp" ,(file-append openssh "/libexec/sftp-server")))))) +@end example + +@item @code{accepted-environment} (predeterminado: @code{'()}) +List of strings describing which environment variables may be exported. + +Each string gets on its own line. See the @code{AcceptEnv} option in +@code{man sshd_config}. + +This example allows ssh-clients to export the @code{COLORTERM} variable. It +is set by terminal emulators, which support colors. You can use it in your +shell's ressource file to enable colors for the prompt and commands if this +variable is set. + +@example +(service openssh-service-type + (openssh-configuration + (accepted-environment '("COLORTERM")))) +@end example + +@item @code{authorized-keys} (predeterminadas: @code{'()}) +@cindex claves autorizadas, SSH +@cindex SSH, claves autorizadas +This is the list of authorized keys. Each element of the list is a user +name followed by one or more file-like objects that represent SSH public +keys. For example: + +@example +(openssh-configuration + (authorized-keys + `(("rekado" ,(local-file "rekado.pub")) + ("chris" ,(local-file "chris.pub")) + ("root" ,(local-file "rekado.pub") ,(local-file "chris.pub"))))) +@end example + +@noindent +registers the specified public keys for user accounts @code{rekado}, +@code{chris}, and @code{root}. + +Additional authorized keys can be specified @i{via} +@code{service-extension}. + +Note that this does @emph{not} interfere with the use of +@file{~/.ssh/authorized_keys}. + +@item @code{log-level} (predeterminado: @code{'info}) +This is a symbol specifying the logging level: @code{quiet}, @code{fatal}, +@code{error}, @code{info}, @code{verbose}, @code{debug}, etc. See the man +page for @file{sshd_config} for the full list of level names. + +@item @code{extra-content} (predeterminado: @code{""}) +This field can be used to append arbitrary text to the configuration file. +It is especially useful for elaborate configurations that cannot be +expressed otherwise. This configuration, for example, would generally +disable root logins, but permit them from one specific IP address: + +@example +(openssh-configuration + (extra-content "\ +Match Address 192.168.0.1 + PermitRootLogin yes")) +@end example + +@end table +@end deftp + +@deffn {Procedimiento Scheme} dropbear-service [@var{config}] +Run the @uref{https://matt.ucc.asn.au/dropbear/dropbear.html,Dropbear SSH +daemon} with the given @var{config}, a @code{<dropbear-configuration>} +object. + +For example, to specify a Dropbear service listening on port 1234, add this +call to the operating system's @code{services} field: + +@example +(dropbear-service (dropbear-configuration + (port-number 1234))) +@end example +@end deffn + +@deftp {Tipo de datos} dropbear-configuration +This data type represents the configuration of a Dropbear SSH daemon. + +@table @asis +@item @code{dropbear} (predeterminado: @var{dropbear}) +El paquete de Dropbear usado. + +@item @code{port-number} (predeterminado: 22) +Puerto TCP donde el daemon espera conexiones entrantes. + +@item @code{syslog-output?} (predeterminado: @code{#t}) +Whether to enable syslog output. + +@item @code{pid-file} (predeterminado: @code{"/var/run/dropbear.pid"}) +File name of the daemon's PID file. + +@item @code{root-login?} (predeterminado: @code{#f}) +Whether to allow @code{root} logins. + +@item @code{allow-empty-passwords?} (predeterminado: @code{#f}) +Whether to allow empty passwords. + +@item @code{password-authentication?} (predeterminado: @code{#t}) +Whether to enable password-based authentication. +@end table +@end deftp + +@defvr {Variable Scheme} %facebook-host-aliases +This variable contains a string for use in @file{/etc/hosts} (@pxref{Host +Names,,, libc, The GNU C Library Reference Manual}). Each line contains a +entry that maps a known server name of the Facebook on-line service---e.g., +@code{www.facebook.com}---to the local host---@code{127.0.0.1} or its IPv6 +equivalent, @code{::1}. + +This variable is typically used in the @code{hosts-file} field of an +@code{operating-system} declaration (@pxref{Referencia de ``operating-system'', +@file{/etc/hosts}}): + +@example +(use-modules (gnu) (guix)) + +(operating-system + (host-name "micompu") + ;; ... + (hosts-file + ;; Crea un fichero /etc/hosts file con alias para "localhost" + ;; y "micompu", así como los servidores de facebook. + (plain-file "hosts" + (string-append (local-host-aliases host-name) + %facebook-host-aliases)))) +@end example + +Este mecanismo puede impedir a los programas que se ejecutan localmente, +como navegadores Web, el acceso a Facebook. +@end defvr + +El módulo @code{(gnu services avahi)} proporciona la siguiente definición. + +@defvr {Scheme Variable} avahi-service-type +This is the service that runs @command{avahi-daemon}, a system-wide +mDNS/DNS-SD responder that allows for service discovery and +``zero-configuration'' host name lookups (see @uref{http://avahi.org/}). +Its value must be a @code{zero-configuration} record---see below. + +This service extends the name service cache daemon (nscd) so that it can +resolve @code{.local} host names using +@uref{http://0pointer.de/lennart/projects/nss-mdns/, nss-mdns}. @xref{Selector de servicios de nombres}, for information on host name resolution. + +Additionally, add the @var{avahi} package to the system profile so that +commands such as @command{avahi-browse} are directly usable. +@end defvr + +@deftp {Data Type} avahi-configuration +Data type representation the configuration for Avahi. + +@table @asis + +@item @code{host-name} (default: @code{#f}) +If different from @code{#f}, use that as the host name to publish for this +machine; otherwise, use the machine's actual host name. + +@item @code{publish?} (default: @code{#t}) +When true, allow host names and services to be published (broadcast) over +the network. + +@item @code{publish-workstation?} (default: @code{#t}) +When true, @command{avahi-daemon} publishes the machine's host name and IP +address via mDNS on the local network. To view the host names published on +your local network, you can run: + +@example +avahi-browse _workstation._tcp +@end example + +@item @code{wide-area?} (default: @code{#f}) +When true, DNS-SD over unicast DNS is enabled. + +@item @code{ipv4?} (default: @code{#t}) +@itemx @code{ipv6?} (default: @code{#t}) +These fields determine whether to use IPv4/IPv6 sockets. + +@item @code{domains-to-browse} (default: @code{'()}) +This is a list of domains to browse. +@end table +@end deftp + +@deffn {Variable Scheme} openvswitch-service-type +This is the type of the @uref{http://www.openvswitch.org, Open vSwitch} +service, whose value should be an @code{openvswitch-configuration} object. +@end deffn + +@deftp {Tipo de datos} openvswitch-configuration +Data type representing the configuration of Open vSwitch, a multilayer +virtual switch which is designed to enable massive network automation +through programmatic extension. + +@table @asis +@item @code{package} (predeterminado: @var{openvswitch}) +Package object of the Open vSwitch. + +@end table +@end deftp + +@node Sistema X Window +@subsection Sistema X Window + +@cindex X11 +@cindex Sistema de ventanas X +@cindex gestor de ingreso en el sistema +Support for the X Window graphical display system---specifically Xorg---is +provided by the @code{(gnu services xorg)} module. Note that there is no +@code{xorg-service} procedure. Instead, the X server is started by the +@dfn{login manager}, by default the GNOME Display Manager (GDM). + +@cindex GDM +@cindex GNOME, login manager +GDM of course allows users to log in into window managers and desktop +environments other than GNOME; for those using GNOME, GDM is required for +features such as automatic screen locking. + +@cindex gestor de ventanas +To use X11, you must install at least one @dfn{window manager}---for example +the @code{windowmaker} or @code{openbox} packages---preferably by adding it +to the @code{packages} field of your operating system definition +(@pxref{Referencia de ``operating-system'', system-wide packages}). + +@defvr {Scheme Variable} gdm-service-type +This is the type for the @uref{https://wiki.gnome.org/Projects/GDM/, GNOME +Desktop Manager} (GDM), a program that manages graphical display servers and +handles graphical user logins. Its value must be a @code{gdm-configuration} +(see below.) + +@cindex tipos de sesión (X11) +@cindex X11, tipos de sesión +GDM looks for @dfn{session types} described by the @file{.desktop} files in +@file{/run/current-system/profile/share/xsessions} and allows users to +choose a session from the log-in screen. Packages such as @code{gnome}, +@code{xfce}, and @code{i3} provide @file{.desktop} files; adding them to the +system-wide set of packages automatically makes them available at the log-in +screen. + +In addition, @file{~/.xsession} files are honored. When available, +@file{~/.xsession} must be an executable that starts a window manager and/or +other X clients. +@end defvr + +@deftp {Data Type} gdm-configuration +@table @asis +@item @code{auto-login?} (predeterminado: @code{#f}) +@itemx @code{default-user} (default: @code{#f}) +When @code{auto-login?} is false, GDM presents a log-in screen. + +When @code{auto-login?} is true, GDM logs in directly as +@code{default-user}. + +@item @code{gnome-shell-assets} (default: ...) +List of GNOME Shell assets needed by GDM: icon theme, fonts, etc. + +@item @code{xorg-configuration} (default: @code{(xorg-configuration)}) +Configuration of the Xorg graphical server. + +@item @code{xsession} (default: @code{(xinitrc)}) +Script to run before starting a X session. + +@item @code{dbus-daemon} (default: @code{dbus-daemon-wrapper}) +File name of the @code{dbus-daemon} executable. + +@item @code{gdm} (default: @code{gdm}) +The GDM package to use. +@end table +@end deftp + +@defvr {Variable Scheme} slim-service-type +Este es el tipo para el gestor de ingreso al sistema gráfico para X11 SLiM. + +Like GDM, SLiM looks for session types described by @file{.desktop} files +and allows users to choose a session from the log-in screen using @kbd{F1}. +It also honors @file{~/.xsession} files. +@end defvr + +@deftp {Tipo de datos} slim-configuration +Data type representing the configuration of @code{slim-service-type}. + +@table @asis +@item @code{allow-empty-passwords?} (predeterminado: @code{#t}) +Whether to allow logins with empty passwords. + +@item @code{auto-login?} (predeterminado: @code{#f}) +@itemx @code{default-user} (predeterminado: @code{""}) +When @code{auto-login?} is false, SLiM presents a log-in screen. + +When @code{auto-login?} is true, SLiM logs in directly as +@code{default-user}. + +@item @code{theme} (predeterminado: @code{%default-slim-theme}) +@itemx @code{theme-name} (predeterminado: @code{%default-slim-theme-name}) +The graphical theme to use and its name. + +@item @code{auto-login-session} (predeterminado: @code{#f}) +If true, this must be the name of the executable to start as the default +session---e.g., @code{(file-append windowmaker "/bin/windowmaker")}. + +If false, a session described by one of the available @file{.desktop} files +in @code{/run/current-system/profile} and @code{~/.guix-profile} will be +used. + +@quotation Nota +You must install at least one window manager in the system profile or in +your user profile. Failing to do that, if @code{auto-login-session} is +false, you will be unable to log in. +@end quotation + +@item @code{xorg-configuration} (default @code{(xorg-configuration)}) +Configuration of the Xorg graphical server. + +@item @code{xauth} (predeterminado: @code{xauth}) +El paquete XAuth usado. + +@item @code{shepherd} (predeterminado: @code{shepherd}) +The Shepherd package used when invoking @command{halt} and @command{reboot}. + +@item @code{sessreg} (predeterminado: @code{sessreg}) +The sessreg package used in order to register the session. + +@item @code{slim} (predeterminado: @code{slim}) +El paquete SLiM usado. +@end table +@end deftp + +@defvr {Variable Scheme} %default-theme +@defvrx {Variable Scheme} %default-theme-name +The default SLiM theme and its name. +@end defvr + + +@deftp {Tipo de datos} sddm-configuration +This is the data type representing the sddm service configuration. + +@table @asis +@item @code{display-server} (predeterminado: "x11") +Select display server to use for the greeter. Valid values are "x11" or +"wayland". + +@item @code{numlock} (predeterminado: "on") +Valid values are "on", "off" or "none". + +@item @code{halt-command} (predeterminado @code{#~(string-apppend #$shepherd "/sbin/halt")}) +Command to run when halting. + +@item @code{reboot-command} (predeterminado @code{#~(string-append #$shepherd "/sbin/reboot")}) +Command to run when rebooting. + +@item @code{theme} (predeterminado "maldives") +Theme to use. Default themes provided by SDDM are "elarun" or "maldives". + +@item @code{themes-directory} (predeterminado "/run/current-system/profile/share/sddm/themes") +Directory to look for themes. + +@item @code{faces-directory} (predeterminado "/run/current-system/profile/share/sddm/faces") +Directory to look for faces. + +@item @code{default-path} (predeterminado "/run/current-system/profile/bin") +Default PATH to use. + +@item @code{minimum-uid} (predeterminado 1000) +Minimum UID to display in SDDM. + +@item @code{maximum-uid} (predeterminado 2000) +Maximum UID to display in SDDM + +@item @code{remember-last-user?} (predeterminado #t) +Remember last user. + +@item @code{remember-last-session?} (predeterminado #t) +Remember last session. + +@item @code{hide-users} (predeterminado "") +Usernames to hide from SDDM greeter. + +@item @code{hide-shells} (predeterminado @code{#~(string-append #$shadow "/sbin/nologin")}) +Users with shells listed will be hidden from the SDDM greeter. + +@item @code{session-command} (predeterminado @code{#~(string-append #$sddm "/share/sddm/scripts/wayland-session")}) +Script to run before starting a wayland session. + +@item @code{sessions-directory} (predeterminado "/run/current-system/profile/share/wayland-sessions") +Directory to look for desktop files starting wayland sessions. + +@item @code{xorg-configuration} (default @code{(xorg-configuration)}) +Configuration of the Xorg graphical server. + +@item @code{xauth-path} (predeterminado @code{#~(string-append #$xauth "/bin/xauth")}) +Path to xauth. + +@item @code{xephyr-path} (predeterminado @code{#~(string-append #$xorg-server "/bin/Xephyr")}) +Path to Xephyr. + +@item @code{xdisplay-start} (predeterminado @code{#~(string-append #$sddm "/share/sddm/scripts/Xsetup")}) +Script to run after starting xorg-server. + +@item @code{xdisplay-stop} (predeterminado @code{#~(string-append #$sddm "/share/sddm/scripts/Xstop")}) +Script to run before stopping xorg-server. + +@item @code{xsession-command} (predeterminado: @code{xinitrc}) +Script to run before starting a X session. + +@item @code{xsessions-directory} (predeterminado: "/run/current-system/profile/share/xsessions") +Directory to look for desktop files starting X sessions. + +@item @code{minimum-vt} (predeterminado: 7) +Minimum VT to use. + +@item @code{auto-login-user} (predeterminado "") +User to use for auto-login. + +@item @code{auto-login-session} (predeterminado "") +Desktop file to use for auto-login. + +@item @code{relogin?} (predeterminado #f) +Relogin after logout. + +@end table +@end deftp + +@cindex gestor de ingreso en el sistema +@cindex X11, ingreso al sistema +@deffn {Procedimiento Scheme} sddm-service config +Return a service that spawns the SDDM graphical login manager for config of +type @code{<sddm-configuration>}. + +@example + (sddm-service (sddm-configuration + (auto-login-user "Alicia") + (auto-login-session "xfce.desktop"))) +@end example +@end deffn + +@cindex Xorg, configuration +@deftp {Data Type} xorg-configuration +This data type represents the configuration of the Xorg graphical display +server. Note that there is not Xorg service; instead, the X server is +started by a ``display manager'' such as GDM, SDDM, and SLiM. Thus, the +configuration of these display managers aggregates an +@code{xorg-configuration} record. + +@table @asis +@item @code{modules} (default: @code{%default-xorg-modules}) +This is a list of @dfn{module packages} loaded by the Xorg server---e.g., +@code{xf86-video-vesa}, @code{xf86-input-keyboard}, and so on. + +@item @code{fonts} (default: @code{%default-xorg-fonts}) +This is a list of font directories to add to the server's @dfn{font path}. + +@item @code{drivers} (default: @code{'()}) +This must be either the empty list, in which case Xorg chooses a graphics +driver automatically, or a list of driver names that will be tried in this +order---e.g., @code{("modesetting" "vesa")}. + +@item @code{resolutions} (default: @code{'()}) +When @code{resolutions} is the empty list, Xorg chooses an appropriate +screen resolution. Otherwise, it must be a list of resolutions---e.g., +@code{((1024 768) (640 480))}. + +@cindex keyboard layout, for Xorg +@cindex keymap, for Xorg +@item @code{keyboard-layout} (predeterminada: @code{#f}) +If this is @code{#f}, Xorg uses the default keyboard layout---usually US +English (``qwerty'') for a 105-key PC keyboard. + +Otherwise this must be a @code{keyboard-layout} object specifying the +keyboard layout in use when Xorg is running. @xref{Distribución de teclado}, for +more information on how to specify the keyboard layout. + +@item @code{extra-config} (default: @code{'()}) +This is a list of strings or objects appended to the configuration file. It +is used to pass extra text to be added verbatim to the configuration file. + +@item @code{server} (default: @code{xorg-server}) +This is the package providing the Xorg server. + +@item @code{server-arguments} (default: @code{%default-xorg-server-arguments}) +This is the list of command-line arguments to pass to the X server. The +default is @code{-nolisten tcp}. +@end table +@end deftp + +@deffn {Scheme Procedure} set-xorg-configuration @var{config} @ + [@var{login-manager-service-type}] Tell the log-in manager (of type +@var{login-manager-service-type}) to use @var{config}, an +<xorg-configuration> record. + +Since the Xorg configuration is embedded in the log-in manager's +configuration---e.g., @code{gdm-configuration}---this procedure provides a +shorthand to set the Xorg configuration. +@end deffn + +@deffn {Scheme Procedure} xorg-start-command [@var{config}] +Return a @code{startx} script in which the modules, fonts, etc. specified in +@var{config}, are available. The result should be used in place of +@code{startx}. + +Usually the X server is started by a login manager. +@end deffn + + +@deffn {Procedimiento Scheme} screen-locker-service @var{paquete} [@var{programa}] +Añade @var{paquete}, un paquete para un bloqueador de sesión o un +salvapantallas cuya orden es @var{programa}, al conjunto de programas setuid +y añade una entrada PAM para él. Por ejemplo: + +@lisp +(screen-locker-service xlockmore "xlock") +@end lisp + +permite usar el viejo XlockMore. +@end deffn + + +@node Servicios de impresión +@subsection Servicios de impresión + +@cindex printer support with CUPS +The @code{(gnu services cups)} module provides a Guix service definition for +the CUPS printing service. To add printer support to a Guix system, add a +@code{cups-service} to the operating system definition: + +@deffn {Variable Scheme} cups-service-type +The service type for the CUPS print server. Its value should be a valid +CUPS configuration (see below). To use the default settings, simply write: +@example +(service cups-service-type) +@end example +@end deffn + +The CUPS configuration controls the basic things about your CUPS +installation: what interfaces it listens on, what to do if a print job +fails, how much logging to do, and so on. To actually add a printer, you +have to visit the @url{http://localhost:631} URL, or use a tool such as +GNOME's printer configuration services. By default, configuring a CUPS +service will generate a self-signed certificate if needed, for secure +connections to the print server. + +Suppose you want to enable the Web interface of CUPS and also add support +for Epson printers @i{via} the @code{escpr} package and for HP printers +@i{via} the @code{hplip-minimal} package. You can do that directly, like +this (you need to use the @code{(gnu packages cups)} module): + +@example +(service cups-service-type + (cups-configuration + (web-interface? #t) + (extensions + (list cups-filters escpr hplip-minimal)))) +@end example + +Note: If you wish to use the Qt5 based GUI which comes with the hplip +package then it is suggested that you install the @code{hplip} package, +either in your OS configuration file or as your user. + +The available configuration parameters follow. Each parameter definition is +preceded by its type; for example, @samp{string-list foo} indicates that the +@code{foo} parameter should be specified as a list of strings. There is +also a way to specify the configuration as a string, if you have an old +@code{cupsd.conf} file that you want to port over from some other system; +see the end for more details. + +@c The following documentation was initially generated by +@c (generate-documentation) in (gnu services cups). Manually maintained +@c documentation is better, so we shouldn't hesitate to edit below as +@c needed. However if the change you want to make to this documentation +@c can be done in an automated way, it's probably easier to change +@c (generate-documentation) than to make it below and have to deal with +@c the churn as CUPS updates. + + +Available @code{cups-configuration} fields are: + +@deftypevr {@code{cups-configuration} parameter} package cups +El paquete CUPS. +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} package-list extensions +Drivers and other extensions to the CUPS package. +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} files-configuration files-configuration +Configuration of where to write logs, what directories to use for print +spools, and related privileged configuration parameters. + +Available @code{files-configuration} fields are: + +@deftypevr {@code{files-configuration} parameter} log-location access-log +Defines the access log filename. Specifying a blank filename disables +access log generation. The value @code{stderr} causes log entries to be +sent to the standard error file when the scheduler is running in the +foreground, or to the system log daemon when run in the background. The +value @code{syslog} causes log entries to be sent to the system log daemon. +The server name may be included in filenames using the string @code{%s}, as +in @code{/var/log/cups/%s-access_log}. + +Defaults to @samp{"/var/log/cups/access_log"}. +@end deftypevr + +@deftypevr {@code{files-configuration} parameter} file-name cache-dir +Where CUPS should cache data. + +Defaults to @samp{"/var/cache/cups"}. +@end deftypevr + +@deftypevr {@code{files-configuration} parameter} string config-file-perm +Specifies the permissions for all configuration files that the scheduler +writes. + +Note that the permissions for the printers.conf file are currently masked to +only allow access from the scheduler user (typically root). This is done +because printer device URIs sometimes contain sensitive authentication +information that should not be generally known on the system. There is no +way to disable this security feature. + +Defaults to @samp{"0640"}. +@end deftypevr + +@deftypevr {@code{files-configuration} parameter} log-location error-log +Defines the error log filename. Specifying a blank filename disables access +log generation. The value @code{stderr} causes log entries to be sent to +the standard error file when the scheduler is running in the foreground, or +to the system log daemon when run in the background. The value +@code{syslog} causes log entries to be sent to the system log daemon. The +server name may be included in filenames using the string @code{%s}, as in +@code{/var/log/cups/%s-error_log}. + +Defaults to @samp{"/var/log/cups/error_log"}. +@end deftypevr + +@deftypevr {@code{files-configuration} parameter} string fatal-errors +Specifies which errors are fatal, causing the scheduler to exit. The kind +strings are: + +@table @code +@item none +No errors are fatal. + +@item all +All of the errors below are fatal. + +@item browse +Browsing initialization errors are fatal, for example failed connections to +the DNS-SD daemon. + +@item config +Configuration file syntax errors are fatal. + +@item listen +Listen or Port errors are fatal, except for IPv6 failures on the loopback or +@code{any} addresses. + +@item log +Log file creation or write errors are fatal. + +@item permissions +Bad startup file permissions are fatal, for example shared TLS certificate +and key files with world-read permissions. +@end table + +Defaults to @samp{"all -browse"}. +@end deftypevr + +@deftypevr {@code{files-configuration} parameter} boolean file-device? +Specifies whether the file pseudo-device can be used for new printer +queues. The URI @uref{file:///dev/null} is always allowed. + +El valor predeterminado es @samp{#f} +@end deftypevr + +@deftypevr {@code{files-configuration} parameter} string group +Specifies the group name or ID that will be used when executing external +programs. + +Defaults to @samp{"lp"}. +@end deftypevr + +@deftypevr {@code{files-configuration} parameter} string log-file-perm +Specifies the permissions for all log files that the scheduler writes. + +Defaults to @samp{"0644"}. +@end deftypevr + +@deftypevr {@code{files-configuration} parameter} log-location page-log +Defines the page log filename. Specifying a blank filename disables access +log generation. The value @code{stderr} causes log entries to be sent to +the standard error file when the scheduler is running in the foreground, or +to the system log daemon when run in the background. The value +@code{syslog} causes log entries to be sent to the system log daemon. The +server name may be included in filenames using the string @code{%s}, as in +@code{/var/log/cups/%s-page_log}. + +Defaults to @samp{"/var/log/cups/page_log"}. +@end deftypevr + +@deftypevr {@code{files-configuration} parameter} string remote-root +Specifies the username that is associated with unauthenticated accesses by +clients claiming to be the root user. The default is @code{remroot}. + +Defaults to @samp{"remroot"}. +@end deftypevr + +@deftypevr {@code{files-configuration} parameter} file-name request-root +Specifies the directory that contains print jobs and other HTTP request +data. + +Defaults to @samp{"/var/spool/cups"}. +@end deftypevr + +@deftypevr {@code{files-configuration} parameter} sandboxing sandboxing +Specifies the level of security sandboxing that is applied to print filters, +backends, and other child processes of the scheduler; either @code{relaxed} +or @code{strict}. This directive is currently only used/supported on macOS. + +Defaults to @samp{strict}. +@end deftypevr + +@deftypevr {@code{files-configuration} parameter} file-name server-keychain +Specifies the location of TLS certificates and private keys. CUPS will look +for public and private keys in this directory: a @code{.crt} files for +PEM-encoded certificates and corresponding @code{.key} files for PEM-encoded +private keys. + +Defaults to @samp{"/etc/cups/ssl"}. +@end deftypevr + +@deftypevr {@code{files-configuration} parameter} file-name server-root +Specifies the directory containing the server configuration files. + +Defaults to @samp{"/etc/cups"}. +@end deftypevr + +@deftypevr {@code{files-configuration} parameter} boolean sync-on-close? +Specifies whether the scheduler calls fsync(2) after writing configuration +or state files. + +El valor predeterminado es @samp{#f} +@end deftypevr + +@deftypevr {@code{files-configuration} parameter} space-separated-string-list system-group +Specifies the group(s) to use for @code{@@SYSTEM} group authentication. +@end deftypevr + +@deftypevr {@code{files-configuration} parameter} file-name temp-dir +Specifies the directory where temporary files are stored. + +Defaults to @samp{"/var/spool/cups/tmp"}. +@end deftypevr + +@deftypevr {@code{files-configuration} parameter} string user +Specifies the user name or ID that is used when running external programs. + +Defaults to @samp{"lp"}. +@end deftypevr +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} access-log-level access-log-level +Specifies the logging level for the AccessLog file. The @code{config} level +logs when printers and classes are added, deleted, or modified and when +configuration files are accessed or updated. The @code{actions} level logs +when print jobs are submitted, held, released, modified, or canceled, and +any of the conditions for @code{config}. The @code{all} level logs all +requests. + +Defaults to @samp{actions}. +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} boolean auto-purge-jobs? +Specifies whether to purge job history data automatically when it is no +longer required for quotas. + +El valor predeterminado es @samp{#f} +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} browse-local-protocols browse-local-protocols +Specifies which protocols to use for local printer sharing. + +Defaults to @samp{dnssd}. +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} boolean browse-web-if? +Specifies whether the CUPS web interface is advertised. + +El valor predeterminado es @samp{#f} +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} boolean browsing? +Specifies whether shared printers are advertised. + +El valor predeterminado es @samp{#f} +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} string classification +Specifies the security classification of the server. Any valid banner name +can be used, including "classified", "confidential", "secret", "topsecret", +and "unclassified", or the banner can be omitted to disable secure printing +functions. + +El valor predeterminado es @samp{""}. +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} boolean classify-override? +Specifies whether users may override the classification (cover page) of +individual print jobs using the @code{job-sheets} option. + +El valor predeterminado es @samp{#f} +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} default-auth-type default-auth-type +Specifies the default type of authentication to use. + +Defaults to @samp{Basic}. +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} default-encryption default-encryption +Specifies whether encryption will be used for authenticated requests. + +Defaults to @samp{Required}. +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} string default-language +Specifies the default language to use for text and web content. + +Defaults to @samp{"en"}. +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} string default-paper-size +Specifies the default paper size for new print queues. @samp{"Auto"} uses a +locale-specific default, while @samp{"None"} specifies there is no default +paper size. Specific size names are typically @samp{"Letter"} or +@samp{"A4"}. + +Defaults to @samp{"Auto"}. +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} string default-policy +Specifies the default access policy to use. + +Defaults to @samp{"default"}. +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} boolean default-shared? +Specifies whether local printers are shared by default. + +Defaults to @samp{#t}. +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} non-negative-integer dirty-clean-interval +Specifies the delay for updating of configuration and state files, in +seconds. A value of 0 causes the update to happen as soon as possible, +typically within a few milliseconds. + +El valor predeterminado es @samp{30}. +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} error-policy error-policy +Specifies what to do when an error occurs. Possible values are +@code{abort-job}, which will discard the failed print job; @code{retry-job}, +which will retry the job at a later time; @code{retry-this-job}, which +retries the failed job immediately; and @code{stop-printer}, which stops the +printer. + +Defaults to @samp{stop-printer}. +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} non-negative-integer filter-limit +Specifies the maximum cost of filters that are run concurrently, which can +be used to minimize disk, memory, and CPU resource problems. A limit of 0 +disables filter limiting. An average print to a non-PostScript printer +needs a filter limit of about 200. A PostScript printer needs about half +that (100). Setting the limit below these thresholds will effectively limit +the scheduler to printing a single job at any time. + +El valor predeterminado es @samp{0}. +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} non-negative-integer filter-nice +Specifies the scheduling priority of filters that are run to print a job. +The nice value ranges from 0, the highest priority, to 19, the lowest +priority. + +El valor predeterminado es @samp{0}. +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} host-name-lookups host-name-lookups +Specifies whether to do reverse lookups on connecting clients. The +@code{double} setting causes @code{cupsd} to verify that the hostname +resolved from the address matches one of the addresses returned for that +hostname. Double lookups also prevent clients with unregistered addresses +from connecting to your server. Only set this option to @code{#t} or +@code{double} if absolutely required. + +El valor predeterminado es @samp{#f} +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} non-negative-integer job-kill-delay +Specifies the number of seconds to wait before killing the filters and +backend associated with a canceled or held job. + +El valor predeterminado es @samp{30}. +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} non-negative-integer job-retry-interval +Specifies the interval between retries of jobs in seconds. This is +typically used for fax queues but can also be used with normal print queues +whose error policy is @code{retry-job} or @code{retry-current-job}. + +El valor predeterminado es @samp{30}. +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} non-negative-integer job-retry-limit +Specifies the number of retries that are done for jobs. This is typically +used for fax queues but can also be used with normal print queues whose +error policy is @code{retry-job} or @code{retry-current-job}. + +Defaults to @samp{5}. +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} boolean keep-alive? +Specifies whether to support HTTP keep-alive connections. + +Defaults to @samp{#t}. +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} non-negative-integer keep-alive-timeout +Specifies how long an idle client connection remains open, in seconds. + +El valor predeterminado es @samp{30}. +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} non-negative-integer limit-request-body +Specifies the maximum size of print files, IPP requests, and HTML form +data. A limit of 0 disables the limit check. + +El valor predeterminado es @samp{0}. +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} multiline-string-list listen +Listens on the specified interfaces for connections. Valid values are of +the form @var{address}:@var{port}, where @var{address} is either an IPv6 +address enclosed in brackets, an IPv4 address, or @code{*} to indicate all +addresses. Values can also be file names of local UNIX domain sockets. The +Listen directive is similar to the Port directive but allows you to restrict +access to specific interfaces or networks. +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} non-negative-integer listen-back-log +Specifies the number of pending connections that will be allowed. This +normally only affects very busy servers that have reached the MaxClients +limit, but can also be triggered by large numbers of simultaneous +connections. When the limit is reached, the operating system will refuse +additional connections until the scheduler can accept the pending ones. + +Defaults to @samp{128}. +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} location-access-control-list location-access-controls +Specifies a set of additional access controls. + +Available @code{location-access-controls} fields are: + +@deftypevr {@code{location-access-controls} parameter} file-name path +Specifies the URI path to which the access control applies. +@end deftypevr + +@deftypevr {@code{location-access-controls} parameter} access-control-list access-controls +Access controls for all access to this path, in the same format as the +@code{access-controls} of @code{operation-access-control}. + +Defaults to @samp{()}. +@end deftypevr + +@deftypevr {@code{location-access-controls} parameter} method-access-control-list method-access-controls +Access controls for method-specific access to this path. + +Defaults to @samp{()}. + +Available @code{method-access-controls} fields are: + +@deftypevr {@code{method-access-controls} parameter} boolean reverse? +If @code{#t}, apply access controls to all methods except the listed +methods. Otherwise apply to only the listed methods. + +El valor predeterminado es @samp{#f} +@end deftypevr + +@deftypevr {@code{method-access-controls} parameter} method-list methods +Methods to which this access control applies. + +Defaults to @samp{()}. +@end deftypevr + +@deftypevr {@code{method-access-controls} parameter} access-control-list access-controls +Access control directives, as a list of strings. Each string should be one +directive, such as "Order allow,deny". + +Defaults to @samp{()}. +@end deftypevr +@end deftypevr +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} non-negative-integer log-debug-history +Specifies the number of debugging messages that are retained for logging if +an error occurs in a print job. Debug messages are logged regardless of the +LogLevel setting. + +Defaults to @samp{100}. +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} log-level log-level +Specifies the level of logging for the ErrorLog file. The value @code{none} +stops all logging while @code{debug2} logs everything. + +Defaults to @samp{info}. +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} log-time-format log-time-format +Specifies the format of the date and time in the log files. The value +@code{standard} logs whole seconds while @code{usecs} logs microseconds. + +Defaults to @samp{standard}. +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-clients +Specifies the maximum number of simultaneous clients that are allowed by the +scheduler. + +Defaults to @samp{100}. +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-clients-per-host +Specifies the maximum number of simultaneous clients that are allowed from a +single address. + +Defaults to @samp{100}. +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-copies +Specifies the maximum number of copies that a user can print of each job. + +Defaults to @samp{9999}. +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-hold-time +Specifies the maximum time a job may remain in the @code{indefinite} hold +state before it is canceled. A value of 0 disables cancellation of held +jobs. + +El valor predeterminado es @samp{0}. +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-jobs +Specifies the maximum number of simultaneous jobs that are allowed. Set to +0 to allow an unlimited number of jobs. + +Defaults to @samp{500}. +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-jobs-per-printer +Specifies the maximum number of simultaneous jobs that are allowed per +printer. A value of 0 allows up to MaxJobs jobs per printer. + +El valor predeterminado es @samp{0}. +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-jobs-per-user +Specifies the maximum number of simultaneous jobs that are allowed per +user. A value of 0 allows up to MaxJobs jobs per user. + +El valor predeterminado es @samp{0}. +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-job-time +Specifies the maximum time a job may take to print before it is canceled, in +seconds. Set to 0 to disable cancellation of "stuck" jobs. + +Defaults to @samp{10800}. +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-log-size +Specifies the maximum size of the log files before they are rotated, in +bytes. The value 0 disables log rotation. + +Defaults to @samp{1048576}. +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} non-negative-integer multiple-operation-timeout +Specifies the maximum amount of time to allow between files in a multiple +file print job, in seconds. + +Defaults to @samp{300}. +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} string page-log-format +Specifies the format of PageLog lines. Sequences beginning with percent +(@samp{%}) characters are replaced with the corresponding information, while +all other characters are copied literally. The following percent sequences +are recognized: + +@table @samp +@item %% +insert a single percent character + +@item %@{name@} +insert the value of the specified IPP attribute + +@item %C +insert the number of copies for the current page + +@item %P +insert the current page number + +@item %T +insert the current date and time in common log format + +@item %j +insert the job ID + +@item %p +insert the printer name + +@item %u +insert the username +@end table + +A value of the empty string disables page logging. The string @code{%p %u +%j %T %P %C %@{job-billing@} %@{job-originating-host-name@} %@{job-name@} +%@{media@} %@{sides@}} creates a page log with the standard items. + +El valor predeterminado es @samp{""}. +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} environment-variables environment-variables +Passes the specified environment variable(s) to child processes; a list of +strings. + +Defaults to @samp{()}. +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} policy-configuration-list policies +Specifies named access control policies. + +Available @code{policy-configuration} fields are: + +@deftypevr {@code{policy-configuration} parameter} string name +Name of the policy. +@end deftypevr + +@deftypevr {@code{policy-configuration} parameter} string job-private-access +Specifies an access list for a job's private values. @code{@@ACL} maps to +the printer's requesting-user-name-allowed or requesting-user-name-denied +values. @code{@@OWNER} maps to the job's owner. @code{@@SYSTEM} maps to +the groups listed for the @code{system-group} field of the +@code{files-config} configuration, which is reified into the +@code{cups-files.conf(5)} file. Other possible elements of the access list +include specific user names, and @code{@@@var{group}} to indicate members of +a specific group. The access list may also be simply @code{all} or +@code{default}. + +Defaults to @samp{"@@OWNER @@SYSTEM"}. +@end deftypevr + +@deftypevr {@code{policy-configuration} parameter} string job-private-values +Specifies the list of job values to make private, or @code{all}, +@code{default}, or @code{none}. + +Defaults to @samp{"job-name job-originating-host-name +job-originating-user-name phone"}. +@end deftypevr + +@deftypevr {@code{policy-configuration} parameter} string subscription-private-access +Specifies an access list for a subscription's private values. @code{@@ACL} +maps to the printer's requesting-user-name-allowed or +requesting-user-name-denied values. @code{@@OWNER} maps to the job's +owner. @code{@@SYSTEM} maps to the groups listed for the +@code{system-group} field of the @code{files-config} configuration, which is +reified into the @code{cups-files.conf(5)} file. Other possible elements of +the access list include specific user names, and @code{@@@var{group}} to +indicate members of a specific group. The access list may also be simply +@code{all} or @code{default}. + +Defaults to @samp{"@@OWNER @@SYSTEM"}. +@end deftypevr + +@deftypevr {@code{policy-configuration} parameter} string subscription-private-values +Specifies the list of job values to make private, or @code{all}, +@code{default}, or @code{none}. + +Defaults to @samp{"notify-events notify-pull-method notify-recipient-uri +notify-subscriber-user-name notify-user-data"}. +@end deftypevr + +@deftypevr {@code{policy-configuration} parameter} operation-access-control-list access-controls +Access control by IPP operation. + +Defaults to @samp{()}. +@end deftypevr +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} boolean-or-non-negative-integer preserve-job-files +Specifies whether job files (documents) are preserved after a job is +printed. If a numeric value is specified, job files are preserved for the +indicated number of seconds after printing. Otherwise a boolean value +applies indefinitely. + +Defaults to @samp{86400}. +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} boolean-or-non-negative-integer preserve-job-history +Specifies whether the job history is preserved after a job is printed. If a +numeric value is specified, the job history is preserved for the indicated +number of seconds after printing. If @code{#t}, the job history is +preserved until the MaxJobs limit is reached. + +Defaults to @samp{#t}. +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} non-negative-integer reload-timeout +Specifies the amount of time to wait for job completion before restarting +the scheduler. + +El valor predeterminado es @samp{30}. +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} string rip-cache +Specifies the maximum amount of memory to use when converting documents into +bitmaps for a printer. + +Defaults to @samp{"128m"}. +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} string server-admin +Specifies the email address of the server administrator. + +Defaults to @samp{"root@@localhost.localdomain"}. +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} host-name-list-or-* server-alias +The ServerAlias directive is used for HTTP Host header validation when +clients connect to the scheduler from external interfaces. Using the +special name @code{*} can expose your system to known browser-based DNS +rebinding attacks, even when accessing sites through a firewall. If the +auto-discovery of alternate names does not work, we recommend listing each +alternate name with a ServerAlias directive instead of using @code{*}. + +Defaults to @samp{*}. +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} string server-name +Specifies the fully-qualified host name of the server. + +Defaults to @samp{"localhost"}. +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} server-tokens server-tokens +Specifies what information is included in the Server header of HTTP +responses. @code{None} disables the Server header. @code{ProductOnly} +reports @code{CUPS}. @code{Major} reports @code{CUPS 2}. @code{Minor} +reports @code{CUPS 2.0}. @code{Minimal} reports @code{CUPS 2.0.0}. +@code{OS} reports @code{CUPS 2.0.0 (@var{uname})} where @var{uname} is the +output of the @code{uname} command. @code{Full} reports @code{CUPS 2.0.0 +(@var{uname}) IPP/2.0}. + +Defaults to @samp{Minimal}. +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} string set-env +Set the specified environment variable to be passed to child processes. + +Defaults to @samp{"variable value"}. +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} multiline-string-list ssl-listen +Listens on the specified interfaces for encrypted connections. Valid values +are of the form @var{address}:@var{port}, where @var{address} is either an +IPv6 address enclosed in brackets, an IPv4 address, or @code{*} to indicate +all addresses. + +Defaults to @samp{()}. +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} ssl-options ssl-options +Sets encryption options. By default, CUPS only supports encryption using +TLS v1.0 or higher using known secure cipher suites. The @code{AllowRC4} +option enables the 128-bit RC4 cipher suites, which are required for some +older clients that do not implement newer ones. The @code{AllowSSL3} option +enables SSL v3.0, which is required for some older clients that do not +support TLS v1.0. + +Defaults to @samp{()}. +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} boolean strict-conformance? +Specifies whether the scheduler requires clients to strictly adhere to the +IPP specifications. + +El valor predeterminado es @samp{#f} +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} non-negative-integer timeout +Specifies the HTTP request timeout, in seconds. + +Defaults to @samp{300}. + +@end deftypevr + +@deftypevr {@code{cups-configuration} parameter} boolean web-interface? +Specifies whether the web interface is enabled. + +El valor predeterminado es @samp{#f} +@end deftypevr + +At this point you're probably thinking ``oh dear, Guix manual, I like you +but you can stop already with the configuration options''. Indeed. +However, one more point: it could be that you have an existing +@code{cupsd.conf} that you want to use. In that case, you can pass an +@code{opaque-cups-configuration} as the configuration of a +@code{cups-service-type}. + +Available @code{opaque-cups-configuration} fields are: + +@deftypevr {@code{opaque-cups-configuration} parameter} package cups +El paquete CUPS. +@end deftypevr + +@deftypevr {@code{opaque-cups-configuration} parameter} string cupsd.conf +The contents of the @code{cupsd.conf}, as a string. +@end deftypevr + +@deftypevr {@code{opaque-cups-configuration} parameter} string cups-files.conf +The contents of the @code{cups-files.conf} file, as a string. +@end deftypevr + +For example, if your @code{cupsd.conf} and @code{cups-files.conf} are in +strings of the same name, you could instantiate a CUPS service like this: + +@example +(service cups-service-type + (opaque-cups-configuration + (cupsd.conf cupsd.conf) + (cups-files.conf cups-files.conf))) +@end example + + +@node Servicios de escritorio +@subsection Servicios de escritorio + +The @code{(gnu services desktop)} module provides services that are usually +useful in the context of a ``desktop'' setup---that is, on a machine running +a graphical display server, possibly with graphical user interfaces, etc. +It also defines services that provide specific desktop environments like +GNOME, Xfce or MATE. + +To simplify things, the module defines a variable containing the set of +services that users typically expect on a machine with a graphical +environment and networking: + +@defvr {Variable Scheme} %desktop-services +This is a list of services that builds upon @var{%base-services} and adds or +adjusts services for a typical ``desktop'' setup. + +In particular, it adds a graphical login manager (@pxref{Sistema X Window, +@code{gdm-service-type}}), screen lockers, a network management tool +(@pxref{Servicios de red, @code{network-manager-service-type}}), energy +and color management services, the @code{elogind} login and seat manager, +the Polkit privilege service, the GeoClue location service, the +AccountsService daemon that allows authorized users change system passwords, +an NTP client (@pxref{Servicios de red}), the Avahi daemon, and has the +name service switch service configured to be able to use @code{nss-mdns} +(@pxref{Selector de servicios de nombres, mDNS}). +@end defvr + +The @var{%desktop-services} variable can be used as the @code{services} +field of an @code{operating-system} declaration (@pxref{Referencia de ``operating-system'', @code{services}}). + +Additionally, the @code{gnome-desktop-service-type}, +@code{xfce-desktop-service}, @code{mate-desktop-service-type} and +@code{enlightenment-desktop-service-type} procedures can add GNOME, Xfce, +MATE and/or Enlightenment to a system. To ``add GNOME'' means that +system-level services like the backlight adjustment helpers and the power +management utilities are added to the system, extending @code{polkit} and +@code{dbus} appropriately, allowing GNOME to operate with elevated +privileges on a limited number of special-purpose system interfaces. +Additionally, adding a service made by @code{gnome-desktop-service-type} +adds the GNOME metapackage to the system profile. Likewise, adding the Xfce +service not only adds the @code{xfce} metapackage to the system profile, but +it also gives the Thunar file manager the ability to open a ``root-mode'' +file management window, if the user authenticates using the administrator's +password via the standard polkit graphical interface. To ``add MATE'' means +that @code{polkit} and @code{dbus} are extended appropriately, allowing MATE +to operate with elevated privileges on a limited number of special-purpose +system interfaces. Additionally, adding a service of type +@code{mate-desktop-service-type} adds the MATE metapackage to the system +profile. ``Adding Enlightenment'' means that @code{dbus} is extended +appropriately, and several of Enlightenment's binaries are set as setuid, +allowing Enlightenment's screen locker and other functionality to work as +expetected. + +The desktop environments in Guix use the Xorg display server by default. If +you'd like to use the newer display server protocol called Wayland, you need +to use the @code{sddm-service} instead of GDM as the graphical login +manager. You should then select the ``GNOME (Wayland)'' session in SDDM. +Alternatively you can also try starting GNOME on Wayland manually from a TTY +with the command ``XDG_SESSION_TYPE=wayland exec dbus-run-session +gnome-session``. Currently only GNOME has support for Wayland. + +@defvr {Scheme Variable} gnome-desktop-service-type +This is the type of the service that adds the @uref{https://www.gnome.org, +GNOME} desktop environment. Its value is a +@code{gnome-desktop-configuration} object (see below.) + +This service adds the @code{gnome} package to the system profile, and +extends polkit with the actions from @code{gnome-settings-daemon}. +@end defvr + +@deftp {Data Type} gnome-desktop-configuration +Configuration record for the GNOME desktop environment. + +@table @asis +@item @code{gnome} (default @code{gnome}) +The GNOME package to use. +@end table +@end deftp + +@defvr {Scheme Variable} xfce-desktop-service-type +This is the type of a service to run the @uref{Xfce, https://xfce.org/} +desktop environment. Its value is an @code{xfce-desktop-configuration} +object (see below.) + +This service that adds the @code{xfce} package to the system profile, and +extends polkit with the ability for @code{thunar} to manipulate the file +system as root from within a user session, after the user has authenticated +with the administrator's password. +@end defvr + +@deftp {Data Type} xfce-desktop-configuration +Configuration record for the Xfce desktop environment. + +@table @asis +@item @code{xfce} (default @code{xfce}) +The Xfce package to use. +@end table +@end deftp + +@deffn {Scheme Variable} mate-desktop-service-type +This is the type of the service that runs the +@uref{https://mate-desktop.org/, MATE desktop environment}. Its value is a +@code{mate-desktop-configuration} object (see below.) + +This service adds the @code{mate} package to the system profile, and extends +polkit with the actions from @code{mate-settings-daemon}. +@end deffn + +@deftp {Data Type} mate-desktop-configuration +Configuration record for the MATE desktop environment. + +@table @asis +@item @code{mate} (default @code{mate}) +The MATE package to use. +@end table +@end deftp + +@deffn {Scheme Variable} enlightenment-desktop-service-type +Return a service that adds the @code{enlightenment} package to the system +profile, and extends dbus with actions from @code{efl}. +@end deffn + +@deftp {Tipo de datos} enlightenment-desktop-service-configuration +@table @asis +@item @code{enlightenment} (predeterminado @code{enlightenment}) +El paquete enlightenment usado. +@end table +@end deftp + +Because the GNOME, Xfce and MATE desktop services pull in so many packages, +the default @code{%desktop-services} variable doesn't include any of them by +default. To add GNOME, Xfce or MATE, just @code{cons} them onto +@code{%desktop-services} in the @code{services} field of your +@code{operating-system}: + +@example +(use-modules (gnu)) +(use-service-modules desktop) +(operating-system + ... + ;; cons* adds items to the list given as its last argument. + (services (cons* (service gnome-desktop-service-type) + (service xfce-desktop-service) + %desktop-services)) + ...) +@end example + +These desktop environments will then be available as options in the +graphical login window. + +The actual service definitions included in @code{%desktop-services} and +provided by @code{(gnu services dbus)} and @code{(gnu services desktop)} are +described below. + +@deffn {Procedimiento Scheme} dbus-service [#:dbus @var{dbus}] [#:services '()] +Return a service that runs the ``system bus'', using @var{dbus}, with +support for @var{services}. + +@uref{http://dbus.freedesktop.org/, D-Bus} is an inter-process communication +facility. Its system bus is used to allow system services to communicate +and to be notified of system-wide events. + +@var{services} must be a list of packages that provide an +@file{etc/dbus-1/system.d} directory containing additional D-Bus +configuration and policy files. For example, to allow avahi-daemon to use +the system bus, @var{services} must be equal to @code{(list avahi)}. +@end deffn + +@deffn {Procedimiento Scheme} elogind-service [#:config @var{config}] +Return a service that runs the @code{elogind} login and seat management +daemon. @uref{https://github.com/elogind/elogind, Elogind} exposes a D-Bus +interface that can be used to know which users are logged in, know what kind +of sessions they have open, suspend the system, inhibit system suspend, +reboot the system, and other tasks. + +Elogind handles most system-level power events for a computer, for example +suspending the system when a lid is closed, or shutting it down when the +power button is pressed. + +The @var{config} keyword argument specifies the configuration for elogind, +and should be the result of an @code{(elogind-configuration (@var{parameter} +@var{value})...)} invocation. Available parameters and their default values +are: + +@table @code +@item kill-user-processes? +@code{#f} +@item kill-only-users +@code{()} +@item kill-exclude-users +@code{("root")} +@item inhibit-delay-max-seconds +@code{5} +@item handle-power-key +@code{poweroff} +@item handle-suspend-key +@code{suspend} +@item handle-hibernate-key +@code{hibernate} +@item handle-lid-switch +@code{suspend} +@item handle-lid-switch-docked +@code{ignore} +@item power-key-ignore-inhibited? +@code{#f} +@item suspend-key-ignore-inhibited? +@code{#f} +@item hibernate-key-ignore-inhibited? +@code{#f} +@item lid-switch-ignore-inhibited? +@code{#t} +@item holdoff-timeout-seconds +@code{30} +@item idle-action +@code{ignore} +@item idle-action-seconds +@code{(* 30 60)} +@item runtime-directory-size-percent +@code{10} +@item runtime-directory-size +@code{#f} +@item remove-ipc? +@code{#t} +@item suspend-state +@code{("mem" "standby" "freeze")} +@item suspend-mode +@code{()} +@item hibernate-state +@code{("disk")} +@item hibernate-mode +@code{("platform" "shutdown")} +@item hybrid-sleep-state +@code{("disk")} +@item hybrid-sleep-mode +@code{("suspend" "platform" "shutdown")} +@end table +@end deffn + +@deffn {Procedimiento Scheme} accountsservice-service @ + [#:accountsservice @var{accountsservice}] Return a service that runs +AccountsService, a system service that can list available accounts, change +their passwords, and so on. AccountsService integrates with PolicyKit to +enable unprivileged users to acquire the capability to modify their system +configuration. +@uref{https://www.freedesktop.org/wiki/Software/AccountsService/, the +accountsservice web site} for more information. + +The @var{accountsservice} keyword argument is the @code{accountsservice} +package to expose as a service. +@end deffn + +@deffn {Procedimiento Scheme} polkit-service @ + [#:polkit @var{polkit}] Return a service that runs the +@uref{http://www.freedesktop.org/wiki/Software/polkit/, Polkit privilege +management service}, which allows system administrators to grant access to +privileged operations in a structured way. By querying the Polkit service, +a privileged system component can know when it should grant additional +capabilities to ordinary users. For example, an ordinary user can be +granted the capability to suspend the system if the user is logged in +locally. +@end deffn + +@defvr {Scheme Variable} upower-service-type +Service that runs @uref{http://upower.freedesktop.org/, @command{upowerd}}, +a system-wide monitor for power consumption and battery levels, with the +given configuration settings. + +It implements the @code{org.freedesktop.UPower} D-Bus interface, and is +notably used by GNOME. +@end defvr + +@deftp {Data Type} upower-configuration +Data type representation the configuration for UPower. + +@table @asis + +@item @code{upower} (default: @var{upower}) +Package to use for @code{upower}. + +@item @code{watts-up-pro?} (default: @code{#f}) +Enable the Watts Up Pro device. + +@item @code{poll-batteries?} (default: @code{#t}) +Enable polling the kernel for battery level changes. + +@item @code{ignore-lid?} (default: @code{#f}) +Ignore the lid state, this can be useful if it's incorrect on a device. + +@item @code{use-percentage-for-policy?} (default: @code{#f}) +Whether battery percentage based policy should be used. The default is to +use the time left, change to @code{#t} to use the percentage. + +@item @code{percentage-low} (default: @code{10}) +When @code{use-percentage-for-policy?} is @code{#t}, this sets the +percentage at which the battery is considered low. + +@item @code{percentage-critical} (default: @code{3}) +When @code{use-percentage-for-policy?} is @code{#t}, this sets the +percentage at which the battery is considered critical. + +@item @code{percentage-action} (default: @code{2}) +When @code{use-percentage-for-policy?} is @code{#t}, this sets the +percentage at which action will be taken. + +@item @code{time-low} (default: @code{1200}) +When @code{use-time-for-policy?} is @code{#f}, this sets the time remaining +in seconds at which the battery is considered low. + +@item @code{time-critical} (default: @code{300}) +When @code{use-time-for-policy?} is @code{#f}, this sets the time remaining +in seconds at which the battery is considered critical. + +@item @code{time-action} (default: @code{120}) +When @code{use-time-for-policy?} is @code{#f}, this sets the time remaining +in seconds at which action will be taken. + +@item @code{critical-power-action} (default: @code{'hybrid-sleep}) +The action taken when @code{percentage-action} or @code{time-action} is +reached (depending on the configuration of +@code{use-percentage-for-policy?}). + +Possible values are: + +@itemize @bullet +@item +@code{'power-off} + +@item +@code{'hibernate} + +@item +@code{'hybrid-sleep}. +@end itemize + +@end table +@end deftp + +@deffn {Procedimiento Scheme} udisks-service [#:udisks @var{udisks}] +Return a service for @uref{http://udisks.freedesktop.org/docs/latest/, +UDisks}, a @dfn{disk management} daemon that provides user interfaces with +notifications and ways to mount/unmount disks. Programs that talk to UDisks +include the @command{udisksctl} command, part of UDisks, and GNOME Disks. +@end deffn + +@deffn {Procedimiento Scheme} colord-service [#:colord @var{colord}] +Return a service that runs @command{colord}, a system service with a D-Bus +interface to manage the color profiles of input and output devices such as +screens and scanners. It is notably used by the GNOME Color Manager +graphical tool. See @uref{http://www.freedesktop.org/software/colord/, the +colord web site} for more information. +@end deffn + +@deffn {Scheme Procedure} geoclue-application name [#:allowed? #t] [#:system? #f] [#:users '()] +Return a configuration allowing an application to access GeoClue location +data. @var{name} is the Desktop ID of the application, without the +@code{.desktop} part. If @var{allowed?} is true, the application will have +access to location information by default. The boolean @var{system?} value +indicates whether an application is a system component or not. Finally +@var{users} is a list of UIDs of all users for which this application is +allowed location info access. An empty users list means that all users are +allowed. +@end deffn + +@defvr {Variable Scheme} %standard-geoclue-applications +The standard list of well-known GeoClue application configurations, granting +authority to the GNOME date-and-time utility to ask for the current location +in order to set the time zone, and allowing the IceCat and Epiphany web +browsers to request location information. IceCat and Epiphany both query +the user before allowing a web page to know the user's location. +@end defvr + +@deffn {Procedimiento Scheme} geoclue-service [#:colord @var{colord}] @ + [#:whitelist '()] @ [#:wifi-geolocation-url +"https://location.services.mozilla.com/v1/geolocate?key=geoclue"] @ +[#:submit-data? #f] [#:wifi-submission-url +"https://location.services.mozilla.com/v1/submit?key=geoclue"] @ +[#:submission-nick "geoclue"] @ [#:applications +%standard-geoclue-applications] Return a service that runs the GeoClue +location service. This service provides a D-Bus interface to allow +applications to request access to a user's physical location, and optionally +to add information to online location databases. See +@uref{https://wiki.freedesktop.org/www/Software/GeoClue/, the GeoClue web +site} for more information. +@end deffn + +@deffn {Procedimiento Scheme} bluetooth-service [#:bluez @var{bluez}] @ + [@w{#:auto-enable? #f}] Return a service that runs the @command{bluetoothd} +daemon, which manages all the Bluetooth devices and provides a number of +D-Bus interfaces. When AUTO-ENABLE? is true, the bluetooth controller is +powered automatically at boot, which can be useful when using a bluetooth +keyboard or mouse. + +Users need to be in the @code{lp} group to access the D-Bus service. +@end deffn + +@node Servicios de sonido +@subsection Servicios de sonido + +@cindex sound support +@cindex ALSA +@cindex PulseAudio, sound support + +The @code{(gnu services sound)} module provides a service to configure the +Advanced Linux Sound Architecture (ALSA) system, which makes PulseAudio the +preferred ALSA output driver. + +@deffn {Variable Scheme} alsa-service-type +This is the type for the @uref{https://alsa-project.org/, Advanced Linux +Sound Architecture} (ALSA) system, which generates the +@file{/etc/asound.conf} configuration file. The value for this type is a +@command{alsa-configuration} record as in this example: + +@example +(service alsa-service-type) +@end example + +See below for details about @code{alsa-configuration}. +@end deffn + +@deftp {Tipo de datos} alsa-configuration +Data type representing the configuration for @code{alsa-service}. + +@table @asis +@item @code{alsa-plugins} (predeterminados: @var{alsa-plugins}) +El paquete @code{alsa-plugins} usado. + +@item @code{pulseaudio?} (predeterminado: @var{#t}) +Whether ALSA applications should transparently be made to use the +@uref{http://www.pulseaudio.org/, PulseAudio} sound server. + +Using PulseAudio allows you to run several sound-producing applications at +the same time and to individual control them @i{via} @command{pavucontrol}, +among other things. + +@item @code{extra-options} (predeterminado: @var{""}) +String to append to the @file{/etc/asound.conf} file. + +@end table +@end deftp + +Individual users who want to override the system configuration of ALSA can +do it with the @file{~/.asoundrc} file: + +@example +# In guix, we have to specify the absolute path for plugins. +pcm_type.jack @{ + lib "/home/alice/.guix-profile/lib/alsa-lib/libasound_module_pcm_jack.so" +@} + +# Routing ALSA to jack: +# <http://jackaudio.org/faq/routing_alsa.html>. +pcm.rawjack @{ + type jack + playback_ports @{ + 0 system:playback_1 + 1 system:playback_2 + @} + + capture_ports @{ + 0 system:capture_1 + 1 system:capture_2 + @} +@} + +pcm.!default @{ + type plug + slave @{ + pcm "rawjack" + @} +@} +@end example + +See @uref{https://www.alsa-project.org/main/index.php/Asoundrc} for the +details. + + +@node Servicios de bases de datos +@subsection Servicios de bases de datos + +@cindex base de datos +@cindex SQL +El módulo @code{(gnu services databases)} proporciona los siguientes +servicios. + +@deffn {Procedimiento Scheme} postgresql-service [#:postgresql postgresql] @ + [#:config-file] [#:data-directory ``/var/lib/postgresql/data''] @ [#:port +5432] [#:locale ``en_US.utf8''] [#:extension-packages '()] Return a service +that runs @var{postgresql}, the PostgreSQL database server. + +The PostgreSQL daemon loads its runtime configuration from +@var{config-file}, creates a database cluster with @var{locale} as the +default locale, stored in @var{data-directory}. It then listens on +@var{port}. + +@cindex postgresql extension-packages +Additional extensions are loaded from packages listed in +@var{extension-packages}. Extensions are available at runtime. For +instance, to create a geographic database using the @code{postgis} +extension, a user can configure the postgresql-service as in this example: + +@cindex postgis +@example +(use-package-modules databases geo) + +(operating-system + ... + ;; postgresql is required to run `psql' but postgis is not required for + ;; proper operation. + (packages (cons* postgresql %base-packages)) + (services + (cons* + (postgresql-service #:extension-packages (list postgis)) + %base-services))) +@end example + +Then the extension becomes visible and you can initialise an empty +geographic database in this way: + +@example +psql -U postgres +> create database postgistest; +> \connect postgistest; +> create extension postgis; +> create extension postgis_topology; +@end example + +There is no need to add this field for contrib extensions such as hstore or +dblink as they are already loadable by postgresql. This field is only +required to add extensions provided by other packages. +@end deffn + +@deffn {Procedimiento Scheme} mysql-service [#:config (mysql-configuration)] +Return a service that runs @command{mysqld}, the MySQL or MariaDB database +server. + +El parámetro opcional @var{config} especifica la configuración para +@command{mysqld}, que debe ser un objeto @code{<mysql-configuration>}. +@end deffn + +@deftp {Tipo de datos} mysql-configuration +Data type representing the configuration of @var{mysql-service}. + +@table @asis +@item @code{mysql} (predeterminado: @var{mariadb}) +Package object of the MySQL database server, can be either @var{mariadb} or +@var{mysql}. + +For MySQL, a temporary root password will be displayed at activation time. +For MariaDB, the root password is empty. + +@item @code{port} (predeterminado: @code{3306}) +TCP port on which the database server listens for incoming connections. +@end table +@end deftp + +@defvr {Variable Scheme} memcached-service-type +This is the service type for the @uref{https://memcached.org/, Memcached} +service, which provides a distributed in memory cache. The value for the +service type is a @code{memcached-configuration} object. +@end defvr + +@example +(service memcached-service-type) +@end example + +@deftp {Tipo de datos} memcached-configuration +Data type representing the configuration of memcached. + +@table @asis +@item @code{memcached} (predeterminado: @code{memcached}) +El paquete de Memcached usado. + +@item @code{interfaces} (predeterminadas: @code{'("0.0.0.0")}) +Network interfaces on which to listen. + +@item @code{tcp-port} (predeterminado: @code{11211}) +Port on which to accept connections on, + +@item @code{udp-port} (predeterminado: @code{11211}) +Port on which to accept UDP connections on, a value of 0 will disable +listening on a UDP socket. + +@item @code{additional-options} (predeterminadas: @code{'()}) +Additional command line options to pass to @code{memcached}. +@end table +@end deftp + +@defvr {Variable Scheme} mongodb-service-type +This is the service type for @uref{https://www.mongodb.com/, MongoDB}. The +value for the service type is a @code{mongodb-configuration} object. +@end defvr + +@example +(service mongodb-service-type) +@end example + +@deftp {Tipo de datos} mongodb-configuration +Tipo de datos que representa la configuración de GPM. + +@table @asis +@item @code{mongodb} (predeterminado: @code{mongodb}) +El paquete MongoDB usado. + +@item @code{config-file} (predeterminado: @code{%default-mongodb-configuration-file}) +The configuration file for MongoDB. + +@item @code{data-directory} (predeterminado: @code{"/var/lib/mongodb"}) +This value is used to create the directory, so that it exists and is owned +by the mongodb user. It should match the data-directory which MongoDB is +configured to use through the configuration file. +@end table +@end deftp + +@defvr {Variable Scheme} redis-service-type +This is the service type for the @uref{https://redis.io/, Redis} key/value +store, whose value is a @code{redis-configuration} object. +@end defvr + +@deftp {Tipo de datos} redis-configuration +Data type representing the configuration of redis. + +@table @asis +@item @code{redis} (predeterminado: @code{redis}) +The Redis package to use. + +@item @code{bind} (predeterminada: @code{"127.0.0.1"}) +La interfaz de red en la que se escucha. + +@item @code{port} (predeterminado: @code{6379}) +Port on which to accept connections on, a value of 0 will disable listening +on a TCP socket. + +@item @code{working-directory} (predeterminado: @code{"/var/lib/redis"}) +Directory in which to store the database and related files. +@end table +@end deftp + +@node Servicios de correo +@subsection Servicios de correo + +@cindex mail +@cindex email +The @code{(gnu services mail)} module provides Guix service definitions for +email services: IMAP, POP3, and LMTP servers, as well as mail transport +agents (MTAs). Lots of acronyms! These services are detailed in the +subsections below. + +@subsubheading Servicio Dovecot + +@deffn {Procedimiento Scheme} dovecot-service [#:config (dovecot-configuration)] +Return a service that runs the Dovecot IMAP/POP3/LMTP mail server. +@end deffn + +By default, Dovecot does not need much configuration; the default +configuration object created by @code{(dovecot-configuration)} will suffice +if your mail is delivered to @code{~/Maildir}. A self-signed certificate +will be generated for TLS-protected connections, though Dovecot will also +listen on cleartext ports by default. There are a number of options, +though, which mail administrators might need to change, and as is the case +with other services, Guix allows the system administrator to specify these +parameters via a uniform Scheme interface. + +Por ejemplo, para especificar que el correo se encuentra en +@code{maildir:~/.correo}, se debe instanciar el servicio de Dovecot de esta +manera: + +@example +(dovecot-service #:config + (dovecot-configuration + (mail-location "maildir:~/.correo"))) +@end example + +The available configuration parameters follow. Each parameter definition is +preceded by its type; for example, @samp{string-list foo} indicates that the +@code{foo} parameter should be specified as a list of strings. There is +also a way to specify the configuration as a string, if you have an old +@code{dovecot.conf} file that you want to port over from some other system; +see the end for more details. + +@c The following documentation was initially generated by +@c (generate-documentation) in (gnu services mail). Manually maintained +@c documentation is better, so we shouldn't hesitate to edit below as +@c needed. However if the change you want to make to this documentation +@c can be done in an automated way, it's probably easier to change +@c (generate-documentation) than to make it below and have to deal with +@c the churn as dovecot updates. + +Available @code{dovecot-configuration} fields are: + +@deftypevr {@code{dovecot-configuration} parameter} package dovecot +El paquete dovecot. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} comma-separated-string-list listen +A list of IPs or hosts where to listen for connections. @samp{*} listens on +all IPv4 interfaces, @samp{::} listens on all IPv6 interfaces. If you want +to specify non-default ports or anything more complex, customize the address +and port fields of the @samp{inet-listener} of the specific services you are +interested in. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} protocol-configuration-list protocols +List of protocols we want to serve. Available protocols include +@samp{imap}, @samp{pop3}, and @samp{lmtp}. + +Available @code{protocol-configuration} fields are: + +@deftypevr {@code{protocol-configuration} parameter} string name +El nombre del protocolo. +@end deftypevr + +@deftypevr {@code{protocol-configuration} parameter} string auth-socket-path +UNIX socket path to the master authentication server to find users. This is +used by imap (for shared users) and lda. It defaults to +@samp{"/var/run/dovecot/auth-userdb"}. +@end deftypevr + +@deftypevr {@code{protocol-configuration} parameter} space-separated-string-list mail-plugins +Space separated list of plugins to load. +@end deftypevr + +@deftypevr {@code{protocol-configuration} parameter} non-negative-integer mail-max-userip-connections +Maximum number of IMAP connections allowed for a user from each IP address. +NOTE: The username is compared case-sensitively. Defaults to @samp{10}. +@end deftypevr + +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} service-configuration-list services +List of services to enable. Available services include @samp{imap}, +@samp{imap-login}, @samp{pop3}, @samp{pop3-login}, @samp{auth}, and +@samp{lmtp}. + +Available @code{service-configuration} fields are: + +@deftypevr {@code{service-configuration} parameter} string kind +The service kind. Valid values include @code{director}, @code{imap-login}, +@code{pop3-login}, @code{lmtp}, @code{imap}, @code{pop3}, @code{auth}, +@code{auth-worker}, @code{dict}, @code{tcpwrap}, @code{quota-warning}, or +anything else. +@end deftypevr + +@deftypevr {@code{service-configuration} parameter} listener-configuration-list listeners +Listeners for the service. A listener is either a +@code{unix-listener-configuration}, a @code{fifo-listener-configuration}, or +an @code{inet-listener-configuration}. Defaults to @samp{()}. + +Available @code{unix-listener-configuration} fields are: + +@deftypevr {@code{unix-listener-configuration} parameter} string path +Path to the file, relative to @code{base-dir} field. This is also used as +the section name. +@end deftypevr + +@deftypevr {@code{unix-listener-configuration} parameter} string mode +The access mode for the socket. Defaults to @samp{"0600"}. +@end deftypevr + +@deftypevr {@code{unix-listener-configuration} parameter} string user +The user to own the socket. Defaults to @samp{""}. +@end deftypevr + +@deftypevr {@code{unix-listener-configuration} parameter} string group +The group to own the socket. Defaults to @samp{""}. +@end deftypevr + + +Available @code{fifo-listener-configuration} fields are: + +@deftypevr {@code{fifo-listener-configuration} parameter} string path +Path to the file, relative to @code{base-dir} field. This is also used as +the section name. +@end deftypevr + +@deftypevr {@code{fifo-listener-configuration} parameter} string mode +The access mode for the socket. Defaults to @samp{"0600"}. +@end deftypevr + +@deftypevr {@code{fifo-listener-configuration} parameter} string user +The user to own the socket. Defaults to @samp{""}. +@end deftypevr + +@deftypevr {@code{fifo-listener-configuration} parameter} string group +The group to own the socket. Defaults to @samp{""}. +@end deftypevr + + +Available @code{inet-listener-configuration} fields are: + +@deftypevr {@code{inet-listener-configuration} parameter} string protocol +The protocol to listen for. +@end deftypevr + +@deftypevr {@code{inet-listener-configuration} parameter} string address +The address on which to listen, or empty for all addresses. Defaults to +@samp{""}. +@end deftypevr + +@deftypevr {@code{inet-listener-configuration} parameter} non-negative-integer port +The port on which to listen. +@end deftypevr + +@deftypevr {@code{inet-listener-configuration} parameter} boolean ssl? +Whether to use SSL for this service; @samp{yes}, @samp{no}, or +@samp{required}. Defaults to @samp{#t}. +@end deftypevr + +@end deftypevr + +@deftypevr {@code{service-configuration} parameter} non-negative-integer client-limit +Maximum number of simultaneous client connections per process. Once this +number of connections is received, the next incoming connection will prompt +Dovecot to spawn another process. If set to 0, @code{default-client-limit} +is used instead. + +El valor predeterminado es @samp{0}. + +@end deftypevr + +@deftypevr {@code{service-configuration} parameter} non-negative-integer service-count +Number of connections to handle before starting a new process. Typically +the only useful values are 0 (unlimited) or 1. 1 is more secure, but 0 is +faster. <doc/wiki/LoginProcess.txt>. Defaults to @samp{1}. + +@end deftypevr + +@deftypevr {@code{service-configuration} parameter} non-negative-integer process-limit +Maximum number of processes that can exist for this service. If set to 0, +@code{default-process-limit} is used instead. + +El valor predeterminado es @samp{0}. + +@end deftypevr + +@deftypevr {@code{service-configuration} parameter} non-negative-integer process-min-avail +Number of processes to always keep waiting for more connections. Defaults +to @samp{0}. +@end deftypevr + +@deftypevr {@code{service-configuration} parameter} non-negative-integer vsz-limit +If you set @samp{service-count 0}, you probably need to grow this. Defaults +to @samp{256000000}. +@end deftypevr + +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} dict-configuration dict +Dict configuration, as created by the @code{dict-configuration} constructor. + +Available @code{dict-configuration} fields are: + +@deftypevr {@code{dict-configuration} parameter} free-form-fields entries +A list of key-value pairs that this dict should hold. Defaults to +@samp{()}. +@end deftypevr + +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} passdb-configuration-list passdbs +A list of passdb configurations, each one created by the +@code{passdb-configuration} constructor. + +Available @code{passdb-configuration} fields are: + +@deftypevr {@code{passdb-configuration} parameter} string driver +The driver that the passdb should use. Valid values include @samp{pam}, +@samp{passwd}, @samp{shadow}, @samp{bsdauth}, and @samp{static}. Defaults +to @samp{"pam"}. +@end deftypevr + +@deftypevr {@code{passdb-configuration} parameter} space-separated-string-list args +Space separated list of arguments to the passdb driver. Defaults to +@samp{""}. +@end deftypevr + +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} userdb-configuration-list userdbs +List of userdb configurations, each one created by the +@code{userdb-configuration} constructor. + +Available @code{userdb-configuration} fields are: + +@deftypevr {@code{userdb-configuration} parameter} string driver +The driver that the userdb should use. Valid values include @samp{passwd} +and @samp{static}. Defaults to @samp{"passwd"}. +@end deftypevr + +@deftypevr {@code{userdb-configuration} parameter} space-separated-string-list args +Space separated list of arguments to the userdb driver. Defaults to +@samp{""}. +@end deftypevr + +@deftypevr {@code{userdb-configuration} parameter} free-form-args override-fields +Override fields from passwd. Defaults to @samp{()}. +@end deftypevr + +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} plugin-configuration plugin-configuration +Plug-in configuration, created by the @code{plugin-configuration} +constructor. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} list-of-namespace-configuration namespaces +List of namespaces. Each item in the list is created by the +@code{namespace-configuration} constructor. + +Available @code{namespace-configuration} fields are: + +@deftypevr {@code{namespace-configuration} parameter} string name +Name for this namespace. +@end deftypevr + +@deftypevr {@code{namespace-configuration} parameter} string type +Namespace type: @samp{private}, @samp{shared} or @samp{public}. Defaults to +@samp{"private"}. +@end deftypevr + +@deftypevr {@code{namespace-configuration} parameter} string separator +Hierarchy separator to use. You should use the same separator for all +namespaces or some clients get confused. @samp{/} is usually a good one. +The default however depends on the underlying mail storage format. Defaults +to @samp{""}. +@end deftypevr + +@deftypevr {@code{namespace-configuration} parameter} string prefix +Prefix required to access this namespace. This needs to be different for +all namespaces. For example @samp{Public/}. Defaults to @samp{""}. +@end deftypevr + +@deftypevr {@code{namespace-configuration} parameter} string location +Physical location of the mailbox. This is in the same format as +mail_location, which is also the default for it. Defaults to @samp{""}. +@end deftypevr + +@deftypevr {@code{namespace-configuration} parameter} boolean inbox? +There can be only one INBOX, and this setting defines which namespace has +it. Defaults to @samp{#f}. +@end deftypevr + +@deftypevr {@code{namespace-configuration} parameter} boolean hidden? +If namespace is hidden, it's not advertised to clients via NAMESPACE +extension. You'll most likely also want to set @samp{list? #f}. This is +mostly useful when converting from another server with different namespaces +which you want to deprecate but still keep working. For example you can +create hidden namespaces with prefixes @samp{~/mail/}, @samp{~%u/mail/} and +@samp{mail/}. Defaults to @samp{#f}. +@end deftypevr + +@deftypevr {@code{namespace-configuration} parameter} boolean list? +Show the mailboxes under this namespace with the LIST command. This makes +the namespace visible for clients that do not support the NAMESPACE +extension. The special @code{children} value lists child mailboxes, but +hides the namespace prefix. Defaults to @samp{#t}. +@end deftypevr + +@deftypevr {@code{namespace-configuration} parameter} boolean subscriptions? +Namespace handles its own subscriptions. If set to @code{#f}, the parent +namespace handles them. The empty prefix should always have this as +@code{#t}). Defaults to @samp{#t}. +@end deftypevr + +@deftypevr {@code{namespace-configuration} parameter} mailbox-configuration-list mailboxes +List of predefined mailboxes in this namespace. Defaults to @samp{()}. + +Available @code{mailbox-configuration} fields are: + +@deftypevr {@code{mailbox-configuration} parameter} string name +Name for this mailbox. +@end deftypevr + +@deftypevr {@code{mailbox-configuration} parameter} string auto +@samp{create} will automatically create this mailbox. @samp{subscribe} will +both create and subscribe to the mailbox. Defaults to @samp{"no"}. +@end deftypevr + +@deftypevr {@code{mailbox-configuration} parameter} space-separated-string-list special-use +List of IMAP @code{SPECIAL-USE} attributes as specified by RFC 6154. Valid +values are @code{\All}, @code{\Archive}, @code{\Drafts}, @code{\Flagged}, +@code{\Junk}, @code{\Sent}, and @code{\Trash}. Defaults to @samp{()}. +@end deftypevr + +@end deftypevr + +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} file-name base-dir +Base directory where to store runtime data. Defaults to +@samp{"/var/run/dovecot/"}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string login-greeting +Greeting message for clients. Defaults to @samp{"Dovecot ready."}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list login-trusted-networks +List of trusted network ranges. Connections from these IPs are allowed to +override their IP addresses and ports (for logging and for authentication +checks). @samp{disable-plaintext-auth} is also ignored for these networks. +Typically you would specify your IMAP proxy servers here. Defaults to +@samp{()}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list login-access-sockets +List of login access check sockets (e.g.@: tcpwrap). Defaults to @samp{()}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} boolean verbose-proctitle? +Show more verbose process titles (in ps). Currently shows user name and IP +address. Useful for seeing who is actually using the IMAP processes (e.g.@: +shared mailboxes or if the same uid is used for multiple accounts). +Defaults to @samp{#f}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} boolean shutdown-clients? +Should all processes be killed when Dovecot master process shuts down. +Setting this to @code{#f} means that Dovecot can be upgraded without forcing +existing client connections to close (although that could also be a problem +if the upgrade is e.g.@: due to a security fix). Defaults to @samp{#t}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer doveadm-worker-count +If non-zero, run mail commands via this many connections to doveadm server, +instead of running them directly in the same process. Defaults to @samp{0}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string doveadm-socket-path +UNIX socket or host:port used for connecting to doveadm server. Defaults to +@samp{"doveadm-server"}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list import-environment +List of environment variables that are preserved on Dovecot startup and +passed down to all of its child processes. You can also give key=value +pairs to always set specific settings. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} boolean disable-plaintext-auth? +Disable LOGIN command and all other plaintext authentications unless SSL/TLS +is used (LOGINDISABLED capability). Note that if the remote IP matches the +local IP (i.e.@: you're connecting from the same computer), the connection +is considered secure and plaintext authentication is allowed. See also +ssl=required setting. Defaults to @samp{#t}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer auth-cache-size +Authentication cache size (e.g.@: @samp{#e10e6}). 0 means it's disabled. +Note that bsdauth, PAM and vpopmail require @samp{cache-key} to be set for +caching to be used. Defaults to @samp{0}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string auth-cache-ttl +Time to live for cached data. After TTL expires the cached record is no +longer used, *except* if the main database lookup returns internal failure. +We also try to handle password changes automatically: If user's previous +authentication was successful, but this one wasn't, the cache isn't used. +For now this works only with plaintext authentication. Defaults to @samp{"1 +hour"}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string auth-cache-negative-ttl +TTL for negative hits (user not found, password mismatch). 0 disables +caching them completely. Defaults to @samp{"1 hour"}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list auth-realms +List of realms for SASL authentication mechanisms that need them. You can +leave it empty if you don't want to support multiple realms. Many clients +simply use the first one listed here, so keep the default realm first. +Defaults to @samp{()}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string auth-default-realm +Default realm/domain to use if none was specified. This is used for both +SASL realms and appending @@domain to username in plaintext logins. +Defaults to @samp{""}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string auth-username-chars +List of allowed characters in username. If the user-given username contains +a character not listed in here, the login automatically fails. This is just +an extra check to make sure user can't exploit any potential quote escaping +vulnerabilities with SQL/LDAP databases. If you want to allow all +characters, set this value to empty. Defaults to +@samp{"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ01234567890.-_@@"}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string auth-username-translation +Username character translations before it's looked up from databases. The +value contains series of from -> to characters. For example @samp{#@@/@@} +means that @samp{#} and @samp{/} characters are translated to @samp{@@}. +Defaults to @samp{""}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string auth-username-format +Username formatting before it's looked up from databases. You can use the +standard variables here, e.g.@: %Lu would lowercase the username, %n would +drop away the domain if it was given, or @samp{%n-AT-%d} would change the +@samp{@@} into @samp{-AT-}. This translation is done after +@samp{auth-username-translation} changes. Defaults to @samp{"%Lu"}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string auth-master-user-separator +If you want to allow master users to log in by specifying the master +username within the normal username string (i.e.@: not using SASL +mechanism's support for it), you can specify the separator character here. +The format is then <username><separator><master username>. UW-IMAP uses +@samp{*} as the separator, so that could be a good choice. Defaults to +@samp{""}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string auth-anonymous-username +Username to use for users logging in with ANONYMOUS SASL mechanism. +Defaults to @samp{"anonymous"}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer auth-worker-max-count +Maximum number of dovecot-auth worker processes. They're used to execute +blocking passdb and userdb queries (e.g.@: MySQL and PAM). They're +automatically created and destroyed as needed. Defaults to @samp{30}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string auth-gssapi-hostname +Host name to use in GSSAPI principal names. The default is to use the name +returned by gethostname(). Use @samp{$ALL} (with quotes) to allow all +keytab entries. Defaults to @samp{""}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string auth-krb5-keytab +Kerberos keytab to use for the GSSAPI mechanism. Will use the system +default (usually @file{/etc/krb5.keytab}) if not specified. You may need to +change the auth service to run as root to be able to read this file. +Defaults to @samp{""}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} boolean auth-use-winbind? +Do NTLM and GSS-SPNEGO authentication using Samba's winbind daemon and +@samp{ntlm-auth} helper. <doc/wiki/Authentication/Mechanisms/Winbind.txt>. +Defaults to @samp{#f}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} file-name auth-winbind-helper-path +Path for Samba's @samp{ntlm-auth} helper binary. Defaults to +@samp{"/usr/bin/ntlm_auth"}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string auth-failure-delay +Time to delay before replying to failed authentications. Defaults to +@samp{"2 secs"}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} boolean auth-ssl-require-client-cert? +Require a valid SSL client certificate or the authentication fails. +Defaults to @samp{#f}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} boolean auth-ssl-username-from-cert? +Take the username from client's SSL certificate, using +@code{X509_NAME_get_text_by_NID()} which returns the subject's DN's +CommonName. Defaults to @samp{#f}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list auth-mechanisms +List of wanted authentication mechanisms. Supported mechanisms are: +@samp{plain}, @samp{login}, @samp{digest-md5}, @samp{cram-md5}, @samp{ntlm}, +@samp{rpa}, @samp{apop}, @samp{anonymous}, @samp{gssapi}, @samp{otp}, +@samp{skey}, and @samp{gss-spnego}. NOTE: See also +@samp{disable-plaintext-auth} setting. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list director-servers +List of IPs or hostnames to all director servers, including ourself. Ports +can be specified as ip:port. The default port is the same as what director +service's @samp{inet-listener} is using. Defaults to @samp{()}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list director-mail-servers +List of IPs or hostnames to all backend mail servers. Ranges are allowed +too, like 10.0.0.10-10.0.0.30. Defaults to @samp{()}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string director-user-expire +How long to redirect users to a specific server after it no longer has any +connections. Defaults to @samp{"15 min"}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string director-username-hash +How the username is translated before being hashed. Useful values include +%Ln if user can log in with or without @@domain, %Ld if mailboxes are shared +within domain. Defaults to @samp{"%Lu"}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string log-path +Log file to use for error messages. @samp{syslog} logs to syslog, +@samp{/dev/stderr} logs to stderr. Defaults to @samp{"syslog"}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string info-log-path +Log file to use for informational messages. Defaults to @samp{log-path}. +Defaults to @samp{""}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string debug-log-path +Log file to use for debug messages. Defaults to @samp{info-log-path}. +Defaults to @samp{""}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string syslog-facility +Syslog facility to use if you're logging to syslog. Usually if you don't +want to use @samp{mail}, you'll use local0..local7. Also other standard +facilities are supported. Defaults to @samp{"mail"}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} boolean auth-verbose? +Log unsuccessful authentication attempts and the reasons why they failed. +Defaults to @samp{#f}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} boolean auth-verbose-passwords? +In case of password mismatches, log the attempted password. Valid values +are no, plain and sha1. sha1 can be useful for detecting brute force +password attempts vs. user simply trying the same password over and over +again. You can also truncate the value to n chars by appending ":n" (e.g.@: +sha1:6). Defaults to @samp{#f}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} boolean auth-debug? +Even more verbose logging for debugging purposes. Shows for example SQL +queries. Defaults to @samp{#f}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} boolean auth-debug-passwords? +In case of password mismatches, log the passwords and used scheme so the +problem can be debugged. Enabling this also enables @samp{auth-debug}. +Defaults to @samp{#f}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} boolean mail-debug? +Enable mail process debugging. This can help you figure out why Dovecot +isn't finding your mails. Defaults to @samp{#f}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} boolean verbose-ssl? +Show protocol level SSL errors. Defaults to @samp{#f}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string log-timestamp +Prefix for each line written to log file. % codes are in strftime(3) +format. Defaults to @samp{"\"%b %d %H:%M:%S \""}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list login-log-format-elements +List of elements we want to log. The elements which have a non-empty +variable value are joined together to form a comma-separated string. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string login-log-format +Login log format. %s contains @samp{login-log-format-elements} string, %$ +contains the data we want to log. Defaults to @samp{"%$: %s"}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string mail-log-prefix +Log prefix for mail processes. See doc/wiki/Variables.txt for list of +possible variables you can use. Defaults to +@samp{"\"%s(%u)<%@{pid@}><%@{session@}>: \""}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string deliver-log-format +Format to use for logging mail deliveries. You can use variables: +@table @code +@item %$ +Delivery status message (e.g.@: @samp{saved to INBOX}) +@item %m +Message-ID +@item %s +Subject +@item %f +From address +@item %p +Tamaño físico +@item %w +Tamaño virtual. +@end table +Defaults to @samp{"msgid=%m: %$"}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string mail-location +Location for users' mailboxes. The default is empty, which means that +Dovecot tries to find the mailboxes automatically. This won't work if the +user doesn't yet have any mail, so you should explicitly tell Dovecot the +full location. + +If you're using mbox, giving a path to the INBOX file (e.g.@: /var/mail/%u) +isn't enough. You'll also need to tell Dovecot where the other mailboxes +are kept. This is called the "root mail directory", and it must be the +first path given in the @samp{mail-location} setting. + +There are a few special variables you can use, eg.: + +@table @samp +@item %u +username +@item %n +user part in user@@domain, same as %u if there's no domain +@item %d +domain part in user@@domain, empty if there's no domain +@item %h +home director +@end table + +See doc/wiki/Variables.txt for full list. Some examples: +@table @samp +@item maildir:~/Maildir +@item mbox:~/mail:INBOX=/var/mail/%u +@item mbox:/var/mail/%d/%1n/%n:INDEX=/var/indexes/%d/%1n/% +@end table +El valor predeterminado es @samp{""}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string mail-uid +System user and group used to access mails. If you use multiple, userdb can +override these by returning uid or gid fields. You can use either numbers +or names. <doc/wiki/UserIds.txt>. Defaults to @samp{""}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string mail-gid + +El valor predeterminado es @samp{""}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string mail-privileged-group +Group to enable temporarily for privileged operations. Currently this is +used only with INBOX when either its initial creation or dotlocking fails. +Typically this is set to "mail" to give access to /var/mail. Defaults to +@samp{""}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string mail-access-groups +Grant access to these supplementary groups for mail processes. Typically +these are used to set up access to shared mailboxes. Note that it may be +dangerous to set these if users can create symlinks (e.g.@: if "mail" group +is set here, ln -s /var/mail ~/mail/var could allow a user to delete others' +mailboxes, or ln -s /secret/shared/box ~/mail/mybox would allow reading +it). Defaults to @samp{""}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} boolean mail-full-filesystem-access? +Allow full file system access to clients. There's no access checks other +than what the operating system does for the active UID/GID. It works with +both maildir and mboxes, allowing you to prefix mailboxes names with e.g.@: +/path/ or ~user/. Defaults to @samp{#f}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} boolean mmap-disable? +Don't use mmap() at all. This is required if you store indexes to shared +file systems (NFS or clustered file system). Defaults to @samp{#f}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} boolean dotlock-use-excl? +Rely on @samp{O_EXCL} to work when creating dotlock files. NFS supports +@samp{O_EXCL} since version 3, so this should be safe to use nowadays by +default. Defaults to @samp{#t}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string mail-fsync +When to use fsync() or fdatasync() calls: +@table @code +@item optimized +Whenever necessary to avoid losing important data +@item always +Useful with e.g.@: NFS when write()s are delayed +@item never +Never use it (best performance, but crashes can lose data). +@end table +Defaults to @samp{"optimized"}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} boolean mail-nfs-storage? +Mail storage exists in NFS. Set this to yes to make Dovecot flush NFS +caches whenever needed. If you're using only a single mail server this +isn't needed. Defaults to @samp{#f}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} boolean mail-nfs-index? +Mail index files also exist in NFS. Setting this to yes requires +@samp{mmap-disable? #t} and @samp{fsync-disable? #f}. Defaults to +@samp{#f}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string lock-method +Locking method for index files. Alternatives are fcntl, flock and dotlock. +Dotlocking uses some tricks which may create more disk I/O than other +locking methods. NFS users: flock doesn't work, remember to change +@samp{mmap-disable}. Defaults to @samp{"fcntl"}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} file-name mail-temp-dir +Directory in which LDA/LMTP temporarily stores incoming mails >128 kB. +Defaults to @samp{"/tmp"}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer first-valid-uid +Valid UID range for users. This is mostly to make sure that users can't log +in as daemons or other system users. Note that denying root logins is +hardcoded to dovecot binary and can't be done even if @samp{first-valid-uid} +is set to 0. Defaults to @samp{500}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer last-valid-uid + +El valor predeterminado es @samp{0}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer first-valid-gid +Valid GID range for users. Users having non-valid GID as primary group ID +aren't allowed to log in. If user belongs to supplementary groups with +non-valid GIDs, those groups are not set. Defaults to @samp{1}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer last-valid-gid + +El valor predeterminado es @samp{0}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mail-max-keyword-length +Maximum allowed length for mail keyword name. It's only forced when trying +to create new keywords. Defaults to @samp{50}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} colon-separated-file-name-list valid-chroot-dirs +List of directories under which chrooting is allowed for mail processes +(i.e.@: /var/mail will allow chrooting to /var/mail/foo/bar too). This +setting doesn't affect @samp{login-chroot} @samp{mail-chroot} or auth chroot +settings. If this setting is empty, "/./" in home dirs are ignored. +WARNING: Never add directories here which local users can modify, that may +lead to root exploit. Usually this should be done only if you don't allow +shell access for users. <doc/wiki/Chrooting.txt>. Defaults to @samp{()}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string mail-chroot +Default chroot directory for mail processes. This can be overridden for +specific users in user database by giving /./ in user's home directory +(e.g.@: /home/./user chroots into /home). Note that usually there is no +real need to do chrooting, Dovecot doesn't allow users to access files +outside their mail directory anyway. If your home directories are prefixed +with the chroot directory, append "/."@: to @samp{mail-chroot}. +<doc/wiki/Chrooting.txt>. Defaults to @samp{""}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} file-name auth-socket-path +UNIX socket path to master authentication server to find users. This is +used by imap (for shared users) and lda. Defaults to +@samp{"/var/run/dovecot/auth-userdb"}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} file-name mail-plugin-dir +Directory where to look up mail plugins. Defaults to +@samp{"/usr/lib/dovecot"}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list mail-plugins +List of plugins to load for all services. Plugins specific to IMAP, LDA, +etc.@: are added to this list in their own .conf files. Defaults to +@samp{()}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mail-cache-min-mail-count +The minimum number of mails in a mailbox before updates are done to cache +file. This allows optimizing Dovecot's behavior to do less disk writes at +the cost of more disk reads. Defaults to @samp{0}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string mailbox-idle-check-interval +When IDLE command is running, mailbox is checked once in a while to see if +there are any new mails or other changes. This setting defines the minimum +time to wait between those checks. Dovecot can also use dnotify, inotify +and kqueue to find out immediately when changes occur. Defaults to +@samp{"30 secs"}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} boolean mail-save-crlf? +Save mails with CR+LF instead of plain LF. This makes sending those mails +take less CPU, especially with sendfile() syscall with Linux and FreeBSD. +But it also creates a bit more disk I/O which may just make it slower. Also +note that if other software reads the mboxes/maildirs, they may handle the +extra CRs wrong and cause problems. Defaults to @samp{#f}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} boolean maildir-stat-dirs? +By default LIST command returns all entries in maildir beginning with a +dot. Enabling this option makes Dovecot return only entries which are +directories. This is done by stat()ing each entry, so it causes more disk +I/O. (For systems setting struct @samp{dirent->d_type} this check is free +and it's done always regardless of this setting). Defaults to @samp{#f}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} boolean maildir-copy-with-hardlinks? +When copying a message, do it with hard links whenever possible. This makes +the performance much better, and it's unlikely to have any side effects. +Defaults to @samp{#t}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} boolean maildir-very-dirty-syncs? +Assume Dovecot is the only MUA accessing Maildir: Scan cur/ directory only +when its mtime changes unexpectedly or when we can't find the mail +otherwise. Defaults to @samp{#f}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list mbox-read-locks +Which locking methods to use for locking mbox. There are four available: + +@table @code +@item dotlock +Create <mailbox>.lock file. This is the oldest and most NFS-safe solution. +If you want to use /var/mail/ like directory, the users will need write +access to that directory. +@item dotlock-try +Same as dotlock, but if it fails because of permissions or because there +isn't enough disk space, just skip it. +@item fcntl +Use this if possible. Works with NFS too if lockd is used. +@item flock +May not exist in all systems. Doesn't work with NFS. +@item lockf +May not exist in all systems. Doesn't work with NFS. +@end table + +You can use multiple locking methods; if you do the order they're declared +in is important to avoid deadlocks if other MTAs/MUAs are using multiple +locking methods as well. Some operating systems don't allow using some of +them simultaneously. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list mbox-write-locks + +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string mbox-lock-timeout +Maximum time to wait for lock (all of them) before aborting. Defaults to +@samp{"5 mins"}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string mbox-dotlock-change-timeout +If dotlock exists but the mailbox isn't modified in any way, override the +lock file after this much time. Defaults to @samp{"2 mins"}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} boolean mbox-dirty-syncs? +When mbox changes unexpectedly we have to fully read it to find out what +changed. If the mbox is large this can take a long time. Since the change +is usually just a newly appended mail, it'd be faster to simply read the new +mails. If this setting is enabled, Dovecot does this but still safely +fallbacks to re-reading the whole mbox file whenever something in mbox isn't +how it's expected to be. The only real downside to this setting is that if +some other MUA changes message flags, Dovecot doesn't notice it +immediately. Note that a full sync is done with SELECT, EXAMINE, EXPUNGE +and CHECK commands. Defaults to @samp{#t}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} boolean mbox-very-dirty-syncs? +Like @samp{mbox-dirty-syncs}, but don't do full syncs even with SELECT, +EXAMINE, EXPUNGE or CHECK commands. If this is set, @samp{mbox-dirty-syncs} +is ignored. Defaults to @samp{#f}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} boolean mbox-lazy-writes? +Delay writing mbox headers until doing a full write sync (EXPUNGE and CHECK +commands and when closing the mailbox). This is especially useful for POP3 +where clients often delete all mails. The downside is that our changes +aren't immediately visible to other MUAs. Defaults to @samp{#t}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mbox-min-index-size +If mbox size is smaller than this (e.g.@: 100k), don't write index files. +If an index file already exists it's still read, just not updated. Defaults +to @samp{0}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mdbox-rotate-size +Maximum dbox file size until it's rotated. Defaults to @samp{10000000}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string mdbox-rotate-interval +Maximum dbox file age until it's rotated. Typically in days. Day begins +from midnight, so 1d = today, 2d = yesterday, etc. 0 = check disabled. +Defaults to @samp{"1d"}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} boolean mdbox-preallocate-space? +When creating new mdbox files, immediately preallocate their size to +@samp{mdbox-rotate-size}. This setting currently works only in Linux with +some file systems (ext4, xfs). Defaults to @samp{#f}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string mail-attachment-dir +sdbox and mdbox support saving mail attachments to external files, which +also allows single instance storage for them. Other backends don't support +this for now. + +WARNING: This feature hasn't been tested much yet. Use at your own risk. + +Directory root where to store mail attachments. Disabled, if empty. +Defaults to @samp{""}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mail-attachment-min-size +Attachments smaller than this aren't saved externally. It's also possible +to write a plugin to disable saving specific attachments externally. +Defaults to @samp{128000}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string mail-attachment-fs +File system backend to use for saving attachments: +@table @code +@item posix +No SiS done by Dovecot (but this might help FS's own deduplication) +@item sis posix +SiS with immediate byte-by-byte comparison during saving +@item sis-queue posix +SiS with delayed comparison and deduplication. +@end table +Defaults to @samp{"sis posix"}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string mail-attachment-hash +Hash format to use in attachment filenames. You can add any text and +variables: @code{%@{md4@}}, @code{%@{md5@}}, @code{%@{sha1@}}, +@code{%@{sha256@}}, @code{%@{sha512@}}, @code{%@{size@}}. Variables can be +truncated, e.g.@: @code{%@{sha256:80@}} returns only first 80 bits. +Defaults to @samp{"%@{sha1@}"}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer default-process-limit + +Defaults to @samp{100}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer default-client-limit + +Defaults to @samp{1000}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer default-vsz-limit +Default VSZ (virtual memory size) limit for service processes. This is +mainly intended to catch and kill processes that leak memory before they eat +up everything. Defaults to @samp{256000000}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string default-login-user +Login user is internally used by login processes. This is the most +untrusted user in Dovecot system. It shouldn't have access to anything at +all. Defaults to @samp{"dovenull"}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string default-internal-user +Internal user is used by unprivileged processes. It should be separate from +login user, so that login processes can't disturb other processes. Defaults +to @samp{"dovecot"}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string ssl? +SSL/TLS support: yes, no, required. <doc/wiki/SSL.txt>. Defaults to +@samp{"required"}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string ssl-cert +PEM encoded X.509 SSL/TLS certificate (public key). Defaults to +@samp{"</etc/dovecot/default.pem"}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string ssl-key +PEM encoded SSL/TLS private key. The key is opened before dropping root +privileges, so keep the key file unreadable by anyone but root. Defaults to +@samp{"</etc/dovecot/private/default.pem"}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string ssl-key-password +If key file is password protected, give the password here. Alternatively +give it when starting dovecot with -p parameter. Since this file is often +world-readable, you may want to place this setting instead to a different. +Defaults to @samp{""}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string ssl-ca +PEM encoded trusted certificate authority. Set this only if you intend to +use @samp{ssl-verify-client-cert? #t}. The file should contain the CA +certificate(s) followed by the matching CRL(s). (e.g.@: @samp{ssl-ca +</etc/ssl/certs/ca.pem}). Defaults to @samp{""}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} boolean ssl-require-crl? +Require that CRL check succeeds for client certificates. Defaults to +@samp{#t}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} boolean ssl-verify-client-cert? +Request client to send a certificate. If you also want to require it, set +@samp{auth-ssl-require-client-cert? #t} in auth section. Defaults to +@samp{#f}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string ssl-cert-username-field +Which field from certificate to use for username. commonName and +x500UniqueIdentifier are the usual choices. You'll also need to set +@samp{auth-ssl-username-from-cert? #t}. Defaults to @samp{"commonName"}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string ssl-min-protocol +Minimum SSL protocol version to accept. Defaults to @samp{"TLSv1"}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string ssl-cipher-list +SSL ciphers to use. Defaults to +@samp{"ALL:!kRSA:!SRP:!kDHd:!DSS:!aNULL:!eNULL:!EXPORT:!DES:!3DES:!MD5:!PSK:!RC4:!ADH:!LOW@@STRENGTH"}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string ssl-crypto-device +SSL crypto device to use, for valid values run "openssl engine". Defaults +to @samp{""}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string postmaster-address +Address to use when sending rejection mails. %d expands to recipient +domain. Defaults to @samp{"postmaster@@%d"}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string hostname +Hostname to use in various parts of sent mails (e.g.@: in Message-Id) and +in LMTP replies. Default is the system's real hostname@@domain. Defaults +to @samp{""}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} boolean quota-full-tempfail? +If user is over quota, return with temporary failure instead of bouncing the +mail. Defaults to @samp{#f}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} file-name sendmail-path +Binary to use for sending mails. Defaults to @samp{"/usr/sbin/sendmail"}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string submission-host +If non-empty, send mails via this SMTP host[:port] instead of sendmail. +Defaults to @samp{""}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string rejection-subject +Subject: header to use for rejection mails. You can use the same variables +as for @samp{rejection-reason} below. Defaults to @samp{"Rejected: %s"}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string rejection-reason +Human readable error message for rejection mails. You can use variables: + +@table @code +@item %n +CRLF +@item %r +reason +@item %s +original subject +@item %t +recipient +@end table +Defaults to @samp{"Your message to <%t> was automatically rejected:%n%r"}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string recipient-delimiter +Delimiter character between local-part and detail in email address. +Defaults to @samp{"+"}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string lda-original-recipient-header +Header where the original recipient address (SMTP's RCPT TO: address) is +taken from if not available elsewhere. With dovecot-lda -a parameter +overrides this. A commonly used header for this is X-Original-To. Defaults +to @samp{""}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} boolean lda-mailbox-autocreate? +Should saving a mail to a nonexistent mailbox automatically create it?. +Defaults to @samp{#f}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} boolean lda-mailbox-autosubscribe? +Should automatically created mailboxes be also automatically subscribed?. +Defaults to @samp{#f}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer imap-max-line-length +Maximum IMAP command line length. Some clients generate very long command +lines with huge mailboxes, so you may need to raise this if you get "Too +long argument" or "IMAP command line too large" errors often. Defaults to +@samp{64000}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string imap-logout-format +IMAP logout format string: +@table @code +@item %i +número total de bytes leídos del cliente +@item %o +número total de bytes enviados al cliente. +@end table +See @file{doc/wiki/Variables.txt} for a list of all the variables you can +use. Defaults to @samp{"in=%i out=%o deleted=%@{deleted@} +expunged=%@{expunged@} trashed=%@{trashed@} hdr_count=%@{fetch_hdr_count@} +hdr_bytes=%@{fetch_hdr_bytes@} body_count=%@{fetch_body_count@} +body_bytes=%@{fetch_body_bytes@}"}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string imap-capability +Override the IMAP CAPABILITY response. If the value begins with '+', add +the given capabilities on top of the defaults (e.g.@: +XFOO XBAR). Defaults +to @samp{""}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string imap-idle-notify-interval +How long to wait between "OK Still here" notifications when client is +IDLEing. Defaults to @samp{"2 mins"}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string imap-id-send +ID field names and values to send to clients. Using * as the value makes +Dovecot use the default value. The following fields have default values +currently: name, version, os, os-version, support-url, support-email. +Defaults to @samp{""}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string imap-id-log +ID fields sent by client to log. * means everything. Defaults to +@samp{""}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list imap-client-workarounds +Workarounds for various client bugs: + +@table @code +@item delay-newmail +Send EXISTS/RECENT new mail notifications only when replying to NOOP and +CHECK commands. Some clients ignore them otherwise, for example OSX Mail +(<v2.1). Outlook Express breaks more badly though, without this it may show +user "Message no longer in server" errors. Note that OE6 still breaks even +with this workaround if synchronization is set to "Headers Only". + +@item tb-extra-mailbox-sep +Thunderbird gets somehow confused with LAYOUT=fs (mbox and dbox) and adds +extra @samp{/} suffixes to mailbox names. This option causes Dovecot to +ignore the extra @samp{/} instead of treating it as invalid mailbox name. + +@item tb-lsub-flags +Show \Noselect flags for LSUB replies with LAYOUT=fs (e.g.@: mbox). This +makes Thunderbird realize they aren't selectable and show them greyed out, +instead of only later giving "not selectable" popup error. +@end table +Defaults to @samp{()}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string imap-urlauth-host +Host allowed in URLAUTH URLs sent by client. "*" allows all. Defaults to +@samp{""}. +@end deftypevr + + +Whew! Lots of configuration options. The nice thing about it though is that +Guix has a complete interface to Dovecot's configuration language. This +allows not only a nice way to declare configurations, but also offers +reflective capabilities as well: users can write code to inspect and +transform configurations from within Scheme. + +However, it could be that you just want to get a @code{dovecot.conf} up and +running. In that case, you can pass an @code{opaque-dovecot-configuration} +as the @code{#:config} parameter to @code{dovecot-service}. As its name +indicates, an opaque configuration does not have easy reflective +capabilities. + +Available @code{opaque-dovecot-configuration} fields are: + +@deftypevr {@code{opaque-dovecot-configuration} parameter} package dovecot +El paquete dovecot. +@end deftypevr + +@deftypevr {@code{opaque-dovecot-configuration} parameter} string string +The contents of the @code{dovecot.conf}, as a string. +@end deftypevr + +For example, if your @code{dovecot.conf} is just the empty string, you could +instantiate a dovecot service like this: + +@example +(dovecot-service #:config + (opaque-dovecot-configuration + (string ""))) +@end example + +@subsubheading Servicio OpenSMTPD + +@deffn {Variable Scheme} opensmtpd-service-type +This is the type of the @uref{https://www.opensmtpd.org, OpenSMTPD} service, +whose value should be an @code{opensmtpd-configuration} object as in this +example: + +@example +(service opensmtpd-service-type + (opensmtpd-configuration + (config-file (local-file "./mi-smtpd.conf")))) +@end example +@end deffn + +@deftp {Tipo de datos} opensmtpd-configuration +Data type representing the configuration of opensmtpd. + +@table @asis +@item @code{package} (predeterminado: @var{opensmtpd}) +El objeto paquete del servidor SMTP OpenSMTPD. + +@item @code{config-file} (predeterminado: @var{%default-opensmtpd-file}) +File-like object of the OpenSMTPD configuration file to use. By default it +listens on the loopback network interface, and allows for mail from users +and daemons on the local machine, as well as permitting email to remote +servers. Run @command{man smtpd.conf} for more information. + +@end table +@end deftp + +@subsubheading Servicio Exim + +@cindex mail transfer agent (MTA) +@cindex MTA (mail transfer agent) +@cindex SMTP + +@deffn {Variable Scheme} exim-service-type +This is the type of the @uref{https://exim.org, Exim} mail transfer agent +(MTA), whose value should be an @code{exim-configuration} object as in this +example: + +@example +(service exim-service-type + (exim-configuration + (config-file (local-file "./mi-exim.conf")))) +@end example +@end deffn + +In order to use an @code{exim-service-type} service you must also have a +@code{mail-aliases-service-type} service present in your +@code{operating-system} (even if it has no aliases). + +@deftp {Tipo de datos} exim-configuration +Tipo de datos que representa la configuración de exim. + +@table @asis +@item @code{package} (predeterminado: @var{exim}) +Package object of the Exim server. + +@item @code{config-file} (predeterminado: @code{#f}) +File-like object of the Exim configuration file to use. If its value is +@code{#f} then use the default configuration file from the package provided +in @code{package}. The resulting configuration file is loaded after setting +the @code{exim_user} and @code{exim_group} configuration variables. + +@end table +@end deftp + +@subsubheading Servicios de alias de correo + +@cindex correo electrónico, alias +@cindex alias, para direcciones de correo electrónico + +@deffn {Variable Scheme} mail-aliases-service-type +This is the type of the service which provides @code{/etc/aliases}, +specifying how to deliver mail to users on this system. + +@example +(service mail-aliases-service-type + '(("postmaster" "rober") + ("rober" "rober@@example.com" "rober@@example2.com"))) +@end example +@end deffn + +The configuration for a @code{mail-aliases-service-type} service is an +association list denoting how to deliver mail that comes to this +system. Each entry is of the form @code{(alias addresses ...)}, with +@code{alias} specifying the local alias and @code{addresses} specifying +where to deliver this user's mail. + +The aliases aren't required to exist as users on the local system. In the +above example, there doesn't need to be a @code{postmaster} entry in the +@code{operating-system}'s @code{user-accounts} in order to deliver the +@code{postmaster} mail to @code{bob} (which subsequently would deliver mail +to @code{bob@@example.com} and @code{bob@@example2.com}). + +@subsubheading GNU Mailutils IMAP4 Daemon +@cindex GNU Mailutils IMAP4 Daemon + +@deffn {Scheme Variable} imap4d-service-type +This is the type of the GNU Mailutils IMAP4 Daemon (@pxref{imap4d,,, +mailutils, GNU Mailutils Manual}), whose value should be an +@code{imap4d-configuration} object as in this example: + +@example +(service imap4d-service-type + (imap4d-configuration + (config-file (local-file "imap4d.conf")))) +@end example +@end deffn + +@deftp {Data Type} imap4d-configuration +Data type representing the configuration of @command{imap4d}. + +@table @asis +@item @code{package} (default: @code{mailutils}) +The package that provides @command{imap4d}. + +@item @code{config-file} (default: @code{%default-imap4d-config-file}) +File-like object of the configuration file to use, by default it will listen +on TCP port 143 of @code{localhost}. @xref{Conf-imap4d,,, mailutils, GNU +Mailutils Manual}, for details. + +@end table +@end deftp + +@node Servicios de mensajería +@subsection Servicios de mensajería + +@cindex messaging +@cindex jabber +@cindex XMPP +The @code{(gnu services messaging)} module provides Guix service definitions +for messaging services: currently only Prosody is supported. + +@subsubheading Servicio Prosody + +@deffn {Variable Scheme} prosody-service-type +This is the type for the @uref{https://prosody.im, Prosody XMPP +communication server}. Its value must be a @code{prosody-configuration} +record as in this example: + +@example +(service prosody-service-type + (prosody-configuration + (modules-enabled (cons "groups" "mam" %default-modules-enabled)) + (int-components + (list + (int-component-configuration + (hostname "conference.example.net") + (plugin "muc") + (mod-muc (mod-muc-configuration))))) + (virtualhosts + (list + (virtualhost-configuration + (domain "example.net")))))) +@end example + +See below for details about @code{prosody-configuration}. + +@end deffn + +By default, Prosody does not need much configuration. Only one +@code{virtualhosts} field is needed: it specifies the domain you wish +Prosody to serve. + +You can perform various sanity checks on the generated configuration with +the @code{prosodyctl check} command. + +Prosodyctl will also help you to import certificates from the +@code{letsencrypt} directory so that the @code{prosody} user can access +them. See @url{https://prosody.im/doc/letsencrypt}. + +@example +prosodyctl --root cert import /etc/letsencrypt/live +@end example + +The available configuration parameters follow. Each parameter definition is +preceded by its type; for example, @samp{string-list foo} indicates that the +@code{foo} parameter should be specified as a list of strings. Types +starting with @code{maybe-} denote parameters that won't show up in +@code{prosody.cfg.lua} when their value is @code{'disabled}. + +There is also a way to specify the configuration as a string, if you have an +old @code{prosody.cfg.lua} file that you want to port over from some other +system; see the end for more details. + +The @code{file-object} type designates either a file-like object +(@pxref{Expresiones-G, file-like objects}) or a file name. + +@c The following documentation was initially generated by +@c (generate-documentation) in (gnu services messaging). Manually maintained +@c documentation is better, so we shouldn't hesitate to edit below as +@c needed. However if the change you want to make to this documentation +@c can be done in an automated way, it's probably easier to change +@c (generate-documentation) than to make it below and have to deal with +@c the churn as Prosody updates. + +Available @code{prosody-configuration} fields are: + +@deftypevr {@code{prosody-configuration} parameter} package prosody +El paquete Prosody. +@end deftypevr + +@deftypevr {@code{prosody-configuration} parameter} file-name data-path +Location of the Prosody data storage directory. See +@url{https://prosody.im/doc/configure}. Defaults to +@samp{"/var/lib/prosody"}. +@end deftypevr + +@deftypevr {@code{prosody-configuration} parameter} file-object-list plugin-paths +Additional plugin directories. They are searched in all the specified paths +in order. See @url{https://prosody.im/doc/plugins_directory}. Defaults to +@samp{()}. +@end deftypevr + +@deftypevr {@code{prosody-configuration} parameter} file-name certificates +Every virtual host and component needs a certificate so that clients and +servers can securely verify its identity. Prosody will automatically load +certificates/keys from the directory specified here. Defaults to +@samp{"/etc/prosody/certs"}. +@end deftypevr + +@deftypevr {@code{prosody-configuration} parameter} string-list admins +This is a list of accounts that are admins for the server. Note that you +must create the accounts separately. See +@url{https://prosody.im/doc/admins} and +@url{https://prosody.im/doc/creating_accounts}. Example: @code{(admins +'("user1@@example.com" "user2@@example.net"))} Defaults to @samp{()}. +@end deftypevr + +@deftypevr {@code{prosody-configuration} parameter} boolean use-libevent? +Enable use of libevent for better performance under high load. See +@url{https://prosody.im/doc/libevent}. Defaults to @samp{#f}. +@end deftypevr + +@deftypevr {@code{prosody-configuration} parameter} module-list modules-enabled +This is the list of modules Prosody will load on startup. It looks for +@code{mod_modulename.lua} in the plugins folder, so make sure that exists +too. Documentation on modules can be found at: +@url{https://prosody.im/doc/modules}. Defaults to @samp{("roster" +"saslauth" "tls" "dialback" "disco" "carbons" "private" "blocklist" "vcard" +"version" "uptime" "time" "ping" "pep" "register" "admin_adhoc")}. +@end deftypevr + +@deftypevr {@code{prosody-configuration} parameter} string-list modules-disabled +@samp{"offline"}, @samp{"c2s"} and @samp{"s2s"} are auto-loaded, but should +you want to disable them then add them to this list. Defaults to @samp{()}. +@end deftypevr + +@deftypevr {@code{prosody-configuration} parameter} file-object groups-file +Path to a text file where the shared groups are defined. If this path is +empty then @samp{mod_groups} does nothing. See +@url{https://prosody.im/doc/modules/mod_groups}. Defaults to +@samp{"/var/lib/prosody/sharedgroups.txt"}. +@end deftypevr + +@deftypevr {@code{prosody-configuration} parameter} boolean allow-registration? +Disable account creation by default, for security. See +@url{https://prosody.im/doc/creating_accounts}. Defaults to @samp{#f}. +@end deftypevr + +@deftypevr {@code{prosody-configuration} parameter} maybe-ssl-configuration ssl +These are the SSL/TLS-related settings. Most of them are disabled so to use +Prosody's defaults. If you do not completely understand these options, do +not add them to your config, it is easy to lower the security of your server +using them. See @url{https://prosody.im/doc/advanced_ssl_config}. + +Available @code{ssl-configuration} fields are: + +@deftypevr {@code{ssl-configuration} parameter} maybe-string protocol +This determines what handshake to use. +@end deftypevr + +@deftypevr {@code{ssl-configuration} parameter} maybe-file-name key +Path to your private key file. +@end deftypevr + +@deftypevr {@code{ssl-configuration} parameter} maybe-file-name certificate +Path to your certificate file. +@end deftypevr + +@deftypevr {@code{ssl-configuration} parameter} file-object capath +Path to directory containing root certificates that you wish Prosody to +trust when verifying the certificates of remote servers. Defaults to +@samp{"/etc/ssl/certs"}. +@end deftypevr + +@deftypevr {@code{ssl-configuration} parameter} maybe-file-object cafile +Path to a file containing root certificates that you wish Prosody to trust. +Similar to @code{capath} but with all certificates concatenated together. +@end deftypevr + +@deftypevr {@code{ssl-configuration} parameter} maybe-string-list verify +A list of verification options (these mostly map to OpenSSL's +@code{set_verify()} flags). +@end deftypevr + +@deftypevr {@code{ssl-configuration} parameter} maybe-string-list options +A list of general options relating to SSL/TLS. These map to OpenSSL's +@code{set_options()}. For a full list of options available in LuaSec, see +the LuaSec source. +@end deftypevr + +@deftypevr {@code{ssl-configuration} parameter} maybe-non-negative-integer depth +How long a chain of certificate authorities to check when looking for a +trusted root certificate. +@end deftypevr + +@deftypevr {@code{ssl-configuration} parameter} maybe-string ciphers +An OpenSSL cipher string. This selects what ciphers Prosody will offer to +clients, and in what order. +@end deftypevr + +@deftypevr {@code{ssl-configuration} parameter} maybe-file-name dhparam +A path to a file containing parameters for Diffie-Hellman key exchange. You +can create such a file with: @code{openssl dhparam -out +/etc/prosody/certs/dh-2048.pem 2048} +@end deftypevr + +@deftypevr {@code{ssl-configuration} parameter} maybe-string curve +Curve for Elliptic curve Diffie-Hellman. Prosody's default is +@samp{"secp384r1"}. +@end deftypevr + +@deftypevr {@code{ssl-configuration} parameter} maybe-string-list verifyext +A list of "extra" verification options. +@end deftypevr + +@deftypevr {@code{ssl-configuration} parameter} maybe-string password +Password for encrypted private keys. +@end deftypevr + +@end deftypevr + +@deftypevr {@code{prosody-configuration} parameter} boolean c2s-require-encryption? +Whether to force all client-to-server connections to be encrypted or not. +See @url{https://prosody.im/doc/modules/mod_tls}. Defaults to @samp{#f}. +@end deftypevr + +@deftypevr {@code{prosody-configuration} parameter} string-list disable-sasl-mechanisms +Set of mechanisms that will never be offered. See +@url{https://prosody.im/doc/modules/mod_saslauth}. Defaults to +@samp{("DIGEST-MD5")}. +@end deftypevr + +@deftypevr {@code{prosody-configuration} parameter} boolean s2s-require-encryption? +Whether to force all server-to-server connections to be encrypted or not. +See @url{https://prosody.im/doc/modules/mod_tls}. Defaults to @samp{#f}. +@end deftypevr + +@deftypevr {@code{prosody-configuration} parameter} boolean s2s-secure-auth? +Whether to require encryption and certificate authentication. This provides +ideal security, but requires servers you communicate with to support +encryption AND present valid, trusted certificates. See +@url{https://prosody.im/doc/s2s#security}. Defaults to @samp{#f}. +@end deftypevr + +@deftypevr {@code{prosody-configuration} parameter} string-list s2s-insecure-domains +Many servers don't support encryption or have invalid or self-signed +certificates. You can list domains here that will not be required to +authenticate using certificates. They will be authenticated using DNS. See +@url{https://prosody.im/doc/s2s#security}. Defaults to @samp{()}. +@end deftypevr + +@deftypevr {@code{prosody-configuration} parameter} string-list s2s-secure-domains +Even if you leave @code{s2s-secure-auth?} disabled, you can still require +valid certificates for some domains by specifying a list here. See +@url{https://prosody.im/doc/s2s#security}. Defaults to @samp{()}. +@end deftypevr + +@deftypevr {@code{prosody-configuration} parameter} string authentication +Select the authentication backend to use. The default provider stores +passwords in plaintext and uses Prosody's configured data storage to store +the authentication data. If you do not trust your server please see +@url{https://prosody.im/doc/modules/mod_auth_internal_hashed} for +information about using the hashed backend. See also +@url{https://prosody.im/doc/authentication} Defaults to +@samp{"internal_plain"}. +@end deftypevr + +@deftypevr {@code{prosody-configuration} parameter} maybe-string log +Set logging options. Advanced logging configuration is not yet supported by +the Prosody service. See @url{https://prosody.im/doc/logging}. Defaults to +@samp{"*syslog"}. +@end deftypevr + +@deftypevr {@code{prosody-configuration} parameter} file-name pidfile +File to write pid in. See @url{https://prosody.im/doc/modules/mod_posix}. +Defaults to @samp{"/var/run/prosody/prosody.pid"}. +@end deftypevr + +@deftypevr {@code{prosody-configuration} parameter} maybe-non-negative-integer http-max-content-size +Maximum allowed size of the HTTP body (in bytes). +@end deftypevr + +@deftypevr {@code{prosody-configuration} parameter} maybe-string http-external-url +Some modules expose their own URL in various ways. This URL is built from +the protocol, host and port used. If Prosody sits behind a proxy, the +public URL will be @code{http-external-url} instead. See +@url{https://prosody.im/doc/http#external_url}. +@end deftypevr + +@deftypevr {@code{prosody-configuration} parameter} virtualhost-configuration-list virtualhosts +A host in Prosody is a domain on which user accounts can be created. For +example if you want your users to have addresses like +@samp{"john.smith@@example.com"} then you need to add a host +@samp{"example.com"}. All options in this list will apply only to this +host. + +Note: the name "virtual" host is used in configuration to avoid confusion +with the actual physical host that Prosody is installed on. A single +Prosody instance can serve many domains, each one defined as a VirtualHost +entry in Prosody's configuration. Conversely a server that hosts a single +domain would have just one VirtualHost entry. + +See @url{https://prosody.im/doc/configure#virtual_host_settings}. + +Available @code{virtualhost-configuration} fields are: + +all these @code{prosody-configuration} fields: @code{admins}, +@code{use-libevent?}, @code{modules-enabled}, @code{modules-disabled}, +@code{groups-file}, @code{allow-registration?}, @code{ssl}, +@code{c2s-require-encryption?}, @code{disable-sasl-mechanisms}, +@code{s2s-require-encryption?}, @code{s2s-secure-auth?}, +@code{s2s-insecure-domains}, @code{s2s-secure-domains}, +@code{authentication}, @code{log}, @code{http-max-content-size}, +@code{http-external-url}, @code{raw-content}, plus: +@deftypevr {@code{virtualhost-configuration} parameter} string domain +Domain you wish Prosody to serve. +@end deftypevr + +@end deftypevr + +@deftypevr {@code{prosody-configuration} parameter} int-component-configuration-list int-components +Components are extra services on a server which are available to clients, +usually on a subdomain of the main server (such as +@samp{"mycomponent.example.com"}). Example components might be chatroom +servers, user directories, or gateways to other protocols. + +Internal components are implemented with Prosody-specific plugins. To add +an internal component, you simply fill the hostname field, and the plugin +you wish to use for the component. + +See @url{https://prosody.im/doc/components}. Defaults to @samp{()}. + +Available @code{int-component-configuration} fields are: + +all these @code{prosody-configuration} fields: @code{admins}, +@code{use-libevent?}, @code{modules-enabled}, @code{modules-disabled}, +@code{groups-file}, @code{allow-registration?}, @code{ssl}, +@code{c2s-require-encryption?}, @code{disable-sasl-mechanisms}, +@code{s2s-require-encryption?}, @code{s2s-secure-auth?}, +@code{s2s-insecure-domains}, @code{s2s-secure-domains}, +@code{authentication}, @code{log}, @code{http-max-content-size}, +@code{http-external-url}, @code{raw-content}, plus: +@deftypevr {@code{int-component-configuration} parameter} string hostname +Hostname of the component. +@end deftypevr + +@deftypevr {@code{int-component-configuration} parameter} string plugin +Plugin you wish to use for the component. +@end deftypevr + +@deftypevr {@code{int-component-configuration} parameter} maybe-mod-muc-configuration mod-muc +Multi-user chat (MUC) is Prosody's module for allowing you to create hosted +chatrooms/conferences for XMPP users. + +General information on setting up and using multi-user chatrooms can be +found in the "Chatrooms" documentation +(@url{https://prosody.im/doc/chatrooms}), which you should read if you are +new to XMPP chatrooms. + +See also @url{https://prosody.im/doc/modules/mod_muc}. + +Available @code{mod-muc-configuration} fields are: + +@deftypevr {@code{mod-muc-configuration} parameter} string name +The name to return in service discovery responses. Defaults to +@samp{"Prosody Chatrooms"}. +@end deftypevr + +@deftypevr {@code{mod-muc-configuration} parameter} string-or-boolean restrict-room-creation +If @samp{#t}, this will only allow admins to create new chatrooms. +Otherwise anyone can create a room. The value @samp{"local"} restricts room +creation to users on the service's parent domain. E.g.@: +@samp{user@@example.com} can create rooms on @samp{rooms.example.com}. The +value @samp{"admin"} restricts to service administrators only. Defaults to +@samp{#f}. +@end deftypevr + +@deftypevr {@code{mod-muc-configuration} parameter} non-negative-integer max-history-messages +Maximum number of history messages that will be sent to the member that has +just joined the room. Defaults to @samp{20}. +@end deftypevr + +@end deftypevr + +@end deftypevr + +@deftypevr {@code{prosody-configuration} parameter} ext-component-configuration-list ext-components +External components use XEP-0114, which most standalone components support. +To add an external component, you simply fill the hostname field. See +@url{https://prosody.im/doc/components}. Defaults to @samp{()}. + +Available @code{ext-component-configuration} fields are: + +all these @code{prosody-configuration} fields: @code{admins}, +@code{use-libevent?}, @code{modules-enabled}, @code{modules-disabled}, +@code{groups-file}, @code{allow-registration?}, @code{ssl}, +@code{c2s-require-encryption?}, @code{disable-sasl-mechanisms}, +@code{s2s-require-encryption?}, @code{s2s-secure-auth?}, +@code{s2s-insecure-domains}, @code{s2s-secure-domains}, +@code{authentication}, @code{log}, @code{http-max-content-size}, +@code{http-external-url}, @code{raw-content}, plus: +@deftypevr {@code{ext-component-configuration} parameter} string component-secret +Password which the component will use to log in. +@end deftypevr + +@deftypevr {@code{ext-component-configuration} parameter} string hostname +Hostname of the component. +@end deftypevr + +@end deftypevr + +@deftypevr {@code{prosody-configuration} parameter} non-negative-integer-list component-ports +Port(s) Prosody listens on for component connections. Defaults to +@samp{(5347)}. +@end deftypevr + +@deftypevr {@code{prosody-configuration} parameter} string component-interface +Interface Prosody listens on for component connections. Defaults to +@samp{"127.0.0.1"}. +@end deftypevr + +@deftypevr {@code{prosody-configuration} parameter} maybe-raw-content raw-content +Raw content that will be added to the configuration file. +@end deftypevr + +It could be that you just want to get a @code{prosody.cfg.lua} up and +running. In that case, you can pass an @code{opaque-prosody-configuration} +record as the value of @code{prosody-service-type}. As its name indicates, +an opaque configuration does not have easy reflective capabilities. +Available @code{opaque-prosody-configuration} fields are: + +@deftypevr {@code{opaque-prosody-configuration} parameter} package prosody +El paquete prosody. +@end deftypevr + +@deftypevr {@code{opaque-prosody-configuration} parameter} string prosody.cfg.lua +The contents of the @code{prosody.cfg.lua} to use. +@end deftypevr + +For example, if your @code{prosody.cfg.lua} is just the empty string, you +could instantiate a prosody service like this: + +@example +(service prosody-service-type + (opaque-prosody-configuration + (prosody.cfg.lua ""))) +@end example + +@c end of Prosody auto-generated documentation + +@subsubheading Servicio BitlBee + +@cindex IRC (Internet Relay Chat) +@cindex pasarela IRC +@url{http://bitlbee.org,BitlBee} is a gateway that provides an IRC interface +to a variety of messaging protocols such as XMPP. + +@defvr {Variable Scheme} bitlbee-service-type +This is the service type for the @url{http://bitlbee.org,BitlBee} IRC +gateway daemon. Its value is a @code{bitlbee-configuration} (see below). + +To have BitlBee listen on port 6667 on localhost, add this line to your +services: + +@example +(service bitlbee-service-type) +@end example +@end defvr + +@deftp {Tipo de datos} bitlbee-configuration +This is the configuration for BitlBee, with the following fields: + +@table @asis +@item @code{interface} (predeterminada: @code{"127.0.0.1"}) +@itemx @code{port} (predeterminado: @code{6667}) +Escucha en la interfaz de red correspondiente a la dirección IP especificada +en @var{interface}, en el puerto @var{port}. + +When @var{interface} is @code{127.0.0.1}, only local clients can connect; +when it is @code{0.0.0.0}, connections can come from any networking +interface. + +@item @code{package} (predeterminado: @code{bitlbee}) +El paquete BitlBee usado. + +@item @code{plugins} (predeterminados: @code{'()}) +List of plugin packages to use---e.g., @code{bitlbee-discord}. + +@item @code{extra-settings} (predeterminado: @code{""}) +Configuration snippet added as-is to the BitlBee configuration file. +@end table +@end deftp + +@subsubheading Quassel Service + +@cindex IRC (Internet Relay Chat) +@url{https://quassel-irc.org/,Quassel} is a distributed IRC client, meaning +that one or more clients can attach to and detach from the central core. + +@defvr {Scheme Variable} quassel-service-type +This is the service type for the @url{https://quassel-irc.org/,Quassel} IRC +backend daemon. Its value is a @code{quassel-configuration} (see below). +@end defvr + +@deftp {Data Type} quassel-configuration +This is the configuration for Quassel, with the following fields: + +@table @asis +@item @code{quassel} (default: @code{quassel}) +The Quassel package to use. + +@item @code{interface} (default: @code{"::,0.0.0.0"}) +@item @code{port} (default: @code{4242}) +Listen on the network interface(s) corresponding to the IPv4 or IPv6 +interfaces specified in the comma delimited @var{interface}, on @var{port}. + +@item @code{loglevel} (default: @code{"Info"}) +The level of logging desired. Accepted values are Debug, Info, Warning and +Error. +@end table +@end deftp + +@node Servicios de telefonía +@subsection Servicios de telefonía + +@cindex Murmur (servidor VoIP) +@cindex servidor VoIP +This section describes how to set up and run a Murmur server. Murmur is the +server of the @uref{https://mumble.info, Mumble} voice-over-IP (VoIP) suite. + +@deftp {Tipo de datos} murmur-configuration +The service type for the Murmur server. An example configuration can look +like this: + +@example +(service murmur-service-type + (murmur-configuration + (welcome-text + "Welcome to this Mumble server running on Guix!") + (cert-required? #t) ;disallow text password logins + (ssl-cert "/etc/letsencrypt/live/mumble.example.com/fullchain.pem") + (ssl-key "/etc/letsencrypt/live/mumble.example.com/privkey.pem"))) +@end example + +After reconfiguring your system, you can manually set the murmur +@code{SuperUser} password with the command that is printed during the +activation phase. + +It is recommended to register a normal Mumble user account and grant it +admin or moderator rights. You can use the @code{mumble} client to login as +new normal user, register yourself, and log out. For the next step login +with the name @code{SuperUser} use the @code{SuperUser} password that you +set previously, and grant your newly registered mumble user administrator or +moderator rights and create some channels. + +Available @code{murmur-configuration} fields are: + +@table @asis +@item @code{package} (predeterminado: @code{mumble}) +Package that contains @code{bin/murmurd}. + +@item @code{user} (predeterminado: @code{"murmur"}) +User who will run the Murmur server. + +@item @code{group} (predeterminado: @code{"murmur"}) +Group of the user who will run the murmur server. + +@item @code{port} (predeterminado: @code{64738}) +Puerto en el que escucha el servidor. + +@item @code{welcome-text} (predeterminado: @code{""}) +Welcome text sent to clients when they connect. + +@item @code{server-password} (predeterminada: @code{""}) +Password the clients have to enter in order to connect. + +@item @code{max-users} (predeterminados: @code{100}) +Maximum of users that can be connected to the server at once. + +@item @code{max-user-bandwidth} (predeterminado: @code{#f}) +Maximum voice traffic a user can send per second. + +@item @code{database-file} (predeterminado: @code{"/var/lib/murmur/db.sqlite"}) +File name of the sqlite database. The service's user will become the owner +of the directory. + +@item @code{log-file} (predeterminado: @code{"/var/log/murmur/murmur.log"}) +File name of the log file. The service's user will become the owner of the +directory. + +@item @code{autoban-attempts} (predeterminados: @code{10}) +Maximum number of logins a user can make in @code{autoban-timeframe} without +getting auto banned for @code{autoban-time}. + +@item @code{autoban-timeframe} (predeterminado: @code{120}) +Timeframe for autoban in seconds. + +@item @code{autoban-time} (predeterminado: @code{300}) +Amount of time in seconds for which a client gets banned when violating the +autoban limits. + +@item @code{opus-threshold} (predeterminado: @code{100}) +Percentage of clients that need to support opus before switching over to +opus audio codec. + +@item @code{channel-nesting-limit} (predeterminado: @code{10}) +How deep channels can be nested at maximum. + +@item @code{channelname-regex} (predeterminado: @code{#f}) +A string in form of a Qt regular expression that channel names must conform +to. + +@item @code{username-regex} (predeterminado: @code{#f}) +A string in form of a Qt regular expression that user names must conform to. + +@item @code{text-message-length} (predeterminado: @code{5000}) +Maximum size in bytes that a user can send in one text chat message. + +@item @code{image-message-length} (predeterminado: @code{(* 128 1024)}) +Maximum size in bytes that a user can send in one image message. + +@item @code{cert-required?} (predeterminado: @code{#f}) +If it is set to @code{#t} clients that use weak password authentification +will not be accepted. Users must have completed the certificate wizard to +join. + +@item @code{remember-channel?} (predeterminado: @code{#f}) +Should murmur remember the last channel each user was in when they +disconnected and put them into the remembered channel when they rejoin. + +@item @code{allow-html?} (predeterminado: @code{#f}) +Should html be allowed in text messages, user comments, and channel +descriptions. + +@item @code{allow-ping?} (predeterminado: @code{#f}) +Setting to true exposes the current user count, the maximum user count, and +the server's maximum bandwidth per client to unauthenticated users. In the +Mumble client, this information is shown in the Connect dialog. + +Disabling this setting will prevent public listing of the server. + +@item @code{bonjour?} (predeterminado: @code{#f}) +Should the server advertise itself in the local network through the bonjour +protocol. + +@item @code{send-version?} (predeterminado: @code{#f}) +Should the murmur server version be exposed in ping requests. + +@item @code{log-days} (predeterminado: @code{31}) +Murmur also stores logs in the database, which are accessible via RPC. The +default is 31 days of months, but you can set this setting to 0 to keep logs +forever, or -1 to disable logging to the database. + +@item @code{obfuscate-ips?} (predeterminado: @code{#t}) +Should logged ips be obfuscated to protect the privacy of users. + +@item @code{ssl-cert} (predeterminado: @code{#f}) +File name of the SSL/TLS certificate used for encrypted connections. + +@example +(ssl-cert "/etc/letsencrypt/live/example.com/fullchain.pem") +@end example +@item @code{ssl-key} (predeterminada: @code{#f}) +Filepath to the ssl private key used for encrypted connections. +@example +(ssl-key "/etc/letsencrypt/live/example.com/privkey.pem") +@end example + +@item @code{ssl-dh-params} (predeterminado: @code{#f}) +File name of a PEM-encoded file with Diffie-Hellman parameters for the +SSL/TLS encryption. Alternatively you set it to @code{"@@ffdhe2048"}, +@code{"@@ffdhe3072"}, @code{"@@ffdhe4096"}, @code{"@@ffdhe6144"} or +@code{"@@ffdhe8192"} to use bundled parameters from RFC 7919. + +@item @code{ssl-ciphers} (predeterminado: @code{#f}) +The @code{ssl-ciphers} option chooses the cipher suites to make available +for use in SSL/TLS. + +This option is specified using +@uref{https://www.openssl.org/docs/apps/ciphers.html#CIPHER-LIST-FORMAT, +OpenSSL cipher list notation}. + +It is recommended that you try your cipher string using 'openssl ciphers +<string>' before setting it here, to get a feel for which cipher suites you +will get. After setting this option, it is recommend that you inspect your +Murmur log to ensure that Murmur is using the cipher suites that you +expected it to. + +Note: Changing this option may impact the backwards compatibility of your +Murmur server, and can remove the ability for older Mumble clients to be +able to connect to it. + +@item @code{public-registration} (predeterminado: @code{#f}) +Must be a @code{<murmur-public-registration-configuration>} record or +@code{#f}. + +You can optionally register your server in the public server list that the +@code{mumble} client shows on startup. You cannot register your server if +you have set a @code{server-password}, or set @code{allow-ping} to +@code{#f}. + +It might take a few hours until it shows up in the public list. + +@item @code{file} (predeterminado: @code{#f}) +Optional alternative override for this configuration. +@end table +@end deftp + +@deftp {Tipo de datos} murmur-public-registration-configuration +Configuration for public registration of a murmur service. + +@table @asis +@item @code{name} +This is a display name for your server. Not to be confused with the +hostname. + +@item @code{password} +A password to identify your registration. Subsequent updates will need the +same password. Don't lose your password. + +@item @code{url} +This should be a @code{http://} or @code{https://} link to your web site. + +@item @code{hostname} (predeterminado: @code{#f}) +By default your server will be listed by its IP address. If it is set your +server will be linked by this host name instead. +@end table +@end deftp + + + +@node Servicios de monitorización +@subsection Servicios de monitorización + +@subsubheading Servicio Tailon + +@uref{https://tailon.readthedocs.io/, Tailon} is a web application for +viewing and searching log files. + +The following example will configure the service with default values. By +default, Tailon can be accessed on port 8080 (@code{http://localhost:8080}). + +@example +(service tailon-service-type) +@end example + +The following example customises more of the Tailon configuration, adding +@command{sed} to the list of allowed commands. + +@example +(service tailon-service-type + (tailon-configuration + (config-file + (tailon-configuration-file + (allowed-commands '("tail" "grep" "awk" "sed")))))) +@end example + + +@deftp {Tipo de datos} tailon-configuration +Data type representing the configuration of Tailon. This type has the +following parameters: + +@table @asis +@item @code{config-file} (predeterminado: @code{(tailon-configuration-file)}) +The configuration file to use for Tailon. This can be set to a +@dfn{tailon-configuration-file} record value, or any gexp +(@pxref{Expresiones-G}). + +For example, to instead use a local file, the @code{local-file} function can +be used: + +@example +(service tailon-service-type + (tailon-configuration + (config-file (local-file "./mi-tailon.conf")))) +@end example + +@item @code{package} (predeterminado: @code{tailon}) +El paquete tailon usado. + +@end table +@end deftp + +@deftp {Tipo de datos} tailon-configuration-file +Tipo de datos que representa las opciones de configuración de Tailon. Este +tipo tiene los siguientes parámetros: + +@table @asis +@item @code{files} (predeterminados: @code{(list "/var/log")}) +List of files to display. The list can include strings for a single file or +directory, or a list, where the first item is the name of a subsection, and +the remaining items are the files or directories in that subsection. + +@item @code{bind} (predeterminado: @code{"localhost:8080"}) +Address and port to which Tailon should bind on. + +@item @code{relative-root} (predeterminado: @code{#f}) +URL path to use for Tailon, set to @code{#f} to not use a path. + +@item @code{allow-transfers?} (predeterminado: @code{#t}) +Allow downloading the log files in the web interface. + +@item @code{follow-names?} (predeterminado: @code{#t}) +Allow tailing of not-yet existent files. + +@item @code{tail-lines} (predeterminado: @code{200}) +Number of lines to read initially from each file. + +@item @code{allowed-commands} (predeterminadas: @code{(list "tail" "grep" "awk")}) +Órdenes cuya ejecución está permitida. Por defecto, @code{sed} está +deshabilitado. + +@item @code{debug?} (predeterminado: @code{#f}) +Set @code{debug?} to @code{#t} to show debug messages. + +@item @code{wrap-lines} (predeterminado: @code{#t}) +Initial line wrapping state in the web interface. Set to @code{#t} to +initially wrap lines (the default), or to @code{#f} to initially not wrap +lines. + +@item @code{http-auth} (predeterminado: @code{#f}) +HTTP authentication type to use. Set to @code{#f} to disable authentication +(the default). Supported values are @code{"digest"} or @code{"basic"}. + +@item @code{users} (predeterminado: @code{#f}) +If HTTP authentication is enabled (see @code{http-auth}), access will be +restricted to the credentials provided here. To configure users, use a list +of pairs, where the first element of the pair is the username, and the 2nd +element of the pair is the password. + +@example +(tailon-configuration-file + (http-auth "basic") + (users '(("usuaria1" . "contraseña1") + ("usuaria2" . "contraseña2")))) +@end example + +@end table +@end deftp + + +@subsubheading Servicio Darkstat +@cindex darkstat +Darkstat is a packet sniffer that captures network traffic, calculates +statistics about usage, and serves reports over HTTP. + +@defvar {Variable Scheme} darkstat-service-type +This is the service type for the @uref{https://unix4lyfe.org/darkstat/, +darkstat} service, its value must be a @code{darkstat-configuration} record +as in this example: + +@example +(service darkstat-service-type + (darkstat-configuration + (interface "eno1"))) +@end example +@end defvar + +@deftp {Tipo de datos} darkstat-configuration +Tipo de datos que representa la configuración de @command{darkstat}. + +@table @asis +@item @code{package} (predeterminado: @code{darkstat}) +El paquete darkstat usado. + +@item @code{interface} +Captura el tráfico en la interfaz de red especificada. + +@item @code{port} (predeterminado: @code{"667"}) +Bind the web interface to the specified port. + +@item @code{bind-address} (predeterminada: @code{"127.0.0.1"}) +Bind the web interface to the specified address. + +@item @code{base} (predeterminada: @code{"/"}) +Specify the path of the base URL. This can be useful if @command{darkstat} +is accessed via a reverse proxy. + +@end table +@end deftp + +@subsubheading Servicio del exportador de nodos Prometheus + +@cindex prometheus-node-exporter +The Prometheus ``node exporter'' makes hardware and operating system +statistics provided by the Linux kernel available for the Prometheus +monitoring system. This service should be deployed on all physical nodes +and virtual machines, where monitoring these statistics is desirable. + +@defvar {Variable Scheme} prometheus-node-exporter-service-type +This is the service type for the +@uref{https://github.com/prometheus/node_exporter/, +prometheus-node-exporter} service, its value must be a +@code{prometheus-node-exporter-configuration} record as in this example: + +@example +(service prometheus-node-exporter-service-type + (prometheus-node-exporter-configuration + (web-listen-address ":9100"))) +@end example +@end defvar + +@deftp {Tipo de datos} prometheus-node-exporter-configuration +Tipo de datos que representa la configuración de @command{node_exporter}. + +@table @asis +@item @code{package} (predeterminado: @code{go-github-com-prometheus-node-exporter}) +El paquete prometheus-node-exporter usado. + +@item @code{web-listen-address} (predeterminada: @code{":9100"}) +Bind the web interface to the specified address. + +@end table +@end deftp + +@subsubheading Zabbix server +@cindex zabbix zabbix-server +Zabbix provides monitoring metrics, among others network utilization, CPU +load and disk space consumption: + +@itemize +@item High performance, high capacity (able to monitor hundreds of thousands of devices). +@item Auto-discovery of servers and network devices and interfaces. +@item Low-level discovery, allows to automatically start monitoring new items, file systems or network interfaces among others. +@item Distributed monitoring with centralized web administration. +@item Native high performance agents. +@item SLA, and ITIL KPI metrics on reporting. +@item High-level (business) view of monitored resources through user-defined visual console screens and dashboards. +@item Remote command execution through Zabbix proxies. +@end itemize + +@c %start of fragment + +Available @code{zabbix-server-configuration} fields are: + +@deftypevr {@code{zabbix-server-configuration} parameter} package zabbix-server +The zabbix-server package. + +@end deftypevr + +@deftypevr {@code{zabbix-server-configuration} parameter} string user +User who will run the Zabbix server. + +Defaults to @samp{"zabbix"}. + +@end deftypevr + +@deftypevr {@code{zabbix-server-configuration} parameter} group group +Group who will run the Zabbix server. + +Defaults to @samp{"zabbix"}. + +@end deftypevr + +@deftypevr {@code{zabbix-server-configuration} parameter} string db-host +Database host name. + +Defaults to @samp{"127.0.0.1"}. + +@end deftypevr + +@deftypevr {@code{zabbix-server-configuration} parameter} string db-name +Database name. + +Defaults to @samp{"zabbix"}. + +@end deftypevr + +@deftypevr {@code{zabbix-server-configuration} parameter} string db-user +Database user. + +Defaults to @samp{"zabbix"}. + +@end deftypevr + +@deftypevr {@code{zabbix-server-configuration} parameter} string db-password +Database password. Please, use @code{include-files} with +@code{DBPassword=SECRET} inside a specified file instead. + +El valor predeterminado es @samp{""}. + +@end deftypevr + +@deftypevr {@code{zabbix-server-configuration} parameter} number db-port +Database port. + +Defaults to @samp{5432}. + +@end deftypevr + +@deftypevr {@code{zabbix-server-configuration} parameter} string log-type +Specifies where log messages are written to: + +@itemize @bullet +@item +@code{system} - syslog. + +@item +@code{file} - file specified with @code{log-file} parameter. + +@item +@code{console} - standard output. + +@end itemize + +El valor predeterminado es @samp{""}. + +@end deftypevr + +@deftypevr {@code{zabbix-server-configuration} parameter} string log-file +Log file name for @code{log-type} @code{file} parameter. + +Defaults to @samp{"/var/log/zabbix/server.log"}. + +@end deftypevr + +@deftypevr {@code{zabbix-server-configuration} parameter} string pid-file +Name of PID file. + +Defaults to @samp{"/var/run/zabbix/zabbix_server.pid"}. + +@end deftypevr + +@deftypevr {@code{zabbix-server-configuration} parameter} string ssl-ca-location +The location of certificate authority (CA) files for SSL server certificate +verification. + +Defaults to @samp{"/etc/ssl/certs/ca-certificates.crt"}. + +@end deftypevr + +@deftypevr {@code{zabbix-server-configuration} parameter} string ssl-cert-location +Location of SSL client certificates. + +Defaults to @samp{"/etc/ssl/certs"}. + +@end deftypevr + +@deftypevr {@code{zabbix-server-configuration} parameter} string extra-options +Extra options will be appended to Zabbix server configuration file. + +El valor predeterminado es @samp{""}. + +@end deftypevr + +@deftypevr {@code{zabbix-server-configuration} parameter} include-files include-files +You may include individual files or all files in a directory in the +configuration file. + +Defaults to @samp{()}. + +@end deftypevr + +@c %end of fragment + +@subsubheading Zabbix agent +@cindex zabbix zabbix-agent + +Zabbix agent gathers information for Zabbix server. + +@c %start of fragment + +Available @code{zabbix-agent-configuration} fields are: + +@deftypevr {@code{zabbix-agent-configuration} parameter} package zabbix-agent +The zabbix-agent package. + +@end deftypevr + +@deftypevr {@code{zabbix-agent-configuration} parameter} string user +User who will run the Zabbix agent. + +Defaults to @samp{"zabbix"}. + +@end deftypevr + +@deftypevr {@code{zabbix-agent-configuration} parameter} group group +Group who will run the Zabbix agent. + +Defaults to @samp{"zabbix"}. + +@end deftypevr + +@deftypevr {@code{zabbix-agent-configuration} parameter} string hostname +Unique, case sensitive hostname which is required for active checks and must +match hostname as configured on the server. + +Defaults to @samp{"Zabbix server"}. + +@end deftypevr + +@deftypevr {@code{zabbix-agent-configuration} parameter} string log-type +Specifies where log messages are written to: + +@itemize @bullet +@item +@code{system} - syslog. + +@item +@code{file} - file specified with @code{log-file} parameter. + +@item +@code{console} - standard output. + +@end itemize + +El valor predeterminado es @samp{""}. + +@end deftypevr + +@deftypevr {@code{zabbix-agent-configuration} parameter} string log-file +Log file name for @code{log-type} @code{file} parameter. + +Defaults to @samp{"/var/log/zabbix/agent.log"}. + +@end deftypevr + +@deftypevr {@code{zabbix-agent-configuration} parameter} string pid-file +Name of PID file. + +Defaults to @samp{"/var/run/zabbix/zabbix_agent.pid"}. + +@end deftypevr + +@deftypevr {@code{zabbix-agent-configuration} parameter} list server +List of IP addresses, optionally in CIDR notation, or hostnames of Zabbix +servers and Zabbix proxies. Incoming connections will be accepted only from +the hosts listed here. + +Defaults to @samp{("127.0.0.1")}. + +@end deftypevr + +@deftypevr {@code{zabbix-agent-configuration} parameter} list server-active +List of IP:port (or hostname:port) pairs of Zabbix servers and Zabbix +proxies for active checks. If port is not specified, default port is used. +If this parameter is not specified, active checks are disabled. + +Defaults to @samp{("127.0.0.1")}. + +@end deftypevr + +@deftypevr {@code{zabbix-agent-configuration} parameter} string extra-options +Extra options will be appended to Zabbix server configuration file. + +El valor predeterminado es @samp{""}. + +@end deftypevr + +@deftypevr {@code{zabbix-agent-configuration} parameter} include-files include-files +You may include individual files or all files in a directory in the +configuration file. + +Defaults to @samp{()}. + +@end deftypevr + +@c %end of fragment + +@subsubheading Zabbix front-end +@cindex zabbix zabbix-front-end + +This service provides a WEB interface to Zabbix server. + +@c %start of fragment + +Available @code{zabbix-front-end-configuration} fields are: + +@deftypevr {@code{zabbix-front-end-configuration} parameter} nginx-server-configuration-list nginx +Configuración de NGINX. + +@end deftypevr + +@deftypevr {@code{zabbix-front-end-configuration} parameter} string db-host +Database host name. + +Defaults to @samp{"localhost"}. + +@end deftypevr + +@deftypevr {@code{zabbix-front-end-configuration} parameter} number db-port +Database port. + +Defaults to @samp{5432}. + +@end deftypevr + +@deftypevr {@code{zabbix-front-end-configuration} parameter} string db-name +Database name. + +Defaults to @samp{"zabbix"}. + +@end deftypevr + +@deftypevr {@code{zabbix-front-end-configuration} parameter} string db-user +Database user. + +Defaults to @samp{"zabbix"}. + +@end deftypevr + +@deftypevr {@code{zabbix-front-end-configuration} parameter} string db-password +Database password. Please, use @code{db-secret-file} instead. + +El valor predeterminado es @samp{""}. + +@end deftypevr + +@deftypevr {@code{zabbix-front-end-configuration} parameter} string db-secret-file +Secret file which will be appended to @file{zabbix.conf.php} file. This +file contains credentials for use by Zabbix front-end. You are expected to +create it manually. + +El valor predeterminado es @samp{""}. + +@end deftypevr + +@deftypevr {@code{zabbix-front-end-configuration} parameter} string zabbix-host +Zabbix server hostname. + +Defaults to @samp{"localhost"}. + +@end deftypevr + +@deftypevr {@code{zabbix-front-end-configuration} parameter} number zabbix-port +Zabbix server port. + +Defaults to @samp{10051}. + +@end deftypevr + + +@c %end of fragment + +@node Servicios Kerberos +@subsection Servicios Kerberos +@cindex Kerberos + +The @code{(gnu services kerberos)} module provides services relating to the +authentication protocol @dfn{Kerberos}. + +@subsubheading Servicio Krb5 + +Programs using a Kerberos client library normally expect a configuration +file in @file{/etc/krb5.conf}. This service generates such a file from a +definition provided in the operating system declaration. It does not cause +any daemon to be started. + +No ``keytab'' files are provided by this service---you must explicitly +create them. This service is known to work with the MIT client library, +@code{mit-krb5}. Other implementations have not been tested. + +@defvr {Variable Scheme} krb5-service-type +A service type for Kerberos 5 clients. +@end defvr + +@noindent +Este es un ejemplo de su uso: +@lisp +(service krb5-service-type + (krb5-configuration + (default-realm "EXAMPLE.COM") + (allow-weak-crypto? #t) + (realms (list + (krb5-realm + (name "EXAMPLE.COM") + (admin-server "groucho.example.com") + (kdc "karl.example.com")) + (krb5-realm + (name "ARGRX.EDU") + (admin-server "kerb-admin.argrx.edu") + (kdc "keys.argrx.edu")))))) +@end lisp + +@noindent +This example provides a Kerberos@tie{}5 client configuration which: +@itemize +@item Recognizes two realms, @i{viz:} ``EXAMPLE.COM'' and ``ARGRX.EDU'', both +of which have distinct administration servers and key distribution centers; +@item Will default to the realm ``EXAMPLE.COM'' if the realm is not explicitly +specified by clients; +@item Accepts services which only support encryption types known to be weak. +@end itemize + +The @code{krb5-realm} and @code{krb5-configuration} types have many fields. +Only the most commonly used ones are described here. For a full list, and +more detailed explanation of each, see the MIT +@uref{http://web.mit.edu/kerberos/krb5-devel/doc/admin/conf_files/krb5_conf.html,,krb5.conf} +documentation. + + +@deftp {Tipo de datos} krb5-realm +@cindex realm, kerberos +@table @asis +@item @code{name} +This field is a string identifying the name of the realm. A common +convention is to use the fully qualified DNS name of your organization, +converted to upper case. + +@item @code{admin-server} +This field is a string identifying the host where the administration server +is running. + +@item @code{kdc} +This field is a string identifying the key distribution center for the +realm. +@end table +@end deftp + +@deftp {Tipo de datos} krb5-configuration + +@table @asis +@item @code{allow-weak-crypto?} (predeterminado: @code{#f}) +If this flag is @code{#t} then services which only offer encryption +algorithms known to be weak will be accepted. + +@item @code{default-realm} (predeterminado: @code{#f}) +This field should be a string identifying the default Kerberos realm for the +client. You should set this field to the name of your Kerberos realm. If +this value is @code{#f} then a realm must be specified with every Kerberos +principal when invoking programs such as @command{kinit}. + +@item @code{realms} +This should be a non-empty list of @code{krb5-realm} objects, which clients +may access. Normally, one of them will have a @code{name} field matching +the @code{default-realm} field. +@end table +@end deftp + + +@subsubheading Servicio PAM krb5 +@cindex pam-krb5 + +The @code{pam-krb5} service allows for login authentication and password +management via Kerberos. You will need this service if you want PAM enabled +applications to authenticate users using Kerberos. + +@defvr {Variable Scheme} pam-krb5-service-type +A service type for the Kerberos 5 PAM module. +@end defvr + +@deftp {Tipo de datos} pam-krb5-configuration +Data type representing the configuration of the Kerberos 5 PAM module This +type has the following parameters: +@table @asis +@item @code{pam-krb5} (predeterminado: @code{pam-krb5}) +El paquete pam-krb5 usado. + +@item @code{minimum-uid} (predeterminado: @code{1000}) +The smallest user ID for which Kerberos authentications should be +attempted. Local accounts with lower values will silently fail to +authenticate. +@end table +@end deftp + + +@node Servicios LDAP +@subsection Servicios LDAP +@cindex LDAP +@cindex nslcd, LDAP service + +The @code{(gnu services authentication)} module provides the +@code{nslcd-service-type}, which can be used to authenticate against an LDAP +server. In addition to configuring the service itself, you may want to add +@code{ldap} as a name service to the Name Service Switch. @xref{Selector de servicios de nombres} for detailed information. + +Here is a simple operating system declaration with a default configuration +of the @code{nslcd-service-type} and a Name Service Switch configuration +that consults the @code{ldap} name service last: + +@example +(use-service-modules authentication) +(use-modules (gnu system nss)) +... +(operating-system + ... + (services + (cons* + (service nslcd-service-type) + (service dhcp-client-service-type) + %base-services)) + (name-service-switch + (let ((services (list (name-service (name "db")) + (name-service (name "files")) + (name-service (name "ldap"))))) + (name-service-switch + (inherit %mdns-host-lookup-nss) + (password services) + (shadow services) + (group services) + (netgroup services) + (gshadow services))))) +@end example + +@c %start of generated documentation for nslcd-configuration + +Available @code{nslcd-configuration} fields are: + +@deftypevr {@code{nslcd-configuration} parameter} package nss-pam-ldapd +The @code{nss-pam-ldapd} package to use. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-number threads +The number of threads to start that can handle requests and perform LDAP +queries. Each thread opens a separate connection to the LDAP server. The +default is to start 5 threads. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} string uid +This specifies the user id with which the daemon should be run. + +Defaults to @samp{"nslcd"}. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} string gid +This specifies the group id with which the daemon should be run. + +Defaults to @samp{"nslcd"}. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} log-option log +This option controls the way logging is done via a list containing SCHEME +and LEVEL. The SCHEME argument may either be the symbols "none" or +"syslog", or an absolute file name. The LEVEL argument is optional and +specifies the log level. The log level may be one of the following symbols: +"crit", "error", "warning", "notice", "info" or "debug". All messages with +the specified log level or higher are logged. + +Defaults to @samp{("/var/log/nslcd" info)}. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} list uri +The list of LDAP server URIs. Normally, only the first server will be used +with the following servers as fall-back. + +Defaults to @samp{("ldap://localhost:389/")}. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-string ldap-version +The version of the LDAP protocol to use. The default is to use the maximum +version supported by the LDAP library. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-string binddn +Specifies the distinguished name with which to bind to the directory server +for lookups. The default is to bind anonymously. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-string bindpw +Specifies the credentials with which to bind. This option is only +applicable when used with binddn. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-string rootpwmoddn +Specifies the distinguished name to use when the root user tries to modify a +user's password using the PAM module. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-string rootpwmodpw +Specifies the credentials with which to bind if the root user tries to +change a user's password. This option is only applicable when used with +rootpwmoddn + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-string sasl-mech +Specifies the SASL mechanism to be used when performing SASL authentication. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-string sasl-realm +Specifies the SASL realm to be used when performing SASL authentication. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-string sasl-authcid +Specifies the authentication identity to be used when performing SASL +authentication. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-string sasl-authzid +Specifies the authorization identity to be used when performing SASL +authentication. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean sasl-canonicalize? +Determines whether the LDAP server host name should be canonicalised. If +this is enabled the LDAP library will do a reverse host name lookup. By +default, it is left up to the LDAP library whether this check is performed +or not. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-string krb5-ccname +Set the name for the GSS-API Kerberos credentials cache. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} string base +The directory search base. + +Defaults to @samp{"dc=example,dc=com"}. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} scope-option scope +Specifies the search scope (subtree, onelevel, base or children). The +default scope is subtree; base scope is almost never useful for name service +lookups; children scope is not supported on all servers. + +Defaults to @samp{(subtree)}. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-deref-option deref +Specifies the policy for dereferencing aliases. The default policy is to +never dereference aliases. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean referrals +Specifies whether automatic referral chasing should be enabled. The default +behaviour is to chase referrals. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} list-of-map-entries maps +This option allows for custom attributes to be looked up instead of the +default RFC 2307 attributes. It is a list of maps, each consisting of the +name of a map, the RFC 2307 attribute to match and the query expression for +the attribute as it is available in the directory. + +Defaults to @samp{()}. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} list-of-filter-entries filters +A list of filters consisting of the name of a map to which the filter +applies and an LDAP search filter expression. + +Defaults to @samp{()}. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-number bind-timelimit +Specifies the time limit in seconds to use when connecting to the directory +server. The default value is 10 seconds. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-number timelimit +Specifies the time limit (in seconds) to wait for a response from the LDAP +server. A value of zero, which is the default, is to wait indefinitely for +searches to be completed. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-number idle-timelimit +Specifies the period if inactivity (in seconds) after which the con‐ nection +to the LDAP server will be closed. The default is not to time out +connections. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-number reconnect-sleeptime +Specifies the number of seconds to sleep when connecting to all LDAP servers +fails. By default one second is waited between the first failure and the +first retry. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-number reconnect-retrytime +Specifies the time after which the LDAP server is considered to be +permanently unavailable. Once this time is reached retries will be done +only once per this time period. The default value is 10 seconds. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-ssl-option ssl +Specifies whether to use SSL/TLS or not (the default is not to). If +'start-tls is specified then StartTLS is used rather than raw LDAP over SSL. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-tls-reqcert-option tls-reqcert +Specifies what checks to perform on a server-supplied certificate. The +meaning of the values is described in the ldap.conf(5) manual page. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-cacertdir +Specifies the directory containing X.509 certificates for peer authen‐ +tication. This parameter is ignored when using GnuTLS. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-cacertfile +Specifies the path to the X.509 certificate for peer authentication. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-randfile +Specifies the path to an entropy source. This parameter is ignored when +using GnuTLS. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-ciphers +Specifies the ciphers to use for TLS as a string. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-cert +Specifies the path to the file containing the local certificate for client +TLS authentication. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-key +Specifies the path to the file containing the private key for client TLS +authentication. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-number pagesize +Set this to a number greater than 0 to request paged results from the LDAP +server in accordance with RFC2696. The default (0) is to not request paged +results. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-ignore-users-option nss-initgroups-ignoreusers +This option prevents group membership lookups through LDAP for the specified +users. Alternatively, the value 'all-local may be used. With that value +nslcd builds a full list of non-LDAP users on startup. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-number nss-min-uid +This option ensures that LDAP users with a numeric user id lower than the +specified value are ignored. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-number nss-uid-offset +This option specifies an offset that is added to all LDAP numeric user ids. +This can be used to avoid user id collisions with local users. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-number nss-gid-offset +This option specifies an offset that is added to all LDAP numeric group +ids. This can be used to avoid user id collisions with local groups. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean nss-nested-groups +If this option is set, the member attribute of a group may point to another +group. Members of nested groups are also returned in the higher level group +and parent groups are returned when finding groups for a specific user. The +default is not to perform extra searches for nested groups. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean nss-getgrent-skipmembers +If this option is set, the group member list is not retrieved when looking +up groups. Lookups for finding which groups a user belongs to will remain +functional so the user will likely still get the correct groups assigned on +login. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean nss-disable-enumeration +If this option is set, functions which cause all user/group entries to be +loaded from the directory will not succeed in doing so. This can +dramatically reduce LDAP server load in situations where there are a great +number of users and/or groups. This option is not recommended for most +configurations. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-string validnames +This option can be used to specify how user and group names are verified +within the system. This pattern is used to check all user and group names +that are requested and returned from LDAP. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean ignorecase +This specifies whether or not to perform searches using case-insensitive +matching. Enabling this could open up the system to authorization bypass +vulnerabilities and introduce nscd cache poisoning vulnerabilities which +allow denial of service. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean pam-authc-ppolicy +This option specifies whether password policy controls are requested and +handled from the LDAP server when performing user authentication. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-string pam-authc-search +By default nslcd performs an LDAP search with the user's credentials after +BIND (authentication) to ensure that the BIND operation was successful. The +default search is a simple check to see if the user's DN exists. A search +filter can be specified that will be used instead. It should return at +least one entry. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-string pam-authz-search +This option allows flexible fine tuning of the authorisation check that +should be performed. The search filter specified is executed and if any +entries match, access is granted, otherwise access is denied. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} maybe-string pam-password-prohibit-message +If this option is set password modification using pam_ldap will be denied +and the specified message will be presented to the user instead. The +message can be used to direct the user to an alternative means of changing +their password. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{nslcd-configuration} parameter} list pam-services +List of pam service names for which LDAP authentication should suffice. + +Defaults to @samp{()}. + +@end deftypevr + +@c %end of generated documentation for nslcd-configuration + + +@node Servicios Web +@subsection Servicios Web + +@cindex web +@cindex www +@cindex HTTP +El módulo @code{(gnu services web)} proporciona el servidor HTTP Apache, el +servidor web nginx y también un recubrimiento del daemon de fastcgi. + +@subsubheading Servidor HTTP Apache + +@deffn {Variable Scheme} httpd-service-type +Service type for the @uref{https://httpd.apache.org/,Apache HTTP} server +(@dfn{httpd}). The value for this service type is a +@code{httpd-configuration} record. + +A simple example configuration is given below. + +@example +(service httpd-service-type + (httpd-configuration + (config + (httpd-config-file + (server-name "www.example.com") + (document-root "/srv/http/www.example.com"))))) +@end example + +Other services can also extend the @code{httpd-service-type} to add to the +configuration. + +@example +(simple-service 'mi-servidor-extra httpd-service-type + (list + (httpd-virtualhost + "*:80" + (list (string-append + "ServerName "www.example.com + DocumentRoot \"/srv/http/www.example.com\""))))) +@end example +@end deffn + +The details for the @code{httpd-configuration}, @code{httpd-module}, +@code{httpd-config-file} and @code{httpd-virtualhost} record types are given +below. + +@deffn {Tipo de datos} httpd-configuration +This data type represents the configuration for the httpd service. + +@table @asis +@item @code{package} (predeterminado: @code{httpd}) +El paquete httpd usado. + +@item @code{pid-file} (predeterminado: @code{"/var/run/httpd"}) +El fichero pid usado por el servicio de Shepherd. + +@item @code{config} (predeterminado: @code{(httpd-config-file)}) +The configuration file to use with the httpd service. The default value is a +@code{httpd-config-file} record, but this can also be a different +G-expression that generates a file, for example a @code{plain-file}. A file +outside of the store can also be specified through a string. + +@end table +@end deffn + +@deffn {Tipo de datos} httpd-module +This data type represents a module for the httpd service. + +@table @asis +@item @code{name} +The name of the module. + +@item @code{file} +The file for the module. This can be relative to the httpd package being +used, the absolute location of a file, or a G-expression for a file within +the store, for example @code{(file-append mod-wsgi "/modules/mod_wsgi.so")}. + +@end table +@end deffn + +@defvr {Variable Scheme} %default-httpd-modules +A default list of @code{httpd-module} objects. +@end defvr + +@deffn {Tipo de datos} httpd-config-file +This data type represents a configuration file for the httpd service. + +@table @asis +@item @code{modules} (predeterminados: @code{%default-httpd-modules}) +The modules to load. Additional modules can be added here, or loaded by +additional configuration. + +For example, in order to handle requests for PHP files, you can use Apache’s +@code{mod_proxy_fcgi} module along with @code{php-fpm-service-type}: + +@example +(service httpd-service-type + (httpd-configuration + (config + (httpd-config-file + (modules (cons* + (httpd-module + (name "proxy_module") + (file "modules/mod_proxy.so")) + (httpd-module + (name "proxy_fcgi_module") + (file "modules/mod_proxy_fcgi.so")) + %default-httpd-modules)) + (extra-config (list "\ +<FilesMatch \\.php$> + SetHandler \"proxy:unix:/var/run/php-fpm.sock|fcgi://localhost/\" +</FilesMatch>")))))) +(service php-fpm-service-type + (php-fpm-configuration + (socket "/var/run/php-fpm.sock") + (socket-group "httpd"))) +@end example + +@item @code{server-root} (predeterminado: @code{httpd}) +The @code{ServerRoot} in the configuration file, defaults to the httpd +package. Directives including @code{Include} and @code{LoadModule} are taken +as relative to the server root. + +@item @code{server-name} (predeterminado: @code{#f}) +The @code{ServerName} in the configuration file, used to specify the request +scheme, hostname and port that the server uses to identify itself. + +This doesn't need to be set in the server config, and can be specifyed in +virtual hosts. The default is @code{#f} to not specify a @code{ServerName}. + +@item @code{document-root} (predeterminado: @code{"/srv/http"}) +The @code{DocumentRoot} from which files will be served. + +@item @code{listen} (predeterminado: @code{'("80")}) +The list of values for the @code{Listen} directives in the config file. The +value should be a list of strings, when each string can specify the port +number to listen on, and optionally the IP address and protocol to use. + +@item @code{pid-file} (predeterminado: @code{"/var/run/httpd"}) +The @code{PidFile} to use. This should match the @code{pid-file} set in the +@code{httpd-configuration} so that the Shepherd service is configured +correctly. + +@item @code{error-log} (predeterminado: @code{"/var/log/httpd/error_log"}) +The @code{ErrorLog} to which the server will log errors. + +@item @code{user} (predeterminada: @code{"httpd"}) +La usuaria como la que el servidor responderá a las peticiones. + +@item @code{group} (predeterminado: @code{"httpd"}) +El grupo como el que el servidor responderá a las peticiones. + +@item @code{extra-config} (predeterminadas: @code{(list "TypesConfig etc/httpd/mime.types")}) +A flat list of strings and G-expressions which will be added to the end of +the configuration file. + +Any values which the service is extended with will be appended to this list. + +@end table +@end deffn + +@deffn {Tipo de datos} httpd-virtualhost +This data type represents a virtualhost configuration block for the httpd +service. + +These should be added to the extra-config for the httpd-service. + +@example +(simple-service 'mi-servidor-extra httpd-service-type + (list + (httpd-virtualhost + "*:80" + (list (string-append + "ServerName "www.example.com + DocumentRoot \"/srv/http/www.example.com\""))))) +@end example + +@table @asis +@item @code{addresses-and-ports} +The addresses and ports for the @code{VirtualHost} directive. + +@item @code{contents} +The contents of the @code{VirtualHost} directive, this should be a list of +strings and G-expressions. + +@end table +@end deffn + +@subsubheading NGINX + +@deffn {Variable Scheme} nginx-service-type +Service type for the @uref{https://nginx.org/,NGinx} web server. The value +for this service type is a @code{<nginx-configuration>} record. + +A simple example configuration is given below. + +@example +(service nginx-service-type + (nginx-configuration + (server-blocks + (list (nginx-server-configuration + (server-name '("www.example.com")) + (root "/srv/http/www.example.com")))))) +@end example + +In addition to adding server blocks to the service configuration directly, +this service can be extended by other services to add server blocks, as in +this example: + +@example +(simple-service 'mi-servidor-extra nginx-service-type + (list (nginx-server-configuration + (root "/srv/http/sitio-extra") + (try-files (list "$uri" "$uri/index.html"))))) +@end example +@end deffn + +At startup, @command{nginx} has not yet read its configuration file, so it +uses a default file to log error messages. If it fails to load its +configuration file, that is where error messages are logged. After the +configuration file is loaded, the default error log file changes as per +configuration. In our case, startup error messages can be found in +@file{/var/run/nginx/logs/error.log}, and after configuration in +@file{/var/log/nginx/error.log}. The second location can be changed with +the @var{log-directory} configuration option. + +@deffn {Tipo de datos} nginx-configuration +This data type represents the configuration for NGinx. Some configuration +can be done through this and the other provided record types, or +alternatively, a config file can be provided. + +@table @asis +@item @code{nginx} (predeterminado: @code{nginx}) +El paquete nginx usado. + +@item @code{log-directory} (predeterminado: @code{"/var/log/nginx"}) +The directory to which NGinx will write log files. + +@item @code{run-directory} (predeterminado: @code{"/var/run/nginx"}) +The directory in which NGinx will create a pid file, and write temporary +files. + +@item @code{server-blocks} (predeterminados: @code{'()}) +A list of @dfn{server blocks} to create in the generated configuration file, +the elements should be of type @code{<nginx-server-configuration>}. + +The following example would setup NGinx to serve @code{www.example.com} from +the @code{/srv/http/www.example.com} directory, without using HTTPS. +@example +(service nginx-service-type + (nginx-configuration + (server-blocks + (list (nginx-server-configuration + (server-name '("www.example.com")) + (root "/srv/http/www.example.com")))))) +@end example + +@item @code{upstream-blocks} (predeterminados: @code{'()}) +A list of @dfn{upstream blocks} to create in the generated configuration +file, the elements should be of type @code{<nginx-upstream-configuration>}. + +Configuring upstreams through the @code{upstream-blocks} can be useful when +combined with @code{locations} in the @code{<nginx-server-configuration>} +records. The following example creates a server configuration with one +location configuration, that will proxy requests to a upstream +configuration, which will handle requests with two servers. + +@example +(service + nginx-service-type + (nginx-configuration + (server-blocks + (list (nginx-server-configuration + (server-name '("www.example.com")) + (root "/srv/http/www.example.com") + (locations + (list + (nginx-location-configuration + (uri "/path1") + (body '("proxy_pass http://server-proxy;")))))))) + (upstream-blocks + (list (nginx-upstream-configuration + (name "server-proxy") + (servers (list "server1.example.com" + "server2.example.com"))))))) +@end example + +@item @code{file} (predeterminado: @code{#f}) +If a configuration @var{file} is provided, this will be used, rather than +generating a configuration file from the provided @code{log-directory}, +@code{run-directory}, @code{server-blocks} and @code{upstream-blocks}. For +proper operation, these arguments should match what is in @var{file} to +ensure that the directories are created when the service is activated. + +This can be useful if you have an existing configuration file, or it's not +possible to do what is required through the other parts of the +nginx-configuration record. + +@item @code{server-names-hash-bucket-size} (predeterminado: @code{#f}) +Bucket size for the server names hash tables, defaults to @code{#f} to use +the size of the processors cache line. + +@item @code{server-names-hash-bucket-max-size} (predeterminado: @code{#f}) +Maximum bucket size for the server names hash tables. + +@item @code{extra-content} (predeterminado: @code{""}) +Extra content for the @code{http} block. Should be string or a string +valued G-expression. + +@end table +@end deffn + +@deftp {Tipo de datos} nginx-server-configuration +Data type representing the configuration of an nginx server block. This +type has the following parameters: + +@table @asis +@item @code{listen} (predeterminadas: @code{'("80" "443 ssl")}) +Each @code{listen} directive sets the address and port for IP, or the path +for a UNIX-domain socket on which the server will accept requests. Both +address and port, or only address or only port can be specified. An address +may also be a hostname, for example: + +@example +'("127.0.0.1:8000" "127.0.0.1" "8000" "*:8000" "localhost:8000") +@end example + +@item @code{server-name} (predeterminados: @code{(list 'default)}) +A list of server names this server represents. @code{'default} represents +the default server for connections matching no other server. + +@item @code{root} (predeterminada: @code{"/srv/http"}) +Raíz del sitio web que nginx proporcionará. + +@item @code{locations} (predeterminado: @code{'()}) +A list of @dfn{nginx-location-configuration} or +@dfn{nginx-named-location-configuration} records to use within this server +block. + +@item @code{index} (predeterminado: @code{(list "index.html")}) +Index files to look for when clients ask for a directory. If it cannot be +found, Nginx will send the list of files in the directory. + +@item @code{try-files} (predeterminado: @code{'()}) +A list of files whose existence is checked in the specified order. +@code{nginx} will use the first file it finds to process the request. + +@item @code{ssl-certificate} (predeterminado: @code{#f}) +Where to find the certificate for secure connections. Set it to @code{#f} +if you don't have a certificate or you don't want to use HTTPS. + +@item @code{ssl-certificate-key} (predeterminado: @code{#f}) +Where to find the private key for secure connections. Set it to @code{#f} +if you don't have a key or you don't want to use HTTPS. + +@item @code{server-tokens?} (predeterminado: @code{#f}) +Whether the server should add its configuration to response. + +@item @code{raw-content} (predeterminado: @code{'()}) +A list of raw lines added to the server block. + +@end table +@end deftp + +@deftp {Tipo de datos} nginx-upstream-configuration +Data type representing the configuration of an nginx @code{upstream} block. +This type has the following parameters: + +@table @asis +@item @code{name} +Name for this group of servers. + +@item @code{servers} +Specify the addresses of the servers in the group. The address can be +specified as a IP address (e.g.@: @samp{127.0.0.1}), domain name (e.g.@: +@samp{backend1.example.com}) or a path to a UNIX socket using the prefix +@samp{unix:}. For addresses using an IP address or domain name, the default +port is 80, and a different port can be specified explicitly. + +@end table +@end deftp + +@deftp {Tipo de datos} nginx-location-configuration +Data type representing the configuration of an nginx @code{location} block. +This type has the following parameters: + +@table @asis +@item @code{uri} +URI which this location block matches. + +@anchor{nginx-location-configuration body} +@item @code{body} +Body of the location block, specified as a list of strings. This can contain +many configuration directives. For example, to pass requests to a upstream +server group defined using an @code{nginx-upstream-configuration} block, the +following directive would be specified in the body @samp{(list "proxy_pass +http://upstream-name;")}. + +@end table +@end deftp + +@deftp {Tipo de datos} nginx-named-location-configuration +Data type representing the configuration of an nginx named location block. +Named location blocks are used for request redirection, and not used for +regular request processing. This type has the following parameters: + +@table @asis +@item @code{name} +Name to identify this location block. + +@item @code{body} +@xref{nginx-location-configuration body}, as the body for named location +blocks can be used in a similar way to the +@code{nginx-location-configuration body}. One restriction is that the body +of a named location block cannot contain location blocks. + +@end table +@end deftp + +@subsubheading Varnish Cache +@cindex Varnish +Varnish is a fast cache server that sits in between web applications and end +users. It proxies requests from clients and caches the accessed URLs such +that multiple requests for the same resource only creates one request to the +back-end. + +@defvr {Variable Scheme} varnish-service-type +Service type for the Varnish daemon. +@end defvr + +@deftp {Tipo de datos} varnish-configuration +Data type representing the @code{varnish} service configuration. This type +has the following parameters: + +@table @asis +@item @code{package} (predeterminado: @code{varnish}) +El paquete Varnish usado. + +@item @code{name} (predeterminado: @code{"default"}) +A name for this Varnish instance. Varnish will create a directory in +@file{/var/varnish/} with this name and keep temporary files there. If the +name starts with a forward slash, it is interpreted as an absolute directory +name. + +Pass the @code{-n} argument to other Varnish programs to connect to the +named instance, e.g.@: @command{varnishncsa -n default}. + +@item @code{backend} (predeterminado: @code{"localhost:8080"}) +The backend to use. This option has no effect if @code{vcl} is set. + +@item @code{vcl} (predeterminado: #f) +The @dfn{VCL} (Varnish Configuration Language) program to run. If this is +@code{#f}, Varnish will proxy @code{backend} using the default +configuration. Otherwise this must be a file-like object with valid VCL +syntax. + +@c Varnish does not support HTTPS, so keep this URL to avoid confusion. +For example, to mirror @url{http://www.gnu.org,www.gnu.org} with VCL you can +do something along these lines: + +@example +(define %espejo-gnu + (plain-file + "gnu.vcl" + "vcl 4.1; +backend gnu @{ .host = "www.gnu.org"; @}")) + +(operating-system + ... + (services (cons (service varnish-service-type + (varnish-configuration + (listen '(":80")) + (vcl %espejo-gnu))) + %base-services))) +@end example + +The configuration of an already running Varnish instance can be inspected +and changed using the @command{varnishadm} program. + +Consult the @url{https://varnish-cache.org/docs/,Varnish User Guide} and +@url{https://book.varnish-software.com/4.0/,Varnish Book} for comprehensive +documentation on Varnish and its configuration language. + +@item @code{listen} (predeterminada: @code{'("localhost:80")}) +Lista de direcciones en las que Varnish escucha. + +@item @code{storage} (predeterminado: @code{'("malloc,128m")}) +List of storage backends that will be available in VCL. + +@item @code{parameters} (predeterminados: @code{'()}) +List of run-time parameters in the form @code{'(("parameter" . "value"))}. + +@item @code{extra-options} (predeterminadas: @code{'()}) +Additional arguments to pass to the @command{varnishd} process. + +@end table +@end deftp + +@subsubheading FastCGI +@cindex fastcgi +@cindex fcgiwrap +FastCGI is an interface between the front-end and the back-end of a web +service. It is a somewhat legacy facility; new web services should +generally just talk HTTP between the front-end and the back-end. However +there are a number of back-end services such as PHP or the optimized HTTP +Git repository access that use FastCGI, so we have support for it in Guix. + +To use FastCGI, you configure the front-end web server (e.g., nginx) to +dispatch some subset of its requests to the fastcgi backend, which listens +on a local TCP or UNIX socket. There is an intermediary @code{fcgiwrap} +program that sits between the actual backend process and the web server. +The front-end indicates which backend program to run, passing that +information to the @code{fcgiwrap} process. + +@defvr {Variable Scheme} fcgiwrap-service-type +A service type for the @code{fcgiwrap} FastCGI proxy. +@end defvr + +@deftp {Tipo de datos} fcgiwrap-configuration +Data type representing the configuration of the @code{fcgiwrap} service. +This type has the following parameters: +@table @asis +@item @code{package} (predeterminado: @code{fcgiwrap}) +El paquete fcgiwrap usado. + +@item @code{socket} (predeterminado: @code{tcp:127.0.0.1:9000}) +The socket on which the @code{fcgiwrap} process should listen, as a string. +Valid @var{socket} values include @code{unix:@var{/path/to/unix/socket}}, +@code{tcp:@var{dot.ted.qu.ad}:@var{port}} and +@code{tcp6:[@var{ipv6_addr}]:port}. + +@item @code{user} (predeterminado: @code{fcgiwrap}) +@itemx @code{group} (predeterminado: @code{fcgiwrap}) +The user and group names, as strings, under which to run the @code{fcgiwrap} +process. The @code{fastcgi} service will ensure that if the user asks for +the specific user or group names @code{fcgiwrap} that the corresponding user +and/or group is present on the system. + +It is possible to configure a FastCGI-backed web service to pass HTTP +authentication information from the front-end to the back-end, and to allow +@code{fcgiwrap} to run the back-end process as a corresponding local user. +To enable this capability on the back-end., run @code{fcgiwrap} as the +@code{root} user and group. Note that this capability also has to be +configured on the front-end as well. +@end table +@end deftp + +@cindex php-fpm +PHP-FPM (FastCGI Process Manager) is an alternative PHP FastCGI +implementation with some additional features useful for sites of any size. + +These features include: +@itemize @bullet +@item Adaptive process spawning +@item Basic statistics (similar to Apache's mod_status) +@item Advanced process management with graceful stop/start +@item Ability to start workers with different uid/gid/chroot/environment +and different php.ini (replaces safe_mode) +@item Stdout & stderr logging +@item Emergency restart in case of accidental opcode cache destruction +@item Accelerated upload support +@item Support for a "slowlog" +@item Enhancements to FastCGI, such as fastcgi_finish_request() - +a special function to finish request & flush all data while continuing to do +something time-consuming (video converting, stats processing, etc.) +@end itemize +...@: and much more. + +@defvr {Variable Scheme} php-fpm-service-type +Un tipo de servicio para @code{php-fpm}. +@end defvr + +@deftp {Tipo de datos} php-fpm-configuration +Tipo de datos para la configuración del servicio php-fpm. +@table @asis +@item @code{php} (predeterminado: @code{php}) +El paquete php usado. +@item @code{socket} (predeterminado: @code{(string-append "/var/run/php" (version-major (package-version php)) "-fpm.sock")}) +La dirección desde la que FastCGI acepta peticiones. Las sintaxis válidas +son: +@table @asis +@item @code{"dir.ecc.ión.ip:puerto"} +Escucha con un socket TCP en la dirección especificada en un puerto +específico. +@item @code{"puerto"} +Escucha en un socket TCP en todas las direcciones sobre un puerto +específico. +@item @code{"/ruta/a/socket/unix"} +Escucha en un socket Unix. +@end table + +@item @code{user} (predeterminada: @code{php-fpm}) +User who will own the php worker processes. +@item @code{group} (predeterminado: @code{php-fpm}) +Group of the worker processes. +@item @code{socket-user} (predeterminado: @code{php-fpm}) +User who can speak to the php-fpm socket. +@item @code{socket-group} (predeterminado: @code{php-fpm}) +Group that can speak to the php-fpm socket. +@item @code{pid-file} (predeterminado: @code{(string-append "/var/run/php" (version-major (package-version php)) "-fpm.pid")}) +The process id of the php-fpm process is written to this file once the +service has started. +@item @code{log-file} (predeterminado: @code{(string-append "/var/log/php" (version-major (package-version php)) "-fpm.log")}) +Log for the php-fpm master process. +@item @code{process-manager} (predeterminado: @code{(php-fpm-dynamic-process-manager-configuration)}) +Detailed settings for the php-fpm process manager. Must be either: +@table @asis +@item @code{<php-fpm-dynamic-process-manager-configuration>} +@item @code{<php-fpm-static-process-manager-configuration>} +@item @code{<php-fpm-on-demand-process-manager-configuration>} +@end table +@item @code{display-errors} (predeterminado @code{#f}) +Determines whether php errors and warning should be sent to clients and +displayed in their browsers. This is useful for local php development, but +a security risk for public sites, as error messages can reveal passwords and +personal data. +@item @code{timezone} (default @code{#f}) +Specifies @code{php_admin_value[date.timezone]} parameter. +@item @code{workers-logfile} (predeterminado @code{(string-append "/var/log/php" (version-major (package-version php)) "-fpm.www.log")}) +This file will log the @code{stderr} outputs of php worker processes. Can +be set to @code{#f} to disable logging. +@item @code{file} (predeterminado @code{#f}) +An optional override of the whole configuration. You can use the +@code{mixed-text-file} function or an absolute filepath for it. +@end table +@end deftp + +@deftp {Tipo de datos} php-fpm-dynamic-process-manager-configuration +Data Type for the @code{dynamic} php-fpm process manager. With the +@code{dynamic} process manager, spare worker processes are kept around based +on it's configured limits. +@table @asis +@item @code{max-children} (predeterminados: @code{5}) +Maximum of worker processes. +@item @code{start-servers} (predeterminados: @code{2}) +How many worker processes should be started on start-up. +@item @code{min-spare-servers} (predeterminado: @code{1}) +How many spare worker processes should be kept around at minimum. +@item @code{max-spare-servers} (predeterminados: @code{3}) +How many spare worker processes should be kept around at maximum. +@end table +@end deftp + +@deftp {Tipo de datos} php-fpm-static-process-manager-configuration +Data Type for the @code{static} php-fpm process manager. With the +@code{static} process manager, an unchanging number of worker processes are +created. +@table @asis +@item @code{max-children} (predeterminados: @code{5}) +Maximum of worker processes. +@end table +@end deftp + +@deftp {Tipo de datos} php-fpm-on-demand-process-manager-configuration +Data Type for the @code{on-demand} php-fpm process manager. With the +@code{on-demand} process manager, worker processes are only created as +requests arrive. +@table @asis +@item @code{max-children} (predeterminados: @code{5}) +Maximum of worker processes. +@item @code{process-idle-timeout} (predeterminado: @code{10}) +The time in seconds after which a process with no requests is killed. +@end table +@end deftp + + +@deffn {Procedimiento Scheme} nginx-php-fpm-location @ + [#:nginx-package nginx] @ [socket (string-append "/var/run/php" @ +(version-major (package-version php)) @ "-fpm.sock")] A helper function to +quickly add php to an @code{nginx-server-configuration}. +@end deffn + +A simple services setup for nginx with php can look like this: +@example +(services (cons* (service dhcp-client-service-type) + (service php-fpm-service-type) + (service nginx-service-type + (nginx-server-configuration + (server-name '("example.com")) + (root "/srv/http/") + (locations + (list (nginx-php-location))) + (listen '("80")) + (ssl-certificate #f) + (ssl-certificate-key #f))) + %base-services)) +@end example + +@cindex cat-avatar-generator +The cat avatar generator is a simple service to demonstrate the use of +php-fpm in @code{Nginx}. It is used to generate cat avatar from a seed, for +instance the hash of a user's email address. + +@deffn {Scheme Procedure} cat-avatar-generator-service @ + [#:cache-dir "/var/cache/cat-avatar-generator"] @ [#:package +cat-avatar-generator] @ [#:configuration (nginx-server-configuration)] +Returns an nginx-server-configuration that inherits @code{configuration}. +It extends the nginx configuration to add a server block that serves +@code{package}, a version of cat-avatar-generator. During execution, +cat-avatar-generator will be able to use @code{cache-dir} as its cache +directory. +@end deffn + +A simple setup for cat-avatar-generator can look like this: +@example +(services (cons* (cat-avatar-generator-service + #:configuration + (nginx-server-configuration + (server-name '("example.com")))) + ... + %base-services)) +@end example + +@subsubheading Hpcguix-web + +@cindex hpcguix-web +The @uref{hpcguix-web, https://github.com/UMCUGenetics/hpcguix-web/} program +is a customizable web interface to browse Guix packages, initially designed +for users of high-performance computing (HPC) clusters. + +@defvr {Variable Scheme} hpcguix-web-service-type +El tipo de servicio para @code{hpcguix-web}. +@end defvr + +@deftp {Tipo de datos} hpcguix-web-configuration +El tipo de datos para la configuración del servicio hpcguix-web. + +@table @asis +@item @code{specs} +A gexp (@pxref{Expresiones-G}) specifying the hpcguix-web service +configuration. The main items available in this spec are: + +@table @asis +@item @code{title-prefix} (predeterminado: @code{"hpcguix | "}) +El prefijo del título de la página. + +@item @code{guix-command} (predeterminada: @code{"guix"}) +La orden @command{guix}. + +@item @code{package-filter-proc} (predeterminado: @code{(const #t)}) +A procedure specifying how to filter packages that are displayed. + +@item @code{package-page-extension-proc} (predeterminado: @code{(const '())}) +Extension package for @code{hpcguix-web}. + +@item @code{menu} (predeterminadas: @code{'()}) +Entradas adicionales en el menú de la página. + +@item @code{channels} (predeterminados: @code{%default-channels}) +List of channels from which the package list is built (@pxref{Canales}). + +@item @code{package-list-expiration} (predeterminado: @code{(* 12 3600)}) +The expiration time, in seconds, after which the package list is rebuilt +from the latest instances of the given channels. +@end table + +See the hpcguix-web repository for a +@uref{https://github.com/UMCUGenetics/hpcguix-web/blob/master/hpcweb-configuration.scm, +complete example}. + +@item @code{package} (predeterminado: @code{hpcguix-web}) +The hpcguix-web package to use. +@end table +@end deftp + +A typical hpcguix-web service declaration looks like this: + +@example +(service hpcguix-web-service-type + (hpcguix-web-configuration + (specs + #~(define site-config + (hpcweb-configuration + (title-prefix "Guix-HPC - ") + (menu '(("/about" "ABOUT")))))))) +@end example + +@quotation Nota +The hpcguix-web service periodically updates the package list it publishes +by pulling channels from Git. To that end, it needs to access X.509 +certificates so that it can authenticate Git servers when communicating over +HTTPS, and it assumes that @file{/etc/ssl/certs} contains those +certificates. + +Thus, make sure to add @code{nss-certs} or another certificate package to +the @code{packages} field of your configuration. @ref{Certificados X.509}, +for more information on X.509 certificates. +@end quotation + +@node Servicios de certificados +@subsection Servicios de certificados + +@cindex Web +@cindex HTTP, HTTPS +@cindex Let's Encrypt +@cindex certificados TLS +The @code{(gnu services certbot)} module provides a service to automatically +obtain a valid TLS certificate from the Let's Encrypt certificate +authority. These certificates can then be used to serve content securely +over HTTPS or other TLS-based protocols, with the knowledge that the client +will be able to verify the server's authenticity. + +@url{https://letsencrypt.org/, Let's Encrypt} provides the @code{certbot} +tool to automate the certification process. This tool first securely +generates a key on the server. It then makes a request to the Let's Encrypt +certificate authority (CA) to sign the key. The CA checks that the request +originates from the host in question by using a challenge-response protocol, +requiring the server to provide its response over HTTP. If that protocol +completes successfully, the CA signs the key, resulting in a certificate. +That certificate is valid for a limited period of time, and therefore to +continue to provide TLS services, the server needs to periodically ask the +CA to renew its signature. + +The certbot service automates this process: the initial key generation, the +initial certification request to the Let's Encrypt service, the web server +challenge/response integration, writing the certificate to disk, the +automated periodic renewals, and the deployment tasks associated with the +renewal (e.g.@: reloading services, copying keys with different +permissions). + +Certbot is run twice a day, at a random minute within the hour. It won't do +anything until your certificates are due for renewal or revoked, but running +it regularly would give your service a chance of staying online in case a +Let's Encrypt-initiated revocation happened for some reason. + +By using this service, you agree to the ACME Subscriber Agreement, which can +be found there: @url{https://acme-v01.api.letsencrypt.org/directory}. + +@defvr {Variable Scheme} certbot-service-type +A service type for the @code{certbot} Let's Encrypt client. Its value must +be a @code{certbot-configuration} record as in this example: + +@example +(define %nginx-deploy-hook + (program-file + "nginx-deploy-hook" + #~(let ((pid (call-with-input-file "/var/run/nginx/pid" read))) + (kill pid SIGHUP)))) + +(service certbot-service-type + (certbot-configuration + (email "foo@@example.net") + (certificates + (list + (certificate-configuration + (domains '("example.net" "www.example.net")) + (deploy-hook %nginx-deploy-hook)) + (certificate-configuration + (domains '("bar.example.net"))))))) +@end example + +See below for details about @code{certbot-configuration}. +@end defvr + +@deftp {Tipo de datos} certbot-configuration +Data type representing the configuration of the @code{certbot} service. +This type has the following parameters: + +@table @asis +@item @code{package} (predeterminado: @code{certbot}) +El paquete certbot usado. + +@item @code{webroot} (predeterminado: @code{/var/www}) +The directory from which to serve the Let's Encrypt challenge/response +files. + +@item @code{certificates} (predeterminados: @code{()}) +A list of @code{certificates-configuration}s for which to generate +certificates and request signatures. Each certificate has a @code{name} and +several @code{domains}. + +@item @code{email} +Mandatory email used for registration, recovery contact, and important +account notifications. + +@item @code{rsa-key-size} (predeterminado: @code{2048}) +Tamaño de la clave RSA. + +@item @code{default-location} (predeterminada: @i{vea a continuación}) +The default @code{nginx-location-configuration}. Because @code{certbot} +needs to be able to serve challenges and responses, it needs to be able to +run a web server. It does so by extending the @code{nginx} web service with +an @code{nginx-server-configuration} listening on the @var{domains} on port +80, and which has a @code{nginx-location-configuration} for the +@code{/.well-known/} URI path subspace used by Let's Encrypt. @xref{Servicios Web}, for more on these nginx configuration data types. + +Requests to other URL paths will be matched by the @code{default-location}, +which if present is added to all @code{nginx-server-configuration}s. + +By default, the @code{default-location} will issue a redirect from +@code{http://@var{domain}/...} to @code{https://@var{domain}/...}, leaving +you to define what to serve on your site via @code{https}. + +Pass @code{#f} to not issue a default location. +@end table +@end deftp + +@deftp {Tipo de datos} certificate-configuration +Data type representing the configuration of a certificate. This type has +the following parameters: + +@table @asis +@item @code{name} (predeterminado: @i{vea a continuación}) +This name is used by Certbot for housekeeping and in file paths; it doesn't +affect the content of the certificate itself. To see certificate names, run +@code{certbot certificates}. + +Its default is the first provided domain. + +@item @code{domains} (predeterminado: @code{()}) +The first domain provided will be the subject CN of the certificate, and all +domains will be Subject Alternative Names on the certificate. + +@item @code{deploy-hook} (predeterminado: @code{#f}) +Command to be run in a shell once for each successfully issued certificate. +For this command, the shell variable @code{$RENEWED_LINEAGE} will point to +the config live subdirectory (for example, +@samp{"/etc/letsencrypt/live/example.com"}) containing the new certificates +and keys; the shell variable @code{$RENEWED_DOMAINS} will contain a +space-delimited list of renewed certificate domains (for example, +@samp{"example.com www.example.com"}. + +@end table +@end deftp + +For each @code{certificate-configuration}, the certificate is saved to +@code{/etc/letsencrypt/live/@var{name}/fullchain.pem} and the key is saved +to @code{/etc/letsencrypt/live/@var{name}/privkey.pem}. +@node Servicios DNS +@subsection Servicios DNS +@cindex DNS (domain name system) +@cindex domain name system (DNS) + +The @code{(gnu services dns)} module provides services related to the +@dfn{domain name system} (DNS). It provides a server service for hosting an +@emph{authoritative} DNS server for multiple zones, slave or master. This +service uses @uref{https://www.knot-dns.cz/, Knot DNS}. And also a caching +and forwarding DNS server for the LAN, which uses +@uref{http://www.thekelleys.org.uk/dnsmasq/doc.html, dnsmasq}. + +@subsubheading Servicio Knot + +An example configuration of an authoritative server for two zones, one +master and one slave, is: + +@lisp +(define-zone-entries example.org.zone +;; Name TTL Class Type Data + ("@@" "" "IN" "A" "127.0.0.1") + ("@@" "" "IN" "NS" "ns") + ("ns" "" "IN" "A" "127.0.0.1")) + +(define master-zone + (knot-zone-configuration + (domain "example.org") + (zone (zone-file + (origin "example.org") + (entries example.org.zone))))) + +(define slave-zone + (knot-zone-configuration + (domain "plop.org") + (dnssec-policy "default") + (master (list "plop-master")))) + +(define plop-master + (knot-remote-configuration + (id "plop-master") + (address (list "208.76.58.171")))) + +(operating-system + ;; ... + (services (cons* (service knot-service-type + (knot-configuration + (remotes (list plop-master)) + (zones (list master-zone slave-zone)))) + ;; ... + %base-services))) +@end lisp + +@deffn {Variable Scheme} knot-service-type +This is the type for the Knot DNS server. + +Knot DNS is an authoritative DNS server, meaning that it can serve multiple +zones, that is to say domain names you would buy from a registrar. This +server is not a resolver, meaning that it can only resolve names for which +it is authoritative. This server can be configured to serve zones as a +master server or a slave server as a per-zone basis. Slave zones will get +their data from masters, and will serve it as an authoritative server. From +the point of view of a resolver, there is no difference between master and +slave. + +The following data types are used to configure the Knot DNS server: +@end deffn + +@deftp {Tipo de datos} knot-key-configuration +Data type representing a key. This type has the following parameters: + +@table @asis +@item @code{id} (predeterminado: @code{""}) +An identifier for other configuration fields to refer to this key. IDs must +be unique and must not be empty. + +@item @code{algorithm} (predeterminado: @code{#f}) +The algorithm to use. Choose between @code{#f}, @code{'hmac-md5}, +@code{'hmac-sha1}, @code{'hmac-sha224}, @code{'hmac-sha256}, +@code{'hmac-sha384} and @code{'hmac-sha512}. + +@item @code{secret} (predeterminado: @code{""}) +The secret key itself. + +@end table +@end deftp + +@deftp {Tipo de datos} knot-acl-configuration +Data type representing an Access Control List (ACL) configuration. This +type has the following parameters: + +@table @asis +@item @code{id} (predeterminado: @code{""}) +An identifier for ether configuration fields to refer to this key. IDs must +be unique and must not be empty. + +@item @code{address} (predeterminada: @code{'()}) +An ordered list of IP addresses, network subnets, or network ranges +represented with strings. The query must match one of them. Empty value +means that address match is not required. + +@item @code{key} (predeterminada: @code{'()}) +An ordered list of references to keys represented with strings. The string +must match a key ID defined in a @code{knot-key-configuration}. No key +means that a key is not require to match that ACL. + +@item @code{action} (predeterminada: @code{'()}) +An ordered list of actions that are permitted or forbidden by this ACL. +Possible values are lists of zero or more elements from @code{'transfer}, +@code{'notify} and @code{'update}. + +@item @code{deny?} (predeterminado: @code{#f}) +When true, the ACL defines restrictions. Listed actions are forbidden. +When false, listed actions are allowed. + +@end table +@end deftp + +@deftp {Tipo de datos} zone-entry +Data type represnting a record entry in a zone file. This type has the +following parameters: + +@table @asis +@item @code{name} (predeterminado: @code{"@@"}) +The name of the record. @code{"@@"} refers to the origin of the zone. +Names are relative to the origin of the zone. For example, in the +@code{example.org} zone, @code{"ns.example.org"} actually refers to +@code{ns.example.org.example.org}. Names ending with a dot are absolute, +which means that @code{"ns.example.org."} refers to @code{ns.example.org}. + +@item @code{ttl} (predeterminado: @code{""}) +The Time-To-Live (TTL) of this record. If not set, the default TTL is used. + +@item @code{class} (predeterminada: @code{"IN"}) +The class of the record. Knot currently supports only @code{"IN"} and +partially @code{"CH"}. + +@item @code{type} (predeterminado: @code{"A"}) +The type of the record. Common types include A (IPv4 address), AAAA (IPv6 +address), NS (Name Server) and MX (Mail eXchange). Many other types are +defined. + +@item @code{data} (predeterminados: @code{""}) +The data contained in the record. For instance an IP address associated +with an A record, or a domain name associated with an NS record. Remember +that domain names are relative to the origin unless they end with a dot. + +@end table +@end deftp + +@deftp {Tipo de datos} zone-file +Data type representing the content of a zone file. This type has the +following parameters: + +@table @asis +@item @code{entries} (predeterminadas: @code{'()}) +The list of entries. The SOA record is taken care of, so you don't need to +put it in the list of entries. This list should probably contain an entry +for your primary authoritative DNS server. Other than using a list of +entries directly, you can use @code{define-zone-entries} to define a object +containing the list of entries more easily, that you can later pass to the +@code{entries} field of the @code{zone-file}. + +@item @code{origin} (predeterminado: @code{""}) +The name of your zone. This parameter cannot be empty. + +@item @code{ns} (predeterminado: @code{"ns"}) +The domain of your primary authoritative DNS server. The name is relative +to the origin, unless it ends with a dot. It is mandatory that this primary +DNS server corresponds to an NS record in the zone and that it is associated +to an IP address in the list of entries. + +@item @code{mail} (predeterminado: @code{"hostmaster"}) +An email address people can contact you at, as the owner of the zone. This +is translated as @code{<mail>@@<origin>}. + +@item @code{serial} (predeterminado: @code{1}) +The serial number of the zone. As this is used to keep track of changes by +both slaves and resolvers, it is mandatory that it @emph{never} decreases. +Always increment it when you make a change in your zone. + +@item @code{refresh} (predeterminado: @code{(* 2 24 3600)}) +The frequency at which slaves will do a zone transfer. This value is a +number of seconds. It can be computed by multiplications or with +@code{(string->duration)}. + +@item @code{retry} (predeterminado: @code{(* 15 60)}) +The period after which a slave will retry to contact its master when it +fails to do so a first time. + +@item @code{expiry} (predeterminado: @code{(* 14 24 3600)}) +Default TTL of records. Existing records are considered correct for at most +this amount of time. After this period, resolvers will invalidate their +cache and check again that it still exists. + +@item @code{nx} (predeterminado: @code{3600}) +Default TTL of inexistant records. This delay is usually short because you +want your new domains to reach everyone quickly. + +@end table +@end deftp + +@deftp {Tipo de datos} knot-remote-configuration +Data type representing a remote configuration. This type has the following +parameters: + +@table @asis +@item @code{id} (predeterminado: @code{""}) +An identifier for other configuration fields to refer to this remote. IDs +must be unique and must not be empty. + +@item @code{address} (predeterminada: @code{'()}) +An ordered list of destination IP addresses. Addresses are tried in +sequence. An optional port can be given with the @@ separator. For +instance: @code{(list "1.2.3.4" "2.3.4.5@@53")}. Default port is 53. + +@item @code{via} (predeterminada: @code{'()}) +An ordered list of source IP addresses. An empty list will have Knot choose +an appropriate source IP. An optional port can be given with the @@ +separator. The default is to choose at random. + +@item @code{key} (predeterminada: @code{#f}) +A reference to a key, that is a string containing the identifier of a key +defined in a @code{knot-key-configuration} field. + +@end table +@end deftp + +@deftp {Tipo de datos} knot-keystore-configuration +Data type representing a keystore to hold dnssec keys. This type has the +following parameters: + +@table @asis +@item @code{id} (predeterminado: @code{""}) +The id of the keystore. It must not be empty. + +@item @code{backend} (predeterminado: @code{'pem}) +El motor en el que se almacenan las claves. Puede ser @code{'pem} o +@code{'pkcs11}. + +@item @code{config} (predeterminada: @code{"/var/lib/knot/keys/keys"}) +The configuration string of the backend. An example for the PKCS#11 is: +@code{"pkcs11:token=knot;pin-value=1234 +/gnu/store/.../lib/pkcs11/libsofthsm2.so"}. For the pem backend, the string +reprensents a path in the file system. + +@end table +@end deftp + +@deftp {Tipo de datos} knot-policy-configuration +Data type representing a dnssec policy. Knot DNS is able to automatically +sign your zones. It can either generate and manage your keys automatically +or use keys that you generate. + +Dnssec is usually implemented using two keys: a Key Signing Key (KSK) that +is used to sign the second, and a Zone Signing Key (ZSK) that is used to +sign the zone. In order to be trusted, the KSK needs to be present in the +parent zone (usually a top-level domain). If your registrar supports +dnssec, you will have to send them your KSK's hash so they can add a DS +record in their zone. This is not automated and need to be done each time +you change your KSK. + +The policy also defines the lifetime of keys. Usually, ZSK can be changed +easily and use weaker cryptographic functions (they use lower parameters) in +order to sign records quickly, so they are changed often. The KSK however +requires manual interaction with the registrar, so they are changed less +often and use stronger parameters because they sign only one record. + +Este tipo tiene los siguientes parámetros: + +@table @asis +@item @code{id} (predeterminado: @code{""}) +The id of the policy. It must not be empty. + +@item @code{keystore} (predeterminado: @code{"default"}) +A reference to a keystore, that is a string containing the identifier of a +keystore defined in a @code{knot-keystore-configuration} field. The +@code{"default"} identifier means the default keystore (a kasp database that +was setup by this service). + +@item @code{manual?} (predeterminado: @code{#f}) +Whether the key management is manual or automatic. + +@item @code{single-type-signing?} (predeterminado: @code{#f}) +When @code{#t}, use the Single-Type Signing Scheme. + +@item @code{algorithm} (predeterminado: @code{"ecdsap256sha256"}) +An algorithm of signing keys and issued signatures. + +@item @code{ksk-size} (predeterminado: @code{256}) +The length of the KSK. Note that this value is correct for the default +algorithm, but would be unsecure for other algorithms. + +@item @code{zsk-size} (predeterminado: @code{256}) +The length of the ZSK. Note that this value is correct for the default +algorithm, but would be unsecure for other algorithms. + +@item @code{dnskey-ttl} (predeterminado: @code{'default}) +The TTL value for DNSKEY records added into zone apex. The special +@code{'default} value means same as the zone SOA TTL. + +@item @code{zsk-lifetime} (predeterminado: @code{(* 30 24 3600)}) +The period between ZSK publication and the next rollover initiation. + +@item @code{propagation-delay} (predeterminado: @code{(* 24 3600)}) +An extra delay added for each key rollover step. This value should be high +enough to cover propagation of data from the master server to all slaves. + +@item @code{rrsig-lifetime} (predeterminado: @code{(* 14 24 3600)}) +A validity period of newly issued signatures. + +@item @code{rrsig-refresh} (predeterminado: @code{(* 7 24 3600)}) +A period how long before a signature expiration the signature will be +refreshed. + +@item @code{nsec3?} (predeterminado: @code{#f}) +When @code{#t}, NSEC3 will be used instead of NSEC. + +@item @code{nsec3-iterations} (predeterminado: @code{5}) +The number of additional times the hashing is performed. + +@item @code{nsec3-salt-length} (predeterminado: @code{8}) +The length of a salt field in octets, which is appended to the original +owner name before hashing. + +@item @code{nsec3-salt-lifetime} (predeterminado: @code{(* 30 24 3600)}) +The validity period of newly issued salt field. + +@end table +@end deftp + +@deftp {Tipo de datos} knot-zone-configuration +Data type representing a zone served by Knot. This type has the following +parameters: + +@table @asis +@item @code{domain} (predeterminado: @code{""}) +The domain served by this configuration. It must not be empty. + +@item @code{file} (predeterminado: @code{""}) +The file where this zone is saved. This parameter is ignored by master +zones. Empty means default location that depends on the domain name. + +@item @code{zone} (predeterminado: @code{(zone-file)}) +The content of the zone file. This parameter is ignored by slave zones. It +must contain a zone-file record. + +@item @code{master} (predeterminado: @code{'()}) +A list of master remotes. When empty, this zone is a master. When set, +this zone is a slave. This is a list of remotes identifiers. + +@item @code{ddns-master} (predeterminado: @code{#f}) +The main master. When empty, it defaults to the first master in the list of +masters. + +@item @code{notify} (predeterminado: @code{'()}) +A list of slave remote identifiers. + +@item @code{acl} (predeterminado: @code{'()}) +A list of acl identifiers. + +@item @code{semantic-checks?} (predeterminado: @code{#f}) +When set, this adds more semantic checks to the zone. + +@item @code{disable-any?} (predeterminado: @code{#f}) +When set, this forbids queries of the ANY type. + +@item @code{zonefile-sync} (predeterminado: @code{0}) +The delay between a modification in memory and on disk. 0 means immediate +synchronization. + +@item @code{serial-policy} (predeterminado: @code{'increment}) +A policy between @code{'increment} and @code{'unixtime}. + +@end table +@end deftp + +@deftp {Tipo de datos} knot-configuration +Data type representing the Knot configuration. This type has the following +parameters: + +@table @asis +@item @code{knot} (predeterminado: @code{knot}) +El paquete Knot. + +@item @code{run-directory} (predeterminado: @code{"/var/run/knot"}) +The run directory. This directory will be used for pid file and sockets. + +@item @code{listen-v4} (predeterminada: @code{"0.0.0.0"}) +La dirección IP en la que escuchar. + +@item @code{listen-v6} (predeterminada: @code{"::"}) +La dirección IP en la que escuchar. + +@item @code{listen-port} (predeterminado: @code{53}) +El puerto en el que escuchar. + +@item @code{keys} (predeterminada: @code{'()}) +The list of knot-key-configuration used by this configuration. + +@item @code{acls} (predeterminado: @code{'()}) +The list of knot-acl-configuration used by this configuration. + +@item @code{remotes} (predeterminada: @code{'()}) +The list of knot-remote-configuration used by this configuration. + +@item @code{zones} (predeterminada: @code{'()}) +The list of knot-zone-configuration used by this configuration. + +@end table +@end deftp + +@subsubheading Servicio Dnsmasq + +@deffn {Variable Scheme} dnsmasq-service-type +This is the type of the dnsmasq service, whose value should be an +@code{dnsmasq-configuration} object as in this example: + +@example +(service dnsmasq-service-type + (dnsmasq-configuration + (no-resolv? #t) + (servers '("192.168.1.1")))) +@end example +@end deffn + +@deftp {Tipo de datos} dnsmasq-configuration +Data type representing the configuration of dnsmasq. + +@table @asis +@item @code{package} (predeterminado: @var{dnsmasq}) +Package object of the dnsmasq server. + +@item @code{no-hosts?} (predeterminado: @code{#f}) +When true, don't read the hostnames in /etc/hosts. + +@item @code{port} (predeterminado: @code{53}) +The port to listen on. Setting this to zero completely disables DNS +responses, leaving only DHCP and/or TFTP functions. + +@item @code{local-service?} (predeterminado: @code{#t}) +Accept DNS queries only from hosts whose address is on a local subnet, ie a +subnet for which an interface exists on the server. + +@item @code{listen-addresses} (predeterminadas: @code{'()}) +Escucha en las direcciones IP proporcionadas. + +@item @code{resolv-file} (predeterminado: @code{"/etc/resolv.conf"}) +The file to read the IP address of the upstream nameservers from. + +@item @code{no-resolv?} (predeterminado: @code{#f}) +When true, don't read @var{resolv-file}. + +@item @code{servers} (predeterminados: @code{'()}) +Specify IP address of upstream servers directly. + +@item @code{cache-size} (predeterminado: @code{150}) +Set the size of dnsmasq's cache. Setting the cache size to zero disables +caching. + +@item @code{negative-cache?} (predeterminado: @code{#t}) +When false, disable negative caching. + +@end table +@end deftp + +@subsubheading Servicio ddclient + +@cindex ddclient +The ddclient service described below runs the ddclient daemon, which takes +care of automatically updating DNS entries for service providers such as +@uref{https://dyn.com/dns/, Dyn}. + +The following example show instantiates the service with its default +configuration: + +@example +(service ddclient-service-type) +@end example + +Note that ddclient needs to access credentials that are stored in a +@dfn{secret file}, by default @file{/etc/ddclient/secrets} (see +@code{secret-file} below.) You are expected to create this file manually, +in an ``out-of-band'' fashion (you @emph{could} make this file part of the +service configuration, for instance by using @code{plain-file}, but it will +be world-readable @i{via} @file{/gnu/store}.) See the examples in the +@file{share/ddclient} directory of the @code{ddclient} package. + +@c %start of fragment + +Los campos disponibles de @code{ddclient-configuration} son: + +@deftypevr {@code{ddclient-configuration} parameter} package ddclient +El paquete ddclient. + +@end deftypevr + +@deftypevr {@code{ddclient-configuration} parameter} integer daemon +The period after which ddclient will retry to check IP and domain name. + +Defaults to @samp{300}. + +@end deftypevr + +@deftypevr {@code{ddclient-configuration} parameter} boolean syslog +Use syslog for the output. + +Defaults to @samp{#t}. + +@end deftypevr + +@deftypevr {@code{ddclient-configuration} parameter} string mail +Mail to user. + +Defaults to @samp{"root"}. + +@end deftypevr + +@deftypevr {@code{ddclient-configuration} parameter} string mail-failure +Mail failed update to user. + +Defaults to @samp{"root"}. + +@end deftypevr + +@deftypevr {@code{ddclient-configuration} parameter} string pid +The ddclient PID file. + +Defaults to @samp{"/var/run/ddclient/ddclient.pid"}. + +@end deftypevr + +@deftypevr {@code{ddclient-configuration} parameter} boolean ssl +Enable SSL support. + +Defaults to @samp{#t}. + +@end deftypevr + +@deftypevr {@code{ddclient-configuration} parameter} string user +Specifies the user name or ID that is used when running ddclient program. + +Defaults to @samp{"ddclient"}. + +@end deftypevr + +@deftypevr {@code{ddclient-configuration} parameter} string group +Group of the user who will run the ddclient program. + +Defaults to @samp{"ddclient"}. + +@end deftypevr + +@deftypevr {@code{ddclient-configuration} parameter} string secret-file +Secret file which will be appended to @file{ddclient.conf} file. This file +contains credentials for use by ddclient. You are expected to create it +manually. + +Defaults to @samp{"/etc/ddclient/secrets.conf"}. + +@end deftypevr + +@deftypevr {@code{ddclient-configuration} parameter} list extra-options +Extra options will be appended to @file{ddclient.conf} file. + +Defaults to @samp{()}. + +@end deftypevr + + +@c %end of fragment + + +@node Servicios VPN +@subsection Servicios VPN +@cindex VPN (red virtual privada) +@cindex red virtual privada (VPN) + +The @code{(gnu services vpn)} module provides services related to +@dfn{virtual private networks} (VPNs). It provides a @emph{client} service +for your machine to connect to a VPN, and a @emph{servire} service for your +machine to host a VPN. Both services use @uref{https://openvpn.net/, +OpenVPN}. + +@deffn {Procedimiento Scheme} openvpn-client-service @ + [#:config (openvpn-client-configuration)] + +Devuelve un servicio que ejecuta @command{openvpn}, un daemon VPN, como +cliente. +@end deffn + +@deffn {Procedimiento Scheme} openvpn-server-service @ + [#:config (openvpn-server-configuration)] + +Devuelve un servicio que ejecuta @command{openvpn}, un daemon VPN, como +servidor. + +Pueden ejecutarse simultáneamente. +@end deffn + +@c %automatically generated documentation + +Los campos disponibles de @code{openvpn-client-configuration} son: + +@deftypevr {@code{openvpn-client-configuration} parameter} package openvpn +El paquete OpenVPN. + +@end deftypevr + +@deftypevr {@code{openvpn-client-configuration} parameter} string pid-file +The OpenVPN pid file. + +Defaults to @samp{"/var/run/openvpn/openvpn.pid"}. + +@end deftypevr + +@deftypevr {@code{openvpn-client-configuration} parameter} proto proto +The protocol (UDP or TCP) used to open a channel between clients and +servers. + +Defaults to @samp{udp}. + +@end deftypevr + +@deftypevr {@code{openvpn-client-configuration} parameter} dev dev +The device type used to represent the VPN connection. + +Defaults to @samp{tun}. + +@end deftypevr + +@deftypevr {@code{openvpn-client-configuration} parameter} string ca +The certificate authority to check connections against. + +Defaults to @samp{"/etc/openvpn/ca.crt"}. + +@end deftypevr + +@deftypevr {@code{openvpn-client-configuration} parameter} string cert +The certificate of the machine the daemon is running on. It should be +signed by the authority given in @code{ca}. + +Defaults to @samp{"/etc/openvpn/client.crt"}. + +@end deftypevr + +@deftypevr {@code{openvpn-client-configuration} parameter} string key +The key of the machine the daemon is running on. It must be the key whose +certificate is @code{cert}. + +Defaults to @samp{"/etc/openvpn/client.key"}. + +@end deftypevr + +@deftypevr {@code{openvpn-client-configuration} parameter} boolean comp-lzo? +Whether to use the lzo compression algorithm. + +Defaults to @samp{#t}. + +@end deftypevr + +@deftypevr {@code{openvpn-client-configuration} parameter} boolean persist-key? +Don't re-read key files across SIGUSR1 or --ping-restart. + +Defaults to @samp{#t}. + +@end deftypevr + +@deftypevr {@code{openvpn-client-configuration} parameter} boolean persist-tun? +Don't close and reopen TUN/TAP device or run up/down scripts across SIGUSR1 +or --ping-restart restarts. + +Defaults to @samp{#t}. + +@end deftypevr + +@deftypevr {@code{openvpn-client-configuration} parameter} number verbosity +Verbosity level. + +Defaults to @samp{3}. + +@end deftypevr + +@deftypevr {@code{openvpn-client-configuration} parameter} tls-auth-client tls-auth +Add an additional layer of HMAC authentication on top of the TLS control +channel to protect against DoS attacks. + +El valor predeterminado es @samp{#f} + +@end deftypevr + +@deftypevr {@code{openvpn-client-configuration} parameter} key-usage verify-key-usage? +Whether to check the server certificate has server usage extension. + +Defaults to @samp{#t}. + +@end deftypevr + +@deftypevr {@code{openvpn-client-configuration} parameter} bind bind? +Bind to a specific local port number. + +El valor predeterminado es @samp{#f} + +@end deftypevr + +@deftypevr {@code{openvpn-client-configuration} parameter} resolv-retry resolv-retry? +Retry resolving server address. + +Defaults to @samp{#t}. + +@end deftypevr + +@deftypevr {@code{openvpn-client-configuration} parameter} openvpn-remote-list remote +A list of remote servers to connect to. + +Defaults to @samp{()}. + +Los campos disponibles de @code{openvpn-remote-configuration} son: + +@deftypevr {@code{openvpn-remote-configuration} parameter} string name +Nombre del servidor. + +Defaults to @samp{"my-server"}. + +@end deftypevr + +@deftypevr {@code{openvpn-remote-configuration} parameter} number port +Port number the server listens to. + +Defaults to @samp{1194}. + +@end deftypevr + +@end deftypevr +@c %end of automatic openvpn-client documentation + +@c %automatically generated documentation + +Available @code{openvpn-server-configuration} fields are: + +@deftypevr {@code{openvpn-server-configuration} parameter} package openvpn +El paquete OpenVPN. + +@end deftypevr + +@deftypevr {@code{openvpn-server-configuration} parameter} string pid-file +The OpenVPN pid file. + +Defaults to @samp{"/var/run/openvpn/openvpn.pid"}. + +@end deftypevr + +@deftypevr {@code{openvpn-server-configuration} parameter} proto proto +The protocol (UDP or TCP) used to open a channel between clients and +servers. + +Defaults to @samp{udp}. + +@end deftypevr + +@deftypevr {@code{openvpn-server-configuration} parameter} dev dev +The device type used to represent the VPN connection. + +Defaults to @samp{tun}. + +@end deftypevr + +@deftypevr {@code{openvpn-server-configuration} parameter} string ca +The certificate authority to check connections against. + +Defaults to @samp{"/etc/openvpn/ca.crt"}. + +@end deftypevr + +@deftypevr {@code{openvpn-server-configuration} parameter} string cert +The certificate of the machine the daemon is running on. It should be +signed by the authority given in @code{ca}. + +Defaults to @samp{"/etc/openvpn/client.crt"}. + +@end deftypevr + +@deftypevr {@code{openvpn-server-configuration} parameter} string key +The key of the machine the daemon is running on. It must be the key whose +certificate is @code{cert}. + +Defaults to @samp{"/etc/openvpn/client.key"}. + +@end deftypevr + +@deftypevr {@code{openvpn-server-configuration} parameter} boolean comp-lzo? +Whether to use the lzo compression algorithm. + +Defaults to @samp{#t}. + +@end deftypevr + +@deftypevr {@code{openvpn-server-configuration} parameter} boolean persist-key? +Don't re-read key files across SIGUSR1 or --ping-restart. + +Defaults to @samp{#t}. + +@end deftypevr + +@deftypevr {@code{openvpn-server-configuration} parameter} boolean persist-tun? +Don't close and reopen TUN/TAP device or run up/down scripts across SIGUSR1 +or --ping-restart restarts. + +Defaults to @samp{#t}. + +@end deftypevr + +@deftypevr {@code{openvpn-server-configuration} parameter} number verbosity +Verbosity level. + +Defaults to @samp{3}. + +@end deftypevr + +@deftypevr {@code{openvpn-server-configuration} parameter} tls-auth-server tls-auth +Add an additional layer of HMAC authentication on top of the TLS control +channel to protect against DoS attacks. + +El valor predeterminado es @samp{#f} + +@end deftypevr + +@deftypevr {@code{openvpn-server-configuration} parameter} number port +Specifies the port number on which the server listens. + +Defaults to @samp{1194}. + +@end deftypevr + +@deftypevr {@code{openvpn-server-configuration} parameter} ip-mask server +An ip and mask specifying the subnet inside the virtual network. + +Defaults to @samp{"10.8.0.0 255.255.255.0"}. + +@end deftypevr + +@deftypevr {@code{openvpn-server-configuration} parameter} cidr6 server-ipv6 +A CIDR notation specifying the IPv6 subnet inside the virtual network. + +El valor predeterminado es @samp{#f} + +@end deftypevr + +@deftypevr {@code{openvpn-server-configuration} parameter} string dh +The Diffie-Hellman parameters file. + +Defaults to @samp{"/etc/openvpn/dh2048.pem"}. + +@end deftypevr + +@deftypevr {@code{openvpn-server-configuration} parameter} string ifconfig-pool-persist +The file that records client IPs. + +Defaults to @samp{"/etc/openvpn/ipp.txt"}. + +@end deftypevr + +@deftypevr {@code{openvpn-server-configuration} parameter} gateway redirect-gateway? +When true, the server will act as a gateway for its clients. + +El valor predeterminado es @samp{#f} + +@end deftypevr + +@deftypevr {@code{openvpn-server-configuration} parameter} boolean client-to-client? +When true, clients are allowed to talk to each other inside the VPN. + +El valor predeterminado es @samp{#f} + +@end deftypevr + +@deftypevr {@code{openvpn-server-configuration} parameter} keepalive keepalive +Causes ping-like messages to be sent back and forth over the link so that +each side knows when the other side has gone down. @code{keepalive} +requires a pair. The first element is the period of the ping sending, and +the second element is the timeout before considering the other side down. + +@end deftypevr + +@deftypevr {@code{openvpn-server-configuration} parameter} number max-clients +The maximum number of clients. + +Defaults to @samp{100}. + +@end deftypevr + +@deftypevr {@code{openvpn-server-configuration} parameter} string status +The status file. This file shows a small report on current connection. It +is truncated and rewritten every minute. + +Defaults to @samp{"/var/run/openvpn/status"}. + +@end deftypevr + +@deftypevr {@code{openvpn-server-configuration} parameter} openvpn-ccd-list client-config-dir +The list of configuration for some clients. + +Defaults to @samp{()}. + +Available @code{openvpn-ccd-configuration} fields are: + +@deftypevr {@code{openvpn-ccd-configuration} parameter} string name +Nombre del cliente. + +Defaults to @samp{"client"}. + +@end deftypevr + +@deftypevr {@code{openvpn-ccd-configuration} parameter} ip-mask iroute +Client own network + +El valor predeterminado es @samp{#f} + +@end deftypevr + +@deftypevr {@code{openvpn-ccd-configuration} parameter} ip-mask ifconfig-push +Client VPN IP. + +El valor predeterminado es @samp{#f} + +@end deftypevr + +@end deftypevr + + +@c %end of automatic openvpn-server documentation + + +@node Sistema de ficheros en red +@subsection Sistema de ficheros en red +@cindex NFS + +The @code{(gnu services nfs)} module provides the following services, which +are most commonly used in relation to mounting or exporting directory trees +as @dfn{network file systems} (NFS). + +@subsubheading RPC Bind Service +@cindex rpcbind + +The RPC Bind service provides a facility to map program numbers into +universal addresses. Many NFS related services use this facility. Hence it +is automatically started when a dependent service starts. + +@defvr {Variable Scheme} rpcbind-service-type +A service type for the RPC portmapper daemon. +@end defvr + + +@deftp {Tipo de datos} rpcbind-configuration +Data type representing the configuration of the RPC Bind Service. This type +has the following parameters: +@table @asis +@item @code{rpcbind} (default: @code{rpcbind}) +The rpcbind package to use. + +@item @code{warm-start?} (default: @code{#t}) +If this parameter is @code{#t}, then the daemon will read a state file on +startup thus reloading state information saved by a previous instance. +@end table +@end deftp + + +@subsubheading Pipefs Pseudo File System +@cindex pipefs +@cindex rpc_pipefs + +The pipefs file system is used to transfer NFS related data between the +kernel and user space programs. + +@defvr {Variable Scheme} pipefs-service-type +A service type for the pipefs pseudo file system. +@end defvr + +@deftp {Tipo de datos} pipefs-configuration +Data type representing the configuration of the pipefs pseudo file system +service. This type has the following parameters: +@table @asis +@item @code{mount-point} (default: @code{"/var/lib/nfs/rpc_pipefs"}) +The directory to which the file system is to be attached. +@end table +@end deftp + + +@subsubheading Servicio del daemon GSS +@cindex GSSD +@cindex GSS +@cindex global security system + +The @dfn{global security system} (GSS) daemon provides strong security for +RPC based protocols. Before exchanging RPC requests an RPC client must +establish a security context. Typically this is done using the Kerberos +command @command{kinit} or automatically at login time using PAM services +(@pxref{Servicios Kerberos}). + +@defvr {Variable Scheme} gss-service-type +Un tipo de servicio para el daemon del sistema de seguridad global (GSS). +@end defvr + +@deftp {Tipo de datos} gss-configuration +Data type representing the configuration of the GSS daemon service. This +type has the following parameters: +@table @asis +@item @code{nfs-utils} (predeterminado: @code{nfs-utils}) +The package in which the @command{rpc.gssd} command is to be found. + +@item @code{pipefs-directory} (predeterminado: @code{"/var/lib/nfs/rpc_pipefs"}) +The directory where the pipefs file system is mounted. + +@end table +@end deftp + + +@subsubheading Servicio del daemon IDMAP +@cindex idmapd +@cindex name mapper + +The idmap daemon service provides mapping between user IDs and user names. +Typically it is required in order to access file systems mounted via NFSv4. + +@defvr {Variable Scheme} idmap-service-type +A service type for the Identity Mapper (IDMAP) daemon. +@end defvr + +@deftp {Tipo de datos} idmap-configuration +Data type representing the configuration of the IDMAP daemon service. This +type has the following parameters: +@table @asis +@item @code{nfs-utils} (predeterminado: @code{nfs-utils}) +The package in which the @command{rpc.idmapd} command is to be found. + +@item @code{pipefs-directory} (predeterminado: @code{"/var/lib/nfs/rpc_pipefs"}) +The directory where the pipefs file system is mounted. + +@item @code{domain} (predeterminado: @code{#f}) +The local NFSv4 domain name. This must be a string or @code{#f}. If it is +@code{#f} then the daemon will use the host's fully qualified domain name. + +@end table +@end deftp + +@node Integración continua +@subsection Integración continua + +@cindex integración continua +@uref{https://git.savannah.gnu.org/cgit/guix/guix-cuirass.git, Cuirass} is a +continuous integration tool for Guix. It can be used both for development +and for providing substitutes to others (@pxref{Sustituciones}). + +El módulo @code{(gnu services cuirass)} proporciona el siguiente servicio. + +@defvr {Procedimiento Scheme} cuirass-service-type +The type of the Cuirass service. Its value must be a +@code{cuirass-configuration} object, as described below. +@end defvr + +To add build jobs, you have to set the @code{specifications} field of the +configuration. Here is an example of a service that polls the Guix +repository and builds the packages from a manifest. Some of the packages +are defined in the @code{"custom-packages"} input, which is the equivalent +of @code{GUIX_PACKAGE_PATH}. + +@example +(define %cuirass-specs + #~(list + '((#:name . "my-manifest") + (#:load-path-inputs . ("guix")) + (#:package-path-inputs . ("custom-packages")) + (#:proc-input . "guix") + (#:proc-file . "build-aux/cuirass/gnu-system.scm") + (#:proc . cuirass-jobs) + (#:proc-args . ((subset . "manifests") + (systems . ("x86_64-linux")) + (manifests . (("config" . "guix/manifest.scm"))))) + (#:inputs . (((#:name . "guix") + (#:url . "git://git.savannah.gnu.org/guix.git") + (#:load-path . ".") + (#:branch . "master") + (#:no-compile? . #t)) + ((#:name . "config") + (#:url . "git://git.example.org/config.git") + (#:load-path . ".") + (#:branch . "master") + (#:no-compile? . #t)) + ((#:name . "custom-packages") + (#:url . "git://git.example.org/custom-packages.git") + (#:load-path . ".") + (#:branch . "master") + (#:no-compile? . #t))))))) + +(service cuirass-service-type + (cuirass-configuration + (specifications %cuirass-specs))) +@end example + +While information related to build jobs is located directly in the +specifications, global settings for the @command{cuirass} process are +accessible in other @code{cuirass-configuration} fields. + +@deftp {Tipo de datos} cuirass-configuration +Data type representing the configuration of Cuirass. + +@table @asis +@item @code{log-file} (predeterminado: @code{"/var/log/cuirass.log"}) +Location of the log file. + +@item @code{cache-directory} (predeterminado: @code{"/var/cache/cuirass"}) +Location of the repository cache. + +@item @code{user} (predeterminado: @code{"cuirass"}) +Owner of the @code{cuirass} process. + +@item @code{group} (predeterminado: @code{"cuirass"}) +Owner's group of the @code{cuirass} process. + +@item @code{interval} (predeterminado: @code{60}) +Number of seconds between the poll of the repositories followed by the +Cuirass jobs. + +@item @code{database} (predeterminada: @code{"/var/lib/cuirass/cuirass.db"}) +Location of sqlite database which contains the build results and previously +added specifications. + +@item @code{ttl} (predeterminado: @code{(* 30 24 3600)}) +Specifies the time-to-live (TTL) in seconds of garbage collector roots that +are registered for build results. This means that build results are +protected from garbage collection for at least @var{ttl} seconds. + +@item @code{port} (predeterminado: @code{8081}) +Número de puerto usado por el servidor HTTP. + +@item --listen=@var{dirección} +Listen on the network interface for @var{host}. The default is to accept +connections from localhost. + +@item @code{specifications} (predeterminada: @code{#~'()}) +A gexp (@pxref{Expresiones-G}) that evaluates to a list of specifications, +where a specification is an association list (@pxref{Associations Lists,,, +guile, GNU Guile Reference Manual}) whose keys are keywords +(@code{#:keyword-example}) as shown in the example above. + +@item @code{use-substitutes?} (predeterminado: @code{#f}) +This allows using substitutes to avoid building every dependencies of a job +from source. + +@item @code{one-shot?} (predeterminado: @code{#f}) +Only evaluate specifications and build derivations once. + +@item @code{fallback?} (predeterminado: @code{#f}) +When substituting a pre-built binary fails, fall back to building packages +locally. + +@item @code{cuirass} (predeterminado: @code{cuirass}) +El paquete Cuirass usado. +@end table +@end deftp + +@node Servicios de gestión de energía +@subsection Servicios de gestión de energía + +@cindex tlp +@cindex gestión de energía con TLP +@subsubheading Daemon TLP + +El módulo @code{(gnu services pm)} proporciona una definición de servicio +Guix para la herramienta de gestión de energía de Linux TLP. + +TLP enables various powersaving modes in userspace and kernel. Contrary to +@code{upower-service}, it is not a passive, monitoring tool, as it will +apply custom settings each time a new power source is detected. More +information can be found at @uref{http://linrunner.de/en/tlp/tlp.html, TLP +home page}. + +@deffn {Variable Scheme} tlp-service-type +The service type for the TLP tool. Its value should be a valid TLP +configuration (see below). To use the default settings, simply write: +@example +(service tlp-service-type) +@end example +@end deffn + +By default TLP does not need much configuration but most TLP parameters can +be tweaked using @code{tlp-configuration}. + +Each parameter definition is preceded by its type; for example, +@samp{boolean foo} indicates that the @code{foo} parameter should be +specified as a boolean. Types starting with @code{maybe-} denote parameters +that won't show up in TLP config file when their value is @code{'disabled}. + +@c The following documentation was initially generated by +@c (generate-tlp-documentation) in (gnu services pm). Manually maintained +@c documentation is better, so we shouldn't hesitate to edit below as +@c needed. However if the change you want to make to this documentation +@c can be done in an automated way, it's probably easier to change +@c (generate-documentation) than to make it below and have to deal with +@c the churn as TLP updates. + +Available @code{tlp-configuration} fields are: + +@deftypevr {@code{tlp-configuration} parameter} package tlp +El paquete TLP. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} boolean tlp-enable? +Set to true if you wish to enable TLP. + +Defaults to @samp{#t}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} string tlp-default-mode +Default mode when no power supply can be detected. Alternatives are AC and +BAT. + +Defaults to @samp{"AC"}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} non-negative-integer disk-idle-secs-on-ac +Number of seconds Linux kernel has to wait after the disk goes idle, before +syncing on AC. + +El valor predeterminado es @samp{0}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} non-negative-integer disk-idle-secs-on-bat +Same as @code{disk-idle-ac} but on BAT mode. + +Defaults to @samp{2}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} non-negative-integer max-lost-work-secs-on-ac +Dirty pages flushing periodicity, expressed in seconds. + +Defaults to @samp{15}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} non-negative-integer max-lost-work-secs-on-bat +Same as @code{max-lost-work-secs-on-ac} but on BAT mode. + +Defaults to @samp{60}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list cpu-scaling-governor-on-ac +CPU frequency scaling governor on AC mode. With intel_pstate driver, +alternatives are powersave and performance. With acpi-cpufreq driver, +alternatives are ondemand, powersave, performance and conservative. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list cpu-scaling-governor-on-bat +Same as @code{cpu-scaling-governor-on-ac} but on BAT mode. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-scaling-min-freq-on-ac +Set the min available frequency for the scaling governor on AC. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-scaling-max-freq-on-ac +Set the max available frequency for the scaling governor on AC. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-scaling-min-freq-on-bat +Set the min available frequency for the scaling governor on BAT. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-scaling-max-freq-on-bat +Set the max available frequency for the scaling governor on BAT. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-min-perf-on-ac +Limit the min P-state to control the power dissipation of the CPU, in AC +mode. Values are stated as a percentage of the available performance. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-max-perf-on-ac +Limit the max P-state to control the power dissipation of the CPU, in AC +mode. Values are stated as a percentage of the available performance. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-min-perf-on-bat +Same as @code{cpu-min-perf-on-ac} on BAT mode. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-max-perf-on-bat +Same as @code{cpu-max-perf-on-ac} on BAT mode. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} maybe-boolean cpu-boost-on-ac? +Enable CPU turbo boost feature on AC mode. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} maybe-boolean cpu-boost-on-bat? +Same as @code{cpu-boost-on-ac?} on BAT mode. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} boolean sched-powersave-on-ac? +Allow Linux kernel to minimize the number of CPU cores/hyper-threads used +under light load conditions. + +El valor predeterminado es @samp{#f} + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} boolean sched-powersave-on-bat? +Same as @code{sched-powersave-on-ac?} but on BAT mode. + +Defaults to @samp{#t}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} boolean nmi-watchdog? +Enable Linux kernel NMI watchdog. + +El valor predeterminado es @samp{#f} + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} maybe-string phc-controls +For Linux kernels with PHC patch applied, change CPU voltages. An example +value would be @samp{"F:V F:V F:V F:V"}. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} string energy-perf-policy-on-ac +Set CPU performance versus energy saving policy on AC. Alternatives are +performance, normal, powersave. + +Defaults to @samp{"performance"}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} string energy-perf-policy-on-bat +Same as @code{energy-perf-policy-ac} but on BAT mode. + +Defaults to @samp{"powersave"}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} space-separated-string-list disks-devices +Dispositivos de disco duro. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} space-separated-string-list disk-apm-level-on-ac +Hard disk advanced power management level. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} space-separated-string-list disk-apm-level-on-bat +Same as @code{disk-apm-bat} but on BAT mode. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list disk-spindown-timeout-on-ac +Hard disk spin down timeout. One value has to be specified for each +declared hard disk. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list disk-spindown-timeout-on-bat +Same as @code{disk-spindown-timeout-on-ac} but on BAT mode. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list disk-iosched +Select IO scheduler for disk devices. One value has to be specified for +each declared hard disk. Example alternatives are cfq, deadline and noop. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} string sata-linkpwr-on-ac +SATA aggressive link power management (ALPM) level. Alternatives are +min_power, medium_power, max_performance. + +Defaults to @samp{"max_performance"}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} string sata-linkpwr-on-bat +Same as @code{sata-linkpwr-ac} but on BAT mode. + +Defaults to @samp{"min_power"}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} maybe-string sata-linkpwr-blacklist +Exclude specified SATA host devices for link power management. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} maybe-on-off-boolean ahci-runtime-pm-on-ac? +Enable Runtime Power Management for AHCI controller and disks on AC mode. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} maybe-on-off-boolean ahci-runtime-pm-on-bat? +Same as @code{ahci-runtime-pm-on-ac} on BAT mode. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} non-negative-integer ahci-runtime-pm-timeout +Seconds of inactivity before disk is suspended. + +Defaults to @samp{15}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} string pcie-aspm-on-ac +PCI Express Active State Power Management level. Alternatives are default, +performance, powersave. + +Defaults to @samp{"performance"}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} string pcie-aspm-on-bat +Same as @code{pcie-aspm-ac} but on BAT mode. + +Defaults to @samp{"powersave"}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} string radeon-power-profile-on-ac +Radeon graphics clock speed level. Alternatives are low, mid, high, auto, +default. + +Defaults to @samp{"high"}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} string radeon-power-profile-on-bat +Same as @code{radeon-power-ac} but on BAT mode. + +Defaults to @samp{"low"}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} string radeon-dpm-state-on-ac +Radeon dynamic power management method (DPM). Alternatives are battery, +performance. + +Defaults to @samp{"performance"}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} string radeon-dpm-state-on-bat +Same as @code{radeon-dpm-state-ac} but on BAT mode. + +Defaults to @samp{"battery"}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} string radeon-dpm-perf-level-on-ac +Radeon DPM performance level. Alternatives are auto, low, high. + +Defaults to @samp{"auto"}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} string radeon-dpm-perf-level-on-bat +Same as @code{radeon-dpm-perf-ac} but on BAT mode. + +Defaults to @samp{"auto"}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} on-off-boolean wifi-pwr-on-ac? +Wifi power saving mode. + +El valor predeterminado es @samp{#f} + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} on-off-boolean wifi-pwr-on-bat? +Same as @code{wifi-power-ac?} but on BAT mode. + +Defaults to @samp{#t}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} y-n-boolean wol-disable? +Disable wake on LAN. + +Defaults to @samp{#t}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} non-negative-integer sound-power-save-on-ac +Timeout duration in seconds before activating audio power saving on Intel +HDA and AC97 devices. A value of 0 disables power saving. + +El valor predeterminado es @samp{0}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} non-negative-integer sound-power-save-on-bat +Same as @code{sound-powersave-ac} but on BAT mode. + +Defaults to @samp{1}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} y-n-boolean sound-power-save-controller? +Disable controller in powersaving mode on Intel HDA devices. + +Defaults to @samp{#t}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} boolean bay-poweroff-on-bat? +Enable optical drive in UltraBay/MediaBay on BAT mode. Drive can be powered +on again by releasing (and reinserting) the eject lever or by pressing the +disc eject button on newer models. + +El valor predeterminado es @samp{#f} + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} string bay-device +Name of the optical drive device to power off. + +Defaults to @samp{"sr0"}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} string runtime-pm-on-ac +Runtime Power Management for PCI(e) bus devices. Alternatives are on and +auto. + +Defaults to @samp{"on"}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} string runtime-pm-on-bat +Same as @code{runtime-pm-ac} but on BAT mode. + +Defaults to @samp{"auto"}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} boolean runtime-pm-all? +Runtime Power Management for all PCI(e) bus devices, except blacklisted +ones. + +Defaults to @samp{#t}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list runtime-pm-blacklist +Exclude specified PCI(e) device addresses from Runtime Power Management. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} space-separated-string-list runtime-pm-driver-blacklist +Exclude PCI(e) devices assigned to the specified drivers from Runtime Power +Management. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} boolean usb-autosuspend? +Enable USB autosuspend feature. + +Defaults to @samp{#t}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} maybe-string usb-blacklist +Exclude specified devices from USB autosuspend. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} boolean usb-blacklist-wwan? +Exclude WWAN devices from USB autosuspend. + +Defaults to @samp{#t}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} maybe-string usb-whitelist +Include specified devices into USB autosuspend, even if they are already +excluded by the driver or via @code{usb-blacklist-wwan?}. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} maybe-boolean usb-autosuspend-disable-on-shutdown? +Enable USB autosuspend before shutdown. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} boolean restore-device-state-on-startup? +Restore radio device state (bluetooth, wifi, wwan) from previous shutdown on +system startup. + +El valor predeterminado es @samp{#f} + +@end deftypevr + +@cindex thermald +@cindex escalado de frecuencia de la CPU con thermald +@subsubheading Daemon Thermald + +El módulo @code{(gnu services pm)} proporciona una interfaz con thermald, un +servicio de escalado de frecuencia de la CPU que ayuda a prevenir el +sobrecalentamiento. + +@defvr {Variable Scheme} thermald-service-type +This is the service type for @uref{https://01.org/linux-thermal-daemon/, +thermald}, the Linux Thermal Daemon, which is responsible for controlling +the thermal state of processors and preventing overheating. +@end defvr + +@deftp {Tipo de datos} thermald-configuration +Tipo de datos que representa la configuración de +@code{thermald-service-type}. + +@table @asis +@item @code{ignore-cpuid-check?} (predeterminado: @code{#f}) +Ignore cpuid check for supported CPU models. + +@item @code{thermald} (predeterminado: @var{thermald}) +Package object of thermald. + +@end table +@end deftp + +@node Servicios de audio +@subsection Servicios de audio + +El módulo @code{(gnu services audio)} proporciona un servicio para iniciar +MPD (el daemon de reproducción de música). + +@cindex mpd +@subsubheading Daemon de reproducción de música (MPD) + +El daemon de reproducción de música (MPD) es un servicio que puede +reproducir música mientras se controla desde la máquina local o sobre una +red por una multitud de clientes. + +El siguiente ejemplo muestra como se puede ejecutar @code{mpd} como +@code{"rober"} en el puerto @code{6666}. Usa pulseaudio para su salida. + +@example +(service mpd-service-type + (mpd-configuration + (user "rober") + (port "6666"))) +@end example + +@defvr {Variable Scheme} mpd-service-type +El tipo de servicio para @command{mpd}. +@end defvr + +@deftp {Tipo de datos} mpd-configuration +Data type representing the configuration of @command{mpd}. + +@table @asis +@item @code{user} (predeterminada: @code{"mpd"}) +Usuaria que ejecuta mpd. + +@item @code{music-dir} (predeterminado: @code{"~/Music"}) +The directory to scan for music files. + +@item @code{playlist-dir} (predeterminado: @code{"~/.mpd/playlists"}) +The directory to store playlists. + +@item @code{db-file} (default: @code{"~/.mpd/tag_cache"}) +The location of the music database. + +@item @code{state-file} (default: @code{"~/.mpd/state"}) +The location of the file that stores current MPD's state. + +@item @code{sticker-file} (default: @code{"~/.mpd/sticker.sql"}) +The location of the sticker database. + +@item @code{port} (predeterminado: @code{"6600"}) +Puerto sobre el que se ejecuta mpd. + +@item @code{address} (predeterminada: @code{"any"}) +The address that mpd will bind to. To use a Unix domain socket, an absolute +path can be specified here. + +@end table +@end deftp + +@node Servicios de virtualización +@subsection Servicios de virtualización + +The @code{(gnu services virtualization)} module provides services for the +libvirt and virtlog daemons, as well as other virtualization-related +services. + +@subsubheading Demonio Libvirt +@code{libvirtd} is the server side daemon component of the libvirt +virtualization management system. This daemon runs on host servers and +performs required management tasks for virtualized guests. + +@deffn {Variable Scheme} libvirt-service-type +This is the type of the @uref{https://libvirt.org, libvirt daemon}. Its +value must be a @code{libvirt-configuration}. + +@example +(service libvirt-service-type + (libvirt-configuration + (unix-sock-group "libvirt") + (tls-port "16555"))) +@end example +@end deffn + +@c Auto-generated with (generate-libvirt-documentation) +Available @code{libvirt-configuration} fields are: + +@deftypevr {@code{libvirt-configuration} parameter} package libvirt +Paquete libvirt. + +@end deftypevr + +@deftypevr {@code{libvirt-configuration} parameter} boolean listen-tls? +Flag listening for secure TLS connections on the public TCP/IP port. must +set @code{listen} for this to have any effect. + +It is necessary to setup a CA and issue server certificates before using +this capability. + +Defaults to @samp{#t}. + +@end deftypevr + +@deftypevr {@code{libvirt-configuration} parameter} boolean listen-tcp? +Listen for unencrypted TCP connections on the public TCP/IP port. must set +@code{listen} for this to have any effect. + +Using the TCP socket requires SASL authentication by default. Only SASL +mechanisms which support data encryption are allowed. This is DIGEST_MD5 +and GSSAPI (Kerberos5) + +El valor predeterminado es @samp{#f} + +@end deftypevr + +@deftypevr {@code{libvirt-configuration} parameter} string tls-port +Port for accepting secure TLS connections This can be a port number, or +service name + +Defaults to @samp{"16514"}. + +@end deftypevr + +@deftypevr {@code{libvirt-configuration} parameter} string tcp-port +Port for accepting insecure TCP connections This can be a port number, or +service name + +Defaults to @samp{"16509"}. + +@end deftypevr + +@deftypevr {@code{libvirt-configuration} parameter} string listen-addr +IP address or hostname used for client connections. + +Defaults to @samp{"0.0.0.0"}. + +@end deftypevr + +@deftypevr {@code{libvirt-configuration} parameter} boolean mdns-adv? +Flag toggling mDNS advertisement of the libvirt service. + +Alternatively can disable for all services on a host by stopping the Avahi +daemon. + +El valor predeterminado es @samp{#f} + +@end deftypevr + +@deftypevr {@code{libvirt-configuration} parameter} string mdns-name +Default mDNS advertisement name. This must be unique on the immediate +broadcast network. + +Defaults to @samp{"Virtualization Host <hostname>"}. + +@end deftypevr + +@deftypevr {@code{libvirt-configuration} parameter} string unix-sock-group +UNIX domain socket group ownership. This can be used to allow a 'trusted' +set of users access to management capabilities without becoming root. + +Defaults to @samp{"root"}. + +@end deftypevr + +@deftypevr {@code{libvirt-configuration} parameter} string unix-sock-ro-perms +UNIX socket permissions for the R/O socket. This is used for monitoring VM +status only. + +Defaults to @samp{"0777"}. + +@end deftypevr + +@deftypevr {@code{libvirt-configuration} parameter} string unix-sock-rw-perms +UNIX socket permissions for the R/W socket. Default allows only root. If +PolicyKit is enabled on the socket, the default will change to allow +everyone (eg, 0777) + +Defaults to @samp{"0770"}. + +@end deftypevr + +@deftypevr {@code{libvirt-configuration} parameter} string unix-sock-admin-perms +UNIX socket permissions for the admin socket. Default allows only owner +(root), do not change it unless you are sure to whom you are exposing the +access to. + +Defaults to @samp{"0777"}. + +@end deftypevr + +@deftypevr {@code{libvirt-configuration} parameter} string unix-sock-dir +The directory in which sockets will be found/created. + +Defaults to @samp{"/var/run/libvirt"}. + +@end deftypevr + +@deftypevr {@code{libvirt-configuration} parameter} string auth-unix-ro +Authentication scheme for UNIX read-only sockets. By default socket +permissions allow anyone to connect + +Defaults to @samp{"polkit"}. + +@end deftypevr + +@deftypevr {@code{libvirt-configuration} parameter} string auth-unix-rw +Authentication scheme for UNIX read-write sockets. By default socket +permissions only allow root. If PolicyKit support was compiled into +libvirt, the default will be to use 'polkit' auth. + +Defaults to @samp{"polkit"}. + +@end deftypevr + +@deftypevr {@code{libvirt-configuration} parameter} string auth-tcp +Authentication scheme for TCP sockets. If you don't enable SASL, then all +TCP traffic is cleartext. Don't do this outside of a dev/test scenario. + +Defaults to @samp{"sasl"}. + +@end deftypevr + +@deftypevr {@code{libvirt-configuration} parameter} string auth-tls +Authentication scheme for TLS sockets. TLS sockets already have encryption +provided by the TLS layer, and limited authentication is done by +certificates. + +It is possible to make use of any SASL authentication mechanism as well, by +using 'sasl' for this option + +Defaults to @samp{"none"}. + +@end deftypevr + +@deftypevr {@code{libvirt-configuration} parameter} optional-list access-drivers +API access control scheme. + +By default an authenticated user is allowed access to all APIs. Access +drivers can place restrictions on this. + +Defaults to @samp{()}. + +@end deftypevr + +@deftypevr {@code{libvirt-configuration} parameter} string key-file +Server key file path. If set to an empty string, then no private key is +loaded. + +El valor predeterminado es @samp{""}. + +@end deftypevr + +@deftypevr {@code{libvirt-configuration} parameter} string cert-file +Server key file path. If set to an empty string, then no certificate is +loaded. + +El valor predeterminado es @samp{""}. + +@end deftypevr + +@deftypevr {@code{libvirt-configuration} parameter} string ca-file +Server key file path. If set to an empty string, then no CA certificate is +loaded. + +El valor predeterminado es @samp{""}. + +@end deftypevr + +@deftypevr {@code{libvirt-configuration} parameter} string crl-file +Certificate revocation list path. If set to an empty string, then no CRL is +loaded. + +El valor predeterminado es @samp{""}. + +@end deftypevr + +@deftypevr {@code{libvirt-configuration} parameter} boolean tls-no-sanity-cert +Disable verification of our own server certificates. + +When libvirtd starts it performs some sanity checks against its own +certificates. + +El valor predeterminado es @samp{#f} + +@end deftypevr + +@deftypevr {@code{libvirt-configuration} parameter} boolean tls-no-verify-cert +Disable verification of client certificates. + +Client certificate verification is the primary authentication mechanism. +Any client which does not present a certificate signed by the CA will be +rejected. + +El valor predeterminado es @samp{#f} + +@end deftypevr + +@deftypevr {@code{libvirt-configuration} parameter} optional-list tls-allowed-dn-list +Whitelist of allowed x509 Distinguished Name. + +Defaults to @samp{()}. + +@end deftypevr + +@deftypevr {@code{libvirt-configuration} parameter} optional-list sasl-allowed-usernames +Whitelist of allowed SASL usernames. The format for username depends on the +SASL authentication mechanism. + +Defaults to @samp{()}. + +@end deftypevr + +@deftypevr {@code{libvirt-configuration} parameter} string tls-priority +Override the compile time default TLS priority string. The default is +usually "NORMAL" unless overridden at build time. Only set this is it is +desired for libvirt to deviate from the global default settings. + +Defaults to @samp{"NORMAL"}. + +@end deftypevr + +@deftypevr {@code{libvirt-configuration} parameter} integer max-clients +Maximum number of concurrent client connections to allow over all sockets +combined. + +Defaults to @samp{5000}. + +@end deftypevr + +@deftypevr {@code{libvirt-configuration} parameter} integer max-queued-clients +Maximum length of queue of connections waiting to be accepted by the +daemon. Note, that some protocols supporting retransmission may obey this +so that a later reattempt at connection succeeds. + +Defaults to @samp{1000}. + +@end deftypevr + +@deftypevr {@code{libvirt-configuration} parameter} integer max-anonymous-clients +Maximum length of queue of accepted but not yet authenticated clients. Set +this to zero to turn this feature off + +Defaults to @samp{20}. + +@end deftypevr + +@deftypevr {@code{libvirt-configuration} parameter} integer min-workers +Number of workers to start up initially. + +Defaults to @samp{5}. + +@end deftypevr + +@deftypevr {@code{libvirt-configuration} parameter} integer max-workers +Maximum number of worker threads. + +If the number of active clients exceeds @code{min-workers}, then more +threads are spawned, up to max_workers limit. Typically you'd want +max_workers to equal maximum number of clients allowed. + +Defaults to @samp{20}. + +@end deftypevr + +@deftypevr {@code{libvirt-configuration} parameter} integer prio-workers +Number of priority workers. If all workers from above pool are stuck, some +calls marked as high priority (notably domainDestroy) can be executed in +this pool. + +Defaults to @samp{5}. + +@end deftypevr + +@deftypevr {@code{libvirt-configuration} parameter} integer max-requests +Total global limit on concurrent RPC calls. + +Defaults to @samp{20}. + +@end deftypevr + +@deftypevr {@code{libvirt-configuration} parameter} integer max-client-requests +Limit on concurrent requests from a single client connection. To avoid one +client monopolizing the server this should be a small fraction of the global +max_requests and max_workers parameter. + +Defaults to @samp{5}. + +@end deftypevr + +@deftypevr {@code{libvirt-configuration} parameter} integer admin-min-workers +Same as @code{min-workers} but for the admin interface. + +Defaults to @samp{1}. + +@end deftypevr + +@deftypevr {@code{libvirt-configuration} parameter} integer admin-max-workers +Same as @code{max-workers} but for the admin interface. + +Defaults to @samp{5}. + +@end deftypevr + +@deftypevr {@code{libvirt-configuration} parameter} integer admin-max-clients +Same as @code{max-clients} but for the admin interface. + +Defaults to @samp{5}. + +@end deftypevr + +@deftypevr {@code{libvirt-configuration} parameter} integer admin-max-queued-clients +Same as @code{max-queued-clients} but for the admin interface. + +Defaults to @samp{5}. + +@end deftypevr + +@deftypevr {@code{libvirt-configuration} parameter} integer admin-max-client-requests +Same as @code{max-client-requests} but for the admin interface. + +Defaults to @samp{5}. + +@end deftypevr + +@deftypevr {@code{libvirt-configuration} parameter} integer log-level +Logging level. 4 errors, 3 warnings, 2 information, 1 debug. + +Defaults to @samp{3}. + +@end deftypevr + +@deftypevr {@code{libvirt-configuration} parameter} string log-filters +Filtros de log. + +A filter allows to select a different logging level for a given category of +logs The format for a filter is one of: + +@itemize @bullet +@item +x:nombre + +@item +x:+nombre + +@end itemize + +where @code{name} is a string which is matched against the category given in +the @code{VIR_LOG_INIT()} at the top of each libvirt source file, e.g., +"remote", "qemu", or "util.json" (the name in the filter can be a substring +of the full category name, in order to match multiple similar categories), +the optional "+" prefix tells libvirt to log stack trace for each message +matching name, and @code{x} is the minimal level where matching messages +should be logged: + +@itemize @bullet +@item +1: DEBUG + +@item +2: INFO + +@item +3: WARNING + +@item +4: ERROR + +@end itemize + +Multiple filters can be defined in a single filters statement, they just +need to be separated by spaces. + +Defaults to @samp{"3:remote 4:event"}. + +@end deftypevr + +@deftypevr {@code{libvirt-configuration} parameter} string log-outputs +Logging outputs. + +An output is one of the places to save logging information The format for an +output can be: + +@table @code +@item x:stderr +output goes to stderr + +@item x:syslog:name +use syslog for the output and use the given name as the ident + +@item x:file:file_path +output to a file, with the given filepath + +@item x:journald +output to journald logging system + +@end table + +In all case the x prefix is the minimal level, acting as a filter + +@itemize @bullet +@item +1: DEBUG + +@item +2: INFO + +@item +3: WARNING + +@item +4: ERROR + +@end itemize + +Multiple outputs can be defined, they just need to be separated by spaces. + +Defaults to @samp{"3:stderr"}. + +@end deftypevr + +@deftypevr {@code{libvirt-configuration} parameter} integer audit-level +Allows usage of the auditing subsystem to be altered + +@itemize @bullet +@item +0: disable all auditing + +@item +1: enable auditing, only if enabled on host + +@item +2: enable auditing, and exit if disabled on host. + +@end itemize + +Defaults to @samp{1}. + +@end deftypevr + +@deftypevr {@code{libvirt-configuration} parameter} boolean audit-logging +Send audit messages via libvirt logging infrastructure. + +El valor predeterminado es @samp{#f} + +@end deftypevr + +@deftypevr {@code{libvirt-configuration} parameter} optional-string host-uuid +Host UUID. UUID must not have all digits be the same. + +El valor predeterminado es @samp{""}. + +@end deftypevr + +@deftypevr {@code{libvirt-configuration} parameter} string host-uuid-source +Source to read host UUID. + +@itemize @bullet +@item +@code{smbios}: fetch the UUID from @code{dmidecode -s system-uuid} + +@item +@code{machine-id}: fetch the UUID from @code{/etc/machine-id} + +@end itemize + +If @code{dmidecode} does not provide a valid UUID a temporary UUID will be +generated. + +Defaults to @samp{"smbios"}. + +@end deftypevr + +@deftypevr {@code{libvirt-configuration} parameter} integer keepalive-interval +A keepalive message is sent to a client after @code{keepalive_interval} +seconds of inactivity to check if the client is still responding. If set to +-1, libvirtd will never send keepalive requests; however clients can still +send them and the daemon will send responses. + +Defaults to @samp{5}. + +@end deftypevr + +@deftypevr {@code{libvirt-configuration} parameter} integer keepalive-count +Maximum number of keepalive messages that are allowed to be sent to the +client without getting any response before the connection is considered +broken. + +In other words, the connection is automatically closed approximately after +@code{keepalive_interval * (keepalive_count + 1)} seconds since the last +message received from the client. When @code{keepalive-count} is set to 0, +connections will be automatically closed after @code{keepalive-interval} +seconds of inactivity without sending any keepalive messages. + +Defaults to @samp{5}. + +@end deftypevr + +@deftypevr {@code{libvirt-configuration} parameter} integer admin-keepalive-interval +Same as above but for admin interface. + +Defaults to @samp{5}. + +@end deftypevr + +@deftypevr {@code{libvirt-configuration} parameter} integer admin-keepalive-count +Same as above but for admin interface. + +Defaults to @samp{5}. + +@end deftypevr + +@deftypevr {@code{libvirt-configuration} parameter} integer ovs-timeout +Timeout for Open vSwitch calls. + +The @code{ovs-vsctl} utility is used for the configuration and its timeout +option is set by default to 5 seconds to avoid potential infinite waits +blocking libvirt. + +Defaults to @samp{5}. + +@end deftypevr + +@c %end of autogenerated docs + +@subsubheading Daemon Virtlog +The virtlogd service is a server side daemon component of libvirt that is +used to manage logs from virtual machine consoles. + +This daemon is not used directly by libvirt client applications, rather it +is called on their behalf by @code{libvirtd}. By maintaining the logs in a +standalone daemon, the main @code{libvirtd} daemon can be restarted without +risk of losing logs. The @code{virtlogd} daemon has the ability to re-exec() +itself upon receiving @code{SIGUSR1}, to allow live upgrades without +downtime. + +@deffn {Variable Scheme} virtlog-service-type +This is the type of the virtlog daemon. Its value must be a +@code{virtlog-configuration}. + +@example +(service virtlog-service-type + (virtlog-configuration + (max-clients 1000))) +@end example +@end deffn + +@deftypevr {@code{virtlog-configuration} parameter} integer log-level +Logging level. 4 errors, 3 warnings, 2 information, 1 debug. + +Defaults to @samp{3}. + +@end deftypevr + +@deftypevr {@code{virtlog-configuration} parameter} string log-filters +Filtros de log. + +A filter allows to select a different logging level for a given category of +logs The format for a filter is one of: + +@itemize @bullet +@item +x:nombre + +@item +x:+nombre + +@end itemize + +where @code{name} is a string which is matched against the category given in +the @code{VIR_LOG_INIT()} at the top of each libvirt source file, e.g., +"remote", "qemu", or "util.json" (the name in the filter can be a substring +of the full category name, in order to match multiple similar categories), +the optional "+" prefix tells libvirt to log stack trace for each message +matching name, and @code{x} is the minimal level where matching messages +should be logged: + +@itemize @bullet +@item +1: DEBUG + +@item +2: INFO + +@item +3: WARNING + +@item +4: ERROR + +@end itemize + +Multiple filters can be defined in a single filters statement, they just +need to be separated by spaces. + +Defaults to @samp{"3:remote 4:event"}. + +@end deftypevr + +@deftypevr {@code{virtlog-configuration} parameter} string log-outputs +Logging outputs. + +An output is one of the places to save logging information The format for an +output can be: + +@table @code +@item x:stderr +output goes to stderr + +@item x:syslog:name +use syslog for the output and use the given name as the ident + +@item x:file:file_path +output to a file, with the given filepath + +@item x:journald +output to journald logging system + +@end table + +In all case the x prefix is the minimal level, acting as a filter + +@itemize @bullet +@item +1: DEBUG + +@item +2: INFO + +@item +3: WARNING + +@item +4: ERROR + +@end itemize + +Multiple outputs can be defined, they just need to be separated by spaces. + +Defaults to @samp{"3:stderr"}. + +@end deftypevr + +@deftypevr {@code{virtlog-configuration} parameter} integer max-clients +Maximum number of concurrent client connections to allow over all sockets +combined. + +Defaults to @samp{1024}. + +@end deftypevr + +@deftypevr {@code{virtlog-configuration} parameter} integer max-size +Maximum file size before rolling over. + +Defaults to @samp{2MB} + +@end deftypevr + +@deftypevr {@code{virtlog-configuration} parameter} integer max-backups +Maximum number of backup files to keep. + +Defaults to @samp{3} + +@end deftypevr + +@subsubheading Transparent Emulation with QEMU + +@cindex emulación +@cindex @code{binfmt_misc} +@code{qemu-binfmt-service-type} provides support for transparent emulation +of program binaries built for different architectures---e.g., it allows you +to transparently execute an ARMv7 program on an x86_64 machine. It achieves +this by combining the @uref{https://www.qemu.org, QEMU} emulator and the +@code{binfmt_misc} feature of the kernel Linux. + +@defvr {Variable Scheme} qemu-binfmt-service-type +This is the type of the QEMU/binfmt service for transparent emulation. Its +value must be a @code{qemu-binfmt-configuration} object, which specifies the +QEMU package to use as well as the architecture we want to emulated: + +@example +(service qemu-binfmt-service-type + (qemu-binfmt-configuration + (platforms (lookup-qemu-platforms "arm" "aarch64" "mips64el")))) +@end example + +In this example, we enable transparent emulation for the ARM and aarch64 +platforms. Running @code{herd stop qemu-binfmt} turns it off, and running +@code{herd start qemu-binfmt} turns it back on (@pxref{Invoking herd, the +@command{herd} command,, shepherd, The GNU Shepherd Manual}). +@end defvr + +@deftp {Tipo de datos} qemu-binfmt-configuration +This is the configuration for the @code{qemu-binfmt} service. + +@table @asis +@item @code{platforms} (predeterminadas: @code{'()}) +The list of emulated QEMU platforms. Each item must be a @dfn{platform +object} as returned by @code{lookup-qemu-platforms} (see below). + +@item @code{guix-support?} (predeterminado: @code{#f}) +When it is true, QEMU and all its dependencies are added to the build +environment of @command{guix-daemon} (@pxref{Invocación de guix-daemon, +@code{--chroot-directory} option}). This allows the @code{binfmt_misc} +handlers to be used within the build environment, which in turn means that +you can transparently build programs for another architecture. + +For example, let's suppose you're on an x86_64 machine and you have this +service: + +@example +(service qemu-binfmt-service-type + (qemu-binfmt-configuration + (platforms (lookup-qemu-platforms "arm")) + (guix-support? #t))) +@end example + +You can run: + +@example +guix build -s armhf-linux inkscape +@end example + +@noindent +and it will build Inkscape for ARMv7 @emph{as if it were a native build}, +transparently using QEMU to emulate the ARMv7 CPU. Pretty handy if you'd +like to test a package build for an architecture you don't have access to! + +@item @code{qemu} (predeterminado: @code{qemu}) +El paquete QEMU usado. +@end table +@end deftp + +@deffn {Procedimiento Scheme} lookup-qemu-platforms @var{plataformas}@dots{} +Return the list of QEMU platform objects corresponding to +@var{platforms}@dots{}. @var{platforms} must be a list of strings +corresponding to platform names, such as @code{"arm"}, @code{"sparc"}, +@code{"mips64el"}, and so on. +@end deffn + +@deffn {Procedimiento Scheme} qemu-platform? @var{obj} +Devuelve verdadero si @var{obj} es un objeto plataforma. +@end deffn + +@deffn {Procedimiento Scheme} qemu-platform-name @var{plataforma} +Devuelve el nombre de @var{plataforma}---una cadena como @code{"arm"}. +@end deffn + +@node Servicios de control de versiones +@subsection Servicios de control de versiones + +The @code{(gnu services version-control)} module provides a service to allow +remote access to local Git repositories. There are three options: the +@code{git-daemon-service}, which provides access to repositories via the +@code{git://} unsecured TCP-based protocol, extending the @code{nginx} web +server to proxy some requests to @code{git-http-backend}, or providing a web +interface with @code{cgit-service-type}. + +@deffn {Procedimiento Scheme} git-daemon-service [#:config (git-daemon-configuration)] + +Devuelve un servicio que ejecuta @command{git daemon}, un servidor TCP +simple para exponer repositorios con el protocolo Git para acceso anónimo. + +The optional @var{config} argument should be a +@code{<git-daemon-configuration>} object, by default it allows read-only +access to exported@footnote{By creating the magic file +"git-daemon-export-ok" in the repository directory.} repositories under +@file{/srv/git}. + +@end deffn + +@deftp {Tipo de datos} git-daemon-configuration +Tipo de datos que representa la configuración para +@code{git-daemon-service}. + +@table @asis +@item @code{package} (predeterminado: @var{git}) +Package object of the Git distributed version control system. + +@item @code{export-all?} (predeterminado: @var{#f}) +Whether to allow access for all Git repositories, even if they do not have +the @file{git-daemon-export-ok} file. + +@item @code{base-path} (predeterminado: @file{/srv/git}) +Whether to remap all the path requests as relative to the given path. If +you run git daemon with @var{(base-path "/srv/git")} on example.com, then if +you later try to pull @code{git://example.com/hello.git}, git daemon will +interpret the path as @code{/srv/git/hello.git}. + +@item @code{user-path} (predeterminado: @var{#f}) +Whether to allow @code{~user} notation to be used in requests. When +specified with empty string, requests to @code{git://host/~alice/foo} is +taken as a request to access @code{foo} repository in the home directory of +user @code{alice}. If @var{(user-path "path")} is specified, the same +request is taken as a request to access @code{path/foo} repository in the +home directory of user @code{alice}. + +@item @code{listen} (predeterminado: @var{'()}) +Whether to listen on specific IP addresses or hostnames, defaults to all. + +@item @code{port} (predeterminado: @var{#f}) +Whether to listen on an alternative port, which defaults to 9418. + +@item @code{whitelist} (predeterminado: @var{'()}) +If not empty, only allow access to this list of directories. + +@item @code{extra-options} (predeterminadas: @var{'()}) +Extra options will be passed to @code{git daemon}, please run @command{man +git-daemon} for more information. + +@end table +@end deftp + +The @code{git://} protocol lacks authentication. When you pull from a +repository fetched via @code{git://}, you don't know that the data you +receive was modified is really coming from the specified host, and you have +your connection is subject to eavesdropping. It's better to use an +authenticated and encrypted transport, such as @code{https}. Although Git +allows you to serve repositories using unsophisticated file-based web +servers, there is a faster protocol implemented by the +@code{git-http-backend} program. This program is the back-end of a proper +Git web service. It is designed to sit behind a FastCGI proxy. @xref{Servicios Web}, for more on running the necessary @code{fcgiwrap} daemon. + +Guix has a separate configuration data type for serving Git repositories +over HTTP. + +@deftp {Tipo de datos} git-http-configuration +Data type representing the configuration for @code{git-http-service}. + +@table @asis +@item @code{package} (predeterminado: @var{git}) +Package object of the Git distributed version control system. + +@item @code{git-root} (predeterminada: @file{/srv/git}) +Directory containing the Git repositories to expose to the world. + +@item @code{export-all?} (predeterminado: @var{#f}) +Whether to expose access for all Git repositories in @var{git-root}, even if +they do not have the @file{git-daemon-export-ok} file. + +@item @code{uri-path} (predeterminada: @file{/git/}) +Path prefix for Git access. With the default @code{/git/} prefix, this will +map @code{http://@var{server}/git/@var{repo}.git} to +@code{/srv/git/@var{repo}.git}. Requests whose URI paths do not begin with +this prefix are not passed on to this Git instance. + +@item @code{fcgiwrap-socket} (predeterminado: @code{127.0.0.1:9000}) +The socket on which the @code{fcgiwrap} daemon is listening. @xref{Servicios Web}. +@end table +@end deftp + +There is no @code{git-http-service-type}, currently; instead you can create +an @code{nginx-location-configuration} from a @code{git-http-configuration} +and then add that location to a web server. + +@deffn {Procedimiento Scheme} git-http-nginx-location-configuration @ + [config=(git-http-configuration)] Compute an +@code{nginx-location-configuration} that corresponds to the given Git http +configuration. An example nginx service definition to serve the default +@file{/srv/git} over HTTPS might be: + +@example +(service nginx-service-type + (nginx-configuration + (server-blocks + (list + (nginx-server-configuration + (listen '("443 ssl")) + (server-name "git.my-host.org") + (ssl-certificate + "/etc/letsencrypt/live/git.my-host.org/fullchain.pem") + (ssl-certificate-key + "/etc/letsencrypt/live/git.my-host.org/privkey.pem") + (locations + (list + (git-http-nginx-location-configuration + (git-http-configuration (uri-path "/")))))))))) +@end example + +This example assumes that you are using Let's Encrypt to get your TLS +certificate. @xref{Servicios de certificados}. The default @code{certbot} +service will redirect all HTTP traffic on @code{git.my-host.org} to HTTPS. +You will also need to add an @code{fcgiwrap} proxy to your system services. +@xref{Servicios Web}. +@end deffn + +@subsubheading Servicio Cgit + +@cindex servicio Cgit +@cindex Git, web interface +@uref{https://git.zx2c4.com/cgit/, Cgit} is a web frontend for Git +repositories written in C. + +The following example will configure the service with default values. By +default, Cgit can be accessed on port 80 (@code{http://localhost:80}). + +@example +(service cgit-service-type) +@end example + +The @code{file-object} type designates either a file-like object +(@pxref{Expresiones-G, file-like objects}) or a string. + +@c %start of fragment + +Available @code{cgit-configuration} fields are: + +@deftypevr {@code{cgit-configuration} parameter} package package +El paquete CGIT. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} nginx-server-configuration-list nginx +Configuración de NGINX. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} file-object about-filter +Specifies a command which will be invoked to format the content of about +pages (both top-level and for each repository). + +El valor predeterminado es @samp{""}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} string agefile +Specifies a path, relative to each repository path, which can be used to +specify the date and time of the youngest commit in the repository. + +El valor predeterminado es @samp{""}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} file-object auth-filter +Specifies a command that will be invoked for authenticating repository +access. + +El valor predeterminado es @samp{""}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} string branch-sort +Flag which, when set to @samp{age}, enables date ordering in the branch ref +list, and when set @samp{name} enables ordering by branch name. + +Defaults to @samp{"name"}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} string cache-root +Path used to store the cgit cache entries. + +Defaults to @samp{"/var/cache/cgit"}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} integer cache-static-ttl +Number which specifies the time-to-live, in minutes, for the cached version +of repository pages accessed with a fixed SHA1. + +Defaults to @samp{-1}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} integer cache-dynamic-ttl +Number which specifies the time-to-live, in minutes, for the cached version +of repository pages accessed without a fixed SHA1. + +Defaults to @samp{5}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} integer cache-repo-ttl +Number which specifies the time-to-live, in minutes, for the cached version +of the repository summary page. + +Defaults to @samp{5}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} integer cache-root-ttl +Number which specifies the time-to-live, in minutes, for the cached version +of the repository index page. + +Defaults to @samp{5}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} integer cache-scanrc-ttl +Number which specifies the time-to-live, in minutes, for the result of +scanning a path for Git repositories. + +Defaults to @samp{15}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} integer cache-about-ttl +Number which specifies the time-to-live, in minutes, for the cached version +of the repository about page. + +Defaults to @samp{15}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} integer cache-snapshot-ttl +Number which specifies the time-to-live, in minutes, for the cached version +of snapshots. + +Defaults to @samp{5}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} integer cache-size +The maximum number of entries in the cgit cache. When set to @samp{0}, +caching is disabled. + +El valor predeterminado es @samp{0}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} boolean case-sensitive-sort? +Sort items in the repo list case sensitively. + +Defaults to @samp{#t}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} list clone-prefix +List of common prefixes which, when combined with a repository URL, +generates valid clone URLs for the repository. + +Defaults to @samp{()}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} list clone-url +List of @code{clone-url} templates. + +Defaults to @samp{()}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} file-object commit-filter +Command which will be invoked to format commit messages. + +El valor predeterminado es @samp{""}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} string commit-sort +Flag which, when set to @samp{date}, enables strict date ordering in the +commit log, and when set to @samp{topo} enables strict topological ordering. + +Defaults to @samp{"git log"}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} file-object css +URL which specifies the css document to include in all cgit pages. + +Defaults to @samp{"/share/cgit/cgit.css"}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} file-object email-filter +Specifies a command which will be invoked to format names and email address +of committers, authors, and taggers, as represented in various places +throughout the cgit interface. + +El valor predeterminado es @samp{""}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} boolean embedded? +Flag which, when set to @samp{#t}, will make cgit generate a HTML fragment +suitable for embedding in other HTML pages. + +El valor predeterminado es @samp{#f} + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} boolean enable-commit-graph? +Flag which, when set to @samp{#t}, will make cgit print an ASCII-art commit +history graph to the left of the commit messages in the repository log page. + +El valor predeterminado es @samp{#f} + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} boolean enable-filter-overrides? +Flag which, when set to @samp{#t}, allows all filter settings to be +overridden in repository-specific cgitrc files. + +El valor predeterminado es @samp{#f} + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} boolean enable-follow-links? +Flag which, when set to @samp{#t}, allows users to follow a file in the log +view. + +El valor predeterminado es @samp{#f} + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} boolean enable-http-clone? +If set to @samp{#t}, cgit will act as an dumb HTTP endpoint for Git clones. + +Defaults to @samp{#t}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} boolean enable-index-links? +Flag which, when set to @samp{#t}, will make cgit generate extra links +"summary", "commit", "tree" for each repo in the repository index. + +El valor predeterminado es @samp{#f} + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} boolean enable-index-owner? +Flag which, when set to @samp{#t}, will make cgit display the owner of each +repo in the repository index. + +Defaults to @samp{#t}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} boolean enable-log-filecount? +Flag which, when set to @samp{#t}, will make cgit print the number of +modified files for each commit on the repository log page. + +El valor predeterminado es @samp{#f} + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} boolean enable-log-linecount? +Flag which, when set to @samp{#t}, will make cgit print the number of added +and removed lines for each commit on the repository log page. + +El valor predeterminado es @samp{#f} + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} boolean enable-remote-branches? +Flag which, when set to @code{#t}, will make cgit display remote branches in +the summary and refs views. + +El valor predeterminado es @samp{#f} + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} boolean enable-subject-links? +Flag which, when set to @code{1}, will make cgit use the subject of the +parent commit as link text when generating links to parent commits in commit +view. + +El valor predeterminado es @samp{#f} + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} boolean enable-html-serving? +Flag which, when set to @samp{#t}, will make cgit use the subject of the +parent commit as link text when generating links to parent commits in commit +view. + +El valor predeterminado es @samp{#f} + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} boolean enable-tree-linenumbers? +Flag which, when set to @samp{#t}, will make cgit generate linenumber links +for plaintext blobs printed in the tree view. + +Defaults to @samp{#t}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} boolean enable-git-config? +Flag which, when set to @samp{#f}, will allow cgit to use Git config to set +any repo specific settings. + +El valor predeterminado es @samp{#f} + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} file-object favicon +URL used as link to a shortcut icon for cgit. + +Defaults to @samp{"/favicon.ico"}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} string footer +The content of the file specified with this option will be included verbatim +at the bottom of all pages (i.e.@: it replaces the standard "generated +by..."@: message). + +El valor predeterminado es @samp{""}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} string head-include +The content of the file specified with this option will be included verbatim +in the HTML HEAD section on all pages. + +El valor predeterminado es @samp{""}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} string header +The content of the file specified with this option will be included verbatim +at the top of all pages. + +El valor predeterminado es @samp{""}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} file-object include +Name of a configfile to include before the rest of the current config- file +is parsed. + +El valor predeterminado es @samp{""}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} string index-header +The content of the file specified with this option will be included verbatim +above the repository index. + +El valor predeterminado es @samp{""}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} string index-info +The content of the file specified with this option will be included verbatim +below the heading on the repository index page. + +El valor predeterminado es @samp{""}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} boolean local-time? +Flag which, if set to @samp{#t}, makes cgit print commit and tag times in +the servers timezone. + +El valor predeterminado es @samp{#f} + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} file-object logo +URL which specifies the source of an image which will be used as a logo on +all cgit pages. + +Defaults to @samp{"/share/cgit/cgit.png"}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} string logo-link +URL loaded when clicking on the cgit logo image. + +El valor predeterminado es @samp{""}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} file-object owner-filter +Command which will be invoked to format the Owner column of the main page. + +El valor predeterminado es @samp{""}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} integer max-atom-items +Number of items to display in atom feeds view. + +Defaults to @samp{10}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} integer max-commit-count +Number of entries to list per page in "log" view. + +Defaults to @samp{50}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} integer max-message-length +Number of commit message characters to display in "log" view. + +Defaults to @samp{80}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} integer max-repo-count +Specifies the number of entries to list per page on the repository index +page. + +Defaults to @samp{50}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} integer max-repodesc-length +Specifies the maximum number of repo description characters to display on +the repository index page. + +Defaults to @samp{80}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} integer max-blob-size +Specifies the maximum size of a blob to display HTML for in KBytes. + +El valor predeterminado es @samp{0}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} string max-stats +Maximum statistics period. Valid values are @samp{week},@samp{month}, +@samp{quarter} and @samp{year}. + +El valor predeterminado es @samp{""}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} mimetype-alist mimetype +Mimetype for the specified filename extension. + +Defaults to @samp{((gif "image/gif") (html "text/html") (jpg "image/jpeg") +(jpeg "image/jpeg") (pdf "application/pdf") (png "image/png") (svg +"image/svg+xml"))}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} file-object mimetype-file +Specifies the file to use for automatic mimetype lookup. + +El valor predeterminado es @samp{""}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} string module-link +Text which will be used as the formatstring for a hyperlink when a submodule +is printed in a directory listing. + +El valor predeterminado es @samp{""}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} boolean nocache? +If set to the value @samp{#t} caching will be disabled. + +El valor predeterminado es @samp{#f} + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} boolean noplainemail? +If set to @samp{#t} showing full author email addresses will be disabled. + +El valor predeterminado es @samp{#f} + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} boolean noheader? +Flag which, when set to @samp{#t}, will make cgit omit the standard header +on all pages. + +El valor predeterminado es @samp{#f} + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} project-list project-list +A list of subdirectories inside of @code{repository-directory}, relative to +it, that should loaded as Git repositories. An empty list means that all +subdirectories will be loaded. + +Defaults to @samp{()}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} file-object readme +Text which will be used as default value for @code{cgit-repo-readme}. + +El valor predeterminado es @samp{""}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} boolean remove-suffix? +If set to @code{#t} and @code{repository-directory} is enabled, if any +repositories are found with a suffix of @code{.git}, this suffix will be +removed for the URL and name. + +El valor predeterminado es @samp{#f} + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} integer renamelimit +Maximum number of files to consider when detecting renames. + +Defaults to @samp{-1}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} string repository-sort +The way in which repositories in each section are sorted. + +El valor predeterminado es @samp{""}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} robots-list robots +Text used as content for the @code{robots} meta-tag. + +Defaults to @samp{("noindex" "nofollow")}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} string root-desc +Text printed below the heading on the repository index page. + +Defaults to @samp{"a fast webinterface for the git dscm"}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} string root-readme +The content of the file specified with this option will be included verbatim +below thef "about" link on the repository index page. + +El valor predeterminado es @samp{""}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} string root-title +Text printed as heading on the repository index page. + +El valor predeterminado es @samp{""}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} boolean scan-hidden-path +If set to @samp{#t} and repository-directory is enabled, +repository-directory will recurse into directories whose name starts with a +period. Otherwise, repository-directory will stay away from such +directories, considered as "hidden". Note that this does not apply to the +".git" directory in non-bare repos. + +El valor predeterminado es @samp{#f} + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} list snapshots +Text which specifies the default set of snapshot formats that cgit generates +links for. + +Defaults to @samp{()}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} repository-directory repository-directory +Name of the directory to scan for repositories (represents +@code{scan-path}). + +Defaults to @samp{"/srv/git"}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} string section +The name of the current repository section - all repositories defined after +this option will inherit the current section name. + +El valor predeterminado es @samp{""}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} string section-sort +Flag which, when set to @samp{1}, will sort the sections on the repository +listing by name. + +El valor predeterminado es @samp{""}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} integer section-from-path +A number which, if defined prior to repository-directory, specifies how many +path elements from each repo path to use as a default section name. + +El valor predeterminado es @samp{0}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} boolean side-by-side-diffs? +If set to @samp{#t} shows side-by-side diffs instead of unidiffs per +default. + +El valor predeterminado es @samp{#f} + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} file-object source-filter +Specifies a command which will be invoked to format plaintext blobs in the +tree view. + +El valor predeterminado es @samp{""}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} integer summary-branches +Specifies the number of branches to display in the repository "summary" +view. + +Defaults to @samp{10}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} integer summary-log +Specifies the number of log entries to display in the repository "summary" +view. + +Defaults to @samp{10}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} integer summary-tags +Specifies the number of tags to display in the repository "summary" view. + +Defaults to @samp{10}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} string strict-export +Filename which, if specified, needs to be present within the repository for +cgit to allow access to that repository. + +El valor predeterminado es @samp{""}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} string virtual-root +URL which, if specified, will be used as root for all cgit links. + +Defaults to @samp{"/"}. + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} repository-cgit-configuration-list repositories +A list of @dfn{cgit-repo} records to use with config. + +Defaults to @samp{()}. + +Available @code{repository-cgit-configuration} fields are: + +@deftypevr {@code{repository-cgit-configuration} parameter} repo-list snapshots +A mask of snapshot formats for this repo that cgit generates links for, +restricted by the global @code{snapshots} setting. + +Defaults to @samp{()}. + +@end deftypevr + +@deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object source-filter +Override the default @code{source-filter}. + +El valor predeterminado es @samp{""}. + +@end deftypevr + +@deftypevr {@code{repository-cgit-configuration} parameter} repo-string url +The relative URL used to access the repository. + +El valor predeterminado es @samp{""}. + +@end deftypevr + +@deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object about-filter +Override the default @code{about-filter}. + +El valor predeterminado es @samp{""}. + +@end deftypevr + +@deftypevr {@code{repository-cgit-configuration} parameter} repo-string branch-sort +Flag which, when set to @samp{age}, enables date ordering in the branch ref +list, and when set to @samp{name} enables ordering by branch name. + +El valor predeterminado es @samp{""}. + +@end deftypevr + +@deftypevr {@code{repository-cgit-configuration} parameter} repo-list clone-url +A list of URLs which can be used to clone repo. + +Defaults to @samp{()}. + +@end deftypevr + +@deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object commit-filter +Override the default @code{commit-filter}. + +El valor predeterminado es @samp{""}. + +@end deftypevr + +@deftypevr {@code{repository-cgit-configuration} parameter} repo-string commit-sort +Flag which, when set to @samp{date}, enables strict date ordering in the +commit log, and when set to @samp{topo} enables strict topological ordering. + +El valor predeterminado es @samp{""}. + +@end deftypevr + +@deftypevr {@code{repository-cgit-configuration} parameter} repo-string defbranch +The name of the default branch for this repository. If no such branch +exists in the repository, the first branch name (when sorted) is used as +default instead. By default branch pointed to by HEAD, or "master" if there +is no suitable HEAD. + +El valor predeterminado es @samp{""}. + +@end deftypevr + +@deftypevr {@code{repository-cgit-configuration} parameter} repo-string desc +The value to show as repository description. + +El valor predeterminado es @samp{""}. + +@end deftypevr + +@deftypevr {@code{repository-cgit-configuration} parameter} repo-string homepage +The value to show as repository homepage. + +El valor predeterminado es @samp{""}. + +@end deftypevr + +@deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object email-filter +Override the default @code{email-filter}. + +El valor predeterminado es @samp{""}. + +@end deftypevr + +@deftypevr {@code{repository-cgit-configuration} parameter} maybe-repo-boolean enable-commit-graph? +A flag which can be used to disable the global setting +@code{enable-commit-graph?}. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{repository-cgit-configuration} parameter} maybe-repo-boolean enable-log-filecount? +A flag which can be used to disable the global setting +@code{enable-log-filecount?}. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{repository-cgit-configuration} parameter} maybe-repo-boolean enable-log-linecount? +A flag which can be used to disable the global setting +@code{enable-log-linecount?}. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{repository-cgit-configuration} parameter} maybe-repo-boolean enable-remote-branches? +Flag which, when set to @code{#t}, will make cgit display remote branches in +the summary and refs views. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{repository-cgit-configuration} parameter} maybe-repo-boolean enable-subject-links? +A flag which can be used to override the global setting +@code{enable-subject-links?}. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{repository-cgit-configuration} parameter} maybe-repo-boolean enable-html-serving? +A flag which can be used to override the global setting +@code{enable-html-serving?}. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{repository-cgit-configuration} parameter} repo-boolean hide? +Flag which, when set to @code{#t}, hides the repository from the repository +index. + +El valor predeterminado es @samp{#f} + +@end deftypevr + +@deftypevr {@code{repository-cgit-configuration} parameter} repo-boolean ignore? +Flag which, when set to @samp{#t}, ignores the repository. + +El valor predeterminado es @samp{#f} + +@end deftypevr + +@deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object logo +URL which specifies the source of an image which will be used as a logo on +this repo’s pages. + +El valor predeterminado es @samp{""}. + +@end deftypevr + +@deftypevr {@code{repository-cgit-configuration} parameter} repo-string logo-link +URL loaded when clicking on the cgit logo image. + +El valor predeterminado es @samp{""}. + +@end deftypevr + +@deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object owner-filter +Override the default @code{owner-filter}. + +El valor predeterminado es @samp{""}. + +@end deftypevr + +@deftypevr {@code{repository-cgit-configuration} parameter} repo-string module-link +Text which will be used as the formatstring for a hyperlink when a submodule +is printed in a directory listing. The arguments for the formatstring are +the path and SHA1 of the submodule commit. + +El valor predeterminado es @samp{""}. + +@end deftypevr + +@deftypevr {@code{repository-cgit-configuration} parameter} module-link-path module-link-path +Text which will be used as the formatstring for a hyperlink when a submodule +with the specified subdirectory path is printed in a directory listing. + +Defaults to @samp{()}. + +@end deftypevr + +@deftypevr {@code{repository-cgit-configuration} parameter} repo-string max-stats +Override the default maximum statistics period. + +El valor predeterminado es @samp{""}. + +@end deftypevr + +@deftypevr {@code{repository-cgit-configuration} parameter} repo-string name +El valor a mostrar como nombre del repositorio. + +El valor predeterminado es @samp{""}. + +@end deftypevr + +@deftypevr {@code{repository-cgit-configuration} parameter} repo-string owner +A value used to identify the owner of the repository. + +El valor predeterminado es @samp{""}. + +@end deftypevr + +@deftypevr {@code{repository-cgit-configuration} parameter} repo-string path +La ruta absoluta al directorio del repositorio. + +El valor predeterminado es @samp{""}. + +@end deftypevr + +@deftypevr {@code{repository-cgit-configuration} parameter} repo-string readme +A path (relative to repo) which specifies a file to include verbatim as the +"About" page for this repo. + +El valor predeterminado es @samp{""}. + +@end deftypevr + +@deftypevr {@code{repository-cgit-configuration} parameter} repo-string section +The name of the current repository section - all repositories defined after +this option will inherit the current section name. + +El valor predeterminado es @samp{""}. + +@end deftypevr + +@deftypevr {@code{repository-cgit-configuration} parameter} repo-list extra-options +Extra options will be appended to cgitrc file. + +Defaults to @samp{()}. + +@end deftypevr + +@end deftypevr + +@deftypevr {@code{cgit-configuration} parameter} list extra-options +Extra options will be appended to cgitrc file. + +Defaults to @samp{()}. + +@end deftypevr + + +@c %end of fragment + +However, it could be that you just want to get a @code{cgitrc} up and +running. In that case, you can pass an @code{opaque-cgit-configuration} as +a record to @code{cgit-service-type}. As its name indicates, an opaque +configuration does not have easy reflective capabilities. + +Available @code{opaque-cgit-configuration} fields are: + +@deftypevr {@code{opaque-cgit-configuration} parameter} package cgit +El paquete cgit. +@end deftypevr + +@deftypevr {@code{opaque-cgit-configuration} parameter} string string +The contents of the @code{cgitrc}, as a string. +@end deftypevr + +For example, if your @code{cgitrc} is just the empty string, you could +instantiate a cgit service like this: + +@example +(service cgit-service-type + (opaque-cgit-configuration + (cgitrc ""))) +@end example + +@subsubheading Servicio Gitolite + +@cindex servicio Gitolite +@cindex Git, alojamiento +@uref{http://gitolite.com/gitolite/, Gitolite} is a tool for hosting Git +repositories on a central server. + +Gitolite can handle multiple repositories and users, and supports flexible +configuration of the permissions for the users on the repositories. + +The following example will configure Gitolite using the default @code{git} +user, and the provided SSH public key. + +@example +(service gitolite-service-type + (gitolite-configuration + (admin-pubkey (plain-file + "sunombre.pub" + "ssh-rsa AAAA... guix@@example.com")))) +@end example + +Gitolite is configured through a special admin repository which you can +clone, for example, if you setup Gitolite on @code{example.com}, you would +run the following command to clone the admin repository. + +@example +git clone git@@example.com:gitolite-admin +@end example + +When the Gitolite service is activated, the provided @code{admin-pubkey} +will be inserted in to the @file{keydir} directory in the gitolite-admin +repository. If this results in a change in the repository, it will be +committed using the message ``gitolite setup by GNU Guix''. + +@deftp {Tipo de datos} gitolite-configuration +Tipo de datos que representa la configuración de +@code{gitolite-service-type}. + +@table @asis +@item @code{package} (predeterminado: @var{gitolite}) +Paquete Gitolite usado. + +@item @code{user} (predeterminado: @var{git}) +User to use for Gitolite. This will be user that you use when accessing +Gitolite over SSH. + +@item @code{group} (predeterminado: @var{git}) +Grupo usado por Gitolite. + +@item @code{home-directory} (predeterminado: @var{"/var/lib/gitolite"}) +Directory in which to store the Gitolite configuration and repositories. + +@item @code{rc-file} (predeterminado: @var{(gitolite-rc-file)}) +A ``file-like'' object (@pxref{Expresiones-G, file-like objects}), +representing the configuration for Gitolite. + +@item @code{admin-pubkey} (predeterminada: @var{#f}) +A ``file-like'' object (@pxref{Expresiones-G, file-like objects}) used to +setup Gitolite. This will be inserted in to the @file{keydir} directory +within the gitolite-admin repository. + +To specify the SSH key as a string, use the @code{plain-file} function. + +@example +(plain-file "yourname.pub" "ssh-rsa AAAA... guix@@example.com") +@end example + +@end table +@end deftp + +@deftp {Tipo de datos} gitolite-rc-file +Tipo de datos que representa el fichero RC de Gitolite. + +@table @asis +@item @code{umask} (predeterminada: @code{#o0077}) +This controls the permissions Gitolite sets on the repositories and their +contents. + +A value like @code{#o0027} will give read access to the group used by +Gitolite (by default: @code{git}). This is necessary when using Gitolite +with software like cgit or gitweb. + +@item @code{git-config-keys} (predeterminadas: @code{""}) +Gitolite allows you to set git config values using the "config" +keyword. This setting allows control over the config keys to accept. + +@item @code{roles} (predeterminados: @code{'(("READERS" . 1) ("WRITERS" . ))}) +Set the role names allowed to be used by users running the perms command. + +@item @code{enable} (default: @code{'("help" "desc" "info" "perms" "writable" "ssh-authkeys" "git-config" "daemon" "gitweb")}) +This setting controls the commands and features to enable within Gitolite. + +@end table +@end deftp + + +@node Servicios de juegos +@subsection Servicios de juegos + +@subsubheading El servicio de La batalla por Wesnoth +@cindex wesnothd +@uref{https://wesnoth.org, La batalla por Wesnoth} es un juego de estrategia +táctica, de fantasía y basado en turnos, con varias campañas de una +jugadora, y partidas para múltiples jugadoras (tanto en red como +localmente). + +@defvar {Variable Scheme} wesnothd-service-type +Service type for the wesnothd service. Its value must be a +@code{wesnothd-configuration} object. To run wesnothd in the default +configuration, instantiate it as: + +@example +(service wesnothd-service-type) +@end example +@end defvar + +@deftp {Tipo de datos} wesnothd-configuration +Tipo de datos que representa la configuración de @command{wesnothd}. + +@table @asis +@item @code{package} (predeterminado: @code{wesnoth-server}) +El paquete del servidor wesnoth usado. + +@item @code{port} (predeterminado: @code{15000}) +Número de puerto usado por el servidor. +@end table +@end deftp + +@node Servicios misceláneos +@subsection Servicios misceláneos + +@cindex huella dactilar +@subsubheading Servicios de huella dactilar + +The @code{(gnu services authentication)} module provides a DBus service to +read and identify fingerprints via a fingerprint sensor. + +@defvr {Variable Scheme} fprintd-service-type +The service type for @command{fprintd}, which provides the fingerprint +reading capability. + +@example +(service fprintd-service-type) +@end example +@end defvr + +@cindex sysctl +@subsubheading Servicios de control del sistema + +The @code{(gnu services sysctl)} provides a service to configure kernel +parameters at boot. + +@defvr {Variable Scheme} sysctl-service-type +The service type for @command{sysctl}, which modifies kernel parameters +under @file{/proc/sys/}. To enable IPv4 forwarding, it can be instantiated +as: + +@example +(service sysctl-service-type + (sysctl-configuration + (settings '(("net.ipv4.ip_forward" . "1"))))) +@end example +@end defvr + +@deftp {Tipo de datos} sysctl-configuration +Tipo de datos que representa la configuración de @command{sysctl}. + +@table @asis +@item @code{sysctl} (predeterminado: @code{(file-append procps "/sbin/sysctl"}) +El ejecutable @command{sysctl} usado. + +@item @code{settings} (predeterminados: @code{'()}) +An association list specifies kernel parameters and their values. +@end table +@end deftp + +@cindex pcscd +@subsubheading Servicio del daemon de tarjetas inteligentes PC/SC + +The @code{(gnu services security-token)} module provides the following +service to run @command{pcscd}, the PC/SC Smart Card Daemon. +@command{pcscd} is the daemon program for pcsc-lite and the MuscleCard +framework. It is a resource manager that coordinates communications with +smart card readers, smart cards and cryptographic tokens that are connected +to the system. + +@defvr {Variable Scheme} pcscd-service-type +Service type for the @command{pcscd} service. Its value must be a +@code{pcscd-configuration} object. To run pcscd in the default +configuration, instantiate it as: + +@example +(service pcscd-service-type) +@end example +@end defvr + +@deftp {Tipo de datos} pcscd-configuration +The data type representing the configuration of @command{pcscd}. + +@table @asis +@item @code{pcsc-lite} (predeterminado: @code{pcsc-lite}) +The pcsc-lite package that provides pcscd. +@item @code{usb-drivers} (predeterminado: @code{(list ccid)}) +List of packages that provide USB drivers to pcscd. Drivers are expected to +be under @file{pcsc/drivers} in the store directory of the package. +@end table +@end deftp + +@cindex lirc +@subsubheading Servicio Lirc + +El módulo @code{(gnu services lirc)} proporciona el siguiente servicio. + +@deffn {Procedimiento Scheme} lirc-service [#:lirc lirc] @ + [#:device #f] [#:driver #f] [#:config-file #f] @ [#:extra-options '()] +Return a service that runs @url{http://www.lirc.org,LIRC}, a daemon that +decodes infrared signals from remote controls. + +Optionally, @var{device}, @var{driver} and @var{config-file} (configuration +file name) may be specified. See @command{lircd} manual for details. + +Finally, @var{extra-options} is a list of additional command-line options +passed to @command{lircd}. +@end deffn + +@cindex spice +@subsubheading Servicio Spice + +El módulo @code{(gnu services spice)} proporciona el siguiente servicio. + +@deffn {Procedimiento Scheme} spice-vdagent-service [#:spice-vdagent] +Returns a service that runs @url{http://www.spice-space.org,VDAGENT}, a +daemon that enables sharing the clipboard with a vm and setting the guest +display resolution when the graphical console window resizes. +@end deffn + +@cindex inputattach +@subsubheading inputattach Service + +@cindex tablet input, for Xorg +@cindex touchscreen input, for Xorg +The @uref{https://linuxwacom.github.io/, inputattach} service allows you to +use input devices such as Wacom tablets, touchscreens, or joysticks with the +Xorg display server. + +@deffn {Scheme Variable} inputattach-service-type +Type of a service that runs @command{inputattach} on a device and dispatches +events from it. +@end deffn + +@deftp {Data Type} inputattach-configuration +@table @asis +@item @code{device-type} (default: @code{"wacom"}) +The type of device to connect to. Run @command{inputattach --help}, from +the @code{inputattach} package, to see the list of supported device types. + +@item @code{device} (default: @code{"/dev/ttyS0"}) +The device file to connect to the device. + +@item @code{log-file} (default: @code{#f}) +If true, this must be the name of a file to log messages to. +@end table +@end deftp + +@subsection Servicios de diccionario +@cindex diccionario +El módulo @code{(gnu services dict)} proporciona el servicio siguiente: + +@deffn {Procedimiento Scheme} dicod-service [#:config (dicod-configuration)] +Devuelve un servicio que ejecuta el daemon @command{dicod}, una +implementación del servidor DICT (@pxref{Dicod,,, dico, GNU Dico Manual}). + +El parámetro opcional @var{config} especifica la configuración para +@command{dicod}, que debe ser un objeto @code{<dicod-configuration>}, por +defecto proporciona el diccionario colaborativo internacional de Inglés de +GNU. + +You can add @command{open localhost} to your @file{~/.dico} file to make +@code{localhost} the default server for @command{dico} client +(@pxref{Initialization File,,, dico, GNU Dico Manual}). +@end deffn + +@deftp {Tipo de datos} dicod-configuration +Tipo de datos que representa la configuración de dicod. + +@table @asis +@item @code{dico} (predeterminado: @var{dico}) +Package object of the GNU Dico dictionary server. + +@item @code{interfaces} (predeterminada: @var{'("localhost")}) +This is the list of IP addresses and ports and possibly socket file names to +listen to (@pxref{Server Settings, @code{listen} directive,, dico, GNU Dico +Manual}). + +@item @code{handlers} (predeterminados: @var{'()}) +List of @code{<dicod-handler>} objects denoting handlers (module instances). + +@item @code{databases} (predeterminada: @var{(list %dicod-database:gcide)}) +List of @code{<dicod-database>} objects denoting dictionaries to be served. +@end table +@end deftp + +@deftp {Tipo de datos} dicod-handler +Data type representing a dictionary handler (module instance). + +@table @asis +@item @code{name} +Name of the handler (module instance). + +@item @code{module} (predeterminado: @var{#f}) +Name of the dicod module of the handler (instance). If it is @code{#f}, the +module has the same name as the handler. (@pxref{Módulos,,, dico, GNU Dico +Manual}). + +@item @code{options} +List of strings or gexps representing the arguments for the module handler +@end table +@end deftp + +@deftp {Tipo de datos} dicod-database +Tipo de datos que representa una base de datos de diccionario. + +@table @asis +@item @code{name} +Nombre de la base de datos, será usada en las órdenes DICT. + +@item @code{handler} +Name of the dicod handler (module instance) used by this database +(@pxref{Handlers,,, dico, GNU Dico Manual}). + +@item @code{complex?} (predeterminado: @var{#f}) +Whether the database configuration complex. The complex configuration will +need a corresponding @code{<dicod-handler>} object, otherwise not. + +@item @code{options} +List of strings or gexps representing the arguments for the database +(@pxref{Databases,,, dico, GNU Dico Manual}). +@end table +@end deftp + +@defvr {Variable Scheme} %dicod-database:gcide +A @code{<dicod-database>} object serving the GNU Collaborative International +Dictionary of English using the @code{gcide} package. +@end defvr + +The following is an example @code{dicod-service} configuration. + +@example +(dicod-service #:config + (dicod-configuration + (handlers (list (dicod-handler + (name "wordnet") + (module "dictorg") + (options + (list #~(string-append "dbdir=" #$wordnet)))))) + (databases (list (dicod-database + (name "wordnet") + (complex? #t) + (handler "wordnet") + (options '("database=wn"))) + %dicod-database:gcide)))) +@end example + +@cindex Docker +@subsubheading Docker Service + +The @code{(gnu services docker)} module provides the following service. + +@defvr {Scheme Variable} docker-service-type + +This is the type of the service that runs +@url{http://www.docker.com,Docker}, a daemon that can execute application +bundles (sometimes referred to as ``containers'') in isolated environments. + +@end defvr + +@deftp {Data Type} docker-configuration +This is the data type representing the configuration of Docker and +Containerd. + +@table @asis + +@item @code{package} (default: @code{docker}) +The Docker package to use. + +@item @code{containerd} (default: @var{containerd}) +The Containerd package to use. + +@end table +@end deftp + +@node Programas con setuid +@section Programas con setuid + +@cindex programas con setuid +Algunos programas necesitan ejecutarse con privilegios de ``root'', incluso +cuando se ejecutan por usuarias sin privilegios. Un ejemplo notable es el +programa @command{passwd}, que las usuarias ejecutan para cambiar su +contraseña, y que necesita acceso a los ficheros @file{/etc/passwd} y +@file{/etc/shadow}---algo normalmente restringido a root, por razones de +seguridad obvias. Para solventarlo, estos ejecutables tienen @dfn{setuid de +root}, lo que significa que siempre se ejecutan con privilegios de root +(@pxref{How Change Persona,,, libc, The GNU C Library Reference Manual}, +para más información sobre el mecanismo setuid). + +El almacén en sí @emph{no puede} contener programas setuid: sería un +problema de seguridad puesto que cualquier usuaria del sistema puede +escribir derivaciones que pueblen el almacén (@pxref{El almacén}). Por tanto, +se usa un mecanismo diferente: en vez de cambiar el bit de setuid +directamente en los ficheros que se encuentran en el almacén, se permite que +la administradora del sistema @emph{declare} qué programas deberían tener +setuid de root. + +El campo @code{setuid-programs} de una declaración @code{operating-system} +contiene una lista de expresiones-G que denotan nombres de programas que +tendrán setuid de root (@pxref{Uso de la configuración del sistema}). Por +ejemplo, el programa @command{passwd}, que es parte del paquete Shadow, +puede designarse con esta expresión-G (@pxref{Expresiones-G}): + +@example +#~(string-append #$shadow "/bin/passwd") +@end example + +Un conjunto predeterminado de programas con el bit setuid se define en la +variable @code{%setuid-programs} del módulo @code{(gnu system)}. + +@defvr {Variable Scheme} %setuid-programs +Una lista de expresiones-G que denotan programas comunes que se marcan con +setuid de root. + +La lista incluye órdenes como @command{passwd}, @command{ping}, @command{su} +y @command{sudo}. +@end defvr + +Para su implementación, los programas con setuid reales se crean en el +directorio @file{/run/setuid-programs} durante la activación del +sistema. Los ficheros en este directorio hacen referencia a los binarios +``reales'', que estan en el almacén. + +@node Certificados X.509 +@section Certificados X.509 + +@cindex HTTPS, certificados +@cindex certificados X.509 +@cindex TLS +En las conexiones HTTPS a servidores Web (esto es, HTTP sobre el mecanismo +de seguridad de la capa de transporte, TLS) se envía a los programas +clientes un @dfn{certificado X.509} que el cliente puede usar para +@emph{autentificar} al servidor. Para hacerlo, los clientes verifican que el +certificado del servidor está firmado por una de las llamadas +@dfn{autoridades de certificación} (AC, CA en inglés). Pero para verificar +la firma de una AC, los clientes deben haber obtenido previamente el +certificado de dicha AC. + +Los navegadores Web como GNU@tie{}IceCat incluyen su propio conjunto de +certificados de AC, de manera que pueden verificar las firmas +independientemente. + +No obstante, a la mayor parte de otros programas que pueden comunicarse a +través de HTTPS---@command{wget}, @command{git}, @command{w3m}, etc.---se +les debe informar de dónde pueden encontrar los certificados de CA. + +@cindex @code{nss-certs} +In Guix, this is done by adding a package that provides certificates to the +@code{packages} field of the @code{operating-system} declaration +(@pxref{Referencia de ``operating-system''}). Guix includes one such package, +@code{nss-certs}, which is a set of CA certificates provided as part of +Mozilla's Network Security Services. + +Fíjese que @emph{no} es parte de @var{%base-packages}, por lo que debe ser +añadido explícitamente. El directorio @file{/etc/ssl/certs}, donde la mayor +parte de las aplicaciones y bibliotecas buscarán los certificados de manera +predeterminada, enlaza a los certificados instalados de manera global. + +Las usuarias sin privilegios, incluyendo a usuarias de Guix en una +distribución distinta, pueden también instalar su propio paquete de +certificados en su perfil. Es necesario definir cierto número de variables +de entorno de manera que las aplicaciones y bibliotecas sepan dónde +encontrarlos. Por ejemplo, la biblioteca OpenSSL inspecciona las variables +@code{SSL_CERT_DIR} y @code{SSL_CERT_FILE}. Algunas aplicaciones añaden sus +variables de entorno propias; por ejemplo, el sistema de control de +versiones Git inspecciona el empaquetado de certificados al que apunta la +variable de entorno @code{GIT_SSL_CAINFO}. Por tanto, en el caso típico se +debe ejecutar algo parecido a esto: + +@example +$ guix package -i nss-certs +$ export SSL_CERT_DIR="$HOME/.guix-profile/etc/ssl/certs" +$ export SSL_CERT_FILE="$HOME/.guix-profile/etc/ssl/certs/ca-certificates.crt" +$ export GIT_SSL_CAINFO="$SSL_CERT_FILE" +@end example + +Como otro ejemplo, R necesita que la variable de entorno +@code{CURL_CA_BUNDLE} apunte al empaquetado de certificados, de manera que +se debe ejecutar algo parecido a esto: + +@example +$ guix package -i nss-certs +$ export CURL_CA_BUNDLE="$HOME/.guix-profile/etc/ssl/certs/ca-certificates.crt" +@end example + +Para otras aplicaciones puede tener que buscar la variable de entorno +necesaria en la documentación relevante. + + +@node Selector de servicios de nombres +@section Selector de servicios de nombres + +@cindex name service switch +@cindex NSS +El módulo @code{(gnu system nss)} proporciona una interfaz con el fichero de +configuración del @dfn{selector de servicios de nombres} o @dfn{NSS} +(@pxref{NSS Configuration File,,, libc, The GNU C Library Reference +Manual}). En resumen, NSS es un mecanismo que permite la extensión de libc +con nuevos métodos de búsqueda de ``nombres'', lo que incluye nombres de +máquinas, nombres de servicios, cuentas de usuaria y más (@pxref{Selector de servicios de nombres, System Databases and Name Service Switch,, libc, The GNU C +Library Reference Manual}). + +La configuración de NSS especifica, para cada base de datos del sistema, que +método de búsqueda debe ser usado, y cómo los varios métodos se enlazan +entre sí---por ejemplo, bajo qué circunstancias NSS deberá probar con el +siguiente método en la lista. La configuración de NSS se proporciona en el +campo @code{name-service-switch} de las declaraciones +@code{operating-system} (@pxref{Referencia de ``operating-system'', +@code{name-service-switch}}). + +@cindex nss-mdns +@cindex .local, búsqueda de nombres de máquina +Como ejemplo, la siguiente declaración configura NSS para usar el +@uref{http://0pointer.de/lennart/projects/nss-mdns/, motor @code{nss-mdns}}, +que permite las búsquedas de nombres de máquinas sobre DNS multicast (mDNS) +para nombres de máquinas terminados en @code{.local}: + +@example +(name-service-switch + (hosts (list %files ;primero, comprueba /etc/hosts + + ;; Si lo anterior no funcionó, prueba + ;; con 'mdns_minimal'. + (name-service + (name "mdns_minimal") + + ;; 'mdns_minimal' tiene autoridad sobre + ;; '.local'. Cuando devuelve 'not-found, + ;; no es necesario intentarlo con los + ;; métodos siguientes. + (reaction (lookup-specification + (not-found => return)))) + + ;; Si no, usa DNS. + (name-service + (name "dns")) + + ;; Finalmente, prueba con 'mdns' "al completo". + (name-service + (name "mdns"))))) +@end example + +No se preocupe: la variable @code{%mdns-host-lookup-nss} (véase a +continuación) contiene esta configuración, de manera que no tiene que +escribirla si todo lo que desea es que funcione la búsqueda de nombres de +máquina en @code{.local}. + +Note that, in this case, in addition to setting the +@code{name-service-switch} of the @code{operating-system} declaration, you +also need to use @code{avahi-service-type} (@pxref{Servicios de red, +@code{avahi-service-type}}), or @var{%desktop-services}, which includes it +(@pxref{Servicios de escritorio}). Doing this makes @code{nss-mdns} accessible to +the name service cache daemon (@pxref{Servicios base, @code{nscd-service}}). + +Por conveniencia, las siguientes variables proporcionan configuraciones NSS +típicas. + +@defvr {Variable Scheme} %default-nss +Esta es la configuración predeterminada del selector de servicios de +nombres, un objeto @code{name-service-switch}. +@end defvr + +@defvr {Variable Scheme} %mdns-host-lookup-nss +Esta es la configuración del selector de servicios de nombres que permite la +búsqueda de nombres de máquinas por DNS multicast (mDNS) para nombres de +máquinas terminados en @code{.local}. +@end defvr + +La referencia de la configuración del selector de servicios de nombres se +proporciona a continuación. Tiene una asociación directa con el formato del +fichero de configuración de la biblioteca C, por lo que se recomienda el +manual de la biblioteca C para obtener más información (@pxref{NSS +Configuration File,,, libc, The GNU C Library Reference Manual}). En +comparación con el formato del fichero de configuración del NSS de libc, no +solo tiene solo la ventaja de la cálida sensación proporcionada por la +adición de paréntesis que tanto nos gustan, sino que también tiene +comprobaciones estáticas: conocerá los errores sintácticos y tipográficos +con la ejecución de @command{guix system}. + +@deftp {Tipo de datos} name-service-switch + +El tipo de datos que representa la configuración del selector de servicios +de nombres (NSS). Cada campo a continuación representa una de las bases de +datos del sistema admitidas. + +@table @code +@item aliases +@itemx ethers +@itemx group +@itemx gshadow +@itemx hosts +@itemx initgroups +@itemx netgroup +@itemx networks +@itemx password +@itemx public-key +@itemx rpc +@itemx services +@itemx shadow +Las bases de datos del sistema que maneja el NSS. Cada uno de estos campos +debe ser una lista de objetos @code{<name-service>} (véase a continuación). +@end table +@end deftp + +@deftp {Tipo de datos} name-service + +Este es el tipo de datos que representa un servicio de nombres real y la +acción de búsqueda asociada. + +@table @code +@item name +Una cadena que denota el nombre de servicio (@pxref{Services in the NSS +configuration,,, libc, The GNU C Library Reference Manual}). + +Fijese que los servicios de nombres enumerados aquí deben ser visibles para +nscd. Esto se consigue mediante la adición del parámetro +@code{#:name-services} a @code{nscd-service} con la lista de paquetes que +proporcionan los servicios de nombres necesarios (@pxref{Servicios base, +@code{nscd-service}}). + +@item reaction +Una acción especificada mediante el uso del macro +@code{lookup-specification} (@pxref{Actions in the NSS configuration,,, +libc, The GNU C Library Reference Manual}). Por ejemplo: + +@example +(lookup-specification (unavailable => continue) + (success => return)) +@end example +@end table +@end deftp + +@node Disco en RAM inicial +@section Disco en RAM inicial + +@cindex initrd +@cindex disco inicial de RAM +Para el propósito del arranque inicial, se le proporciona al núcleo +Linux-libre un @dfn{disco inicial de RAM}, o @dfn{initrd}. Un initrd +contiene un sistema de ficheros raíz temporal así como un guión de +inicialización. Este último es responsable del montaje del sistema de +ficheros raíz real, así como de la carga de cualquier módulo del núcleo que +pueda ser necesario para esta tarea. + +El campo @code{initrd-modules} de una declaración @code{operating-system} le +permite especificar qué módulos del nucleo Linux-libre deben estar +disponibles en el initrd. En particular, aquñi es donde se debe enumerar los +módulos que controlen realmente el disco duro deonde su partición raíz se +encuentre---aunque el valor predeterminado de @code{initrd-modules} debería +cubrir la mayor parte de casos de uso. Por ejemplo, en caso de necesitar el +módulo @code{megaraid_sas} además de los módulos predeterminados para poder +acceder a sistema de ficheros raíz, se podría escribir: + +@example +(operating-system + ;; @dots{} + (initrd-modules (cons "megaraid_sas" %base-initrd-modules))) +@end example + +@defvr {Variable Scheme} %base-initrd-modules +Esta es la lista de módulos del nucleo que se incluyen en el initrd +predeterminado. +@end defvr + +Más allá, si necesita personalizaciones de un nivel más bajo, el campo +@code{initrd} de una declaración @code{operating-system} le permite +especificar qué initrd desea usar. El módulo @code{(gnu system +linux-initrd)} proporciona tres formas de construir un initrd: el +procedimiento de alto nivel @code{base-initrd} y los procedimientos de bajo +nivel @code{raw-initrd} y @code{expression->initrd}. + +El procedimiento @code{base-initrd} está pensado para cubrir la mayor parte +de usos comunes. Por ejemplo, si desea añadir algunos módulos del nucleo que +deben cargarse durante el arranque, puede definir el campo @code{initrd} de +la declaración de sistema operativo de esta forma: + +@example +(initrd (lambda (sistemas-de-ficheros . resto) + ;; Crea un initrd estándar pero configura la red + ;; con los parámetros que QEMU espera por omisión. + (apply base-initrd sistemas-de-ficheros + #:qemu-networking? #t + resto))) +@end example + +El procedimiento @code{base-initrd} también maneja casos de uso comunes que +implican el uso del sistema en un anfitrión QEMU, o como un sistema ``live'' +con un sistema de ficheros raíz volátil. + +El procedimiento @code{base-initrd} se construye sobre el procedimiento +@code{raw-initrd}. Al contrario que @code{base-initrd}, @code{raw-initrd} no +funciona a alto nivel, como sería intentar deducir qué módulos del nucleo y +paquetes deben incluirse en el initrd. Un ejemplo de uso de +@code{raw-initrd} es cuando una usuaria tiene personalizada una +configuración del nucleo Linux y los módulos predeterminados del núcleo que +incluye @code{base-initrd} no están disponibles. + +El disco inicial de RAM producido por @code{base-initrd} o @code{raw-initrd} +inspecciona varias opciones proporcionadas por la línea de órdenes al núcleo +Linux (esto es, argumentos pasados a través de la orden @code{linux} de +GRUB, o de la opción @code{-append} de QEMU), notablemente: + +@table @code +@item --load=@var{arranque} +Indica al disco de RAM inicial que cargue @var{arranque}, un fichero que +contiene un programa Scheme, una vez haya montado el sistema de ficheros +raíz. + +Guix uses this option to yield control to a boot program that runs the +service activation programs and then spawns the GNU@tie{}Shepherd, the +initialization system. + +@item --root=@var{raíz} +Monta @var{raíz} como el sistema de ficheros raíz. @var{raíz} puede ser un +nombre de dispositivo como @code{/dev/sda1}, una etiqueta del sistema de +ficheros o un UUID del sistema de ficheros. + +@item --system=@var{sistema} +Hace que @file{/run/booted-system} y @file{/run/current-system} apunten a +@var{sistema}. + +@item modprobe.blacklist=@var{módulos}@dots{} +@cindex módulo, lista negra +@cindex lista negra, de módulos del núcleo +Indica al disco inicial de RAM así como a la orden @command{modprobe} (del +paquete kmod) que deben negarse a cargar @var{módulos}. @var{módulos} debe +ser una lista separada por comas de nombres de módulos---por ejemplo, +@code{usbkbd,9pnet}. + +@item --repl +Inicia una sesión interactiva (REPL) desde el disco inicial de RAM antes de +que intente cargar los módulos del núcleo y del montaje del sistema de +ficheros raíz. Nuestro departamento comercial lo llama +@dfn{arranca-en-Guile}. Como amante de Scheme, lo adorará. @xref{Using Guile +Interactively,,, guile, GNU Guile Reference Manual}, para más información +sobre sesiones interactivas Guile. + +@end table + +Now that you know all the features that initial RAM disks produced by +@code{base-initrd} and @code{raw-initrd} provide, here is how to use it and +customize it further. + +@cindex initrd +@cindex disco inicial de RAM +@deffn {Procedimiento Scheme} raw-initrd @var{sistemas-de-ficheros} @ + [#:linux-modules '()] [#:mapped-devices '()] @ [#:keyboard-layout #f] @ +[#:helper-packages '()] [#:qemu-networking? #f] [#:volatile-root? #f] Return +a derivation that builds a raw initrd. @var{file-systems} is a list of file +systems to be mounted by the initrd, possibly in addition to the root file +system specified on the kernel command line via @code{--root}. +@var{linux-modules} is a list of kernel modules to be loaded at boot time. +@var{mapped-devices} is a list of device mappings to realize before +@var{file-systems} are mounted (@pxref{Dispositivos traducidos}). +@var{helper-packages} is a list of packages to be copied in the initrd. It +may include @code{e2fsck/static} or other packages needed by the initrd to +check the root file system. + +When true, @var{keyboard-layout} is a @code{<keyboard-layout>} record +denoting the desired console keyboard layout. This is done before +@var{mapped-devices} are set up and before @var{file-systems} are mounted +such that, should the user need to enter a passphrase or use the REPL, this +happens using the intended keyboard layout. + +Cuando @var{qemu-networking?} es verdadero, configura la red con los +parámetros QEMU estándar. Cuando @var{virtio?} es verdadero, carga módulos +adicionales para que la imagen en RAM pueda ser usada como un sistema +virtualizado por QEMU con controladores paravirtualizados de E/S. + +Cuando @var{volatile-root?} es verdadero, el sistema de ficheros raíz tiene +permisos de escritura pero cualquier cambio realizado se perderá. +@end deffn + +@deffn {Procedimiento Scheme} base-initrd @var{sistemas-de-ficheros} @ + [#:mapped-devices '()] [#:keyboard-layout #f] @ [#:qemu-networking? #f] +[#:volatile-root? #f] @ [#:linux-modules '()] Return as a file-like object a +generic initrd, with kernel modules taken from @var{linux}. +@var{file-systems} is a list of file-systems to be mounted by the initrd, +possibly in addition to the root file system specified on the kernel command +line via @code{--root}. @var{mapped-devices} is a list of device mappings +to realize before @var{file-systems} are mounted. + +When true, @var{keyboard-layout} is a @code{<keyboard-layout>} record +denoting the desired console keyboard layout. This is done before +@var{mapped-devices} are set up and before @var{file-systems} are mounted +such that, should the user need to enter a passphrase or use the REPL, this +happens using the intended keyboard layout. + +@var{qemu-networking?} y @var{volatile-root?} funcionan como en +@code{raw-initrd}. + +El initrd incorpora automáticamente todos los módulos del nucleo necesarios +para @var{sistemas-de-ficheros} y para las opciones proporcionadas. Módulos +del nucleo adicionales pueden proporcionarse a través de +@var{linux-modules}. Se añadirán al initrd y se cargarán en tiempo de +arranque en el orden que aparezcan. +@end deffn + +No es necesario decir que los initrd que producimos y usamos embeben un +Guile enlazado estáticamente, y que el programa de inicialización es un +programa Guile. Esto proporciona mucha flexibilidad. El procedimiento +@code{expression->initrd} construye un initrd de ese tipo, una vez +proporcionado el programa a ejecutar en dicho initrd. + +@deffn {Procedimiento Scheme} expression->initrd @var{exp} @ + [#:guile %guile-static-stripped] [#:name "guile-initrd"] +Devuelve como un objeto tipo-fichero el initrd de Linux (un archivador cpio +comprimido con gzip) que contiene @var{guile} y que evalua a @var{exp}, una +expresión-G, al arranque. Todas las derivaciones a las que @var{exp} hace +referencia se copian automáticamente en el initrd. +@end deffn + +@node Configuración del gestor de arranque +@section Configuración del gestor de arranque + +@cindex bootloader +@cindex cargador de arranque + +El sistema operativo permite varios cargadores de arranque. El cargador de +arranque se configura mediante el uso de la declaración +@code{bootloader-configuration}. Todos los campos de esta estructura son +independientes del cargador de arranque excepto uno, @code{bootloader}, que +indica el cargador de arranque a configurar e instalar. + +Algunos de los cargadores de arranque no inspeccionan todos los campos de +@code{bootloader-configuration}. Por ejemplo, el cargador de arranque +extlinux no permite temas y por lo tanto ignora el campo @code{theme}. + +@deftp {Tipo de datos} bootloader-configuration +El tipo de una declaración de configuración del cargador de arranque. + +@table @asis + +@item @code{bootloader} +@cindex EFI, cargador de arranque +@cindex UEFI, cargador de arranque +@cindex BIOS, cargador de arranque +El cargador de arranque a usar, como un objeto @code{bootloader}. De momento +se aceptan @code{grub-bootloader}, @code{grub-efi-bootloader}, +@code{extlinux-bootloader} y @code{u-boot-bootloader}. + +@vindex grub-efi-bootloader +@code{grub-efi-bootloader} permite el arranque en sistemas modernos que usan +la @dfn{interfaz extendida de firmware unificada} (UEFI). Es el que debería +ser usado si la imagen de instalación contiene un directorio +@file{/sys/firmware/efi} cuando la arranca en su sistema. + +@vindex grub-bootloader +@code{grub-bootloader} permite el arranque en máquinas basadas en Intel en +modo ``antiguo'' BIOS. + +@cindex ARM, cargadores de arranque +@cindex AArch64, cargadores de arranque +Los cargadores de arranque se describen en los módulos @code{(gnu bootloader +@dots{})}. En particular, @code{(gnu bootloader u-boot)} contiene +definiciones de cargadores de arranque para un amplio rango de sistemas ARM +y AArch64, mediante el uso del @uref{http://www.denx.de/wiki/U-Boot/, +cargador de arranque U-Boot}. + +@item @code{target} +Una cadena que indica donde se instalará el cargador de arranque. + +La interpretación depende del cargador de arranque en cuestión. Para +@code{grub-bootloader}, por ejemplo, debe ser un nombre de dispositivo que +entienda la orden @command{install} del cargador de arranque, como +@code{/dev/sda} o @code{(hd0)} (@pxref{Invoking grub-install,,, grub, GNU +GRUB Manual}). Para @code{grub-efi-bootloader}, debe apuntar al punto de +montaje del sistema de ficheros EFI, habitualmente @file{/boot/efi}. + +@item @code{menu-entries} (predeterminadas: @code{()}) +Una lista posiblemente vacia de objetos @code{menu-entry} (véase a +continuación), que indican entradas que deben aparecer en el menú del +cargador de arranque, además de la entrada del sistema actual y la entrada +que apunta a generaciones previas del sistema. + +@item @code{default-entry} (predeterminada: @code{0}) +El índice de la entrada del menú de arranque por omisión. El índice 0 es +para la entrada del sistema actual. + +@item @code{timeout} (predeterminado: @code{5}) +El número de segundos que se esperará entrada por el teclado antes de +arrancar. El valor 0 indica que se debe arrancar de forma inmediata, y -1 +que se debe esperar indefinidamente. + +@cindex keyboard layout, for the bootloader +@item @code{keyboard-layout} (predeterminada: @code{#f}) +If this is @code{#f}, the bootloader's menu (if any) uses the default +keyboard layout, usually US@tie{}English (``qwerty''). + +Otherwise, this must be a @code{keyboard-layout} object (@pxref{Distribución de teclado}). + +@quotation Nota +This option is currently ignored by bootloaders other than @code{grub} and +@code{grub-efi}. +@end quotation + +@item @code{theme} (predeterminado: @var{#f}) +El objeto del tema del cargador de arranque que describa el tema a usar. Si +no se proporciona ningún tema, algunos cargadores de arranque pueden usar un +tema por omisión, lo cual es cierto en GRUB. + +@item @code{terminal-outputs} (predeterminada: @code{'gfxterm}) +Los terminales de salida que se usarán para el menú de arranque, como una +lista de símbolos. GRUB acepta los valores: @code{console}, @code{serial}, +@code{serial_@{0-3@}}, @code{gfxterm}, @code{vga_text}, @code{mda_text}, +@code{morse} y @code{pkmodem}. Este campo corresponde con la variable +@code{GRUB_TERMINAL_OUTPUT} (@pxref{Simple configuration,,, grub, GNU GRUB +manual}). + +@item @code{terminal-inputs} (predeterminadas: @code{'()}) +Los terminales de entrada que se usarán para el menú de arranque, como una +lista de símbolos. Para GRUB, el valor predeterminado es el terminal nativo +de la platafroma determinado en tiempo de ejecución. GRUB acepta los +valores: @code{console}, @code{serial}, @code{serial@{0-3@}}, +@code{at_keyboard} y @code{usb_keyboard}. Este campo corresponde a la +variable GRUB @code{GRUB_TERMINAL_INPUT} (@pxref{Simple configuration,,, +grub,GNU GRUB manual}). + +@item @code{serial-unit} (predeterminada: @code{#f}) +La unidad serie usada por el cargador de arranque, como un entero del 0 al +3. Para GRUB, se selecciona en tiempo de ejecución; actualmente GRUB +selecciona 0 lo que corresponde a COM1 (@pxref{Serial terminal,,, grub,GNU +GRUB manual}). + +@item @code{serial-speed} (predeterminada: @code{#f}) +La velocidad de la interfaz serie, como un entero. Para GRUB, el valor +predeterminado se selecciona en tiempo de ejecución, actualmente GRUB +selecciona 9600@tie{}bps (@pxref{Serial terminal,,, grub,GNU GRUB manual}). +@end table + +@end deftp + +@cindex arranque dual +@cindex menú de arranque +Si desease listar entradas adicionales para el menú de arranque a través del +campo @code{menu-entries} mostrado previamente, deberá crearlas con la forma +@code{menu-entry}. Por ejemplo, imagine que desea ser capaz de arrancar otra +distribución (¡difícil de imaginar!), puede definir una entrada de menú de +esta forma: + +@example +(menu-entry + (label "La otra distribución") + (linux "/boot/old/vmlinux-2.6.32") + (linux-arguments '("root=/dev/sda2")) + (initrd "/boot/old/initrd")) +@end example + +Los detalles se encuentran a continuación. + +@deftp {Tipo de datos} menu-entry +El tipo de una entrada en el menú del cargador de arranque. + +@table @asis + +@item @code{label} +La etiqueta a mostrar en el menú---por ejemplo, @code{"GNU"}. + +@item @code{linux} +La imagen del núcleo Linux a arrancar, por ejemplo: + +@example +(file-append linux-libre "/bzImage") +@end example + +Con GRUB, también es posible especificar un dispositivo explícitamente +mediante el uso de la convención de nombres de dispositivo de GRUB +(@pxref{Naming convention,,, grub, GNU GRUB manual}), por ejemplo: + +@example +"(hd0,msdos1)/boot/vmlinuz" +@end example + +Si se especifica el dispositivo explícitamente como en el ejemplo anterior, +el campo @code{device} se ignora completamente. + +@item @code{linux-arguments} (predeterminados: @code{()}) +La lista de parámetros extra de línea de órdenes para el núcleo Linux---por +ejemplo, @code{("console=ttyS0")}. + +@item @code{initrd} +Una expresión-G o una cadena que contiene el nombre de fichero del disco +inicial en RAM a usar (@pxref{Expresiones-G}). +@item @code{device} (predeterminado: @code{#f}) +El dispositivo donde se encuentran el núcleo y el initrd---es decir, para +GRUB, @dfn{raíz} de esta entrada de menú (@pxref{root,,, grub, GNU GRUB +manual}). + +Puede ser una etiqueta de sistema de ficheros (una cadena), un UUID de +sistema de ficheros (un vector de bytes, @pxref{Sistemas de ficheros}), o @code{#f}, +en cuyo caso el cargador de arranque buscará el dispositivo que contenga el +fichero especificado por el campo @code{linux} (@pxref{search,,, grub, GNU +GRUB manual}). @emph{No} debe ser un nombre de dispositivo del SO como +@file{/dev/sda1}. + +@end table +@end deftp + +@c FIXME: Write documentation once it's stable. +For now only GRUB has theme support. GRUB themes are created using the +@code{grub-theme} form, which is not documented yet. + +@defvr {Variable Scheme} %default-theme +Este es el tema predeterminado de GRUB que usa el sistema operativo si no se +especifica el campo @code{theme} en el registro +@code{bootloader-configuration}. + +Viene con una bonita imagen de fondo que muestra los logos de GNU y Guix. +@end defvr + + +@node Invocación de guix system +@section Invocación de @code{guix system} + +Una vez haya escrito la declaración de sistema operativo como se ha visto en +la sección previa, puede @dfn{instanciarse} mediante el uso de la orden +@command{guix system}. Su sinopsis es: + +@example +guix system @var{opciones}@dots{} @var{acción} @var{fichero} +@end example + +@var{fichero} debe ser el nombre de un fichero que contenga una declaración +@code{operating-system}. @var{acción} especifica cómo se instancia el +sistema operativo. Actualmente se permiten los siguientes valores: + +@table @code +@item search +Muestra las definiciones de tipos de servicio disponibles que corresponden +con las expresiones regulares proporcionadas, ordenadas por relevancia: + +@example +$ guix system search console font +name: console-fonts +location: gnu/services/base.scm:729:2 +extends: shepherd-root +description: Install the given fonts on the specified ttys (fonts are ++ per virtual console on GNU/Linux). The value of this service is a list ++ of tty/font pairs like: ++ ++ '(("tty1" . "LatGrkCyr-8x16")) +relevance: 20 + +name: mingetty +location: gnu/services/base.scm:1048:2 +extends: shepherd-root +description: Provide console login using the `mingetty' program. +relevance: 2 + +name: login +location: gnu/services/base.scm:775:2 +extends: pam +description: Provide a console log-in service as specified by its ++ configuration value, a `login-configuration' object. +relevance: 2 + +@dots{} +@end example + +Como con @command{guix package --search}, el resultado se obtiene en formato +@code{recutils}, lo que facilita el filtrado de la salida (@pxref{Top, GNU +recutils databases,, recutils, GNU recutils manual}). + +@item reconfigure +Build the operating system described in @var{file}, activate it, and switch +to it@footnote{This action (and the related actions @code{switch-generation} +and @code{roll-back}) are usable only on systems already running Guix +System.}. + +This effects all the configuration specified in @var{file}: user accounts, +system services, global package list, setuid programs, etc. The command +starts system services specified in @var{file} that are not currently +running; if a service is currently running this command will arrange for it +to be upgraded the next time it is stopped (e.g.@: by @code{herd stop X} or +@code{herd restart X}). + +Esta orden crea una nueva generación cuyo número es el sucesor de la +siguiente generación (como lo muestra @command{guix system +list-generations}). Si esa generación ya existe, será sobreescrita. Este +comportamiento es el mismo que el de @command{guix package} (@pxref{Invocación de guix package}). + +También añade una entrada al cargador de arranque para la nueva +configuración del sistema operativo---en caso de que no se proporcione la +opción @option{--no-bootloader}. Con GRUB, mueve las entradas de +configuraciones antiguas a un submenú, permitiendo la selección de una +generación previa del sistema en tiempo de arranque en caso necesario. + +@quotation Nota +@c The paragraph below refers to the problem discussed at +@c <http://lists.gnu.org/archive/html/guix-devel/2014-08/msg00057.html>. +Es altamente recomendable ejecutar @command{guix pull} antes de la primera +ejecución de @command{guix system reconfigure} (@pxref{Invocación de guix pull}). No hacerlo puede ocasionar que se obtenga una versión más antigua de +Guix una vez que @command{reconfigure} se haya completado. +@end quotation + +@item switch-generation +@cindex generaciones +Cambia a una generación existente del sistema. Esta acción cambia +atómicamente el perfil del sistema a la generación del sistema +especificada. También redistribuye las entradas de sistema del menú de +arranque existentes. Marca como predeterminada la entrada de la generación +de sistema especificada y mueve las entradas de otras generaciones a un +submenú, si el cargador de arranque lo permite. La próxima vez que se +arranque el sistema, se usará la generación de sistema especificada. + +El cargador de arranque en sí no se reinstala durante esta orden. Por tanto, +el cargador de arranque instalado se usa con un fichero de configuración +actualizado. + +La generación deseada puede especificarse explícitamente con su numero de +generación. Por ejemplo, la siguiente invocación cambiaría a la generación 7 +del sistema: + +@example +guix system switch-generation 7 +@end example + +La generación deseada puede especificarse también de forma relativa a la +generación actual con la forma @code{+N} o @code{-N}, donde @code{+3} +significa ``3 generaciones después de la generación actual'', y @code{-1} +significa ``1 generación antes de la generación actual''. Cuando se +especifica un valor negativo como @code{-1} debe ir precedido de @code{--} +para evitar que se analice como una opción. Por ejemplo: + +@example +guix system switch-generation -- -1 +@end example + +Actualmente, el efecto de la invocación de esta acción es @emph{únicamente} +cambiar el perfil del sistema a una generación existente y redistribuir las +entradas del menú de arranque. Para realmente empezar a usar la generación +deseada del sistema, debe reiniciar tras esta acción. En el futuro, se +actualizará para hacer lo mismo que @command{reconfigure}, como activación y +desactivación de servicios. + +Esta acción fallará si la generación especificada no existe. + +@item roll-back +@cindex vuelta atrás +Cambia a la generación de sistema previa. Tras el siguiente arranque del +sistema, usará la generación de sistema precedente. Es la operación inversa +de @command{reconfigure}, y es equivalente a la invocación de +@command{switch-generation} con @code{-1} como parámetro. + +Actualmente, como con @command{switch-generation}, debe reiniciar tras la +ejecución de esta acción para realmente empezar a usar la generación de +sistema precedente. + +@item delete-generations +@cindex deleting system generations +@cindex saving space +Delete system generations, making them candidates for garbage collection +(@pxref{Invocación de guix gc}, for information on how to run the ``garbage +collector''). + +This works in the same way as @command{guix package --delete-generations} +(@pxref{Invocación de guix package, @code{--delete-generations}}). With no +arguments, all system generations but the current one are deleted: + +@example +guix system delete-generations +@end example + +You can also select the generations you want to delete. The example below +deletes all the system generations that are more than two month old: + +@example +guix system delete-generations 2m +@end example + +Running this command automatically reinstalls the bootloader with an updated +list of menu entries---e.g., the ``old generations'' sub-menu in GRUB no +longer lists the generations that have been deleted. + +@item build +Construye la derivación del sistema operativo, que incluye todos los +ficheros de configuración y programas necesarios para el arranque y la +ejecución del sistema. Esta acción no instala nada en realidad. + +@item init +Populate the given directory with all the files necessary to run the +operating system specified in @var{file}. This is useful for first-time +installations of Guix System. For instance: + +@example +guix system init mi-conf-del-so.scm /mnt +@end example + +copia a @file{/mnt} todos los elementos del almacén necesarios para la +configuración especificada en @file{mi-conf-del-so.scm}. Esto incluye los +ficheros de configuración, paquetes y demás. También crea otros ficheros +esenciales necesarios para la correcta operación del sistema---por ejemplo, +los directorios @file{/etc}, @file{/var} y @file{/run}, y el fichero +@file{/bin/sh}. + +Esta orden también instala el cargador de arranque en el destino +especificado en @file{mi-conf-del-so.scm}, siempre que no se proporcione la +opción @option{--no-bootloader}. + +@item vm +@cindex máquina virtual +@cindex VM +@anchor{guix system vm} +Build a virtual machine that contains the operating system declared in +@var{file}, and return a script to run that virtual machine (VM). + +@quotation Nota +The @code{vm} action and others below can use KVM support in the Linux-libre +kernel. Specifically, if the machine has hardware virtualization support, +the corresponding KVM kernel module should be loaded, and the +@file{/dev/kvm} device node must exist and be readable and writable by the +user and by the build users of the daemon (@pxref{Configuración del entorno de construcción}). +@end quotation + +Arguments given to the script are passed to QEMU as in the example below, +which enables networking and requests 1@tie{}GiB of RAM for the emulated +machine: + +@example +$ /gnu/store/@dots{}-run-vm.sh -m 1024 -net user +@end example + +La VM comparte su almacén con el sistema anfitrión. + +Sistemas de ficheros adicionales pueden compartirse entre la máquina +anfitriona y la virtual mediante el uso de las opciones @code{--share} y +@code{--expose}: la primera especifica un directorio a compartir con acceso +de escritura, mientras que la última proporciona solo acceso de lectura al +directorio compartido. + +El siguiente ejemplo crea una máquina virtual en la que el directorio de la +usuaria es accesible en modo solo-lecture, y donde el directorio +@file{/intercambio} esta asociado de forma lectura-escritura con +@file{$HOME/tmp} en el sistema anfitrión: + +@example +guix system vm mi-configuracion.scm \ + --expose=$HOME --share=$HOME/tmp=/intercambio +@end example + +En GNU/Linux, lo predeterminado es arrancar directamente el núcleo; esto +posee la ventaja de necesitar únicamente una pequeña imagen del disco raíz +pequeña ya el el almacén de la anfitriona puede montarse. + +La opción @code{--full-boot} fuerza una secuencia de arranque completa, +desde el cargador de arranque. Esto necesita más espacio en disco ya que la +imagen raíz que contiene el núcleo, initrd y los ficheros de datos del +cargador de arranque deben crearse. La opción @code{--image-size} puede +usarse para especificar el tamaño de la imagen. + +@cindex Imágenes de sistema, creación en varios formatos +@cindex Creación de imágenes del sistema en varios formatos +@item vm-image +@itemx disk-image +@itemx docker-image +Devuelve una máquina virtual, imagen de disco o imagen Docker del sistema +operativo declarado en @var{fichero} que es independiente. Por omisión, +@command{guix system} estima el tamaño de la imagen necesario para almacenar +el sistema, pero puede usar la opción @option{--image-size} para especificar +un valor. Las imagenes Docker se construyen para que contengan exactamente +lo que necesitan, por lo que la opción @option{--image-size} se ignora en el +caso de @code{docker-image}. + +Puede especificar el sistema de ficheros raíz mediante el uso de la opción +@option{--file-system-type}. Su valor predeterminado es @code{ext4}. + +When using @code{vm-image}, the returned image is in qcow2 format, which the +QEMU emulator can efficiently use. @xref{Ejecutar Guix en una máquina virtual}, for more +information on how to run the image in a virtual machine. + +Con @code{disk-image} se produce una imagen de disco cruda; puede copiarse +tal cual en una memoria USB, por ejemplo. Asumiendo que @code{/dev/sdc} es +el dispositivo que corresponde a la memoria USB, se podría copiar la imagen +con la siguiente orden: + +@example +# dd if=$(guix system disk-image mi-so.scm) of=/dev/sdc +@end example + +Con @code{docker-image} se produce una imagen Docker. Guix construye la +imagen de cero, no de una imagen Docker base preexistente. Como resultado, +contiene @emph{exactamente} lo definido en el fichero de configuración del +sistema operativo. Puede cargar la imagen y ejecutar un contenedor Docker +mediante el uso de ordenes como las siguientes: + +@example +image_id="$(docker load < guix-system-docker-image.tar.gz)" +docker run -e GUIX_NEW_SYSTEM=/var/guix/profiles/system \\ + --entrypoint /var/guix/profiles/system/profile/bin/guile \\ + $image_id /var/guix/profiles/system/boot +@end example + +This command starts a new Docker container from the specified image. It +will boot the Guix system in the usual manner, which means it will start any +services you have defined in the operating system configuration. Depending +on what you run in the Docker container, it may be necessary to give the +container additional permissions. For example, if you intend to build +software using Guix inside of the Docker container, you may need to pass the +@option{--privileged} option to @code{docker run}. + +@item container +Devuelve un guión de la ejecución del sistema operativo declarado en +@var{fichero} dentro de un contenedor. Los contenedores son un conjunto de +mecanismos de aislamiento ligeros que proporciona el núcleo Linux-libre. Los +contenedores necesitan sustancialmente menos recursos que máquinas virtuales +completas debido a que el núcleo, los objetos compartidos y otros recursos +pueden compartirse con el sistema anfitrión; esto también significa que +proporcionan un menor aislamiento. + +En este momento, el guión debe ejecutarse como root para permitir más de una +única usuaria y grupo. El contenedor comparte su almacén con la máquina +anfitriona. + +Como con la acción @code{vm} (@pxref{guix system vm}), sistemas de ficheros +adicionales a compartir entre la máquina anfitriona y el contenedor pueden +especificarse mediante el uso de las opciones @option{--share} y +@option{--expose}: + +@example +guix system container mi-configuracion.scm \ + --expose=$HOME --share=$HOME/tmp=/intercambio +@end example + +@quotation Nota +Esta opción requiere Linux-libre 3.19 o posterior. +@end quotation + +@end table + +@var{opciones} puede contener cualquiera de las opciones de construcción +comunes (@pxref{Opciones comunes de construcción}). Además, @var{opciones} puede +contener una de las siguientes: + +@table @option +@item --expression=@var{expr} +@itemx -e @var{expr} +Consider the operating-system @var{expr} evaluates to. This is an +alternative to specifying a file which evaluates to an operating system. +This is used to generate the Guix system installer @pxref{Construcción de la imagen de instalación}). + +@item --system=@var{sistema} +@itemx -s @var{sistema} +Intenta la construcción para @var{sistema} en vez de para el tipo de la +máquina anfitriona. Funciona como en @command{guix build} (@pxref{Invocación de guix build}). + +@item --derivation +@itemx -d +Devuelve el nombre de fichero de la derivación del sistema operativo +proporcionado sin construir nada. + +@item --file-system-type=@var{tipo} +@itemx -t @var{tipo} +Para la acción @code{disk-image}, crea un sistema de ficheros del @var{tipo} +proporcionado en la imagen. + +Cuando se omite esta opción, @command{guix system} usa @code{ext4}. + +@cindex ISO-9660, formato +@cindex CD, formato de imagen +@cindex DVD, formato de imagen +@code{--file-system-type=iso9660} produce una imagen ISO-9660, que puede ser +grabada en CD y DVD. + +@item --image-size=@var{tamaño} +Junto a las acciones @code{vm-image} y @code{disk-image}, crea una imagen +del @var{ŧamaño} proporcionado. @var{tamaño} debe ser un número de bytes o +puede incluir una unidad como sufijo (@pxref{Block size, size +specifications,, coreutils, GNU Coreutils}). + +Cuando se omite esta opción, @command{guix system} calcula una estimación +del tamaño de la imagen en función del tamaño del sistema declarado en +@var{fichero}. + +@item --root=@var{fichero} +@itemx -r @var{fichero} +Hace que @var{fichero} sea un enlace simbólico al resultado, y lo registra +como una raíz del recolector de basura. + +@item --skip-checks +Omite las comprobaciones de seguridad previas a la instalación. + +Por omisión, @command{guix system init} y @command{guix system reconfigure} +realizan comprobaciones de seguridad: se aseguran de que los sistemas de +ficheros que aparecen en la declaración @code{operating-system} realmente +existen (@pxref{Sistemas de ficheros}) y que cualquier módulo del núcleo Linux que +pudiese necesitarse durante el arranque se encuentre en +@code{initrd-modules} (@pxref{Disco en RAM inicial}). El uso de esta opción +omite todas estas comprobaciones. + +@cindex on-error +@cindex on-error strategy +@cindex error strategy +@item --on-error=@var{estrategia} +Aplica @var{estrategia} cuando ocurre un error durante la lectura de +@var{fichero}. @var{estrategia} puede ser uno de los siguientes valores: + +@table @code +@item nothing-special +Informa concisamente del error y termina la ejecución. Es la estrategia +predeterminada. + +@item backtrace +Del mismo modo, pero también muestra la secuencia de llamadas. + +@item debug +Informa del error y entra en el depurador de Guile. A partir de ahí, puede +ejecutar órdenes como @code{,bt} para obtener la secuencia de llamads, +@code{,locals} para mostrar los valores de las variables locales, e +inspeccionar el estado del programa de forma más general. @xref{Debug +Commands,,, guile, GNU Guile Reference Manual}, para una lista de órdenes de +depuración disponibles. +@end table +@end table + +Once you have built, configured, re-configured, and re-re-configured your +Guix installation, you may find it useful to list the operating system +generations available on disk---and that you can choose from the bootloader +boot menu: + +@table @code + +@item list-generations +Muestra un resumen de cada generación del sistema operativo disponible en el +disco, de manera legible por humanos. Es similar a la opción +@option{--list-generations} de @command{guix package} (@pxref{Invocación de guix package}). + +De manera opcional, se puede especificar un patrón, con la misma sintaxis +que la usada en @command{guix package --list-generations}, para restringir +la lista de generaciones mostradas. Por ejemplo, la siguiente orden muestra +generaciones que tienen hasta 10 días de antigüedad: + +@example +$ guix system list-generations 10d +@end example + +@end table + +¡La orden @command{guix system} tiene aún más que ofrecer! Las siguientes +ordenes le permiten visualizar cual es la relación entre los servicios del +sistema: + +@anchor{system-extension-graph} +@table @code + +@item extension-graph +Emite en formato Dot/Graphviz por la salida estándar el @dfn{grafo de +extensiones de servicio} del sistema operativo definido en @var{fichero} +(@pxref{Composición de servicios}, para más información sobre extensiones de +servicio). + +La orden: + +@example +$ guix system extension-graph @var{fichero} | dot -Tpdf > servicios.pdf +@end example + +produce un fichero PDF que muestra las relaciones de extensiones entre los +servicios. + +@anchor{system-shepherd-graph} +@item shepherd-graph +Emite en formato Dot/Graphviz por la salida estándar el @dfn{grafo de +dependencias} de los servicios shepherd del sistema operativo definido en +@var{fichero}. @xref{Servicios de Shepherd}, para más información y un grafo de +ejemplo. + +@end table + +@node Ejecutar Guix en una máquina virtual +@section Ejecución de Guix en una máquina virtual + +@cindex máquina virtual +To run Guix in a virtual machine (VM), one can either use the pre-built Guix +VM image distributed at +@indicateurl{https://alpha.gnu.org/gnu/guix/guix-system-vm-image-@value{VERSION}.@var{system}.xz} +, or build their own virtual machine image using @command{guix system +vm-image} (@pxref{Invocación de guix system}). The returned image is in qcow2 +format, which the @uref{http://qemu.org/, QEMU emulator} can efficiently +use. + +@cindex QEMU +Si ha construido su propia imagen, debe copiarla fuera del almacén y +proporcionarse a sí misma permisos de escritura sobre dicha copia antes de +usarla. En la invocación de QEMU debe elegir un emulador de sistema que sea +adecuado para su plataforma hardware. Esta es una invocación de QEMU mínima +que arrancará el resultado de @command{guix system vm-image} en hardware +x86_64: + +@example +$ qemu-system-x86_64 \ + -net user -net nic,model=virtio \ + -enable-kvm -m 256 /tmp/imagen-qemu +@end example + +Aquí está el significado de cada una de esas opciones: + +@table @code +@item qemu-system-x86_64 +Esto especifica la plataforma hardware a emular. Debe corresponder con el +anfitrión. + +@item -net user +Habilita la pila de red en modo de usuaria sin privilegios. El SO +virtualizado puede acceder al anfitrión pero no al revés. Esta es la forma +más simple de poner en línea un SO virtualizado. + +@item -net nic,model=virtio +Debe crear una interfaz de red del modelo proporcionado. Si la crea, el +arranque fallará. Asumiendo que su plataforma hardware sea x86_64, puede +obtener una lista de modelos de interfaz de red disponibles ejecutando +@command{qemu-system-x86_64 -net nic,model=help}. + +@item -enable-kvm +Si su sistema tiene extensiones de virtualización por hardware, la +activación de la implementación de máquinas virtuales (KVM) del núcleo Linux +hará que la ejecución sea más rápida. + +@item -m 256 +RAM disponible para el sistema operativo virtualizado, en mebibytes. El +valor predeterminado es 128@tie{}MiB, que puede ser insuficiente para +algunas operaciones. + +@item /tmp/imagen-qemu +El nombre de fichero de la imagen qcow2. +@end table + +El guión @command{run-vm.sh} predeterminado que devuelve la invocación de +@command{guix system vm} no añade una opción @command{-net user} por +defecto. Para obtener acceso a la red desde la máquina virtual añada el +servicio @code{(dhcp-client-service)} a su definición de sistema y arranque +la máquina virtual mediante el uso de @command{`guix system vm config.scm` +-net user}. Un punto importante a tener en cuenta del uso de @command{-net +user} para la obtención de red es que @command{ping} no funcionará, puesto +que usa el protocolo ICMP. Deberá usar una orden diferente para comprobar la +conectividad a la red, por ejemplo @command{guix download}. + +@subsection Conexión a través de SSH + +@cindex SSH +@cindex servidor SSH +Para activar SSH dentro de una máquina virtual debe añadir un servidor SSH +como @code{(dropbear-service)} o @code{(lsh-service)} en su máquina +virtual. El servicio @code{(lsh-service)} no arranca actualmente sin +supervisión, ya que precisa de entrada para inicializar el generador de +aleatoriedad. Además tiene que redirigir el puerto SSH, 22 el +predeterminado, a la máquina anfitriona. Puede hacerlo con + +@example +`guix system vm config.scm` -net user,hostfwd=tcp::10022-:22 +@end example + +Para conectarse a la máquina virtual puede ejecutar + +@example +ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -p 10022 +@end example + +La @command{-p} indica a @command{ssh} el puerto al que se debe +conectar. @command{-o UserKnownHostsFile=/dev/null} evita que @command{ssh} +se queje cada vez que modifique su fichero @command{config.scm} y la orden +@command{-o StrictHostKeyChecking=no} evita que tenga que autorizar la +conexión a una máquina desconocida cada vez que se conecte. + +@subsection Uso de @command{virt-viewer} con Spice + +Como alternativa al cliente gráfico predeterminado de @command{qemu} puede +usar @command{remote-viewer} del paquete @command{virt-viewer}. Para +conectarse proporcione la opción @command{-spice +port=5930,disable-ticketing} a @command{qemu}. Véase la sección previa para +más información sobre cómo hacer esto. + +Spice también le permite hacer cosas como compartir su portapapeles con su +máquina virtual. Para activarlo debe proporcionar también las siguientes +opciones a @command{qemu}: + +@example +-device virtio-serial-pci,id=virtio-serial0,max_ports=16,bus=pci.0,addr=0x5 +-chardev spicevmc,name=vdagent,id=vdagent +-device virtserialport,nr=1,bus=virtio-serial0.0,chardev=vdagent, +name=com.redhat.spice.0 +@end example + +También debe añadir el @pxref{Servicios misceláneos, servicio Spice}. + +@node Definición de servicios +@section Definición de servicios + +Las secciones anteriores muestran los servicios disponibles y cómo se pueden +combinar en una declaración @code{operating-system}. ¿Pero cómo las +definimos en primer lugar? ¿Y qué es un servicio en cualquier caso? + +@menu +* Composición de servicios:: El modelo para la composición de servicios. +* Tipos de servicios y servicios:: Tipos y servicios +* Referencia de servicios:: Referencia de la API. +* Servicios de Shepherd:: Un tipo de servicio particular. +@end menu + +@node Composición de servicios +@subsection Composición de servicios + +@cindex services +@cindex daemons +Definimos un @dfn{servicio} como, @i{grosso modo}, algo que extiende la +funcionalidad del sistema operativo. Habitualmente un servicio es un +proceso---un @dfn{daemon}---iniciado cuando el sistema arranca: un servidor +de shell seguro, un servidor Web, el daemon de construcción de Guix, etc. A +veces un servicio es un daemon cuya ejecución puede ser iniciada por otro +daemon---por ejemplo, un servidor FTP iniciado por @command{inetd} o un +servicio D-Bus activado por @command{dbus-daemon}. De manera ocasional, un +servicio no se puede asociar a un daemon. Por ejemplo, el servicio +``account'' recopila cuentas de usuaria y se asegura que existen cuando el +sistema se ejecuta; el servicio ``udev'' recopila reglas de gestión de +dispositivos y los pone a disposición del daemon eudev; el servicio +@file{/etc} genera el contenido del directorio @file{/etc} del sistema. + +@cindex extensiones de servicios +Guix system services are connected by @dfn{extensions}. For instance, the +secure shell service @emph{extends} the Shepherd---the initialization +system, running as PID@tie{}1---by giving it the command lines to start and +stop the secure shell daemon (@pxref{Servicios de red, +@code{openssh-service-type}}); the UPower service extends the D-Bus service +by passing it its @file{.service} specification, and extends the udev +service by passing it device management rules (@pxref{Servicios de escritorio, +@code{upower-service}}); the Guix daemon service extends the Shepherd by +passing it the command lines to start and stop the daemon, and extends the +account service by passing it a list of required build user accounts +(@pxref{Servicios base}). + +Al fin y al cabo, los servicios y sus relaciones de ``extensión'' forman un +grafo acíclico dirigido (GAD). Si representamos los servicios como cajas y +las extensiones como flechas, un sistema típico puede proporcionar algo de +este estilo: + +@image{images/service-graph,,5in,Grafo típico de extensiones de servicios.} + +@cindex servicio del sistema +En la base, podemos ver el @dfn{servicio del sistema}, el cual produce el +directorio que contiene todo lo necesario para ejecutar y arrancar el +sistema, como es devuelto por la orden @command{guix system +build}. @xref{Referencia de servicios}, para aprender acerca de otros servicios +mostrados aquí. @xref{system-extension-graph, la orden @command{guix system +extension-graph}}, para información sobre cómo generar esta representación +para una definición particular de sistema operativo. + +@cindex tipos de servicio +Technically, developers can define @dfn{service types} to express these +relations. There can be any number of services of a given type on the +system---for instance, a system running two instances of the GNU secure +shell server (lsh) has two instances of @code{lsh-service-type}, with +different parameters. + +La siguiente sección describe la interfaz programática para tipos de +servicio y servicios. + +@node Tipos de servicios y servicios +@subsection Tipos de servicios y servicios + +Un @dfn{tipo de servicio} es un nodo en el GAD descrito +previamente. Empecemos con un ejemplo simple, el tipo de servicio para el +daemon de construcción Guix (@pxref{Invocación de guix-daemon}): + +@example +(define guix-service-type + (service-type + (name 'guix) + (extensions + (list (service-extension shepherd-root-service-type guix-shepherd-service) + (service-extension account-service-type guix-accounts) + (service-extension activation-service-type guix-activation))) + (default-value (guix-configuration)))) +@end example + +@noindent +Define tres cosas: + +@enumerate +@item +Un nombre, cuyo único propósito es facilitar la inspección y la depuración. + +@item +Una lista de @dfn{extensiones de servicio}, donde cada extensión designa el +tipo de servicio a extender y un procedimiento que, dados los parámetros del +servicio, devuelve una lista de objetos para extender el servicio de dicho +tipo. + +Cada tipo de servicio tiene al menos una extensión de servicio. La única +excepción es el @dfn{tipo de servicio de arranque}, que es el último +servicio. + +@item +De manera opcional, un valor predeterminado para instancias de este tipo. +@end enumerate + +In this example, @code{guix-service-type} extends three services: + +@table @code +@item shepherd-root-service-type +The @code{guix-shepherd-service} procedure defines how the Shepherd service +is extended. Namely, it returns a @code{<shepherd-service>} object that +defines how @command{guix-daemon} is started and stopped (@pxref{Servicios de Shepherd}). + +@item account-service-type +This extension for this service is computed by @code{guix-accounts}, which +returns a list of @code{user-group} and @code{user-account} objects +representing the build user accounts (@pxref{Invocación de guix-daemon}). + +@item activation-service-type +Here @code{guix-activation} is a procedure that returns a gexp, which is a +code snippet to run at ``activation time''---e.g., when the service is +booted. +@end table + +Un servicio de este tipo se puede instanciar de esta manera: + +@example +(service guix-service-type + (guix-configuration + (build-accounts 5) + (use-substitutes? #f))) +@end example + +El segundo parámetro a la forma @code{service} es un valor que representa +los parámetros de esta instancia específica del +servicio. @xref{guix-configuration-type, @code{guix-configuration}}, para +información acerca del tipo de datos @code{guix-configuration}. Cuando se +omite el valor, se usa el valor predeterminado por @code{guix-service-type}: + +@example +(service guix-service-type) +@end example + +@code{guix-service-type} is quite simple because it extends other services +but is not extensible itself. + +@c @subsubsubsection Extensible Service Types + +El tipo de servicio para un servicio @emph{extensible} puede tener esta +forma: + +@example +(define udev-service-type + (service-type (name 'udev) + (extensions + (list (service-extension shepherd-root-service-type + udev-shepherd-service))) + + (compose concatenate) ;concatena la lista de reglas + (extend (lambda (config rules) + (match config + (($ <udev-configuration> udev initial-rules) + (udev-configuration + (udev udev) ;el paquete udev a usar + (rules (append initial-rules rules))))))))) +@end example + +This is the service type for the +@uref{https://wiki.gentoo.org/wiki/Project:Eudev, eudev device management +daemon}. Compared to the previous example, in addition to an extension of +@code{shepherd-root-service-type}, we see two new fields: + +@table @code +@item compose +Este es el procedimiento para @dfn{componer} la lista de extensiones en +servicios de este tipo. + +Los servicios pueden extender el servicio udev proporcionandole una lista de +reglas; componemos estas extensiones simplemente concatenandolas. + +@item extend +Este procedimiento define cómo el valor del servicio se @dfn{extiende} con +la composición de la extensión. + +Las extensiones de udev se componen en una lista de reglas, pero el valor +del servicio udev es en sí un registro @code{<udev-configuration>}. Por +tanto aquí extendemos el registro agregando la lista de reglas que contiene +al final de la lista de reglas que se contribuyeron. + +@item description +Es una cadena que proporciona una descripción del tipo de servicio. Dicha +cadena puede contener lenguaje de marcado Texinfo (@pxref{Overview,,, +texinfo, GNU Texinfo}). La orden @command{guix system search} busca estas +cadenas y las muestra (@pxref{Invocación de guix system}). +@end table + +There can be only one instance of an extensible service type such as +@code{udev-service-type}. If there were more, the @code{service-extension} +specifications would be ambiguous. + +¿Todavía aquí? La siguiente sección proporciona una referencia de la +interfaz programática de los servicios. + +@node Referencia de servicios +@subsection Referencia de servicios + +Ya hemos echado un vistazo a los tipos de servicio (@pxref{Tipos de servicios y servicios}). Esta sección proporciona referencias sobre cómo manipular +servicios y tipos de servicio. Esta interfaz se proporciona en el módulo +@code{(gnu services)}. + +@deffn {Procedimiento Scheme} service @var{tipo} [@var{valor}] +Devuelve un nuevo servicio de @var{tipo}, un objeto @code{<service-type>} +(véase a continuación). @var{valor} puede ser cualquier objeto; represental +los parámetros de esta instancia de servicio particular. + +Cuando se omite @var{valor}, se usa el valor predeterminado especificado por +@var{tipo}; si @var{type} no especifica ningún valor, se produce un error. + +Por ejemplo, esto: + +@example +(service openssh-service-type) +@end example + +@noindent +es equivalente a esto: + +@example +(service openssh-service-type + (openssh-configuration)) +@end example + +En ambos casos el resultado es una instancia de @code{openssh-service-type} +con la configuración predeterminada. +@end deffn + +@deffn {Procedimiento Scheme} service? @var{obj} +Devuelve verdadero si @var{obj} es un servicio. +@end deffn + +@deffn {Procedimiento Scheme} service-kind @var{servicio} +Devuelve el tipo de @var{servicio}---es decir, un objeto +@code{<service-type>}. +@end deffn + +@deffn {Procedimiento Scheme} service-value @var{servicio} +Devuelve el valor asociado con @var{servicio}. Representa sus parámetros. +@end deffn + +Este es un ejemplo de creación y manipulación de un servicio: + +@example +(define s + (service nginx-service-type + (nginx-configuration + (nginx nginx) + (log-directory log-directory) + (run-directory run-directory) + (file config-file)))) + +(service? s) +@result{} #t + +(eq? (service-kind s) nginx-service-type) +@result{} #t +@end example + +The @code{modify-services} form provides a handy way to change the +parameters of some of the services of a list such as @code{%base-services} +(@pxref{Servicios base, @code{%base-services}}). It evaluates to a list of +services. Of course, you could always use standard list combinators such as +@code{map} and @code{fold} to do that (@pxref{SRFI-1, List Library,, guile, +GNU Guile Reference Manual}); @code{modify-services} simply provides a more +concise form for this common pattern. + +@deffn {Sintaxis Scheme} modify-services @var{servicios} @ + (@var{tipo} @var{variable} => @var{cuerpo}) @dots{} + +Modifica los servicios listados en @var{servicios} de acuerdo a las +cláusulas proporcionadas. Cada cláusula tiene la forma: + +@example +(@var{tipo} @var{variable} => @var{cuerpo}) +@end example + +donde @var{tipo} es un tipo de servicio---por ejemplo, +@code{guix-service-type}---y @var{variable} es un identificador que se +asocia dentro del @var{cuerpo} a los parámetros del servicio---por ejemplo, +una instancia @code{guix-configuration}---del servicio original de dicho +@var{ŧipo}. + +El @var{cuerpo} deve evaluar a los nuevos parámetros del servicio, que serán +usados para configurar el nuevo servicio. Este nuevo servicio reemplaza el +original en la lista resultante. Debido a que los parámetros de servicio de +un servicio se crean mediante el uso de @code{define-record-type*}, puede +escribir un breve @var{cuerpo} que evalúe a los nuevos parámetros del +servicio mediante el uso de la característica @code{inherit} que proporciona +@code{define-record-type*} para heredar los valores antiguos. + +@xref{Uso de la configuración del sistema}, para ejemplos de uso. + +@end deffn + +A continuación se procede con la interfaz programática de los tipos de +servicios. Es algo que debe conocer para escribir definiciones de nuevos +servicios, pero no es cuando busque formas de personalizar su declaración +@code{operating-system}. + +@deftp {Tipo de datos} service-type +@cindex tipo de servicio +Esta es la representación de un @dfn{tipo de servicio} (@pxref{Tipos de servicios y servicios}). + +@table @asis +@item @code{name} +Es un símbolo, usado únicamente para simplificar la inspección y la +depuración. + +@item @code{extensions} +Una lista no vacía de objetos @code{<service-extension>} (véase a +continuación). + +@item @code{compose} (predeterminado: @code{#f}) +Si es @code{#f}, entonces el tipo de servicio denota servicios que no pueden +extenderse---es decir, servicios que no pueden recibir ``valores'' de otros +servicios. + +En otro caso, debe ser un procedimiento de un único parámetro. El +procedimiento es invocado en @code{fold-services} y se le proporciona una +lista de valores recibidos de las extensiones. Puede devolver un valor +único. + +@item @code{extend} (predeterminado: @code{#f}) +Si es @code{#f}, los servicios de este tipo no pueden extenderse. + +En otro caso, debe ser un procedimiento que acepte dos parámetros: +@code{fold-services} lo invoca, proporcionandole el valor inicial del +servicio como el primer parámetro y el resultado de aplicar @code{compose} a +los valores de las extensiones como segundo parámetro. Debe devolver un +valor que es un parámetro válido para la instancia del servicio. +@end table + +@xref{Tipos de servicios y servicios}, para ejemplos. +@end deftp + +@deffn {Procedimiento Scheme} service-extension @var{tipo-deseado} @ + @var{calcula} + +Devuelve una nueva extensión para servicios del tipo +@var{tipo-deseado}. @var{calcula} debe ser un procedimiento de un único +parámetro: es llamado en @code{fold-services}, proporcionandole el valor +asociado con el servicio que proporciona la extensión; debe devolver un +valor válido para el servicio deseado. +@end deffn + +@deffn {Procedimiento Scheme} service-extension? @var{obj} +Devuelve verdadero si @var{obj} es una expresión-G. +@end deffn + +De manera ocasional, puede desear simplemente extender un servicio +existente. Esto implica la creación de un nuevo tipo de servicio y la +especificación de la extensión deseada, lo cual puede ser engorroso; el +procedimiento @code{simple-service} proporciona un atajo para ello. + +@deffn {Procedimiento Scheme} simple-service @var{nombre} @var{deseado} @var{valor} +Devuelve un servicio que extiende @var{deseado} con @var{valor}. Esto +funciona creando una instancia única del tipo de servicio @var{nombre}, de +la cual el servicio devuelto es una instancia. + +Por ejemplo, esto extiende mcron (@pxref{Ejecución de tareas programadas}) con una +tarea adicional: + +@example +(simple-service 'mi-tarea-mcron mcron-service-type + #~(job '(next-hour (3)) "guix gc -F 2G")) +@end example +@end deffn + +En el núcleo de la abstracción de los servicios se encuentra el +procedimiento @code{fold-services}, que es responsable de la ``compilación'' +de una lista de servicios en un único directorio que contiene todo lo +necesario para arrancar y ejecutar el sistema---el directorio mostrado por +la orden @command{guix system build} (@pxref{Invocación de guix system}). En +esencia, propaga las extensiones de servicios a través del grafo de +servicios, actualizando los parámetros de cada nodo en el camino, hasta que +alcanza el nodo raíz. + +@deffn {Procedimiento Scheme} fold-services @var{servicios} @ + [#:target-type @var{system-service-type}] +Recorre @var{servicios} propagando sus extensiones hasta la raíz del tipo +@var{target-type}; devuelve el servicio raíz tratado de la manera apropiada. +@end deffn + +Por último, el módulo @code{(gnu services)} también define varios tipos +esenciales de servicios, algunos de los cuales se enumeran a continuación. + +@defvr {Variable Scheme} system-service-type +Esta es la raíz del grafo de servicios. Produce el directorio del sistema +como lo devuelve la orden @code{guix system build}. +@end defvr + +@defvr {Variable Scheme} boot-service-type +El tipo del ``servicio de arranque'', que produce un @dfn{guión de +arranque}. El guión de arranque es lo que ejecuta el disco inicial de RAM +cuando se arranca. +@end defvr + +@defvr {Variable Scheme} etc-service-type +El tipo del servicio @file{/etc}. Este servicio se usa para crear los +ficheros en @file{/etc} y puede extenderse proporcionandole pares +nombre/fichero como estas: + +@example +(list `("issue" ,(plain-file "issue" "¡Bienvenida!\n"))) +@end example + +En este ejemplo, el ejecto sería la adición de un fichero @file{/etc/issue} +que apunta al fichero proporcionado. +@end defvr + +@defvr {Variable Scheme} setuid-program-service-type +Tipo para el ``servicio de programas setuid''. Este servicio recopila listas +de nombres de ficheros ejecutables, proporcionados como expresiones-G, y los +añade al conjunto de programas con setuid de root en el sistema +(@pxref{Programas con setuid}). +@end defvr + +@defvr {Variable Scheme} profile-service-type +Tipo del servicio que genera el @dfn{perfil del sistema}---es decir, los +programas en @file{/run/current-system/profile}. Otros servicios pueden +extenderlo proporcionandole listas de paquetes a añadir al perfil del +sistema. +@end defvr + + +@node Servicios de Shepherd +@subsection Servicios de Shepherd + +@cindex servicios de shepherd +@cindex PID 1 +@cindex sistema de inicio +The @code{(gnu services shepherd)} module provides a way to define services +managed by the GNU@tie{}Shepherd, which is the initialization system---the +first process that is started when the system boots, also known as +PID@tie{}1 (@pxref{Introducción,,, shepherd, The GNU Shepherd Manual}). + +Los servicios en Shepherd pueden depender de otros servicios. Por ejemplo, +el daemon SSH puede tener que arrancarse tras el arranque del daemon syslog, +lo cual a su vez puede suceder únicamente tras el montaje de todos los +sistemas de ficheros. El sistema operativo simple definido previamente +(@pxref{Uso de la configuración del sistema}) genera un grafo de servicios como +este: + +@image{images/shepherd-graph,,5in,Grafo típico de servicios de shepherd.} + +En realidad puede generar dicho grafo para cualquier definición de sistema +operativo mediante el uso de la orden @command{guix system shepherd-graph} +(@pxref{system-shepherd-graph, @command{guix system shepherd-graph}}). + +The @code{%shepherd-root-service} is a service object representing +PID@tie{}1, of type @code{shepherd-root-service-type}; it can be extended by +passing it lists of @code{<shepherd-service>} objects. + +@deftp {Tipo de datos} shepherd-service +El tipo de datos que representa un servicio gestionado por Shepherd. + +@table @asis +@item @code{provision} +Una lista de símbolos que indican lo que proporciona el servicio. + +Esto son nombres que pueden proporcionarse a @command{herd start}, +@command{herd status} y órdenes similares (@pxref{Invoking herd,,, shepherd, +The GNU Shepherd Manual}). @xref{Slots of services, the @code{provides} +slot,, shepherd, The GNU Shepherd Manual}, para más detalles. + +@item @code{requirements} (predeterminados: @code{'()}) +Lista de símbolos que indican los servicios Shepherd de los que este +depende. + +@cindex one-shot services, for the Shepherd +@item @code{one-shot?} (predeterminado: @code{#f}) +Whether this service is @dfn{one-shot}. One-shot services stop immediately +after their @code{start} action has completed. @xref{Slots of services,,, +shepherd, The GNU Shepherd Manual}, for more info. + +@item @code{respawn?} (predeterminado: @code{#t}) +Indica si se debe reiniciar el servicio cuando se para, por ejemplo cuando +el proceso subyacente muere. + +@item @code{start} +@itemx @code{stop} (predeterminado: @code{#~(const #f)}) +Los campos @code{start} y @code{stop} hacen referencia a las características +de Shepherd de arranque y parada de procesos respectivamente (@pxref{Service +De- and Constructors,,, shepherd, The GNU Shepherd Manual}). Se proporcionan +como expresiones-G que se expandirán en el fichero de configuración de +Shepherd (@pxref{Expresiones-G}). + +@item @code{actions} (predeterminadas: @code{'()}) +@cindex acciones, de servicios de Shepherd +Esta es la lista de objetos @code{shepherd-action} (véase a continuación) +que definen las @dfn{acciones} permitidas por el servicio, además de las +acciones estándar @code{start} y @code{stop}. Las acciones que se listan +aquí estarán disponibles como ordenes de @command{herd}: + +@example +herd @var{acción} @var{servicio} [@var{parámetros}@dots{}] +@end example + +@item @code{documentación} +Una cadena de documentación, que se mostrará al ejecutar: + +@example +herd doc @var{nombre-del-servicio} +@end example + +where @var{service-name} is one of the symbols in @code{provision} +(@pxref{Invoking herd,,, shepherd, The GNU Shepherd Manual}). + +@item @code{modules} (default: @code{%default-modules}) +Esta es la lista de módulos que deben estar dentro del ámbito cuando +@code{start} y @code{stop} son evaluados. + +@end table +@end deftp + +@deftp {Tipo de datos} shepherd-action +Este es el tipo de datos que define acciones adicionales implementadas por +un servicio Shepherd (vea previamente). + +@table @code +@item name +Símbolo que nombra la acción. + +@item documentación +Esta es una cadena de documentación para la acción. Puede verse ejecutando: + +@example +herd doc @var{servicio} action @var{acción} +@end example + +@item procedure +Debe ser una expresión-G que evalua a un procedimiento de al menos un +parámetro, el cual es el ``valor de ejecución'' del servicio (@pxref{Slots +of services,,, shepherd, The GNU Shepherd Manual}). +@end table + +El siguiente ejemplo define una acción llamada @code{di-hola} que saluda +amablemente a la usuaria: + +@example +(shepherd-action + (name 'di-hola) + (documentation "¡Di hola!") + (procedure #~(lambda (running . args) + (format #t "¡Hola, compa! parámetros: ~s\n" + args) + #t))) +@end example + +Asumiendo que esta acción se añade al servicio @code{ejemplo}, puede +ejecutar: + +@example +# herd di-hola ejemplo +¡Hola, compa! parámetros: () +# herd di-hola ejemplo a b c +¡Hola, compa! parámetros: ("a" "b" "c") +@end example + +Esta, como puede ver, es una forma un tanto sofisticada de decir +hola. @xref{Service Convenience,,, shepherd, The GNU Shepherd Manual}, para +más información sobre acciones. +@end deftp + +@defvr {Variable Scheme} shepherd-root-service-type +El tipo de servicio para el ``servicio raíz'' de Shepherd---es decir, +PID@tie{}1. + +El tipo de servicio que las extensiones declaran cuando desean crear +servicios shepherd (@pxref{Tipos de servicios y servicios}, para un +ejemplo). Cada extensión debe pasar una lista de @code{<shepherd-service>}. +@end defvr + +@defvr {Variable Scheme} %shepherd-root-service +Este servicio representa el PID@tie{}1. +@end defvr + + +@node Documentación +@chapter Documentación + +@cindex documentación, búsqueda +@cindex búsqueda de documentación +@cindex Info, formato de documentación +@cindex páginas man +@cindex páginas de manual +En la mayor parte de casos, los paquetes instalados con Guix contienen +documentación. Hay dos formatos principales de documentación: ``Info'', un +formato hipertextual navegable usado para software GNU, y ``páginas de +manual'' (o ``páginas man''), la documentación lineal encontrada +tradicionalmente en Unix. Se accede a los manuales Info con la orden +@command{info} o con Emacs, y las páginas man con @command{man}. + +Puede buscar documentación de software instalado en su sistema por palabras +clave. Por ejemplo, la siguiente orden busca información sobre ``TLS'' en +manuales Info: + +@example +$ info -k TLS +"(emacs)Network Security" -- STARTTLS +"(emacs)Network Security" -- TLS +"(gnutls)Core TLS API" -- gnutls_certificate_set_verify_flags +"(gnutls)Core TLS API" -- gnutls_certificate_set_verify_function +@dots{} +@end example + +@noindent +La orden siguiente busca por la misma palabra clave en páginas man: + +@example +$ man -k TLS +SSL (7) - OpenSSL SSL/TLS library +certtool (1) - GnuTLS certificate tool +@dots {} +@end example + +Estas búsquedas son completamente locales en su máquina de modo que tiene la +garantía de que la documentación que encuentre corresponde con lo que está +realmente instalado, puede acceder a ella sin conexión a la red, y se +respeta su privacidad. + +Una vez tenga estos resultados, puede ver la documentación relevante +mediante la ejecución de, digamos: + +@example +$ info "(gnutls)Core TLS API" +@end example + +@noindent +o: + +@example +$ man certtool +@end example + +Los manuales Info contienen secciones e índices, así como enlaces como +aquellos encontrados en páginas Web. El lector @command{info} (@pxref{Top, +Info reader,, info-stnd, Stand-alone GNU Info}) y su contraparte en Emacs +(@pxref{Misc Help,,, emacs, The GNU Emacs Manual}) proporcionan +combinaciones de teclas intuitivas para la navegación en los +manuales. @xref{Getting Started,,, info, Info: An Introduction}, para una +introducción a la navegación en Info. + +@node Instalación de ficheros de depuración +@chapter Instalación de ficheros de depuración + +@cindex ficheros de depuración +Los programas binarios, como los producidos por los compiladores GCC por +ejemplo, se escriben típicamente en el formato ELF, con una sección que +contiene @dfn{información de depuración}. La información de depuración es lo +que permite que el depurador, GDB, asocie código binario a código fuente; es +necesaria para depurar un programa compilado en condiciones adecuadas. + +El problema con la información de depuración es que ocupa un espacio +considerable en el disco. Por ejemplo, la información de depuración de la +biblioteca C de GNU ocupa más de 60 MiB. Por tanto, como usuaria, mantener +toda la información de depuración de todos los programas instalados no es +habitualmente una opción. No obstante, el ahorro de espacio no debe ser +impedir la depuración---especialmente en el sistema GNU, que debería +facilitar a sus usuarias ejercitar su libertad de computación (@pxref{Distribución GNU}). + +Afortunadamente, las utilidades binarias GNU (Binutils) y GDB proporcionan +un mecanismo que permite a las usuarias obtener lo mejor de ambos mundos: la +información de depuración puede extraerse de los binarios y almacenarse en +ficheros separados. GDB es capaz entonces de cargar la información de +depuración desde esos ficheros, cuando estén disponibles (@pxref{Separate +Debug Files,,, gdb, Debugging with GDB}). + +La distribución GNU toma ventaja de este hecho almacenando la información de +depuración en el subdirectorio @code{lib/debug} de una salida separada del +paquete llamada @code{debug} (@pxref{Paquetes con múltiples salidas}). Las +usuarias pueden elegir si instalan la salida @code{debug} de un paquete +cuando la necesitan. Por ejemplo, la siguiente orden instala la información +de depuración para la biblioteca C de GNU y para GNU Guile. + +@example +guix package -i glibc:debug guile:debug +@end example + +Se debe decir entonces a GDB que busque los ficheros de depuración en el +perfil de la usuaria, proporcionando un valor a la variable +@code{debug-file-directory} (considere hacerlo en el fichero +@file{~/.gdbinit}, @pxref{Startup,,, gdb, Debugging with GDB}): + +@example +(gdb) set debug-file-directory ~/.guix-profile/lib/debug +@end example + +A partir de ese momento GDB obtendrá la información de depuración de los +ficheros @code{.debug} bajo @file{~/.guix-profile/lib/debug}. + +Además, probablemente desee que GDB sea capaz de mostrar el código fuente +que está depurando. Para hacerlo, tiene que desempaquetar el código fuente +del paquete de su interés (obtenido con @code{guix build --source}, +@pxref{Invocación de guix build}) e indicar a GDB cual es el directorio de +fuentes mediante el uso de la orden @code{directory} (@pxref{Source Path, +@code{directory},, gdb, Debugging with GDB}). + +@c XXX: keep me up-to-date +El mecanismo de la salida @code{debug} en Guix se implementa por el sistema +de construcción @code{gnu-build-system} (@pxref{Sistemas de construcción}). Ahora mismo +necesita una activación explícita---la información de depuración está +disponible únicamente para paquetes con definiciones que declaren +explícitamente una salida @code{debug}. Esto puede cambiarse por una +activación implícita en el futuro si nuestras granjas de construcción pueden +soportar la carga. Para comprobar si un paquete tiene una salida +@code{debug}, use @command{guix package --list-available} (@pxref{Invocación de guix package}). + + +@node Actualizaciones de seguridad +@chapter Actualizaciones de seguridad + +@cindex actualizaciones de seguridad +@cindex vulnerabilidades de seguridad +De manera ocasional, vulnerabilidades importantes de seguridad se descubren +en los paquetes de software y deben parchearse. Las desarrolladoras de Guix +tratan de seguir las vulnerabilidades conocidas y aplicar parches tan pronto +como sea posible en la rama @code{master} de Guix (todavía no proporcionamos +una rama ``estable'' que contenga únicamente actualizaciones de +seguridad). La herramienta @command{guix lint} ayuda a las desarrolladoras a +encontrar versiones vulnerables de paquetes de software en la distribución: + +@smallexample +$ guix lint -c cve +gnu/packages/base.scm:652:2: glibc@@2.21: probably vulnerable to CVE-2015-1781, CVE-2015-7547 +gnu/packages/gcc.scm:334:2: gcc@@4.9.3: probably vulnerable to CVE-2015-5276 +gnu/packages/image.scm:312:2: openjpeg@@2.1.0: probably vulnerable to CVE-2016-1923, CVE-2016-1924 +@dots{} +@end smallexample + +@xref{Invocación de guix lint}, para más información. + +@quotation Nota +En la versión @value{VERSION}, esta característica descrita a continuación +se considera en estado ``beta''. +@end quotation + +Guix sigue una disciplina funcional de gestión de paquetes +(@pxref{Introducción}), lo que implica que, cuando se cambia un paquete, +@emph{todos los paquetes que dependen de él} deben ser reconstruidos. Esto +puede ralentizar de manera significativa el despliegue de correcciones en +paquetes básicos como libc o Bash, ya que básicamente la distribución al +completo debe reconstruirse. El uso de binarios preconstruidos ayuda +(@pxref{Sustituciones}), pero el despliegue aún puede tomar más tiempo del +deseado. + +@cindex injertos (grafts en inglés) +Para afrontar esto, Guix implementa @dfn{injertos}, un mecanismo que permite +un rápido despliegue de actualizaciones críticas sin los costes asociados +con una reconstrucción completa de la distribución. La idea es reconstruir +únicamente el paquete que hace falta parchear, y entonces ``injertarlo'' en +los paquetes explícitamente instalados por la usuaria y que previamente +hacían referencia al paquete original. El coste de realizar un injerto es +menor que una reconstrucción completa de la cadena de dependencias. + +@cindex reemplazos de paquetes, para injertos +For instance, suppose a security update needs to be applied to Bash. Guix +developers will provide a package definition for the ``fixed'' Bash, say +@code{bash-fixed}, in the usual way (@pxref{Definición de paquetes}). Then, the +original package definition is augmented with a @code{replacement} field +pointing to the package containing the bug fix: + +@example +(define bash + (package + (name "bash") + ;; @dots{} + (replacement bash-fixed))) +@end example + +From there on, any package depending directly or indirectly on Bash---as +reported by @command{guix gc --requisites} (@pxref{Invocación de guix gc})---that +is installed is automatically ``rewritten'' to refer to @code{bash-fixed} +instead of @code{bash}. This grafting process takes time proportional to +the size of the package, usually less than a minute for an ``average'' +package on a recent machine. Grafting is recursive: when an indirect +dependency requires grafting, then grafting ``propagates'' up to the package +that the user is installing. + +Currently, the length of the name and version of the graft and that of the +package it replaces (@code{bash-fixed} and @code{bash} in the example above) +must be equal. This restriction mostly comes from the fact that grafting +works by patching files, including binary files, directly. Other +restrictions may apply: for instance, when adding a graft to a package +providing a shared library, the original shared library and its replacement +must have the same @code{SONAME} and be binary-compatible. + +La opción de línea de órdenes @option{--no-grafts} le permite anular +voluntariamente el proceso de injerto (@pxref{Opciones comunes de construcción, +@option{--no-grafts}}). Por tanto, la orden: + +@example +guix build bash --no-grafts +@end example + +@noindent +devuelve el nombre de fichero del almacén de la versión original de Bash, +mientras que: + +@example +guix build bash +@end example + +@noindent +devuelve el nombre de fichero del almacén de la versión ``corregida'', +reemplazo de Bash. Esto le permite distinguir entre las dos variantes de +Bash. + +Para verificar a qué Bash hace referencia su perfil al completo, puede +ejecutar (@pxref{Invocación de guix gc}): + +@example +guix gc -R `readlink -f ~/.guix-profile` | grep bash +@end example + +@noindent +@dots{} y compare los nombres de fichero del almacén que obtendrá con los +ejemplos previos. Del mismo modo, para una generación completa del sistema +Guix: + +@example +guix gc -R `guix system build mi-configuracion.scm` | grep bash +@end example + +Por último, para comprobar qué versión de Bash están usando los procesos en +ejecución, puede usar la orden @command{lsof}: + +@example +lsof | grep /gnu/store/.*bash +@end example + + +@node Lanzamiento inicial +@chapter Lanzamiento inicial + +@c Adapted from the ELS 2013 paper. + +@cindex lanzamiento inicial + +El lanzamiento inicial en nuestro contexto hace referencia a cómo la +distribución se construye ``de la nada''. Recuerde que el entorno de +construcción de una derivación no contiene más que sus entradas declaradas +(@pxref{Introducción}). Por lo que hay un evidente problema ``del huevo y la +gallina'': ¿cómo se construye el primer paquete? ¿Cómo se compila el primer +compilador? Fíjese que esta es una cuestión de interés únicamente para la +hacker curiosa, no para la usuaria normal, así que puede pasar por encima +está sección sin ninguna vergüenza si se considera una ``usuaria normal''. + +@cindex binarios del lanzamiento inicial +El sistema GNU está compuesto principalmente de código C, con libc en su +base. El sistema de construcción GNU en sí asume la disponibilidad del shell +Bourne y las herramientas de línea de órdenes proporcionadas por GNU +Coreutils, Awk, Findutils, `sed' y `grep'. Además, los programas de +construcción---programas que ejecutan @code{./configure}, @code{make}, +etc.---están escritos en Scheme Guile +(@pxref{Derivaciones}). Consecuentemente, para ser capaz de construir +cualquier cosa, desde cero, Guix depende en binarios preconstruidos de +Guile, GCC, Binutils, libc y otros paquetes mencionados anteriormente---los +@dfn{binarios del lanzamiento inicial}. + +Estos binarios del lanzamiento inicial se ``dan por supuestos'', aunque se +pueden volver a crear si se necesita (más sobre esto más adelante). + +@unnumberedsec Preparación para usar los binarios del lanzamiento inicial + +@c As of Emacs 24.3, Info-mode displays the image, but since it's a +@c large image, it's hard to scroll. Oh well. +@image{images/bootstrap-graph,6in,,Grafo de dependencias de las derivaciones +del lanzamiento inicial temprano} + +La figura previa muestra el auténtico inicio del grafo de dependencias de la +distribución, correspondiente a las definiciones de paquete del módulo +@code{(gnu packages bootstrap)}. Un gráfico similar puede generarse con +@command{guix graph} (@pxref{Invocación de guix graph}), más o menos así: + +@example +guix graph -t derivation \ + -e '(@@@@ (gnu packages bootstrap) %bootstrap-gcc)' \ + | dot -Tps > t.ps +@end example + +En este nivel de detalle, las cosas son ligeramente complejas. Primero, +Guile en sí consiste en un ejecutable ELF, junto a muchas fuentes y ficheros +compilados Scheme que se cargan dinámicamente durante la ejecución. Esto se +almacena en el archivador tar @file{guile-2.0.7.tar.xz} mostrado en este +grafo. Este archivador es parte de la distribución de ``fuentes'' de Guix, y +se inserta en el almacén con @code{add-to-store} (@pxref{El almacén}). + +¿Pero cómo escribimos una derivación que extraiga este archivador y lo añada +al almacén? Para resolver este problema, la derivación +@code{guile-bootstrap-2.0.drv}---la primera en construirse---usa @code{bash} +como su constructor, que ejecuta @code{build-bootstrap-guile.sh}, que a su +vez llama a @code{tar} para extraer el archivador. Por tanto, @file{bash}, +@file{tar}, @file{xz} y @file{mkdir} son binarios enlazados estáticamente, +también parte de la distribución de fuentes de Guix, cuyo único propósito es +permitir la extracción del archivador de Guile. + +Una vez que@code{guile-bootstrap-2.0.drv} se ha construido, tenemos un Guile +funcional que se puede usar para ejecutar los programas de construcción +siguientes. Su primera tarea es descargar los archivadores qu contienen los +otros binarios preconstruidos---esto es lo que las derivaciones +@code{.tar.xz.drv} hacen. Módulos Guix como @code{ftp-client.scm} se usan +para este propósito. Las derivaciones @code{module-import.drv} importan esos +módulos en un directorio del almacén, manteniendo la distribución de +carpetas. Las derivaciones @code{module-import-compiled.drv} compilan esos +módulos, y los escriben en un directorio con la distribución de carpetas +correcta. Esto corresponde al parámetro @code{#:modules} de +@code{build-expression->derivation} (@pxref{Derivaciones}). + +Finalmente, los archivadores tar son extraídos por las derivaciones +@code{gcc-bootstrap-0.drv}, @code{glibc-bootstrap-0.drv}, etcétera, hasta el +punto en el que disponemos de una cadena de herramientas C funcional. + + +@unnumberedsec Construcción de las herramientas de construcción + +El lanzamiento inicial está completo cuando tenemos una cadena de +herramientas completa que no depende en las herramientas preconstruidas del +lanzamiento inicial descritas previamente. Este requisito de no-dependencia +se verifica comprobando si los ficheros de la cadena de herramientas final +contienen referencias a directorios de @file{/gnu/store} de las entradas del +lanzamiento. El proceso que lleva a esta cadena de herramientas ``final'' es +descrito por las definiciones de paquetes encontradas en el módulo +@code{(gnu packages commencement)}. + +La orden @command{guix graph} nos permite ``distanciarnos'' en comparación +con el grafo previo, mirando al nivel de objetos de paquetes en vez de +derivaciones individuales---recuerde que un paquete puede traducirse en +varias derivaciones, típicamente una derivación para descargar sus fuentes, +una para construir los módulos Guile que necesita y uno para realmente +construir el paquete de las fuentes. La orden: + +@example +guix graph -t bag \ + -e '(@@@@ (gnu packages commencement) + glibc-final-with-bootstrap-bash)' | dot -Tps > t.ps +@end example + +@noindent +produce el grafo de dependencias que lleva a la biblioteca C +``final''@footnote{Puede haberse dado cuenta de la etiqueta +@code{glibc-intermediate}, sugiriendo que no es @emph{completamente} final, +pero como es una buena aproximación, la consideraremos final}, mostrado a +continuación. + +@image{images/bootstrap-packages,6in,,Grafo de dependencias de los primeros +paquetes} + +@c See <http://lists.gnu.org/archive/html/gnu-system-discuss/2012-10/msg00000.html>. +La primera herramienta que se construye con los binarios del lanzamiento +inicial es GNU@tie{}Make---marcado como @code{make-boot0} en el grafo---, +que es un pre-requisito para todos los paquetes siguientes. Una vez hecho se +construyen Findutils y Diffutils. + +Después viene la primera fase de Binutils y GCC, construidas como +herramientas pseudo-cruzadas---es decir, con @code{--target} igual a +@code{--host}. Se usan para construir libc. Gracias a este truco de +compilación cruzada, se garantiza que esta libc no tendrá ninguna referencia +a la cadena de herramientas inicial. + +Posteriormente se construyen las herramientas Binutils y GCC (no mostradas +previamente) finales, y enlazan los programas contra la libc recién +construía. Esta cadena de herramientas se usa para construir otros paquetes +usados por Guix y el sistema de construcción GNU: Guile, Bash, Coreutils, +etc. + +¡Y voilà! En este punto tenemos un conjunto completo de herramientas de +construcción esperadas por el sistema de construcción GNU. Están en la +variable @code{%final-inputs} del módulo @code{(gnu packages commencement)}, +y se usan implícitamente por cualquier paquete que use +@code{gnu-build-system} (@pxref{Sistemas de construcción, @code{gnu-build-system}}). + + +@unnumberedsec Construir los binarios de lanzamiento + +@cindex binarios del lanzamiento inicial +Debido a que la cadena de herramientas final no depende de los binarios de +lanzamiento, estos rara vez necesitan ser actualizados. No obstante, es útil +tener una forma automatizada de producirlos en caso de que se dé una +actualización, y esto es lo que proporciona el módulo @code{(gnu packages +make-bootstrap)}. + +La siguiente orden construye los archivadores que contienen los binarios de +lanzamiento (Guile, Binutils, GCC, libc, y un archivador que contiene una +mezcla de Coreutils y otras herramientas básicas de línea de órdenes): + +@example +guix build bootstrap-tarballs +@end example + +Los archivadores generados son aquellos que son referenciados en el módulo +@code{(gnu packages bootstrap)} mencionado al inicio de esta sección. + +¿Todavía aquí? Entonces quizá se habrá empezado a preguntar: ¿cuándo +llegamos a un punto fijo? ¡Esa es una pregunta interesante! La respuesta es +desconocida, pero si pudiese investigar más a fondo (y tiene unos recursos +computacionales y de almacenamiento significativos para hacerlo) háganoslo +saber. + +@unnumberedsec Reducción del conjunto de binarios de lanzamiento + +Nuestros binarios de lanzamiento actualmente incluyen GCC, Guile, etc. ¡Eso +es un montón de código binario! ¿Por qué es eso un problema? Es un problema +porque esos chorros de código binario no son auditables en la práctica, lo +que hace difícil establecer qué código fuente los produjo. Cada binario +no-auditable también nos deja vulnerables a puertas traseras en los +compiladores, como describió Ken Thompson en su publicación de 1984 +@emph{Reflections on Trusting Trust}. + +Esto se mitiga por el hecho de que nuestros binarios de lanzamiento fueron +generados por una revisión anterior de Guix. No obstante, esto no posee el +nivel de transparencia que obtenemos en el resto del grado de dependencias +de los paquetes, donde Guix siempre nos da una asociación de +fuente-a-binario. Por lo tanto, nuestro objetivo es reducir el conjunto de +binarios de lanzamiento al mínimo posible. + +El @uref{http://bootstrappable.org, sitio web Bootstrappable.org} enumera +proyectos en activo realizándolo. Uno de ellos está a punto de sustituir el +GCC de lanzamiento con una secuencia de ensambladores, interpretes y +compiladores de complejidad incremental, que pueden ser construidos desde +las fuentes empezando con un código ensamblador simple y auditable. ¡Su +ayuda es bienvenida! + + +@node Transportar +@chapter Transportar a una nueva plataforma + +Como se explicó previamente, la distribución GNU es autocontenida, lo cual +se consigue dependiendo de unos ``binarios del lanzamiento inicial'' +preconstruidos (@pxref{Lanzamiento inicial}). Estos binarios son específicos para +un núcleo del sistema operativo, arquitectura de la CPU e interfaz binaria +de aplicaciones (ABI). Por tanto, para transportar la distribución a una +nueva plataforma que no está soportada todavía, se deben construir estos +binarios del lanzamiento inicial, y actualizar el módulo @code{(gnu packages +bootstrap)} para usarlos en dicha plataforma. + +Por suerte, Guix puede @emph{compilar de forma cruzada} esos binarios del +lanzamiento inicial. Cuando todo va bien, y asumiendo que la cadena de +herramientas GNU soporta para la plataforma deseada, esto puede ser tan +simple como ejecutar una orden así: + +@example +guix build --target=armv5tel-linux-gnueabi bootstrap-tarballs +@end example + +Para que esto funcione, el procedimiento @code{glibc-dynamic-linker} en +@code{(gnu packages bootstrap)} debe aumentarse para devolver el nombre de +fichero correcto para el enlazador dinámico de libc en dicha plataforma; de +igual manera, @code{system->linux-architecture} en @code{(gnu packages +linux)} debe modificarse para la nueva plataforma. + +Una vez construidos, el módulo @code{(gnu packages bootstrap)} debe ser +actualizado para hacer referencia a estos binarios en la plataforma +deseada. Esto es, los hash y las URL de los archivadores del lanzamiento +inicial de la nueva plataforma deben añadirse junto a aquellos de las +plataformas disponibles actualmente. El archivador tar del Guile usado para +el lanzamiento inicial se trata de forma especial: se espera que esté +disponible localmente, y @file{gnu/local.mk} tiene reglas que lo descargan +para las arquitecturas disponibles; se debe añadir una regla para la nueva +plataforma también. + +En la práctica puede haber algunas complicaciones. Primero, puede ser que la +tripleta extendida GNU que especifica un ABI (como el sufijo @code{eabi} +previamente) no es reconocida por todas las herramientas GNU. Típicamente, +glibc reconoce algunas de ellas, mientras que GCC usa una opción de +configuración extra @code{--with-abi} (vea @code{gcc.scm} para ejemplos de +como manejar este caso). En segundo lugar, algunos de los paquetes +necesarios pueden fallar en su construcción para dicha plataforma. Por +último, los binarios generados pueden estar defectuosos por alguna razón. + +@c ********************************************************************* +@include contributing.es.texi + +@c ********************************************************************* +@node Reconocimientos +@chapter Reconocimientos + +Guix está basado en el @uref{http://nixops.org/nix, gestor de paquetes Nix}, +que fue diseñado e implementado por Eelco Dolstra, con contribuciones de +otra gente (véase el fichero @file{nix/AUTHORS} en Guix). Nix fue pionero en +la gestión de paquetes funcional, y promovió características sin +precedentes, como las actualizaciones de paquetes transaccionales y vuelta +atrás, perfiles por usuaria y un proceso de compilación referencialmente +transparente. Sin este trabajo, Guix no existiría. + +Las distribuciones de software basadas en Nix, Nixpkgs y NixOS, también han +sido una inspiración para Guix. + +GNU@tie{}Guix en sí es un trabajo colectivo con contribuciones de un número +de gente. Mire el fichero @file{AUTHORS} en Guix para más información sobre +esa gente maja. El fichero @file{THANKS} enumera personas que han ayudado +informando de errores, haciendose cargo de la infraestructura, +proporcionando arte y temas, haciendo sugerencias, y más---¡gracias! + + +@c ********************************************************************* +@node Licencia de documentación libre GNU +@appendix Licencia de documentación libre GNU +@cindex licencia, GNU Free Documentation License +@include fdl-1.3.texi + +@c ********************************************************************* +@node Índice de conceptos +@unnumbered Índice de conceptos +@printindex cp + +@node Índice programático +@unnumbered Índice programático +@syncodeindex tp fn +@syncodeindex vr fn +@printindex fn + +@bye + +@c Local Variables: +@c ispell-local-dictionary: "american"; +@c End: |