\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.pt_BR.info
@documentencoding UTF-8
@documentlanguage pt_BR
@frenchspacing on
@settitle Manual de referência do GNU Guix
@c %**end of header

@include version-pt_BR.texi

@c Identifier of the OpenPGP key used to sign tarballs and such.
@set OPENPGP-SIGNING-KEY-ID 3CE464558A84FDC69DB40CFB090B11993D9AEBB5
@set OPENPGP-SIGNING-KEY-URL https://sv.gnu.org/people/viewgpg.php?user_id=15145

@c Base URL for downloads.
@set BASE-URL https://ftpmirror.gnu.org/gnu/guix

@c The official substitute server used by default.
@set SUBSTITUTE-SERVER-1 bordeaux.guix.gnu.org
@set SUBSTITUTE-SERVER-2 ci.guix.gnu.org
@set SUBSTITUTE-URLS https://@value{SUBSTITUTE-SERVER-1} https://@value{SUBSTITUTE-SERVER-2}

@copying
Copyright @copyright{} 2012--2025 Ludovic Courtès@* Copyright @copyright{}
2013, 2014, 2016, 2024 Andreas Enge@* Copyright @copyright{} 2013 Nikita
Karetnikov@* Copyright @copyright{} 2014, 2015, 2016 Alex Kost@* Copyright
@copyright{} 2015, 2016 Mathieu Lirzin@* Copyright @copyright{} 2014
Pierre-Antoine Rault@* Copyright @copyright{} 2015 Taylan Ulrich
Bayırlı/Kammer@* Copyright @copyright{} 2015, 2016, 2017, 2019, 2020, 2021,
2023, 2025 Leo Famulari@* Copyright @copyright{} 2015, 2016, 2017, 2018,
2019, 2020, 2021, 2022, 2023 Ricardo Wurmus@* Copyright @copyright{} 2016
Ben Woodcroft@* Copyright @copyright{} 2016, 2017, 2018, 2021 Chris
Marusich@* Copyright @copyright{} 2016, 2017, 2018, 2019, 2020, 2021, 2022,
2023, 2025 Efraim Flashner@* Copyright @copyright{} 2016 John Darrington@*
Copyright @copyright{} 2016, 2017 Nikita Gillmann@* Copyright @copyright{}
2016, 2017, 2018, 2019, 2020, 2021, 2022, 2023, 2024, 2025 Janneke
Nieuwenhuizen@* Copyright @copyright{} 2016, 2017, 2018, 2019, 2020, 2021
Julien Lepiller@* Copyright @copyright{} 2016 Alex ter Weele@* Copyright
@copyright{} 2016, 2017, 2018, 2019, 2020, 2021 Christopher Baines@*
Copyright @copyright{} 2017, 2018, 2019 Clément Lassieur@* Copyright
@copyright{} 2017, 2018, 2020, 2021, 2022 Mathieu Othacehe@* Copyright
@copyright{} 2017 Federico Beffa@* Copyright @copyright{} 2017, 2018, 2024,
2025 Carlo Zancanaro@* Copyright @copyright{} 2017 Thomas Danckaert@*
Copyright @copyright{} 2017 humanitiesNerd@* Copyright @copyright{} 2017,
2021 Christine Lemmer-Webber@* Copyright @copyright{} 2017, 2018, 2019,
2020, 2021, 2022 Marius Bakke@* Copyright @copyright{} 2017, 2019, 2020,
2022 Hartmut Goebel@* Copyright @copyright{} 2017, 2019--2025 Maxim
Cournoyer@* Copyright @copyright{} 2017–2022 Tobias Geerinckx-Rice@*
Copyright @copyright{} 2017 George Clemmer@* Copyright @copyright{} 2017
Andy Wingo@* Copyright @copyright{} 2017, 2018, 2019, 2020, 2023, 2024, 2025
Arun Isaac@* Copyright @copyright{} 2017 nee@* Copyright @copyright{} 2018
Rutger Helling@* Copyright @copyright{} 2018, 2021, 2023, 2025 Oleg
Pykhalov@* Copyright @copyright{} 2018 Mike Gerwitz@* Copyright @copyright{}
2018 Pierre-Antoine Rouby@* Copyright @copyright{} 2018, 2019 Gábor
Boskovits@* Copyright @copyright{} 2018, 2019, 2020, 2022, 2023, 2024
Florian Pelz@* Copyright @copyright{} 2018 Laura Lazzati@* Copyright
@copyright{} 2018 Alex Vong@* Copyright @copyright{} 2019 Josh Holland@*
Copyright @copyright{} 2019, 2020 Diego Nicola Barbato@* Copyright
@copyright{} 2019 Ivan Petkov@* Copyright @copyright{} 2019 Jakob
L. Kreuze@* Copyright @copyright{} 2019 Kyle Andrews@* Copyright
@copyright{} 2019 Alex Griffin@* Copyright @copyright{} 2019, 2020, 2021,
2022 Guillaume Le Vaillant@* Copyright @copyright{} 2020 Liliana Marie
Prikler@* Copyright @copyright{} 2019, 2020, 2021, 2022, 2023 Simon
Tournier@* Copyright @copyright{} 2020 Wiktor Żelazny@* Copyright
@copyright{} 2020 Damien Cassou@* Copyright @copyright{} 2020 Jakub
Kądziołka@* Copyright @copyright{} 2020 Jack Hill@* Copyright @copyright{}
2020 Naga Malleswari@* Copyright @copyright{} 2020, 2021 Brice Waegeneire@*
Copyright @copyright{} 2020 R Veera Kumar@* Copyright @copyright{} 2020,
2021, 2022 Pierre Langlois@* Copyright @copyright{} 2020 pinoaffe@*
Copyright @copyright{} 2020, 2023 André Batista@* Copyright @copyright{}
2020, 2021 Alexandru-Sergiu Marton@* Copyright @copyright{} 2020 raingloom@*
Copyright @copyright{} 2020 Daniel Brooks@* Copyright @copyright{} 2020 John
Soo@* Copyright @copyright{} 2020 Jonathan Brielmaier@* Copyright
@copyright{} 2020 Edgar Vincent@* Copyright @copyright{} 2021, 2022 Maxime
Devos@* Copyright @copyright{} 2021 B. Wilson@* Copyright @copyright{} 2021
Xinglu Chen@* Copyright @copyright{} 2021 Raghav Gururajan@* Copyright
@copyright{} 2021 Domagoj Stolfa@* Copyright @copyright{} 2021 Hui Lu@*
Copyright @copyright{} 2021 pukkamustard@* Copyright @copyright{} 2021 Alice
Brenon@* Copyright @copyright{} 2021-2023 Josselin Poiret@* Copyright
@copyright{} 2021, 2023 muradm@* Copyright @copyright{} 2021, 2022 Andrew
Tropin@* Copyright @copyright{} 2021 Sarah Morgensen@* Copyright
@copyright{} 2022 Remco van 't Veer@* Copyright @copyright{} 2022 Aleksandr
Vityazev@* Copyright @copyright{} 2022 Philip M@sup{c}Grath@* Copyright
@copyright{} 2022 Karl Hallsby@* Copyright @copyright{} 2022 Justin
Veilleux@* Copyright @copyright{} 2022 Reily Siegel@* Copyright @copyright{}
2022 Simon Streit@* Copyright @copyright{} 2022 (@* Copyright @copyright{}
2022 John Kehayias@* Copyright @copyright{} 2022⁠–⁠2023 Bruno Victal@*
Copyright @copyright{} 2022 Ivan Vilata-i-Balaguer@* Copyright @copyright{}
2023-2025 Giacomo Leidi@* Copyright @copyright{} 2022 Antero Mejr@*
Copyright @copyright{} 2023 Karl Hallsby@* Copyright @copyright{} 2023
Nathaniel Nicandro@* Copyright @copyright{} 2023 Tanguy Le Carrour@*
Copyright @copyright{} 2023-2024 Zheng Junjie@* Copyright @copyright{} 2023
Brian Cully@* Copyright @copyright{} 2023 Felix Lechner@* Copyright
@copyright{} 2023 Foundation Devices, Inc.@* Copyright @copyright{} 2023
Thomas Ieong@* Copyright @copyright{} 2023 Saku Laesvuori@* Copyright
@copyright{} 2023 Graham James Addis@* Copyright @copyright{} 2023-2025
Tomas Volf@* Copyright @copyright{} 2024, 2025 Herman Rimm@* Copyright
@copyright{} 2024 Matthew Trzcinski@* Copyright @copyright{} 2024 Richard
Sent@* Copyright @copyright{} 2024 Dariqq@* Copyright @copyright{} 2024
Denis 'GNUtoo' Carikli@* Copyright @copyright{} 2024 Fabio Natali@*
Copyright @copyright{} 2024 Arnaud Daby-Seesaram@* Copyright @copyright{}
2024-2025 Nigko Yerden@* Copyright @copyright{} 2024 Troy Figiel@* Copyright
@copyright{} 2024 Sharlatan Hellseher@* Copyright @copyright{} 2024 45mg@*
Copyright @copyright{} 2024 Greg Hogan@* Copyright @copyright{} 2025 Sören
Tempel@* Copyright @copyright{} 2025 Rostislav Svoboda@* Copyright
@copyright{} 2025 Zacchaeus@* Copyright @copyright{} 2025 Sergio Pastor
Pérez@* Copyright @copyright{} 2024 Evgeny Pisemsky@* Copyright @copyright{}
2025 jgart@* Copyright @copyright{} 2025 Artur Wroblewski@* Copyright
@copyright{} 2025 Edouard Klein@* Copyright @copyright{} 2025 Rodion
Goritskov@* Copyright @copyright{} 2025 dan@* Copyright @copyright{} 2025
Noé Lopez@*

Permissão concedida para copiar, distribuir e/ou modificar este documento
sob os termos da Licença de Documentação Livre GNU, Versão 1.3 ou qualquer
versão mais recente publicada pela Free Software Foundation; sem Seções
Invariantes, Textos de Capa Frontal, e sem Textos de Contracapa. Uma cópia
da licença está incluída na seção intitulada ``GNU Free Documentation
License''.
@end copying

@dircategory Administração do sistema
@direntry
* Guix.pt_BR: (guix.pt_BR).  Gerencie softwares instalados e configuração do 
                               sistema.
* guix package: (guix.pt_BR)Invocando guix package.  Instalando, removendo e 
                                                       atualizando pacotes.
* guix gc: (guix.pt_BR)Invocando guix gc.  Recuperando espaço em disco não 
                                             utilizado.
* guix pull: (guix.pt_BR)Invocando guix pull.  Atualize a lista de pacotes 
                                                 disponíveis.
* guix system: (guix.pt_BR)Invocando guix system.  Gerencie a configuração 
                                                     do sistema operacional.
* guix deploy: (guix.pt_BR)Invocando guix deploy.  Gerenciar configurações 
                                                     do sistema operacional 
                                                     para hosts remotos.
@end direntry

@dircategory Desenvolvimento de software
@direntry
* guix shell: (guix.pt_BR)Invocando guix shell.  Creating software 
                                                   environments.
* guix environment: (guix.pt_BR)Invocando guix environment.  Compilando 
                                                               ambientes de 
                                                               desenvolvimento 
                                                               com Guix.
* guix build: (guix.pt_BR)Invocando guix build.  Compilando pacotes.
* guix pack: (guix.pt_BR)Invocando guix pack.  Criando embalagens de 
                                                 binários.
@end direntry

@titlepage
@title Manual de referência do GNU Guix
@subtitle Usando o Gerenciador de Pacotes Funcional GNU Guix
@author Desenvolvedores do GNU Guix

@page
@vskip 0pt plus 1filll
Edição @value{EDITION} @* @value{UPDATED} @*

@insertcopying
@end titlepage

@contents

@c *********************************************************************
@node Top
@top GNU Guix

Esse documento descreve Guix versão @value{VERSION}, uma ferramenta de
gerenciamento de pacotes funcional escrita para o 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 também está disponível em inglês (@pxref{Top,,, guix, GNU Guix
Reference Manual}), chinês simplificado (@pxref{Top ,,, guix.zh_CN, GNU
Guix参考手册}), francês (@pxref{Top ,,, guix.fr, Manuel de référence de GNU
Guix}), alemão (@pxref{Top,,, guix.de, Referenzhandbuch zu GNU Guix}),
espanhol (@pxref{Top,,, guix.es, Manual de referencia de GNU Guix}),
italiano (@pxref{Top,,, guix.it, Manuale di riferimento di GNU Guix}) e
russo (@pxref{Top,,, guix.ru, Руководство GNU Guix}). Se você quiser
traduzi-lo para seu idioma nativo, considere participar do
@uref{https://translate.codeberg.org/projects/guix/documentation-manual,
Weblate} (@pxref{Traduzindo o Guix}).

@menu
* Introdução::               Sobre o que é o Guix?
* Instalação::               Instalando o Guix.
* Instalação do sistema::    Instalando todo o sistema operacional.
* Começando::                Seus primeiros passos.
* Gerenciamento de pacote::  Instalação de pacote, atualização, etc.
* Canais::                   Personalizando a coleção de pacotes.
* Desenvolvimento::          Desenvolvimento de software auxiliado pelo 
                               Guix.
* Interface de programação::  Usando o Guix no Scheme.
* Utilitários::              Comandos de gerenciamento de pacote.
* Arquiteturas estrangeiras::  Construir para arquiteturas estrangeiras.
* Configuração do sistema::  Configurando o sistema operacional.
* Dicas para solução de problemas do sistema::  Quando as coisas não saem 
                                                  como planejado.
* Home Configuration::       Configuring the home environment.
* Documentação::             Navegando por manuais do usuário do software.
* Plataformas::              Defining platforms.
* Imagens do sistema::       Creating system images.
* Instalando arquivos de depuração::  Alimentando o depurador.
* Usando TeX e LaTeX::       Typesetting.
* Atualizações de segurança::  Implementando correções de segurança 
                                 rapidamente.
* Inicializando::            GNU/Linux compilado do zero.
* Portando::                 Objetivando outra plataforma ou kernel.
* Contribuindo::             Sua ajuda é necessária!

* Agradecimentos::           Obrigado!
* Licença de Documentação Livre GNU::  A licença deste manual.
* Índice de conceitos::      Conceitos.
* Índice de programação::    Tipos de dados, funções e variáveis.

@detailmenu
 --- A listagem detalhada de nós ---



Introdução



* Gerenciando software do jeito do Guix::  O que há de especial.
* Distribuição GNU::         Os pacotes e as ferramentas.

Instalação



* Instalação de binários::   Faça o Guix funcionar rapidamente!
* Configurando o daemon::    Preparando o ambiente do daemon de compilação.
* Invocando guix-daemon::    Executando o daemon de compilação.
* Configuração de aplicativo::  Configuração específica de aplicativo.
* Atualizando o Guix::       Atualizando o Guix e seu daemon de compilação.

Configurando o daemon



* Configuração do ambiente de compilação::  Preparando o ambiente de 
                                              compilação isolado.
* Configuração de descarregamento de daemon::  Descarregando compilações 
                                                 para máquinas remotas.
* Suporte a SELinux::        Usando um política SELinux para o daemon.

Instalação do sistema



* Limitações::               O que você pode esperar.
* Considerações de hardware::  Hardware suportado.
* Instalação em um pendrive e em DVD::  Preparando a mídia de instalação.
* Preparando para instalação::  Rede, particionamento, etc.
* Instalação gráfica guiada::  Instalação gráfica fácil.
* Instalação manual::        Instalação manual para magos.
* Após a instalação do sistema::  Quando a instalação conclui com sucesso.
* Instalando Guix em uma VM::  Parque de diversões do Guix System.
* Compilando a imagem de instalação::  Como isso vem a ser.

Instalação manual



* Disposição de teclado e rede e particionamento::  Configuração inicial.
* Prosseguindo com a instalação::  Instalando.

Gerenciamento de pacote



* Recursos::                 Como o Guix vai iluminar a sua vida.
* Invocando guix package::   Instalação de pacote, remoção, etc.
* Substitutos::              Baixando binários pré-compilados.
* Pacotes com múltiplas saídas::  Um único pacote de fontes, várias saídas.
* Invocando guix locate::    Localizando pacotes que fornecem um arquivo.
* Invocando guix gc::        Executando o coletor de lixo.
* Invocando guix pull::      Obtendo o Guix mais recente e distribuição.
* Invocando guix time-machine::  Executando uma revisão mais antiga do Guix.
* Inferiores::               Interagindo com outra revisão do Guix.
* Invocando guix describe::  Exibe informações sobre sua revisão do Guix.
* Invocando guix archive::   Exportando e importando arquivos do armazém.

Substitutos



* Official Substitute Servers::  Uma fonte específica de substitutos.
* Autorização de servidor substituto::  Como habilitar ou desabilitar 
                                          substitutos.
* Obtendo substitutos de outros servidores::  Diversidade de substitutos.
* Autenticação de substituto::  Como Guix verifica substitutos.
* Configurações de proxy::   Como obter substitutos via proxy.
* Falha na substituição::    O que acontece quando a substituição falha.
* Confiança em binários::    Como você pode confiar naquele blob binário?

Canais



* Especificando canais adicionais::  Ampliando a coleta de pacotes.
* Usando um canal Guix personalizado::  Usando um Guix personalizado.
* Replicando Guix::          Executando o @emph{exatamente o mesmo} Guix.
* Customizing the System-Wide Guix::  Default channels on Guix System.
* Autenticação de canal::    Como o Guix verifica o que busca.
* Canais com substitutos::   Utilizando canais com substitutos disponíveis.
* Criando um canal::         Como escrever seu canal personalizado.
* Módulos de pacote em um subdiretório::  Especificando a localização dos 
                                            módulos do pacote do canal.
* Declarando dependências de canal::  Como depender de outros canais.
* Especificando autorizações de canal::  Definindo autorizações de autores 
                                           de canais.
* URL principal::            Distinguir o espelho do original.
* Escrevendo notícias do canal::  Comunicar informações aos usuários do 
                                    canal.

Desenvolvimento



* Invocando guix shell::     Spawning one-off software environments.
* Invocando guix environment::  Configurando ambientes de desenvolvimento.
* Invocando guix pack::      Criando embalagens de software.
* A cadeia de ferramentas do GCC::  Trabalhando com idiomas suportados pelo 
                                      GCC.
* Invocando guix git authenticate::  Autenticando repositórios Git.

Interface de programação



* Módulos de pacote::        Pacotes do ponto de vista do programador.
* Definindo pacotes::        Definindo novos pacotes.
* Definindo variantes de pacote::  Personalização de pacotes.
* Escrevendo manifestos::    A lista de materiais do seu ambiente.
* Sistemas de compilação::   Especificando como pacotes são compilados.
* Fases de construção::      Fases do processo de construção de um pacote.
* Construir utilitários::    Auxiliares para suas definições de pacotes e 
                               muito mais.
* Caminhos de pesquisa::     Declaring search path environment variables.
* O armazém::                Manipulação do armazém de pacotes.
* Derivações::               Interface de baixo nível para derivações de 
                               pacotes.
* A mônada do armazém::      Interface puramente funcional para o armazém.
* Expressões-G::             Manipulação de expressões de compilação.
* Invocando guix repl::      Programação Guix em Guile
* Usando Guix interativamente::  Interação de granulação fina no REPL.

Definindo pacotes



* Referência do package::    O tipo de dados package.
* Referência do origin::     O tipo de dados origin.

Utilitários



* Invocando guix build::     Compilando pacotes a partir da linha de 
                               comando.
* Invocando guix edit::      Editando definições de pacote.
* Invocando guix download::  Baixando um arquivo e imprimindo seu hash.
* Invocando guix hash::      Computando a hash criptográfica de um arquivo.
* Invocando guix import::    Importando definições de pacote.
* Invocando guix refresh::   Atualizando definições de pacotes.
* Invocando guix style::     Styling package definitions.
* Invocando guix lint::      Encontrando erros nas definições de pacote.
* Invocando guix size::      Perfilando uso de disco.
* Invocando guix graph::     Visualizando o grafo de pacotes.
* Invocando guix publish::   Compartilhando substitutos.
* Invocando guix challenge::  Desafiando servidores substitutos.
* Invocando guix copy::      Copiando para e de um armazém remoto.
* Invocando guix container::  Isolação de processo.
* Invocando guix weather::   Acessando disponibilidade de substituto.
* Invocando guix processes::  Listando processos do cliente.

Invocando @command{guix build}



* Opções de compilação comuns::  Opções de compilação para a maioria dos 
                                   comandos.
* Opções de transformação de pacote::  Criando variantes de pacotes.
* Opções de compilação adicional::  Opções específicas para "guix build".
* Depurando falhas de compilação::  Experiência de empacotamento na vida 
                                      real.

Arquiteturas estrangeiras



* Compilação cruzada::       Compilação cruzada para outra arquitetura.
* Construções nativas::      Targeting another architecture through native 
                               builds.

Configuração do sistema



* Começando com o Sistema::  Seus primeiros passos.
* Usando o sistema de configuração::  Personalizando seu sistema GNU.
* Referência do operating-system::  Detalhe das declarações do 
                                      operating-system.
* Sistemas de arquivos::     Configurando montagens de sistema de arquivos.
* Dispositivos mapeados::    Processamento extra de dispositivo de bloco.
* Espaço de troca (swap)::   Apoiando a RAM com espaço em disco.
* Contas de usuário::        Especificando contas de usuários.
* Disposição do teclado::    Como o sistema interpreta pressionamento de 
                               teclas.
* Localidades::              Configurações de idioma e de convenção 
                               cultural.
* Serviços::                 Especificando serviços de sistema.
* Privileged Programs::      Programs running with elevated privileges.
* Certificados X.509::       Autenticando servidores HTTPS.
* Name Service Switch::      Configurando name service switch do libc.
* Disco de RAM inicial::     Inicialização do Linux-Libre.
* Configuração do carregador de inicialização::  Configurando o 
                                                   "bootloader".
* Invocando guix system::    Inicializando uma configuração de sistema.
* Invocando guix deploy::    Implantando uma configuração de sistema em um 
                               host remoto.
* Executando Guix em uma VM::  Como executar Guix System em uma máquina 
                                 virtual.
* Definindo serviços::       Adicionando novas definições de serviço.

Sistemas de arquivos



* Sistema de arquivos Btrfs::  Sistema de arquivos Btrfs

Serviços



* Serviços básicos::         Serviços essenciais do sistema.
* Execução de trabalho agendado::  O serviço mcron.
* Rotação de log::           Archiving and deleting old logs.
* Networking Setup::         Configurando interfaces de rede.
* Serviços de Rede::         Firewall, SSH daemon, etc.
* Atualizações sem supervisão::  Atualizações automatizadas do sistema.
* X Window::                 Exibição gráfica.
* Serviços de impressão::    Suporte a impressora local e remota.
* Serviços de desktop::      Serviços de D-Bus e desktop.
* Serviços de som::          Serviços ALSA e Pulseaudio.
* File Search Services::     Ferramentas para procurar arquivos.
* Serviços de bancos de dados::  Banco de dados SQL, armazenamentos de valor 
                                   chave, etc.
* Serviços de correio::      IMAP, POP3, SMTP e tudo isso.
* Serviços de mensageria::   Serviços de mensageria.
* Serviços de telefonia::    Serviços de telefonia.
* Serviços de compartilhamento de arquivos::  Serviços de compartilhamento 
                                                de arquivos.
* Serviços de monitoramento::  Serviços de monitoramento.
* Serviços Kerberos::        Serviços Kerberos.
* Serviços LDAP::            Serviços LDAP.
* Serviços web::             Servidores Web.
* High Availability Services::  High availability services.
* Serviços de certificado::  Certificados TLS via Let's Encrypt.
* Serviços DNS::             Deamons DNS.
* VNC Services::             VNC daemons.
* Serviços VPN::             Deamons VPN.
* Sistema de arquivos de rede::  Serviços relacionados a NFS.
* Samba Services::           Serviços Samba.
* Integração Contínua::      Os serviços Cuirass e Laminar.
* Serviços de gerenciamento de energia::  Extending battery life, etc.
* Serviços de áudio::        O MPD.
* Serviços de virtualização::  Serviços de virtualização.
* Serviços de controlando versão::  Fornecendo acesso remoto a repositórios 
                                      Git.
* Serviços de jogos::        Servidores de jogos.
* Serviço de montagem PAM::  Serviço para montar volumes ao efetuar login.
* Serviços Guix::            Serviços relacionados especificamente ao Guix.
* Serviços Linux::           Serviços vinculados ao kernel Linux.
* Serviços Hurd::            Serviços específicos para um Sistema Hurd.
* Serviços diversos::        Outros serviços.

Definindo serviços



* Composição de serviço::    O modelo para serviços de composição.
* Tipos de Service e Serviços::  Tipos e serviços.
* Referência de Service::    Referência de API.
* Serviços de Shepherd::     Um tipo em particular de serviço.
* Complex Configurations::   Defining bindings for complex configurations.

Dicas para solução de problemas do sistema



* Acessando um sistema existente via chroot::  Acessando um sistema 
                                                 existente via chroot

Home Configuration



* Declarando o ambiente pessoal::  Personalizando seu ambiente pessoal.
* Configurando o "Shell"::   Habilitando o ambiente pessoal.
* Serviços pessoais::        Especificando serviços pessoais.
* Invocando guix home::      Inicializando uma configuração pessoal.

Serviços pessoais



* Serviços essenciais pessoais::  Variáveis de ambiente, pacotes, scripts 
                                    on-*.
* Shells: Shells Home Services.  POSIX shells, Bash, Zsh.
* Mcron: Mcron Home Service.  Execução de trabalho do Usuário agendado.
* Power Management: Power Management Home Services.  Services for battery 
                                                       power.
* Shepherd: Shepherd Home Service.  Managing User's Daemons.
* SSH: Secure Shell.         Configurando o cliente de shell seguro.
* GPG: GNU Privacy Guard.    Configurando GPG e ferramentas relacionadas.
* Desktop: Desktop Home Services.  Serviços para ambientes gráficos.
* Guix: Guix Home Services.  Services for Guix.
* Backup: Backup Home Services.  Services for backing up User's files.
* Fonts: Fonts Home Services.  Services for managing User's fonts.
* Sound: Sound Home Services.  Lidando com áudio.
* Mail: Mail Home Services.  Services for managing mail.
* Messaging: Messaging Home Services.  Services for managing messaging.
* Media: Media Home Services.  Services for managing media.
* Sway: Gerenciador de janelas Sway.  Setting up the Sway configuration.
* Networking: Networking Home Services.  Networking services.
* Secrets: Secrets Home Services.  Services for storing secrets.
* Miscellaneous: Miscellaneous Home Services.  More services.

Plataformas



* Referência do platform::   Detail of platform declarations.
* Supported Platforms::      Description of the supported platforms.

Criando imagens do sistema



* image Reference::          Detail of image declarations.
* Instanciar uma imagem::    Como instanciar um registro de imagem.
* image-type Reference::     Detail of image types declaration.
* Módulos de imagem::        Definição de módulos de imagem.

@code{image} Reference



* Referência do partition::  Referência do partition

Instalando arquivos de depuração



* Informações de depuração separadas::  Instalando saídas de 'depuração'.
* Reconstruindo informações de depuração::  Informações de depuração 
                                              ausentes no edifício.

Inicializando



* Bootstrap de código fonte completo::  Um Bootstrap digno do GNU.
* Preparando para usar os binários do Bootstrap::  Construindo o que mais 
                                                     importa.

@end detailmenu
@end menu

@c *********************************************************************
@node Introdução
@chapter Introdução

@cindex propósito
GNU Guix@footnote{``Guix'' é pronunciado como ``geeks'', ou ``ɡiːks'' usando
o alfabeto fonético internacional (IPA).} é uma ferramenta de gerenciamento
de pacotes e distribuição do sistema GNU. O Guix facilita a instalação, a
atualização ou a remoção de pacotes de software, a reversão para um conjunto
de pacotes anterior, a compilação de pacotes a partir do código-fonte e
geralmente ajuda na criação e manutenção de ambientes de software.

@cindex Sistema Guix
@cindex GuixSD, agora Guix System
@cindex Guix System Distribution, agora Guix System
Você pode instalar o GNU@tie{}Guix sobre um sistema GNU/Linux existente,
onde ele complementa as ferramentas disponíveis sem interferência
(@pxref{Instalação}) ou você pode usá-lo como uma distribuição de sistema
operacional independente, @dfn{Guix@tie{}System}@footnote{Costumávamos nos
referir ao Guix System como ``Guix System Distribution'' ou
``GuixSD''. Agora consideramos que faz mais sentido agrupar tudo sob o
banner ``Guix'', pois, afinal, o Guix System está prontamente disponível
através do comando @command{guix system}, mesmo se você estiver usando uma
distribuição diferente por baixo!}. @xref{Distribuição GNU}.

@menu
* Gerenciando software do jeito do Guix::  O que há de especial.
* Distribuição GNU::         Os pacotes e as ferramentas.
@end menu

@node Gerenciando software do jeito do Guix
@section Gerenciando software do jeito do Guix

@cindex interfaces de usuário
O Guix fornece uma interface de gerenciamento de pacotes de linha de comando
(@pxref{Gerenciamento de pacote}), ferramentas para ajudar no desenvolvimento de
software (@pxref{Desenvolvimento}), utilitários de linha de comando para uso
mais avançado (@pxref{Utilitários}), bem como interfaces de programação Scheme
(@pxref{Interface de programação}).
@cindex build daemon
O @dfn{build daemon} é responsável por compilar pacotes em nome dos usuários
(@pxref{Configurando o daemon}) e por baixar binários pré-compilados de
fontes autorizados (@pxref{Substitutos}).

@cindex extensibilidade da distribuição
@cindex personalização, de pacotes
Guix inclui definições de pacotes para muitos pacotes GNU e não-GNU, todos
os quais @uref{https://www.gnu.org/philosophy/free-sw.html, respeitam a
liberdade de computação do usuário}. É @emph{extensível}: os usuários podem
escrever suas próprias definições de pacotes (@pxref{Definindo pacotes}) e
disponibilizá-los como módulos de pacotes independentes (@pxref{Módulos de pacote}). Também é @emph{personalizável}: os usuários podem @emph{derivar}
definições de pacotes especializados das existentes, incluindo da linha de
comando (@pxref{Opções de transformação de pacote}).

@cindex gerenciamento de pacotes funcional
@cindex isolação
Nos bastidores, a Guix implementa a disciplina @dfn{gerenciamento de pacotes
funcional} pioneira da Nix (@pxref{Agradecimentos}). No Guix, o processo de
compilação e instalação de pacotes é visto como uma @emph{função}, no
sentido matemático. Essa função recebe entradas, como scripts de compilação,
um compilador e bibliotecas, e retorna um pacote instalado. Como uma função
pura, seu resultado depende apenas de suas entradas – por exemplo, não pode
fazer referência a um software ou scripts que não foram explicitamente
passados como entradas. Uma função de compilação sempre produz o mesmo
resultado ao passar por um determinado conjunto de entradas. Não pode
alterar o ambiente do sistema em execução de qualquer forma; por exemplo,
ele não pode criar, modificar ou excluir arquivos fora de seus diretórios de
compilação e instalação. Isto é conseguido através da execução de processos
de compilação em ambientes isolados (ou @dfn{containers}), onde somente suas
entradas explícitas são visíveis.

@cindex store
O resultado das funções de compilação do pacote é mantido (@dfn{cached}) no
sistema de arquivos, em um diretório especial chamado @dfn{armazém}
(@pxref{O armazém}). Cada pacote é instalado em um diretório próprio no
armazém – por padrão, em @file{/gnu/store}. O nome do diretório contém um
hash de todas as entradas usadas para compilar esse pacote; Assim, a
alteração uma entrada gera um nome de diretório diferente.

Essa abordagem é a fundação para os principais recursos do Guix: suporte
para atualização transacional de pacotes e reversão, instalação por usuário
e coleta de lixo de pacotes (@pxref{Recursos}).


@node Distribuição GNU
@section Distribuição GNU

@cindex Sistema Guix
O Guix vem com uma distribuição do sistema GNU que consiste inteiramente de
software livre@footnote{O termo ``free'' em ``free software`` se refere à
@url{https://www.gnu.org/philosophy/free-sw.html,liberdade fornecida aos
usuários desse software}. A ambiguidade no termo em inglês não ocorre na
tradução para português ``livre``.}. A distribuição pode ser instalada por
conta própria (@pxref{Instalação do sistema}), mas também é possível instalar
o Guix como um gerenciador de pacotes em cima de um sistema GNU/Linux
instalado (@pxref{Instalação}). Quando precisamos distinguir entre os
dois, nos referimos à distribuição independente como Guix@tie{}System.

A distribuição fornece pacotes GNU principais, como GNU libc, GCC e
Binutils, além de muitos aplicativos GNU e não GNU. A lista completa de
pacotes disponíveis pode ser acessada
@url{https://www.gnu.org/software/guix/packages,online} ou executando
@command{guix package} (@pxref{Invocando guix package}):

@example
guix package --list-available
@end example

Nosso objetivo é fornecer uma distribuição prática e 100% de software livre,
baseada em Linux e outras variantes do GNU, com foco na promoção e forte
integração de componentes do GNU e ênfase em programas e ferramentas que
ajudam os usuários a exercer essa liberdade.

Os pacotes estão atualmente disponíveis nas seguintes plataformas:

@table @code

@item x86_64-linux
Arquitetura Intel/AMD @code{x86_64}, kernel Linux-Libre.

@item i686-linux
Arquitetura Intel de 32 bits (IA32), kernel Linux-Libre.

@item armhf-linux
Arquitetura ARMv7-A com hard float, Thumb-2 e NEON, usando a interface
binária de aplicativos EABI hard-float (ABI) e o kernel Linux-Libre.

@item aarch64-linux
Processadores ARMv8-A little-endian de 64 bits, kernel Linux-Libre.

@item i586-gnu
@uref{https://hurd.gnu.org, GNU/Hurd} sobre a arquitetura Intel de 32 bits
(IA32).

Esta configuração é experimental e está em desenvolvimento. A maneira mais
fácil de você tentar é configurando uma instância de
@code{hurd-vm-service-type} na sua máquina GNU/Linux
(@pxref{transparent-emulation-qemu,
@code{hurd-vm-service-type}}). @xref{Contribuindo}, sobre como ajudar!

@item x86_64-gnu
@uref{https://hurd.gnu.org, GNU/Hurd} on the @code{x86_64} Intel/AMD 64-bit
architecture.

This configuration is even more experimental and under heavy upstream
development.

@item mips64el-linux (sem suporte)
processadores little-endian MIPS de 64 bits, especificamente a série
Loongson, n32 ABI e kernel Linux-Libre. Esta configuração não é mais
totalmente suportada; em particular, não há trabalho em andamento para
garantir que esta arquitetura ainda funcione. Caso alguém decida que deseja
reviver esta arquitetura, o código ainda estará disponível.

@item powerpc-linux (sem suporte)
processadores PowerPC big-endian de 32 bits, especificamente o PowerPC G4
com suporte AltiVec e kernel Linux-Libre. Esta configuração não é totalmente
suportada e não há trabalho em andamento para garantir que esta arquitetura
funcione.

@item powerpc64le-linux
processadores little-endian 64 bits Power ISA, kernel Linux-Libre. Isso
inclui sistemas POWER9 como o
@uref{https://www.fsf.org/news/talos-ii-mainboard-and-talos-ii-lite-mainboard-now-fsf-certified-to-respect-your-freedom,
placa-mãe RYF Talos II}. Esta plataforma está disponível como uma "prévia de
tecnologia": embora seja suportada, substitutos ainda não estão disponíveis
na fazenda de construção (@pxref{Substitutos}), e alguns pacotes podem
falhar na construção (@pxref{Rastreando Bugs e Mudanças}). Dito isso, a
comunidade Guix está trabalhando ativamente para melhorar esse suporte, e
agora é um ótimo momento para experimentá-lo e se envolver!

@item riscv64-linux
processadores little-endian RISC-V de 64 bits, especificamente RV64GC, e
kernel Linux-Libre. Esta plataforma está disponível como uma "prévia de
tecnologia": embora seja suportada, substitutos ainda não estão disponíveis
na build farm (@pxref{Substitutos}), e alguns pacotes podem falhar na
compilação (@pxref{Rastreando Bugs e Mudanças}). Dito isto, a comunidade Guix
está trabalhando ativamente para melhorar este suporte, e agora é um ótimo
momento para experimentá-lo e se envolver!

@end table

Com o Guix@tie{}System, você @emph{declara} todos os aspectos da
configuração do sistema operacional, e o Guix cuida de instanciar a
configuração de maneira transacional, reproduzível e sem estado
(@pxref{Configuração do sistema}). O Guix System usa o kernel Linux-libre, o
sistema de inicialização Shepherd (@pxref{Introduction ,,, shepherd, The GNU
Shepherd Manual}), os conhecidos utilitários do GNU e cadeia de ferramentas,
bem como o ambiente gráfico ou os serviços de sistema do sua escolha.

Guix System is available on all the above platforms except
@code{mips64el-linux}, @code{powerpc-linux}, @code{powerpc64le-linux} and
@code{riscv64-linux}.

@noindent
Para obter informações sobre como portar para outras arquiteturas ou
kernels, @pxref{Portando}.

A construção desta distribuição é um esforço cooperativo e você está
convidado a participar! @xref{Contribuindo}, para obter informações sobre
como você pode ajudar.


@c *********************************************************************
@node Instalação
@chapter Instalação

@cindex instalando Guix
@cindex distro alheia
@cindex Sistema Guix
Você pode instalar a ferramenta de gerenciamento de pacotes Guix sobre um
sistema GNU/Linux ou GNU/Hurd existente@footnote{O suporte ao Hurd é
atualmente limitado.}, conhecido como @dfn{distro estrangeiro}. Se, em vez
disso, você quiser instalar a distribuição completa e autônoma do sistema
GNU, @dfn{Guix@tie{}System}, @pxref{Instalação do sistema}. Esta seção se
preocupa apenas com a instalação do Guix em uma distro estrangeira.

@quotation Importante
Esta seção se aplica somente a sistemas sem Guix. Segui-la para instalações
Guix existentes sobrescreverá arquivos importantes do sistema.
@end quotation

@cindex diretórios relacionados à distro alheia
Quando instalado sobre uma distro alheia. GNU@tie{}Guix complementa as
ferramentas disponíveis sem interferência. Seus dados residem exclusivamente
em dois diretórios, geralmente @file{/gnu/store} e @file{/var/guix}; outros
arquivos no seu sistema, como @file{/etc}, são deixados intactos.

Uma vez instalado, o Guix pode ser atualizado executando @command{guix pull}
(@pxref{Invocando guix pull}).

@menu
* Instalação de binários::   Faça o Guix funcionar rapidamente!
* Configurando o daemon::    Preparando o ambiente do daemon de compilação.
* Invocando guix-daemon::    Executando o daemon de compilação.
* Configuração de aplicativo::  Configuração específica de aplicativo.
* Atualizando o Guix::       Atualizando o Guix e seu daemon de compilação.
@end menu

@node Instalação de binários
@section Instalação de binários

@cindex instalando Guix de binários
@cindex script de instalação
This section describes how to install Guix from a self-contained tarball
providing binaries for Guix and for all its dependencies.  This is often
quicker than installing from source, described later (@pxref{Compilando do git}).

@quotation Importante
Esta seção se aplica somente a sistemas sem Guix. Segui-la para instalações
Guix existentes sobrescreverá arquivos importantes do sistema.
@end quotation

The @uref{https://guix.gnu.org/guix-install.sh, @file{guix-install.sh}}
shell script automates the binary installation process.  Use of
@file{guix-install.sh} requires Bash, GnuPG, GNU@tie{}tar, wget, and Xz.  On
systems where systemd is detected, the tool @command{newgidmap} from the
@code{uidmap} package is also required.

To install Guix on top of your GNU/Linux system, run the following commands
as root:

@example
cd /tmp
wget https://guix.gnu.org/guix-install.sh
chmod +x guix-install.sh
./guix-install.sh
@end example

Quando terminar de instalar o Guix, @pxref{Configuração de aplicativo} para
configurações extras que você pode precisar e @ref{Começando} para
seus primeiros passos!

The script goes through the following steps:

@enumerate
@item
Downloading the binary tarball from
@indicateurl{@value{BASE-URL}/guix-binary-@value{VERSION}.x86_64-linux.tar.xz}
(where @code{x86_64-linux} can be replaced with @code{i686-linux} for an
@code{i686} (32-bits) machine already running the kernel Linux, and so
on---@pxref{Distribuição GNU}) and extracting it.
@item
Setting up the build daemon (@pxref{Configurando o daemon}).
@item
Making the @command{guix} command available to non-root users.
@item
Configuring substitute servers (@pxref{Official Substitute Servers}).
@end enumerate

@quotation Nota
Por padrão, @file{guix-install.sh} configurará o Guix para baixar binários
de pacotes pré-construídos, chamados @dfn{substitutes}
(@pxref{Substitutos}), das fazendas de construção do projeto. Se você
escolher não permitir isso, o Guix construirá @emph{tudo} a partir da fonte,
tornando cada instalação e atualização muito cara. @xref{Confiança em binários} para uma discussão sobre por que você pode querer construir
pacotes a partir da fonte.

@cindex substitutos, autenticação dela
Para usar substitutos de @code{@value{SUBSTITUTE-SERVER-1}},
@code{@value{SUBSTITUTE-SERVER-2}} ou um espelho, você deve
autorizá-los. Por exemplo,

@example
guix archive --authorize < \
   ~root/.config/guix/current/share/guix/@value{SUBSTITUTE-SERVER-1}.pub
guix archive --authorize < \
   ~root/.config/guix/current/share/guix/@value{SUBSTITUTE-SERVER-2}.pub
@end example
@end quotation

@quotation Nota
O tarball da instalação binária pode ser (re)produzido e verificado
simplesmente executando o seguinte comando na árvore de código-fonte do
Guix:

@example
make guix-binary.@var{sistema}.tar.xz
@end example

@noindent
...@: que, por sua vez, executa:

@example
guix pack -s @var{sistema} --localstatedir \
  --profile-name=current-guix guix
@end example

@xref{Invocando guix pack}, para mais informações sobre essa ferramenta útil.
@end quotation

@cindex uninstalling Guix
@cindex uninstallation, of Guix
Caso você queira desinstalar o Guix, execute o mesmo script com o
sinalizador @option{--uninstall}:

@example
./guix-install.sh --uninstall
@end example

Com @option{--uninstall}, o script exclui irreversivelmente todos os
arquivos Guix, configuração e serviços.

Some GNU/Linux distributions, such as openSUSE, Alpine and NixOS provide
Guix through their own package managers.  The version of Guix may be older
than @value{VERSION} but you can update it afterwards by running
@command{guix pull}.

Aconselhamos os administradores de sistema que instalam o Guix, tanto a
partir do script de instalação quanto por meio do gerenciador de pacotes
nativo de sua distribuição estrangeira, a também ler e seguir regularmente
os avisos de segurança, conforme mostrado pelo @command{guix pull}.

@node Configurando o daemon
@section Configurando o daemon

@cindex daemon
@cindex build daemon
Durante a instalação, o @dfn{build daemon} que deve estar em execução para
usar o Guix já foi configurado e você pode executar comandos @command{guix}
no seu programa de terminal, @pxref{Começando}:

@example
guix build hello
@end example

Se isso ocorrer sem erros, sinta-se à vontade para pular esta seção. Você
deve continuar com a seção seguinte, @ref{Configuração de aplicativo}.

No entanto, agora seria um bom momento para substituir versões
desatualizadas do daemon, ajustá-lo, executar compilações em outras máquinas
(@pxref{Configuração de descarregamento de daemon}) ou iniciá-lo manualmente em ambientes
especiais como ``chroots'' (@pxref{Acessando um sistema existente via chroot}) ou
WSL (não necessário para imagens WSL criadas com Guix, @pxref{Imagens do sistema,
@code{wsl2-image-type}}). Se você quiser saber mais ou otimizar seu sistema,
vale a pena ler esta seção.

Operações como compilar um pacote ou executar o coletor de lixo são todas
executadas por um processo especializado, o build daemon, em nome dos
clientes. Apenas o daemon pode acessar o armazém e seu banco de dados
associado. Assim, qualquer operação que manipule o armazém passa pelo
daemon. Por exemplo, ferramentas de linha de comando como @command{guix
package} e @command{guix build} se comunicam com o daemon (@i{via} chamadas
de procedimento remoto) para instruir o que fazer.

As seções a seguir explicam como preparar o ambiente do daemon de
compilação. @xref{Substitutos} para informações sobre como permitir que o
daemon baixe binários pré-compilados.

@menu
* Configuração do ambiente de compilação::  Preparando o ambiente de 
                                              compilação isolado.
* Configuração de descarregamento de daemon::  Descarregando compilações 
                                                 para máquinas remotas.
* Suporte a SELinux::        Usando um política SELinux para o daemon.
* AppArmor Support::         Using an AppArmor profile for the daemon.
@end menu

@node Configuração do ambiente de compilação
@subsection Configuração do ambiente de compilação

@cindex ambiente de compilação
Em uma configuração multiusuário padrão, o Guix e seu daemon – o programa
@command{guix-daemon} – são instalados pelo administrador do
sistema. Usuários desprivilegiados podem usar ferramentas Guix para criar
pacotes ou acessar o armazém, e o daemon fará isso em seu nome, garantindo
que o armazém seja mantido em um estado consistente e permitindo que pacotes
construídos sejam compartilhados entre os usuários.

There are currently two ways to set up and run the build daemon:

@enumerate
@item
running @command{guix-daemon} as ``root'', letting it run build processes as
unprivileged users taken from a pool of build users---this is the historical
approach;

@item
running @command{guix-daemon} as a separate unprivileged user, relying on
Linux's @dfn{unprivileged user namespace} functionality to set up isolated
environments---this is the option chosen when installing Guix on a
systemd-based distribution with the installation script (@pxref{Instalação de binários}).
@end enumerate

The sections below describe each of these two configurations in more detail
and summarize the kind of build isolation they provide.

@unnumberedsubsubsec Daemon se executando como root

@cindex usuários de compilação
Quando @command{guix-daemon} é executado como @code{root}, você pode não
querer que os próprios processos de compilação de pacotes também sejam
executados como @code{root}, por razões óbvias de segurança. Para evitar
isso, um conjunto especial de @dfn{usuários de compilação} deve ser criado
para uso pelos processos de construção iniciados pelo daemon. Ter vários
desses usuários permite que o daemon ative processos de compilação distintos
sob UIDs separados, o que garante que eles não interfiram uns com os outros
- um recurso essencial, pois as compilações são consideradas funções puras
(@pxref{Introdução}).

Em um sistema GNU/Linux, um conjunto de usuários de construção pode ser
criado assim (usando a sintaxe Bash e os comandos @code{shadow}):

@c See https://lists.gnu.org/archive/html/bug-guix/2013-01/msg00239.html
@c for why `-G' is needed.
@example
# groupadd --system guixbuild
# for i in $(seq -w 1 10);
  do
    useradd -g guixbuild -G guixbuild           \
            -d /var/empty -s $(which nologin)   \
            -c "Guix build user $i" --system    \
            guixbuilder$i;
  done
@end example

@noindent
O número de usuários de compilação determina quantos trabalhos de compilação
podem ser executados em paralelo, conforme especificado pela opção
@option{--max-jobs} (@pxref{Invocando guix-daemon,
@option{--max-jobs}}). Para usar @command{guix system vm} e comandos
relacionados, você pode precisar adicionar os usuários de compilação ao
grupo @code{kvm} para que eles possam acessar @file{/dev/kvm}, usando
@code{-G guixbuild,kvm} em vez de @code{-G guixbuild} (@pxref{Invocando guix system}).

The @code{guix-daemon} program may then be run as @code{root} with the
following command@footnote{If your machine uses the systemd init system,
copying the @file{@var{prefix}/lib/systemd/system/guix-daemon.service} file
to @file{/etc/systemd/system} will ensure that @command{guix-daemon} is
automatically started.  Similarly, if your machine uses the Upstart init
system, copy the @file{@var{prefix}/lib/upstart/system/guix-daemon.conf}
file to @file{/etc/init}.}:

@example
# guix-daemon --build-users-group=guixbuild
@end example

In this setup, @file{/gnu/store} is owned by @code{root}.

@unnumberedsubsubsec Daemon Running Without Privileges

@cindex rootless build daemon
@cindex unprivileged build daemon
@cindex build daemon, unprivileged
The second and preferred option is to run @command{guix-daemon} @emph{as an
unprivileged user}.  It has the advantage of reducing the harm that can be
done should a build process manage to exploit a vulnerability in the
daemon.  This option requires the use of Linux's unprivileged user namespace
mechanism; today it is available and enabled by most GNU/Linux distributions
but can still be disabled.  The installation script automatically determines
whether this option is available on your system (@pxref{Instalação de binários}).

When using this option, you only need to create one user account, and
@command{guix-daemon} will run with the authority of that account:

@example
# groupadd --system guix-daemon
# useradd -g guix-daemon -G guix-daemon              \
          -d /var/empty -s $(which nologin)          \
          -c "Guix daemon privilege separation user" \
          --system guix-daemon
@end example

@quotation Aviso
If the @command{nologin} binary is not found by @command{which nologin}, you
may need to specify its path manually.  This will usually be
@file{/sbin/nologin} or @file{/usr/sbin/nologin}.
@end quotation

In this configuration, @file{/gnu/store} is owned by the @code{guix-daemon}
user.

@anchor{unprivileged-daemon-migration}
@unnumberedsubsubsec Migrating to the Unprivileged Daemon

@cindex unprivileged daemon, migration
@cindex rootless daemon, migration
To switch an existing installation to the unprivileged execution mode, a
number of steps must be taken: creating a new dedicated @code{guix-daemon}
user account, changing ownership of the relevant files to
@code{guix-daemon}, and ensuring that the @command{guix-daemon} program runs
as @code{guix-daemon}.

On Guix System, these steps are carried out automatically when you set the
@code{privileged?} field of the @code{guix-configuration} record to
@code{#f} and reconfigure (@pxref{guix-configuration-type,
@code{guix-configuration}}).

However, on a foreign distribution, the process is manual.  The following
paragraphs describe what you need to do.

@quotation Aviso
Follow the instructions below only after making sure you have a recent
version of @command{guix-daemon} with support for unprivileged execution.
@end quotation

File ownership can be changed, after stopping the daemon, by running the
following commands as root (the @command{chown} can take a while if there
are many files in @file{/gnu/store}):

@example
groupadd --system guix-daemon
useradd -g guix-daemon -G guix-daemon,kvm               \
        -d /var/empty -s $(which nologin)               \
        -c "Guix daemon privilege separation user"      \
        --system guix-daemon

# Make the store writable, in case the systemd 'gnu-store.mount'
# unit made it read-only.
mount -o remount,rw /gnu/store

chown -R guix-daemon:guix-daemon                        \
  /gnu                                                  \
  /var/guix/@{gc.lock,daemon-socket,db,discover@}         \
  /var/guix/@{gcroots,offload,substitute,temproots@}      \
  /var/log/guix                                         \
  /etc/guix
@end example

If your system uses the systemd service manager, running the daemon as
@code{guix-daemon} will be a matter of copying the relevant configuration
files---make sure to review any changes you might have made in your own
@file{.service} files before overwriting them:

@example
cp /var/guix/profiles/per-user/root/current-guix/lib/systemd/system/*.service \
   /etc/systemd/system
systemctl daemon-reload
systemctl start guix-daemon
@end example

If your system has AppArmor enabled, @pxref{AppArmor Support}.

@quotation Aviso
The commands above assume that @command{guix pull} was run for the root
user.  You can check whether this is the case by running this command:

@example
grep User=guix-daemon \
  /var/guix/profiles/per-user/root/current-guix/lib/systemd/system/guix-daemon.service
@end example

If that command does not show the @code{User=guix-daemon} line, then run
@command{guix pull} as the root user.
@end quotation

@unnumberedsubsubsec The Isolated Build Environment

@cindex chroot
@cindex build environment isolation
@cindex isolated build environment
@cindex hermetic build environment
In both cases, privileged and unprivileged, the daemon starts build
processes without privileges in an @emph{isolated} or @emph{hermetic} build
environment---a ``chroot''.  On GNU/Linux, by default, the build environment
contains nothing but:

@c Keep this list in sync with libstore/build.cc! -----------------------
@itemize
@item
um diretório @code{/dev} mínimo, criado principalmente independentemente do
@code{/dev} do hospedeiro@footnote{``Principalmente'' porque enquanto o
conjunto de arquivos que aparece no @code{/dev} do chroot é corrigido, a
maioria desses arquivos só pode ser criada se o hospedeiro os possuir.};

@item
o diretório @code{/proc}; mostra apenas os processos do contêiner desde que
um espaço de nome PID separado é usado;

@item
@file{/etc/passwd} com uma entrada para o usuário atual e uma entrada para o
usuário @file{nobody};

@item
@file{/etc/group} com uma entrada para o grupo de usuários;

@item
@file{/etc/hosts} com uma entrada que mapeia @code{localhost} para
@code{127.0.0.1};

@item
um diretório @file{/tmp} com permissão de escrita.
@end itemize

O chroot não contém um diretório @file{/home}, e a variável de ambiente
@env{HOME} é definida como o inexistente @file{/homeless-shelter}. Isso
ajuda a destacar usos inapropriados de @env{HOME} nos scripts de construção
de pacotes.

Tudo isso geralmente é suficiente para garantir que os detalhes do ambiente
não influenciem os processos de construção. Em alguns casos excepcionais em
que mais controle é necessário --- normalmente sobre a data, kernel ou CPU
--- você pode recorrer a uma máquina de construção virtual (@pxref{build-vm,
máquinas de construção virtual}).

Você pode influenciar o diretório onde o daemon armazena árvores de build
@i{via} a variável de ambiente @env{TMPDIR}. No entanto, a árvore de build
dentro do chroot é sempre chamada @file{/tmp/guix-build-@var{name}.drv-0},
onde @var{name} é o nome da derivação---por exemplo,
@code{coreutils-8.24}. Dessa forma, o valor de @env{TMPDIR} não vaza dentro
de ambientes de build, o que evita discrepâncias em casos em que os
processos de build capturam o nome de sua árvore de build.

@vindex http_proxy
@vindex https_proxy
O daemon também respeita as variáveis de ambiente @env{http_proxy} e
@env{https_proxy} para downloads HTTP e HTTPS que ele realiza, seja para
derivações de saída fixa (@pxref{Derivações}) ou para substitutos
(@pxref{Substitutos}).


@node Configuração de descarregamento de daemon
@subsection Usando o recurso de descarregamento

@cindex descarregamento
@cindex hook de compilação
Quando desejado, o daemon de compilação pode @dfn{offload} compilações de
derivação para outras máquinas executando Guix, usando o @code{offload}
@dfn{build hook}@footnote{Este recurso está disponível somente quando
@uref{https://github.com/artyom-poptsov/guile-ssh, Guile-SSH} está
presente.}. Quando esse recurso é habilitado, uma lista de máquinas de
compilação especificadas pelo usuário é lida de
@file{/etc/guix/machines.scm}; toda vez que uma compilação é solicitada, por
exemplo via @code{guix build}, o daemon tenta descarregá-la para uma das
máquinas que satisfazem as restrições da derivação, em particular seus tipos
de sistema --- por exemplo, @code{x86_64-linux}. Uma única máquina pode ter
vários tipos de sistema, seja porque sua arquitetura o suporta nativamente,
via emulação (@pxref{transparent-emulation-qemu, Transparent Emulation with
QEMU}), ou ambos. Os pré-requisitos ausentes para a compilação são copiados
por SSH para a máquina de destino, que então prossegue com a compilação; em
caso de sucesso, a(s) saída(s) da compilação são copiadas de volta para a
máquina inicial. O recurso de offload vem com um agendador básico que tenta
selecionar a melhor máquina. A melhor máquina é escolhida entre as máquinas
disponíveis com base em critérios como:

@enumerate
@item
A disponibilidade de um slot de build. Uma máquina de build pode ter tantos
slots de build (conexões) quanto o valor do campo @code{parallel-builds} do
seu objeto @code{build-machine}.

@item
Sua velocidade relativa, conforme definida pelo campo @code{speed} do seu
objeto @code{build-machine}.

@item
Sua carga. A carga normalizada da máquina deve ser menor que um valor
limite, configurável por meio do campo @code{overload-threshold} de seu
objeto @code{build-machine}.

@item
Disponibilidade de espaço em disco. Mais de 100 MiB devem estar disponíveis.
@end enumerate

O arquivo @file{/etc/guix/machines.scm} geralmente se parece com isso:

@lisp
(list (build-machine
        (name "eightysix.example.org")
        (systems (list "x86_64-linux" "i686-linux"))
        (host-key "ssh-ed25519 AAAAC3Nza@dots{}")
        (user "bob")
        (speed 2.))     ;incredibly fast!

      (build-machine
        (name "armeight.example.org")
        (systems (list "aarch64-linux"))
        (host-key "ssh-rsa AAAAB3Nza@dots{}")
        (user "alice")

        ;; Lembre-se de que 'guix offload' é gerado por
        ;; 'guix-daemon' como root.
        (private-key "/root/.ssh/identity-for-guix")))
@end lisp

@noindent
No exemplo acima, especificamos uma lista de duas máquinas de compilação,
uma para as arquiteturas @code{x86_64} e @code{i686} e uma para a
arquitetura @code{aarch64}.

De fato, esse arquivo é -- não surpreendentemente! -- um arquivo de Scheme
que é avaliado quando o hook @code{offload} é iniciado. Seu valor de retorno
deve ser uma lista de objetos de @code{build-machine}. Embora este exemplo
mostre uma lista fixa de máquinas de compilação, pode-se imaginar, digamos,
usando DNS-SD para retornar uma lista de possíveis máquinas de compilação
descobertas na rede local (@pxref{Introduction, Guile-Avahi ,, guile-avahi,
Using Avahi in Guile Scheme Programs}). O tipo de dados de
@code{build-machine} está detalhado abaixo.

@deftp {Tipo de dados} build-machine
Esse tipo de dados representa máquinas de compilação nas quais o daemon pode
descarregar compilações. Os campos importantes são:

@table @code

@item name
O nome de host da máquina remota.

@item systems
O sistema digita os tipos que a máquina remota suporta, por exemplo,
@code{(list "x86_64-linux" "i686-linux")}.

@item user
The user account on the remote machine to use when connecting over SSH.
Note that the SSH key pair must @emph{not} be passphrase-protected, to allow
non-interactive logins.

@item host-key
Essa deve ser a SSH @dfn{chave pública do host} da máquina no formato
OpenSSH. Isso é usado para autenticar a máquina quando nos conectamos a
ela. É uma string longa que se parece com isso:

@example
ssh-ed25519 AAAAC3NzaC@dots{}mde+UhL hint@@example.org
@end example

Se a máquina estiver executando o daemon OpenSSH, @command{sshd}, a chave do
host poderá ser encontrada em um arquivo como
@file{/etc/ssh/ssh_host_ed25519_key.pub}.

@end table

Vários campos opcionais podem ser especificados:

@table @asis

@item @code{port} (padrão: @code{22})
O número da porta para o servidor SSH na máquina.

@item @code{private-key} (padrão: @file{~root/.ssh/id_rsa})
O arquivo de chave privada SSH a ser usado ao conectar-se à máquina, no
formato OpenSSH. Esta chave não deve ser protegida com uma senha.

Observe que o valor padrão é a chave privada @emph{da usuário
root}. Verifique se ele existe se você usar o padrão.

@item @code{compression} (padrão: @code{"zlib@@openssh.com,zlib"})
@itemx @code{compression-level} (padrão: @code{3})
Os métodos de compactação no nível SSH e o nível de compactação solicitado.

Observe que o descarregamento depende da compactação SSH para reduzir o uso
da largura de banda ao transferir arquivos de e para máquinas de compilação.

@item @code{daemon-socket} (padrão: @code{"/var/guix/daemon-socket/socket"})
O nome do arquivo do soquete do domínio Unix @command{guix-daemon} está
escutando nessa máquina.

@item @code{overload-threshold} (default: @code{0.8})
O limite de carga acima do qual uma máquina de offload potencial é
desconsiderada pelo agendador de offload. O valor traduz aproximadamente o
uso total do processador da máquina de build, variando de 0,0 (0%) a 1,0
(100%). Ele também pode ser desabilitado definindo @code{overload-threshold}
para @code{#f}.

@item @code{parallel-builds} (padrão: @code{1})
O número de compilações que podem ser executadas paralelamente na máquina.

@item @code{speed} (padrão: @code{1.0})
Um ``fator de velocidade relativo''. O agendador de descarregamento tenderá
a preferir máquinas com um fator de velocidade mais alto.

@item @code{features} (padrão: @code{'()})
Uma lista de strgins que denotam recursos específicos suportados pela
máquina. Um exemplo é @code{"kvm"} para máquinas que possuem os módulos KVM
Linux e o suporte de hardware correspondente. As derivações podem solicitar
recursos pelo nome e serão agendadas nas máquinas de compilação
correspondentes.

@end table
@end deftp

@quotation Nota
No Guix System, em vez de gerenciar @file{/etc/guix/machines.scm} de forma
independente, você pode escolher especificar máquinas de compilação
diretamente na declaração @code{operating-system}, no campo
@code{build-machines} de
@code{guix-configuration}. @xref{guix-configuration-build-machines, campo
@code{build-machines} de @code{guix-configuration}}.
@end quotation

O comando @command{guix} deve estar no caminho de pesquisa nas máquinas de
compilação. Você pode verificar se este é o caso executando:

@example
ssh build-machine guix repl --version
@end example

Há uma última coisa a fazer quando o @file{machines.scm} está em vigor. Como
explicado acima, ao descarregar, os arquivos são transferidos entre os
armazéns das máquinas. Para que isso funcione, primeiro você precisa gerar
um par de chaves em cada máquina para permitir que o daemon exporte arquivos
assinados de arquivos do armazém (@pxref{Invocando guix archive}):

@example
# guix archive --generate-key
@end example

@quotation Nota
Este par de chaves não está relacionado ao par de chaves SSH mencionado
anteriormente na descrição do tipo de dados @code{build-machine}.
@end quotation

@noindent
Cada máquina de construção deve autorizar a chave da máquina principal para
que ela aceite itens do armazém que recebe do mestre:

@example
# guix archive --authorize < master-public-key.txt
@end example

@noindent
Da mesma forma, a máquina principal deve autorizar a chave de cada máquina
de compilação.

Todo esse barulho com as chaves está aqui para expressar relações de
confiança mútua de pares entre a máquina mestre e as de
compilação. Concretamente, quando o mestre recebe arquivos de uma máquina de
compilação (e @i{vice-versa}), seu daemon de compilação pode garantir que
eles sejam genuínos, não tenham sido violados e que sejam assinados por uma
chave autorizada.

@cindex offload test
Para testar se sua configuração está operacional, execute este comando no nó
principal:

@example
# guix offload test
@end example

Isso tentará se conectar a cada uma das máquinas de compilação especificadas
em @file{/etc/guix/machines.scm}, certificar-se de que o Guix esteja
disponível em cada máquina, tentará exportar para a máquina e importar dela
e relatará qualquer erro no processo.

Se você quiser testar um arquivo de máquina diferente, basta especificá-lo
na linha de comando:

@example
# guix offload test machines-qualif.scm
@end example

Por fim, você pode testar o subconjunto das máquinas cujo nome corresponde a
uma expressão regular como esta:

@example
# guix offload test machines.scm '\.gnu\.org$'
@end example

@cindex offload status
Para exibir o carregamento atual de todos os hosts de compilação, execute
este comando no nó principal:

@example
# guix offload status
@end example


@node Suporte a SELinux
@subsection Suporte a SELinux

@cindex SELinux, política de daemons
@cindex controle de acesso obrigatório, SELinux
@cindex segurança, guix-daemon
O Guix inclui um arquivo de políticas do SELinux em
@file{etc/guix-daemon.cil} que pode ser instalado em um sistema em que o
SELinux está ativado, para rotular os arquivos do Guix e especificar o
comportamento esperado do daemon. Como o Guix System não fornece uma
política básica do SELinux, a política do daemon não pode ser usada no Guix
System.

@subsubsection Instalando a política do SELinux
@cindex SELinux, instalação de política

@quotation Nota
O script de instalação binária @code{guix-install.sh} se oferece para
executar as etapas abaixo para você (@pxref{Instalação de binários}).
@end quotation

Para instalar a política, execute esse comando como root:

@example
semodule -i /var/guix/profiles/per-user/root/current-guix/share/selinux/guix-daemon.cil
@end example

Então, como root, renomeie o sistema de arquivos, possivelmente depois de
torná-lo gravável:

@example
mount -o remount,rw /gnu/store
restorecon -R /gnu /var/guix
@end example

Neste ponto, você pode iniciar ou reiniciar @command{guix-daemon}; em uma
distribuição que usa systemd como seu gerenciador de serviços, você pode
fazer isso com:

@example
systemctl restart guix-daemon
@end example

Depois que a política é instalada, o sistema de arquivos foi rotulado
novamente e o daemon foi reiniciado, ele deve estar em execução no contexto
@code{guix_daemon_t}. Você pode confirmar isso com o seguinte comando:

@example
ps -Zax | grep guix-daemon
@end example

Monitore os arquivos de log do SELinux enquanto executa um comando como
@code{guix build hello} para se convencer de que o SELinux permite todas as
operações necessárias.

@subsubsection Limitações
@cindex SELinux, limitações

Esta política não é perfeita. Aqui está uma lista de limitações ou
peculiaridades que devem ser consideradas ao implementar a política SELinux
fornecida para o daemon Guix.

@enumerate
@item
@code{guix_daemon_socket_t} isn’t actually used.  None of the socket
operations involve contexts that have anything to do with
@code{guix_daemon_socket_t}.  It doesn’t hurt to have this unused label, but
it would be preferable to define socket rules for only this label.

@item
@code{guix gc} não pode acessar links arbitrários para perfis. Por design, o
rótulo do arquivo do destino de uma ligação simbólica é independente do
rótulo do arquivo do próprio link. Embora todos os perfis em
@file{$localstatedir} estejam rotulados, as ligações para esses perfis
herdam o rótulo do diretório em que estão. Para as ligações no diretório
pessoal do usuário, será @code{user_home_t}. Mas, para ligações do diretório
pessoal do usuário root, ou @file{/tmp}, ou do diretório de trabalho do
servidor HTTP etc., isso não funcionará. @code{guix gc} seria impedido de
ler e seguir essas ligações.

@item
O recurso do daemon de escutar conexões TCP pode não funcionar mais. Isso
pode exigir regras extras, porque o SELinux trata os soquetes de rede de
maneira diferente dos arquivos.

@item
Atualmente, todos os arquivos com um nome correspondente à expressão regular
@code{/gnu/store/.+-(guix-.+|profile)/bin/guix-daemon} recebem o rótulo
@code{guix_daemon_exec_t}; isso significa que @emph{qualquer} arquivo com
esse nome em qualquer perfil poderá ser executado no domínio de
@code{guix_daemon_t}. Isto não é o ideal. Um invasor pode criar um pacote
que forneça esse executável e convencer um usuário a instalar e executá-lo,
o que o eleva ao domínio de @code{guix_daemon_t}. Nesse ponto, o SELinux não
poderia impedir o acesso a arquivos permitidos para processos nesse domínio.

Você precisará renomear o diretório store após todas as atualizações para
@file{guix-daemon}, como após executar @code{guix pull}. Supondo que o store
esteja em @file{/gnu}, você pode fazer isso com @code{restorecon -vR /gnu},
ou por outros meios fornecidos pelo seu sistema operacional.

Poderíamos gerar uma política muito mais restritiva no momento da
instalação, para que apenas o nome do arquivo @emph{exato} do executável
@code{guix-daemon} atualmente instalado seja rotulado com
@code{guix_daemon_exec_t}, em vez de usar um amplo expressão regular. A
desvantagem é que o root precisaria instalar ou atualizar a política no
momento da instalação sempre que o pacote Guix que fornece o executável
@code{guix-daemon} em execução efetiva for atualizado.
@end enumerate

@node AppArmor Support
@subsection AppArmor Support

@cindex AppArmor

Guix includes an AppArmor profile for the build daemon in
@file{etc/apparmor.d/guix-daemon} that can be installed on systems with
strict AppArmor policies to allow it to run unprivileged (@pxref{Configuração do ambiente de compilação}).  Indeed, the unprivileged daemon makes use of Linux
user namespaces but these are disallowed without an AppArmor policy on some
systems like Ubuntu.

To know if this applies to you, check if the
@code{kernel.apparmor_restrict_unprivileged_userns} kernel parameter is
enabled.

@subsubsection Installing the AppArmor profile
@cindex AppArmor, profile installation

@quotation Nota
O script de instalação binária @code{guix-install.sh} se oferece para
executar as etapas abaixo para você (@pxref{Instalação de binários}).
@end quotation

Run these commands as root to install the profile:

@example
export apparmor_sources=/var/guix/profiles/per-user/root/current-guix/etc/apparmor.d
cp -f -t /etc/apparmor.d/tunables "$apparmor_sources/tunables/guix"
cp -f -t /etc/apparmor.d "$apparmor_sources/guix-daemon"
cp -f -t /etc/apparmor.d "$apparmor_sources/guix"
apparmor_parser -r /etc/apparmor.d/guix-daemon
apparmor_parser -r /etc/apparmor.d/guix
@end example

After this, the build daemon will be able to function correctly.

@node Invocando guix-daemon
@section Invocando @command{guix-daemon}
@cindex @command{guix-daemon}
O programa @command{guix-daemon} implementa todas as funcionalidades para
acessar o armazém. Isso inclui iniciar processos de compilação, executar o
coletor de lixo, consultar a disponibilidade de um resultado da compilação
etc. É normalmente executado como @code{root}, assim:

@example
# guix-daemon --build-users-group=guixbuild
@end example

@cindex socket activation, for @command{guix-daemon}
Este daemon também pode ser iniciado seguindo o protocolo de ``ativação de
soquete'' do systemd (@pxref{Service De- and Constructors,
@code{make-systemd-constructor},, shepherd, The GNU Shepherd Manual}).

Para detalhes sobre como configurá-lo, @pxref{Configurando o daemon}.

@cindex chroot
@cindex contêiner, ambiente de compilação
@cindex ambiente de compilação
@cindex compilações reproduzíveis
Por padrão, @command{guix-daemon} inicia processos de compilação sob
diferentes UIDs, obtidos do grupo de compilação especificado com
@option{--build-users-group}. Além disso, cada processo de compilação é
executado em um ambiente chroot que contém apenas o subconjunto do armazém
do qual o processo de compilação depende, conforme especificado por sua
derivação (@pxref{Interface de programação, derivação}), mais um conjunto de
diretórios de sistema específicos. Por padrão, o último contém @file{/dev} e
@file{/dev/pts}. Além disso, no GNU/Linux, o ambiente de compilação é um
@dfn{container}: além de ter sua própria árvore de sistema de arquivos, ele
tem um espaço de nome de montagem separado, seu próprio espaço de nome PID,
espaço de nome de rede, etc. Isso ajuda a obter compilações reproduzíveis
(@pxref{Recursos}).

Quando o daemon executa uma compilação em nome do usuário, ele cria um
diretório de compilação em @file{/tmp} ou no diretório especificado por sua
variável de ambiente @env{TMPDIR}. Esse diretório é compartilhado com o
contêiner durante a compilação, embora dentro do contêiner, a árvore de
compilação seja sempre chamada de @file{/tmp/guix-build-@var{name}.drv-0}.

O diretório de compilação é excluído automaticamente após a conclusão, a
menos que a compilação falhe e o cliente tenha especificado
@option{--keep-failed} (@pxref{Opções de compilação comuns,
@option{--keep-failed}}).

O daemon escuta conexões e gera um subprocesso para cada sessão iniciada por
um cliente (um dos subcomandos @command{guix}). O comando @command{guix
processes} permite que você tenha uma visão geral da atividade no seu
sistema visualizando cada uma das sessões e clientes ativos. @xref{Invocando guix processes}, para mais informações.

As seguintes opções de linha de comando são suportadas:

@table @code
@item --build-users-group=@var{grupo}
Obtém os usuários do @var{grupo} para executar os processos de compilação
(@pxref{Configurando o daemon, usuários de compilação}).

@item --no-substitutes
@cindex substitutos
Não use substitutos para compilar produtos. Ou seja, sempre crie coisas
localmente, em vez de permitir downloads de binários pré-compilados
(@pxref{Substitutos}).

Quando o daemon é executado com @option{--no-substitutes}, os clientes ainda
podem habilitar explicitamente a substituição por meio da chamada de
procedimento remoto @code{set-build-options} (@pxref{O armazém}).

@anchor{daemon-substitute-urls}
@item --substitute-urls=@var{urls}
Consider @var{urls} the default whitespace-separated list of substitute
source URLs.  When this option is omitted,
@indicateurl{@value{SUBSTITUTE-URLS}} is used.

Isso significa que os substitutos podem ser baixados de @var{urls}, desde
que assinados por uma assinatura confiável (@pxref{Substitutos}).

@xref{Obtendo substitutos de outros servidores}, para mais informações sobre
como configurar o daemon para obter substitutos de outros servidores.

@cindex descarregamento
@item --no-offload
Não use compilações de offload para outras máquinas (@pxref{Configuração de descarregamento de daemon}). Ou seja, sempre compile as coisas localmente em vez de descarregar
compilações para máquinas remotas.

@item --cache-failures
Armazena em cache as compilações que falharam. Por padrão, apenas
compilações bem-sucedidas são armazenadas em cache.

Quando essa opção é usada, o @command{guix gc --list-failures} pode ser
usado para consultar o conjunto de itens do armazém marcados como com falha;
O @command{guix gc --clear-failures} remove os itens do armazém do conjunto
de falhas em cache. @xref{Invocando guix gc}.

@item --cores=@var{n}
@itemx -c @var{n}
Usa @var{n} núcleos de CPU para compilar cada derivação; @code{0} significa
todos disponíveis.

O valor padrão é @code{0}, mas pode ser substituído pelos clientes, como a
opção @option{--cores} de @command{guix build} (@pxref{Invocando guix build}).

O efeito é definir a variável de ambiente @env{NIX_BUILD_CORES} no processo
de compilação, que pode então usá-la para explorar o paralelismo interno —
por exemplo, executando @code{make -j$NIX_BUILD_CORES}.

@item --max-jobs=@var{n}
@itemx -M @var{n}
Permite no máximo @var{n} tarefas de compilação em paralelo. O valor padrão
é @code{1}. Definir como @code{0} significa que nenhuma compilação será
executada localmente; em vez disso, o daemon descarregará as compilações
(@pxref{Configuração de descarregamento de daemon}) ou simplesmente falhará.

@item --max-silent-time=@var{segundos}
Quando o processo de compilação ou substituição permanecer em silêncio por
mais de @var{segundos}, encerra-o e relata uma falha de compilação.

The default value is @code{3600} (one hour).

O valor especificado aqui pode ser substituído pelos clientes (@pxref{Opções de compilação comuns, @option{--max-silent-time}}).

@item --timeout=@var{segundos}
Da mesma forma, quando o processo de compilação ou substituição durar mais
que @var{segundos}, encerra-o e relata uma falha de compilação.

O valor padrão é 24 horas.

O valor especificado aqui pode ser substituído pelos clientes (@pxref{Opções de compilação comuns, @option{--timeout}}).

@item --rounds=@var{N}
Compila cada derivação @var{n} vezes seguidas e gera um erro se os
resultados consecutivos da compilação não forem idênticos bit a bit. Observe
que essa configuração pode ser substituída por clientes como @command{guix
build} (@pxref{Invocando guix build}).

Quando usado em conjunto com @option{--keep-failed}, uma saída de comparação
é mantida no armazém, sob  @file{/gnu/store/@dots{}-check}. Isso facilita
procurar por diferenças entre os dois resultados.

@item --debug
Produz uma saída de depuração.

Isso é útil para depurar problemas de inicialização do daemon, mas pode ser
substituído pelos clientes, por exemplo, a opção @option{--verbosity} de
@command{guix build} (@pxref{Invocando guix build}).

@item --chroot-directory=@var{dir}
adiciona @var{dir} ao chroot de compilação.

Isso pode alterar o resultado dos processos de compilação -- por exemplo, se
eles usam dependências opcionais encontradas em @var{dir} quando estão
disponíveis, e não o contrário. Por esse motivo, não é recomendável
fazê-lo. Em vez disso, verifique se cada derivação declara todas as entradas
necessárias.

@item --disable-chroot
Desabilita compilações em chroot.

@quotation Aviso
Using this option is not recommended since it allows build processes to gain
access to undeclared dependencies, to interfere with one another, and more
generally to do anything that can be done with the authority of build users
or that of the daemon---which includes at least the ability to tamper with
any file in the store!

You may find it necessary, though, when support for Linux unprivileged user
namespaces is missing (@pxref{Configuração do ambiente de compilação}).  Use at your own
risk!
@end quotation

@item --isolate-host-loopback
Prevent fixed-output chroot builds from accessing the host loopback.  When
this is used, fixed-output builds will have their own loopback interface,
and attempts to connect to 127.0.0.1 or ::1 will instead attempt to connect
to its local loopback interface.

@item --log-compression=@var{tipo}
Compacta logs de compilação de aconrdo com @var{tipo}, que pode ser um entre
@code{gzip}, @code{bzip2} e @code{none}.

A menos que @option{--lose-logs} seja usado, todos os logs de build são
mantidos em @var{localstatedir}. Para economizar espaço, o daemon os
compacta automaticamente com gzip por padrão.

@item --discover[=yes|no]
Se deve descobrir servidores substitutos na rede local usando mDNS e DNS-SD.

Este recurso ainda é experimental. No entanto, aqui estão algumas
considerações.

@enumerate
@item
Pode ser mais rápido/menos caro do que buscar em servidores remotos;
@item
Não há riscos de segurança, apenas substitutos genuínos serão usados
(@pxref{Autenticação de substituto});
@item
Um invasor anunciando @command{guix publish} na sua LAN não pode fornecer
binários maliciosos, mas pode descobrir qual software você está instalando;
@item
Os servidores podem servir substitutos via HTTP, sem criptografia, para que
qualquer pessoa na LAN possa ver qual software você está instalando.
@end enumerate

Também é possível habilitar ou desabilitar a descoberta de servidor
substituto em tempo de execução executando:

@example
herd discover guix-daemon on
herd discover guix-daemon off
@end example

@item --disable-deduplication
@cindex deduplicação
Desabilita ``deduplicação'' automática de arquivos no armazém.

Por padrão, os arquivos adicionados ao armazém são automaticamente
``deduplicados'': se um arquivo recém-adicionado for idêntico a outro
encontrado no armazém, o daemon tornará o novo arquivo um link físico para o
outro arquivo. Isso pode reduzir notavelmente o uso do disco, às custas de
um leve aumento na carga de entrada/saída no final de um processo de
criação. Esta opção desativa essa otimização.

@item --gc-keep-outputs[=yes|no]
Diz se o coletor de lixo (GC) deve manter as saídas de derivações vivas.

@cindex raízes de GC
@cindex raízes de coletor de lixo
Quando definido como @code{yes}, o GC manterá as saídas de qualquer
derivação ativa disponível no armazém---os arquivos @file{.drv}. O padrão é
@code{no}, o que significa que as saídas de derivação são mantidas somente
se forem acessíveis a partir de uma raiz do GC. @xref{Invocando guix gc},
para mais informações sobre raízes do GC.

@item --gc-keep-derivations[=yes|no]
Diz se o coletor de lixo (GC) deve manter as derivações correspondentes às
saídas vivas.

Quando definido como @code{yes}, como é o caso por padrão, o GC mantém
derivações---ou seja, arquivos @file{.drv}---desde que pelo menos uma de
suas saídas esteja ativa. Isso permite que os usuários acompanhem as origens
dos itens em seu armazém. Defini-lo como @code{no} economiza um pouco de
espaço em disco.

Dessa forma, definir @option{--gc-keep-derivations} como @code{yes} faz com
que a vivacidade flua das saídas para as derivações, e definir
@option{--gc-keep-outputs} como @code{yes} faz com que a vivacidade flua das
derivações para as saídas. Quando ambos são definidos como @code{yes}, o
efeito é manter todos os pré-requisitos de compilação (as fontes, o
compilador, as bibliotecas e outras ferramentas de tempo de compilação) de
objetos ativos no armazém, independentemente de esses pré-requisitos serem
acessíveis a partir de uma raiz GC. Isso é conveniente para desenvolvedores,
pois economiza reconstruções ou downloads.

@item --impersonate-linux-2.6
Em sistemas baseados em Linux, personifique o Linux 2.6. Isso significa que
a chamada de sistema @command{uname} do kernel relatará 2.6 como o número da
versão.

Isso pode ser útil para criar programas que (geralmente de forma errada)
dependem do número da versão do kernel.

@item --lose-logs
Não mantenha logs de build. Por padrão, eles são mantidos em
@file{@var{localstatedir}/guix/log}.

@item --system=@var{sistema}
Assuma @var{sistema} como o tipo de sistema atual. Por padrão, é o par
arquitetura/kernel encontrado no momento da configuração, como
@code{x86_64-linux}.

@item --listen=@var{endpoint}
Ouça conexões em @var{endpoint}. @var{endpoint} é interpretado como o nome
do arquivo de um soquete de domínio Unix se ele começar com @code{/} (sinal
de barra). Caso contrário, @var{endpoint} é interpretado como um nome de
host ou nome de host e porta para ouvir. Aqui estão alguns exemplos:

@table @code
@item --listen=/gnu/var/daemon
Ouça conexões no soquete de domínio Unix @file{/gnu/var/daemon}, criando-o
se necessário.

@item --listen=localhost
@cindex daemon, acesso remoto
@cindex acesso remoto ao daemon
@cindex daemon, configuração de cluster
@cindex clusters, configuração do daemon
Ouça as conexões TCP na interface de rede correspondente a @code{localhost},
na porta 44146.

@item --listen=128.0.0.42:1234
Ouça as conexões TCP na interface de rede correspondente ao
@code{128.0.0.42}, na porta 1234.
@end table

Esta opção pode ser repetida várias vezes, nesse caso @command{guix-daemon}
aceita conexões em todos os endpoints especificados. Os usuários podem
informar aos comandos do cliente a qual endpoint se conectar definindo a
variável de ambiente @env{GUIX_DAEMON_SOCKET} (@pxref{O armazém,
@env{GUIX_DAEMON_SOCKET}}).

@quotation Nota
O protocolo daemon é @emph{unauthenticated and unencrypted}. Usar
@option{--listen=@var{host}} é adequado em redes locais, como clusters, onde
apenas nós confiáveis podem se conectar ao daemon de compilação. Em outros
casos em que o acesso remoto ao daemon é necessário, recomendamos usar
soquetes de domínio Unix junto com SSH.
@end quotation

Quando @option{--listen} é omitido, @command{guix-daemon} escuta conexões no
soquete de domínio Unix localizado em
@file{@var{localstatedir}/guix/daemon-socket/socket}.
@end table


@node Configuração de aplicativo
@section Configuração de aplicativo

@cindex distro alheia
Ao usar Guix sobre uma distribuição GNU/Linux que não seja um Guix System
--- uma chamada @dfn{distro alheia} --- algumas etapas adicionais são
necessárias para colocar tudo no seu lugar. Aqui estão algumas delas.

@subsection Localidades

@anchor{locales-and-locpath}
@cindex locales, quando não está no Guix System
@vindex LOCPATH
@vindex GUIX_LOCPATH
Pacotes instalados @i{via} Guix não usarão os dados de localidade do sistema
host. Em vez disso, você deve primeiro instalar um dos pacotes de localidade
disponíveis com Guix e então definir a variável de ambiente
@env{GUIX_LOCPATH}:

@example
$ guix install glibc-locales
$ export GUIX_LOCPATH=$HOME/.guix-profile/lib/locale
@end example

Observe que o pacote @code{glibc-locales} contém dados para todos os locais
suportados pela GNU@tie{}libc e pesa cerca de 930@tie{}MiB@footnote{O
tamanho do pacote @code{glibc-locales} é reduzido para cerca de 213@tie{}MiB
com desduplicação de armazém e ainda mais para cerca de 67@tie{}MiB ao usar
um sistema de arquivos Btrfs compactado em zstd.}. Se você precisar apenas
de alguns locais, poderá definir seu pacote de locais personalizados por
meio do procedimento @code{make-glibc-utf8-locales} do módulo @code{(gnu
packages base)}. O exemplo a seguir define um pacote contendo os vários
locais UTF-8 canadenses conhecidos pela GNU@tie{}libc, que pesa cerca de
14@tie{}MiB:

@lisp
(use-modules (gnu packages base))

(define my-glibc-locales
  (make-glibc-utf8-locales
   glibc
   #:locales (list "en_CA" "fr_CA" "ik_CA" "iu_CA" "shs_CA")
   #:name "glibc-canadian-utf8-locales"))
@end lisp

A variável @env{GUIX_LOCPATH} desempenha um papel similar a @env{LOCPATH}
(@pxref{Locale Names, @env{LOCPATH},, libc, The GNU C Library Reference
Manual}). Há duas diferenças importantes, no entanto:

@enumerate
@item
@env{GUIX_LOCPATH} é honrado apenas pela libc no Guix, e não pela libc
fornecida por distros estrangeiras. Assim, usar @env{GUIX_LOCPATH} permite
que você tenha certeza de que os programas da distro estrangeira não
acabarão carregando dados de localidade incompatíveis.

@item
libc sufixa cada entrada de @env{GUIX_LOCPATH} com @code{/X.Y}, onde
@code{X.Y} é a versão libc---por exemplo, @code{2.22}. Isso significa que,
caso seu perfil Guix contenha uma mistura de programas vinculados a
diferentes versões libc, cada versão libc tentará carregar apenas dados de
localidade no formato correto.
@end enumerate

Isso é importante porque o formato de dados de localidade usado por
diferentes versões da libc pode ser incompatível.

@subsection Name Service Switch

@cindex troca de serviço de nome, glibc
@cindex NSS (troca de serviço de nomes), glibc
@cindex @abbr{nscd, name service cache daemon}
Ao usar o Guix em uma distro alheia, nós @emph{recomendamos fortemente} que
o sistema use o @dfn{daemon de cache de serviço de nomes} da biblioteca C do
GNU, @command{nscd}, que deve ouvir no soquete
@file{/var/run/nscd/socket}. Caso não faça isso, os aplicativos instalados
com Guix podem falhar em procurar nomes de máquina e contas de usuário, ou
até mesmo travar. Os próximos parágrafos explicam o porquê.

@cindex @file{nsswitch.conf}
A biblioteca GNU C implementa um @dfn{name service switch} (NSS), que é um
mecanismo extensível para ``pesquisas de nomes'' em geral: resolução de
nomes de host, contas de usuários e muito mais (@pxref{Name Service
Switch,,, libc, The GNU C Library Reference Manual}).

@cindex Serviço de informação de rede (NIS)
@cindex NIS (Serviço de informação de rede)
Sendo extensível, o NSS suporta @dfn{plugins}, que fornecem novas
implementações de pesquisa de nomes: por exemplo, o plugin @code{nss-mdns}
permite a resolução de nomes de host @code{.local}, o plugin @code{nis}
permite a pesquisa de contas de usuários usando o Network information
service (NIS), e assim por diante. Esses "serviços de pesquisa'' extras são
configurados em todo o sistema em @file{/etc/nsswitch.conf}, e todos os
programas em execução no sistema honram essas configurações (@pxref{NSS
Configuration File,,, libc, The GNU C Reference Manual}).

Quando eles realizam uma pesquisa de nome --- por exemplo chamando a função
@code{getaddrinfo} em C --- os aplicativos primeiro tentam se conectar ao
nscd; em caso de sucesso, o nscd realiza pesquisas de nome em seu nome. Se o
nscd não estiver em execução, eles realizam a pesquisa de nome sozinhos,
carregando os serviços de pesquisa de nome em seu próprio espaço de endereço
e executando-o. Esses serviços de pesquisa de nome --- os arquivos
@file{libnss_*.so} --- são @code{dlopen}'d, mas podem vir da biblioteca C do
sistema host, em vez da biblioteca C à qual o aplicativo está vinculado (a
biblioteca C vem do Guix).

E é aqui que está o problema: se seu aplicativo estiver vinculado à
biblioteca C do Guix (por exemplo, glibc 2.24) e tentar carregar plugins NSS
de outra biblioteca C (por exemplo, @code{libnss_mdns.so} para glibc 2.22),
ele provavelmente travará ou terá suas pesquisas de nome falhando
inesperadamente.

Executar @command{nscd} no sistema, entre outras vantagens, elimina esse
problema de incompatibilidade binária porque esses arquivos
@code{libnss_*.so} são carregados no processo @command{nscd}, não nos
próprios aplicativos.

@cindex nsncd, replacement for nscd
Note that @command{nscd} is no longer provided on some GNU/Linux distros,
such as Arch Linux (as of Dec. 2024).  @command{nsncd} can be used as a
drop-in-replacement.  See @uref{https://github.com/twosigma/nsncd, the nsncd
repository} and @uref{https://flokli.de/posts/2022-11-18-nsncd/, this blog
post} for more information.

@subsection Fontes X11

@cindex fontes
A maioria dos aplicativos gráficos usa o Fontconfig para localizar e
carregar fontes e executar renderização do lado do cliente X11. O pacote
@code{fontconfig} no Guix procura fontes em @file{$HOME/.guix-profile} por
padrão. Assim, para permitir que aplicativos gráficos instalados com o Guix
exibam fontes, você precisa instalar fontes com o Guix também. Pacotes de
fontes essenciais incluem @code{font-ghostscript}, @code{font-dejavu} e
@code{font-gnu-freefont}.

@cindex @code{fc-cache}
@cindex cache de font
Depois de instalar ou remover fontes, ou quando notar que um aplicativo não
encontra fontes, talvez seja necessário instalar o Fontconfig e forçar uma
atualização do cache de fontes executando:

@example
guix install fontconfig
fc-cache -rv
@end example

Para exibir texto escrito em chinês, japonês ou coreano em aplicativos
gráficos, considere instalar @code{font-adobe-source-han-sans} ou
@code{font-wqy-zenhei}. O primeiro tem várias saídas, uma por família de
idiomas (@pxref{Pacotes com múltiplas saídas}). Por exemplo, o comando a
seguir instala fontes para idiomas chineses:

@example
guix install font-adobe-source-han-sans:cn
@end example

@cindex @code{xterm}
Programas mais antigos como @command{xterm} não usam Fontconfig e, em vez
disso, dependem da renderização de fontes do lado do servidor. Tais
programas exigem a especificação de um nome completo de uma fonte usando
XLFD (X Logical Font Description), como este:

@example
-*-dejavu sans-medium-r-normal-*-*-100-*-*-*-*-*-1
@end example

Para poder usar esses nomes completos para as fontes TrueType instaladas no
seu perfil Guix, você precisa estender o caminho da fonte do 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}
Depois disso, você pode executar @code{xlsfonts} (do pacote @code{xlsfonts})
para garantir que suas fontes TrueType estejam listadas lá.


@subsection Certificados X.509

@cindex @code{nss-certs}
O pacote @code{nss-certs} fornece certificados X.509, que permitem que
programas autentiquem servidores Web acessados por HTTPS.

Ao usar uma Guix em uma distro alheia, você pode instalar esse pacote e
definir as variáveis de ambiente relevantes de forma que os pacotes saibam
onde procurar por certificados. @xref{Certificados X.509}, para informações
detalhadas.

@subsection Pacotes Emacs

@cindex @code{emacs}
Quando você instala pacotes do Emacs com o Guix, os arquivos Elisp são
colocados no diretório @file{share/emacs/site-lisp/} do perfil no qual eles
são instalados. As bibliotecas Elisp são disponibilizadas para o Emacs por
meio da variável de ambiente @env{EMACSLOADPATH}, que é definida ao instalar
o próprio Emacs.

@cindex guix-emacs-autoload-packages, atualizando pacotes Emacs
Além disso, as definições de autoload são avaliadas automaticamente na
inicialização do Emacs, pelo procedimento específico do Guix
@code{guix-emacs-autoload-packages}. Este procedimento pode ser invocado
interativamente para que pacotes Emacs recém-instalados sejam descobertos,
sem precisar reiniciar o Emacs. Se, por algum motivo, você quiser evitar o
carregamento automático dos pacotes Emacs instalados com o Guix, você pode
fazer isso executando o Emacs com a opção @option{--no-site-file}
(@pxref{Init File,,, emacs, The GNU Emacs Manual}).

@quotation Nota
A maioria das variantes do Emacs agora são capazes de fazer compilação
nativa. A abordagem adotada pelo Guix Emacs, no entanto, difere muito da
abordagem adotada pelo upstream.

O Upstream Emacs compila pacotes just-in-time e normalmente coloca arquivos
de objetos compartilhados em uma pasta especial dentro do seu
@code{user-emacs-directory}. Esses objetos compartilhados dentro da referida
pasta são organizados em uma hierarquia plana, e seus nomes de arquivo
contêm dois hashes para verificar o nome do arquivo original e o conteúdo do
código-fonte.

O Guix Emacs, por outro lado, prefere compilar pacotes antes do
tempo. Objetos compartilhados retêm muito do nome do arquivo original e
nenhum hashe é adicionado para verificar o nome do arquivo original ou o
conteúdo do arquivo. Crucialmente, isso permite que o Guix Emacs e os
pacotes construídos contra ele sejam enxertados (@pxref{Atualizações de segurança,
enxertos}), mas, ao mesmo tempo, o Guix Emacs não tem a verificação baseada
em hash do código-fonte embutido no Emacs upstream. Como esse esquema de
nomenclatura é trivial de explorar, desabilitamos a compilação just-in-time.

Observe ainda que @code{emacs-minimal}---o Emacs padrão para construir
pacotes---foi configurado sem compilação nativa. Para compilar nativamente
seus pacotes emacs antes do tempo, use uma transformação como
@option{--with-input=emacs-minimal=emacs}.
@end quotation

@node Atualizando o Guix
@section Atualizando o Guix

@cindex Atualizando o Guix, em uma distribuição estrangeira

Para atualizar o Guix, execute:

@example
guix pull
@end example

@xref{Invocando guix pull}, para maiores informações.

@cindex atualizando Guix para o usuário root, em uma distribuição estrangeira
@cindex atualizando o daemon Guix, em uma distribuição estrangeira
@cindex @command{guix pull} para o usuário root, em uma distribuição estrangeira

If you installed Guix on a foreign distro with @file{guix-install.sh}, you
can upgrade the build daemon by running:

@example
sudo -i guix pull
@end example

@noindent
seguido por (supondo que sua distribuição use a ferramenta de gerenciamento
de serviço systemd):

@example
systemctl restart guix-daemon.service
@end example

While this works for @file{guix-install.sh}, it will most likely not work if
you installed Guix through the package manager of another distribution (for
instance with @command{sudo apt install guix}, @command{pacman -S guix}, or
similar commands)  because on many distributions @file{guix-daemon.service}
will only run the Guix daemon provided by the distribution.

Waiting for your distribution to provide security fixes sometimes work, but
fixing security issues in the Guix package takes times for distributions
because Guix doesn't backport the security fixes to the releases used by the
distributions. On some distribution versions, the Guix package is never
fixed.

However since Guix updates also comes with a new daemon, so you can simply
configure your distribution to use the guix-daemon provided by Guix
instead. The following will assume that your distribution uses systemd.

You first need to override @file{guix-daemon.service} with the following
command:

@example
sudo install -m 644 \
     /lib/systemd/system/guix-daemon.service \
     /etc/systemd/system/guix-daemon.service
@end example

You will then need to edit
@file{/etc/systemd/system/guix-daemon.service}. To do that open this file
with a text editor that has root permissions:

@example
sudo $EDITOR /etc/systemd/system/guix-daemon.service
@end example

Then try to find a line with @emph{ExecStart=}, it should look a bit like
that:
@example
...
[Service]
ExecStart=/usr/bin/guix-daemon --build-users-group=_guixbuild
...
@end example

Then change @emph{/usr/bin/guix-daemon} into
@emph{/var/guix/profiles/per-user/root/current-guix/bin/guix-daemon} and
save the changes.

Once done you need to tell systemd that @emph{guix-daemon.service} was
overriden:

@example
sudo systemctl daemon-reload
@end example

Once done you can then update the Guix daemon in the same way than if you
installed Guix with @file{guix-install.sh}:

@example
sudo -i guix pull
sudo systemctl restart guix-daemon.service
@end example

No sistema Guix, a atualização do daemon é obtida reconfigurando o sistema
(@pxref{Invocando guix system, @code{guix system reconfigure}}).

To migrate an existing installation to the @emph{unprivileged daemon} where
@command{guix-daemon} does not run as root,
@pxref{unprivileged-daemon-migration}.

@c TODO What else?

@c *********************************************************************
@node Instalação do sistema
@chapter Instalação do sistema

@cindex instalando o Guix System
@cindex Guix System, instalação
Esta seção explica como instalar o Guix System em uma máquina. Guix, como
gerenciador de pacotes, também pode ser instalado sobre um sistema GNU/Linux
em execução, @pxref{Instalação}.

@ifinfo
@quotation Nota
@c This paragraph is for people reading this from tty2 of the
@c installation image.
Você está lendo esta documentação com um leitor de informações. Para obter
detalhes sobre como usá-lo, pressione a tecla @key{RET} ("return'' ou
"enter'') no link a seguir: @pxref{Top, Info reader,, info-stnd, Stand-alone
GNU Info}. Clique em @kbd{l} depois para voltar aqui.

Alternativamente, execute @command{info info} em outro tty para manter o
manual disponível.
@end quotation
@end ifinfo

@menu
* Limitações::               O que você pode esperar.
* Considerações de hardware::  Hardware suportado.
* Instalação em um pendrive e em DVD::  Preparando a mídia de instalação.
* Preparando para instalação::  Rede, particionamento, etc.
* Instalação gráfica guiada::  Instalação gráfica fácil.
* Instalação manual::        Instalação manual para magos.
* Após a instalação do sistema::  Quando a instalação conclui com sucesso.
* Instalando Guix em uma VM::  Parque de diversões do Guix System.
* Compilando a imagem de instalação::  Como isso vem a ser.
@end menu

@node Limitações
@section Limitações

Consideramos que o Guix System está pronto para uma ampla gama de casos de
uso de "desktop'' e servidores. As garantias de confiabilidade que ele
fornece – atualizações e reversões transacionais, reprodutibilidade –
tornam-no uma base sólida.

Cada vez mais serviços de sistema são fornecidos (@pxref{Serviços}).

No entanto, antes de prosseguir com a instalação, esteja ciente de que
alguns serviços dos quais você depende ainda podem estar faltando na versão
@value{VERSION}.

Mais do que um aviso de isenção de responsabilidade, este é um convite para
relatar problemas (e histórias de sucesso!) e se juntar a nós para
melhorá-los. @xref{Contribuindo}, para mais informações.


@node Considerações de hardware
@section Considerações de hardware

@cindex suporte a hardware no Guix System
GNU@tie{}Guix se concentra em respeitar a liberdade computacional do
usuário. Ele é construído em torno do kernel Linux-libre, o que significa
que apenas o hardware para o qual existem drivers e firmware de software
livre é suportado. Hoje em dia, uma ampla gama de hardware disponível no
mercado é suportada no GNU/Linux-libre – de teclados a placas gráficas,
scanners e controladores Ethernet. Infelizmente, ainda existem áreas onde os
fornecedores de hardware negam aos usuários o controle sobre sua própria
computação, e tal hardware não é suportado no Guix System.

@cindex Wi-Fi, suporte de hardware
Uma das principais áreas onde faltam drivers ou firmware gratuitos são os
dispositivos WiFi. Os dispositivos WiFi que funcionam incluem aqueles que
usam chips Atheros (AR9271 e AR7010), que corresponde ao driver @code{ath9k}
Linux-libre, e aqueles que usam chips Broadcom/AirForce (BCM43xx com
Wireless-Core Revisão 5), que corresponde a o driver livre Linux
@code{b43-open}. Existe firmware livre para ambos e está disponível
imediatamente no Guix System, como parte do @code{%base-firmware}
(@pxref{Referência do operating-system, @code{firmware}}).

O instalador avisa você antecipadamente se detectar dispositivos que
@emph{não} funcionam devido à falta de firmware ou drivers gratuitos.

@cindex RYF, respeita sua liberdade
A @uref{https://www.fsf.org/, Free Software Foundation} administra
@uref{https://www.fsf.org/ryf, @dfn{Respects Your Freedom}} (RYF), um
programa de certificação para produtos de hardware que respeitem sua
liberdade e privacidade e garantam que você tenha controle sobre seu
dispositivo. Recomendamos que você verifique a lista de dispositivos
certificados RYF.

Outro recurso útil é o site @uref{https://www.h-node.org/, H-Node}. Ele
contém um catálogo de dispositivos de hardware com informações sobre seu
suporte no GNU/Linux.


@node Instalação em um pendrive e em DVD
@section Instalação em um pendrive e em DVD

Uma imagem de instalação ISO-9660 que pode ser gravada em um pendrive ou
gravada em um DVD pode ser baixada em
@indicateurl{@value{BASE-URL}/guix-system-install-@value{VERSION}.x86_64-linux.iso},
onde você pode substituir @code{x86_64-linux} por um dos seguintes:

@table @code
@item x86_64-linux
para um sistema GNU/Linux em CPUs de 64 bits compatíveis com Intel/AMD;

@item i686-linux
para um sistema GNU/Linux de 32 bits em CPUs compatíveis com Intel.
@end table

@c start duplication of authentication part from ``Binary Installation''
Certifique-se de baixar o arquivo @file{.sig} associado e verificar a
autenticidade da imagem em relação a ele, seguindo estas linhas:

@example
$ wget @value{BASE-URL}/guix-system-install-@value{VERSION}.x86_64-linux.iso.sig
$ gpg --verify guix-system-install-@value{VERSION}.x86_64-linux.iso.sig
@end example

Se esse comando falhar porque você não possui a chave pública requerida,
execute este comando para importá-lo:

@example
$ wget @value{OPENPGP-SIGNING-KEY-URL} \
      -qO - | gpg --import -
@end example

@noindent
e execute novamente o comando @code{gpg --verify}.

Observe que um aviso como "Esta chave não está certificada com uma
assinatura confiável!'' é normal.

@c end duplication

Esta imagem contém as ferramentas necessárias para uma instalação. Ele deve
ser copiado @emph{como está} para um pendrive ou DVD grande o suficiente.

@unnumberedsubsec Copiando para um pendrive

Insira um pendrive de 1@tie{}GiB ou mais em sua máquina e determine o nome
do dispositivo. Supondo que o pendrive seja conhecido como @file{/dev/sdX},
copie a imagem com:

@example
dd if=guix-system-install-@value{VERSION}.x86_64-linux.iso of=/dev/sdX status=progress
sync
@end example

O acesso a @file{/dev/sdX} geralmente requer privilégios de root.

@unnumberedsubsec Gravando em um DVD

Insira um DVD virgem em sua máquina e determine o nome do
dispositivo. Supondo que a unidade de DVD seja conhecida como
@file{/dev/srX}, copie a imagem com:

@example
growisofs -dvd-compat -Z /dev/srX=guix-system-install-@value{VERSION}.x86_64-linux.iso
@end example

O acesso a @file{/dev/srX} geralmente requer privilégios de root.

@unnumberedsubsec Inicializando

Feito isso, você poderá reiniciar o sistema e inicializar a partir do
pendrive ou DVD@. O último geralmente requer que você entre no menu de
inicialização do BIOS ou UEFI, onde você pode optar por inicializar a partir
do pendrive. Para inicializar a partir do Libreboot, mude para o modo de
comando pressionando a tecla @kbd{c} e digite @command{search_grub usb}.

Infelizmente, em algumas máquinas, o meio de instalação não pode ser
inicializado corretamente e você só verá uma tela preta após a
inicialização, mesmo depois de esperar dez minutos. Isto pode indicar que
sua máquina não consegue executar o Sistema Guix; talvez você queira
instalar o Guix em uma distribuição estrangeira (@pxref{Instalação de binários}). Mas não desista ainda; uma possível solução alternativa é
pressionar a tecla @kbd{e} no menu de inicialização do GRUB e anexar
@option{nomodeset} à linha de inicialização do Linux. Às vezes, o problema
da tela preta também pode ser resolvido conectando um monitor diferente.

@xref{Instalando Guix em uma VM}, se, em vez disso, você quiser instalar o
Guix System em uma máquina virtual (VM).


@node Preparando para instalação
@section Preparando para instalação

Depois de inicializar, você pode usar o instalador gráfico guiado, o que
facilita o início (@pxref{Instalação gráfica guiada}). Alternativamente,
se você já está familiarizado com GNU/Linux e deseja mais controle do que o
instalador gráfico oferece, você pode escolher o processo de instalação
"manual'' (@pxref{Instalação manual}).

O instalador gráfico está disponível em TTY1. Você pode obter shells root em
TTYs 3 a 6 pressionando @kbd{ctrl-alt-f3}, @kbd{ctrl-alt-f4}, etc. TTY2
mostra esta documentação e você pode acessá-la com @kbd{ctrl-alt -f2}. A
documentação pode ser navegada usando os comandos do leitor de informações
(@pxref{Top,,, info-stnd, Stand-alone GNU Info}). O sistema de instalação
executa o daemon do mouse GPM, que permite selecionar texto com o botão
esquerdo do mouse e colá-lo com o botão do meio.

@quotation Nota
A instalação requer acesso à Internet para que quaisquer dependências
ausentes na configuração do sistema possam ser baixadas. Consulte a seção
"Rede" abaixo.
@end quotation

@node Instalação gráfica guiada
@section Instalação gráfica guiada

O instalador gráfico é uma interface de usuário baseada em texto. Ele guiará
você, com caixas de diálogo, pelas etapas necessárias para instalar o
GNU@tie{}Guix System.

As primeiras caixas de diálogo permitem que você configure o sistema
conforme você o utiliza durante a instalação: você pode escolher o idioma, o
layout do teclado e configurar a rede que será usada durante a instalação. A
imagem abaixo mostra a caixa de diálogo de rede.

@image{images/installer-network,5in,, configuração de rede com o instalador
gráfico}

As etapas posteriores permitem particionar seu disco rígido, conforme
mostrado na imagem abaixo, escolher se deseja ou não usar sistemas de
arquivos criptografados, inserir o nome do host e a senha root e criar uma
conta adicional, entre outras coisas.

@image{images/installer-partitions,5in,, particionando com o instalador
gráfico}

Observe que, a qualquer momento, o instalador permite sair da etapa de
instalação atual e retomar uma etapa anterior, conforme imagem abaixo.

@image{images/installer-resume,5in,, retomando o processo de instalação}

Quando terminar, o instalador produz uma configuração do sistema operacional
e a exibe (@pxref{Usando o sistema de configuração}). Nesse ponto você pode
clicar em "OK'' e a instalação continuará. Se tiver sucesso, você pode
reiniciar no novo sistema e aproveitar. @xref{Após a instalação do sistema},
para saber o que vem a seguir!


@node Instalação manual
@section Instalação manual

Esta seção descreve como você instalaria "manualmente'' o GNU@tie{}Guix
System em sua máquina. Esta opção requer familiaridade com GNU/Linux, com o
shell e com ferramentas de administração comuns. Se você acha que isso não é
para você, considere usar o instalador gráfico guiado (@pxref{Instalação gráfica guiada}).

O sistema de instalação fornece shells root nos TTYs 3 a 6; pressione
@kbd{ctrl-alt-f3}, @kbd{ctrl-alt-f4} e assim por diante para
alcançá-los. Inclui muitas ferramentas comuns necessárias para instalar o
sistema, mas também é um sistema Guix completo. Isso significa que você pode
instalar pacotes adicionais, caso precise, usando @command{guix package}
(@pxref{Invocando guix package}).

@menu
* Disposição de teclado e rede e particionamento::  Configuração inicial.
* Prosseguindo com a instalação::  Instalando.
@end menu

@node Disposição de teclado e rede e particionamento
@subsection Layout de teclado, rede e particionamento

Antes de instalar o sistema, você pode querer ajustar o layout do teclado,
configurar a rede e particionar o disco rígido de destino. Esta seção irá
guiá-lo através disso.

@subsubsection Disposição do teclado

@cindex disposição do teclado
A imagem de instalação usa o layout de teclado qwerty dos EUA. Se quiser
alterá-lo, você pode usar o comando @command{loadkeys}. Por exemplo, o
comando a seguir seleciona o layout do teclado Dvorak:

@example
loadkeys dvorak
@end example

Consulte os arquivos em @file{/run/current-system/profile/share/keymaps}
para obter uma lista de layouts de teclado disponíveis. Execute @command{man
loadkeys} para obter mais informações.

@anchor{manual-installation-networking}
@subsubsection Rede

Execute o seguinte comando para ver como são chamadas suas interfaces de
rede:

@example
ifconfig -a
@end example

@noindent
@dots{} ou, usando o comando @command{ip} específico do GNU/Linux:

@example
ip address
@end example

@c https://cgit.freedesktop.org/systemd/systemd/tree/src/udev/udev-builtin-net_id.c#n20
As interfaces com fio têm um nome que começa com @samp{e}; por exemplo, a
interface correspondente ao primeiro controlador Ethernet integrado é
chamada @samp{eno1}. As interfaces sem fio têm um nome que começa com
@samp{w}, como @samp{w1p2s0}.

@table @asis
@item Conexão cabeada
Para configurar uma rede com fio execute o seguinte comando, substituindo
@var{interface} pelo nome da interface com fio que você deseja usar.

@example
ifconfig @var{interface} up
@end example

@noindent
@dots{} ou, usando o comando @command{ip} específico do GNU/Linux:

@example
ip link set @var{interface} up
@end example

@item Conexão sem fio
@cindex sem fio
@cindex WiFi
Para configurar a rede sem fio, você pode criar um arquivo de configuração
para a ferramenta de configuração @command{wpa_supplicant} (sua localização
não é importante) usando um dos editores de texto disponíveis, como
@command{nano}:

@example
nano wpa_supplicant.conf
@end example

Como exemplo, a sub-rotina a seguir pode ir para este arquivo e funcionará
para muitas redes sem fio, desde que você forneça o SSID e a senha reais da
rede à qual está se conectando:

@example
network=@{
  ssid="@var{my-ssid}"
  key_mgmt=WPA-PSK
  psk="the network's secret passphrase"
@}
@end example

Inicie o serviço sem fio e execute-o em segundo plano com o seguinte comando
(substitua @var{interface} pelo nome da interface de rede que deseja usar):

@example
wpa_supplicant -c wpa_supplicant.conf -i @var{interface} -B
@end example

Execute @command{man wpa_supplicant} para obter mais informações.
@end table

@cindex DHCP
Neste ponto, você precisa adquirir um endereço IP. Em uma rede onde os
endereços IP são atribuídos automaticamente @i{via} DHCP, você pode
executar:

@example
dhclient -v @var{interface}
@end example

Tente executar ping em um servidor para ver se a rede está funcionando:

@example
ping -c 3 gnu.org
@end example

Configurar o acesso à rede é quase sempre um requisito porque a imagem não
contém todos os softwares e ferramentas que podem ser necessários.

@cindex proxy, durante a instalação do sistema
Se você precisar de acesso HTTP e HTTPS para passar por um proxy, execute o
seguinte comando:

@example
herd set-http-proxy guix-daemon @var{URL}
@end example

@noindent
onde @var{URL} é a URL do proxy, por exemplo @code{http://example.org:8118}.

@cindex instalando via SSH
Se desejar, você pode continuar a instalação remotamente iniciando um
servidor SSH:

@example
herd start ssh-daemon
@end example

Certifique-se de definir uma senha com @command{passwd} ou configurar a
autenticação de chave pública OpenSSH antes de efetuar login.

@subsubsection Particionamento de disco

A menos que isso já tenha sido feito, o próximo passo é particionar e então
formatar a(s) partição(ões) de destino.

A imagem de instalação inclui várias ferramentas de particionamento,
incluindo Parted (@pxref{Overview,,, parted, GNU Parted User Manual}),
@command{fdisk} e @command{cfdisk}. Execute-a e configure seu disco com o
layout de partição que você deseja:

@example
cfdisk
@end example

Se o seu disco usa o formato GUID Partition Table (GPT) e você planeja
instalar o GRUB baseado em BIOS (que é o padrão), certifique-se de que uma
partição de inicialização do BIOS esteja disponível (@pxref{BIOS
installation,,, grub, manual do GNU GRUB}).

@cindex EFI, instalação
@cindex UEFI, instalação
@cindex ESP, partição do sistema EFI
Se você preferir usar o GRUB baseado em EFI, uma partição de sistema EFI
(ESP) FAT32 @dfn{EFI System Partition} é necessária. Essa partição pode ser
montada em @file{/boot/efi}, por exemplo, e deve ter o sinalizador
@code{esp} definido. Por exemplo, para @command{parted}:

@example
parted /dev/sda set 1 esp on
@end example

@quotation Nota
@vindex grub-bootloader
@vindex grub-efi-bootloader
Não tem certeza se deve usar o GRUB baseado em EFI ou BIOS? Se o diretório
@file{/sys/firmware/efi} existir na imagem de instalação, então você
provavelmente deve executar uma instalação EFI, usando
@code{grub-efi-bootloader}. Caso contrário, você deve usar o GRUB baseado em
BIOS, conhecido como @code{grub-bootloader}. @xref{Configuração do carregador de inicialização}, para mais informações sobre bootloaders.
@end quotation

Depois de terminar de particionar o disco rígido de destino, você precisa
criar um sistema de arquivos na(s) partição(ões)
relevante(s)@footnote{Atualmente, o Guix System suporta apenas sistemas de
arquivos ext4, btrfs, JFS, F2FS e XFS. Em particular, o código que lê UUIDs
e rótulos do sistema de arquivos funciona apenas para esses tipos de sistema
de arquivos.}. Para o ESP, se você tiver um e presumindo que seja
@file{/dev/sda1}, execute:

@example
mkfs.fat -F32 /dev/sda1
@end example

Para o sistema de arquivos raiz, ext4 é o formato mais amplamente
usado. Outros sistemas de arquivos, como Btrfs, suportam compressão, que é
relatada como um bom complemento para a desduplicação de arquivos que o
daemon executa independentemente do sistema de arquivos (@pxref{Invocando guix-daemon, deduplication}).

De preferência, atribua um rótulo aos sistemas de arquivos para que você
possa se referir a eles de forma fácil e confiável nas declarações
@code{file-system} (@pxref{Sistemas de arquivos}). Isso normalmente é feito usando a
opção @code{-L} de @command{mkfs.ext4} e comandos relacionados. Então,
assumindo que a partição raiz de destino esteja em @file{/dev/sda2}, um
sistema de arquivos com o rótulo @code{my-root} pode ser criado com:

@example
mkfs.ext4 -L my-root /dev/sda2
@end example

@cindex disco criptografado
Se você estiver planejando criptografar a partição raiz, você pode usar os
utilitários Cryptsetup/LUKS para fazer isso (veja @inlinefmtifelse{html,
@uref{https://linux.die.net/man/8/cryptsetup, @code{man cryptsetup}},
@code{man cryptsetup}} para mais informações).

Supondo que você queira armazenar a partição raiz em @file{/dev/sda2}, a
sequência de comandos para formatá-la como uma partição LUKS seria algo como
isto:

@example
cryptsetup luksFormat /dev/sda2
cryptsetup open /dev/sda2 my-partition
mkfs.ext4 -L my-root /dev/mapper/my-partition
@end example

Feito isso, monte o sistema de arquivos de destino em @file{/mnt} com um
comando como (novamente, assumindo que @code{my-root} é o rótulo do sistema
de arquivos raiz):

@example
mount LABEL=my-root /mnt
@end example

Monte também quaisquer outros sistemas de arquivos que você gostaria de usar
no sistema de destino em relação a este caminho. Se você optou por
@file{/boot/efi} como um ponto de montagem EFI, por exemplo, monte-o em
@file{/mnt/boot/efi} agora para que ele seja encontrado por @code{guix
system init} depois.

Por fim, se você planeja usar uma ou mais partições swap (@pxref{Espaço de troca (swap)}), certifique-se de inicializá-las com @command{mkswap}. Supondo que
você tenha uma partição swap em @file{/dev/sda3}, você executaria:

@example
mkswap /dev/sda3
swapon /dev/sda3
@end example

Alternativamente, você pode usar um arquivo de swap. Por exemplo, supondo
que no novo sistema você queira usar o arquivo @file{/swapfile} como um
arquivo de swap, você executaria @footnote{Este exemplo funcionará para
muitos tipos de sistemas de arquivos (por exemplo, ext4). No entanto, para
sistemas de arquivos copy-on-write (por exemplo, btrfs), as etapas
necessárias podem ser diferentes. Para detalhes, veja as páginas do manual
para @command{mkswap} e @command{swapon}.}:

@example
# Este é 10 GiB de espaço de swap. Ajuste "count" para alterar o tamanho.
dd if=/dev/zero of=/mnt/swapfile bs=1MiB count=10240
# Por segurança, torne o arquivo legível e gravável somente pelo root.
chmod 600 /mnt/swapfile
mkswap /mnt/swapfile
swapon /mnt/swapfile
@end example

Observe que se você criptografou a partição raiz e criou um arquivo de swap
em seu sistema de arquivos, conforme descrito acima, a criptografia também
protegerá o arquivo de swap, assim como qualquer outro arquivo naquele
sistema de arquivos.

@node Prosseguindo com a instalação
@subsection Prosseguindo com a instalação

Com as partições de destino prontas e a raiz de destino montada em
@file{/mnt}, estamos prontos para começar. Primeiro, execute:

@example
herd start cow-store /mnt
@end example

Isso torna @file{/gnu/store} copy-on-write, de modo que os pacotes
adicionados a ele durante a fase de instalação são gravados no disco de
destino em @file{/mnt} em vez de mantidos na memória. Isso é necessário
porque a primeira fase do comando @command{guix system init} (veja abaixo)
envolve downloads ou compilações para @file{/gnu/store} que, inicialmente, é
um sistema de arquivos na memória.

Em seguida, você precisa editar um arquivo e fornecer a declaração do
sistema operacional a ser instalado. Para isso, o sistema de instalação vem
com três editores de texto. Recomendamos o GNU nano (@pxref{Top,,, nano, GNU
nano Manual}), que suporta realce de sintaxe e correspondência de
parênteses; outros editores incluem mg (um clone do Emacs) e nvi (um clone
do editor original BSD @command{vi}). Recomendamos fortemente armazenar esse
arquivo no sistema de arquivos raiz de destino, digamos, como
@file{/mnt/etc/config.scm}. Se isso não for feito, você perderá seu arquivo
de configuração depois de reinicializar o sistema recém-instalado.

@xref{Usando o sistema de configuração}, para uma visão geral do arquivo de
configuração. As configurações de exemplo discutidas nessa seção estão
disponíveis em @file{/etc/configuration} na imagem de instalação. Assim,
para começar com uma configuração de sistema fornecendo um servidor de
exibição gráfica (um sistema ``desktop''), você pode executar algo como
estas linhas:

@example
# mkdir /mnt/etc
# cp /etc/configuration/desktop.scm /mnt/etc/config.scm
# nano /mnt/etc/config.scm
@end example

Você deve prestar atenção ao que seu arquivo de configuração contém e, em
particular:

@itemize
@item
Certifique-se de que o formulário @code{bootloader-configuration} se refere
aos alvos nos quais você deseja instalar o GRUB. Ele deve mencionar
@code{grub-bootloader} se você estiver instalando o GRUB da maneira legada,
ou @code{grub-efi-bootloader} para sistemas UEFI mais novos. Para sistemas
legados, o campo @code{targets} contém os nomes dos dispositivos, como
@code{(list "/dev/sda")}; para sistemas UEFI, ele nomeia os caminhos para
partições EFI montadas, como @code{(list "/boot/efi")}; certifique-se de que
os caminhos estejam montados no momento e que uma entrada @code{file-system}
esteja especificada em sua configuração.

@item
Certifique-se de que os rótulos do seu sistema de arquivos correspondam ao
valor dos respectivos campos @code{device} na sua configuração
@code{file-system}, supondo que sua configuração @code{file-system} use o
procedimento @code{file-system-label} no seu campo @code{device}.

@item
Se houver partições criptografadas ou RAID, certifique-se de adicionar um
campo @code{mapped-devices} para descrevê-las (@pxref{Dispositivos mapeados}).
@end itemize

Depois de terminar de preparar o arquivo de configuração, o novo sistema
deve ser inicializado (lembre-se de que o sistema de arquivos raiz de
destino é montado em @file{/mnt}):

@example
guix system init /mnt/etc/config.scm /mnt
@end example

@noindent
Isso copia todos os arquivos necessários e instala o GRUB em
@file{/dev/sdX}, a menos que você passe a opção
@option{--no-bootloader}. Para mais informações, @pxref{Invocando guix system}. Este comando pode disparar downloads ou compilações de pacotes
ausentes, o que pode levar algum tempo.

Após a conclusão desse comando -- e esperamos que com sucesso! -- você pode
executar o comando @command{reboot} e inicializar no novo sistema. A senha
@code{root} no novo sistema está inicialmente vazia; as senhas de outros
usuários precisam ser inicializadas executando o comando @command{passwd}
como @code{root}, a menos que sua configuração especifique o contrário
(@pxref{user-account-password, senhas de contas de usuário}). @xref{Após a instalação do sistema}, para o que vem a seguir!


@node Após a instalação do sistema
@section Após a instalação do sistema

Success, you've now booted into Guix System! Login to the system using the
non-@code{root} user that you created during installation.  You can upgrade
the system whenever you want by running:

@example
guix pull
sudo guix system reconfigure /etc/config.scm
@end example

@noindent
Isso cria uma nova @dfn{geração} sistema com os pacotes e serviços mais
recentes.

Agora, @pxref{Começando com o Sistema}, junte-se a nós no
@code{#guix} na rede IRC Libera.Chat ou no @email{guix-devel@@gnu.org} para
compartilhar sua experiência!


@node Instalando Guix em uma VM
@section Instalando Guix em uma Máquina Virtual

@cindex máquina virtual, instalação do Guix System
@cindex servidor virtual privado (VPS)
@cindex VPS (servidor virtual privado)
Se você deseja instalar o Guix System em uma máquina virtual (VM) ou em um
servidor virtual privado (VPS) em vez de na sua máquina favorita, esta seção
é para você.

Para inicializar uma VM @uref{https://qemu.org/,QEMU} para instalar o Guix
System em uma imagem de disco, siga estas etapas:

@enumerate
@item
Primeiro, recupere e descompacte a imagem de instalação do sistema Guix
conforme descrito anteriormente (@pxref{Instalação em um pendrive e em DVD}).

@item
Crie uma imagem de disco que irá conter o sistema instalado. Para criar uma
imagem de disco formatada em qcow2, use o comando @command{qemu-img}:

@example
qemu-img create -f qcow2 guix-system.img 50G
@end example

O arquivo resultante será muito menor que 50 GB (normalmente menos de 1 MB),
mas aumentará à medida que o dispositivo de armazenamento virtualizado for
preenchido.

@item
Boot the USB installation image in a VM:

@example
qemu-system-x86_64 -m 1024 -smp 1 -enable-kvm \
  -nic user,model=virtio-net-pci -boot menu=on,order=d \
  -drive file=guix-system.img \
  -drive media=cdrom,readonly=on,file=guix-system-install-@value{VERSION}.@var{sistema}.iso
@end example

@code{-enable-kvm} é opcional, mas melhora significativamente o desempenho,
@pxref{Executando Guix em uma VM}.

@item
Agora você está como root na VM, prossiga com o processo de
instalação. @xref{Preparando para instalação} e siga as instruções.
@end enumerate

Quando a instalação estiver concluída, você pode inicializar o sistema que
está na sua imagem @file{guix-system.img}. @xref{Executando Guix em uma VM}, para
saber como fazer isso.

@node Compilando a imagem de instalação
@section Compilando a imagem de instalação

@cindex imagem de instalação
A imagem de instalação descrita acima foi criada usando o comando
@command{guix system}, especificamente:

@example
guix system image -t iso9660 gnu/system/install.scm
@end example

Dê uma olhada em @file{gnu/system/install.scm} na árvore de origem e veja
também @ref{Invocando guix system} para mais informações sobre a imagem de
instalação.

@section Construindo a imagem de instalação para placas ARM

Muitas placas ARM exigem uma variante específica do bootloader
@uref{https://www.denx.de/wiki/U-Boot/, U-Boot}.

Se você criar uma imagem de disco e o bootloader não estiver disponível de
outra forma (em outra unidade de inicialização, etc.), é aconselhável criar
uma imagem que inclua o bootloader, especificamente:

@example
guix system image --system=armhf-linux -e '((@@ (gnu system install) os-with-u-boot) (@@ (gnu system install) installation-os) "A20-OLinuXino-Lime2")'
@end example

@code{A20-OLinuXino-Lime2} é o nome do quadro. Se você especificar um quadro
inválido, uma lista de quadros possíveis será mostrada.


@c *********************************************************************
@node Começando
@chapter Começando

Presumivelmente, você chegou a esta seção porque instalou o Guix sobre outra
distribuição (@pxref{Instalação}) ou instalou o Guix System autônomo
(@pxref{Instalação do sistema}). É hora de começar a usar o Guix e esta seção
tem como objetivo ajudar você a fazer isso e dar uma ideia de como é.

Guix é sobre instalar software, então provavelmente a primeira coisa que
você vai querer fazer é realmente procurar por software. Digamos que você
esteja procurando por um editor de texto, você pode executar:

@example
guix search text editor
@end example

Este comando mostra a você um número de @dfn{pacotes} correspondentes, cada
vez mostrando o nome do pacote, versão, uma descrição e informações
adicionais. Depois de descobrir qual você quer usar, digamos Emacs (ah ha!),
você pode prosseguir e instalá-lo (execute este comando como um usuário
regular, @emph{não precisa de privilégios de root}!):

@example
guix install emacs
@end example

@cindex perfil
Você instalou seu primeiro pacote, parabéns! O pacote agora está visível no
seu @dfn{perfil} padrão, @file{$HOME/.guix-profile}---um perfil é um
diretório que contém pacotes instalados. No processo, você provavelmente
notou que o Guix baixou binários pré-compilados; ou, se você escolheu
explicitamente @emph{não} usar binários pré-compilados, então provavelmente
o Guix ainda está compilando software (@pxref{Substitutos}, para mais
informações).

A menos que você esteja usando o Guix System, o comando @command{guix
install} deve ter mostrado esta dica:

@example
dica: Considere definir as variáveis de ambiente necessárias executando:

     GUIX_PROFILE="$HOME/.guix-profile"
     . "$GUIX_PROFILE/etc/profile"

Alternativamente, consulte `guix package --search-paths -p "$HOME/.guix-profile"'.
@end example

De fato, agora você deve informar ao seu shell onde @command{emacs} e outros
programas instalados com Guix podem ser encontrados. Colar as duas linhas
acima fará exatamente isso: adicionará @code{$HOME/.guix-profile/bin}---que
é onde o pacote instalado está---à variável de ambiente @code{PATH}. Você
pode colar essas duas linhas no seu shell para que elas entrem em vigor
imediatamente, mas o mais importante é adicioná-las a @file{~/.bash_profile}
(ou arquivo equivalente se você não usar Bash) para que as variáveis de
ambiente sejam definidas na próxima vez que você gerar um shell. Você só
precisa fazer isso uma vez e outras variáveis de ambiente de caminhos de
busca serão cuidadas de forma semelhante---por exemplo, se você
eventualmente instalar @code{python} e bibliotecas Python,
@env{GUIX_PYTHONPATH} será definido.

Você pode continuar instalando pacotes à vontade. Para listar os pacotes
instalados, execute:

@example
guix package --list-installed
@end example

Para remover um pacote, você executaria, sem surpresa, @command{guix
remove}. Um recurso diferenciador é a capacidade de @dfn{reverter} qualquer
operação que você fez---instalação, remoção, atualização---simplesmente
digitando:

@example
guix package --roll-back
@end example

Isso ocorre porque cada operação é, na verdade, uma @dfn{transação} que cria
uma nova @dfn{geração}. Essas gerações e a diferença entre elas podem ser
exibidas executando:

@example
guix package --list-generations
@end example

Agora você conhece os conceitos básicos de gerenciamento de pacotes!

@quotation Indo além
@xref{Gerenciamento de pacote}, para mais informações sobre gerenciamento de
pacotes. Você pode gostar do gerenciamento de pacotes @dfn{declarativo} com
@command{guix package --manifest}, gerenciar @dfn{perfis} separados com
@option{--profile}, excluir gerações antigas, coletar lixo e outros recursos
interessantes que serão úteis à medida que você se familiarizar com o
Guix. Se você for um desenvolvedor, @pxref{Desenvolvimento} para ferramentas
adicionais. E se estiver curioso, @pxref{Recursos}, para dar uma olhada nos
bastidores.

Você também pode gerenciar a configuração de todo o seu ambiente
@dfn{pessoal} --- seus "arquivos dot'' de usuário, serviços e pacotes ---
usando o Guix Home. @xref{Home Configuration}, para saber mais sobre isso!
@end quotation

Depois de instalar um conjunto de pacotes, você vai querer
@emph{atualizá-los} periodicamente para a versão mais recente e melhor. Para
fazer isso, você primeiro vai puxar a revisão mais recente do Guix e sua
coleção de pacotes:

@example
guix pull
@end example

O resultado final é um novo comando @command{guix}, em
@file{~/.config/guix/current/bin}. A menos que você esteja no Guix System,
na primeira vez que você executar @command{guix pull}, certifique-se de
seguir a dica que o comando imprime e, similar ao que vimos acima, cole
estas duas linhas no seu terminal e @file{.bash_profile}:

@example
GUIX_PROFILE="$HOME/.config/guix/current"
. "$GUIX_PROFILE/etc/profile"
@end example

@noindent
Você também deve instruir seu shell a apontar para este novo @command{guix}:

@example
hash guix
@end example

Neste ponto, você está executando um Guix novinho em folha. Você pode então
prosseguir e realmente atualizar todos os pacotes que você instalou
anteriormente:

@example
guix upgrade
@end example

Ao executar este comando, você verá que os binários são baixados (ou talvez
alguns pacotes são construídos) e, eventualmente, você acaba com os pacotes
atualizados. Se um desses pacotes atualizados não for do seu agrado,
lembre-se de que você sempre pode reverter!

Você pode exibir a revisão exata do Guix que está usando atualmente
executando:

@example
guix describe
@end example

As informações exibidas são @emph{tudo o que é necessário para reproduzir
exatamente o mesmo Guix}, seja em um momento diferente ou em uma máquina
diferente.

@quotation Indo além
@xref{Invocando guix pull}, para mais informações. @xref{Canais}, sobre
como especificar @dfn{canais} adicionais para extrair pacotes, como replicar
Guix e muito mais. Você também pode achar @command{time-machine} útil
(@pxref{Invocando guix time-machine}).
@end quotation

Se você instalou o Guix System, uma das primeiras coisas que você vai querer
fazer é atualizar seu sistema. Depois de executar @command{guix pull} para
obter o Guix mais recente, você pode atualizar o sistema assim:

@example
sudo guix system reconfigure /etc/config.scm
@end example

Após a conclusão, o sistema executa as versões mais recentes de seus pacotes
de software. Assim como para pacotes, você sempre pode @emph{reverter} para
uma geração anterior @emph{de todo o sistema}. @xref{Começando com o Sistema}, para aprender como gerenciar seu sistema.

Agora você sabe o suficiente para começar!

@quotation Recursos
O restante deste manual fornece uma referência para todas as coisas do
Guix. Aqui estão alguns recursos adicionais que você pode achar úteis:

@itemize
@item
@xref{Top,,, guix-cookbook.pt_BR, O Livro de Receitas do GNU Guix}, para uma
lista de receitas no estilo "como fazer" para uma variedade de aplicações.

@item
O @uref{https://guix.gnu.org/guix-refcard.pdf, GNU Guix Reference Card}
lista em duas páginas a maioria dos comandos e opções que você precisará.

@item
O site contém @uref{https://guix.gnu.org/en/videos/, vídeos instrucionais}
que abordam tópicos como o uso diário do Guix, como obter ajuda e como se
tornar um colaborador.

@item
@xref{Documentação}, para aprender como acessar a documentação no seu
computador.
@end itemize

Esperamos que você goste do Guix tanto quanto a comunidade gosta de criá-lo!
@end quotation

@c *********************************************************************
@node Gerenciamento de pacote
@chapter Gerenciamento de pacote

@cindex pacotes
O propósito do GNU Guix é permitir que os usuários instalem, atualizem e
removam facilmente pacotes de software, sem precisar saber sobre seus
procedimentos de construção ou dependências. O Guix também vai além desse
conjunto óbvio de recursos.

Este capítulo descreve os principais recursos do Guix, bem como as
ferramentas de gerenciamento de pacotes que ele fornece. Junto com a
interface de linha de comando descrita abaixo (@pxref{Invocando guix package,
@code{guix package}}), você também pode usar a interface Emacs-Guix
(@pxref{Top,,, emacs-guix, The Emacs-Guix Reference Manual}), após instalar
o pacote @code{emacs-guix} (execute o comando @kbd{M-x guix-help} para
começar com ele):

@example
guix install emacs-guix
@end example

@menu
* Recursos::                 Como o Guix vai iluminar a sua vida.
* Invocando guix package::   Instalação de pacote, remoção, etc.
* Substitutos::              Baixando binários pré-compilados.
* Pacotes com múltiplas saídas::  Um único pacote de fontes, várias saídas.
* Invocando guix locate::    Localizando pacotes que fornecem um arquivo.
* Invocando guix gc::        Executando o coletor de lixo.
* Invocando guix pull::      Obtendo o Guix mais recente e distribuição.
* Invocando guix time-machine::  Executando uma revisão mais antiga do Guix.
* Inferiores::               Interagindo com outra revisão do Guix.
* Invocando guix describe::  Exibe informações sobre sua revisão do Guix.
* Invocando guix archive::   Exportando e importando arquivos do armazém.
@end menu

@node Recursos
@section Recursos

Aqui presumimos que você já deu os primeiros passos com o Guix
(@pxref{Começando}) e gostaria de ter uma visão geral do que está
acontecendo nos bastidores.

Ao usar o Guix, cada pacote acaba no @dfn{armazém de pacotes}, em seu
próprio diretório — algo que lembra @file{/gnu/store/xxx-package-1.2}, onde
@code{xxx} é uma string base32.

Em vez de se referir a esses diretórios, os usuários têm seu próprio
@dfn{perfil}, que aponta para os pacotes que eles realmente querem
usar. Esses perfis são armazenados dentro do diretório pessoal de cada
usuário, em @code{$HOME/.guix-profile}.

Por exemplo, @code{alice} instala o GCC 4.7.2. Como resultado,
@file{/home/alice/.guix-profile/bin/gcc} aponta para
@file{/gnu/store/@dots{}-gcc-4.7.2/bin/gcc}. Agora, na mesma máquina,
@code{bob} já tinha instalado o GCC 4.8.0. O perfil de @code{bob}
simplesmente continua a apontar para
@file{/gnu/store/@dots{}-gcc-4.8.0/bin/gcc}---ou seja, ambas as versões do
GCC coexistem no mesmo sistema sem nenhuma interferência.

O comando @command{guix package} é a ferramenta central para gerenciar
pacotes (@pxref{Invocando guix package}). Ele opera nos perfis por usuário e
pode ser usado @emph{com privilégios normais de usuário}.

@cindex transações
O comando fornece as operações óbvias de instalação, remoção e
atualização. Cada invocação é, na verdade, uma @emph{transação}: ou a
operação especificada é bem-sucedida ou nada acontece. Portanto, se o
processo @command{guix package} for encerrado durante a transação, ou se
ocorrer uma queda de energia durante a transação, o perfil do usuário
permanecerá em seu estado anterior e continuará utilizável.

Além disso, qualquer transação de pacote pode ser @emph{revertida}. Então,
se, por exemplo, uma atualização instalar uma nova versão de um pacote que
acabe tendo um bug sério, os usuários podem reverter para a instância
anterior de seu perfil, que era conhecida por funcionar bem. Da mesma forma,
a configuração global do sistema no Guix está sujeita a atualizações
transacionais e roll-back (@pxref{Começando com o Sistema}).

Todos os pacotes no repositório de pacotes podem ser
@emph{garbage-collected}. O Guix pode determinar quais pacotes ainda são
referenciados por perfis de usuário e remover aqueles que comprovadamente
não são mais referenciados (@pxref{Invocando guix gc}). Os usuários também
podem remover explicitamente gerações antigas de seus perfis para que os
pacotes aos quais eles se referem possam ser coletados.

@cindex reprodutibilidade
@cindex compilações reproduzíveis
Guix adota uma abordagem @dfn{puramente funcional} para gerenciamento de
pacotes, conforme descrito na introdução (@pxref{Introdução}). Cada nome
de diretório de pacote @file{/gnu/store} contém um hash de todas as entradas
que foram usadas para construir aquele pacote---compilador, bibliotecas,
scripts de construção, etc. Essa correspondência direta permite que os
usuários tenham certeza de que uma determinada instalação de pacote
corresponde ao estado atual de sua distribuição. Também ajuda a maximizar a
@dfn{reprodutibilidade da construção}: graças aos ambientes de construção
isolados que são usados, uma determinada construção provavelmente produzirá
arquivos de bits idênticos quando executada em máquinas diferentes
(@pxref{Invocando guix-daemon, container}).

@cindex substitutos
Essa base permite que o Guix suporte @dfn{transparent binary/source
deployment}. Quando um binário pré-construído para um item @file{/gnu/store}
está disponível em uma fonte externa---um @dfn{substituto}, o Guix apenas o
baixa e descompacta; caso contrário, ele constrói o pacote a partir da
fonte, localmente (@pxref{Substitutos}). Como os resultados da construção
são geralmente reproduzíveis bit a bit, os usuários não precisam confiar em
servidores que fornecem substitutos: eles podem forçar uma construção local
e @emph{desafiar} os provedores (@pxref{Invocando guix challenge}).

O controle sobre o ambiente de construção é um recurso que também é útil
para desenvolvedores. O comando @command{guix shell} permite que os
desenvolvedores de um pacote configurem rapidamente o ambiente de
desenvolvimento correto para seu pacote, sem ter que instalar manualmente as
dependências do pacote em seu perfil (@pxref{Invocando guix shell}).

@cindex replicação, de ambientes de software
@cindex rastreamento de proveniência, de artefatos de software
Todo o Guix e suas definições de pacote são controlados por versão, e
@command{guix pull} permite que você "viaje no tempo'' no histórico do
próprio Guix (@pxref{Invocando guix pull}). Isso torna possível replicar uma
instância do Guix em uma máquina diferente ou em um ponto posterior no
tempo, o que por sua vez permite que você @emph{replique ambientes de
software completos}, enquanto retém o @dfn{rastreamento de procedência}
preciso do software.

@node Invocando guix package
@section Invocando @command{guix package}

@cindex instalando pacotes
@cindex removendo pacotes
@cindex instalação de pacote
@cindex remoção de pacote
@cindex perfil
@cindex @command{guix package}
O comando @command{guix package} é a ferramenta que permite aos usuários
instalar, atualizar e remover pacotes, bem como reverter para configurações
anteriores. Essas operações funcionam no @dfn{perfil} de um usuário---um
diretório de pacotes instalados. Cada usuário tem um perfil padrão em
@file{$HOME/.guix-profile}. O comando opera apenas no próprio perfil do
usuário e funciona com privilégios de usuário normais
(@pxref{Recursos}). Sua sintaxe é:

@example
guix package @var{opções}
@end example

@cindex transações
Principalmente, @var{opções} especifica as operações a serem executadas
durante a transação. Após a conclusão, um novo perfil é criado, mas as
@dfn{gerações} anteriores do perfil permanecem disponíveis, caso o usuário
queira reverter.

Por exemplo, para remover @code{lua} e instalar @code{guile} e
@code{guile-cairo} em uma única transação:

@example
guix package -r lua -i guile guile-cairo
@end example

@cindex aliases, para @command{guix package}
Para sua conveniência, também fornecemos os seguintes aliases:

@itemize
@item
@command{guix search} é um alias para @command{guix package -s},
@item
@command{guix install} é um alias para @command{guix package -i},
@item
@command{guix remove} é um alias para @command{guix package -r},
@item
@command{guix upgrade} é um alias para @command{guix package -u},
@item
e @command{guix show} é um alias para @command{guix package --show=}.
@end itemize

Esses aliases são menos expressivos que @command{guix package} e oferecem
menos opções, então em alguns casos você provavelmente desejará usar
@command{guix package} diretamente.

@command{guix package} também suporta uma @dfn{abordagem declarativa} em que
o usuário especifica o conjunto exato de pacotes que estarão disponíveis e
passa a ele @i{via} a opção @option{--manifest} (@pxref{profile-manifest,
@option{--manifest}}).

@cindex perfil
Para cada usuário, uma ligação simbólica para o perfil padrão do usuário é
criado automaticamente em @file{$HOME/.guix-profile}. Esta ligação simbólico
sempre aponta para a geração atual do perfil padrão do usuário. Assim, os
usuários podem adicionar @file{$HOME/.guix-profile/bin} à sua variável de
ambiente @env{PATH} e assim por diante.
@cindex caminhos de pesquisa
Se você não estiver usando o sistema Guix, considere adicionar as seguintes
linhas ao seu @file{~/.bash_profile} (@pxref{Bash Startup Files,,, bash,
Manual de referência do GNU Bash}) para que os shells recém-gerados obtenham
todos as definições corretas de variáveis de ambiente:

@example
GUIX_PROFILE="$HOME/.guix-profile" ; \
source "$GUIX_PROFILE/etc/profile"
@end example

Em uma configuração multiusuário, os perfis de usuário são armazenados em um
local registrado como @dfn{raiz do coletor de lixo}, para o qual
@file{$HOME/.guix-profile} aponta (@pxref{Invocando guix gc}). Esse diretório
geralmente é
@code{@var{localstatedir}/guix/profiles/per-user/@var{usuário}}, onde
@var{localstatedir} é o valor passado para @code{configure} como @option{--
localstatedir} e @var{usuário} é o nome do usuário. O diretório
@file{per-user} é criado quando @command{guix-daemon} é iniciado, e o
subdiretório @var{usuário} é criado por @command{guix package}.

As seguintes @var{opções} podem ser usadas:

@table @code

@item --install=@var{pacote} @dots{}
@itemx -i @var{pacote} @dots{}
Instale os @var{pacote}s especificados.

Cada @var{pacote} pode especificar um nome de pacote simples como
@code{guile}, opcionalmente seguido por uma arroba e número de versão, como
@code{guile@@3.0.7} ou simplesmente @code{guile@@3.0}. Neste último caso, a
versão mais recente prefixada por @code{3.0} é selecionada.

Se nenhum número de versão for especificado, a versão mais recente
disponível será selecionada. Além disso, tal especificação @var{pacote} pode
conter dois pontos, seguido pelo nome de uma das saídas do pacote, como em
@code{gcc:doc} ou @code{binutils@@2.22:lib} (@pxref{Pacotes com múltiplas saídas}).

Pacotes com um nome correspondente (e opcionalmente versão) são procurados
entre os módulos de distribuição GNU (@pxref{Módulos de pacote}).

Alternativamente, um @var{pacote} pode especificar diretamente um nome de
arquivo de armazém como @file{/gnu/store/...-guile-3.0.7}, conforme
produzido por, por exemplo, @code{guix build}.

@cindex entradas propagadas
Às vezes, os pacotes têm @dfn{propagated-inputs}: são dependências que são
instaladas automaticamente junto com o pacote necessário
(@pxref{package-propagated-inputs, @code{propagated-inputs} em
@code{package} objetos}, para obter informações sobre entradas propagadas em
definições de pacote).

@anchor{package-cmd-propagated-inputs}
Um exemplo é a biblioteca GNU MPC: seus arquivos de cabeçalho C referem-se
aos da biblioteca GNU MPFR, que por sua vez se refere aos da biblioteca
GMP. Assim, ao instalar o MPC, as bibliotecas MPFR e GMP também são
instaladas no perfil; a remoção do MPC também remove o MPFR e o GMP --- a
menos que eles também tenham sido explicitamente instalados pelo usuário.

Além disso, os pacotes às vezes dependem da definição de variáveis de
ambiente para seus caminhos de pesquisa (veja a explicação de
@option{--search-paths} abaixo). Quaisquer definições de variáveis
ambientais ausentes ou possivelmente incorretas são relatadas aqui.

@item --install-from-expression=@var{exp}
@itemx -e @var{exp}
Instale o pacote avaliado por @var{exp}.

@var{exp} deve ser uma expressão de Scheme avaliada como um objeto
@code{<package>}. Esta opção é particularmente útil para desambiguar
variantes de um pacote com o mesmo nome, com expressões como @code{(@@(gnu
packages commencement) guile-final)}.

Observe que esta opção instala a primeira saída do pacote especificado, o
que pode ser insuficiente quando for necessária uma saída específica de um
pacote de múltiplas saídas.

@item --install-from-file=@var{arquivo}
@itemx -f @var{arquivo}
Instale o pacote avaliado pelo código em @var{arquivo}.

Por exemplo, @var{arquivo} pode conter uma definição como esta
(@pxref{Definindo pacotes}):

@lisp
@include package-hello.scm
@end lisp

Os desenvolvedores podem achar útil incluir um arquivo @file{guix.scm} na
raiz da árvore de origem do projeto que pode ser usado para testar
instantâneos de desenvolvimento e criar ambientes de desenvolvimento
reproduzíveis (@pxref{Invocando guix shell}).

O @var{arquivo} também pode conter uma representação JSON de uma ou mais
definições de pacote. Executar @code{guix package -f} em @file{hello.json}
com o seguinte conteúdo resultaria na instalação do pacote @code{greeter}
após construir @code{myhello}:

@example
@verbatiminclude package-hello.json
@end example

@item --remove=@var{pacote} @dots{}
@itemx -r @var{pacote} @dots{}
Remova os @var{pacote}s especificados.

Quanto a @option{--install}, cada @var{pacote} pode especificar um número de
versão e/ou nome de saída além do nome do pacote. Por exemplo, @samp{-r
glibc:debug} removeria a saída de @code{glibc}.

@item --upgrade[=@var{regexp} @dots{}]
@itemx -u [@var{regexp} @dots{}]
@cindex atualização de pacotes
Atualize todos os pacotes instalados. Se um ou mais @var{regexp}s forem
especificados, atualize apenas os pacotes instalados cujo nome corresponda a
um @var{regexp}. Veja também a opção @option{--do-not-upgrade} abaixo.

Note que isso atualiza o pacote para a versão mais recente dos pacotes
encontrados na distribuição atualmente instalada. Para atualizar sua
distribuição, você deve executar regularmente @command{guix pull}
(@pxref{Invocando guix pull}).

@cindex transformações de pacotes, atualizações
Ao atualizar, as transformações de pacote que foram aplicadas originalmente
ao criar o perfil são automaticamente reaplicadas (@pxref{Opções de transformação de pacote}). Por exemplo, suponha que você instalou o Emacs
pela ponta do seu branch de desenvolvimento com:

@example
guix install emacs-next --with-branch=emacs-next=master
@end example

Na próxima vez que você executar @command{guix upgrade}, o Guix puxará
novamente a ponta do branch de desenvolvimento do Emacs e compilará
@code{emacs-next} a partir desse checkout.

Observe que opções de transformação como @option{--with-branch} e
@option{--with-source} dependem do estado externo; cabe a você garantir que
elas funcionem conforme o esperado. Você também pode descartar
transformações que se aplicam a um pacote executando:

@example
guix install @var{pacote}
@end example

@item --do-not-upgrade[=@var{regexp} @dots{}]
Quando usado junto com a opção @option{--upgrade}, @emph{não} atualize
nenhum pacote cujo nome corresponda a um @var{regexp}. Por exemplo, para
atualizar todos os pacotes no perfil atual, exceto aqueles que contêm a
substring "emacs'':

@example
$ guix package --upgrade . --do-not-upgrade emacs
@end example

@item @anchor{profile-manifest}--manifest=@var{arquivo}
@itemx -m @var{arquivo}
@cindex declaração de perfil
@cindex manifesto de perfil
Crie uma nova geração do perfil a partir do objeto manifest retornado pelo
código Scheme em @var{arquivo}. Esta opção pode ser repetida várias vezes,
em cujo caso os manifestos são concatenados.

Isso permite que você @emph{declarando} o conteúdo do perfil em vez de
construí-lo por meio de uma sequência de @option{--install} e comandos
similares. A vantagem é que @var{arquivo} pode ser colocado sob controle de
versão, copiado para máquinas diferentes para reproduzir o mesmo perfil, e
assim por diante.

@var{arquivo} deve retornar um objeto @dfn{manifest}, que é aproximadamente
uma lista de pacotes:

@findex packages->manifest
@lisp
(use-package-modules guile emacs)

(packages->manifest
 (list emacs
       guile-2.0
       ;; Usa uma saída de pacote específica.
       (list guile-2.0 "debug")))
@end lisp

@xref{Escrevendo manifestos}, para obter informações sobre como escrever um
manifesto. @xref{export-manifest, @option{--export-manifest}}, para aprender
como obter um arquivo de manifesto de um perfil existente.

@item --roll-back
@cindex revertendo
@cindex desfazendo transações
@cindex transações, desfazendo
Reverta para a @dfn{geração} anterior do perfil, ou seja, desfaça a última
transação.

Quando combinado com opções como @option{--install}, a reversão ocorre antes
de qualquer outra ação.

Ao reverter da primeira geração que realmente contém pacotes instalados, o
perfil é feito para apontar para a @dfn{geração zero}, que não contém
arquivos além de seus próprios metadados.

Após ter revertido, instalar, remover ou atualizar pacotes sobrescreve
gerações futuras anteriores. Assim, o histórico das gerações em um perfil é
sempre linear.

@item --switch-generation=@var{padrão}
@itemx -S @var{padrão}
@cindex gerações
Mude para uma geração específica definida por @var{padrão}.

@var{padrão} pode ser um número de geração ou um número prefixado com "+''
ou "-''. O último significa: mover para frente/para trás por um número
especificado de gerações. Por exemplo, se você quiser retornar para a última
geração após @option{--roll-back}, use @option{--switch-generation=+1}.

A diferença entre @option{--roll-back} e @option{--switch-generation=-1} é
que @option{--switch-generation} não fará uma geração zero, então se uma
geração especificada não existir, a geração atual não será alterada.

@item --search-paths[=@var{tipo}]
@cindex caminhos de pesquisa
Relata definições de variáveis de ambiente, na sintaxe Bash, que podem ser
necessárias para usar o conjunto de pacotes instalados. Essas variáveis de
ambiente são usadas para especificar @dfn{caminhos de busca} para arquivos
usados por alguns dos pacotes instalados.

Por exemplo, o GCC precisa que as variáveis de ambiente @env{CPATH} e
@env{LIBRARY_PATH} sejam definidas para que ele possa procurar cabeçalhos e
bibliotecas no perfil do usuário (@pxref{Environment Variables,,, gcc,
Usando o GNU Compiler Collection (GCC)}). Se o GCC e, digamos, a biblioteca
C estiverem instalados no perfil, então @option{--search-paths} sugerirá
definir essas variáveis como @file{@var{perfil}/include} e
@file{@var{perfil}/lib}, respectivamente (@pxref{Caminhos de pesquisa}, para obter
informações sobre especificações de caminho de pesquisa associadas a
pacotes.)

O caso de uso típico é definir essas variáveis de ambiente no shell:

@example
$ eval $(guix package --search-paths)
@end example

@var{tipo} pode ser um dos seguintes: @code{exact}, @code{prefix} ou
@code{suffix}, o que significa que as definições de variáveis de ambiente
retornadas serão configurações exatas ou prefixos ou sufixos do valor atual
dessas variáveis. Quando omitido, @var{tipo} assume como padrão
@code{exact}.

Esta opção também pode ser usada para calcular os caminhos de busca
@emph{combinados} de vários perfis. Considere este exemplo:

@example
$ guix package -p foo -i guile
$ guix package -p bar -i guile-json
$ guix package -p foo -p bar --search-paths
@end example

O último comando acima relata sobre a variável @env{GUILE_LOAD_PATH},
embora, considerados individualmente, nem @file{foo} nem @file{bar} levariam
a essa recomendação.


@cindex profile, choosing
@item --profile=@var{perfil}
@itemx -p @var{perfil}
Use @var{perfil} em vez do perfil padrão do usuário.

@var{perfil} deve ser o nome de um arquivo que será criado após a
conclusão. Concretamente, @var{perfil} será uma mera ligação simbólica
("symlink'') apontanda para o perfil real onde os pacotes estão instalados:

@example
$ guix install hello -p ~/code/my-profile
@dots{}
$ ~/code/my-profile/bin/hello
Olá, mundo!
@end example

Tudo o que é preciso para se livrar do perfil é remover este link simbólico
e seus irmãos que apontam para gerações específicas:

@example
$ rm ~/code/my-profile ~/code/my-profile-*-link
@end example

@item --list-profiles
Liste todos os perfis dos usuários:

@example
$ guix package --list-profiles
/home/charlie/.guix-profile
/home/charlie/code/my-profile
/home/charlie/code/devel-profile
/home/charlie/tmp/test
@end example

Ao executar como root, liste todos os perfis de todos os usuários.

@cindex colisões, em um perfil
@cindex pacotes colidindo em perfis
@cindex colisões de perfil
@item --allow-collisions
Permitir pacotes de colisão no novo perfil. Use por sua conta e risco!

Por padrão, @command{guix package} relata como um erro @dfn{collisions} no
perfil. Colisões acontecem quando duas ou mais versões ou variantes
diferentes de um determinado pacote acabam no perfil.

@item --bootstrap
Use o bootstrap Guile para construir o perfil. Esta opção é útil somente
para desenvolvedores de distribuição.

@end table

Além dessas ações, @command{guix package} suporta as seguintes opções para
consultar o estado atual de um perfil ou a disponibilidade de pacotes:

@table @option

@item --search=@var{regexp}
@itemx -s @var{regexp}
@anchor{guix-search}
@cindex procurando por pacotes
Liste os pacotes disponíveis cujo nome, sinopse ou descrição correspondem a
@var{regexp} (sem distinção entre maiúsculas e minúsculas), classificados
por relevância. Imprima todos os metadados dos pacotes correspondentes no
formato @code{recutils} (@pxref{Top, bancos de dados GNU recutils,,
recutils, manual GNU recutils}).

Isso permite que campos específicos sejam extraídos usando o comando
@command{recsel}, por exemplo:

@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

Da mesma forma, para mostrar o nome de todos os pacotes disponíveis sob os
termos da GNU@tie{}LGPL versão 3:

@example
$ guix package -s "" | recsel -p name -e 'license ~ "LGPL 3"'
name: elfutils

name: gmp
@dots{}
@end example

Também é possível refinar os resultados da pesquisa usando vários
sinalizadores @code{-s} para @command{guix package}, ou vários argumentos
para @command{guix search}. Por exemplo, o comando a seguir retorna uma
lista de jogos de tabuleiro (desta vez usando o alias @command{guix
search}):

@example
$ guix search '\<board\>' game | recsel -p name
name: gnubg
@dots{}
@end example

Se omitissemos @code{-s game}, também teríamos pacotes de software que lidam
com placas de circuito impresso; remover os colchetes angulares em torno de
@code{board} adicionaria ainda mais pacotes relacionados a teclados.

E agora um exemplo mais elaborado. O comando a seguir procura bibliotecas
criptográficas, filtra as bibliotecas Haskell, Perl, Python e Ruby e imprime
o nome e a sinopse dos pacotes correspondentes:

@example
$ guix search crypto library | \
    recsel -e '! (name ~ "^(ghc|perl|python|ruby)")' -p name,synopsis
@end example

@noindent
@xref{Selection Expressions,,, recutils, manual GNU recutils}, para obter
mais informações sobre @dfn{expressões de seleção} para @code{recsel -e}.

@item --show=@var{pacote}
Exibe detalhes sobre @var{pacote}, retirados da lista de pacotes
disponíveis, no formato @code{recutils} (@pxref{Top,GNU Recutils Databases,,
recutils, GNU Recutils Manual}).

@example
$ guix package --show=guile | recsel -p name,version
name: guile
version: 3.0.5

name: guile
version: 3.0.2

name: guile
version: 2.2.7
@dots{}
@end example

Você também pode especificar o nome completo de um pacote para obter
detalhes apenas sobre uma versão específica dele (desta vez usando o alias
@command{guix show}):
@example
$ guix show guile@@3.0.5 | recsel -p name,version
name: guile
version: 3.0.5
@end example

@item --list-installed[=@var{regexp}]
@itemx -I [@var{regexp}]
Lista os pacotes instalados mais recentemente no perfil especificado, com os
pacotes instalados mais recentemente mostrados por último. Quando
@var{regexp} for especificado, liste apenas os pacotes instalados cujo nome
corresponda a @var{regexp}.

Para cada pacote instalado, imprima os seguintes itens, separados por
tabulações: o nome do pacote, sua string de versão e a parte do pacote que
está instalada (por exemplo, @code{out} para a saída predefinida,
@code{include} para os seus cabeçalhos, etc.) e o caminho deste pacote no
armazém.

@item --list-available[=@var{regexp}]
@itemx -A [@var{regexp}]
Lista de pacotes atualmente disponíveis na distribuição para este sistema
(@pxref{Distribuição GNU}). Quando @var{regexp} for especificado, liste
apenas os pacotes disponíveis cujo nome corresponda a @var{regexp}.

Para cada pacote, imprima os seguintes itens separados por tabulações: seu
nome, sua string de versão, as partes do pacote (@pxref{Pacotes com múltiplas saídas}) e o local de origem de sua definição.

@item --list-generations[=@var{padrão}]
@itemx -l [@var{padrão}]
@cindex gerações
Retorne uma lista de gerações junto com suas datas de criação; para cada
geração, exiba os pacotes instalados, com os pacotes instalados mais
recentemente mostrados por último. Observe que a geração zero nunca é
mostrada.

Para cada pacote instalado, mostre os seguintes itens, separados por
tabulações: o nome de um pacote, sua string de versão, a parte do pacote que
está instalada (@pxref{Pacotes com múltiplas saídas}) e a localização
deste pacote em o armazém.

Quando @var{padrão} é usado, o comando retorna apenas gerações
correspondentes. Os padrões válidos incluem:

@itemize
@item @emph{Inteiros e números inteiros separados por vírgula}. Ambos os padrões denotam
números de geração. Por exemplo, @option{--list-generations=1} retorna o
primeiro.

E @option{--list-generations=1,8,2} gera três gerações na ordem
especificada. Não são permitidos espaços nem vírgulas finais.

@item @emph{Intervalos}. @option{--list-generations=2..9} mostra o
gerações especificadas e tudo mais. Observe que o início de um intervalo
deve ser menor que o seu final.

Também é possível omitir o ponto final. Por exemplo,
@option{--list-generations=2..} retorna todas as gerações começando pela
segunda.

@item @emph{Duração}. Você também pode visitar os últimos @emph{N}@tie{}dias, semanas,
ou meses passando um número inteiro junto com a primeira letra da
duração. Por exemplo, @option{--list-generations=20d} lista gerações com até
20 dias.
@end itemize

@item --delete-generations[=@var{padrão}]
@itemx -d [@var{padrão}]
Quando @var{padrão} for omitido, exclua todas as gerações, exceto a atual.

Este comando aceita os mesmos padrões de @option{--list-Generations}. Quando
@var{pattern} for especificado, exclua as gerações correspondentes. Quando
@var{padrão} especifica uma duração, as gerações @emph{mais antigas} que a
duração especificada correspondem. Por exemplo,
@option{--delete-generations=1m} exclui gerações com mais de um mês.

Se a geração atual corresponder, ela será @emph{não} excluída. Além disso, a
geração zero nunca é excluída.

Observe que a exclusão de gerações impede a reversão para
elas. Conseqüentemente, este comando deve ser usado com cuidado.

@cindex manifesto, exportando
@anchor{export-manifest}
@item --export-manifest
Escreva na saída padrão um manifesto adequado para @option{--manifest}
correspondente ao(s) perfil(s) selecionado(s).

Esta opção destina-se a ajudá-lo a migrar do modo operacional "imperativo''
--- executando @command{guix install}, @command{guix upgrade}, etc.---para o
modo declarativo que @option{--manifest} ofertas.

Observe que o manifesto resultante @emph{aproxima} o que seu perfil
realmente contém; por exemplo, dependendo de como seu perfil foi criado, ele
pode se referir a pacotes ou versões de pacotes que não são exatamente o que
você especificou.

Tenha em mente que um manifesto é puramente simbólico: ele contém apenas
nomes de pacotes e possivelmente versões, e seu significado varia com o
tempo. Se você quiser ``fixar'' canais nas revisões que foram usadas para
construir o(s) perfil(es), veja @option{--export-channels} abaixo.

@cindex fixação, revisões de canal de um perfil
@item --export-channels
Escreva na saída padrão a lista de canais usados pelo(s) perfil(s)
selecionado(s), em um formato adequado para @command{guix pull --channels}
ou @command{guix time-machine --channels} (@pxref{Canais}) . .

Juntamente com @option{--export-manifest}, esta opção fornece informações
que permitem replicar o perfil atual (@pxref{Replicando Guix}).

No entanto, observe que a saída deste comando @emph{aproxima} o que foi
realmente usado para construir este perfil. Em particular, um único perfil
pode ter sido construído a partir de diversas revisões diferentes do mesmo
canal. Nesse caso, @option{--export-manifest} escolhe a última e escreve a
lista de outras revisões em um comentário. Se você realmente precisa
escolher pacotes de análises de canais diferentes, você pode usar inferiores
em seu manifesto para fazer isso (@pxref{Inferiores}).

Juntamente com @option{--export-manifest}, este é um bom ponto de partida se
você estiver disposto a migrar do modelo "imperativo" para o modelo
totalmente declarativo que consiste em um arquivo de manifesto junto com um
arquivo de canais fixando o canal exato revisão(ões) que você deseja.
@end table

Finalmente, como @command{guix package} pode realmente iniciar processos de
construção, ele suporta todas as opções de construção comuns (@pxref{Opções de compilação comuns}). Ele também oferece suporte a opções de transformação de
pacotes, como @option{--with-source}, e as preserva em atualizações
(@pxref{Opções de transformação de pacote}).

@node Substitutos
@section Substitutos

@cindex substitutos
@cindex binários pré-construídos
Guix suporta implantação transparente de origem/binário, o que significa que
ele pode construir coisas localmente ou baixar itens pré-construídos de um
servidor, ou ambos. Chamamos esses itens pré-construídos de
@dfn{substitutos}---eles são substitutos para resultados de construção
local. Em muitos casos, baixar um substituto é muito mais rápido do que
construir coisas localmente.

Substitutos podem ser qualquer coisa resultante de uma construção de
derivação (@pxref{Derivações}). Claro, no caso comum, eles são binários de
pacotes pré-construídos, mas tarballs de origem, por exemplo, que também
resultam de construções de derivação, podem estar disponíveis como
substitutos.

@menu
* Official Substitute Servers::  Uma fonte específica de substitutos.
* Autorização de servidor substituto::  Como habilitar ou desabilitar 
                                          substitutos.
* Obtendo substitutos de outros servidores::  Diversidade de substitutos.
* Autenticação de substituto::  Como Guix verifica substitutos.
* Configurações de proxy::   Como obter substitutos via proxy.
* Falha na substituição::    O que acontece quando a substituição falha.
* Confiança em binários::    Como você pode confiar naquele blob binário?
@end menu

@node Official Substitute Servers
@subsection Official Substitute Servers

@cindex fazenda de compilação
@code{@value{SUBSTITUTE-SERVER-1}} e @code{@value{SUBSTITUTE-SERVER-2}} são
ambos front-ends para farms de build oficiais que constroem pacotes do Guix
continuamente para algumas arquiteturas e os disponibilizam como
substitutos. Essas são a fonte padrão de substitutos; que podem ser
substituídos passando a opção @option{--substitute-urls} para
@command{guix-daemon} (@pxref{daemon-substitute-urls,, @code{guix-daemon
--substitute-urls}}) ou para ferramentas de cliente como @command{guix
package} (@pxref{client-substitute-urls,, client @option{--substitute-urls}
option}).

URLs substitutos podem ser HTTP ou HTTPS. HTTPS é recomendado porque as
comunicações são criptografadas; por outro lado, usar HTTP torna todas as
comunicações visíveis para um bisbilhoteiro, que pode usar as informações
coletadas para determinar, por exemplo, se seu sistema tem vulnerabilidades
de segurança não corrigidas.

Substitutos das build farms oficiais são habilitados por padrão ao usar o
Guix System (@pxref{Distribuição GNU}). No entanto, eles são desabilitados
por padrão ao usar o Guix em uma distribuição estrangeira, a menos que você
os tenha habilitado explicitamente por meio de uma das etapas de instalação
recomendadas (@pxref{Instalação}). Os parágrafos a seguir descrevem como
habilitar ou desabilitar substitutos para a build farm oficial; o mesmo
procedimento também pode ser usado para habilitar substitutos para qualquer
outro servidor substituto.

@node Autorização de servidor substituto
@subsection Autorização de servidor substituto

@cindex segurança
@cindex substitutos, autenticação dela
@cindex lista de controle de acesso (ACL), para substitutos
@cindex ACL (lista de controle de acesso), para substitutos
Para permitir que o Guix baixe substitutos de
@code{@value{SUBSTITUTE-SERVER-1}}, @code{@value{SUBSTITUTE-SERVER-2}} ou um
espelho, você deve adicionar a chave pública relevante à lista de controle
de acesso (ACL) de importações de arquivo, usando o comando @command{guix
archive} (@pxref{Invocando guix archive}). Fazer isso implica que você confia
que o servidor substituto não será comprometido e servirá substitutos
genuínos.

@quotation Nota
Se você estiver usando o Guix System, pode pular esta seção: O Guix System
autoriza substitutos de @code{@value{SUBSTITUTE-SERVER-1}} e
@code{@value{SUBSTITUTE-SERVER-2}} por padrão.
@end quotation

As chaves públicas para cada um dos servidores substitutos mantidos pelo
projeto são instaladas junto com o Guix, em @code{@var{prefix}/share/guix/},
onde @var{prefix} é o prefixo de instalação do Guix. Se você instalou o Guix
a partir da fonte, certifique-se de verificar a assinatura GPG de
@file{guix-@value{VERSION}.tar.gz}, que contém este arquivo de chave
pública. Então, você pode executar algo como isto:

@example
# guix archive --authorize < @var{prefix}/share/guix/@value{SUBSTITUTE-SERVER-1}.pub
# guix archive --authorize < @var{prefix}/share/guix/@value{SUBSTITUTE-SERVER-2}.pub
@end example

Uma vez que isso esteja pronto, a saída de um comando como @code{guix build}
deve mudar de algo como:

@example
$ guix build emacs --dry-run
A seguinte derivações seriam compiladas:
   /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
para algo como:

@example
$ guix build emacs --dry-run
112.3 MB seriam baixados:
   /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
O texto mudou de "As seguintes derivações seriam construídas'' para "112,3
MB seriam baixados''. Isso indica que os substitutos dos servidores
substitutos configurados são utilizáveis e serão baixados, quando possível,
para construções futuras.

@cindex substitutos, como desabilitar
O mecanismo de substituição pode ser desabilitado globalmente executando
@code{guix-daemon} com @option{--no-substitutes} (@pxref{Invocando guix-daemon}). Ele também pode ser desabilitado temporariamente passando a
opção @option{--no-substitutes} para @command{guix package}, @command{guix
build} e outras ferramentas de linha de comando.

@node Obtendo substitutos de outros servidores
@subsection Obtendo substitutos de outros servidores
@c Note: This section name appears in a hint printed by 'guix weather'.

@cindex servidores substitutos, adicionando mais
Guix pode procurar e buscar substitutos de vários servidores. Isso é útil
quando você está usando pacotes de canais adicionais para os quais o
servidor oficial não tem substitutos, mas outro servidor os fornece. Outra
situação em que isso é útil é quando você prefere baixar do servidor
substituto da sua organização, recorrendo ao servidor oficial apenas como um
fallback ou descartando-o completamente.

Você pode dar ao Guix uma lista de URLs de servidores substitutos e ele irá
verificá-los na ordem especificada. Você também precisa autorizar
explicitamente as chaves públicas dos servidores substitutos para instruir o
Guix a aceitar os substitutos que eles assinam.

No Guix System, isso é obtido modificando a configuração do serviço
@code{guix}. Como o serviço @code{guix} faz parte das listas padrão de
serviços, @code{%base-services} e @code{%desktop-services}, você pode usar
@code{modify-services} para alterar sua configuração e adicionar as URLs e
chaves substitutas que você deseja (@pxref{Referência de Service,
@code{modify-services}}).

Como exemplo, suponha que você queira buscar substitutos de
@code{guix.example.org} e autorizar a chave de assinatura desse servidor,
além do padrão @code{@value{SUBSTITUTE-SERVER-1}} e
@code{@value{SUBSTITUTE-SERVER-2}}. A configuração do sistema operacional
resultante será algo como:

@lisp
(operating-system
 ;; @dots{}
 (services
  ;; Suponha que estamos começando com '%desktop-services'. Substitua-o
  ;; pela lista de serviços que você está realmente usando.
  (modify-services %desktop-services
    (guix-service-type config =>
                       (guix-configuration
                        (inherit config)
                        (substitute-urls
                         (append (list "https://guix.example.org")
                                 %default-substitute-urls))
                        (authorized-keys
                         (append (list (local-file "./key.pub"))
                                 %default-authorized-guix-keys)))))))
@end lisp

Isso pressupõe que o arquivo @file{key.pub} contém a chave de assinatura de
@code{guix.example.org}. Com essa alteração em vigor no arquivo de
configuração do seu sistema operacional (digamos @file{/etc/config.scm}),
você pode reconfigurar e reiniciar o serviço @code{guix-daemon} ou
reinicializar para que as alterações entrem em vigor:

@example
$ sudo guix system reconfigure /etc/config.scm
$ sudo herd restart guix-daemon
@end example

Se você estiver executando o Guix em uma "distribuição estrangeira'', você
deve seguir os seguintes passos para obter substitutos de servidores
adicionais:

@enumerate
@item
Edite o arquivo de configuração de serviço para @code{guix-daemon}; ao usar
systemd, normalmente é
@file{/etc/systemd/system/guix-daemon.service}. Adicione a opção
@option{--substitute-urls} na linha de comando @command{guix-daemon} e liste
as URLs de interesse (@pxref{daemon-substitute-urls, @code{guix-daemon
--substitute-urls}}):

@example
@dots{} --substitute-urls='https://guix.example.org @value{SUBSTITUTE-URLS}'
@end example

@item
Reinicie o daemon. Para systemd, é assim:

@example
systemctl daemon-reload
systemctl restart guix-daemon.service
@end example

@item
Autorize a chave do novo servidor (@pxref{Invocando guix archive}):

@example
guix archive --authorize < key.pub
@end example

Novamente, isso pressupõe que @file{key.pub} contém a chave pública que
@code{guix.example.org} usa para assinar substitutos.
@end enumerate

Agora você está pronto! Os substitutos serão preferencialmente retirados de
@code{https://guix.example.org}, usando @code{@value{SUBSTITUTE-SERVER-1}} e
então @code{@value{SUBSTITUTE-SERVER-2}} como opções de fallback. Claro que
você pode listar quantos servidores substitutos quiser, com a ressalva de
que a pesquisa de substitutos pode ser desacelerada se muitos servidores
precisarem ser contatados.

@quotation Troubleshooting
Para diagnosticar problemas, você pode executar @command{guix weather}. Por
exemplo, executando:

@example
guix weather coreutils
@end example

@noindent
não apenas informa qual dos servidores atualmente configurados tem
substitutos para o pacote @code{coreutils}, mas também informa se um desses
servidores não está autorizado. @xref{Invocando guix weather}, para mais
informações.
@end quotation

Observe que também há situações em que é possível adicionar a URL de um
servidor substituto @emph{sem} autorizar sua chave. @xref{Autenticação de substituto}, para entender esse ponto.

@node Autenticação de substituto
@subsection Autenticação de substituto

@cindex assinaturas digitais
Guix detecta e gera um erro ao tentar usar um substituto que foi
adulterado. Da mesma forma, ele ignora substitutos que não são assinados, ou
que não são assinados por uma das chaves listadas na ACL.

Há uma exceção, no entanto: se um servidor não autorizado fornecer
substitutos que sejam @emph{bit-for-bit idênticos} aos fornecidos por um
servidor autorizado, então o servidor não autorizado se torna elegível para
downloads. Por exemplo, suponha que escolhemos dois servidores substitutos
com esta opção:

@example
--substitute-urls="https://a.example.org https://b.example.org"
@end example

@noindent
@cindex compilações reproduzíveis
Se a ACL contiver apenas a chave para @samp{b.example.org}, e se
@samp{a.example.org} servir os substitutos @emph{exatamente os mesmos},
então o Guix baixará os substitutos de @samp{a.example.org} porque ele vem
primeiro na lista e pode ser considerado um espelho de
@samp{b.example.org}. Na prática, máquinas de construção independentes
geralmente produzem os mesmos binários, graças às construções reproduzíveis
em bits (veja abaixo).

Ao usar HTTPS, o certificado X.509 do servidor é @emph{não} validado (em
outras palavras, o servidor não é autenticado), ao contrário do que os
clientes HTTPS, como navegadores da Web, geralmente fazem. Isso ocorre
porque o Guix autentica as próprias informações substitutas, conforme
explicado acima, que é o que nos importa (enquanto os certificados X.509 são
sobre autenticação de ligações entre nomes de domínio e chaves públicas).

@node Configurações de proxy
@subsection Configurações de proxy

@vindex http_proxy
@vindex https_proxy
Os substitutos são baixados por HTTP ou HTTPS@. As variáveis de ambiente
@env{http_proxy} e @env{https_proxy} podem ser definidas no ambiente de
@command{guix-daemon} e são honradas para downloads de substitutos. Observe
que o valor dessas variáveis de ambiente no ambiente onde @command{guix
build}, @command{guix package} e outros comandos de cliente são executados
não tem @emph{absolutamente nenhum efeito}.

@node Falha na substituição
@subsection Falha na substituição

Mesmo quando um substituto para uma derivação estiver disponível, às vezes a
tentativa de substituição falhará. Isso pode acontecer por vários motivos: o
servidor substituto pode estar offline, o servidor substituto pode ter sido
excluído recentemente, a conexão pode ter sido interrompida, etc.

Quando os substitutos estão habilitados e um substituto para uma derivação
está disponível, mas a tentativa de substituição falha, o Guix tentará
construir a derivação localmente dependendo se @option{--fallback} foi
fornecido ou não (@pxref{fallback-option,, opção de compilação comum
@option{--fallback}}). Especificamente, se @option{--fallback} for omitido,
nenhuma construção local será executada e a derivação será considerada como
tendo falhado. No entanto, se @option{--fallback} for fornecido, o Guix
tentará construir a derivação localmente, e o sucesso ou fracasso da
derivação dependerá do sucesso ou fracasso da construção local. Observe que
quando os substitutos estão desabilitados ou nenhum substituto está
disponível para a derivação em questão, uma construção local @emph{sempre}
será executada, independentemente de @option{--fallback} ter sido fornecido
ou não.

Para ter uma ideia de quantos substitutos estão disponíveis no momento, você
pode tentar executar o comando @command{guix weather} (@pxref{Invocando guix weather}). Este comando fornece estatísticas sobre os substitutos fornecidos
por um servidor.

@node Confiança em binários
@subsection Confiança em binários

@cindex confiança, de binários pré-construídos
Hoje, o controlo de cada indivíduo sobre a sua própria computação está à
mercê de instituições, empresas e grupos com poder e determinação
suficientes para subverter a infra-estrutura informática e explorar as suas
fraquezas. Embora o uso de substitutos possa ser conveniente, encorajamos os
usuários a também construírem por conta própria, ou até mesmo executarem seu
próprio build farm, de modo que os servidores substitutos executados pelo
projeto sejam um alvo menos interessante. Uma maneira de ajudar é publicando
o software que você constrói usando @command{guix publish} para que outros
tenham mais uma opção de servidor para baixar substitutos (@pxref{Invocando guix publish}).

Guix has the foundations to maximize build reproducibility
(@pxref{Recursos}).  In most cases, independent builds of a given package or
derivation should yield bit-identical results.  Thus, through a diverse set
of independent package builds, we can strengthen the integrity of our
systems.  The @command{guix challenge} command aims to help users assess
substitute servers, and to assist developers in finding out about
non-deterministic package builds (@pxref{Invocando guix challenge}).
Similarly, the @option{--check} option of @command{guix build} allows users
to check whether previously-installed substitutes are genuine by rebuilding
them locally (@pxref{build-check, @command{guix build --check}}).  To force
a full rebuild of a package (ignoring security updates via grafts
(@pxref{Atualizações de segurança}), if any grafts exist—which is not always the
case), use @option{--check} together with @option{--no-grafts}
(@pxref{Opções de compilação comuns, @option{--no-grafts}}).  Because grafts are
built as their own derivation, if the package you want to rebuild is subject
to being grafted, merely using @option{--check} will only rebuild the
grafting derivation, and not actually recompile the package.

No futuro, queremos que o Guix tenha suporte para publicação e recuperação
de binários de/para outros usuários, de forma peer-to-peer. Se você gostaria
de discutir este projeto, entre em contato conosco em
@email{guix-devel@@gnu.org}.

@node Pacotes com múltiplas saídas
@section Pacotes com múltiplas saídas

@cindex multiple-output packages
@cindex saídas de pacote
@cindex saídas

Frequentemente, os pacotes definidos no Guix têm uma única @dfn{saída} ---
ou seja, o pacote fonte leva a exatamente um diretório no armazém. Ao
executar @command{guix install glibc}, instala-se a saída padrão do pacote
GNU libc; A saída padrão é chamada @code{out}, mas seu nome pode ser omitido
conforme mostrado neste comando. Neste caso específico, a saída padrão de
@code{glibc} contém todos os arquivos de cabeçalho C, bibliotecas
compartilhadas, bibliotecas estáticas, documentação de informações e outros
arquivos de suporte.

Às vezes é mais apropriado separar os vários tipos de arquivos produzidos a
partir de um único pacote fonte em saídas separadas. Por exemplo, a
biblioteca GLib C (usada pelo GTK+ e pacotes relacionados) instala mais de
20 MiB de documentação de referência como páginas HTML. Para economizar
espaço para usuários que não precisam, a documentação vai para uma saída
separada, chamada @code{doc}. Para instalar a saída principal do GLib, que
contém tudo menos a documentação, seria executado:

@example
guix install glib
@end example

@cindex documentation
O comando para instalar sua documentação é:

@example
guix install glib:doc
@end example

Embora a sintaxe de dois pontos funcione para especificação de linha de
comando de saídas de pacotes, ela não funcionará ao usar uma @emph{variável}
de pacote no código do Scheme. Por exemplo, para adicionar a documentação do
@code{glib} aos pacotes instalados globalmente de um @code{operating-system}
(veja @ref{Referência do operating-system}), uma lista de dois itens, sendo o
primeiro a @emph{variável} de pacote e o segundo o nome da saída a ser
selecionada (uma string), devem ser usados:

@lisp
(use-modules (gnu packages glib))
;; glib-with-documentation é o símbolo de Guile para o pacote glib
(operating-system
 ...
 (packages
  (append
   (list (list glib-with-documentation "doc"))
         %base-packages)))
@end lisp

Alguns pacotes instalam programas com diferentes "pegadas de
dependência''. Por exemplo, o pacote WordNet instala ferramentas de linha de
comando e interfaces gráficas de usuário (GUIs). Os primeiros dependem
exclusivamente da biblioteca C, enquanto os últimos dependem apenas do
Tcl/Tk e das bibliotecas X subjacentes. Nesse caso, deixamos as ferramentas
de linha de comando na saída padrão, enquanto as GUIs ficam em uma saída
separada. Isso permite que usuários que não precisam de GUIs economizem
espaço. O comando @command{guix size} pode ajudar a descobrir tais situações
(@pxref{Invocando guix size}). @command{guix graph} também pode ser útil
(@pxref{Invocando guix graph}).

Existem vários desses pacotes de múltiplas saídas na distribuição
GNU. Outros nomes de saída convencionais incluem @code{lib} para bibliotecas
e possivelmente arquivos de cabeçalho, @code{bin} para programas
independentes e @code{debug} para informações de depuração
(@pxref{Instalando arquivos de depuração}). A saída de um pacote está listada na
terceira coluna da saída de @command{guix package --list-available}
(@pxref{Invocando guix package}).


@node Invocando guix locate
@section Invocando @command{guix locate}

@cindex file, searching in packages
@cindex file search
@cindex procurando por pacotes
Há tantos softwares gratuitos por aí que, mais cedo ou mais tarde, você
precisará procurar por pacotes. O comando @command{guix search} que vimos
antes (@pxref{Invocando guix package}) permite pesquisar por palavras-chave:

@example
guix search video editor
@end example

@cindex procurando por pacotes, por nome de arquivo
Às vezes, você deseja descobrir qual pacote fornece um determinado arquivo,
e é aí que entra @command{guix locate}. Veja como você pode encontrar o
comando @command{ls}:

@example
$ guix locate ls
coreutils@@9.1       /gnu/store/@dots{}-coreutils-9.1/bin/ls
@end example

É claro que o comando funciona para qualquer arquivo, não apenas para
comandos:

@example
$ guix locate unistr.h
icu4c@@71.1          /gnu/store/@dots{}/include/unicode/unistr.h
libunistring@@1.0    /gnu/store/@dots{}/include/unistr.h
@end example

Você também pode especificar @dfn{padrões de globo} com curingas. Por
exemplo, aqui está como você procuraria pacotes que fornecem arquivos
@file{.service}:

@example
$ guix locate -g '*.service'
man-db@@2.11.1        @dots{}/lib/systemd/system/man-db.service
wpa-supplicant@@2.10  @dots{}/system-services/fi.w1.wpa_supplicant1.service
@end example

O comando @command{guix locate} depende de um banco de dados que mapeia
nomes de arquivos para nomes de pacotes. Por padrão, ele cria
automaticamente esse banco de dados, caso ele ainda não exista, percorrendo
os pacotes disponíveis @emph{localmente}, o que pode levar alguns minutos
(dependendo do tamanho do seu armazém e da velocidade do seu dispositivo de
armazenamento).

@quotation Nota
Por enquanto, @command{guix locate} constrói seu banco de dados baseado em
conhecimento puramente local – o que significa que você não encontrará
pacotes que nunca chegaram ao sue armazém. Eventualmente, ele suportará o
download de um banco de dados pré-construído para que você possa encontrar
mais pacotes.
@end quotation

Por padrão, @command{guix locate} primeiro tenta procurar um banco de dados
de todo o sistema, geralmente em @file{/var/cache/guix/locate}; Se não
existir ou for muito antigo, ele retornará ao banco de dados por usuário,
por padrão em @file{~/.cache/guix/locate}. Em um sistema multiusuário, os
administradores podem querer atualizar periodicamente o banco de dados de
todo o sistema para que todos os usuários possam se beneficiar dele, por
exemplo, configurando @code{package-database-service-type} (@pxref{File Search Services, @code{package-database-service-type}}).

A sintaxe geral é:

@example
guix locate [@var{opções}@dots{}] @var{arquivo}@dots{}
@end example

@noindent
... onde @var{arquivo} é o nome de um arquivo a ser pesquisado
(especificamente, o "nome base" do arquivo: arquivos cujos diretórios pais
são chamados @var{arquivo} não são correspondidos).

As opções disponíveis são as seguintes:

@table @code
@item --glob
@item -g
Interprete @var{arquivo}@dots{} como @dfn{padrões de globo}---padrões que
podem incluir caracteres curinga, como @samp{*.scm} para denotar todos os
arquivos que terminam em @samp{.scm}.

@item --stats
Exibir estatísticas do banco de dados.

@item --update
@itemx -u
Atualize o banco de dados dos arquivos.

Por padrão, o banco de dados é atualizado automaticamente quando é muito
antigo.

@item --clear
Limpe o banco de dados e preencha-o novamente.

Esta opção permite começar de novo, garantindo que os dados antigos sejam
removidos do banco de dados, o que também evita ter um banco de dados em
constante crescimento. Por padrão, @command{guix locate} faz isso
automaticamente periodicamente, embora com pouca frequência.

@item --database=@var{arquivo}
Use @var{arquivo} como banco de dados, criando-o se necessário.

Por padrão, @command{guix locate} escolhe o banco de dados em
@file{~/.cache/guix} ou @file{/var/cache/guix}, o que for mais recente.

@item --method=@var{método}
@itemx -m @var{método}
Use @var{método} para selecionar o conjunto de pacotes a serem indexados. Os
valores possíveis são:

@table @code
@item manifests
Este é o método padrão: ele funciona percorrendo perfis na máquina e
gravando os pacotes que encontra – pacotes instalados por você ou por outros
usuários da máquina, direta ou indiretamente. É rápido mas você pode perder
outros pacotes disponíveis no armazém mas não referenciados por nenhum
perfil.

@item store
Este é um método mais lento, porém mais exaustivo: verifica entre todos os
pacotes existentes aqueles que estão disponíveis no armazém e os registra.
@end table
@end table


@node Invocando guix gc
@section Invocando @command{guix gc}

@cindex coletor de lixo
@cindex espaço em disco
@cindex @command{guix gc}
Pacotes instalados mas não usados podem ser @dfn{garbage-collected}. O
comando @command{guix gc} permite que os usuários executem explicitamente o
coletor de lixo para recuperar espaço do diretório @file{/gnu/store}. É a
maneira @emph{única} de remover arquivos de @file{/gnu/store} --- remover
arquivos ou diretórios manualmente pode quebrá-los sem possibilidade de
reparo!

@cindex raízes de GC
@cindex raízes de coletor de lixo
O coletor de lixo possui um conjunto de @dfn{raizes} conhecidos: qualquer
arquivo em @file{/gnu/store} acessível a partir de uma raiz é considerado
@dfn{live} e não pode ser excluído; Qualquer outro arquivo é considerado
@dfn{dead} e pode ser excluído. O conjunto de raízes do coletor de lixo
(abreviadamente ``Raízes GC'') inclui perfis de usuário padrão; por padrão,
as ligações simbólicas em @file{/var/guix/gcroots} representam essas raízes
do GC. Novas raízes de GC podem ser adicionadas com @command{guix build
--root}, por exemplo (@pxref{Invocando guix build}). O comando @command{guix
gc --list-roots} os lista.

Antes de executar @code{guix gc --collect-garbage} para liberar espaço,
geralmente é útil remover gerações antigas dos perfis de usuário; dessa
forma, compilações de pacotes antigos referenciadas por essas gerações podem
ser recuperadas. Isso é conseguido executando @code{guix package
--delete-generations} (@pxref{Invocando guix package}).

Nossa recomendação é executar uma coleta de lixo periodicamente ou quando
houver pouco espaço em disco. Por exemplo, para garantir que pelo menos
5@tie{}GB estejam disponíveis no disco, basta executar:

@example
guix gc -F 5G
@end example

É perfeitamente seguro executar como um trabalho periódico não interativo
(@pxref{Execução de trabalho agendado}, para saber como configurar tal
trabalho). Executar @command{guix gc} sem argumentos coletará o máximo de
lixo possível, mas isso geralmente é inconveniente: você pode ter que
reconstruir ou baixar novamente um software que está "morto" do ponto de
vista do GC, mas que é necessário para construir outras peças de software -
por exemplo, a cadeia de ferramentas do compilador.

O comando @command{guix gc} tem três modos de operação: pode ser usado para
coletar o lixo de quaisquer arquivos mortos (o padrão), para excluir
arquivos específicos (a opção @option{--delete}), para imprimir lixo-
informações do coletor ou para consultas mais avançadas. As opções de coleta
de lixo são as seguintes:

@table @code
@item --collect-garbage[=@var{min}]
@itemx -C [@var{min}]
Colete lixo, ou seja, arquivos e subdiretórios @file{/gnu/store}
inacessíveis. Esta é a operação padrão quando nenhuma opção é especificada.

Quando @var{min} for fornecido, pare quando @var{min} bytes forem
coletados. @var{min} pode ser um número de bytes ou pode incluir uma unidade
como sufixo, como @code{MiB} para mebibytes e @code{GB} para gigabytes
(@pxref{Block size, especificações de tamanho,, coreutils, GNU Coreutils}).

Quando @var{min} for omitido, colete todo o lixo.

@item --free-space=@var{free}
@itemx -F @var{free}
Colete o lixo até que o espaço @var{free} esteja disponível em
@file{/gnu/store}, se possível; @var{free} denota espaço de armazenamento,
como @code{500MiB}, conforme descrito acima.

Quando @var{free} ou mais já estiver disponível em @file{/gnu/store}, não
faça nada e saia imediatamente.

@item --delete-generations[=@var{duração}]
@itemx -d [@var{duração}]
Antes de iniciar o processo de coleta de lixo, exclua todas as gerações
anteriores a @var{duração}, para todos os perfis de usuário e gerações do
ambiente pessoal. Quando executado como root, isso se aplica a todos os
perfis @emph{de todos os usuários}.

Por exemplo, este comando exclui todas as gerações de todos os seus perfis
com mais de 2 meses (exceto as gerações atuais) e depois libera espaço até
que pelo menos 10 GiB estejam disponíveis:

@example
guix gc -d 2m -F 10G
@end example

@item --delete
@itemx -D
Tentativa de excluir todos os arquivos e diretórios de armazém especificados
como argumentos. Isso falhará se alguns dos arquivos não estiverem no
armazém ou se ainda estiverem ativos.

@item --list-failures
Listar itens de armazém correspondentes a falhas de compilação em cache.

Isso não imprime nada, a menos que o daemon tenha sido iniciado com
@option{--cache-failures} (@pxref{Invocando guix-daemon,
@option{--cache-failures}}).

@item --list-roots
Listar as raízes do GC de propriedade do usuário; quando executado como
root, listar @emph{todas} as raízes do GC.

@item --list-busy
Listar itens de armazém em uso por processos em execução no momento. Esses
itens de armazém são efetivamente considerados raízes GC: eles não podem ser
excluídos.

@item --clear-failures
Remova os itens de armazém especificados do cache de compilação com falha.

Novamente, essa opção só faz sentido quando o daemon é iniciado com
@option{--cache-failures}. Caso contrário, não faz nada.

@item --list-dead
Exibe a lista de arquivos e diretórios mortos ainda presentes no armazém, ou
seja, arquivos e diretórios que não podem mais ser acessados de nenhuma
raiz.

@item --list-live
Exibe a lista de arquivos e diretórios do armazém ativa.

@end table

Além disso, as referências entre arquivos de armazém existentes podem ser
consultadas:

@table @code

@item --references
@itemx --referrers
@cindex dependências de pacotes
Listar as referências (respectivamente, os referenciadores) dos arquivos de
armazém fornecidos como argumentos.

@item --requisites
@itemx -R
@cindex closure
Liste os requisitos dos arquivos de armazém passados como argumentos. Os
requisitos incluem os próprios arquivos de armazém, suas referências e as
referências destes, recursivamente. Em outras palavras, a lista retornada é
o @dfn{fechamento transitivo} dos arquivos de armazém.

@xref{Invocando guix size}, para uma ferramenta para criar o perfil do
tamanho do fechamento de um elemento. @xref{Invocando guix graph}, para uma
ferramenta para visualizar o grafo de referências.

@item --derivers
@cindex derivation
Retorna a(s) derivação(ões) que levam aos itens de armazém fornecidos
(@pxref{Derivações}).

Por exemplo, este comando:

@example
guix gc --derivers $(guix package -I ^emacs$ | cut -f4)
@end example

@noindent
retorna o(s) arquivo(s) @file{.drv} que levam ao pacote @code{emacs}
instalado no seu perfil.

Note que pode haver zero arquivos @file{.drv} correspondentes, por exemplo
porque esses arquivos foram coletados como lixo. Também pode haver mais de
um @file{.drv} correspondente devido a derivações de saída fixa.
@end table

Por fim, as seguintes opções permitem que você verifique a integridade do
armazém e controle o uso do disco.

@table @option

@item --verify[=@var{opções}]
@cindex integridade do armazém
@cindex verificação de integridade
Verifique a integridade do armazém.

Por padrão, certifique-se de que todos os itens de armazém marcados como
válidos no banco de dados do daemon realmente existam em @file{/gnu/store}.

Quando fornecido, @var{opções} deve ser uma lista separada por vírgulas
contendo um ou mais de @code{contents} e @code{repair}.

Ao passar @option{--verify=contents}, o daemon calcula o hash de conteúdo de
cada item do armazém e o compara com seu hash no banco de
dados. Incompatibilidades de hash são relatadas como corrupções de
dados. Como ele percorre @emph{todos os arquivos no armazém}, esse comando
pode levar muito tempo, especialmente em sistemas com uma unidade de disco
lenta.

@cindex consertando o armazém
@cindex corrupção, recuperando-se de
Usar @option{--verify=repair} ou @option{--verify=contents,repair} faz com
que o daemon tente reparar itens corrompidos do armazém buscando substitutos
para eles (@pxref{Substitutos}). Como o reparo não é atômico e, portanto,
potencialmente perigoso, ele está disponível apenas para o administrador do
sistema. Uma alternativa leve, quando você sabe exatamente quais itens no
armazém estão corrompidos, é @command{guix build --repair} (@pxref{Invocando guix build}).

@item --optimize
@cindex deduplicação
Otimize o armazém vinculando fisicamente arquivos idênticos — isso é
@dfn{deduplication}.

O daemon executa a desduplicação após cada importação bem-sucedida de build
ou archive, a menos que tenha sido iniciado com
@option{--disable-deduplication} (@pxref{Invocando guix-daemon,
@option{--disable-deduplication}}). Portanto, essa opção é útil
principalmente quando o daemon estava em execução com
@option{--disable-deduplication}.

@item --vacuum-database
@cindex aspirar o banco de dados do armazém
@comment Avoid words like 'repair,' 'compress,' and 'optimize.'
Guix usa um banco de dados sqlite para manter o controle dos itens no
armazém (@pxref{O armazém}). Com o tempo, é possível que o banco de dados
cresça muito e se torne fragmentado. Como resultado, pode-se desejar limpar
o espaço liberado e juntar as páginas parcialmente usadas no banco de dados
deixadas para trás por pacotes removidos ou após executar o coletor de
lixo. Executar @command{sudo guix gc --vacuum-database} bloqueará o banco de
dados e @code{VACUUM} o store, desfragmentando o banco de dados e expurgando
as páginas liberadas, desbloqueando o banco de dados quando terminar.

@end table

@node Invocando guix pull
@section Invocando @command{guix pull}

@cindex atualizando Guix
@cindex atualizando Guix
@cindex @command{guix pull}
@cindex puxar
@cindex segurança, @command{guix pull}
@cindex autenticidade, do código obtido com @command{guix pull}
Os pacotes são instalados ou atualizados para a versão mais recente
disponível na distribuição atualmente disponível na sua máquina local. Para
atualizar essa distribuição, junto com as ferramentas Guix, você deve
executar @command{guix pull}: o comando baixa o código-fonte Guix mais
recente e as descrições dos pacotes, e os implementa. O código-fonte é
baixado de um repositório @uref{https://git-scm.com/book/pt-br/, Git}, por
padrão o repositório oficial GNU@tie{}Guix, embora isso possa ser
personalizado. @command{guix pull} garante que o código que ele baixa é
@emph{autêntico}, verificando se os commits são assinados pelos
desenvolvedores Guix.

Especificamente, @command{guix pull} baixa o código dos @dfn{canais}
(@pxref{Canais}) especificados por um dos seguintes, nesta ordem:

@enumerate
@item
a opção @option{--channels};
@item
o arquivo @file{~/.config/guix/channels.scm} do usuário, a menos que
@option{-q} seja passado;
@item
o arquivo @file{/etc/guix/channels.scm} de todo o sistema, a menos que
@option{-q} seja passado (no sistema Guix, este arquivo pode ser declarado
na configuração do sistema operacional, @pxref{guix-configuration-channels,
campo @code{channels} de @code{guix-configuration}});
@item
os canais padrão integrados especificados na variável
@code{%default-channels}.
@end enumerate

Após a conclusão, @command{guix package} usará pacotes e versões de pacotes
desta cópia recém-recuperada do Guix. Não apenas isso, mas todos os comandos
Guix e módulos Scheme também serão retirados dessa versão mais
recente. Novos subcomandos @command{guix} adicionados pela atualização
também se tornam disponíveis.

Qualquer usuário pode atualizar sua cópia do Guix usando @command{guix
pull}, e o efeito é limitado ao usuário que executou @command{guix
pull}. Por exemplo, quando o usuário @code{root} executa @command{guix
pull}, isso não tem efeito na versão do Guix que o usuário @code{alice} vê,
e vice-versa.

O resultado da execução de @command{guix pull} é um @dfn{perfil} disponível
em @file{~/.config/guix/current} contendo o Guix mais recente.

A opção @option{--list-generations} ou @option{-l} lista gerações anteriores
produzidas por @command{guix pull}, juntamente com detalhes sobre sua
procedência:

@example
$ guix pull -l
Geração 1	10 jun 2018 00:18:18
  guix 65956ad
    URL do repositório: https://git.guix.gnu.org/guix.git
    ramo: origin/master
    commit: 65956ad3526ba09e1f7a40722c96c6ef7c0936fe

Geração 2	11 jun 2018 11:02:49
  guix e0cc7f6
    URL do repositório: https://git.guix.gnu.org/guix.git
    ramo: origin/master
    commit: e0cc7f669bec22c37481dd03a7941c7d11a64f1d

Geração 3	13 jun 2018 23:31:07	(atual)
  guix 844cc1c
    URL do repositório: https://git.guix.gnu.org/guix.git
    ramo: origin/master
    commit: 844cc1c8f394f03b404c5bb3aee086922373490c
@end example

@xref{Invocando guix describe, @command{guix describe}}, para outras maneiras
de descrever o status atual do Guix.

Este perfil @code{~/.config/guix/current} funciona exatamente como os perfis
criados por @command{guix package} (@pxref{Invocando guix package}). Ou seja,
você pode listar gerações, reverter para a geração anterior --- ou seja, o
Guix anterior --- e assim por diante:

@example
$ guix pull --roll-back
trocado da geração 3 para 2
$ guix pull --delete-generations=1
excluindo /var/guix/profiles/per-user/charlie/current-guix-1-link
@end example

Você também pode usar @command{guix package} (@pxref{Invocando guix package})
para gerenciar o perfil nomeando-o explicitamente:
@example
$ guix package -p ~/.config/guix/current --roll-back
trocado da geração 3 para 2
$ guix package -p ~/.config/guix/current --delete-generations=1
excluindo /var/guix/profiles/per-user/charlie/current-guix-1-link
@end example

O comando @command{guix pull} geralmente é invocado sem argumentos, mas
suporta as seguintes opções:

@table @code
@item --url=@var{url}
@itemx --commit=@var{commit}
@itemx --branch=@var{ramo}
Baixe o código para o canal @code{guix} do @var{url} especificado, no
@var{commit} fornecido (um ID de commit Git válido representado como uma
string hexadecimal ou o nome de uma tag) ou @var{ramo}.

@cindex @file{channels.scm}, arquivo de configuração
@cindex arquivo de configuração para canais
Essas opções são fornecidas para sua conveniência, mas você também pode
especificar sua configuração no arquivo @file{~/.config/guix/channels.scm}
ou usando a opção @option{--channels} (veja abaixo).

@item --channels=@var{arquivo}
@itemx -C @var{arquivo}
Leia a lista de canais de @var{arquivo} em vez de
@file{~/.config/guix/channels.scm} ou
@file{/etc/guix/channels.scm}. @var{arquivo} deve conter código Scheme que
avalia uma lista de objetos de canal. @xref{Canais}, para mais
informações.

@item --no-channel-files
@itemx -q
Inibir o carregamento dos arquivos de canal do usuário e do sistema,
@file{~/.config/guix/channels.scm} e @file{/etc/guix/channels.scm}.

@cindex canal de notícias
@item --news
@itemx -N
Exibir notícias escritas por autores de canais para seus usuários para
alterações feitas desde a geração anterior (@pxref{Canais, Escrevendo
Notícias de Canal}). Quando @option{--details} é passado, exibir
adicionalmente pacotes novos e atualizados.

Você pode visualizar essas informações de gerações anteriores com
@command{guix pull -l}.

@item --list-generations[=@var{padrão}]
@itemx -l [@var{padrão}]
Liste todas as gerações de @file{~/.config/guix/current} ou, se @var{padrão}
for fornecido, o subconjunto de gerações que correspondem a @var{padrão}. A
sintaxe de @var{padrão} é a mesma de @code{guix package --list-generations}
(@pxref{Invocando guix package}).

Por padrão, isso imprime informações sobre os canais usados em cada revisão,
bem como as entradas de notícias correspondentes. Se você passar
@option{--details}, ele também imprimirá a lista de pacotes adicionados e
atualizados em cada geração em comparação com a anterior.

@item --details
Instrua @option{--list-generations} ou @option{--news} para exibir mais
informações sobre as diferenças entre gerações subsequentes — veja acima.

@item --roll-back
@cindex revertendo
@cindex desfazendo transações
@cindex transações, desfazendo
Reverta para a @dfn{geração} anterior de @file{~/.config/guix/current}---ou
seja, desfaça a última transação.

@item --switch-generation=@var{padrão}
@itemx -S @var{padrão}
@cindex gerações
Mude para uma geração específica definida por @var{padrão}.

@var{padrão} pode ser um número de geração ou um número prefixado com "+''
ou "-''. O último significa: mover para frente/para trás por um número
especificado de gerações. Por exemplo, se você quiser retornar para a última
geração após @option{--roll-back}, use @option{--switch-generation=+1}.

@item --delete-generations[=@var{padrão}]
@itemx -d [@var{padrão}]
Quando @var{padrão} for omitido, exclua todas as gerações, exceto a atual.

Este comando aceita os mesmos padrões de @option{--list-Generations}. Quando
@var{pattern} for especificado, exclua as gerações correspondentes. Quando
@var{padrão} especifica uma duração, as gerações @emph{mais antigas} que a
duração especificada correspondem. Por exemplo,
@option{--delete-generations=1m} exclui gerações com mais de um mês.

Se a geração atual corresponder, ela @emph{não} será excluída.

Observe que a exclusão de gerações impede a reversão para
elas. Conseqüentemente, este comando deve ser usado com cuidado.

@xref{Invocando guix describe}, para uma maneira de exibir informações
somente sobre a geração atual.

@item --profile=@var{perfil}
@itemx -p @var{perfil}
Use @var{perfil} em vez de @file{~/.config/guix/current}.

@item --dry-run
@itemx -n
Mostre quais commits de canal seriam usados e o que seria construído ou
substituído, mas não faça isso de fato.

@item --allow-downgrades
Permitir extrair revisões de canais mais antigas ou não relacionadas às que
estão em uso atualmente.

@cindex ataques de downgrade, proteção contra
Por padrão, @command{guix pull} protege contra os chamados "ataques de
downgrade'', nos quais o repositório Git de um canal seria redefinido para
uma revisão anterior ou não relacionada a si mesmo, potencialmente levando
você a instalar versões mais antigas e conhecidas de pacotes de software.

@quotation Nota
Certifique-se de entender as implicações de segurança antes de usar
@option{--allow-downgrades}.
@end quotation

@item --disable-authentication
Permitir extrair código de canal sem autenticá-lo.

@cindex autenticação, de código de canal
Por padrão, @command{guix pull} autentica o código baixado de canais
verificando se seus commits são assinados por desenvolvedores autorizados e
gera um erro se esse não for o caso. Esta opção o instrui a não executar
nenhuma verificação desse tipo.

@quotation Nota
Certifique-se de entender as implicações de segurança antes de usar
@option{--disable-authentication}.
@end quotation

@item --no-check-certificate
Do not validate the X.509 certificates of HTTPS servers.

When using this option, you have @emph{absolutely no guarantee} that you are
communicating with the authentic server responsible for the given URL.
Unless the channel is authenticated, this makes you vulnerable to
``man-in-the-middle'' attacks.

@item --system=@var{sistema}
@itemx -s @var{sistema}
Tente compilar para @var{sistema}---por exemplo, @code{i686-linux}---em vez
do tipo de sistema do host de compilação.

@item --bootstrap
Use o bootstrap Guile para construir o Guix mais recente. Esta opção é útil
somente para desenvolvedores Guix.
@end table

O mecanismo dos @dfn{canais} permite que você instrua @command{guix pull} de
qual repositório e branch extrair, bem como @emph{repositórios adicionais}
contendo módulos de pacote que devem ser implantados. @xref{Canais}, para
mais informações.

Além disso, @command{guix pull} suporta todas as opções de compilação comuns
(@pxref{Opções de compilação comuns}).

@node Invocando guix time-machine
@section Invocando @command{guix time-machine}

@cindex @command{guix time-machine}
@cindex fixação, canais
@cindex replicando Guix
@cindex reprodutibilidade, de Guix

O comando @command{guix time-machine} fornece acesso a outras revisões do
Guix, por exemplo, para instalar versões mais antigas de pacotes ou para
reproduzir uma computação em um ambiente idêntico. A revisão do Guix a ser
usada é definida por um commit ou por um arquivo de descrição de canal
criado por @command{guix describe} (@pxref{Invocando guix describe}).

Vamos supor que você queira viajar para aqueles dias de novembro de 2020,
quando a versão 1.2.0 do Guix foi lançada e, uma vez lá, executar o
@command{guile} daquela época:

@example
guix time-machine --commit=v1.2.0 -- \
  environment -C --ad-hoc guile -- guile
@end example

O comando acima busca Guix@tie{}1.2.0 (e possivelmente outros canais
especificados pelos seus arquivos de configuração @file{channels.scm} ---
veja abaixo) e executa seu comando @command{guix environment} para gerar um
ambiente em um contêiner executando @command{guile} (@command{guix
environment} foi desde então subsumido por @command{guix shell};
@pxref{Invocando guix shell}). É como dirigir um DeLorean@footnote{Se você
não sabe o que é um DeLorean, considere viajar de volta para a década de
1980. (@uref{https://www.imdb.com/title/tt0088763/, De Volta para o Futuro
(1985)})}! A primeira invocação de @command{guix time-machine} pode ser
cara: pode ser necessário baixar ou até mesmo construir um grande número de
pacotes; o resultado é armazenado em cache e os comandos subsequentes
direcionados ao mesmo commit são quase instantâneos.

Quanto ao @command{guix pull}, na ausência de quaisquer opções, o
@command{time-machine} busca os últimos commits dos canais especificados em
@file{~/.config/guix/channels.scm}, @file{/etc/guix/channels.scm}, ou os
canais padrão; a opção @option{-q} permite que você ignore esses arquivos de
configuração. O comando:

@example
guix time-machine -q -- build hello
@end example

construirá então o pacote @code{hello} conforme definido no branch principal
do Guix, sem nenhum canal adicional, que é em geral uma revisão mais nova do
Guix do que a que você instalou. A viagem no tempo funciona em ambas as
direções!

@quotation Nota
O histórico do Guix é imutável e @command{guix time-machine} fornece
exatamente o mesmo software que eles estão em uma revisão específica do
Guix. Naturalmente, nenhuma correção de segurança é fornecida para versões
antigas do Guix ou seus canais. Um uso descuidado do @command{guix
time-machine} abre a porta para vulnerabilidades de
segurança. @xref{Invocando guix pull, @option{--allow-downgrades}}.
@end quotation

@c Keep this paragraph in sync with 'time-machine.scm'.
@command{guix time-machine} gera um erro ao tentar viajar para commits mais
antigos que "v0.16.0" (commit @samp{4a0b87f0}), datados de Dez.@: 2018. Este
é um dos commits mais antigos que oferecem suporte ao mecanismo de canal que
torna a "viagem no tempo" possível.

@quotation Nota
Embora seja tecnicamente possível viajar para um commit tão antigo, a
facilidade para fazê-lo dependerá em grande parte da disponibilidade de
substitutos binários. Ao viajar para um passado distante, alguns pacotes
podem não ser mais facilmente construídos a partir da fonte. Um exemplo são
as versões antigas do OpenSSL cujos testes falhavam após uma certa
data. Esse problema em particular pode ser contornado executando uma
@dfn{máquina de construção virtual} com seu relógio ajustado para a hora
certa (@pxref{build-vm, Máquinas de Construção Virtual}).
@end quotation

A sintaxe geral é:

@example
guix time-machine @var{opções}@dots{} -- @var{comando} @var {arg}@dots{}
@end example

onde @var{comando} e @var{arg}@dots{} são passados sem modificações para o
comando @command{guix} da revisão especificada. As @var{opções} que definem
esta revisão são as mesmas que para @command{guix pull} (@pxref{Invocando guix pull}):

@table @code
@item --url=@var{url}
@itemx --commit=@var{commit}
@itemx --branch=@var{ramo}
Use o canal @code{guix} do @var{url} especificado, no @var{commit} fornecido
(um ID de commit Git válido representado como uma string hexadecimal ou o
nome de uma tag) ou @var{ramo}.

@item --channels=@var{arquivo}
@itemx -C @var{arquivo}
Leia a lista de canais de @var{arquivo}. @var{arquivo} deve conter código
Scheme que avalia uma lista de objetos de canal. @xref{Canais} para mais
informações.

@item --no-channel-files
@itemx -q
Inibir o carregamento dos arquivos de canal do usuário e do sistema,
@file{~/.config/guix/channels.scm} e @file{/etc/guix/channels.scm}.

Portanto, @command{guix time-machine -q} é equivalente ao seguinte comando
Bash, usando a sintaxe "substituição de processo" (@pxref{Process
Substitution,,, bash, Manual de referência do GNU Bash}):

@example
guix time-machine -C <(echo %default-channels) @dots{}
@end example

@end table

Observe que @command{guix time-machine} pode acionar compilações de canais e
suas dependências, e elas são controladas pelas opções de compilação padrão
(@pxref{Opções de compilação comuns}).

Se @command{guix time-machine} for executado sem nenhum comando, ele imprime
o nome do arquivo do perfil que seria usado para executar o comando. Isso às
vezes é útil se você precisa obter o nome do arquivo de armazém do perfil
--- por exemplo, quando você quer @command{guix copy} ele.

@node Inferiores
@section Inferiores

@c TODO: Remove this once we're more confident about API stability.
@quotation Nota
A funcionalidade descrita aqui é uma ``prévia de tecnologia'' da versão
@value{VERSION}. Como tal, a interface está sujeita a alterações.
@end quotation

@cindex inferiores
@cindex composição das revisões do Guix
Às vezes, você pode precisar misturar pacotes da revisão do Guix que você
está executando atualmente com pacotes disponíveis em uma revisão diferente
do Guix. Os @dfn{inferiores} do Guix permite que você consiga isso compondo
diferentes revisões do Guix de maneiras arbitrárias.

@cindex pacotes inferiores
Tecnicamente, um ``inferior'' é essencialmente um processo Guix separado
conectado ao seu processo Guix principal por meio de um REPL
(@pxref{Invocando guix repl}). O módulo @code{(guix inferior)} permite que
você crie inferiores e se comunique com eles. Ele também fornece uma
interface de alto nível para navegar e manipular os pacotes que um inferior
fornece---@dfn{pacotes inferiores}.

Quando combinados com canais (@pxref{Canais}), os inferiores fornecem uma
maneira simples de interagir com uma revisão separada do Guix. Por exemplo,
vamos supor que você queira instalar em seu perfil o pacote @code{guile}
atual, junto com o @code{guile-json} como ele existia em uma revisão mais
antiga do Guix---talvez porque o mais novo @code{guile-json} tenha uma API
incompatível e você queira executar seu código contra a API antiga. Para
fazer isso, você pode escrever um manifesto para uso por @code{guix package
--manifest} (@pxref{Escrevendo manifestos}); nesse manifesto, você criaria um
inferior para aquela revisão antiga do Guix que você se importa, e você
procuraria o pacote @code{guile-json} no inferior:

@lisp
(use-modules (guix inferior) (guix channels)
             (srfi srfi-1))   ;para 'first'

(define canais
  ;; Esta é a revisão antiga da qual queremos
  ;; extrair guile-json.
  (list (channel
         (name 'guix)
         (url "https://git.guix.gnu.org/guix.git")
         (commit
          "65956ad3526ba09e1f7a40722c96c6ef7c0936fe"))))

(define inferior
  ;; Um inferior representando a revisão acima.
  (inferior-for-channels canais))

;; Agora crie um manifesto com o pacote "guile" atual
;; e o antigo pacote "guile-json".
(packages->manifest
 (list (first (lookup-inferior-packages inferior "guile-json"))
       (specification->package "guile")))
@end lisp

Na primeira execução, @command{guix package --manifest} pode ter que
construir o canal que você especificou antes de poder criar o inferior;
execuções subsequentes serão muito mais rápidas porque a revisão do Guix
será armazenada em cache.

O módulo @code{(guix inferior)} fornece os seguintes procedimentos para
abrir um inferior:

@deffn {Procedimento} inferior-for-channels canais [#:cache-directory] [#:ttl]
Retorna um inferior para @var{canais}, uma lista de canais. Use o cache em
@var{cache-directory}, onde as entradas podem ser recuperadas após @var{ttl}
segundos. Este procedimento abre uma nova conexão com o daemon de
construção.

Como efeito colateral, esse procedimento pode criar ou substituir binários
para @var{canais}, o que pode levar tempo.
@end deffn

@deffn {Procedimento} open-inferior diretório [#:command "bin/guix"]
Abra o Guix inferior em @var{diretório}, executando o comando
@code{@var{diretório}/@var{command} repl} ou equivalente. Retorne @code{#f}
se o inferior não puder ser iniciado.
@end deffn

@cindex pacotes inferiores
Os procedimentos listados abaixo permitem que você obtenha e manipule
pacotes inferiores.

@deffn {Procedimento} inferior-packages inferior
Retorna a lista de pacotes conhecidos por @var{inferior}.
@end deffn

@deffn {Procedimento} lookup-inferior-packages inferior nome [versão]
Retorna a lista ordenada de pacotes inferiores que correspondem a @var{nome}
em @var{inferior}, com os números de versão mais altos primeiro. Se
@var{versão} for true, retorna apenas pacotes com um número de versão
prefixado por @var{versão}.
@end deffn

@deffn {Procedimento} inferior-package? obj
Retorna verdadeiro se @var{obj} for um pacote inferior.
@end deffn

@deffn {Procedimento} inferior-package-name pacote
@deffnx {Procedimento} inferior-package-version pacote
@deffnx {Procedimento} inferior-package-synopsis pacote
@deffnx {Procedimento} inferior-package-description pacote
@deffnx {Procedimento} inferior-package-home-page pacote
@deffnx {Procedimento} inferior-package-location pacote
@deffnx {Procedimento} inferior-package-inputs pacote
@deffnx {Procedimento} inferior-package-native-inputs pacote
@deffnx {Procedimento} inferior-package-propagated-inputs pacote
@deffnx {Procedimento} inferior-package-transitive-propagated-inputs pacote
@deffnx {Procedimento} inferior-package-native-search-paths pacote
@deffnx {Procedimento} inferior-package-transitive-native-search-paths pacote
@deffnx {Procedimento} inferior-package-search-paths pacote
Esses procedimentos são a contrapartida dos acessadores de registro de
pacote (@pxref{Referência do package}). A maioria deles funciona consultando o
inferior de onde @var{pacote} vem, então o inferior ainda deve estar ativo
quando você chamar esses procedimentos.
@end deffn

Pacotes inferiores podem ser usados transparentemente como qualquer outro
pacote ou objeto tipo arquivo em expressões-G (@pxref{Expressões-G}). Eles
também são manipulados transparentemente pelo procedimento
@code{packages->manifest}, que é comumente usado em manifestos
(@pxref{Invocando guix package, a opção @option{--manifest} de @command{guix
package}}). Assim, você pode inserir um pacote inferior praticamente em
qualquer lugar em que inseriria um pacote regular: em manifestos, no campo
@code{packages} da sua declaração @code{operating-system} e assim por
diante.

@node Invocando guix describe
@section Invocando @command{guix describe}

@cindex reprodutibilidade
@cindex replicando Guix
@cindex @command{guix describe}
Frequentemente você pode querer responder perguntas como: ``Qual revisão do
Guix estou usando?'' ou ``Quais canais estou usando?'' Essas são informações
úteis em muitas situações: se você quiser @emph{replicar} um ambiente em uma
máquina ou conta de usuário diferente, se quiser relatar um bug ou
determinar qual alteração nos canais que você está usando o causou, ou se
quiser registrar o estado do seu sistema para fins de reprodutibilidade. O
comando @command{guix describe} responde a essas perguntas.

Quando executado a partir de um @command{guix} obtido com @command{guix
pull}, @command{guix describe} exibe o(s) canal(ais) dos quais foi criado,
incluindo a URL do repositório e os IDs de confirmação (@pxref{Canais}):

@example
$ guix describe
Geração 10	03 set 2018 17:32:44	(atual)
  guix e0fa68c
    URL do repositório: https://git.guix.gnu.org/guix.git
    ramo: master
    commit: e0fa68c7718fffd33d81af415279d6ddb518f727
@end example

Se você estiver familiarizado com o sistema de controle de versão do Git,
isso é similar em espírito a @command{git describe}; a saída também é
similar à de @command{guix pull --list-generations}, mas limitada à geração
atual (@pxref{Invocando guix pull, a opção
@option{--list-generations}}). Como o ID de commit do Git mostrado acima se
refere inequivocamente a um snapshot do Guix, essa informação é tudo o que é
preciso para descrever a revisão do Guix que você está usando e também para
replicá-la.

Para facilitar a replicação do Guix, @command{guix describe} também pode ser
solicitado a retornar uma lista de canais em vez da descrição legível acima:

@example
$ guix describe -f channels
(list (channel
        (name 'guix)
        (url "https://git.guix.gnu.org/guix.git")
        (commit
          "e0fa68c7718fffd33d81af415279d6ddb518f727")
        (introduction
          (make-channel-introduction
            "9edb3f66fd807b096b48283debdcddccfea34bad"
            (openpgp-fingerprint
              "BBB0 2DDF 2CEA F6A8 0D1D  E643 A2A0 6DF2 A33A 54FA")))))
@end example

@noindent
Você pode salvar isso em um arquivo e alimentá-lo com @command{guix pull -C}
em alguma outra máquina ou em um momento posterior, o que instanciará
@emph{esta revisão exata do Guix} (@pxref{Invocando guix pull, a opção
@option{-C}}). A partir daí, já que você consegue implementar a mesma
revisão do Guix, você pode muito bem @emph{replicar um ambiente de software
completo}. Humildemente achamos isso @emph{incrível}, e esperamos que você
goste também!

Os detalhes das opções suportadas por @command{guix describe} são os
seguintes:

@table @code
@item --format=@var{formato}
@itemx -f @var{formato}
Produza saída no @var{formato} especificado, um dos seguintes:

@table @code
@item human
produzir resultados legíveis por humanos;
@item channels
produz uma lista de especificações de canal que podem ser passadas para
@command{guix pull -C} ou instaladas como @file{~/.config/guix/channels.scm}
(@pxref{Invocando guix pull});
@item channels-sans-intro
como @code{channels}, mas omita o campo @code{introduction}; use-o para
produzir uma especificação de canal adequada para a versão 1.1.0 do Guix ou
anterior --- o campo @code{introduction} tem a ver com autenticação de canal
(@pxref{Canais, Autenticação de canal}) e não é suportado por essas
versões mais antigas;
@item json
@cindex JSON
produzir uma lista de especificações de canal no formato JSON;
@item recutils
produzir uma lista de especificações de canais no formato Recutils.
@end table

@item --list-formats
Exibir formatos disponíveis para a opção @option{--format}.

@item --profile=@var{perfil}
@itemx -p @var{perfil}
Exibir informações sobre @var{perfil}.
@end table

@node Invocando guix archive
@section Invocando @command{guix archive}

@cindex @command{guix archive}
@cindex arquivo
@cindex exportando arquivos do armazém
@cindex importando arquivos para o armazém
O comando @command{guix archive} permite que os usuários @dfn{exportem}
arquivos do armazém para um único arquivamento e depois @dfn{importem} eles
em uma máquina que execute o Guix. Em particular, ele permite que os
arquivos do armazém sejam transferidos de uma máquina para o store em outra
máquina.

@quotation Nota
Se você estiver procurando uma maneira de produzir arquivamentos em um
formato adequado para outras ferramentas além do Guix, @pxref{Invocando guix pack}.
@end quotation

@cindex exportando itens do armazém
Para exportar arquivos de armazém como um arquivamento para saída padrão,
execute:

@example
guix archive --export @var{opções} @var{especificações}...
@end example

@var{especificações} pode ser nomes de arquivos de armazém ou especificações
de pacotes, como para @command{guix package} (@pxref{Invocando guix package}). Por exemplo, o comando a seguir cria um arquivo contendo a saída
@code{gui} do pacote @code{git} e a saída principal de @code{emacs}:

@example
guix archive --export git:gui /gnu/store/...-emacs-24.3 > great.nar
@end example

Se os pacotes especificados ainda não foram construídos, @command{guix
archive} os constrói automaticamente. O processo de construção pode ser
controlado com as opções comuns de construção (@pxref{Opções de compilação comuns}).

Para transferir o pacote @code{emacs} para uma máquina conectada via SSH,
execute:

@example
guix archive --export -r emacs | ssh a-máquina guix archive --import
@end example

@noindent
Da mesma forma, um perfil de usuário completo pode ser transferido de uma
máquina para outra assim:

@example
guix archive --export -r $(readlink -f ~/.guix-profile) | \
  ssh a-máquina guix archive --import
@end example

@noindent
No entanto, observe que, em ambos os exemplos, todos os @code{emacs} e o
perfil, bem como todas as suas dependências são transferidos (devido a
@option{-r}), independentemente do que já esteja disponível no armazém na
máquina de destino. A opção @option{--missing} pode ajudar a descobrir quais
itens estão faltando no armazém de destino. O comando @command{guix copy}
simplifica e otimiza todo esse processo, então é provavelmente isso que você
deve usar neste caso (@pxref{Invocando guix copy}).

@cindex nar, formato de arquivamento
@cindex arquivamento normalizado (nar)
@cindex embalagem nar, formato de arquivamento
Cada item do armazém é escrito no formato @dfn{arquivamento normalizado} ou
@dfn{nar} (descrito abaixo), e a saída de @command{guix archive --export} (e
entrada de @command{guix archive --import}) é uma @dfn{embalagem nar}.

O formato nar é comparável em espírito ao `tar', mas com diferenças que o
tornam mais apropriado para nossos propósitos. Primeiro, em vez de registrar
todos os metadados Unix para cada arquivo, o formato nar menciona apenas o
tipo de arquivo (regular, diretório ou ligação simbólica); permissões Unix e
proprietário/grupo são descartados. Segundo, a ordem em que as entradas de
diretório são armazenadas sempre segue a ordem dos nomes de arquivo de
acordo com a ordem de agrupamento de localidade C. Isso torna a produção de
arquivo totalmente determinística.

O formato da embalagem nar é essencialmente a concatenação de zero ou mais
nars junto com metadados para cada item de armazém que ele contém: seu nome
de arquivo, referências, derivação correspondente e uma assinatura digital.

@c FIXME: Add xref to daemon doc about signatures.
Ao exportar, o daemon assina digitalmente o conteúdo do arquivamento, e essa
assinatura digital é anexada. Ao importar, o daemon verifica a assinatura e
rejeita a importação em caso de uma assinatura inválida ou se a chave de
assinatura não for autorizada.

As principais opções são:

@table @code
@item --export
Exporte os arquivos de armazém ou pacotes especificados (veja abaixo). Grave
o arquivo resultante na saída padrão.

Dependências @emph{não} são incluídas na saída, a menos que
@option{--recursive} seja passado.

@item -r
@itemx --recursive
Quando combinado com @option{--export}, isso instrui @command{guix archive}
a incluir dependências dos itens fornecidos no arquivo. Assim, o arquivo
resultante é autocontido: ele contém o fechamento dos itens exportados do
armazém.

@item --import
Leia um arquivo da entrada padrão e importe os arquivos listados nele para o
armazém. Aborte se o arquivo tiver uma assinatura digital inválida ou se for
assinado por uma chave pública que não esteja entre as chaves autorizadas
(veja @option{--authorize} abaixo).

@item --missing
Leia uma lista de nomes de arquivos do armazém da entrada padrão, um por
linha, e escreva na saída padrão o subconjunto desses arquivos que faltam no
armazém.

@item --generate-key[=@var{parâmetros}]
@cindex assinatura, arquivos
Gere um novo par de chaves para o daemon. Este é um pré-requisito antes que
os arquivos possam ser exportados com @option{--export}. Esta operação é
geralmente instantânea, mas pode levar algum tempo se o pool de entropia do
sistema precisar ser recarregado. No Guix System, @code{guix-service-type}
cuida da geração deste par de chaves na primeira inicialização.

O par de chaves gerado é normalmente armazenado em @file{/etc/guix}, em
@file{signing-key.pub} (chave pública) e @file{signing-key.sec} (chave
privada, que deve ser mantida em segredo). Quando @var{parâmetros} é
omitido, uma chave ECDSA usando a curva Ed25519 é gerada ou, para versões do
Libgcrypt anteriores a 1.6.0, é uma chave RSA de 4096 bits. Como
alternativa, @var{parâmetros} pode especificar parâmetros @code{genkey}
adequados para Libgcrypt (@pxref{General public-key related Functions,
@code{gcry_pk_genkey},, gcrypt, Manual de referência do Libgcrypt}).

@item --authorize
@cindex autorizando, arquivamentos
Autorize importações assinadas pela chave pública passada na entrada
padrão. A chave pública deve estar em ``s-expression advanced
format''---i.e., o mesmo formato do arquivo @file{signing-key.pub}.

A lista de chaves autorizadas é mantida no arquivo editável por humanos
@file{/etc/guix/acl}. O arquivo contém
@url{https://people.csail.mit.edu/rivest/Sexp.txt, ``advanced-format
s-expressions''} e é estruturado como uma lista de controle de acesso no
@url{https://theworld.com/~cme/spki.txt, Simple Public-Key Infrastructure
(SPKI)}.

@item --extract=@var{diretório}
@itemx -x @var{diretório}
Leia um arquivo de item único conforme servido por servidores substitutos
(@pxref{Substitutos}) e extraia-o para @var{diretório}. Esta é uma operação
de baixo nível necessária apenas em casos de uso muito restritos; veja
abaixo.

Por exemplo, o comando a seguir extrai o substituto para o Emacs servido por
@code{@value{SUBSTITUTE-SERVER-1}} para @file{/tmp/emacs}:

@example
$ wget -O - \
  https://@value{SUBSTITUTE-SERVER-1}/nar/gzip/@dots{}-emacs-24.5 \
  | gunzip | guix archive -x /tmp/emacs
@end example

Arquivamentos de item único são diferentes de arquivamentos de itens
múltiplos produzidos por @command{guix archive --export}; eles contêm um
único item de armazém e não @emph{incorporam} uma assinatura. Portanto, essa
operação não faz @emph{nenhuma} verificação de assinatura e sua saída deve
ser considerada insegura.

O objetivo principal desta operação é facilitar a inspeção de conteúdos de
arquivamento provenientes de servidores substitutos possivelmente não
confiáveis (@pxref{Invocando guix challenge}).

@item --list
@itemx -t
Leia um arquivamento de item único servido por servidores substitutos
(@pxref{Substitutos}) e exiba a lista de arquivos que ele contém, como neste
exemplo:

@example
$ wget -O - \
  https://@value{SUBSTITUTE-SERVER-1}/nar/lzip/@dots{}-emacs-26.3 \
  | lzip -d | guix archive -t
@end example

@end table

@c *********************************************************************
@node Canais
@chapter Canais

@cindex channels
@cindex @file{channels.scm}, arquivo de configuração
@cindex arquivo de configuração para canais
@cindex @command{guix pull}, arquivo de configuração
@cindex configuração de @command{guix pull}
Guix e sua coleção de pacotes são atualizados executando @command{guix
pull}. Por padrão, @command{guix pull} baixa e implementa o próprio Guix do
repositório oficial GNU@tie{}Guix. Isso pode ser personalizado fornecendo um
arquivo especificando o conjunto de @dfn{canais} para extrair de
(@pxref{Invocando guix pull}). Um canal especifica a URL e a ramificação de
um repositório Git a ser implantado, e @command{guix pull} pode ser
instruído a extrair de um ou mais canais. Em outras palavras, os canais
podem ser usados para @emph{personalizar} e @emph{estender} o Guix, como
veremos abaixo. O Guix é capaz de levar em conta preocupações de segurança e
lidar com atualizações autenticadas.

@menu
* Especificando canais adicionais::  Ampliando a coleta de pacotes.
* Usando um canal Guix personalizado::  Usando um Guix personalizado.
* Replicando Guix::          Executando o @emph{exatamente o mesmo} Guix.
* Customizing the System-Wide Guix::  Default channels on Guix System.
* Autenticação de canal::    Como o Guix verifica o que busca.
* Canais com substitutos::   Utilizando canais com substitutos disponíveis.
* Criando um canal::         Como escrever seu canal personalizado.
* Módulos de pacote em um subdiretório::  Especificando a localização dos 
                                            módulos do pacote do canal.
* Declarando dependências de canal::  Como depender de outros canais.
* Especificando autorizações de canal::  Definindo autorizações de autores 
                                           de canais.
* URL principal::            Distinguir o espelho do original.
* Escrevendo notícias do canal::  Comunicar informações aos usuários do 
                                    canal.
@end menu

@node Especificando canais adicionais
@section Especificando canais adicionais

@cindex estendendo a coleção de pacotes (canais)
@cindex pacotes variantes (canais)
Você pode especificar @emph{canais adicionais} para puxar. Para usar um
canal, escreva @code{~/.config/guix/channels.scm} para instruir
@command{guix pull} para puxar dele @emph{além} do(s) canal(ais) Guix
padrão:

@vindex %default-channels
@lisp
;; Adicione pacotes variantes aos fornecidos pelo Guix.
(cons (channel
        (name 'variant-packages)
        (url "https://example.org/variant-packages.git"))
      %default-channels)
@end lisp

@noindent
Note que o snippet acima é (como sempre!)@: código do Scheme; usamos
@code{cons} para adicionar um canal à lista de canais aos quais a variável
@code{%default-channels} está vinculada (@pxref{Pairs, @code{cons} and
lists,, guile, GNU Guile Reference Manual}). Com esse arquivo no lugar,
@command{guix pull} compila não apenas o Guix, mas também os módulos do
pacote do seu próprio repositório. O resultado em
@file{~/.config/guix/current} é a união do Guix com seus próprios módulos do
pacote:

@example
$ guix describe
Geração 19	27 ago 2018 16:20:48
  guix d894ab8
    URL do repositório: https://git.guix.gnu.org/guix.git
    ramo: master
    commit: d894ab8e9bfabcefa6c49d9ba2e834dd5a73a300
  variant-packages dd3df5e
    URL do repositório: https://example.org/variant-packages.git
    ramo: master
    commit: dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb
@end example

@noindent
A saída do @command{guix describe} acima mostra que agora estamos executando
o geração@tie{}19 e que ele inclui o Guix e os pacotes do canal
@code{variant-packages} (@pxref{Invocando guix describe}).

@node Usando um canal Guix personalizado
@section Usando um canal Guix personalizado

O canal chamado @code{guix} especifica onde o próprio Guix---suas
ferramentas de linha de comando, bem como sua coleção de pacotes---deve ser
baixado. Por exemplo, suponha que você queira atualizar de outra cópia do
repositório Guix em @code{example.org}, e especificamente o branch
@code{super-hacks}, você pode escrever em @code{~/.config/guix/channels.scm}
esta especificação:

@lisp
;; Diga ao 'guix pull' para usar outro repositório.
(list (channel
        (name 'guix)
        (url "https://example.org/another-guix.git")
        (branch "super-hacks")))
@end lisp

@noindent
A partir daí, @command{guix pull} buscará o código do branch
@code{super-hacks} do repositório em @code{example.org}. A preocupação com a
autenticação é abordada abaixo (@pxref{Autenticação de canal}).

Note que você pode especificar um diretório local no campo @code{url} acima
se o canal que você pretende usar residir em um sistema de arquivos
local. No entanto, neste caso, @command{guix} verifica o diretório em busca
de propriedade antes de qualquer processamento posterior. Isso significa que
se o usuário não for o proprietário do diretório, mas quiser usá-lo como
padrão, ele precisará defini-lo como um diretório seguro em seu arquivo de
configuração global do git. Caso contrário, @command{guix} se recusará até
mesmo a lê-lo. Supondo que seu diretório local de todo o sistema esteja em
@code{/src/guix.git}, você criaria um arquivo de configuração do git em
@code{~/.gitconfig} com o seguinte conteúdo:

@example
[safe]
        directory = /src/guix.git
@end example

@noindent
Isso também se aplica ao usuário root, a menos que seja chamado com
@command{sudo} pelo proprietário do diretório.

@node Replicando Guix
@section Replicando Guix

@cindex fixação, canais
@cindex replicando Guix
@cindex reprodutibilidade, de Guix
O comando @command{guix describe} mostra precisamente quais commits foram
usados para construir a instância do Guix que estamos usando
(@pxref{Invocando guix describe}). Podemos replicar essa instância em outra
máquina ou em um ponto diferente no tempo fornecendo uma especificação de
canal ``fixada'' a esses commits que se parece com isso:

@lisp
;; Implantar commits específicos dos meus canais de interesse.
(list (channel
       (name 'guix)
       (url "https://git.guix.gnu.org/guix.git")
       (commit "6298c3ffd9654d3231a6f25390b056483e8f407c"))
      (channel
       (name 'variant-packages)
       (url "https://example.org/variant-packages.git")
       (commit "dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb")))
@end lisp

Para obter essa especificação de canal fixado, a maneira mais fácil é
executar @command{guix describe} e salvar sua saída no formato
@code{channels} em um arquivo, assim:

@example
guix describe -f channels > channels.scm
@end example

O arquivo @file{channels.scm} resultante pode ser passado para a opção
@option{-C} de @command{guix pull} (@pxref{Invocando guix pull}) ou
@command{guix time-machine} (@pxref{Invocando guix time-machine}), como neste
exemplo:

@example
guix time-machine -C channels.scm -- shell python -- python3
@end example

Dado o arquivo @file{channels.scm}, o comando acima sempre buscará a
@emph{exatamente a mesma instância Guix}, então usará essa instância para
executar exatamente o mesmo Python (@pxref{Invocando guix shell}). Em
qualquer máquina, a qualquer momento, ele acaba executando exatamente os
mesmos binários, bit por bit.

@cindex arquivo de bloqueio
Os canais fixados abordam um problema semelhante a ``arquivos de bloqueio''
conforme implementado por algumas ferramentas de implantação --- eles
permitem que você fixe e reproduza um conjunto de pacotes. No caso do Guix,
no entanto, você está efetivamente fixando o conjunto de pacotes inteiro
conforme definido nos commits de canal fornecidos; na verdade, você está
fixando todo o Guix, incluindo seus módulos principais e ferramentas de
linha de comando. Você também está obtendo fortes garantias de que está, de
fato, obtendo exatamente o mesmo software.

Isso lhe dá superpoderes, permitindo que você rastreie a procedência de
artefatos binários com granularidade muito fina e reproduza ambientes de
software à vontade --- algum tipo de capacidade de ``meta
reprodutibilidade'', se preferir. @xref{Inferiores}, para outra maneira de
aproveitar esses superpoderes.

@node Customizing the System-Wide Guix
@section Customizing the System-Wide Guix

@cindex system-wide Guix, customization
@cindex canais, para o Guix padrão
Se você estiver executando o Guix System ou construindo imagens de sistema
com ele, talvez você queira personalizar o @command{guix} de todo o sistema
que ele fornece---especificamente,
@file{/run/current-system/profile/bin/guix}. Por exemplo, você pode querer
fornecer canais adicionais ou fixar sua revisão.

Isso pode ser feito usando o procedimento @code{guix-for-channels}, que
retorna um pacote para os canais fornecidos e o usa como parte da
configuração do seu sistema operacional, como neste exemplo:

@lisp
(use-modules (gnu packages package-management)
             (guix channels))

(define my-channels
  ;; Canais que devem estar disponíveis para
  ;; /run/current-system/profile/bin/guix.
  (append
   (list (channel
          (name 'guix-science)
          (url "https://codeberg.org/guix-science/guix-science")
          (branch "master")))
   %default-channels))

(operating-system
  ;; @dots{}
  (services
    ;; Change the package used by 'guix-service-type'.
    (modify-services %base-services
      (guix-service-type
       config => (guix-configuration
                  (inherit config)
                  (channels my-channels)
                  (guix (guix-for-channels my-channels)))))))
@end lisp

O sistema operacional resultante terá os canais @code{guix} e
@code{guix-science} visíveis por padrão. O campo @code{channels} de
@code{guix-configuration} acima garante ainda mais que
@file{/etc/guix/channels.scm}, que é usado por @command{guix pull},
especifica o mesmo conjunto de canais (@pxref{guix-configuration-channels,
campo @code{channels} de @code{guix-configuration}}).

O módulo @code{(gnu packages package-management)} exporta o procedimento
@code{guix-for-channels}, descrito abaixo.

@deffn {Procedimento} guix-for-channels @var{canais}
Retorna um pacote correspondente a @var{canais}.

O resultado é um pacote ``regular'', que pode ser usado em
@code{guix-configuration} como mostrado acima ou em qualquer outro lugar que
espere um pacote.
@end deffn

@node Autenticação de canal
@section Autenticação de canal

@anchor{channel-authentication}
@cindex autenticação, de código de canal
Os comandos @command{guix pull} e @command{guix time-machine}
@dfn{autenticam} o código recuperado dos canais: eles garantem que cada
commit que é buscado seja assinado por um desenvolvedor autorizado. O
objetivo é proteger contra modificações não autorizadas no canal que
levariam os usuários a executar código malicioso.

Como usuário, você deve fornecer uma @dfn{introdução de canal} no seu
arquivo de canais para que o Guix saiba como autenticar seu primeiro
commit. Uma especificação de canal, incluindo sua introdução, parece algo
como estas linhas:

@lisp
(channel
  (name 'algum-canal)
  (url "https://example.org/algum-canal.git")
  (introduction
   (make-channel-introduction
    "6f0d8cc0d88abb59c324b2990bfee2876016bb86"
    (openpgp-fingerprint
     "CABB A931 C0FF EEC6 900D  0CFB 090B 1199 3D9A EBB5"))))
@end lisp

A especificação acima mostra o nome e a URL do canal. A chamada para
@code{make-channel-introduction} acima especifica que a autenticação deste
canal começa no commit @code{6f0d8cc@dots{}}, que é assinado pela chave
OpenPGP com impressão digital @code{CABB A931@dots{}}.

Para o canal principal, chamado @code{guix}, você obtém automaticamente
essas informações da sua instalação Guix. Para outros canais, inclua a
introdução do canal fornecida pelos autores do canal no seu arquivo
@file{channels.scm}. Certifique-se de recuperar a introdução do canal de uma
fonte confiável, pois essa é a raiz da sua confiança.

Se você está curioso sobre a mecânica de autenticação, continue lendo!

@node Canais com substitutos
@section Canais com substitutos

Ao executar @command{guix pull}, o Guix primeiro compilará as definições de
cada pacote disponível. Esta é uma operação cara para a qual substitutos
(@pxref{Substitutos}) podem estar disponíveis. O seguinte snippet em
@file{channels.scm} garantirá que o @command{guix pull} use o commit mais
recente com substitutos disponíveis para as definições de pacote: isso é
feito consultando o servidor de integração contínua em
@url{https://ci.guix.gnu.org}.

@lisp
(use-modules (guix ci))

(list (channel-with-substitutes-available
       %default-guix-channel
       "https://ci.guix.gnu.org"))
@end lisp

Note que isso não significa que todos os pacotes que você instalará após
executar @command{guix pull} terão substitutos disponíveis. Isso apenas
garante que @command{guix pull} não tentará compilar definições de
pacotes. Isso é particularmente útil ao usar máquinas com recursos
limitados.

@node Criando um canal
@section Criando um canal

@cindex pacotes pessoais (canais)
@cindex canais, para pacotes pessoais
Digamos que você tenha um monte de variantes de pacotes personalizados ou
pacotes pessoais que você acha que faria pouco sentido contribuir para o
projeto Guix, mas gostaria de ter esses pacotes disponíveis de forma
transparente para você na linha de comando. Ao criar um @dfn{canal}, você
pode usar e publicar tal coleção de pacotes. Isso envolve as seguintes
etapas:

@enumerate
@item
Um canal fica em um repositório Git, então o primeiro passo, ao criar um
canal, é criar seu repositório:

@example
mkdir meu-canal
cd meu-canal
git init
@end example

@item
O próximo passo é criar arquivos contendo módulos de pacote (@pxref{Módulos de pacote}), cada um dos quais conterá uma ou mais definições de pacote
(@pxref{Definindo pacotes}). Um canal pode fornecer coisas além de pacotes,
como sistemas de compilação ou serviços; estamos usando pacotes, pois é o
caso de uso mais comum.

Por exemplo, Alice pode querer fornecer um módulo chamado @code{(alice
packages greetings)} que fornecerá suas implementações favoritas de ``hello
world''. Para fazer isso, Alice criará um diretório correspondente ao nome
desse módulo.

@example
mkdir -p alice/packages
$EDITOR alice/packages/greetings.scm
git add alice/packages/greetings.scm
@end example

Você pode nomear seus módulos de pacote como quiser; a principal restrição a
ter em mente é evitar conflitos de nomes com outras coleções de pacotes, e é
por isso que nossa hipotética Alice sabiamente escolheu o namespace
@code{(alice packages @dots{})}.

Observe que você também pode colocar módulos em um subdiretório do
repositório; @pxref{Módulos de pacote em um subdiretório}, para mais
informações sobre isso.

@item
Com este primeiro módulo em funcionamento, o próximo passo é testar os
pacotes que ele fornece. Isso pode ser feito com @command{guix build}, que
precisa ser informado para procurar módulos no checkout do Git. Por exemplo,
supondo que @code{(alice packages greetings)} forneça um pacote chamado
@code{hi-from-alice}, Alice executará este comando do checkout do Git:

@example
guix build -L. hi-from-alice
@end example

@noindent
... onde @code{-L.} adiciona o diretório atual ao caminho de carregamento do
Guile (@pxref{Load Paths,,, guile, Manual de referência do GNU Guile}).

@item
Pode levar algumas iterações para Alice obter definições de pacote
satisfatórias. Eventualmente, Alice fará commit deste arquivo:

@example
git commit
@end example

Como autor de um canal, considere agrupar material de autenticação com seu
canal para que os usuários possam autenticá-lo. @xref{Autenticação de canal} e @ref{Especificando autorizações de canal} para obter
informações sobre como fazer isso.

@item
Para usar o canal de Alice, qualquer pessoa pode adicioná-lo ao seu arquivo
de canal (@pxref{Especificando canais adicionais}) e executar @command{guix
pull} (@pxref{Invocando guix pull}):

@example
$EDITOR ~/.config/guix/channels.scm
guix pull
@end example

Guix agora se comportará como se o diretório raiz do repositório Git daquele
canal tivesse sido adicionado permanentemente ao caminho de carregamento do
Guile. Neste exemplo, @code{(alice packages greetings)} será encontrado
automaticamente pelo comando @command{guix}.
@end enumerate

Voilà!

@c What follows stems from discussions at
@c <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=22629#134> as well as
@c earlier discussions on guix-devel@gnu.org.
@c Updated in 2025 to refer to the Deprecation Policy.
@quotation Aviso
Antes de publicar seu canal, gostaríamos de compartilhar algumas palavras de
cautela:

@itemize
@item
Antes de publicar um canal, considere contribuir com suas definições de
pacote para o Guix propriamente dito (@pxref{Contribuindo}). O Guix como um
projeto é aberto a software livre de todos os tipos, e os pacotes no Guix
propriamente dito estão prontamente disponíveis para todos os usuários do
Guix e se beneficiam do processo de garantia de qualidade do projeto.

@item
Package modules and package definitions are Scheme code that uses various
programming interfaces (APIs).  Those may occasionally change, in accordance
with our deprecation policy (@pxref{Política de depreciação}), and it is your
responsibility as a channel author to adjust your code accordingly.

@item
Corolário: se você estiver usando um canal externo e esse canal quebrar,
@emph{reporte o problema aos autores do canal}, não ao projeto Guix.
@end itemize

Você foi avisado! Dito isso, acreditamos que canais externos são uma maneira
prática de exercer sua liberdade para aumentar a coleção de pacotes do Guix
e compartilhar suas melhorias, que são princípios básicos do
@uref{https://www.gnu.org/philosophy/free-sw.html, software livre}. Por
favor, envie um e-mail para @email{guix-devel@@gnu.org} se você quiser
discutir isso.
@end quotation



@node Módulos de pacote em um subdiretório
@section Módulos de pacote em um subdiretório

@cindex subdiretório, canais
Como autor de canal, você pode querer manter seus módulos de canal em um
subdiretório. Se seus módulos estiverem no subdiretório @file{guix}, você
deve adicionar um arquivo de metadados @file{.guix-channel} que contenha:

@lisp
(channel
  (version 0)
  (directory "guix"))
@end lisp

Os módulos devem estar @b{abaixo} do diretório especificado, pois o
diretório @code{directory} altera o @code{load-path} do Guile. Por exemplo,
se @file{.guix-channel} tiver @code{(directory "base")}, então um módulo
definido como @code{(define-module (gnu packages fun))} deve estar
localizado em @code{base/gnu/packages/fun.scm}.

Fazer isso permite que apenas partes de um repositório sejam usadas como um
canal, pois o Guix espera módulos Guile válidos ao puxar. Por exemplo, os
arquivos de configuração de máquina @command{guix deploy} não são módulos
Guile válidos, e tratá-los como tal faria com que @command{guix pull}
falhasse.

@node Declarando dependências de canal
@section Declarando dependências de canal

@cindex dependências, canais
@cindex metadados, canais
Os autores de canais podem decidir aumentar uma coleção de pacotes fornecida
por outros canais. Eles podem declarar que seu canal é dependente de outros
canais em um arquivo de metadados @file{.guix-channel}, que deve ser
colocado na raiz do repositório do canal.

O arquivo de metadados deve conter uma expressão S simples como esta:

@lisp
(channel
 (version 0)
 (dependencies
  (channel
   (name algum-coleção)
   (url "https://example.org/first-collection.git")

   ;; The 'introduction' bit below is optional: you would
   ;; provide it for dependencies that can be authenticated.
   (introduction
    (channel-introduction
      (version 0)
      (commit "a8883b58dc82e167c96506cf05095f37c2c2c6cd")
      (signer "CABB A931 C0FF EEC6 900D  0CFB 090B 1199 3D9A EBB5"))))
  (channel
   (name some-other-collection)
   (url "https://example.org/second-collection.git")
   (branch "testing"))))
@end lisp

No exemplo acima, este canal é declarado para depender de dois outros
canais, que serão buscados automaticamente. Os módulos fornecidos pelo canal
serão compilados em um ambiente onde os módulos de todos esses canais
declarados estão disponíveis.

Por uma questão de confiabilidade e manutenibilidade, você deve evitar
dependências em canais que você não controla e deve tentar manter o número
de dependências no mínimo.

@node Especificando autorizações de canal
@section Especificando autorizações de canal

@cindex autorizações de canal
@anchor{channel-authorizations}
Como vimos acima, o Guix garante que o código-fonte que ele extrai dos
canais vem de desenvolvedores autorizados. Como autor de um canal, você
precisa especificar a lista de desenvolvedores autorizados no arquivo
@file{.guix-authorizations} no repositório Git do canal. A regra de
autenticação é simples: cada commit deve ser assinado por uma chave listada
no arquivo @file{.guix-authorizations} de seu(s) commit(s)
pai(s)@footnote{Os commits do Git formam um @dfn{gráfico acíclico
direcionado} (DAG). Cada commit pode ter zero ou mais pais; os commits
``regulares'' têm um pai e os commits de mesclagem têm dois commits
pais. Leia @uref{https://eagain.net/articles/git-for-computer-scientists/,
@i{Git para cientistas da computação}} para uma ótima visão geral.} O
arquivo @file{.guix-authorizations} se parece com isso:

@lisp
;; Exemplo de arquivo '.guix-authorizations'.

(authorizations
 (version 0)               ;current file format version

 (("AD17 A21E F8AE D8F1 CC02  DBD9 F8AE D8F1 765C 61E3"
   (name "alice"))
  ("2A39 3FFF 68F4 EF7A 3D29  12AF 68F4 EF7A 22FB B2D5"
   (name "bob"))
  ("CABB A931 C0FF EEC6 900D  0CFB 090B 1199 3D9A EBB5"
   (name "charlie"))))
@end lisp

Cada impressão digital é seguida por pares chave/valor opcionais, como no
exemplo acima. Atualmente, esses pares chave/valor são ignorados.

Esta regra de autenticação cria um problema do tipo "ovo e galinha": como
autenticamos o primeiro commit? Relacionado a isso: como lidamos com canais
cujo histórico de repositório contém commits não assinados e não tem
@file{.guix-authorizations}? E como bifurcamos canais existentes?

@cindex introdução do canal
As introduções de canal respondem a essas perguntas descrevendo o primeiro
commit de um canal que deve ser autenticado. Na primeira vez que um canal é
buscado com @command{guix pull} ou @command{guix time-machine}, o comando
procura o commit introdutório e verifica se ele está assinado pela chave
OpenPGP especificada. A partir daí, ele autentica os commits de acordo com a
regra acima. A autenticação falha se o commit de destino não for descendente
nem ancestral do commit introdutório.

Além disso, seu canal deve fornecer todas as chaves OpenPGP que já foram
mencionadas em @file{.guix-authorizations}, armazenadas como arquivos
@file{.key}, que podem ser binários ou ``ASCII-armored''. Por padrão, esses
arquivos @file{.key} são pesquisados no branch chamado @code{keyring}, mas
você pode especificar um nome de branch diferente em @code{.guix-channel}
assim:

@lisp
(channel
  (version 0)
  (keyring-reference "my-keyring-branch"))
@end lisp

Para resumir, como autor de um canal, há três coisas que você precisa fazer
para permitir que os usuários autentiquem seu código:

@enumerate
@item
Exporte as chaves OpenPGP de contribuidores anteriores e atuais com
@command{gpg --export} e armazene-as em arquivos @file{.key}, por padrão em
uma ramificação chamada @code{keyring} (recomendamos torná-la uma
@dfn{ramificação órfã}).

@item
Introduza um @file{.guix-authorizations} inicial no repositório do
canal. Faça isso em um commit assinado (@pxref{Confirmar acesso}, para obter
informações sobre como assinar commits do Git).

@item
Anuncie a introdução do canal, por exemplo, na página web do seu canal. A
introdução do canal, como vimos acima, é o par commit/chave---i.e., o commit
que introduziu @file{.guix-authorizations}, e a impressão digital do OpenPGP
usada para assiná-lo.
@end enumerate

Antes de enviar para seu repositório Git público, você pode executar
@command{guix git authenticate} para verificar se você assinou todos os
commits que está prestes a enviar com uma chave autorizada:

@example
guix git authenticate @var{commit} @var{signer}
@end example

@noindent
onde @var{commit} e @var{signer} são a introdução do seu
canal. @xref{Invocando guix git authenticate}, para detalhes.

Publicar um canal assinado requer disciplina: qualquer erro, como um commit
não assinado ou um commit assinado por uma chave não autorizada, impedirá
que usuários puxem do seu canal --- bem, esse é o ponto principal da
autenticação! Preste atenção às mesclagens em particular: commits de
mesclagem são considerados autênticos se e somente se forem assinados por
uma chave presente no arquivo @file{.guix-authorizations} de @emph{ambos} os
ramos.

@node URL principal
@section URL principal

@cindex URL principal, canais
Os autores do canal podem indicar a URL principal do repositório Git do
canal no arquivo @file{.guix-channel}, assim:

@lisp
(channel
  (version 0)
  (url "https://example.org/guix.git"))
@end lisp

Isso permite que @command{guix pull} determine se está puxando código de um
espelho do canal; quando esse for o caso, ele avisa o usuário que o espelho
pode estar obsoleto e exibe a URL primária. Dessa forma, os usuários não
podem ser enganados para buscar código de um espelho obsoleto que não recebe
atualizações de segurança.

Esse recurso só faz sentido para repositórios autenticados, como o canal
oficial @code{guix}, para o qual @command{guix pull} garante que o código
que ele recupera é autêntico.

@node Escrevendo notícias do canal
@section Escrevendo notícias do canal

@cindex notícias, para canais
Os autores do canal podem ocasionalmente querer comunicar aos seus usuários
informações sobre mudanças importantes no canal. Você enviaria um e-mail
para todos eles, mas isso não é conveniente.

Em vez disso, os canais podem fornecer um @dfn{arquivo de notícias}; quando
os usuários do canal executam @command{guix pull}, esse arquivo de notícias
é lido automaticamente e @command{guix pull --news} pode exibir os anúncios
que correspondem aos novos commits que foram extraídos, se houver.

Para fazer isso, os autores do canal devem primeiro declarar o nome do
arquivo de notícias em seu arquivo @file{.guix-channel}:

@lisp
(channel
  (version 0)
  (news-file "etc/news.txt"))
@end lisp

O arquivo de notícias em si, @file{etc/news.txt} neste exemplo, deve ser
parecido com isto:

@lisp
(channel-news
  (version 0)
  (entry (tag "the-bug-fix")
         (title (en "Fixed terrible bug")
                (fr "Oh la la"))
         (body (en "@@emph@{Good news@}!  It's fixed!")
               (eo "Certe ĝi pli bone funkcias nun!")))
  (entry (commit "bdcabe815cd28144a2d2b4bc3c5057b051fa9906")
         (title (en "Added a great package")
                (ca "Què vol dir guix?"))
         (body (en "Don't miss the @@code@{hello@} package!"))))
@end lisp

Enquanto o arquivo de notícias estiver usando a sintaxe Scheme, evite
nomeá-lo com uma extensão @file{.scm} ou então ele será pego ao construir o
canal e gerará um erro, pois não é um módulo válido. Como alternativa, você
pode mover o módulo do canal para um subdiretório e armazenar o arquivo de
notícias em outro diretório.

O arquivo consiste em uma lista de @dfn{entradas de notícias}. Cada entrada
é associada a um commit ou tag: ela descreve as alterações feitas neste
commit, possivelmente em commits anteriores também. Os usuários veem as
entradas somente na primeira vez que obtêm o commit ao qual a entrada se
refere.

O campo @code{title} deve ser um resumo de uma linha, enquanto @code{body}
pode ser arbitrariamente longo, e ambos podem conter marcação Texinfo
(@pxref{Overview,,, texinfo, GNU Texinfo}). Tanto o título quanto o corpo
são uma lista de tuplas de tag/mensagem de idioma, o que permite que
@command{guix pull} exiba notícias no idioma que corresponde à localidade do
usuário.

Se você quiser traduzir notícias usando um fluxo de trabalho baseado em
gettext, você pode extrair strings traduzíveis com @command{xgettext}
(@pxref{xgettext Invocation,,, gettext, GNU Gettext Utilities}). Por
exemplo, supondo que você escreva entradas de notícias em inglês primeiro, o
comando abaixo cria um arquivo PO contendo as strings a serem traduzidas:

@example
xgettext -o news.po -l scheme -ken etc/news.txt
@end example

Para resumir, sim, você pode usar seu canal como um blog. Mas cuidado, isso
é @emph{não é bem} o que seus usuários podem esperar.

@c *********************************************************************
@node Desenvolvimento
@chapter Desenvolvimento

@cindex desenvolvimento de software
Se você é um desenvolvedor de software, o Guix fornece ferramentas que você
achará úteis, independentemente da linguagem em que estiver desenvolvendo. É
sobre isso que este capítulo trata.

O comando @command{guix shell} fornece uma maneira conveniente de configurar
ambientes de software únicos, seja para fins de desenvolvimento ou para
executar um comando sem instalá-lo em seu perfil. O comando @command{guix
pack} permite que você crie @dfn{embalagens de aplicativos} que podem ser
facilmente distribuídas para usuários que não executam o Guix.

@menu
* Invocando guix shell::     Spawning one-off software environments.
* Invocando guix environment::  Configurando ambientes de desenvolvimento.
* Invocando guix pack::      Criando embalagens de software.
* A cadeia de ferramentas do GCC::  Trabalhando com idiomas suportados pelo 
                                      GCC.
* Invocando guix git authenticate::  Autenticando repositórios Git.
@end menu

@node Invocando guix shell
@section Invocando @command{guix shell}

@cindex ambientes de construção reproduzíveis
@cindex ambientes de desenvolvimento
@cindex @command{guix environment}
@cindex @command{guix shell}
@cindex ambiente, ambiente de construção de pacotes
O propósito do @command{guix shell} é facilitar a criação de ambientes de
software únicos, sem alterar o perfil. Ele é normalmente usado para criar
ambientes de desenvolvimento; também é uma maneira conveniente de executar
aplicativos sem ``poluir'' seu perfil.

@quotation Nota
O comando @command{guix shell} foi introduzido recentemente para substituir
@command{guix environment} (@pxref{Invocando guix environment}). Se você
estiver familiarizado com @command{guix environment}, notará que ele é
semelhante, mas também---esperamos!---mais conveniente.
@end quotation

A sintaxe geral é:

@example
guix shell [@var{opções}] [@var{pacote}@dots{}]
@end example

Às vezes, uma sessão de shell interativa não é desejada. Um comando
arbitrário pode ser invocado colocando o token @code{--} para separar o
comando do resto dos argumentos.

O exemplo a seguir cria um ambiente contendo Python e NumPy, compilando ou
baixando qualquer pacote ausente e executa o comando @command{python3} nesse
ambiente:

@example
guix shell python python-numpy -- python3
@end example

Note que é necessário incluir o pacote principal @code{python} neste
comando, mesmo que ele já esteja instalado em seu ambiente. Isso é para que
o ambiente shell saiba definir @env{PYTHONPATH} e outras variáveis
relacionadas. O ambiente shell não pode verificar o ambiente instalado
anteriormente, porque então seria não determinístico. Isso é verdade para a
maioria das bibliotecas: seu pacote de linguagem correspondente deve ser
incluído na invocação do shell.

@quotation Nota
@cindex shebang, para @command{guix shell}
@command{guix shell} também pode ser usado como um interpretador de script,
também conhecido como @dfn{shebang}. Aqui está um exemplo de script Python
autocontido fazendo uso desse recurso:

@example
#!/usr/bin/env -S guix shell python python-numpy -- python3
import numpy
print("This is numpy", numpy.version.version)
@end example

Você pode passar qualquer opção @command{guix shell}, mas há uma ressalva: o
kernel Linux tem um limite de 127 bytes no comprimento do shebang.
@end quotation

Ambientes de desenvolvimento podem ser criados como no exemplo abaixo, que
gera um shell interativo contendo todas as dependências e variáveis de
ambiente necessárias para trabalhar no Inkscape:

@example
guix shell --development inkscape
@end example

Sair do shell coloca o usuário de volta no ambiente original antes de
@command{guix shell} ser invocado. A próxima coleta de lixo (@pxref{Invocando guix gc}) pode limpar pacotes que foram instalados no ambiente e que não são
mais usados fora dele.

Como uma conveniência adicional, @command{guix shell} tentará fazer o que
você quer dizer quando for invocado interativamente sem nenhum outro
argumento, como em:

@example
guix shell
@end example

Se encontrar um @file{manifest.scm} no diretório de trabalho atual ou em
qualquer um dos seus pais, ele usa esse manifesto como se tivesse sido
fornecido via @code{--manifest}. Da mesma forma, se encontrar um
@file{guix.scm} nos mesmos diretórios, ele o usa para construir um perfil de
desenvolvimento como se @code{--development} e @code{--file} estivessem
presentes. Em ambos os casos, o arquivo só será carregado se o diretório em
que ele reside estiver listado em
@file{~/.config/guix/shell-authorized-directories}. Isso fornece uma maneira
fácil de definir, compartilhar e entrar em ambientes de desenvolvimento.

Por padrão, a sessão ou comando do shell é executado em um ambiente
@emph{aumentado}, onde os novos pacotes são adicionados às variáveis de
ambiente do caminho de pesquisa, como @code{PATH}. Em vez disso, você pode
escolher criar um ambiente @emph{isolado} contendo apenas os pacotes
solicitados. Passar a opção @option{--pure} limpa as definições de variáveis
de ambiente encontradas no ambiente pai@footnote{Certifique-se de usar a
opção @option{--check} na primeira vez que usar @command{guix shell}
interativamente para garantir que o shell não desfaça o efeito de
@option{--pure}.}; passar @option{--container} vai um passo além ao gerar um
@dfn{contêiner} isolado do resto do sistema:

@example
guix shell --container emacs gcc-toolchain
@end example

O comando acima gera um shell interativo em um contêiner onde nada além de
@code{emacs}, @code{gcc-toolchain} e suas dependências estão disponíveis. O
contêiner não tem acesso à rede e não compartilha nenhum arquivo além do
diretório de trabalho atual com o ambiente ao redor. Isso é útil para evitar
acesso a recursos de todo o sistema, como @file{/usr/bin} em distros
estrangeiras.

Esta opção @option{--container} também pode ser útil se você deseja executar
um aplicativo sensível à segurança, como um navegador da web, em um ambiente
isolado. Por exemplo, o comando abaixo inicia o Ungoogled-Chromium em um
ambiente isolado, que:
@itemize
@item compartilha o acesso à rede com o host
@item herda as variáveis de ambiente do host @code{DISPLAY} e @code{XAUTHORITY}
@item tem acesso aos registros de autenticação do host do @code{XAUTHORITY}
file
@item não tem informações sobre o diretório atual do host
@end itemize

@example
guix shell --container --network --no-cwd ungoogled-chromium \
  --preserve='^XAUTHORITY$' --expose="$@{XAUTHORITY@}" \
  --preserve='^DISPLAY$' -- chromium
@end example

@vindex GUIX_ENVIRONMENT
@command{guix shell} define a variável @env{GUIX_ENVIRONMENT} no shell que
ele gera; seu valor é o nome do arquivo do perfil deste ambiente. Isso
permite que os usuários, digamos, definam um prompt específico para
ambientes de desenvolvimento em seu @file{.bashrc} (@pxref{Bash Startup
Files,,, bash, Manual de referência do GNU Bash}):

@example
if [ -n "$GUIX_ENVIRONMENT" ]
then
    export PS1="\u@@\h \w [dev]\$ "
fi
@end example

@noindent
...@: ou para navegar pelo perfil:

@example
$ ls "$GUIX_ENVIRONMENT/bin"
@end example

As opções disponíveis estão resumidas abaixo.

@table @code
@item --check
Configure o ambiente e verifique se o shell sobrecarregaria as variáveis de
ambiente. É uma boa ideia usar esta opção na primeira vez que você executar
@command{guix shell} para uma sessão interativa para garantir que sua
configuração esteja correta.

Por exemplo, se o shell modificar a variável de ambiente @env{PATH}, informe
isso, pois você obterá um ambiente diferente do que solicitou.

Tais problemas geralmente indicam que os arquivos de inicialização do shell
estão modificando inesperadamente essas variáveis de ambiente. Por exemplo,
se você estiver usando Bash, certifique-se de que as variáveis de ambiente
estejam definidas ou modificadas em @file{~/.bash_profile} e @emph{não} em
@file{~/.bashrc}---o primeiro é originado apenas por shells de
login. @xref{Bash Startup Files,,, bash, Manual de referência do GNU Bash},
para detalhes sobre os arquivos de inicialização do Bash.

@anchor{shell-development-option}
@item --development
@itemx -D
Faça com que @command{guix shell} inclua no ambiente as dependências do
pacote a seguir em vez do pacote em si. Isso pode ser combinado com outros
pacotes. Por exemplo, o comando abaixo inicia um shell interativo contendo
as dependências de tempo de compilação do GNU@tie{}Guile, além do Autoconf,
Automake e Libtool:

@example
guix shell -D guile autoconf automake libtool
@end example

@item --expression=@var{expr}
@itemx -e @var{expr}
Crie um ambiente para o pacote ou lista de pacotes que @var{expr} avalia.

Por exemplo, executando:

@example
guix shell -D -e '(@@ (gnu packages maths) petsc-openmpi)'
@end example

inicia um shell com o ambiente para esta variante específica do pacote
PETSc.

Rodando:

@example
guix shell -e '(@@ (gnu) %base-packages)'
@end example

inicia um shell com todos os pacotes do sistema base disponíveis.

Os comandos acima usam apenas a saída padrão dos pacotes fornecidos. Para
selecionar outras saídas, duas tuplas de elementos podem ser especificadas:

@example
guix shell -e '(list (@@ (gnu packages bash) bash) "include")'
@end example

@xref{package-development-manifest, @code{package->development-manifest}},
para obter informações sobre como escrever um manifesto para o ambiente de
desenvolvimento de um pacote.

@item --file=@var{arquivo}
@itemx -f @var{arquivo}
Crie um ambiente contendo o pacote ou lista de pacotes que o código dentro
de @var{arquivo} avalia.

Por exemplo, @var{arquivo} pode conter uma definição como esta
(@pxref{Definindo pacotes}):

@lisp
@verbatiminclude environment-gdb.scm
@end lisp

Com o arquivo acima, você pode entrar em um ambiente de desenvolvimento para
o GDB executando:

@example
guix shell -D -f gdb-devel.scm
@end example

@anchor{shell-manifest}
@item --manifest=@var{arquivo}
@itemx -m @var{arquivo}
Crie um ambiente para os pacotes contidos no objeto manifest retornado pelo
código Scheme em @var{arquivo}. Esta opção pode ser repetida várias vezes,
nesse caso os manifestos são concatenados.

Isso é semelhante à opção de mesmo nome em @command{guix package}
(@pxref{profile-manifest, @option{--manifest}}) e usa os mesmos arquivos de
manifesto.

@xref{Escrevendo manifestos}, para informações sobre como escrever um
manifesto. Veja @option{--export-manifest} abaixo sobre como obter um
primeiro manifesto.

@cindex manifesto, exportando
@anchor{shell-export-manifest}
@item --export-manifest
Grave na saída padrão um manifesto adequado para @option{--manifest}
correspondente às opções de linha de comando fornecidas.

Esta é uma maneira de ``converter'' argumentos de linha de comando em um
manifesto. Por exemplo, imagine que você está cansado de digitar linhas
longas e gostaria de obter um manifesto equivalente a esta linha de comando:

@example
guix shell -D guile git emacs emacs-geiser emacs-geiser-guile
@end example

Basta adicionar @option{--export-manifest} à linha de comando acima:

@example
guix shell --export-manifest \
  -D guile git emacs emacs-geiser emacs-geiser-guile
@end example

@noindent
... and you get a manifest along these lines:

@lisp
(concatenate-manifests
  (list (specifications->manifest
          (list "git"
                "emacs"
                "emacs-geiser"
                "emacs-geiser-guile"))
        (package->development-manifest
          (specification->package "guile"))))
@end lisp

Você pode armazená-lo em um arquivo, digamos @file{manifest.scm}, e de lá
passá-lo para @command{guix shell} ou praticamente qualquer comando
@command{guix}:

@example
guix shell -m manifest.scm
@end example

Voilà, você converteu uma longa linha de comando em um manifesto! Esse
processo de conversão honra opções de transformação de pacote
(@pxref{Opções de transformação de pacote}), então deve ser sem perdas.

@item --profile=@var{perfil}
@itemx -p @var{perfil}
Crie um ambiente contendo os pacotes instalados em @var{perfil}. Use
@command{guix package} (@pxref{Invocando guix package}) para criar e
gerenciar perfis.

@item --pure
Desconfigura variáveis de ambiente existentes ao construir o novo ambiente,
exceto aquelas especificadas com @option{--preserve} (veja abaixo). Isso tem
o efeito de criar um ambiente no qual os caminhos de pesquisa contêm apenas
entradas de pacote.

@item --preserve=@var{regexp}
@itemx -E @var{regexp}
Quando usado junto com @option{--pure}, preserva as variáveis de ambiente
que correspondem a @var{regexp}---em outras palavras, coloca-as em uma
``lista branca'' de variáveis de ambiente que devem ser preservadas. Esta
opção pode ser repetida várias vezes.

@example
guix shell --pure --preserve=^SLURM openmpi @dots{} \
  -- mpirun @dots{}
@end example

Este exemplo executa @command{mpirun} em um contexto onde as únicas
variáveis de ambiente definidas são @env{PATH}, variáveis de ambiente cujo
nome começa com @samp{SLURM}, bem como as variáveis ``preciosas'' usuais
(@env{HOME}, @env{USER}, etc.).

@item --search-paths
Exiba as definições de variáveis de ambiente que compõem o ambiente.

@item --system=@var{sistema}
@itemx -s @var{sistema}
Tente construir para @var{sistema}---por exemplo, @code{i686-linux}.

@item --container
@itemx -C
@cindex container
Execute @var{comando} dentro de um contêiner isolado. O diretório de
trabalho atual fora do contêiner é mapeado dentro do contêiner. Além disso,
a menos que substituído por @option{--user}, um diretório pessoal (home)
fictício é criado que corresponde ao diretório pessoal do usuário atual, e
@file{/etc/passwd} é configurado adequadamente.

O processo gerado é executado como o usuário atual fora do contêiner. Dentro
do contêiner, ele tem o mesmo UID e GID que o usuário atual, a menos que
@option{--user} seja passado (veja abaixo).

@item --network
@itemx -N
Para contêineres, compartilhe o namespace de rede com o sistema host. Os
contêineres criados sem esse sinalizador têm acesso somente ao dispositivo
de loopback.

@item --link-profile
@itemx -P
Para contêineres, vincule o perfil do ambiente a @file{~/.guix-profile}
dentro do contêiner e defina @code{GUIX_ENVIRONMENT} para isso. Isso é
equivalente a tornar @file{~/.guix-profile} uma ligação simbólica para o
perfil real dentro do contêiner. A vinculação falhará e abortará o ambiente
se o diretório já existir, o que certamente será o caso se @command{guix
shell} foi invocado no diretório pessoal do usuário.

Certos pacotes são configurados para procurar em @file{~/.guix-profile} por
arquivos de configuração e dados;@footnote{Por exemplo, o pacote
@code{fontconfig} inspeciona @file{~/.guix-profile/share/fonts} por fontes
adicionais.} @option{--link-profile} permite que esses programas se
comportem conforme o esperado no ambiente.

@item --user=@var{usuário}
@itemx -u @var{usuário}
Para contêineres, use o nome de usuário @var{usuário} no lugar do usuário
atual. A entrada @file{/etc/passwd} gerada dentro do contêiner conterá o
nome @var{usuário}, o diretório pessoal será @file{/home/@var{usuário}} e
nenhum dado GECOS do usuário será copiado. Além disso, o UID e o GID dentro
do contêiner são 1000. @var{usuário} não precisa existir no sistema.

Além disso, qualquer caminho compartilhado ou exposto (veja @option{--share}
e @option{--expose} respectivamente) cujo destino esteja dentro do pessoal
do usuário atual será remapeado em relação a @file{/home/USUÁRIO}; isso
inclui o mapeamento automático do diretório de trabalho atual.

@example
# will expose paths as /home/foo/wd, /home/foo/test, and /home/foo/target
cd $HOME/wd
guix shell --container --user=foo \
     --expose=$HOME/test \
     --expose=/tmp/target=$HOME/target
@end example

Embora isso limite o vazamento da identidade do usuário por meio de caminhos
iniciais e de cada um dos campos do usuário, esse é apenas um componente
útil de uma solução mais ampla de privacidade/anonimato — não uma solução em
si.

@item --no-cwd
Para contêineres, o comportamento padrão é compartilhar o diretório de
trabalho atual com o contêiner isolado e mudar imediatamente para esse
diretório dentro do contêiner. Se isso for indesejável, @option{--no-cwd}
fará com que o diretório de trabalho atual @emph{não} seja compartilhado
automaticamente e mudará para o diretório pessoal do usuário dentro do
contêiner. Veja também @option{--user}.

@item --writable-root
When using @option{--container}, this option makes the root file system
writable (it is read-only by default).

@item --expose=@var{fonte}[=@var{alvo}]
@itemx --share=@var{fonte}[=@var{alvo}]
Para contêineres, @option{--expose} (resp. @option{--share}) expõe o sistema
de arquivos @var{fonte} do sistema host como o sistema de arquivos somente
leitura (resp. gravável) @var{alvo} dentro do contêiner. Se @var{alvo} não
for especificado, @var{fonte} será usado como o ponto de montagem de destino
no contêiner.

O exemplo abaixo gera um Guile REPL em um contêiner no qual o diretório
pessoal do usuário é acessível somente para leitura por meio do diretório
@file{/exchange}:

@example
guix shell --container --expose=$HOME=/exchange guile -- guile
@end example

@cindex ligações simbólicas, guix shell
@item --symlink=@var{spec}
@itemx -S @var{spec}
Para contêineres, crie as ligações simbólicas especificadas por @var{spec},
conforme documentado em @ref{pack-symlink-option}.

@cindex padrão de hierarquia do sistema de arquivos (FHS)
@cindex FHS (padrão de hierarquia do sistema de arquivos)
@item --emulate-fhs
@itemx -F
Quando usado com @option{--container}, emule uma configuração do
@uref{https://refspecs.linuxfoundation.org/fhs.shtml, padrão de hierarquia
do sistema de arquivos (Filesystem Hierarchy Standard, FHS)} dentro do
contêiner, fornecendo @file{/bin}, @file{/lib} e outros diretórios e
arquivos especificados pelo FHS.

Como Guix desvia da especificação FHS, esta opção configura o contêiner para
imitar mais de perto o de outras distribuições GNU/Linux. Isto é útil para
reproduzir outros ambientes de desenvolvimento, testar e usar programas que
esperam que a especificação FHS seja seguida. Com esta opção, o contêiner
incluirá uma versão do glibc que lerá @file{/etc/ld.so.cache} dentro do
contêiner para o cache da biblioteca compartilhada (ao contrário do glibc no
uso regular do Guix) e configurará os diretórios FHS esperados: @file{/bin},
@file{/etc}, @file{/lib} e @file{/usr} do perfil do contêiner.

@cindex contêineres aninhados, para @command{guix shell}
@cindex aninhamento de contêineres, para @command{guix shell}
@item --nesting
@itemx -W
Quando usado com @option{--container}, forneça Guix @emph{dentro} do
contêiner e organize para que ele possa interagir com o daemon de construção
que roda fora do contêiner. Isso é útil se você quiser, dentro do seu
contêiner isolado, criar outros contêineres, como nesta sessão de exemplo:

@example
$ guix shell -CW coreutils
[env]$ guix shell -C guile -- guile -c '(display "olá!\n")'
olá!
[env]$ exit
@end example

A sessão acima inicia um contêiner com programas @code{coreutils}
disponíveis em @env{PATH}. A partir daí, geramos @command{guix shell} para
criar um contêiner @emph{aninhado} que fornece nada além de Guile.

Outro exemplo é avaliar um arquivo @file{guix.scm} que não é confiável,
conforme mostrado aqui:

@example
guix shell -CW -- guix build -f guix.scm
@end example

O comando @command{guix build} executado acima só pode acessar o diretório
atual.

Nos bastidores, a opção @option{-W} faz várias coisas:

@itemize
@item
mapeia o socket do daemon (por padrão,
@file{/var/guix/daemon-socket/socket}) dentro do contêiner;
@item
mapeia todo o armazém (por padrão @file{/gnu/store}) dentro do contêiner de
forma que os itens do armazém disponibilizados por invocações aninhadas
@command{guix} sejam visíveis;
@item
adiciona o comando @command{guix} usado atualmente ao perfil no contêiner,
de modo que @command{guix describe} retorne o mesmo estado dentro e fora do
contêiner;
@item
compartilha o cache (por padrão @file{~/.cache/guix}) com o host, para
acelerar operações como @command{guix time-machine} e @command{guix shell}.
@end itemize

@item --rebuild-cache
@cindex cache, de perfis
@cindex caching, em @command{guix shell}
Na maioria dos casos, @command{guix shell} armazena em cache o ambiente para
que os usos subsequentes sejam instantâneos. As entradas de cache menos
usadas recentemente são removidas periodicamente. O cache também é
invalidado, ao usar @option{--file} ou @option{--manifest}, sempre que o
arquivo correspondente for modificado.

O @option{--rebuild-cache} força o ambiente em cache a ser atualizado. Isso
é útil ao usar @option{--file} ou @option{--manifest} e o arquivo
@command{guix.scm} ou @command{manifest.scm} tem dependências externas, ou
se seu comportamento depende, digamos, de variáveis de ambiente.

@item --root=@var{arquivo}
@itemx -r @var{arquivo}
@cindex ambiente persistente
@cindex coletor de lixo raiz, para ambientes
Crie @var{arquivo} como uma ligação simbólica para o perfil deste ambiente e
registre-a como raiz do coletor de lixo.

Isso é útil se você deseja proteger seu ambiente da coleta de lixo, para
torná-lo ``persistente''.

Quando esta opção é omitida, @command{guix shell} armazena em cache os
perfis para que os usos subsequentes do mesmo ambiente sejam instantâneos —
isso é comparável ao uso de @option{--root}, exceto que @command{guix shell}
cuida da remoção periódica das raízes do coletor de lixo menos usadas
recentemente.

Em alguns casos, @command{guix shell} não armazena perfis em cache---por
exemplo, se opções de transformação como @option{--with-latest} forem
usadas. Nesses casos, o ambiente é protegido da coleta de lixo somente
durante a sessão @command{guix shell}. Isso significa que na próxima vez que
você recriar o mesmo ambiente, poderá ter que reconstruir ou baixar
novamente os pacotes.

@xref{Invocando guix pack}, para mais sobre as raízes do coletor de lixo.
@end table

@command{guix shell} também suporta todas as opções de compilação comuns que
@command{guix build} suporta (@pxref{Opções de compilação comuns}), bem como opções
de transformação de pacotes (@pxref{Opções de transformação de pacote}).

@node Invocando guix environment
@section Invocando @command{guix environment}

@cindex @command{guix environment}

O objetivo do @command{guix environment} é auxiliar na criação de ambientes
de desenvolvimento.

@quotation Aviso de descontinuação
O comando @command{guix environment} foi descontinuado em favor do
@command{guix shell}, que executa funções semelhantes, mas é mais
conveniente de usar. @xref{Invocando guix shell}.

Sendo obsoleto, o @command{guix environment} está programado para remoção
futura, mas o projeto Guix está comprometido em mantê-lo até 1º de maio de
2023. Entre em contato conosco pelo e-mail @email{guix-devel@@gnu.org} se
quiser discutir o assunto.
@end quotation

A sintaxe geral é:

@example
guix environment @var{opções} @var{pacote}@dots{}
@end example

O exemplo a seguir gera uma nova configuração de shell para o
desenvolvimento do GNU@tie{}Guile:

@example
guix environment guile
@end example

Se as dependências necessárias ainda não foram construídas, @command{guix
environment} as constrói automaticamente. O ambiente do novo shell é uma
versão aumentada do ambiente em que @command{guix environment} foi
executado. Ele contém os caminhos de pesquisa necessários para construir o
pacote fornecido adicionado às variáveis de ambiente existentes. Para criar
um ambiente ``puro'', no qual as variáveis de ambiente originais foram
desconfiguradas, use a opção @option{--pure}@footnote{Às vezes, os usuários
aumentam incorretamente as variáveis de ambiente, como @env{PATH} em seu
arquivo @file{~/.bashrc}. Como consequência, quando @command{guix
environment} o inicia, o Bash pode ler @file{~/.bashrc}, introduzindo assim
``impurezas'' nessas variáveis de ambiente. É um erro definir essas
variáveis de ambiente em @file{.bashrc}; em vez disso, elas devem ser
definidas em @file{.bash_profile}, que é originado apenas por shells de
login. @xref{Bash Startup Files,,, bash, Manual de referência do GNU Bash},
para detalhes sobre os arquivos de inicialização do Bash.}.

Sair de um ambiente Guix é o mesmo que sair do shell, e colocará o usuário
de volta no ambiente antigo antes de @command{guix environment} ser
invocado. A próxima coleta de lixo (@pxref{Invocando guix gc}) limpará os
pacotes que foram instalados de dentro do ambiente e não são mais usados
fora dele.

@vindex GUIX_ENVIRONMENT
@command{guix environment} define a variável @env{GUIX_ENVIRONMENT} no shell
que ele gera; seu valor é o nome do arquivo do perfil deste ambiente. Isso
permite que os usuários, digamos, definam um prompt específico para
ambientes de desenvolvimento em seu @file{.bashrc} (@pxref{Bash Startup
Files,,, bash, Manual de referência do GNU Bash}):

@example
if [ -n "$GUIX_ENVIRONMENT" ]
then
    export PS1="\u@@\h \w [dev]\$ "
fi
@end example

@noindent
...@: ou para navegar pelo perfil:

@example
$ ls "$GUIX_ENVIRONMENT/bin"
@end example

Além disso, mais de um pacote pode ser especificado, em cujo caso a união
das entradas para os pacotes fornecidos é usada. Por exemplo, o comando
abaixo gera um shell onde todas as dependências do Guile e do Emacs estão
disponíveis:

@example
guix environment guile emacs
@end example

Às vezes, uma sessão de shell interativa não é desejada. Um comando
arbitrário pode ser invocado colocando o token @code{--} para separar o
comando do resto dos argumentos:

@example
guix environment guile -- make -j4
@end example

Em outras situações, é mais conveniente especificar a lista de pacotes
necessários no ambiente. Por exemplo, o comando a seguir executa
@command{python} de um ambiente contendo Python@tie{}3 e NumPy:

@example
guix environment --ad-hoc python-numpy python -- python3
@end example

Além disso, pode-se querer as dependências de um pacote e também alguns
pacotes adicionais que não são dependências de tempo de construção ou tempo
de execução, mas são úteis ao desenvolver, no entanto. Por causa disso, o
sinalizador @option{--ad-hoc} é posicional. Pacotes que aparecem antes de
@option{--ad-hoc} são interpretados como pacotes cujas dependências serão
adicionadas ao ambiente. Pacotes que aparecem depois são interpretados como
pacotes que serão adicionados ao ambiente diretamente. Por exemplo, o
comando a seguir cria um ambiente de desenvolvimento Guix que inclui
adicionalmente Git e strace:

@example
guix environment --pure guix --ad-hoc git strace
@end example

@cindex container
Às vezes, é desejável isolar o ambiente o máximo possível, para máxima
pureza e reprodutibilidade. Em particular, ao usar Guix em uma distribuição
host que não seja Guix System, é desejável impedir o acesso a
@file{/usr/bin} e outros recursos de todo o sistema do ambiente de
desenvolvimento. Por exemplo, o comando a seguir gera um Guile REPL em um
``contêiner'' onde apenas o armazém e o diretório de trabalho atual são
montados:

@example
guix environment --ad-hoc --container guile -- guile
@end example

@quotation Nota
A opção @option{--container} requer Linux-libre 3.19 ou mais recente.
@end quotation

@cindex certificados
Outro caso de uso típico para contêineres é executar aplicativos sensíveis à
segurança, como um navegador da web. Para executar o Eolie, precisamos expor
e compartilhar alguns arquivos e diretórios; incluímos @code{nss-certs} e
expomos @file{/etc/ssl/certs/} para autenticação HTTPS; finalmente,
preservamos a variável de ambiente @env{DISPLAY}, pois os aplicativos
gráficos em contêiner não serão exibidos sem ela.

@example
guix environment --preserve='^DISPLAY$' --container --network \
  --expose=/etc/machine-id \
  --expose=/etc/ssl/certs/ \
  --share=$HOME/.local/share/eolie/=$HOME/.local/share/eolie/ \
  --ad-hoc eolie nss-certs dbus --  eolie
@end example

As opções disponíveis estão resumidas abaixo.

@table @code
@item --check
Configure o ambiente e verifique se o shell sobrecarregaria as variáveis de
ambiente. @xref{Invocando guix shell, @option{--check}}, para mais
informações.

@item --root=@var{arquivo}
@itemx -r @var{arquivo}
@cindex ambiente persistente
@cindex coletor de lixo raiz, para ambientes
Crie @var{arquivo} como uma ligação simbólica para o perfil deste ambiente e
registre-a como raiz do coletor de lixo.

Isso é útil se você deseja proteger seu ambiente da coleta de lixo, para
torná-lo ``persistente''.

Quando esta opção pe omitida, o ambiente é protegido da coleta de lixo
apenas pela duração da sessão do @command{guix environment}.  Isso significa
que na próxima vez que você recriar o mesmo ambiente, você tpoderia ter que
reconstruir ou refazer o download dos pacotes.  @xref{Invocando guix gc},
para mais sobre GC roots.

@item --expression=@var{expr}
@itemx -e @var{expr}
Crie um ambiente para o pacote ou lista de pacotes que @var{expr} avalia.

Por exemplo, executando:

@example
guix environment -e '(@@ (gnu packages maths) petsc-openmpi)'
@end example

inicia um shell com o ambiente para esta variante específica do pacote
PETSc.

Rodando:

@example
guix environment --ad-hoc -e '(@@ (gnu) %base-packages)'
@end example

inicia um shell com todos os pacotes do sistema base disponíveis.

Os comandos acima usam apenas a saída padrão dos pacotes fornecidos. Para
selecionar outras saídas, duas tuplas de elementos podem ser especificadas:

@example
guix environment --ad-hoc -e '(list (@@ (gnu packages bash) bash) "include")'
@end example

@item --load=@var{arquivo}
@itemx -l @var{arquivo}
Crie um ambiente para o pacote ou lista de pacotes que o código dentro de
@var{arquivo} avalia.

Por exemplo, @var{arquivo} pode conter uma definição como esta
(@pxref{Definindo pacotes}):

@lisp
@verbatiminclude environment-gdb.scm
@end lisp

@item --manifest=@var{arquivo}
@itemx -m @var{arquivo}
Crie um ambiente para os pacotes contidos no objeto manifest retornado pelo
código Scheme em @var{arquivo}. Esta opção pode ser repetida várias vezes,
nesse caso os manifestos são concatenados.

Isso é semelhante à opção de mesmo nome em @command{guix package}
(@pxref{profile-manifest, @option{--manifest}}) e usa os mesmos arquivos de
manifesto.

@xref{shell-export-manifest, @command{guix shell --export-manifest}}, para
obter informações sobre como ``converter'' opções de linha de comando em um
manifesto.

@item --ad-hoc
Inclui todos os pacotes especificados no ambiente resultante, como se um
pacote @i{ad hoc} fosse definido com eles como entradas. Esta opção é útil
para criar rapidamente um ambiente sem ter que escrever uma expressão de
pacote para conter as entradas desejadas.

Por exemplo, o comando:

@example
guix environment --ad-hoc guile guile-sdl -- guile
@end example

executa @command{guile} em um ambiente onde Guile e Guile-SDL estão
disponíveis.

Observe que este exemplo solicita implicitamente a saída padrão de
@code{guile} e @code{guile-sdl}, mas é possível solicitar uma saída
específica — por exemplo, @code{glib:bin} solicita a saída @code{bin} de
@code{glib} (@pxref{Pacotes com múltiplas saídas}).

Esta opção pode ser composta com o comportamento padrão de @command{guix
environment}. Pacotes que aparecem antes de @option{--ad-hoc} são
interpretados como pacotes cujas dependências serão adicionadas ao ambiente,
o comportamento padrão. Pacotes que aparecem depois são interpretados como
pacotes que serão adicionados ao ambiente diretamente.

@item --profile=@var{perfil}
@itemx -p @var{perfil}
Crie um ambiente contendo os pacotes instalados em @var{perfil}. Use
@command{guix package} (@pxref{Invocando guix package}) para criar e
gerenciar perfis.

@item --pure
Desconfigura variáveis de ambiente existentes ao construir o novo ambiente,
exceto aquelas especificadas com @option{--preserve} (veja abaixo). Isso tem
o efeito de criar um ambiente no qual os caminhos de pesquisa contêm apenas
entradas de pacote.

@item --preserve=@var{regexp}
@itemx -E @var{regexp}
Quando usado junto com @option{--pure}, preserva as variáveis de ambiente
que correspondem a @var{regexp}---em outras palavras, coloca-as em uma
``lista branca'' de variáveis de ambiente que devem ser preservadas. Esta
opção pode ser repetida várias vezes.

@example
guix environment --pure --preserve=^SLURM --ad-hoc openmpi @dots{} \
  -- mpirun @dots{}
@end example

Este exemplo executa @command{mpirun} em um contexto onde as únicas
variáveis de ambiente definidas são @env{PATH}, variáveis de ambiente cujo
nome começa com @samp{SLURM}, bem como as variáveis ``preciosas'' usuais
(@env{HOME}, @env{USER}, etc.).

@item --search-paths
Exiba as definições de variáveis de ambiente que compõem o ambiente.

@item --system=@var{sistema}
@itemx -s @var{sistema}
Tente construir para @var{sistema}---por exemplo, @code{i686-linux}.

@item --container
@itemx -C
@cindex container
Execute @var{comando} dentro de um contêiner isolado. O diretório de
trabalho atual fora do contêiner é mapeado dentro do contêiner. Além disso,
a menos que substituído por @option{--user}, um diretório pessoal (home)
fictício é criado que corresponde ao diretório pessoal do usuário atual, e
@file{/etc/passwd} é configurado adequadamente.

O processo gerado é executado como o usuário atual fora do contêiner. Dentro
do contêiner, ele tem o mesmo UID e GID que o usuário atual, a menos que
@option{--user} seja passado (veja abaixo).

@item --network
@itemx -N
Para contêineres, compartilhe o namespace de rede com o sistema host. Os
contêineres criados sem esse sinalizador têm acesso somente ao dispositivo
de loopback.

@item --link-profile
@itemx -P
Para contêineres, vincule o perfil do ambiente a @file{~/.guix-profile}
dentro do contêiner e defina @code{GUIX_ENVIRONMENT} para isso. Isso é
equivalente a tornar @file{~/.guix-profile} uma ligação simbólica para o
perfil real dentro do contêiner. A vinculação falhará e abortará o ambiente
se o diretório já existir, o que certamente será o caso se @command{guix
environment} foi invocado no diretório pessoal do usuário.

Certos pacotes são configurados para procurar em @file{~/.guix-profile} por
arquivos de configuração e dados;@footnote{Por exemplo, o pacote
@code{fontconfig} inspeciona @file{~/.guix-profile/share/fonts} por fontes
adicionais.} @option{--link-profile} permite que esses programas se
comportem conforme o esperado no ambiente.

@item --user=@var{usuário}
@itemx -u @var{usuário}
Para contêineres, use o nome de usuário @var{usuário} no lugar do usuário
atual. A entrada @file{/etc/passwd} gerada dentro do contêiner conterá o
nome @var{usuário}, o diretório pessoal será @file{/home/@var{usuário}} e
nenhum dado GECOS do usuário será copiado. Além disso, o UID e o GID dentro
do contêiner são 1000. @var{usuário} não precisa existir no sistema.

Além disso, qualquer caminho compartilhado ou exposto (veja @option{--share}
e @option{--expose} respectivamente) cujo destino esteja dentro do pessoal
do usuário atual será remapeado em relação a @file{/home/USUÁRIO}; isso
inclui o mapeamento automático do diretório de trabalho atual.

@example
# will expose paths as /home/foo/wd, /home/foo/test, and /home/foo/target
cd $HOME/wd
guix environment --container --user=foo \
     --expose=$HOME/test \
     --expose=/tmp/target=$HOME/target
@end example

Embora isso limite o vazamento da identidade do usuário por meio de caminhos
iniciais e de cada um dos campos do usuário, esse é apenas um componente
útil de uma solução mais ampla de privacidade/anonimato — não uma solução em
si.

@item --no-cwd
Para contêineres, o comportamento padrão é compartilhar o diretório de
trabalho atual com o contêiner isolado e mudar imediatamente para esse
diretório dentro do contêiner. Se isso for indesejável, @option{--no-cwd}
fará com que o diretório de trabalho atual @emph{não} seja compartilhado
automaticamente e mudará para o diretório pessoal do usuário dentro do
contêiner. Veja também @option{--user}.

@item --expose=@var{fonte}[=@var{alvo}]
@itemx --share=@var{fonte}[=@var{alvo}]
Para contêineres, @option{--expose} (resp. @option{--share}) expõe o sistema
de arquivos @var{fonte} do sistema host como o sistema de arquivos somente
leitura (resp. gravável) @var{alvo} dentro do contêiner. Se @var{alvo} não
for especificado, @var{fonte} será usado como o ponto de montagem de destino
no contêiner.

O exemplo abaixo gera um Guile REPL em um contêiner no qual o diretório
pessoal do usuário é acessível somente para leitura por meio do diretório
@file{/exchange}:

@example
guix environment --container --expose=$HOME=/exchange --ad-hoc guile -- guile
@end example

@item --emulate-fhs
@item -F
Para contêineres, emule uma configuração Filesystem Hierarchy Standard (FHS)
dentro do contêiner, veja
@uref{https://refspecs.linuxfoundation.org/fhs.shtml, a especificação
oficial}. Como o Guix se desvia da especificação FHS, esta opção configura o
contêiner para imitar mais de perto o de outras distribuições
GNU/Linux. Isto é útil para reproduzir outros ambientes de desenvolvimento,
testar e usar programas que esperam que a especificação FHS seja
seguida. Com esta opção, o contêiner incluirá uma versão de @code{glibc} que
lerá @code{/etc/ld.so.cache} dentro do contêiner para o cache da biblioteca
compartilhada (ao contrário de @code{glibc} no uso regular do Guix) e
configurará os diretórios FHS esperados: @code{/bin}, @code{/etc},
@code{/lib} e @code{/usr} do perfil do contêiner.

@end table

@command{guix environment} também oferece suporte a todas as opções de
compilação comuns que @command{guix build} oferece suporte (@pxref{Opções de compilação comuns}), bem como opções de transformação de pacotes (@pxref{Opções de transformação de pacote}).

@node Invocando guix pack
@section Invocando @command{guix pack}

@cindex @command{guix pack}

Ocasionalmente você quer passar software para pessoas que não têm (ainda!) a
sorte de usar Guix. Você diria para elas executarem @command{guix package -i
@var{algo}}, mas isso não é possível neste caso. É aqui que @command{guix
pack} entra.

@quotation Nota
Se você estiver procurando maneiras de trocar binários entre máquinas que já
executam Guix, @pxref{Invocando guix copy}, @ref{Invocando guix publish} e
@ref{Invocando guix archive}.
@end quotation

@cindex pack
@cindex embalagem
@cindex embalagem de aplicativos
@cindex embalagem de software
O comando @command{guix pack} cria uma @dfn{embalagem de software}
encapsulado: ele cria um tarball ou algum outro arquivo contendo os binários
do software em que você está interessado e todas as suas dependências. O
arquivo resultante pode ser usado em qualquer máquina que não tenha Guix, e
as pessoas podem executar exatamente os mesmos binários que você tem com
Guix. A embalagem em si é criada de forma reproduzível em bits, para que
qualquer um possa verificar se ela realmente contém os resultados da
compilação que você pretende enviar.

Por exemplo, para criar uma embalagem contenda Guile, Emacs, Geiser e todas
as suas dependências, você pode executar:

@example
$ guix pack guile emacs emacs-geiser
@dots{}
/gnu/store/@dots{}-pack.tar.gz
@end example

O resultado aqui é um tarball contendo um diretório @file{/gnu/store} com
todos os pacotes relevantes. O tarball resultante contém um @dfn{perfil} com
os três pacotes de interesse; o perfil é o mesmo que seria criado por
@command{guix package -i}. É esse mecanismo que é usado para criar o próprio
tarball binário autônomo do Guix (@pxref{Instalação de binários}).

Usuários desta embalagem teriam que executar
@file{/gnu/store/@dots{}-profile/bin/guile} para executar o Guile, o que
você pode achar inconveniente. Para contornar isso, você pode criar,
digamos, uma ligação simbólica @file{/opt/gnu/bin} para o perfil:

@example
guix pack -S /opt/gnu/bin=bin guile emacs emacs-geiser
@end example

@noindent
Dessa forma, os usuários podem digitar @file{/opt/gnu/bin/guile} e
aproveitar.

@cindex binários relocáveis, com @command{guix pack}
E se o destinatário do sua embalagem não tiver privilégios de root na
máquina dele e, portanto, não puder descompactá-lo no sistema de arquivos
raiz? Nesse caso, você vai querer usar a opção @option{--relocatable} (veja
abaixo). Essa opção produz @dfn{binários relocáveis}, o que significa que
eles podem ser colocados em qualquer lugar na hierarquia do sistema de
arquivos: no exemplo acima, os usuários podem descompactar seu tarball no
diretório pessoal deles e executar diretamente @file{./opt/gnu/bin/guile}.

@cindex Docker, construa uma imagem com guix pack
Como alternativa, você pode produzir uma embalagem no formato de imagem do
Docker usando o seguinte comando:

@example
guix pack -f docker -S /bin=bin guile guile-readline
@end example

@noindent
O resultado é um tarball que pode ser passado para o comando @command{docker
load}, seguido por @code{docker run}:

@example
docker load < @var{arquivo}
docker run -ti guile-guile-readline /bin/guile
@end example

@noindent
onde @var{arquivo} é a imagem retornada por @command{guix pack}, e
@code{guile-guile-readline} é sua ``image tag''. Veja
@uref{https://docs.docker.com/engine/reference/commandline/load/,
documentação do Docker} para mais informações.

@cindex Singularity, construa uma imagem com guix pack
@cindex SquashFS, construa uma imagem com guix pack
Outra opção é produzir uma imagem SquashFS com o seguinte comando:

@example
guix pack -f squashfs bash guile emacs emacs-geiser
@end example

@noindent
O resultado é uma imagem do sistema de arquivos SquashFS que pode ser
montada ou usada diretamente como uma imagem de contêiner do sistema de
arquivos com o @uref{https://www.sylabs.io/docs/, ambiente de execução do
contêiner Singularity}, usando comandos como @command{singularity shell} ou
@command{singularity exec}.

@cindex AppImage, create an AppImage file with @command{guix pack}
Outro formato internamente baseado em SquashFS é o
@uref{https://appimage.org/, AppImage}. Um arquivo de AppImage pode ser
criado e executado sem qualquer provilégio especial:

@example
file=$(guix pack -f appimage --entry-point=bin/guile guile)
$file --help
@end example

Várias opções de linha de comando permitem que você personalize sua
embalagem:

@table @code
@item --format=@var{formato}
@itemx -f @var{formato}
Produza uma embalagem no @var{formato} fornecido.

Os formatos disponíveis são:

@table @code
@item tarball
Este é o formato padrão. Ele produz um tarball contendo todos os binários e
ligações simbólicas especificados.

@item docker
Isso produz um tarball que segue o
@uref{https://github.com/docker/docker/blob/master/image/spec/v1.2.md,
Docker Image Specification}. Por padrão, o ``nome do repositório'' como
aparece na saída do comando @command{docker images} é computado a partir de
nomes de pacotes passados na linha de comando ou no arquivo manifesto. Como
alternativa, o ``nome do repositório'' também pode ser configurado por meio
da opção @option{--image-tag}. Consulte @option{--help-docker-format} para
obter mais informações sobre essas opções avançadas.

@item squashfs
Isso produz uma imagem SquashFS contendo todos os binários e ligações
simbólicas especificados, bem como pontos de montagem vazios para sistemas
de arquivos virtuais como procfs.

@quotation Nota
Singularity @emph{requer} que você forneça @file{/bin/sh} na imagem. Por
esse motivo, @command{guix pack -f squashfs} sempre implica @code{-S
/bin=bin}. Portanto, sua invocação @command{guix pack} deve sempre começar
com algo como:

@example
guix pack -f squashfs bash @dots{}
@end example

Se você esquecer o pacote @code{bash} (ou similar), @command{singularity
run} e @command{singularity exec} falharão com uma mensagem inútil ``nenhum
arquivo ou diretório''.
@end quotation

@item deb
@cindex Debian, construa um pacote .deb com guix pack
Isso produz um arquivo Debian (um pacote com a extensão de arquivo
@samp{.deb}) contendo todos os binários e ligações simbólicas especificados,
que podem ser instalados em cima de qualquer distribuição GNU(/Linux)
baseada em dpkg. Opções avançadas podem ser reveladas por meio da opção
@option{--help-deb-format}. Elas permitem incorporar arquivos de controle
para um controle mais refinado, como ativar gatilhos específicos ou fornecer
um script de configuração do mantenedor para executar código de configuração
arbitrário na instalação.

@example
guix pack -f deb -C xz -S /usr/bin/hello=bin/hello hello
@end example

@quotation Nota
Como os arquivos produzidos com @command{guix pack} contêm uma coleção de
itens de armazém e como cada pacote @command{dpkg} não deve ter arquivos
conflitantes, na prática isso significa que você provavelmente não
conseguirá instalar mais de um desses arquivos em um dado sistema. Você
pode, no entanto, empacotar quantos pacotes Guix quiser em um desses
arquivos.
@end quotation

@quotation Aviso
@command{dpkg} assumirá a propriedade de quaisquer arquivos contidos no
pacote que ele @emph{não} saiba. Não é sensato instalar arquivos @samp{.deb}
produzidos pelo Guix em um sistema onde @file{/gnu/store} é compartilhado
por outro software, como uma instalação do Guix ou outras embalagens não
deb.
@end quotation

@item rpm
@cindex RPM, construa um arquivo RPM com guix pack
Isso produz um arquivo RPM (um pacote com a extensão de arquivo @samp{.rpm})
contendo todos os binários e ligações simbólicas especificados, que podem
ser instalados em cima de qualquer distribuição GNU/Linux baseada em RPM. O
formato RPM incorpora somas de verificação para cada arquivo que ele contém,
que o comando @command{rpm} usa para validar a integridade do arquivo.

Opções avançadas relacionadas a RPM são reveladas por meio da opção
@option{--help-rpm-format}. Essas opções permitem incorporar scripts de
mantenedor que podem ser executados antes ou depois da instalação do arquivo
RPM, por exemplo.

O formato RPM suporta pacotes relocáveis por meio da opção @option{--prefix}
do comando @command{rpm}, o que pode ser útil para instalar um pacote RPM em
um prefixo específico.

@example
guix pack -f rpm -R -C xz -S /usr/bin/hello=bin/hello hello
@end example

@example
sudo rpm --install --prefix=/opt /gnu/store/...-hello.rpm
@end example

@quotation Nota
Ao contrário dos pacotes Debian, arquivos conflitantes, mas @emph{idênticos}
em pacotes RPM podem ser instalados simultaneamente, o que significa que
vários pacotes RPM produzidos pelo @command{guix pack} geralmente podem ser
instalados lado a lado sem nenhum problema.
@end quotation

@quotation Aviso
@command{rpm} assume a propriedade de quaisquer arquivos contidos no pacote,
o que significa que ele removerá @file{/gnu/store} ao desinstalar um pacote
RPM gerado pelo Guix, a menos que o pacote RPM tenha sido instalado com a
opção @option{--prefix} do comando @command{rpm}. Não é sensato instalar
pacotes @samp{.rpm} produzidos pelo Guix em um sistema onde
@file{/gnu/store} é compartilhado por outro software, como uma instalação do
Guix ou outras embalagens não rpm.
@end quotation

@item appimage
@cindex AppImage, create an AppImage file with @command{guix pack}
Isto produz um @uref{https://appimage.org/, arquivo AppImage} com a extensão
@samp{.AppImage}.  Um AppImage é um volume SquashFS prefixado com uma
execução que monta o sistema de arquivo SquashFS e executa o binário criado
com o @option{--entry-point}.  Isso resulta num arquivo auto-contido que
agrupa o software e todos os requisitos num único arquivo.  Quando o mesmo é
executado, ele roda o software empacotado.

@example
guix pack -f appimage --entry-point=bin/vlc vlc
@end example

A execução usada pelos AppImages invoca o comando @command{fusermount3} para
montar a imagem rapidamente.  Se o comando está indiponível, o AppImage
falha em executar, mas ele ainda pode ser iniciado com a opção
@option{--appimage-extract-and-run}.

@quotation Aviso
Ao construir um AppImage, sempre @emph{passe} a opção @option{--relocatable}
(ou @option{-R}, ou a @option{-RR}) para ter certeza que a imagem pode ser
usada em sistemas onde o Guix não está instalado.  Um aviso é impresso
quando esta opção não é usada.
@end quotation

@example
guix pack -f appimage --entry-point=bin/hello --relocatable hello
@end example

@quotation Nota
The resulting AppImage does not conform to the complete standard as it
currently does not contain a @file{.DirIcon} file.  This does not impact
functionality of the AppImage itself, but possibly that of software used to
manage AppImages.
@end quotation

@quotation Nota
As the generated AppImage packages the complete dependency graph, it will be
larger than comparable AppImage files found online, which depend on host
system libraries.
@end quotation

@end table

@cindex binários realocáveis
@item --relocatable
@itemx -R
Produza @dfn{binários relocáveis}---ou seja, binários que podem ser
colocados em qualquer lugar na hierarquia do sistema de arquivos e
executados a partir daí.

Quando essa opção é passada uma vez, os binários resultantes requerem
suporte para @dfn{user namespaces} no kernel Linux; quando passada
@emph{duas vezes}@footnote{Aqui vai um truque para memorizá-la: @code{-RR},
que adiciona suporte a PRoot, pode ser pensado como a abreviação de ``Really
Relocatable''. Legal, não é?}, binários relocáveis recorrem a outras
técnicas se os namespaces de usuário não estiverem disponíveis, e
essencialmente funcionam em qualquer lugar---veja abaixo as implicações.

Por exemplo, se você criar uma embalagem contendo Bash com:

@example
guix pack -RR -S /mybin=bin bash
@end example

@noindent
...@: você pode copiar essa embalagem para uma máquina que não tenha Guix e,
a partir do seu diretório pessoal, como um usuário normal, executar:

@example
tar xf pack.tar.gz
./mybin/sh
@end example

@noindent
Nesse shell, se você digitar @code{ls /gnu/store}, você notará que
@file{/gnu/store} aparece e contém todas as dependências de @code{bash},
mesmo que a máquina realmente não tenha @file{/gnu/store} completamente!
Essa é provavelmente a maneira mais simples de implementar software
construído pelo Guix em uma máquina não Guix.

@quotation Nota
Por padrão, binários relocáveis dependem do recurso @dfn{user namespace} do
kernel Linux, que permite que usuários sem privilégios montem ou alterem a
raiz (chroot). Versões antigas do Linux não o suportavam, e algumas
distribuições GNU/Linux o desativam.

Para produzir binários relocáveis que funcionam mesmo na ausência de
namespaces de usuário, passe @option{--relocatable} ou @option{-R}
@emph{duas vezes}. Nesse caso, os binários tentarão o suporte a namespaces
de usuário e retornarão a outro @dfn{mecanismo de execução} se os namespaces
de usuário não forem suportados. Os seguintes mecanismos de execução são
suportados:

@table @code
@item default
Experimente usar namespaces de usuário e retorne ao PRoot se eles não forem
suportados (veja abaixo).

@item performance
Experimente usar namespaces de usuário e retorne ao Fakechroot se eles não
forem suportados (veja abaixo).

@item userns
Execute o programa por meio de namespaces de usuário e aborte se eles não
forem suportados.

@item proot
Execute através do PRoot. O programa @uref{https://proot-me.github.io/,
PRoot} fornece o suporte necessário para virtualização do sistema de
arquivos. Ele consegue isso usando a chamada de sistema @code{ptrace} no
programa em execução. Essa abordagem tem a vantagem de funcionar sem exigir
suporte especial do kernel, mas incorre em sobrecarga de tempo de execução
toda vez que uma chamada de sistema é feita.

@item fakechroot
Execute através do Fakechroot. @uref{https://github.com/dex4er/fakechroot/,
Fakechroot} virtualiza acessos ao sistema de arquivos interceptando chamadas
para funções da biblioteca C, como @code{open}, @code{stat}, @code{exec} e
assim por diante. Ao contrário do PRoot, ele incorre em muito pouca
sobrecarga. No entanto, nem sempre funciona: por exemplo, alguns acessos ao
sistema de arquivos feitos de dentro da biblioteca C não são interceptados,
e acessos ao sistema de arquivos feitos @i{via} syscalls diretas também não
são interceptados, levando a um comportamento errático.
@end table

@vindex GUIX_EXECUTION_ENGINE
Ao executar um programa encapsulado, você pode solicitar explicitamente um
dos mecanismos de execução listados acima, definindo a variável de ambiente
@env{GUIX_EXECUTION_ENGINE} adequadamente.
@end quotation

@cindex ponto de entrada para imagens Docker e Singularity
@item --entry-point=@var{comando}
Use @var{comando} como o @dfn{ponto de entrada} da embalagem resultante, se
o formato da embalagem for compatível — atualmente, @code{docker},
@code{appimage} e @code{squashfs} (Singularity) o são. @var{comando} deve
ser relativo ao perfil contido na embalagem.

O ponto de entrada especifica o comando que ferramentas como @code{docker
run} ou @code{singularity run} iniciam automaticamente por padrão. Por
exemplo, você pode fazer:

@example
guix pack -f docker --entry-point=bin/guile guile
@end example

A embalagem resultante pode ser facilmente carregado e @code{docker run} sem
argumentos extras irá gerar @code{bin/guile}:

@example
docker load -i pack.tar.gz
docker run @var{image-id}
@end example

@cindex argumentos de ponto de entrada, para imagens docker
@item --entry-point-argument=@var{comando}
@itemx -A @var{comando}
Use @var{comando} como um argumento para @dfn{o ponto de entrada} da
embalagem resultante. Esta opção é válida somente em conjunto com
@code{--entry-point} e pode aparecer várias vezes na linha de comando.

@example
guix pack -f docker --entry-point=bin/guile --entry-point-argument="--help" guile
@end example

@cindex argumento de camadas máximas, para imagens docker
@item --max-layers=@code{n}
Especifica o número máximo de camadas de imagem do Docker permitidas ao
criar uma imagem.

@example
guix pack -f docker --max-layers=100 guile
@end example

Esta opção permite que você limite o número de camadas em uma imagem
Docker. As imagens Docker são compostas de várias camadas, e cada camada
adiciona ao tamanho geral e à complexidade da imagem. Ao definir um número
máximo de camadas, você pode controlar os seguintes efeitos:

@itemize
@item Uso do disco:
Aumentar o número de camadas pode ajudar a otimizar o espaço em disco
necessário para armazenar várias imagens criadas com um grafo de pacote
semelhante.

@item Puxar:
Ao transferir imagens entre diferentes nós ou sistemas, ter mais camadas
pode reduzir o tempo necessário para puxar a imagem.
@end itemize

@item --expression=@var{expr}
@itemx -e @var{expr}
Considere o pacote que @var{expr} avalia.

Isso tem o mesmo propósito que a opção de mesmo nome em @command{guix build}
(@pxref{Opções de compilação adicional, @option{--expression} em @command{guix
build}}).

@item --file=@var{arquivo}
Build a pack containing the package or other object the code within
@var{file} evaluates to.

This has the same purpose as the same-named option in @command{guix build}
(@pxref{Opções de compilação adicional, @option{--file} in @command{guix build}}),
but it has no shorthand, because @option{-f} already means
@option{--format}.

@anchor{pack-manifest}
@item --manifest=@var{arquivo}
@itemx -m @var{arquivo}
Use os pacotes contidos no objeto manifesto retornado pelo código Scheme em
@var{arquivo}. Esta opção pode ser repetida várias vezes, nesse caso os
manifestos são concatenados.

Isto tem um propósito similar à opção de mesmo nome em @command{guix
package} (@pxref{profile-manifest, @option{--manifest}}) e usa os mesmos
arquivos de manifesto. Ele permite que você defina uma coleção de pacotes
uma vez e use-a tanto para criar perfis quanto para criar arquivos para uso
em máquinas que não tenham o Guix instalado. Note que você pode especificar
@emph{ou} um arquivo de manifesto @emph{ou} uma lista de pacotes, mas não
ambos.

@xref{Escrevendo manifestos}, para obter informações sobre como escrever um
manifesto. @xref{shell-export-manifest, @command{guix shell
--export-manifest}}, para obter informações sobre como ``converter'' opções
de linha de comando em um manifesto.

@item --system=@var{sistema}
@itemx -s @var{sistema}
Tente compilar para @var{sistema}---por exemplo, @code{i686-linux}---em vez
do tipo de sistema do host de compilação.

@item --target=@var{tripleto}
@cindex compilação cruzada
Construção cruzada para @var{tripleto}, que deve ser um tripleto GNU válido,
como @code{"aarch64-linux-gnu"} (@pxref{Specifying target triplets,
tripletos de configuração GNU, autoconf, Autoconf}).

@item --compression=@var{ferramenta}
@itemx -C @var{ferramenta}
Compacte o tarball resultante usando @var{ferramenta}---um dos seguintes:
@code{gzip}, @code{zstd}, @code{bzip2}, @code{xz}, @code{lzip} ou
@code{none} para nenhuma compactação.

@anchor{pack-symlink-option}
@item --symlink=@var{spec}
@itemx -S @var{spec}
Adicione os symlinks especificados por @var{spec} à embalagem. Esta opção
pode aparecer várias vezes.

@var{spec} tem o formato @code{@var{fonte}=@var{alvo}}, onde @var{fonte} é a
ligação simbólica que será criado e @var{alvo} é o destino da ligação
simbólica.

Por exemplo, @code{-S /opt/gnu/bin=bin} cria uma ligação simbólica
@file{/opt/gnu/bin} apontanda para o subdiretório @file{bin} do perfil.

@item --save-provenance
Salvar informações de procedência para os pacotes passados na linha de
comando. As informações de procedência incluem a URL e o commit dos canais
em uso (@pxref{Canais}).

As informações de procedência são salvas no arquivo
@file{/gnu/store/@dots{}-profile/manifest} na embalagem, junto com os
metadados usuais do pacote --- o nome e a versão de cada pacote, suas
entradas propagadas e assim por diante. São informações úteis para o
destinatário da embalagem, que então sabe como a embalagem foi
(supostamente) obtida.

Esta opção não é habilitada por padrão porque, assim como os timestamps, as
informações de proveniência não contribuem em nada para o processo de
construção. Em outras palavras, há uma infinidade de URLs de canais e IDs de
commit que podem levar à mesma embalagem. Gravar esses metadados
``silenciosos'' na saída, portanto, potencialmente quebra a propriedade de
reprodutibilidade bit a bit de origem para binário.

@item --root=@var{arquivo}
@itemx -r @var{arquivo}
@cindex raiz do coletor de lixo, para embalagens
Crie @var{arquivo} como uma ligação simbólica para a embalagem resultante e
registre-a como uma raiz do coletor de lixo.

@item --localstatedir
@itemx --profile-name=@var{nome}
Inclua o ``diretório de estado local'', @file{/var/guix}, na embalagem
resultante, e principalmente o perfil
@file{/var/guix/profiles/per-user/root/@var{nome}} --- por padrão,
@var{nome} é @code{guix-profile}, que corresponde a
@file{~root/.guix-profile}.

@file{/var/guix} contém o banco de dados do armazém (@pxref{O armazém}), bem
como as raízes do coletor de lixo (@pxref{Invocando guix gc}). Fornecê-lo na
embalagem significa que o armazém está ``completo'' e gerenciável pelo Guix;
não fornecê-lo na embalagem significa que o armazém está ``morto'': itens
não podem ser adicionados a ele ou removidos dele após a extração da
embalagem.

Um caso de uso para isso é o tarball binário independente do Guix
(@pxref{Instalação de binários}).

@item --derivation
@itemx -d
Exiba o nome da derivação que constrói a embalagem.

@item --bootstrap
Use os binários bootstrap para construir a embalagem. Esta opção é útil
somente para desenvolvedores do Guix.
@end table

Além disso, @command{guix pack} suporta todas as opções de compilação comuns
(@pxref{Opções de compilação comuns}) e todas as opções de transformação de pacote
(@pxref{Opções de transformação de pacote}).


@node A cadeia de ferramentas do GCC
@section A cadeia de ferramentas do GCC

@cindex GCC
@cindex ld-wrapper
@cindex envoltório do vinculador
@cindex cadeia de ferramentas, para desenvolvimento em C
@cindex cadeia de ferramentas, para desenvolvimento Fortran

Se você precisa de uma cadeia de ferramentas completa para compilar e
vincular código-fonte C ou C++, use o pacote @code{gcc-toolchain}. Este
pacote fornece uma cadeia de ferramentas GCC completa para desenvolvimento
C/C++, incluindo o próprio GCC, a GNU C Library (cabeçalhos e binários, além
de símbolos de depuração na saída @code{debug}), Binutils e um wrapper de
vinculador.

O propósito do wrapper é inspecionar os switches @code{-L} e @code{-l}
passados para o vinculador, adicionar argumentos @code{-rpath}
correspondentes e invocar o vinculador real com esse novo conjunto de
argumentos. Você pode instruir o wrapper a se recusar a vincular bibliotecas
que não estejam no store definindo a variável de ambiente
@env{GUIX_LD_WRAPPER_ALLOW_IMPURITIES} como @code{no}.

O pacote @code{gfortran-toolchain} fornece uma cadeia de ferramentas GCC
completa para desenvolvimento Fortran. Para outras linguagens, use
@samp{guix search gcc toolchain} (@pxref{guix-search,, Invoking guix
package}).


@node Invocando guix git authenticate
@section Invocando @command{guix git authenticate}

@cindex @command{guix git authenticate}
@cindex authentication, of Git checkouts
@cindex Git checkout authentication

O comando @command{guix git authenticate} autentica um checkout do Git
seguindo a mesma regra dos canais (@pxref{channel-authentication,
autenticação dos canais}). Ou seja, a partir de um commit determinado, ele
garante que todos os commits subsequentes sejam assinados por uma chave
OpenPGP cuja impressão digital apareça no arquivo
@file{.guix-authorizations} de seus commits pais.

Você achará esse comando útil se mantiver um canal. Mas, na verdade, esse
mecanismo de autenticação é útil em um contexto mais amplo, então você pode
querer usá-lo para repositórios Git que não tenham nada a ver com Guix.

A sintaxe geral é:

@example
guix git authenticate @var{commit} @var{signer} [@var{options}@dots{}]
@end example

@cindex introdução, para autenticação Git
By default, this command authenticates the Git checkout in the current
directory; it outputs nothing and exits with exit code zero on success and
non-zero on failure.  @var{commit} above denotes the first commit where
authentication takes place, and @var{signer} is the OpenPGP fingerprint of
public key used to sign @var{commit}.  Together, they form a @dfn{channel
introduction} (@pxref{channel-authentication, channel introduction}).  On
your first successful run, the introduction is recorded in the
@file{.git/config} file of your checkout, allowing you to omit them from
subsequent invocations:

@example
guix git authenticate [@var{opções}@dots{}]
@end example

Caso você tenha ramos que exijam introduções diferentes, você pode
especificá-las diretamente em @file{.git/config}. Por exemplo, se o ramo
chamado @code{personal-fork} tiver uma introdução diferente de outros ramos,
você pode estender @file{.git/config} ao longo destas linhas:

@smallexample
[guix "authentication-personal-fork"]
	introduction-commit = cabba936fd807b096b48283debdcddccfea3900d
	introduction-signer = C0FF EECA BBA9 E6A8 0D1D  E643 A2A0 6DF2 A33A 54FA
	keyring = keyring
@end smallexample

A primeira execução também tenta instalar ganchos pré-push e pós-mesclagem,
de modo que @command{guix git authenticate} seja invocado assim que você
executar @command{git push}, @command{git pull} e comandos relacionados; no
entanto, ele não substitui ganchos preexistentes.

As opções de linha de comando descritas abaixo permitem que você ajuste o
processo.

@table @code
@item --repository=@var{diretório}
@itemx -r @var{diretório}
Abra o repositório Git em @var{diretório} em vez do diretório atual.

@item --keyring=@var{referência}
@itemx -k @var{referência}
Carregue o chaveiro OpenPGP de @var{referência}, a referência de uma
ramificação como @code{origin/keyring} ou @code{my-keyring}. A ramificação
deve conter chaves públicas OpenPGP em arquivos @file{.key}, em formato
binário ou ``ASCII-armored''. Por padrão, o chaveiro é carregado da
ramificação chamada @code{keyring}.

@item --end=@var{commit}
Autentique revisões até @var{commit}.

@item --stats
Exibir estatísticas de assinatura de confirmação após a conclusão.

@item --cache-key=@var{chave}
Os commits autenticados anteriormente são armazenados em cache em um arquivo
em @file{~/.cache/guix/authentication}. Esta opção força o cache a ser
armazenado no arquivo @var{chave} naquele diretório.

@item --historical-authorizations=@var{arquivo}
Por padrão, qualquer commit cujo(s) commit(s) pai(s) não tenha(m) o arquivo
@file{.guix-authorizations} é considerado não autêntico. Em contraste, esta
opção considera as autorizações em @var{arquivo} para qualquer commit que
não tenha @file{.guix-authorizations}. O formato de @var{arquivo} é o mesmo
que o de @file{.guix-authorizations} (@pxref{channel-authorizations, formato
@file{.guix-authorizations}}).
@end table


@c *********************************************************************
@node Interface de programação
@chapter Interface de programação

O GNU Guix fornece várias interfaces de programação Scheme (APIs) para
definir, construir e consultar pacotes. A primeira interface permite que os
usuários escrevam definições de pacotes de alto nível. Essas definições se
referem a conceitos de empacotamento familiares, como o nome e a versão de
um pacote, seu sistema de construção e suas dependências. Essas definições
podem então ser transformadas em ações de construção concretas.

As ações de build são executadas pelo daemon Guix, em nome dos usuários. Em
uma configuração padrão, o daemon tem acesso de gravação ao armazém---o
diretório @file{/gnu/store}---enquanto os usuários não têm. A configuração
recomendada também faz com que o daemon execute builds em chroots, sob
usuários de compilação específicos, para minimizar a interferência com o
resto do sistema.

@cindex derivation
APIs de nível inferior estão disponíveis para interagir com o daemon e o
armazém. Para instruir o daemon a executar uma ação de compilação, os
usuários na verdade fornecem a ele uma @dfn{derivação}. Uma derivação é uma
representação de baixo nível das ações de compilação a serem tomadas e do
ambiente no qual elas devem ocorrer --- derivações são para definições de
pacotes o que assembly é para programas C. O termo ``derivação'' vem do fato
de que os resultados de compilação @emph{derivam} deles.

Este capítulo descreve todas essas APIs, começando pelas definições de
pacotes de alto nível. @xref{Estrutura da árvore de origem}, para uma visão geral
mais geral do código-fonte.

@menu
* Módulos de pacote::        Pacotes do ponto de vista do programador.
* Definindo pacotes::        Definindo novos pacotes.
* Definindo variantes de pacote::  Personalização de pacotes.
* Escrevendo manifestos::    A lista de materiais do seu ambiente.
* Sistemas de compilação::   Especificando como pacotes são compilados.
* Fases de construção::      Fases do processo de construção de um pacote.
* Construir utilitários::    Auxiliares para suas definições de pacotes e 
                               muito mais.
* Caminhos de pesquisa::     Declaring search path environment variables.
* O armazém::                Manipulação do armazém de pacotes.
* Derivações::               Interface de baixo nível para derivações de 
                               pacotes.
* A mônada do armazém::      Interface puramente funcional para o armazém.
* Expressões-G::             Manipulação de expressões de compilação.
* Invocando guix repl::      Programação Guix em Guile
* Usando Guix interativamente::  Interação de granulação fina no REPL.
@end menu

@node Módulos de pacote
@section Módulos de pacote

Do ponto de vista da programação, as definições de pacotes da distribuição
GNU são fornecidas pelos módulos Guile no namespace @code{(gnu packages
@dots{})}@footnote{Observe que os pacotes sob o namespace do módulo
@code{(gnu packages @dots{})} não são necessariamente ``pacotes GNU''. Este
esquema de nomenclatura de módulos segue a convenção usual de nomenclatura
de módulos Guile: @code{gnu} significa que esses módulos são distribuídos
como parte do sistema GNU, e @code{packages} identifica módulos que definem
pacotes.} (@pxref{Modules, módulos Guile,, guile, Manual de Referência do
GNU Guile}). Por exemplo, o módulo @code{(gnu packages emacs)} exporta uma
variável chamada @code{emacs}, que é vinculada a um objeto @code{<package>}
(@pxref{Definindo pacotes}).

O namespace do módulo @code{(gnu packages @dots{})} é automaticamente
escaneado em busca de pacotes pelas ferramentas de linha de comando. Por
exemplo, ao executar @code{guix install emacs}, todos os módulos @code{(gnu
packages @dots{})} são escaneados até que um que exporte um objeto de pacote
cujo nome é @code{emacs} seja encontrado. Esse recurso de busca de pacotes é
implementado no módulo @code{(gnu packages)}.

@cindex personalização, de pacotes
@cindex caminho de pesquisa dos módulos de pacote
Os usuários podem armazenar definições de pacotes em módulos com nomes
diferentes --- por exemplo, @code{(my-packages emacs)}@footnote{Observe que
o nome do arquivo e o nome do módulo devem corresponder. Por exemplo, o
módulo @code{(my-packages emacs)} deve ser armazenado em um arquivo
@file{my-packages/emacs.scm} relativo ao caminho de carregamento
especificado com @option{--load-path} ou
@env{GUIX_PACKAGE_PATH}. @xref{Modules and the File System,,, guile, Manual
de Referência do GNU Guile}, para detalhes.}. Há duas maneiras de tornar
essas definições de pacotes visíveis para as interfaces do usuário:

@enumerate
@item
Ao adicionar o diretório que contém os módulos do seu pacote ao caminho de
pesquisa com o sinalizador @code{-L} do @command{guix package} e outros
comandos (@pxref{Opções de compilação comuns}), ou definindo a variável de ambiente
@env{GUIX_PACKAGE_PATH} descrita abaixo.

@item
Ao definir um @dfn{canal} e configurando @command{guix pull} para que ele
puxe dele. Um canal é essencialmente um repositório Git contendo módulos de
pacote. @xref{Canais}, para mais informações sobre como definir e usar
canais.
@end enumerate

@env{GUIX_PACKAGE_PATH} funciona de forma semelhante a outras variáveis de
caminho de pesquisa:

@defvr {Variável de ambiente} GUIX_PACKAGE_PATH
Esta é uma lista de diretórios separados por dois pontos para procurar
módulos de pacotes adicionais. Os diretórios listados nesta variável têm
precedência sobre os próprios módulos da distribuição.
@end defvr

A distribuição é totalmente @dfn{bootstrapped} e @dfn{auto-contida}: cada
pacote é construído com base somente em outros pacotes na distribuição. A
raiz deste grafo de dependência é um pequeno conjunto dos @dfn{binários
bootstrap}, fornecido pelo módulo @code{(gnu packages bootstrap)}. Para mais
informações sobre bootstrapping, @pxref{Inicializando}.

@node Definindo pacotes
@section Definindo pacotes

A interface de alto nível para definições de pacotes é implementada nos
módulos @code{(guix packages)} e @code{(guix build-system)}. Como exemplo, a
definição de pacote, ou @dfn{receita}, para o pacote GNU Hello se parece com
isto:

@lisp
(define-module (gnu packages hello)
  #:use-module (guix packages)
  #:use-module (guix download)
  #:use-module (guix build-system gnu)
  #:use-module (guix licenses)
  #:use-module (gnu packages gawk))

(define-public hello
  (package
    (name "hello")
    (version "2.10")
    (source (origin
              (method url-fetch)
              (uri (string-append "mirror://gnu/hello/hello-" version
                                  ".tar.gz"))
              (sha256
               (base32
                "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i"))))
    (build-system gnu-build-system)
    (arguments
     (list #:configure-flags #~(list "--enable-silent-rules")))
    (inputs (list gawk))
    (synopsis "Hello, GNU world: An example GNU package")
    (description "Guess what GNU Hello prints!")
    (home-page "https://www.gnu.org/software/hello/")
    (license gpl3+)))
@end lisp

@noindent
Sem ser um especialista em Scheme, o leitor pode ter adivinhado o
significado dos vários campos aqui. Esta expressão vincula a variável
@code{hello} a um registro @code{<package>} (@pxref{SRFI-9, Scheme records,,
guile, Manual de Referência do GNU Guile}). Este objeto de pacote pode ser
inspecionado usando procedimentos encontrados no módulo @code{(guix
packages)}; por exemplo, @code{(package-name hello)}
retorna---surpresa!---@code{"hello"}.

@quotation Quick start
Impatient? With luck, you may be able to import part or all of the
definition of the package you are interested in from another repository,
using the @code{guix import} command (@pxref{Invocando guix import}).

Alternatively, try out the
@uref{https://guix-hpc.gitlabpages.inria.fr/guix-packager/, Guix-Packager
interface} in your web browser to produce a preliminary package definition.
@end quotation

No exemplo acima, @code{hello} é definido em um módulo próprio, @code{(gnu
packages hello)}. Tecnicamente, isso não é estritamente necessário, mas é
conveniente fazê-lo: todos os pacotes definidos em módulos sob @code{(gnu
packages @dots{})} são automaticamente conhecidos pelas ferramentas de linha
de comando (@pxref{Módulos de pacote}).

Há alguns pontos que vale a pena observar na definição do pacote acima:

@itemize
@item
O campo @code{source} do pacote é um objeto @code{<origin>} (@pxref{Referência do origin}, para a referência completa). Aqui, o método @code{url-fetch} de
@code{(guix download)} é usado, o que significa que a fonte é um arquivo a
ser baixado por FTP ou HTTP.

O prefixo @code{mirror://gnu} instrui @code{url-fetch} a usar um dos
espelhos GNU definidos em @code{(guix download)}.

O campo @code{sha256} especifica o hash SHA256 esperado do arquivo que está
sendo baixado. É obrigatório e permite que o Guix verifique a integridade do
arquivo. O formulário @code{(base32 @dots{})} introduz a representação
base32 do hash. Você pode obter essas informações com @code{guix download}
(@pxref{Invocando guix download}) e @code{guix hash} (@pxref{Invocando guix hash}).

@cindex remendos
Quando necessário, o formulário @code{origin} também pode ter um campo
@code{patches} listando os remendos a serem aplicados e um campo
@code{snippet} fornecendo uma expressão Scheme para modificar o
código-fonte.

@item
@cindex Sistema de construção GNU
O campo @code{build-system} especifica o procedimento para construir o
pacote (@pxref{Sistemas de compilação}). Aqui, @code{gnu-build-system} representa o
familiar GNU Build System, onde os pacotes podem ser configurados,
construídos e instalados com a sequência de comando usual @code{./configure
&& make && make check && make install}.

Ao começar a empacotar software não trivial, você pode precisar de
ferramentas para manipular essas fases de compilação, manipular arquivos e
assim por diante. @xref{Construir utilitários}, para mais informações sobre isso.

@item
O campo @code{arguments} especifica opções para o sistema de compilação
(@pxref{Sistemas de compilação}). Aqui, ele é interpretado por
@code{gnu-build-system} como uma solicitação executada @file{configure} com
o sinalizador @option{--enable-silent-rules}.

O valor do campo @code{arguments} é uma lista de argumentos passados para o
sistema de construção mais adiante, como com @code{apply} (@pxref{Fly Evaluation, @code{apply},, guile, Manual de referência do GNU Guile}).

@cindex keyword arguments, for build systems
A sequência hash-dois-pontos (@code{#:}) define um @dfn{palavra-chave} em
Scheme (@pxref{Keywords,,, guile, Manual de referência do GNU Guile}) e
@code{#:configure-flags} é uma palavra-chave usada para passar um argumento
de palavra-chave para o sistema de compilação (@pxref{Coding With
Keywords,,, guile, Manual de referência do GNU Guile}).

@findex #~
@findex gexp
@cindex staging, for build system arguments
@cindex code staging, in package definitions
What about these hash-tilde (@code{#~}) characters? This is Guix-specific
syntax introducing a so-called @dfn{G-expression} (@pxref{Expressões-G}),
which denotes code that is @dfn{staged} for eventual evaluation: this staged
code is only evaluated if and when attempting to build the package, by the
build daemon.  In this example, the staged code is the @code{(list @dots{})}
expression, which builds a list of one element, the configure flag.

@item
O campo @code{inputs} especifica entradas para o processo de
construção---i.e., dependências de tempo de construção ou tempo de execução
do pacote. Aqui, adicionamos uma entrada, uma referência à variável
@code{gawk}; @code{gawk} é ele próprio vinculado a um objeto
@code{<package>}.

Note que GCC, Coreutils, Bash e outras ferramentas essenciais não precisam
ser especificadas como entradas aqui. Em vez disso, @code{gnu-build-system}
cuida de garantir que elas estejam presentes (@pxref{Sistemas de compilação}).

No entanto, quaisquer outras dependências precisam ser especificadas no
campo @code{inputs}. Qualquer dependência não especificada aqui simplesmente
ficará indisponível para o processo de build, possivelmente levando a uma
falha de build.
@end itemize

@xref{Referência do package}, para uma descrição completa dos campos possíveis.

@quotation Indo além
@cindex Linguagem de programação Scheme, primeiros passos
Intimidado pela linguagem Scheme ou curioso sobre ela? O Livro de receitas
tem uma seção curta para começar que recapitula algumas das coisas mostradas
acima e explica os fundamentos. @xref{Um curso intensivo de Scheme,,,
guix-cookbook.pt_BR, Livro de receitas do GNU Guix}, para mais informações.
@end quotation

Uma vez que uma definição de pacote esteja pronta, o pacote pode ser
realmente construído usando a ferramenta de linha de comando @code{guix
build} (@pxref{Invocando guix build}), solucionando problemas de quaisquer
falhas de construção que você encontrar (@pxref{Depurando falhas de compilação}). Você pode facilmente voltar para a definição do pacote usando o
comando @command{guix edit} (@pxref{Invocando guix edit}). @xref{Diretrizes de empacotamento}, para mais informações sobre como testar definições de pacote, e
@ref{Invocando guix lint}, para informações sobre como verificar uma
definição para conformidade de estilo.
@vindex GUIX_PACKAGE_PATH
Por fim, @pxref{Canais}, para obter informações sobre como estender a
distribuição adicionando suas próprias definições de pacote em um ``canal''.

Por fim, a atualização da definição do pacote para uma nova versão upstream
pode ser parcialmente automatizada pelo comando @command{guix refresh}
(@pxref{Invocando guix refresh}).

Nos bastidores, uma derivação correspondente ao objeto @code{<package>} é
primeiro computada pelo procedimento @code{package-derivation}. Essa
derivação é armazenada em um arquivo @file{.drv} em @file{/gnu/store}. As
ações de construção que ele prescreve podem então ser realizadas usando o
procedimento @code{build-derivations} (@pxref{O armazém}).

@deffn {Procedimento} package-derivation armazém pacote [sistema]
Retorne o objeto @code{<derivation>} de @var{pacote} para @var{sistema}
(@pxref{Derivações}).

@var{pacote} deve ser um objeto @code{<package>} válido e @var{sistema} deve
ser uma string que indique o tipo de sistema de destino — por exemplo,
@code{"x86_64-linux"} para um sistema GNU baseado em Linux
x86_64. @var{armazém} deve ser uma conexão com o daemon, que opera no
armazém (@pxref{O armazém}).
@end deffn

@noindent
@cindex compilação cruzada
Da mesma forma, é possível calcular uma derivação que crie um pacote para
algum outro sistema:

@deffn {Procedimento} package-cross-derivation armazém pacote alvo [sistema]
Retorne o objeto @code{<derivation>} de @var{pacote} criado de @var{sistema}
para @var{alvo}.

@var{alvo} deve ser um tripleto GNU válido que indique o hardware e o
sistema operacional de destino, como @code{"aarch64-linux-gnu"}
(@pxref{Specifying Target Triplets,,, autoconf, Autoconf}).
@end deffn

Depois de ter as definições dos pacotes, você pode definir facilmente
@emph{variantes} desses pacotes. @xref{Definindo variantes de pacote}, para mais
informações sobre isso.

@menu
* Referência do package::    O tipo de dados package.
* Referência do origin::     O tipo de dados origin.
@end menu


@node Referência do package
@subsection Referência do @code{package}

Esta seção resume todas as opções disponíveis nas declarações @code{package}
(@pxref{Definindo pacotes}).

@deftp {Tipo de dados} package
Este é o tipo de dado que representa uma receita de pacote.

@table @asis
@item @code{name}
The name of the package, as a string.

@item @code{version}
The version of the package, as a string.  @xref{Números de versão}, for
guidelines.

@item @code{source}
Um objeto que diz como o código-fonte do pacote deve ser adquirido. Na
maioria das vezes, este é um objeto @code{origin}, que denota um arquivo
obtido da Internet (@pxref{Referência do origin}). Também pode ser qualquer
outro objeto ``tipo arquivo'', como um @code{local-file}, que denota um
arquivo do sistema de arquivos local (@pxref{Expressões-G,
@code{local-file}}).

@item @code{build-system}
O sistema de compilação que deve ser usado para compilar o pacote
(@pxref{Sistemas de compilação}).

@item @code{arguments} (padrão: @code{'()})
Os argumentos que devem ser passados para o sistema de compilação
(@pxref{Sistemas de compilação}). Esta é uma lista, normalmente contendo pares
sequenciais de palavra-chave-valor, como neste exemplo:

@lisp
(package
  (name "example")
  ;; several fields omitted
  (arguments
    (list #:tests? #f                     ;skip tests
          #:make-flags #~'("VERBOSE=1")   ;pass flags to 'make'
          #:configure-flags #~'("--enable-frobbing"))))
@end lisp

O conjunto exato de palavras-chave suportadas depende do sistema de
compilação (@pxref{Sistemas de compilação}), mas você verá que quase todas elas
honram @code{#:configure-flags}, @code{#:make-flags}, @code{#:tests?} e
@code{#:phases}. A palavra-chave @code{#:phases} em particular permite que
você modifique o conjunto de fases de compilação para seu pacote
(@pxref{Fases de construção}).

O REPL tem comandos dedicados para inspecionar interativamente os valores de
alguns desses argumentos, como um auxílio de depuração conveniente
(@pxref{Usando Guix interativamente}).

@quotation Nota de compatibilidade
Até a versão 1.3.0, o campo @code{arguments} normalmente usaria @code{quote}
(@code{'}) ou @code{quasiquote} (@code{`}) e nenhuma expressão G, assim:

@lisp
(package
  ;; several fields omitted
  (arguments   ;old-style quoted arguments
   '(#:tests? #f
     #:configure-flags '("--enable-frobbing"))))
@end lisp

Para converter esse estilo para o mostrado acima, você pode executar
@code{guix style -S arguments @var{pacote}} (@pxref{Invocando guix style}).
@end quotation

@item @code{inputs} (padrão: @code{'()})
@itemx @code{native-inputs} (padrão: @code{'()})
@itemx @code{propagated-inputs} (padrão: @code{'()})
@cindex entradas, de pacotes
Esses campos listam dependências do pacote. Cada elemento dessas listas é um
pacote, origem ou outro ``objeto tipo arquivo'' (@pxref{Expressões-G});
para especificar a saída desse objeto tipo arquivo que deve ser usado, passe
uma lista de dois elementos onde o segundo elemento é a saída
(@pxref{Pacotes com múltiplas saídas}, para mais informações sobre saídas
de pacotes). Por exemplo, a lista abaixo especifica três entradas:

@lisp
(list libffi libunistring
      `(,glib "bin"))      ;a saída "bin" de GLib
@end lisp

No exemplo acima, a saída @code{"out"} de @code{libffi} e
@code{libunistring} é usada.

@quotation Nota de compatibilidade
Até a versão 1.3.0, as listas de entrada eram uma lista de tuplas, onde cada
tupla tem um rótulo para a entrada (uma string) como seu primeiro elemento,
um pacote, origem ou derivação como seu segundo elemento e, opcionalmente, o
nome da saída que deve ser usada, cujo padrão é @code{"out"}. Por exemplo, a
lista abaixo é equivalente à acima, mas usando o @dfn{antigo estilo de
entrada}:

@lisp
;; Estilo de entrada antigo (obsoleto).
`(("libffi" ,libffi)
  ("libunistring" ,libunistring)
  ("glib:bin" ,glib "bin"))  ;a saída "bin" do GLib
@end lisp

Este estilo agora está obsoleto; ele ainda é suportado, mas o suporte será
removido em uma versão futura. Ele não deve ser usado para novas definições
de pacote. @xref{Invocando guix style}, sobre como migrar para o novo estilo.
@end quotation

@cindex compilação cruzada, dependências de pacotes
A distinção entre @code{native-inputs} e @code{inputs} é necessária ao
considerar a compilação cruzada. Ao compilar cruzadamente, as dependências
listadas em @code{inputs} são construídas para a arquitetura @emph{target}
(alvo); inversamente, as dependências listadas em @code{native-inputs} são
construídas para a arquitetura da máquina @emph{build}.

@code{native-inputs} é normalmente usado para listar ferramentas necessárias
no momento da compilação, mas não no momento da execução, como Autoconf,
Automake, pkg-config, Gettext ou Bison. @command{guix lint} pode relatar
prováveis erros nesta área (@pxref{Invocando guix lint}).

@anchor{package-propagated-inputs}
Por fim, @code{propagated-inputs} é semelhante a @code{inputs}, mas os
pacotes especificados serão instalados automaticamente nos perfis
(@pxref{Recursos, a função dos perfis no Guix}) junto com o pacote ao qual
pertencem (@pxref{package-cmd-propagated-inputs, @command{guix package}},
para obter informações sobre como @command{guix package} lida com entradas
propagadas).

Por exemplo, isso é necessário ao empacotar uma biblioteca C/C++ que precisa
de cabeçalhos de outra biblioteca para compilar, ou quando um arquivo
pkg-config faz referência a outro por meio de seu campo @code{Requires}.

Outro exemplo em que @code{propagated-inputs} é útil é para linguagens que
não têm um recurso para registrar o caminho de pesquisa em tempo de execução
semelhante ao @code{RUNPATH} de arquivos ELF; isso inclui Guile, Python,
Perl e mais. Ao empacotar bibliotecas escritas nessas linguagens, garanta
que elas possam encontrar o código da biblioteca do qual dependem em tempo
de execução listando as dependências em tempo de execução em
@code{propagated-inputs} em vez de @code{inputs}.

@item @code{outputs} (padrão: @code{'("out")})
A lista de nomes de saída do pacote. @xref{Pacotes com múltiplas saídas},
para usos típicos de saídas adicionais.

@item @code{native-search-paths} (padrão: @code{'()})
@itemx @code{search-paths} (padrão: @code{'()})
Uma lista de objetos @code{search-path-specification} descrevendo variáveis
de ambiente do caminho de pesquisa respeitadas pelo pacote. @xref{Caminhos de pesquisa}, para mais informações sobre especificações do caminho de pesquisa.

Quanto às entradas, a distinção entre @code{native-search-paths} e
@code{search-paths} só importa quando há compilação cruzada. Em um contexto
de compilação cruzada, @code{native-search-paths} se aplica exclusivamente a
entradas nativas, enquanto @code{search-paths} se aplica somente a entradas
de host.

Pacotes como compiladores cruzados se importam com entradas de destino ---
por exemplo, nosso compilador cruzado GCC (modificado) tem
@env{CROSS_C_INCLUDE_PATH} em @code{search-paths}, o que permite que ele
escolha arquivos @file{.h} para o sistema de destino e @emph{não} aqueles de
entradas nativas. Para a maioria dos pacotes, porém, apenas
@code{native-search-paths} faz sentido.

@item @code{replacement} (padrão: @code{#f})
Deve ser @code{#f} ou um objeto de pacote que será usado como um
@dfn{substituição} para este pacote. @xref{Atualizações de segurança, enxertos}, para
detalhes.

@item @code{synopsis}
Uma descrição de uma linha do pacote.

@item @code{description}
Uma descrição mais elaborada do pacote, como uma string na sintaxe Texinfo.

@item @code{license}
@cindex licença, de pacotes
A licença do pacote; um valor de @code{(guix licenses)}, ou uma lista de
tais valores.

@item @code{home-page}
A URL para a página inicial do pacote, como uma string.

@item @code{supported-systems} (padrão: @code{%supported-systems})
A lista de sistemas suportados pelo pacote, como strings do formato
@code{arquitetura-kernel}, por exemplo @code{"x86_64-linux"}.

@item @code{location} (padrão: localização de origem do formulário @code{package})
O local de origem do pacote. É útil sobrescrever isso ao herdar de outro
pacote, em cujo caso esse campo não é corrigido automaticamente.
@end table
@end deftp

@defmac this-package
Quando usado no @emph{escopo lexical} de uma definição de campo de pacote,
esse identificador é resolvido para o pacote que está sendo definido.

O exemplo abaixo mostra como adicionar um pacote como uma entrada nativa de
si mesmo durante a compilação cruzada:

@lisp
(package
  (name "guile")
  ;; ...

  ;; Quando compilado de forma cruzada, Guile, por exemplo, depende de
  ;; uma versão nativa de si mesmo. Adicione aqui.
  (native-inputs (if (%current-target-system)
                     (list this-package)
                     '())))
@end lisp

É um erro fazer referência a @code{this-package} fora de uma definição de
pacote.
@end defmac

Os seguintes procedimentos auxiliares são fornecidos para ajudar a lidar com
entradas de pacotes.

@deffn {Procedimento} lookup-package-input pacote nome
@deffnx {Procedimento} lookup-package-native-input pacote nome
@deffnx {Procedimento} lookup-package-propagated-input pacote nome
@deffnx {Procedimento} lookup-package-direct-input pacote nome
Procure @var{nome} entre as entradas de @var{pacote} (ou entradas nativas,
propagadas ou diretas). Retorne-o se encontrado, @code{#f} caso contrário.

@var{name} is the name of a package or the file name of an origin depended
on.  Here's how you might use it:

@lisp
(use-modules (guix packages) (gnu packages base))

(lookup-package-direct-input coreutils "gmp")
@result{} #<package gmp@@6.2.1 @dots{}>
@end lisp

Neste exemplo, obtemos o pacote @code{gmp} que está entre as entradas
diretas de @code{coreutils}.

When looking up an origin, use the name that appears in the origin's
@code{file-name} field or its default file name---e.g.,
@code{"foo-1.2.tar.gz"}.
@end deffn

@cindex development inputs, of a package
@cindex implicit inputs, of a package
Às vezes, você vai querer obter a lista de entradas necessárias para
@emph{desenvolver} um pacote---todas as entradas que são visíveis quando o
pacote é compilado. É isso que o procedimento
@code{package-development-inputs} retorna.

@deffn {Procedimento} package-development-inputs pacote [sistema] [#:target #f]
Retorna a lista de entradas necessárias para @var{pacote} para fins de
desenvolvimento em @var{sistema}. Quando @var{target} é verdadeiro, retorna
as entradas necessárias para compilar cruzadamente @var{pacote} de
@var{sistema} para o alvo @var{target}, onde @var{target} é um tripleto como
@code{"aarch64-linux-gnu"}.

Note que o resultado inclui entradas explícitas e entradas
implícitas---entradas adicionadas automaticamente pelo sistema de construção
(@pxref{Sistemas de compilação}). Vamos pegar o pacote @code{hello} para ilustrar
isso:

@lisp
(use-modules (gnu packages base) (guix packages))

hello
@result{} #<package hello@@2.10 gnu/packages/base.scm:79 7f585d4f6790>

(package-direct-inputs hello)
@result{} ()

(package-development-inputs hello)
@result{} (("source" @dots{}) ("tar" #<package tar@@1.32 @dots{}>) @dots{})
@end lisp

Neste exemplo, @code{package-direct-inputs} retorna a lista vazia, porque
@code{hello} tem zero dependências explícitas. Por outro lado,
@code{package-development-inputs} inclui entradas adicionadas implicitamente
por @code{gnu-build-system} que são necessárias para construir @code{hello}:
tar, gzip, GCC, libc, Bash e mais. Para visualizá-lo, @command{guix graph
hello} mostraria entradas explícitas, enquanto @command{guix graph -t bag
hello} incluiria entradas implícitas (@pxref{Invocando guix graph}).
@end deffn

Como os pacotes são objetos Scheme regulares que capturam um grafo de
dependência completo e procedimentos de construção associados, geralmente é
útil escrever procedimentos que pegam um pacote e retornam uma versão
modificada dele de acordo com alguns parâmetros. Abaixo estão alguns
exemplos.

@cindex cadeia de ferramentas, escolhendo a cadeia de ferramentas de um pacote
@deffn {Procedimento} package-with-c-toolchain pacote cadeia
Retorna uma variante de @var{pacote} que usa @var{cadeia} de ferramentas em
vez da cadeia de ferramentas padrão GNU C/C++. @var{cadeia} deve ser uma
lista de entradas (tuplas de rótulo/pacote) que fornecem funcionalidade
equivalente, como o pacote @code{gcc-toolchain}.

O exemplo abaixo retorna uma variante do pacote @code{hello} criado com
GCC@tie{}10.x e o restante da cadeia de ferramentas GNU (Binutils e a
Biblioteca C GNU) em vez da cadeia de ferramentas padrão:

@lisp
(let ((toolchain (specification->package "gcc-toolchain@@10")))
  (package-with-c-toolchain hello `(("toolchain" ,toolchain))))
@end lisp

A cadeia de ferramentas de construção é parte das @dfn{entradas implícitas}
dos pacotes---geralmente não é listada como parte dos vários campos
``entradas'' e, em vez disso, é puxada pelo sistema de
construção. Consequentemente, esse procedimento funciona alterando o sistema
de construção de @var{pacote} para que ele puxe @var{cadeia} de ferramentas
em vez dos padrões. @xref{Sistemas de compilação}, para mais informações sobre
sistemas de construção.
@end deffn

@node Referência do origin
@subsection Referência do @code{origin}

Esta seção documenta @dfn{origens}. Uma declaração @code{origin} especifica
dados que devem ser ``produzidos''---baixados, normalmente---e cujo hash de
conteúdo é conhecido com antecedência. Origens são usados principalmente
para representar o código-fonte de pacotes (@pxref{Definindo pacotes}). Por
esse motivo, o formulário @code{origin} permite que você declare remendos
para aplicar ao código-fonte original, bem como trechos de código para
modificá-lo.

@deftp {Tipo de dados} origin
Este é o tipo de dado que representa a origem do código-fonte.

@table @asis
@item @code{uri}
Um objeto contendo o URI da fonte. O tipo de objeto depende do @code{method}
(veja abaixo). Por exemplo, ao usar o método @var{url-fetch} de @code{(guix
download)}, os valores válidos de @code{uri} são: uma URL representada como
uma string, ou uma lista delas.

@cindex derivações de saída fixa, para download
@item @code{method}
Um procedimento monádico que manipula o URI fornecido. O procedimento deve
aceitar pelo menos três argumentos: o valor do campo @code{uri} e o
algoritmo de hash e o valor de hash especificados pelo campo
@code{hash}. Ele deve retornar um item do armazém ou uma derivação na mônada
do armazém (@pxref{A mônada do armazém}); a maioria dos métodos retorna uma
derivação de saída fixa (@pxref{Derivações}).

Os métodos comumente usados incluem @code{url-fetch}, que busca dados de uma
URL, e @code{git-fetch}, que busca dados de um repositório Git (veja
abaixo).

@item @code{sha256}
Um bytevector contendo o hash SHA-256 da fonte. Isso é equivalente a
fornecer um objeto SHA256 @code{content-hash} no campo @code{hash} descrito
abaixo.

@item @code{hash}
O objeto @code{content-hash} da fonte — veja abaixo como usar
@code{content-hash}.

You can obtain this information using @code{guix download} (@pxref{Invocando guix download}) or @code{guix hash} (@pxref{Invocando guix hash}).

@item @code{file-name} (padrão: @code{#f})
O nome do arquivo sob o qual o código-fonte deve ser salvo. Quando for
@code{#f}, um valor padrão sensato será usado na maioria dos casos. Caso a
fonte seja obtida de uma URL, o nome do arquivo da URL será usado. Para
checkouts de controle de versão, é recomendado fornecer o nome do arquivo
explicitamente porque o padrão não é muito descritivo.

@item @code{patches} (padrão: @code{'()})
Uma lista de nomes de arquivos, origens ou objetos tipo arquivo
(@pxref{Expressões-G, objetos tipo arquivo}) apontando para remendos a
serem aplicados à origem.

Esta lista de remendos deve ser incondicional. Em particular, não pode
depender do valor de @code{%current-system} ou
@code{%current-target-system}.

@item @code{snippet} (padrão: @code{#f})
Uma expressão G (@pxref{Expressões-G}) ou expressão S que será executada no
diretório de origem. Esta é uma maneira conveniente de modificar a origem,
às vezes mais conveniente do que um patch.

@item @code{patch-flags} (padrão: @code{'("-p1")})
Uma lista de sinalizadores de linha de comando que devem ser passados para o
comando @code{patch}.

@item @code{patch-inputs} (padrão: @code{#f})
Pacotes de entrada ou derivações para o processo de patching. Quando este é
@code{#f}, o conjunto usual de entradas necessárias para patching é
fornecido, como GNU@tie{}Patch.

@item @code{modules} (padrão: @code{'()})
Uma lista de módulos Guile que devem ser carregados durante o processo de
aplicação de remendos e durante a execução do código no campo
@code{snippet}.

@item @code{patch-guile} (padrão: @code{#f})
O pacote Guile que deve ser usado no processo de patching. Quando este é
@code{#f}, um padrão sensato é usado.
@end table
@end deftp

@deftp {Tipo de dados} content-hash @var{valor} [@var{algoritmo}]
Construa um objeto hash de conteúdo para o @var{algoritmo} fornecido, e com
@var{valor} como seu valor hash. Quando @var{algoritmo} é omitido, presuma
que é @code{sha256}.

@var{valor} pode ser uma string literal, nesse caso ela é decodificada em
base32, ou pode ser um bytevector.

Os seguintes formulários são todos equivalentes:

@lisp
(content-hash "05zxkyz9bv3j9h0xyid1rhvh3klhsmrpkf3bcs6frvlgyr2gwilj")
(content-hash "05zxkyz9bv3j9h0xyid1rhvh3klhsmrpkf3bcs6frvlgyr2gwilj"
              sha256)
(content-hash (base32
               "05zxkyz9bv3j9h0xyid1rhvh3klhsmrpkf3bcs6frvlgyr2gwilj"))
(content-hash (base64 "kkb+RPaP7uyMZmu4eXPVkM4BN8yhRd8BTHLslb6f/Rc=")
              sha256)
@end lisp

Tecnicamente, @code{content-hash} é atualmente implementado como uma
macro. Ele realiza verificações de sanidade no momento da expansão da macro,
quando possível, como garantir que @var{valor} tenha o tamanho certo para
@var{algoritmo}.
@end deftp

Como vimos acima, como exatamente os dados aos quais uma origem se refere
são recuperados é determinado pelo seu campo @code{method}. O módulo
@code{(guix download)} fornece o método mais comum, @code{url-fetch},
descrito abaixo.

@deffn {Procedimento} url-fetch url hash-algo hash [nome] [#:executable?? #f]
Retorna uma derivação de saída fixa que busca dados de @var{url} (uma
string, ou uma lista de strings denotando URLs alternativas), que deve ter
hash @var{hash} do tipo @var{hash-algo} (um símbolo). Por padrão, o nome do
arquivo é o nome base de URL; opcionalmente, @var{nome} pode especificar um
nome de arquivo diferente. Quando @var{executable?} é verdadeiro, torna o
arquivo baixado executável.

Quando uma das URLs começa com @code{mirror://}, sua parte host é
interpretada como o nome de um esquema de espelho, obtido de
@file{%mirror-file}.

Como alternativa, quando a URL começa com @code{file://}, retorne o nome do
arquivo correspondente no armazém.
@end deffn

Da mesma forma, o módulo @code{(guix git-download)} define o método de
origem @code{git-fetch}, que busca dados de um repositório de controle de
versão Git, e o tipo de dados @code{git-reference} para descrever o
repositório e a revisão a serem buscados.

@deffn {Procedimento} git-fetch ref hash-algo hash [nome]
Retorna uma derivação de saída fixa que busca @var{ref}, um objeto
@code{<git-reference>}. Espera-se que a saída tenha hash recursivo
@var{hash} do tipo @var{hash-algo} (um símbolo). Use @var{nome} como o nome
do arquivo, ou um nome genérico se @code{#f}.
@end deffn

@deffn {Procedimento} git-fetch/lfs ref hash-algo hash [nome]
Esta é uma variante do procedimento @code{git-fetch} que suporta a extensão
Git @acronym{LFS, Large File Storage}. Isso pode ser útil para extrair
alguns dados de teste binários para executar o conjunto de testes de um
pacote, por exemplo.
@end deffn

@deftp {Tipo de dados} git-reference
Este tipo de dado representa uma referência Git para @code{git-fetch} a
recuperar.

@table @asis
@item @code{url}
A URL do repositório Git a ser clonado.

@item @code{commit}
Esta string denota o commit a ser buscado (uma string hexadecimal) ou a tag
a ser buscada. Você também pode usar um ID de commit ``curto'' ou um
identificador de estilo @command{git describe} como
@code{v1.0.1-10-g58d7909c97}.

@item @code{recursive?} (padrão: @code{#f})
Este booleano indica se os submódulos do Git devem ser buscados
recursivamente.
@end table

O exemplo abaixo denota a tag @code{v2.10} do repositório GNU@tie{}Hello:

@lisp
(git-reference
  (url "https://git.savannah.gnu.org/git/hello.git")
  (commit "v2.10"))
@end lisp

Isso é equivalente à referência abaixo, que nomeia explicitamente o commit:

@lisp
(git-reference
  (url "https://git.savannah.gnu.org/git/hello.git")
  (commit "dc7dc56a00e48fe6f231a58f6537139fe2908fb9"))
@end lisp
@end deftp

Para repositórios Mercurial, o módulo @code{(guix hg-download)} define o
método de origem @code{hg-fetch} e o tipo de dados @code{hg-reference} para
suporte ao sistema de controle de versão Mercurial.

@deffn {Procedimento} hg-fetch ref hash-algo hash [nome]
Retorna uma derivação de saída fixa que busca @var{ref}, um objeto
@code{<hg-reference>}. Espera-se que a saída tenha hash recursivo @var{hash}
do tipo @var{hash-algo} (um símbolo). Use @var{nome} como o nome do arquivo,
ou um nome genérico se @code{#f}.
@end deffn

@deftp {Tipo de dados} hg-reference
Este tipo de dado representa uma referência Mercurial para @code{hg-fetch} a
recuperar.

@table @asis
@item @code{url}
A URL do repositório Mercurial a ser clonado.

@item @code{changeset}
Esta sequência de caracteres indica a revisão a ser buscado.
@end table
@end deftp

Para repositórios Subversion, o módulo @code{(guix svn-download)} define o
método de origem @code{svn-fetch} e o tipo de dados @code{svn-reference}
para suporte ao sistema de controle de versão Subversion.

@deffn {Procedimento} svn-fetch ref hash-algo hash [nome]
Retorna uma derivação de saída fixa que busca @var{ref}, um objeto
@code{<svn-reference>}. Espera-se que a saída tenha hash recursivo
@var{hash} do tipo @var{hash-algo} (um símbolo). Use @var{nome} como o nome
do arquivo, ou um nome genérico se @code{#f}.
@end deffn

@deftp {Tipo de dados} svn-reference
Este tipo de dado representa uma referência Subversion para @code{svn-fetch}
a recuperar.

@table @asis
@item @code{url}
A URL do repositório Subversion a ser clonado.

@item @code{revision}
Esta sequência de caracteres denota a revisão a ser buscada especificada
como um número.

@item @code{recursive?} (padrão: @code{#f})
Este booleano indica se deve-se buscar recursivamente ``externals'' do
Subversion.

@item @code{user-name} (padrão: @code{#f})
O nome de uma conta que tem acesso de leitura ao repositório, se o
repositório não for público.

@item @code{password} (padrão: @code{#f})
Senha para acessar o repositório Subversion, se necessário.
@end table
@end deftp

Para repositórios Bazaar, o módulo @code{(guix bzr-download)} define o
método de origem @code{bzr-fetch} e o tipo de dados @code{bzr-reference}
para suporte ao sistema de controle de versão Bazaar.

@deffn {Procedimento} bzr-fetch ref hash-algo hash [nome]
Retorna uma derivação de saída fixa que busca @var{ref}, um objeto
@code{<bzr-reference>}. Espera-se que a saída tenha hash recursivo
@var{hash} do tipo @var{hash-algo} (um símbolo). Use @var{nome} como o nome
do arquivo, ou um nome genérico se @code{#f}.
@end deffn

@deftp {Tipo de dados} bzr-reference
Este tipo de dado representa uma referência Bazaar para @code{bzr-fetch} a
recuperar.

@table @asis
@item @code{url}
A URL do repositório Bazaar a ser clonado.

@item @code{revision}
Esta sequência de caracteres denota a revisão a ser buscada especificada
como um número.
@end table
@end deftp

Para repositórios CVS, o módulo @code{(guix cvs-download)} define o método
de origem @code{cvs-fetch} e o tipo de dados @code{cvs-reference} para
suporte ao Concurrent Versions System (CVS).

@deffn {Procedimento} cvs-fetch ref hash-algo hash [nome]
Retorna uma derivação de saída fixa que busca @var{ref}, um objeto
@code{<cvs-reference>}. Espera-se que a saída tenha hash recursivo
@var{hash} do tipo @var{hash-algo} (um símbolo). Use @var{nome} como o nome
do arquivo, ou um nome genérico se @code{#f}.
@end deffn

@deftp {Tipo de dados} cvs-reference
Este tipo de dado representa uma referência CVS para @code{cvs-fetch} a
recuperar.

@table @asis
@item @code{root-directory}
O diretório raiz do CVS.

@item @code{module}
Módulo a ser buscado.

@item @code{revision}
Revisão para buscar.
@end table

O exemplo abaixo denota uma versão do gnu-standards para buscar:

@lisp
(cvs-reference
  (root-directory ":pserver:anonymous@@cvs.savannah.gnu.org:/sources/gnustandards")
  (module "gnustandards")
  (revision "2020-11-25"))
@end lisp

@end deftp

@node Definindo variantes de pacote
@section Definindo variantes de pacote

@cindex personalizando pacotes
@cindex variantes, de pacotes
Uma das coisas boas com o Guix é que, dada uma definição de pacote, você
pode facilmente @emph{derivar} variantes desse pacote---para uma versão
upstream diferente, com dependências diferentes, opções de compilação
diferentes e assim por diante. Alguns desses pacotes personalizados podem
ser definidos diretamente da linha de comando (@pxref{Opções de transformação de pacote}). Esta seção descreve como definir variantes de pacotes no
código. Isso pode ser útil em ``manifestos'' (@pxref{Escrevendo manifestos}) e
em sua própria coleção de pacotes (@pxref{Criando um canal}), entre
outros!

@cindex herdar, para definições de pacotes
Conforme discutido anteriormente, os pacotes são objetos de primeira classe
na linguagem Scheme. O módulo @code{(guix packages)} fornece a construção
@code{package} para definir novos objetos de pacote (@pxref{Referência do package}). A maneira mais fácil de definir uma variante de pacote é usando
a palavra-chave @code{inherit} junto com @code{package}. Isso permite que
você herde de uma definição de pacote enquanto substitui os campos que
deseja.

Por exemplo, dada a variável @code{hello}, que contém uma definição para a
versão atual do GNU@tie{}Hello, veja como você definiria uma variante para a
versão 2.2 (lançada em 2006, é vintage!):

@lisp
(use-modules (gnu packages base))    ;para 'hello'

(define hello-2.2
  (package
    (inherit hello)
    (version "2.2")
    (source (origin
              (method url-fetch)
              (uri (string-append "mirror://gnu/hello/hello-" version
                                  ".tar.gz"))
              (sha256
               (base32
                "0lappv4slgb5spyqbh6yl5r013zv72yqg2pcl30mginf3wdqd8k9"))))))
@end lisp

O exemplo acima corresponde ao que as opções de transformação de pacote
@option{--with-version} ou @option{--with-source} fazem. Essencialmente,
@code{hello-2.2} preserva todos os campos de @code{hello}, exceto
@code{version} e @code{source}, que ele substitui. Observe que a variável
@code{hello} original ainda está lá, no módulo @code{(gnu packages base)},
inalterada. Quando você define um pacote personalizado como este, você está
realmente @emph{adicionando} uma nova definição de pacote; a original
permanece disponível.

Você pode também definir variantes com um conjunto diferente de dependências
do que o pacote original. Por exemplo, o pacote padrão @code{gdb} depende de
@code{guile}, mas como essa é uma dependência opcional, você pode definir
uma variante que remova essa dependência assim:

@lisp
(use-modules (gnu packages gdb))   ;para 'gdb'

(define gdb-sans-guile
  (package
    (inherit gdb)
    (inputs (modify-inputs (package-inputs gdb)
              (delete "guile")))))
@end lisp

O formulário @code{modify-inputs} acima remove o pacote @code{"guile"} do
campo @code{inputs} de @code{gdb}. A macro @code{modify-inputs} é um
auxiliar que pode ser útil sempre que você quiser remover, adicionar ou
substituir entradas de pacote.

@defmac modify-inputs entradas cláusulas
Modifique as entradas do pacote fornecido, conforme retornado por
@code{package-inputs} & co., de acordo com as cláusulas fornecidas. Cada
cláusula deve ter uma das seguintes formas:

@table @code
@item (delete @var{nome}@dots{})
Exclua dos pacotes de entrada os @var{nome}s (strings) fornecidos.

@item (prepend @var{pacote}@dots{})
Adicione @var{pacote}s à frente da lista de entrada.

@item (append @var{pacote}@dots{})
Adicione @var{pacote}s ao final da lista de entrada.

@item (replace @var{nome} @var{substituição})
Substitua o pacote chamado @var{nome} por @var{substituição}.
@end table

O exemplo abaixo remove as entradas GMP e ACL do Coreutils e adiciona libcap
à frente da lista de entradas:

@lisp
(modify-inputs (package-inputs coreutils)
  (delete "gmp" "acl")
  (prepend libcap))
@end lisp

O exemplo abaixo substitui o pacote @code{guile} das entradas de
@code{guile-redis} por @code{guile-2.2}:

@lisp
(modify-inputs (package-inputs guile-redis)
  (replace "guile" guile-2.2))
@end lisp

The last type of clause is @code{append}, to add inputs at the back of the
list.
@end defmac

Em alguns casos, você pode achar útil escrever funções (``procedimentos'',
no jargão do Scheme) que retornam um pacote com base em alguns
parâmetros. Por exemplo, considere a biblioteca @code{luasocket} para a
linguagem de programação Lua. Queremos criar pacotes @code{luasocket} para
as principais versões do Lua. Uma maneira de fazer isso é definir um
procedimento que pega um pacote Lua e retorna um pacote @code{luasocket} que
depende dele:

@lisp
(define (make-lua-socket name lua)
  ;; Return a luasocket package built with LUA.
  (package
    (name name)
    (version "3.0")
    ;; several fields omitted
    (inputs (list lua))
    (synopsis "Socket library for Lua")))

(define-public lua5.1-socket
  (make-lua-socket "lua5.1-socket" lua-5.1))

(define-public lua5.2-socket
  (make-lua-socket "lua5.2-socket" lua-5.2))
@end lisp

Aqui definimos os pacotes @code{lua5.1-socket} e @code{lua5.2-socket}
chamando @code{make-lua-socket} com argumentos
diferentes. @xref{Procedures,,, guile, GNU Guile Reference Manual}, para
mais informações sobre procedimentos. Ter definições públicas de nível
superior para esses dois pacotes significa que eles podem ser referenciados
a partir da linha de comando (@pxref{Módulos de pacote}).

@cindex transformações de pacotes
Essas são variantes de pacote bem simples. Como uma conveniência, o módulo
@code{(guix transformations)} fornece uma interface de alto nível que mapeia
diretamente para as opções de transformação de pacote mais sofisticadas
(@pxref{Opções de transformação de pacote}):

@deffn {Procedimento} options->transformation opções
Retorna um procedimento que, quando passado um objeto para construção
(pacote, derivação, etc.), aplica as transformações especificadas por
@var{opções} e retorna os objetos resultantes. @var{opções} deve ser uma
lista de pares símbolo/string como:

@lisp
((with-branch . "guile-gcrypt=master")
 (without-tests . "libgcrypt"))
@end lisp

Cada símbolo nomeia uma transformação e a string correspondente é um
argumento para essa transformação.
@end deffn

Por exemplo, um manifesto equivalente a este comando:

@example
guix build guix \
  --with-branch=guile-gcrypt=master \
  --with-debug-info=zlib
@end example

@noindent
... ficaria assim:

@lisp
(use-modules (guix transformations))

(define transform
  ;; The package transformation procedure.
  (options->transformation
   '((with-branch . "guile-gcrypt=master")
     (with-debug-info . "zlib"))))

(packages->manifest
 (list (transform (specification->package "guix"))))
@end lisp

@cindex reescrita de entrada
@cindex reescrita de grafo de dependência
O procedimento @code{options->transformation} é conveniente, mas talvez
também não seja tão flexível quanto você gostaria. Como ele é implementado?
O leitor astuto provavelmente notou que a maioria das opções de
transformação de pacotes vai além das mudanças superficiais mostradas nos
primeiros exemplos desta seção: elas envolvem @dfn{reescrita de entrada},
por meio da qual o grafo de dependência de um pacote é reescrito pela
substituição de entradas específicas por outras.

A reescrita do grafo de dependência, para fins de troca de pacotes no grafo,
é o que o procedimento @code{package-input-rewriting} em @code{(guix
packages)} implementa.

@deffn {Procedimento} package-input-rewriting substituições [nome-da-reescrita] @
  [#:deep? #t] [#:recursive? #f]
Retorna um procedimento que, quando recebe um pacote, substitui suas
dependências diretas e indiretas, incluindo entradas implícitas quando
@var{deep?} é verdadeiro, de acordo com
@var{substituições}. @var{substituições} é uma lista de pares de pacotes; o
primeiro elemento de cada par é o pacote a ser substituído, e o segundo é a
substituição.

When @var{recursive?} is true, apply replacements to the right-hand sides of
@var{replacements} as well, recursively.

Opcionalmente, @var{nome-da-reescrita} é um procedimento de um argumento que
recebe o nome de um pacote e retorna seu novo nome após a reescrita.
@end deffn

@noindent
Considere este exemplo:

@lisp
(define libressl-instead-of-openssl
  ;; This is a procedure to replace OPENSSL by LIBRESSL,
  ;; recursively.
  (package-input-rewriting `((,openssl . ,libressl))))

(define git-with-libressl
  (libressl-instead-of-openssl git))
@end lisp

@noindent
Aqui, primeiro definimos um procedimento de reescrita que substitui
@var{openssl} por @var{libressl}. Então, o usamos para definir uma
@dfn{variante} do pacote @var{git} que usa @var{libressl} em vez de
@var{openssl}. É exatamente isso que a opção de linha de comando
@option{--with-input} faz (@pxref{Opções de transformação de pacote,
@option{--with-input}}).

A seguinte variante de @code{package-input-rewriting} pode corresponder a
pacotes a serem substituídos por nome em vez de identidade.

@deffn {Procedimento} package-input-rewriting/spec @var{substituições} @
  [#:deep? #t] [#:replace-hidden? #t]
Retorna um procedimento que, dado um pacote, aplica as @var{substituições}
fornecidas a todo o grafo do pacote, incluindo entradas implícitas, a menos
que @var{deep?} seja falso.

@var{replacements} is a list of spec/procedures pair; each spec is a package
specification such as @code{"gcc"} or @code{"guile@@2"}, and each procedure
takes a matching package and returns a replacement for that package.
Matching packages that have the @code{hidden?} property set are not replaced
unless @var{replace-hidden?} is set to true.
@end deffn

O exemplo acima poderia ser reescrito desta forma:

@lisp
(define libressl-instead-of-openssl
  ;; Substitua todos os pacotes chamados "openssl" por LibreSSL.
  (package-input-rewriting/spec `(("openssl" . ,(const libressl)))))
@end lisp

A principal diferença aqui é que, dessa vez, os pacotes são correspondidos
por spec e não por identidade. Em outras palavras, qualquer pacote no grafo
que seja chamado @code{openssl} será substituído.

Um procedimento mais genérico para reescrever um grafo de dependência de
pacote é @code{package-mapping}: ele suporta alterações arbitrárias em nós
no grafo.

@deffn {Procedimento} package-mapping proc [cortar?] [#:deep? #f]
Retorna um procedimento que, dado um pacote, aplica @var{proc} a todos os
pacotes dependentes e retorna o pacote resultante. O procedimento para a
recursão quando @var{cortar?} retorna true para um determinado
pacote. Quando @var{deep?} é true, @var{proc} é aplicado a entradas
implícitas também.
@end deffn

@quotation Dicas
Entender como uma variante realmente se parece pode ser difícil quando se
começa a combinar as ferramentas mostradas acima. Há várias maneiras de
inspecionar um pacote antes de tentar construí-lo que podem ser úteis:

@itemize
@item
Você pode inspecionar o pacote interativamente no REPL, por exemplo, para
visualizar suas entradas, o código de suas fases de construção ou seus
sinalizadores de configuração (@pxref{Usando Guix interativamente}).

@item
Ao reescrever dependências, @command{guix graph} geralmente pode ajudar a
visualizar as alterações feitas (@pxref{Invocando guix graph}).
@end itemize
@end quotation

@node Escrevendo manifestos
@section Escrevendo manifestos

@cindex manifesto
@cindex lista de materiais (manifestos)
Os comandos @command{guix} permitem que você especifique listas de pacotes
na linha de comando. Isso é conveniente, mas conforme a linha de comando se
torna mais longa e menos trivial, rapidamente se torna mais conveniente ter
essa lista de pacotes no que chamamos de @dfn{manifesto}. Um manifesto é
algum tipo de ``lista de materiais'' que define um conjunto de pacotes. Você
normalmente criaria um trecho de código que constrói o manifesto, o
armazenaria em um arquivo, digamos @file{manifest.scm}, e então passaria
esse arquivo para a opção @option{-m} (ou @option{--manifest}) que muitos
comandos @command{guix} suportam. Por exemplo, aqui está como um manifesto
para um conjunto de pacotes simples pode se parecer:

@lisp
;; Manifesto para três pacotes.
(specifications->manifest '("gcc-toolchain" "make" "git"))
@end lisp

Depois de ter esse manifesto, você pode passá-lo, por exemplo, para
@command{guix package} para instalar apenas esses três pacotes no seu perfil
(@pxref{profile-manifest, @option{-m} opção de @command{guix package}}):

@example
guix package -m manifest.scm
@end example

@noindent
... ou você pode passá-lo para @command{guix shell} (@pxref{shell-manifest,
@command{-m} opção de @command{guix shell}}) para gerar um ambiente efêmero:

@example
guix shell -m manifest.scm
@end example

@noindent
... ou você pode passá-lo para @command{guix pack} praticamente da mesma
forma (@pxref{pack-manifest, @option{-m} opção de @command{guix
pack}}). Você pode armazenar o manifesto sob controle de versão,
compartilhá-lo com outros para que eles possam facilmente configurar, etc.

Mas como você escreve seu primeiro manifesto? Para começar, talvez você
queira escrever um manifesto que espelhe o que você já tem em um perfil. Em
vez de começar do zero, @command{guix package} pode gerar um manifesto para
você (@pxref{export-manifest, @command{guix package --export-manifest}}):

@example
# Escreva em 'manifest.scm' um manifesto correspondente ao
# perfil padrão, ~/.guix-profile.
guix package --export-manifest > manifest.scm
@end example

Ou talvez você queira ``traduzir'' argumentos de linha de comando em um
manifesto. Nesse caso, @command{guix shell} pode ajudar
(@pxref{shell-export-manifest, @command{guix shell --export-manifest}}):

@example
# Write a manifest for the packages specified on the command line.
guix shell --export-manifest gcc-toolchain make git > manifest.scm
@end example

Em ambos os casos, a opção @option{--export-manifest} tenta arduamente gerar
um manifesto fiel; em particular, ela leva em consideração as opções de
transformação de pacotes (@pxref{Opções de transformação de pacote}).

@quotation Nota
Manifestos são @emph{simbólicos}: eles se referem a pacotes dos canais
@emph{atualmente em uso} (@pxref{Canais}). No exemplo acima,
@code{gcc-toolchain} pode se referir à versão 14 hoje, mas pode se referir à
versão 16 daqui a dois anos.

Se você quiser ``fixar'' seu ambiente de software em versões e variantes de
pacotes específicos, precisará de uma informação adicional: a lista de
revisões de canal em uso, conforme retornado por @command{guix
describe}. @xref{Replicando Guix}, para mais informações.
@end quotation

Depois de obter seu primeiro manifesto, talvez você queira
personalizá-lo. Como seu manifesto é código, agora você tem acesso a todas
as interfaces de programação Guix!

Vamos supor que você queira um manifesto para implantar uma variante
personalizada do GDB, o GNU Debugger, que não depende do Guile, junto com
outro pacote. Com base no exemplo visto na seção anterior (@pxref{Definindo variantes de pacote}), você pode escrever um manifesto seguindo estas linhas:

@lisp
(use-modules (guix packages)
             (gnu packages gdb)               ;para 'gdb'
             (gnu packages version-control))  ;para 'git'

;; Define a variant of GDB without a dependency on Guile.
(define gdb-sans-guile
  (package
    (inherit gdb)
    (inputs (modify-inputs (package-inputs gdb)
              (delete "guile")))))

;; Return a manifest containing that one package plus Git.
(packages->manifest (list gdb-sans-guile git))
@end lisp

Observe que neste exemplo, o manifesto se refere diretamente às variáveis
@code{gdb} e @code{git}, que são vinculadas a um objeto @code{package}
(@pxref{Referência do package}), em vez de chamar
@code{specifications->manifest} para procurar pacotes por nome, como fizemos
antes. O formulário @code{use-modules} no topo nos permite acessar a
interface do pacote principal (@pxref{Definindo pacotes}) e os módulos que
definem @code{gdb} e @code{git} (@pxref{Módulos de pacote}). Sem problemas,
estamos entrelaçando tudo isso — as possibilidades são infinitas, libere sua
criatividade!

O tipo de dados para manifestos, bem como procedimentos de suporte, são
definidos no módulo @code{(guix profiles)}, que está automaticamente
disponível para o código passado para @option{-m}. A referência segue.

@deftp {Tipo de dados} manifest
Data type representing a manifest.

Atualmente possui um campo:

@table @code
@item entries
Esta deve ser uma lista de registros @code{manifest-entry} --- veja abaixo.
@end table
@end deftp

@deftp {Tipo de dados} manifest-entry
Tipo de dado que representa uma entrada de manifesto. Uma entrada de
manifesto contém metadados essenciais: uma string de nome e versão, o objeto
(geralmente um pacote) para essa entrada, a saída desejada (@pxref{Pacotes com múltiplas saídas}) e uma série de informações opcionais detalhadas
abaixo.

Na maioria das vezes, você não construirá uma entrada de manifesto
diretamente; em vez disso, você passará um pacote para
@code{package->manifest-entry}, descrito abaixo. Em alguns casos incomuns,
no entanto, você pode querer criar entradas de manifesto para coisas que são
@emph{não} pacotes, como neste exemplo:

@lisp
;; Manually build a single manifest entry for a non-package object.
(let ((hello (program-file "hello" #~(display "Hi!"))))
  (manifest-entry
    (name "foo")
    (version "42")
    (item
     (computed-file "hello-directory"
                     #~(let ((bin (string-append #$output "/bin")))
                         (mkdir #$output) (mkdir bin)
                          (symlink #$hello
                                   (string-append bin "/hello")))))))
@end lisp

The available fields are the following:

@table @asis
@item @code{name}
@itemx @code{version}
Nome e sequência de versão para esta entrada.

@item @code{item}
Um pacote ou outro objeto tipo arquivo (@pxref{Expressões-G, objetos tipo
arquivo}).

@item @code{output} (padrão: @code{"out"})
Saída de @code{item} a ser usada, caso @code{item} tenha múltiplas saídas
(@pxref{Pacotes com múltiplas saídas}).

@item @code{dependencies} (padrão: @code{'()})
Lista de entradas de manifesto das quais esta entrada depende. Ao construir
um perfil, dependências são adicionadas ao perfil.

Normalmente, as entradas propagadas de um pacote (@pxref{Referência do package,
@code{propagated-inputs}}) acabam tendo uma entrada de manifesto
correspondente entre as dependências da própria entrada de manifesto do
pacote.

@item @code{search-paths} (padrão: @code{'()})
A lista de especificações de caminhos de pesquisa respeitadas por esta
entrada (@pxref{Caminhos de pesquisa}).

@item @code{properties} (padrão: @code{'()})
Lista de pares de símbolo/valor. Ao construir um perfil, essas propriedades
são serializadas.

Isso pode ser usado para adicionar metadados adicionais, por exemplo, as
transformações aplicadas a um pacote (@pxref{Opções de transformação de pacote}).

@item @code{parent} (padrão: @code{(delay #f)})
Uma promessa apontando para a entrada do manifesto ``pai''.

This is used as a hint to provide context when reporting an error related to
a manifest entry coming from a @code{dependencies} field.
@end table
@end deftp

@deffn {Procedure} concatenate-manifests lst
Concatenate the manifests listed in @var{lst} and return the resulting
manifest.
@end deffn

@c TODO: <manifest-pattern>, manifest-lookup, manifest-remove, etc.

@deffn {Procedure} package->manifest-entry package [output] [#:properties]
Return a manifest entry for the @var{output} of package @var{package}, where
@var{output} defaults to @code{"out"}, and with the given @var{properties}.
By default @var{properties} is the empty list or, if one or more package
transformations were applied to @var{package}, it is an association list
representing those transformations, suitable as an argument to
@code{options->transformation} (@pxref{Definindo variantes de pacote,
@code{options->transformation}}).

The code snippet below builds a manifest with an entry for the default
output and the @code{send-email} output of the @code{git} package:

@lisp
(use-modules (gnu packages version-control))

(manifest (list (package->manifest-entry git)
                (package->manifest-entry git "send-email")))
@end lisp
@end deffn

@deffn {Procedure} packages->manifest packages
Return a list of manifest entries, one for each item listed in
@var{packages}.  Elements of @var{packages} can be either package objects or
package/string tuples denoting a specific output of a package.

Using this procedure, the manifest above may be rewritten more concisely:

@lisp
(use-modules (gnu packages version-control))

(packages->manifest (list git `(,git "send-email")))
@end lisp
@end deffn

@anchor{package-development-manifest}
@deffn {Procedure} package->development-manifest package [system] [#:target]
Return a manifest for the @dfn{development inputs} of @var{package} for
@var{system}, optionally when cross-compiling to @var{target}.  Development
inputs include both explicit and implicit inputs of @var{package}.

Like the @option{-D} option of @command{guix shell}
(@pxref{shell-development-option, @command{guix shell -D}}), the resulting
manifest describes the environment in which one can develop @var{package}.
For example, suppose you're willing to set up a development environment for
Inkscape, with the addition of Git for version control; you can describe
that ``bill of materials'' with the following manifest:

@lisp
(use-modules (gnu packages inkscape)          ;for 'inkscape'
             (gnu packages version-control))  ;for 'git'

(concatenate-manifests
 (list (package->development-manifest inkscape)
       (packages->manifest (list git))))
@end lisp

In this example, the development manifest that
@code{package->development-manifest} returns includes the compiler (GCC),
the many supporting libraries (Boost, GLib, GTK, etc.), and a couple of
additional development tools---these are the dependencies @command{guix show
inkscape} lists.
@end deffn

@c TODO: Move (gnu packages) interface to a section of its own.

Last, the @code{(gnu packages)} module provides higher-level facilities to
build manifests.  In particular, it lets you look up packages by name---see
below.

@deffn {Procedure} specifications->manifest specs
Given @var{specs}, a list of specifications such as @code{"emacs@@25.2"} or
@code{"guile:debug"}, return a manifest.  Specs have the format that
command-line tools such as @command{guix install} and @command{guix package}
understand (@pxref{Invocando guix package}).

As an example, it lets you rewrite the Git manifest that we saw earlier like
this:

@lisp
(specifications->manifest '("git" "git:send-email"))
@end lisp

Notice that we do not need to worry about @code{use-modules}, importing the
right set of modules, and referring to the right variables.  Instead, we
directly refer to packages in the same way as on the command line, which can
often be more convenient.
@end deffn

@c TODO: specifications->package, etc.


@node Sistemas de compilação
@section Sistemas de compilação

@cindex sistema de compilação
Each package definition specifies a @dfn{build system} and arguments for
that build system (@pxref{Definindo pacotes}).  This @code{build-system}
field represents the build procedure of the package, as well as implicit
dependencies of that build procedure.

Build systems are @code{<build-system>} objects.  The interface to create
and manipulate them is provided by the @code{(guix build-system)} module,
and actual build systems are exported by specific modules.

@cindex bag (low-level package representation)
Under the hood, build systems first compile package objects to @dfn{bags}.
A @dfn{bag} is like a package, but with less ornamentation---in other words,
a bag is a lower-level representation of a package, which includes all the
inputs of that package, including some that were implicitly added by the
build system.  This intermediate representation is then compiled to a
derivation (@pxref{Derivações}).  The @code{package-with-c-toolchain} is an
example of a way to change the implicit inputs that a package's build system
pulls in (@pxref{Referência do package, @code{package-with-c-toolchain}}).

Build systems accept an optional list of @dfn{arguments}.  In package
definitions, these are passed @i{via} the @code{arguments} field
(@pxref{Definindo pacotes}).  They are typically keyword arguments
(@pxref{Optional Arguments, keyword arguments in Guile,, guile, GNU Guile
Reference Manual}).  The value of these arguments is usually evaluated in
the @dfn{build stratum}---i.e., by a Guile process launched by the daemon
(@pxref{Derivações}).

O principal sistema de compilação é o @code{gnu-build-system}, que
implementa o processo padrão de compilação para o GNU e muitos outros
pacotes.  É providenciado pelo módulo @code{(guix build-system gnu)}.

@defvar gnu-build-system
@code{gnu-build-system} represents the GNU Build System, and variants
thereof (@pxref{Configuration, configuration and makefile conventions,,
standards, GNU Coding Standards}).

@cindex fases de construção
In a nutshell, packages using it are configured, built, and installed with
the usual @code{./configure && make && make check && make install} command
sequence.  In practice, a few additional steps are often needed.  All these
steps are split up in separate @dfn{phases}.  @xref{Fases de construção}, for more
info on build phases and ways to customize them.

In addition, this build system ensures that the ``standard'' environment for
GNU packages is available.  This includes tools such as GCC, libc,
Coreutils, Bash, Make, Diffutils, grep, and sed (see the @code{(guix
build-system gnu)} module for a complete list).  We call these the
@dfn{implicit inputs} of a package, because package definitions do not have
to mention them.

Esta sistema de compilação suporta um número de palavras-chave como
argumentos, os quais podems er passados @i{via} o campo @code{arguments} de
um pacote.  Veja alguns dos principais parâmetros:

@table @code
@item #:phases
This argument specifies build-side code that evaluates to an alist of build
phases.  @xref{Fases de construção}, for more information.

@item #:configure-flags
This is a list of flags (strings) passed to the @command{configure} script.
@xref{Definindo pacotes}, for an example.

@item #:make-flags
This list of strings contains flags passed as arguments to @command{make}
invocations in the @code{build}, @code{check}, and @code{install} phases.

@item #:out-of-source?
This Boolean, @code{#f} by default, indicates whether to run builds in a
build directory separate from the source tree.

When it is true, the @code{configure} phase creates a separate build
directory, changes to that directory, and runs the @code{configure} script
from there.  This is useful for packages that require it, such as
@code{glibc}.

@item #:tests?
This Boolean, @code{#t} by default, indicates whether the @code{check} phase
should run the package's test suite.

@item #:test-target
This string, @code{"check"} by default, gives the name of the makefile
target used by the @code{check} phase.

@item #:parallel-build?
@itemx #:parallel-tests?
These Boolean values specify whether to build, respectively run the test
suite, in parallel, with the @code{-j} flag of @command{make}.  When they
are true, @code{make} is passed @code{-j@var{n}}, where @var{n} is the
number specified as the @option{--cores} option of @command{guix-daemon} or
that of the @command{guix} client command (@pxref{Opções de compilação comuns,
@option{--cores}}).

@cindex RUNPATH, validation
@item #:validate-runpath?
This Boolean, @code{#t} by default, determines whether to ``validate'' the
@code{RUNPATH} of ELF binaries (@code{.so} shared libraries as well as
executables) previously installed by the @code{install} phase.
@xref{phase-validate-runpath, the @code{validate-runpath} phase}, for
details.

@item #:substituível?
This Boolean, @code{#t} by default, tells whether the package outputs should
be substitutable---i.e., whether users should be able to obtain substitutes
for them instead of building locally (@pxref{Substitutos}).

@item #:allowed-references
@itemx #:disallowed-references
When true, these arguments must be a list of dependencies that must not
appear among the references of the build results.  If, upon build
completion, some of these references are retained, the build process fails.

This is useful to ensure that a package does not erroneously keep a
reference to some of it build-time inputs, in cases where doing so would,
for example, unnecessarily increase its size (@pxref{Invocando guix size}).
@end table

Vários outros sistemas de compilação suportam tais argumentos em
palavras-chave.
@end defvar

Other @code{<build-system>} objects are defined to support other conventions
and tools used by free software packages.  They inherit most of
@code{gnu-build-system}, and differ mainly in the set of inputs implicitly
added to the build process, and in the list of phases executed.  Some of
these build systems are listed below.

@defvar agda-build-system
This variable is exported by @code{(guix build-system agda)}.  It implements
a build procedure for Agda libraries.

It adds @code{agda} to the set of inputs.  A different Agda can be specified
with the @code{#:agda} key.

The @code{#:plan} key is a list of cons cells @code{(@var{regexp}
. @var{parameters})}, where @var{regexp} is a regexp that should match the
@code{.agda} files to build, and @var{parameters} is an optional list of
parameters that will be passed to @code{agda} when type-checking it.

When the library uses Haskell to generate a file containing all imports, the
convenience @code{#:gnu-and-haskell?} can be set to @code{#t} to add
@code{ghc} and the standard inputs of @code{gnu-build-system} to the input
list.  You will still need to manually add a phase or tweak the
@code{'build} phase, as in the definition of @code{agda-stdlib}.

@end defvar

@defvar ant-build-system
This variable is exported by @code{(guix build-system ant)}.  It implements
the build procedure for Java packages that can be built with
@url{https://ant.apache.org/, Ant build tool}.

It adds both @code{ant} and the @dfn{Java Development Kit} (JDK) as provided
by the @code{icedtea} package to the set of inputs.  Different packages can
be specified with the @code{#:ant} and @code{#:jdk} parameters,
respectively.

When the original package does not provide a suitable Ant build file, the
parameter @code{#:jar-name} can be used to generate a minimal Ant build file
@file{build.xml} with tasks to build the specified jar archive.  In this
case the parameter @code{#:source-dir} can be used to specify the source
sub-directory, defaulting to ``src''.

The @code{#:main-class} parameter can be used with the minimal ant buildfile
to specify the main class of the resulting jar.  This makes the jar file
executable.  The @code{#:test-include} parameter can be used to specify the
list of junit tests to run.  It defaults to @code{(list "**/*Test.java")}.
The @code{#:test-exclude} can be used to disable some tests.  It defaults to
@code{(list "**/Abstract*.java")}, because abstract classes cannot be run as
tests.

The parameter @code{#:build-target} can be used to specify the Ant task that
should be run during the @code{build} phase.  By default the ``jar'' task
will be run.

@end defvar

@defvar android-ndk-build-system
@cindex Android distribution
@cindex Android NDK build system
This variable is exported by @code{(guix build-system android-ndk)}.  It
implements a build procedure for Android NDK (native development kit)
packages using a Guix-specific build process.

O sistema de compilação presume que os pacotes instalam seu prório arquivo
(header) de interface pública no subdiretório @file{include} da saída
@code{out} bem como suas próprias bibliotecas no subdirectório @file{lib} da
saída @code{out}.

Também é presumido que a união de todas as dependências de um pacote não
possuem arquivos conflitantes.

For the time being, cross-compilation is not supported - so right now the
libraries and header files are assumed to be host tools.

@end defvar

@defvar asdf-build-system/source
@defvarx asdf-build-system/sbcl
@defvarx asdf-build-system/ecl
@defvarx asdf-build-system/clasp

These variables, exported by @code{(guix build-system asdf)}, implement
build procedures for Common Lisp packages using
@url{https://common-lisp.net/project/asdf/, ``ASDF''}.  ASDF is a system
definition facility for Common Lisp programs and libraries.

The @code{asdf-build-system/source} system installs the packages in source
form, and can be loaded using any common lisp implementation, via ASDF@.
The others, such as @code{asdf-build-system/sbcl}, install binary systems in
the format which a particular implementation understands.  These build
systems can also be used to produce executable programs, or lisp images
which contain a set of packages pre-loaded.

The build system uses naming conventions.  For binary packages, the package
name should be prefixed with the lisp implementation, such as @code{sbcl-}
for @code{asdf-build-system/sbcl}.

Additionally, the corresponding source package should be labeled using the
same convention as Python packages (@pxref{Módulos Python}), using the
@code{cl-} prefix.

In order to create executable programs and images, the build-side procedures
@code{build-program} and @code{build-image} can be used.  They should be
called in a build phase after the @code{create-asdf-configuration} phase, so
that the system which was just built can be used within the resulting
image.  @code{build-program} requires a list of Common Lisp expressions to
be passed as the @code{#:entry-program} argument.

By default, all the @file{.asd} files present in the sources are read to
find system definitions.  The @code{#:asd-files} parameter can be used to
specify the list of @file{.asd} files to read.  Furthermore, if the package
defines a system for its tests in a separate file, it will be loaded before
the tests are run if it is specified by the @code{#:test-asd-file}
parameter.  If it is not set, the files @code{<system>-tests.asd},
@code{<system>-test.asd}, @code{tests.asd}, and @code{test.asd} will be
tried if they exist.

If for some reason the package must be named in a different way than the
naming conventions suggest, or if several systems must be compiled, the
@code{#:asd-systems} parameter can be used to specify the list of system
names.

@end defvar

@defvar cargo-build-system
@cindex Rust programming language
@cindex Cargo (Rust build system)
This variable is exported by @code{(guix build-system cargo)}.  It supports
builds of packages using Cargo, the build tool of the
@uref{https://www.rust-lang.org, Rust programming language}.

@quotation Aviso de descontinuação
Parameters @code{#:cargo-inputs} and @code{#:cargo-development-inputs},
previously used for specifying source inputs, are deprecated.  Their support
will be removed after Dec. 31, 2026.
@end quotation

It adds @code{rust} and @code{rust:cargo} to the set of inputs.  A different
Rust package can be specified with the @code{#:rust} parameter.

In its @code{unpack-rust-crates}, @code{configure} and
@code{patch-cargo-checksums} phases, this build system will make any source
inputs available to Cargo.  It will also remove an included
@code{Cargo.lock} file to be recreated by @command{cargo} during the
@code{build} phase.  The @code{package} phase will run @command{cargo
package} to create a source crate for future use.  The @code{install} phase
installs the binaries defined by the crate.  Unless @code{install-source?
#f} is defined it will also install a source crate repository of itself and
unpacked sources, to ease in future hacking on Rust packages.

This build system supports
@url{https://doc.rust-lang.org/cargo/reference/workspaces.html, Cargo
workspaces}.  Parameter @code{#:cargo-package-crates} (default: @code{''()})
allows specifying names of library crates to package in the @code{package}
phase.  Specified crates are packaged from left to right, in case there's
dependency among them.  For example, specifying @code{''("pcre2-sys"
"pcre2")} will package @code{"pcre2-sys"} first and then @code{"pcre2"}.
Parameter @code{#:cargo-install-paths} (default: @code{''()}) allows
specifying paths of binary crates to install in the @code{install} phase,
@code{''("crates/atuin")}, for example.

@xref{Rust Crates}, for packaging guidelines.
@end defvar

@defvar chicken-build-system
This variable is exported by @code{(guix build-system chicken)}.  It builds
@uref{https://call-cc.org/, CHICKEN Scheme} modules, also called ``eggs'' or
``extensions''.  CHICKEN generates C source code, which then gets compiled
by a C compiler, in this case GCC.

This build system adds @code{chicken} to the package inputs, as well as the
packages of @code{gnu-build-system}.

The build system can't (yet) deduce the egg's name automatically, so just
like with @code{go-build-system} and its @code{#:import-path}, you should
define @code{#:egg-name} in the package's @code{arguments} field.

For example, if you are packaging the @code{srfi-1} egg:

@lisp
(arguments '(#:egg-name "srfi-1"))
@end lisp

Egg dependencies must be defined in @code{propagated-inputs}, not
@code{inputs} because CHICKEN doesn't embed absolute references in compiled
eggs.  Test dependencies should go to @code{native-inputs}, as usual.
@end defvar

@defvar copy-build-system
This variable is exported by @code{(guix build-system copy)}.  It supports
builds of simple packages that don't require much compiling, mostly just
moving files around.

It adds much of the @code{gnu-build-system} packages to the set of inputs.
Because of this, the @code{copy-build-system} does not require all the
boilerplate code often needed for the @code{trivial-build-system}.

To further simplify the file installation process, an @code{#:install-plan}
argument is exposed to let the packager specify which files go where.  The
install plan is a list of @code{(@var{source} @var{target}
[@var{filters}])}.  @var{filters} are optional.

@itemize
@item When @var{source} matches a file or directory without trailing slash, install it to @var{target}.
@itemize
@item If @var{target} has a trailing slash, install @var{source} basename beneath @var{target}.
@item Otherwise install @var{source} as @var{target}.
@end itemize

@item When @var{source} is a directory with a trailing slash, or when @var{filters} are used,
the trailing slash of @var{target} is implied with the same meaning as
above.
@itemize
@item Without @var{filters}, install the full @var{source} @emph{content} to @var{target}.
@item With @var{filters} among @code{#:include}, @code{#:include-regexp}, @code{#:exclude},
@code{#:exclude-regexp}, only select files are installed depending on the
filters.  Each filters is specified by a list of strings.
@itemize
@item With @code{#:include}, install all the files which the path suffix matches
at least one of the elements in the given list.
@item With @code{#:include-regexp}, install all the files which the
subpaths match at least one of the regular expressions in the given list.
@item The @code{#:exclude} and @code{#:exclude-regexp} filters
are the complement of their inclusion counterpart.  Without @code{#:include}
flags, install all files but those matching the exclusion filters.  If both
inclusions and exclusions are specified, the exclusions are done on top of
the inclusions.
@end itemize
@item When a package has multiple outputs, the @code{#:output} argument
can be used to specify which output label the files should be installed to.
@end itemize
In all cases, the paths relative to @var{source} are preserved within
@var{target}.
@end itemize

Exemplos:

@itemize
@item @code{("foo/bar" "share/my-app/")}: Install @file{bar} to @file{share/my-app/bar}.
@item @code{("foo/bar" "share/my-app/baz")}: Install @file{bar} to @file{share/my-app/baz}.
@item @code{("foo/" "share/my-app")}: Install the content of @file{foo} inside @file{share/my-app},
e.g., install @file{foo/sub/file} to @file{share/my-app/sub/file}.
@item @code{("foo/" "share/my-app" #:include ("sub/file"))}: Install only @file{foo/sub/file} to
@file{share/my-app/sub/file}.
@item @code{("foo/sub" "share/my-app" #:include ("file"))}: Install @file{foo/sub/file} to
@file{share/my-app/file}.
@item @code{("foo/doc" "share/my-app/doc" #:output "doc")}: Install
@file{"foo/doc"} to @file{"share/my-app/doc"} within the @code{"doc"}
output.
@end itemize
@end defvar

@defvar vim-build-system
This variable is exported by @code{(guix build-system vim)}.  It is an
extension of the @code{copy-build-system}, installing Vim and Neovim plugins
into locations where these two text editors know to find their plugins,
using their packpaths.

Packages which are prefixed with @code{vim-} will be installed in Vim's
packpath, while those prefixed with @code{neovim-} will be installed in
Neovim's packpath.  If there is a @code{doc} directory with the plugin then
helptags will be generated automatically.

There are a couple of keywords added with the @code{vim-build-system}:
@itemize
@item With @code{plugin-name} it is possible to set the name of the plugin.
While by default this is set to the name and version of the package, it is
often more helpful to set this to name which the upstream author calls their
plugin.  This is the name used for @command{:packadd} from inside Vim.
@item With @code{install-plan} it is possible to augment the built-in
install-plan of the @code{vim-build-system}.  This is particularly helpful
if you have files which should be installed in other locations.  For more
information about using the @code{install-plan}, see the
@code{copy-build-system} (@pxref{Sistemas de compilação, @code{copy-build-system}}).
@item With @code{#:vim} it is possible to add this package to Vim's packpath,
in addition to if it is added automatically because of the @code{vim-}
prefix in the package's name.
@item With @code{#:neovim} it is possible to add this package to Neovim's
packpath, in addition to if it is added automatically because of the
@code{neovim-} prefix in the package's name.
@item With @code{#:mode} it is possible to adjust the path which the plugin is
installed into.  By default the plugin is installed into @code{start} and
other options are available, including @code{opt}.  Adding a plugin into
@code{opt} will mean you will need to run, for example, @command{:packadd
foo} to load the @code{foo} plugin from inside of Vim.
@end itemize
@end defvar

@cindex Clojure (programming language)
@cindex simple Clojure build system
@defvar clojure-build-system
This variable is exported by @code{(guix build-system clojure)}.  It
implements a simple build procedure for @uref{https://clojure.org/, Clojure}
packages using plain old @code{compile} in Clojure.  Cross-compilation is
not supported yet.

It adds @code{clojure}, @code{icedtea} and @code{zip} to the set of inputs.
Different packages can be specified with the @code{#:clojure}, @code{#:jdk}
and @code{#:zip} parameters, respectively.

A list of source directories, test directories and jar names can be
specified with the @code{#:source-dirs}, @code{#:test-dirs} and
@code{#:jar-names} parameters, respectively.  Compile directory and main
class can be specified with the @code{#:compile-dir} and @code{#:main-class}
parameters, respectively.  Other parameters are documented below.

This build system is an extension of @code{ant-build-system}, but with the
following phases changed:

@table @code

@item build
This phase calls @code{compile} in Clojure to compile source files and runs
@command{jar} to create jars from both source files and compiled files
according to the include list and exclude list specified in
@code{#:aot-include} and @code{#:aot-exclude}, respectively.  The exclude
list has priority over the include list.  These lists consist of symbols
representing Clojure libraries or the special keyword @code{#:all}
representing all Clojure libraries found under the source directories.  The
parameter @code{#:omit-source?} decides if source should be included into
the jars.

@item marcar
This phase runs tests according to the include list and exclude list
specified in @code{#:test-include} and @code{#:test-exclude}, respectively.
Their meanings are analogous to that of @code{#:aot-include} and
@code{#:aot-exclude}, except that the special keyword @code{#:all} now
stands for all Clojure libraries found under the test directories.  The
parameter @code{#:tests?} decides if tests should be run.

@item install
This phase installs all jars built previously.
@end table

Apart from the above, this build system also contains an additional phase:

@table @code

@item install-doc
This phase installs all top-level files with base name matching
@code{%doc-regex}.  A different regex can be specified with the
@code{#:doc-regex} parameter.  All files (recursively) inside the
documentation directories specified in @code{#:doc-dirs} are installed as
well.
@end table
@end defvar

@defvar cmake-build-system
This variable is exported by @code{(guix build-system cmake)}.  It
implements the build procedure for packages using the
@url{https://www.cmake.org, CMake build tool}.

This build system adds the following keyword parameters to the ones defined
by @code{gnu-build-system}:

@table @code
@item #:cmake
The @code{cmake} package is added to the set of inputs. Which package is
used can be specified with the @code{#:cmake} parameter.

@item #:build-type
The @code{#:build-type} parameter specifies in abstract terms the flags
passed to the compiler; it defaults to @code{"RelWithDebInfo"} (short for
``release mode with debugging information''), which roughly means that code
is compiled with @code{-O2 -g}, as is the case for Autoconf-based packages
by default.

@item #:generator
This parameter specifies the
@url{https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html,
CMake generator} responsible for writing the input files for the native
build system.

@item #:test-exclude
Tests matching this regular expression are excluded from testing by
@url{https://cmake.org/cmake/help/latest/manual/ctest.1.html, ctest}.

@item #:test-repeat-until-pass?
Directs @url{https://cmake.org/cmake/help/latest/manual/ctest.1.html, ctest}
to
@url{https://cmake.org/cmake/help/latest/manual/ctest.1.html#cmdoption-ctest-repeat,
repeat} failed tests up to @code{#:test-repeat-until-pass-count} times and
is enabled by default.

@item #:test-repeat-until-pass-count
When @code{#:test-repeat-until-pass?} is enabled this parameter sets the
maximum number of failures for each test. The default is @code{5}.
@end table
@end defvar

@defvar composer-build-system
This variable is exported by @code{(guix build-system composer)}.  It
implements the build procedure for packages using
@url{https://getcomposer.org/, Composer}, the PHP package manager.

It automatically adds the @code{php} package to the set of inputs.  Which
package is used can be specified with the @code{#:php} parameter.

The @code{#:test-target} parameter is used to control which script is run
for the tests.  By default, the @code{test} script is run if it exists.  If
the script does not exist, the build system will run @code{phpunit} from the
source directory, assuming there is a @file{phpunit.xml} file.
@end defvar

@defvar dune-build-system
This variable is exported by @code{(guix build-system dune)}.  It supports
builds of packages using @uref{https://dune.build/, Dune}, a build tool for
the OCaml programming language.  It is implemented as an extension of the
@code{ocaml-build-system} which is described below.  As such, the
@code{#:ocaml} and @code{#:findlib} parameters can be passed to this build
system.

It automatically adds the @code{dune} package to the set of inputs.  Which
package is used can be specified with the @code{#:dune} parameter.

There is no @code{configure} phase because dune packages typically don't
need to be configured.  The @code{#:build-flags} parameter is taken as a
list of flags passed to the @code{dune} command during the build.

The @code{#:jbuild?} parameter can be passed to use the @code{jbuild}
command instead of the more recent @code{dune} command while building a
package.  Its default value is @code{#f}.

The @code{#:package} parameter can be passed to specify a package name,
which is useful when a package contains multiple packages and you want to
build only one of them.  This is equivalent to passing the @code{-p}
argument to @code{dune}.

@end defvar

@defvar elm-build-system
This variable is exported by @code{(guix build-system elm)}.  It implements
a build procedure for @url{https://elm-lang.org, Elm} packages similar to
@samp{elm install}.

The build system adds an Elm compiler package to the set of inputs.  The
default compiler package (currently @code{elm-sans-reactor}) can be
overridden using the @code{#:elm} argument.  Additionally, Elm packages
needed by the build system itself are added as implicit inputs if they are
not already present: to suppress this behavior, use the
@code{#:implicit-elm-package-inputs?} argument, which is primarily useful
for bootstrapping.

The @code{"dependencies"} and @code{"test-dependencies"} in an Elm package's
@file{elm.json} file correspond to @code{propagated-inputs} and
@code{inputs}, respectively.

Elm requires a particular structure for package names: @pxref{Pacotes Elm}
for more details, including utilities provided by @code{(guix build-system
elm)}.

There are currently a few noteworthy limitations to @code{elm-build-system}:

@itemize
@item
The build system is focused on @dfn{packages} in the Elm sense of the word:
Elm @dfn{projects} which declare @code{@{ "type": "package" @}} in their
@file{elm.json} files.  Using @code{elm-build-system} to build Elm
@dfn{applications} (which declare @code{@{ "type": "application" @}}) is
possible, but requires ad-hoc modifications to the build phases.  For
examples, see the definitions of the @code{elm-todomvc} example application
and the @code{elm} package itself (because the front-end for the @samp{elm
reactor} command is an Elm application).

@item
Elm supports multiple versions of a package coexisting simultaneously under
@env{ELM_HOME}, but this does not yet work well with
@code{elm-build-system}.  This limitation primarily affects Elm
applications, because they specify exact versions for their dependencies,
whereas Elm packages specify supported version ranges.  As a workaround, the
example applications mentioned above use the
@code{patch-application-dependencies} procedure provided by @code{(guix
build elm-build-system)} to rewrite their @file{elm.json} files to refer to
the package versions actually present in the build environment.
Alternatively, Guix package transformations (@pxref{Definindo variantes de pacote}) could be used to rewrite an application's entire dependency
graph.

@item
We are not yet able to run tests for Elm projects because neither
@url{https://github.com/mpizenberg/elm-test-rs, @command{elm-test-rs}} nor
the Node.js-based @url{https://github.com/rtfeldman/node-test-runner,
@command{elm-test}} runner has been packaged for Guix yet.
@end itemize
@end defvar

@defvar go-build-system
This variable is exported by @code{(guix build-system go)}.  It implements a
build procedure for Go packages using the standard
@url{https://golang.org/cmd/go/#hdr-Compile_packages_and_dependencies, Go
build mechanisms}.

The user is expected to provide a value for the key @code{#:import-path}
and, in some cases, @code{#:unpack-path}.  The
@url{https://golang.org/doc/code.html#ImportPaths, import path} corresponds
to the file system path expected by the package's build scripts and any
referring packages, and provides a unique way to refer to a Go package.  It
is typically based on a combination of the package source code's remote URI
and file system hierarchy structure.  In some cases, you will need to unpack
the package's source code to a different directory structure than the one
indicated by the import path, and @code{#:unpack-path} should be used in
such cases.

Packages that provide Go libraries should install their source code into the
built output.  The key @code{#:install-source?}, which defaults to
@code{#t}, controls whether or not the source code is installed.  It can be
set to @code{#f} for packages that only provide executable files.

Packages can be cross-built, and if a specific architecture or operating
system is desired then the keywords @code{#:goarch} and @code{#:goos} can be
used to force the package to be built for that architecture and operating
system.  The combinations known to Go can be found
@url{https://golang.org/doc/install/source#environment, in their
documentation}.

The key @code{#:go} can be used to specify the Go compiler package with
which to build the package.

The phase @code{check} provides a wrapper for @code{go test} which builds a
test binary (or multiple binaries), vets the code and then runs the test
binary.  Build, test and test binary flags can be provided as
@code{#:test-flags} parameter, default is @code{'()}.  See @code{go help
test} and @code{go help testflag} for more details.

The key @code{#:embed-files}, default is @code{'()}, provides a list of
future embedded files or regexps matching files.  They will be copied to
build directory after @code{unpack} phase.  See
@url{https://pkg.go.dev/embed} for more details.

@end defvar

@defvar glib-or-gtk-build-system
This variable is exported by @code{(guix build-system glib-or-gtk)}.  It is
intended for use with packages making use of GLib or GTK+.

This build system adds the following two phases to the ones defined by
@code{gnu-build-system}:

@table @code
@item glib-or-gtk-wrap
The phase @code{glib-or-gtk-wrap} ensures that programs in @file{bin/} are
able to find GLib ``schemas'' and
@uref{https://developer.gnome.org/gtk3/stable/gtk-running.html, GTK+
modules}.  This is achieved by wrapping the programs in launch scripts that
appropriately set the @env{XDG_DATA_DIRS} and @env{GTK_PATH} environment
variables.

It is possible to exclude specific package outputs from that wrapping
process by listing their names in the
@code{#:glib-or-gtk-wrap-excluded-outputs} parameter.  This is useful when
an output is known not to contain any GLib or GTK+ binaries, and where
wrapping would gratuitously add a dependency of that output on GLib and
GTK+.

@item glib-or-gtk-compile-schemas
The phase @code{glib-or-gtk-compile-schemas} makes sure that all
@uref{https://developer.gnome.org/gio/stable/glib-compile-schemas.html,
GSettings schemas} of GLib are compiled.  Compilation is performed by the
@command{glib-compile-schemas} program.  It is provided by the package
@code{glib:bin} which is automatically imported by the build system.  The
@code{glib} package providing @command{glib-compile-schemas} can be
specified with the @code{#:glib} parameter.
@end table

Both phases are executed after the @code{install} phase.
@end defvar

@defvar guile-build-system
This build system is for Guile packages that consist exclusively of Scheme
code and that are so lean that they don't even have a makefile, let alone a
@file{configure} script.  It compiles Scheme code using @command{guild
compile} (@pxref{Compilation,,, guile, GNU Guile Reference Manual}) and
installs the @file{.scm} and @file{.go} files in the right place.  It also
installs documentation.

This build system supports cross-compilation by using the @option{--target}
option of @samp{guild compile}.

Packages built with @code{guile-build-system} must provide a Guile package
in their @code{native-inputs} field.
@end defvar

@defvar julia-build-system
This variable is exported by @code{(guix build-system julia)}.  It
implements the build procedure used by @uref{https://julialang.org/, julia}
packages, which essentially is similar to running @samp{julia -e 'using Pkg;
Pkg.add(package)'} in an environment where @env{JULIA_LOAD_PATH} contains
the paths to all Julia package inputs.  Tests are run by calling
@code{/test/runtests.jl}.

The Julia package name and uuid is read from the file @file{Project.toml}.
These values can be overridden by passing the argument
@code{#:julia-package-name} (which must be correctly capitalized) or
@code{#:julia-package-uuid}.

Julia packages usually manage their binary dependencies via
@code{JLLWrappers.jl}, a Julia package that creates a module (named after
the wrapped library followed by @code{_jll.jl}.

To add the binary path @code{_jll.jl} packages, you need to patch the files
under @file{src/wrappers/}, replacing the call to the macro
@code{JLLWrappers.@@generate_wrapper_header}, adding as a second argument
containing the store path the binary.

As an example, in the MbedTLS Julia package, we add a build phase
(@pxref{Fases de construção}) to insert the absolute file name of the wrapped
MbedTLS package:

@lisp
(add-after 'unpack 'override-binary-path
  (lambda* (#:key inputs #:allow-other-keys)
    (for-each (lambda (wrapper)
                (substitute* wrapper
                  (("generate_wrapper_header.*")
                   (string-append
                    "generate_wrapper_header(\"MbedTLS\", \""
                    (assoc-ref inputs "mbedtls") "\")\n"))))
              ;; There's a Julia file for each platform, override them all.
              (find-files "src/wrappers/" "\\.jl$"))))
@end lisp

Some older packages that aren't using @file{Project.toml} yet, will require
this file to be created, too.  It is internally done if the arguments
@code{#:julia-package-name} and @code{#:julia-package-uuid} are provided.
@end defvar

@defvar maven-build-system
This variable is exported by @code{(guix build-system maven)}.  It
implements a build procedure for @uref{https://maven.apache.org, Maven}
packages.  Maven is a dependency and lifecycle management tool for Java.  A
user of Maven specifies dependencies and plugins in a @file{pom.xml} file
that Maven reads.  When Maven does not have one of the dependencies or
plugins in its repository, it will download them and use them to build the
package.

The maven build system ensures that maven will not try to download any
dependency by running in offline mode.  Maven will fail if a dependency is
missing.  Before running Maven, the @file{pom.xml} (and subprojects) are
modified to specify the version of dependencies and plugins that match the
versions available in the guix build environment.  Dependencies and plugins
must be installed in the fake maven repository at @file{lib/m2}, and are
symlinked into a proper repository before maven is run.  Maven is instructed
to use that repository for the build and installs built artifacts there.
Changed files are copied to the @file{lib/m2} directory of the package
output.

You can specify a @file{pom.xml} file with the @code{#:pom-file} argument,
or let the build system use the default @file{pom.xml} file in the sources.

In case you need to specify a dependency's version manually, you can use the
@code{#:local-packages} argument.  It takes an association list where the
key is the groupId of the package and its value is an association list where
the key is the artifactId of the package and its value is the version you
want to override in the @file{pom.xml}.

Some packages use dependencies or plugins that are not useful at runtime nor
at build time in Guix.  You can alter the @file{pom.xml} file to remove them
using the @code{#:exclude} argument.  Its value is an association list where
the key is the groupId of the plugin or dependency you want to remove, and
the value is a list of artifactId you want to remove.

You can override the default @code{jdk} and @code{maven} packages with the
corresponding argument, @code{#:jdk} and @code{#:maven}.

The @code{#:maven-plugins} argument is a list of maven plugins used during
the build, with the same format as the @code{inputs} fields of the package
declaration.  Its default value is @code{(default-maven-plugins)} which is
also exported.
@end defvar

@defvar minetest-mod-build-system
This variable is exported by @code{(guix build-system minetest)}.  It
implements a build procedure for @uref{https://www.minetest.net, Minetest}
mods, which consists of copying Lua code, images and other resources to the
location Minetest searches for mods.  The build system also minimises PNG
images and verifies that Minetest can load the mod without errors.
@end defvar

@defvar minify-build-system
This variable is exported by @code{(guix build-system minify)}.  It
implements a minification procedure for simple JavaScript packages.

It adds @code{uglify-js} to the set of inputs and uses it to compress all
JavaScript files in the @file{src} directory.  A different minifier package
can be specified with the @code{#:uglify-js} parameter, but it is expected
that the package writes the minified code to the standard output.

When the input JavaScript files are not all located in the @file{src}
directory, the parameter @code{#:javascript-files} can be used to specify a
list of file names to feed to the minifier.
@end defvar

@defvar mix-build-system
This is a variable exported by @code{guix build-system mix}.  It implements
the standard build procedure used by Elixr programs with
@url{https://hexdocs.pm/mix/Mix.html,Mix}, which consists of running
@command{mix compile}, thereby creating bytecode.

The API is similar to the @var{gnu-build-system}, with some specifics for
Elixir:
@itemize
@item
@code{#:tests?} is a boolean, @code{#true} by default, determining whether
tests for the current build have to be run or not.
@item
@code{#:test-flags} is a list of arguments append to the @command{mix test}
invocation.  It defaults to @code{'()}.
@item
@code{#:mix-exs}, changes the full path to the @code{mix.exs} file.  It
defaults to @code{"mix.exs"}.  Please refer to
@url{https://hexdocs.pm/mix/Mix.html#module-environment-variables,upstream}
documentation for more details.
@item
@code{#:mix-path}, appends extra code paths.  It defaults to @code{#f}.
Please refer to
@url{https://hexdocs.pm/mix/Mix.html#module-environment-variables,upstream}
documentation for more details.
@end itemize
@end defvar

@defvar mozilla-build-system
This variable is exported by @code{(guix build-system mozilla)}.  It sets
the @code{--target} and @code{--host} configuration flags to what software
developed by Mozilla expects -- due to historical reasons, Mozilla software
expects @code{--host} to be the system that is cross-compiled from and
@code{--target} to be the system that is cross-compiled to, contrary to the
standard Autotools conventions.
@end defvar

@defvar ocaml-build-system
This variable is exported by @code{(guix build-system ocaml)}.  It
implements a build procedure for @uref{https://ocaml.org, OCaml} packages,
which consists of choosing the correct set of commands to run for each
package.  OCaml packages can expect many different commands to be run.  This
build system will try some of them.

When the package has a @file{setup.ml} file present at the top-level, it
will run @code{ocaml setup.ml -configure}, @code{ocaml setup.ml -build} and
@code{ocaml setup.ml -install}.  The build system will assume that this file
was generated by @uref{http://oasis.forge.ocamlcore.org/, OASIS} and will
take care of setting the prefix and enabling tests if they are not
disabled.  You can pass configure and build flags with the
@code{#:configure-flags} and @code{#:build-flags}.  The @code{#:test-flags}
key can be passed to change the set of flags used to enable tests.  The
@code{#:use-make?} key can be used to bypass this system in the build and
install phases.

When the package has a @file{configure} file, it is assumed that it is a
hand-made configure script that requires a different argument format than in
the @code{gnu-build-system}.  You can add more flags with the
@code{#:configure-flags} key.

When the package has a @file{Makefile} file (or @code{#:use-make?} is
@code{#t}), it will be used and more flags can be passed to the build and
install phases with the @code{#:make-flags} key.

Finally, some packages do not have these files and use a somewhat standard
location for its build system.  In that case, the build system will run
@code{ocaml pkg/pkg.ml} or @code{ocaml pkg/build.ml} and take care of
providing the path to the required findlib module.  Additional flags can be
passed via the @code{#:build-flags} key.  Install is taken care of by
@command{opam-installer}.  In this case, the @code{opam} package must be
added to the @code{native-inputs} field of the package definition.

Note that most OCaml packages assume they will be installed in the same
directory as OCaml, which is not what we want in guix.  In particular, they
will install @file{.so} files in their module's directory, which is usually
fine because it is in the OCaml compiler directory.  In guix though, these
libraries cannot be found and we use @env{CAML_LD_LIBRARY_PATH}.  This
variable points to @file{lib/ocaml/site-lib/stubslibs} and this is where
@file{.so} libraries should be installed.
@end defvar

@defvar python-build-system
This variable is exported by @code{(guix build-system python)}.  It
implements the more or less standard build procedure used by Python
packages, which consists in running @code{python setup.py build} and then
@code{python setup.py install --prefix=/gnu/store/@dots{}}.

For packages that install stand-alone Python programs under @code{bin/}, it
takes care of wrapping these programs so that their @env{GUIX_PYTHONPATH}
environment variable points to all the Python libraries they depend on.

Which Python package is used to perform the build can be specified with the
@code{#:python} parameter.  This is a useful way to force a package to be
built for a specific version of the Python interpreter, which might be
necessary if the package is only compatible with a single interpreter
version.

By default guix calls @code{setup.py} under control of @code{setuptools},
much like @command{pip} does.  Some packages are not compatible with
setuptools (and pip), thus you can disable this by setting the
@code{#:use-setuptools?} parameter to @code{#f}.

If a @code{"python"} output is available, the package is installed into it
instead of the default @code{"out"} output. This is useful for packages that
include a Python package as only a part of the software, and thus want to
combine the phases of @code{python-build-system} with another build system.
Python bindings are a common usecase.
@end defvar

@defvar pyproject-build-system
This is a variable exported by @code{guix build-system pyproject}.  It is
based on @var{python-build-system}, and adds support for
@file{pyproject.toml} and @url{https://peps.python.org/pep-0517/, PEP 517}.
It also supports a variety of build backends and test frameworks.

The API is slightly different from @var{python-build-system}:
@itemize
@item
@code{#:use-setuptools?} and @code{#:test-target} is removed.
@item
@code{#:configure-flags} is changed. Instead of a list this option must be a
JSON object, whose interpretation depends on the build backend. For instance
the example from @url{https://peps.python.org/pep-0517/#config-settings,PEP
517} should be written as @code{'(@@ ("CC" "gcc") ("--global-option"
("--some-global-option")) ("--build-option" ("--build-option1"
"--build-option2")))}
@item
@code{#:backend-path} is added.  It defaults to @code{#false}, but when set
to a list it will be appended to Python’s search path and overrides the
definition in @file{pyproject.toml}.
@item
@code{#:build-backend} is added.  It defaults to @code{#false} and will try
to guess the appropriate backend based on @file{pyproject.toml}.
@item
@code{#:test-backend} is added.  It defaults to @code{#false} and will guess
an appropriate test backend based on what is available in package inputs.
@item
@code{#:test-flags} is added.  The default is @code{'()}.  These flags are
passed as arguments to the test command.  Note that flags for verbose output
is always enabled on supported backends.
@end itemize

It is considered ``experimental'' in that the implementation details are not
set in stone yet, however users are encouraged to try it for new Python
projects (even those using @file{setup.py}).  The API is subject to change,
but any breaking changes in the Guix channel will be dealt with.

Eventually this build system will be deprecated and merged back into
@var{python-build-system}, probably some time in 2024.
@end defvar

@defvar perl-build-system
This variable is exported by @code{(guix build-system perl)}.  It implements
the standard build procedure for Perl packages, which either consists in
running @code{perl Build.PL --prefix=/gnu/store/@dots{}}, followed by
@code{Build} and @code{Build install}; or in running @code{perl Makefile.PL
PREFIX=/gnu/store/@dots{}}, followed by @code{make} and @code{make install},
depending on which of @code{Build.PL} or @code{Makefile.PL} is present in
the package distribution.  Preference is given to the former if both
@code{Build.PL} and @code{Makefile.PL} exist in the package distribution.
This preference can be reversed by specifying @code{#t} for the
@code{#:make-maker?} parameter.

The initial @code{perl Makefile.PL} or @code{perl Build.PL} invocation
passes flags specified by the @code{#:make-maker-flags} or
@code{#:module-build-flags} parameter, respectively.

Which Perl package is used can be specified with @code{#:perl}.
@end defvar

@defvar renpy-build-system
This variable is exported by @code{(guix build-system renpy)}.  It
implements the more or less standard build procedure used by Ren'py games,
which consists of loading @code{#:game} once, thereby creating bytecode for
it.

It further creates a wrapper script in @code{bin/} and a desktop entry in
@code{share/applications}, both of which can be used to launch the game.

Which Ren'py package is used can be specified with @code{#:renpy}.  Games
can also be installed in outputs other than ``out'' by using
@code{#:output}.
@end defvar

@defvar qt-build-system
This variable is exported by @code{(guix build-system qt)}.  It is intended
for use with applications using Qt or KDE.

This build system adds the following two phases to the ones defined by
@code{cmake-build-system}:

@table @code
@item check-setup
The phase @code{check-setup} prepares the environment for running the checks
as commonly used by Qt test programs.  For now this only sets some
environment variables: @code{QT_QPA_PLATFORM=offscreen},
@code{DBUS_FATAL_WARNINGS=0} and @code{CTEST_OUTPUT_ON_FAILURE=1}.

This phase is added before the @code{check} phase.  It's a separate phase to
ease adjusting if necessary.

@item qt-wrap
The phase @code{qt-wrap} searches for Qt5 plugin paths, QML paths and some
XDG in the inputs and output.  In case some path is found, all programs in
the output's @file{bin/}, @file{sbin/}, @file{libexec/} and
@file{lib/libexec/} directories are wrapped in scripts defining the
necessary environment variables.

It is possible to exclude specific package outputs from that wrapping
process by listing their names in the @code{#:qt-wrap-excluded-outputs}
parameter.  This is useful when an output is known not to contain any Qt
binaries, and where wrapping would gratuitously add a dependency of that
output on Qt, KDE, or such.

This phase is added after the @code{install} phase.
@end table
@end defvar

@defvar r-build-system
This variable is exported by @code{(guix build-system r)}.  It implements
the build procedure used by @uref{https://r-project.org, R} packages, which
essentially is little more than running @samp{R CMD INSTALL
--library=/gnu/store/@dots{}} in an environment where @env{R_LIBS_SITE}
contains the paths to all R package inputs.  Tests are run after
installation using the R function @code{tools::testInstalledPackage}.
@end defvar

@defvar rakudo-build-system
This variable is exported by @code{(guix build-system rakudo)}.  It
implements the build procedure used by @uref{https://rakudo.org/, Rakudo}
for @uref{https://perl6.org/, Perl6} packages.  It installs the package to
@code{/gnu/store/@dots{}/NAME-VERSION/share/perl6} and installs the
binaries, library files and the resources, as well as wrap the files under
the @code{bin/} directory.  Tests can be skipped by passing @code{#f} to the
@code{tests?} parameter.

Which rakudo package is used can be specified with @code{rakudo}.  Which
perl6-tap-harness package used for the tests can be specified with
@code{#:prove6} or removed by passing @code{#f} to the @code{with-prove6?}
parameter.  Which perl6-zef package used for tests and installing can be
specified with @code{#:zef} or removed by passing @code{#f} to the
@code{with-zef?} parameter.
@end defvar

@defvar rebar-build-system
This variable is exported by @code{(guix build-system rebar)}.  It
implements a build procedure around @uref{https://rebar3.org,rebar3}, a
build system for programs written in the Erlang language.

It adds both @code{rebar3} and the @code{erlang} to the set of inputs.
Different packages can be specified with the @code{#:rebar} and
@code{#:erlang} parameters, respectively.

This build system is based on @code{gnu-build-system}, but with the
following phases changed:

@table @code

@item unpack
This phase, after unpacking the source like the @code{gnu-build-system}
does, checks for a file @code{contents.tar.gz} at the top-level of the
source.  If this file exists, it will be unpacked, too.  This eases handling
of package hosted at @uref{https://hex.pm/}, the Erlang and Elixir package
repository.

@item bootstrap
@item configure
There are no @code{bootstrap} and @code{configure} phase because erlang
packages typically don’t need to be configured.

@item build
This phase runs @code{rebar3 compile} with the flags listed in
@code{#:rebar-flags}.

@item marcar
Unless @code{#:tests? #f} is passed, this phase runs @code{rebar3 eunit}, or
some other target specified with @code{#:test-target}, with the flags listed
in @code{#:rebar-flags},

@item install
This installs the files created in the @i{default} profile, or some other
profile specified with @code{#:install-profile}.

@end table
@end defvar

@defvar texlive-build-system
Esta variável é exportada pelo @code{(guix build-system texlive)}.  É usado
para compilar os pacotes TeX no modo de lote com um moter especificado.  O
sistema de compilação configura a variável @env{TEXINPUTS} para encontrar
todos os arquivos de fonte TeX na entrada.

By default it tries to run @code{luatex} on all @file{.ins} files, and if it
fails to find any, on all @file{.dtx} files.  A different engine and format
can be specified with, respectively, the @code{#:tex-engine} and
@code{#:tex-format} arguments.  Different build targets can be specified
with the @code{#:build-targets} argument, which expects a list of file
names.

It also generates font metrics (i.e., @file{.tfm} files) out of Metafont
files whenever possible.  Likewise, it can also create TeX formats (i.e.,
@file{.fmt} files) listed in the @code{#:create-formats} argument, and
generate a symbolic link from @file{bin/} directory to any script located in
@file{texmf-dist/scripts/}, provided its file name is listed in
@code{#:link-scripts} argument.

The build system adds @code{texlive-bin} from @code{(gnu packages tex)} to
the native inputs.  It can be overridden with the @code{#:texlive-bin}
argument.

The package @code{texlive-latex-bin}, from the same module, contains most of
the tools for building TeX Live packages; for convenience, it is also added
by default to the native inputs.  However, this can be troublesome when
building a dependency of @code{texlive-latex-bin} itself.  In this
particular situation, the @code{#:texlive-latex-bin?} argument should be set
to @code{#f}.
@end defvar

@defvar ruby-build-system
This variable is exported by @code{(guix build-system ruby)}.  It implements
the RubyGems build procedure used by Ruby packages, which involves running
@code{gem build} followed by @code{gem install}.

The @code{source} field of a package that uses this build system typically
references a gem archive, since this is the format that Ruby developers use
when releasing their software.  The build system unpacks the gem archive,
potentially patches the source, runs the test suite, repackages the gem, and
installs it.  Additionally, directories and tarballs may be referenced to
allow building unreleased gems from Git or a traditional source release
tarball.

Which Ruby package is used can be specified with the @code{#:ruby}
parameter.  A list of additional flags to be passed to the @command{gem}
command can be specified with the @code{#:gem-flags} parameter.
@end defvar

@defvar waf-build-system
This variable is exported by @code{(guix build-system waf)}.  It implements
a build procedure around the @code{waf} script.  The common
phases---@code{configure}, @code{build}, and @code{install}---are
implemented by passing their names as arguments to the @code{waf} script.

The @code{waf} script is executed by the Python interpreter.  Which Python
package is used to run the script can be specified with the @code{#:python}
parameter.
@end defvar

@defvar zig-build-system
This variable is exported by @code{(guix build-system zig)}.  It implements
the build procedures for the @uref{https://ziglang.org/, Zig} build system
(@command{zig build} command).

Selecting this build system adds @code{zig} to the package inputs, in
addition to the packages of @code{gnu-build-system}.

This build system by default installs package source to output.  This
behavior can be disabled by setting @code{#:install-source?} parameter to
@code{#f}.

For packages that don't install anything and don't come with a test suite
(likely library packages to be used by other Zig packages), you can set
@code{#:skip-build?} parameter to @code{#t}, which skips @code{build} and
@code{check} phases.

The @code{configure} phase sets up environment for @command{zig build}.  You
need to add custom phases after it if you want to invoke @command{zig}.

The @code{#:zig-build-flags} parameter is a list of flags that are passed to
@command{zig build} in @code{build} phase.  The @code{#:zig-test-flags}
parameter is a list of flags that are passed to @command{zig build test} in
@code{check} phase.  The default compiler package can be overridden with the
@code{#:zig} parameter.

The optional @code{#:zig-release-type} parameter declares the type of
release.  Possible values are: @code{"safe"}, @code{"fast"}, or
@code{"small"}.  The default value is @code{#f}, which causes the release
flag to be omitted from the @code{zig} command and results in a
@code{"debug"} build.
@end defvar

@defvar scons-build-system
This variable is exported by @code{(guix build-system scons)}.  It
implements the build procedure used by the SCons software construction
tool.  This build system runs @code{scons} to build the package, @code{scons
test} to run tests, and then @code{scons install} to install the package.

Additional flags to be passed to @code{scons} can be specified with the
@code{#:scons-flags} parameter.  The default build and install targets can
be overridden with @code{#:build-targets} and @code{#:install-targets}
respectively.  The version of Python used to run SCons can be specified by
selecting the appropriate SCons package with the @code{#:scons} parameter.
@end defvar

@defvar hare-build-system
This variable is exported by @code{(guix build-system hare)}.  It implements
the Makefile build process typically used by Hare packages, removing the
@code{configure} phase used by @code{gnu-build-system} and modifying
existing phases to set the Hare architecture tag, module path, and package
install destinations appropriately.

This relies on the package's Makefile supporting, at minimum, the variables
@code{HAREFLAGS} and @code{THIRDPARTYDIR}.  Packages may set
@code{make-flags} to override or supplement these variables.

By default, Hare modules are installed to the @code{lib} output if it
exists, and all other files to the @code{bin} output. If an output does not
exist, the default @code{out} output is used instead. This behavior may be
overriden through the @code{#:binary-output} and @code{#:module-output}
keyword arguments.

@code{(guix build-system hare)} also provides utility definitions for
creating Hare packages.  The variable @code{%hare-supported-systems} is the
list of build targets currently supported by @code{hare}, for use in
@code{supported-systems} (@pxref{Referência do package}).  The procedure
@code{target->hare-arch} may be used to get the Hare architecture tag for a
given (supported) Guix target or system.
@end defvar

@defvar haskell-build-system
This variable is exported by @code{(guix build-system haskell)}.  It
implements the Cabal build procedure used by Haskell packages, which
involves running @code{runhaskell Setup.hs configure
--prefix=/gnu/store/@dots{}} and @code{runhaskell Setup.hs build}.  Instead
of installing the package by running @code{runhaskell Setup.hs install}, to
avoid trying to register libraries in the read-only compiler store
directory, the build system uses @code{runhaskell Setup.hs copy}, followed
by @code{runhaskell Setup.hs register}.  In addition, the build system
generates the package documentation by running @code{runhaskell Setup.hs
haddock}, unless @code{#:haddock? #f} is passed.  Optional Haddock
parameters can be passed with the help of the @code{#:haddock-flags}
parameter.  If the file @code{Setup.hs} is not found, the build system looks
for @code{Setup.lhs} instead.

Which Haskell compiler is used can be specified with the @code{#:haskell}
parameter which defaults to @code{ghc}.
@end defvar

@defvar dub-build-system
This variable is exported by @code{(guix build-system dub)}.  It implements
the Dub build procedure used by D packages, which involves running @code{dub
build} and @code{dub run}.  Installation is done by copying the files
manually.

Which D compiler is used can be specified with the @code{#:ldc} parameter
which defaults to @code{ldc}.
@end defvar

@anchor{emacs-build-system}
@defvar emacs-build-system
This variable is exported by @code{(guix build-system emacs)}.  It
implements an installation procedure similar to the packaging system of
Emacs itself (@pxref{Packages,,, emacs, The GNU Emacs Manual}).

It first creates the @code{@code{package}-autoloads.el} file, then it byte
compiles all Emacs Lisp files.  Differently from the Emacs packaging system,
the Info documentation files are moved to the standard documentation
directory and the @file{dir} file is deleted.  The Elisp package files are
installed directly under @file{share/emacs/site-lisp}.
@end defvar

@defvar font-build-system
This variable is exported by @code{(guix build-system font)}.  It implements
an installation procedure for font packages where upstream provides
pre-compiled TrueType, OpenType, etc.@: font files that merely need to be
copied into place.  It copies font files to standard locations in the output
directory.
@end defvar

@defvar meson-build-system
This variable is exported by @code{(guix build-system meson)}.  It
implements the build procedure for packages that use
@url{https://mesonbuild.com, Meson} as their build system.

It adds both Meson and @uref{https://ninja-build.org/, Ninja} to the set of
inputs, and they can be changed with the parameters @code{#:meson} and
@code{#:ninja} if needed.

This build system is an extension of @code{gnu-build-system}, but with the
following phases changed to some specific for Meson:

@table @code

@item configure
The phase runs @code{meson} with the flags specified in
@code{#:configure-flags}.  The flag @option{--buildtype} is always set to
@code{debugoptimized} unless something else is specified in
@code{#:build-type}.

@item build
The phase runs @code{ninja} to build the package in parallel by default, but
this can be changed with @code{#:parallel-build?}.

@item marcar
The phase runs @samp{meson test} with a base set of options that cannot be
overridden.  This base set of options can be extended via the
@code{#:test-options} argument, for example to select or skip a specific
test suite.

@item install
The phase runs @code{ninja install} and can not be changed.
@end table

Apart from that, the build system also adds the following phases:

@table @code

@item fix-runpath
This phase ensures that all binaries can find the libraries they need.  It
searches for required libraries in subdirectories of the package being
built, and adds those to @code{RUNPATH} where needed.  It also removes
references to libraries left over from the build phase by @code{meson}, such
as test dependencies, that aren't actually required for the program to run.

@item glib-or-gtk-wrap
This phase is the phase provided by @code{glib-or-gtk-build-system}, and it
is not enabled by default.  It can be enabled with @code{#:glib-or-gtk?}.

@item glib-or-gtk-compile-schemas
This phase is the phase provided by @code{glib-or-gtk-build-system}, and it
is not enabled by default.  It can be enabled with @code{#:glib-or-gtk?}.
@end table
@end defvar

@defvar linux-module-build-system
@code{linux-module-build-system} allows building Linux kernel modules.

@cindex fases de construção
This build system is an extension of @code{gnu-build-system}, but with the
following phases changed:

@table @code

@item configure
This phase configures the environment so that the Linux kernel's Makefile
can be used to build the external kernel module.

@item build
This phase uses the Linux kernel's Makefile in order to build the external
kernel module.

@item install
This phase uses the Linux kernel's Makefile in order to install the external
kernel module.
@end table

It is possible and useful to specify the Linux kernel to use for building
the module (in the @code{arguments} form of a package using the
@code{linux-module-build-system}, use the key @code{#:linux} to specify it).
@end defvar

@defvar node-build-system
This variable is exported by @code{(guix build-system node)}.  It implements
the build procedure used by @uref{https://nodejs.org, Node.js}, which
implements an approximation of the @code{npm install} command, followed by
an @code{npm test} command.

Which Node.js package is used to interpret the @code{npm} commands can be
specified with the @code{#:node} parameter which defaults to @code{node}.
@end defvar

@defvar tree-sitter-build-system

This variable is exported by @code{(guix build-system tree-sitter)}.  It
implements procedures to compile grammars for the
@url{https://tree-sitter.github.io/tree-sitter/, Tree-sitter} parsing
library.  It essentially runs @code{tree-sitter generate} to translate
@code{grammar.js} grammars to JSON and then to C.  Which it then compiles to
native code.

Tree-sitter packages may support multiple grammars, so this build system
supports a @code{#:grammar-directories} keyword to specify a list of
locations where a @code{grammar.js} file may be found.

Grammars sometimes depend on each other, such as C++ depending on C and
TypeScript depending on JavaScript.  You may use inputs to declare such
dependencies.

@end defvar

Lastly, for packages that do not need anything as sophisticated, a
``trivial'' build system is provided.  It is trivial in the sense that it
provides basically no support: it does not pull any implicit inputs, and
does not have a notion of build phases.

@defvar trivial-build-system
This variable is exported by @code{(guix build-system trivial)}.

This build system requires a @code{#:builder} argument.  This argument must
be a Scheme expression that builds the package output(s)---as with
@code{build-expression->derivation} (@pxref{Derivações,
@code{build-expression->derivation}}).
@end defvar

@defvar channel-build-system
This variable is exported by @code{(guix build-system channel)}.

This build system is meant primarily for internal use.  A package using this
build system must have a channel specification as its @code{source} field
(@pxref{Canais}); alternatively, its source can be a directory name, in
which case an additional @code{#:commit} argument must be supplied to
specify the commit being built (a hexadecimal string).

Optionally, a @code{#:channels} argument specifying additional channels can
be provided.

The resulting package is a Guix instance of the given channel(s), similar to
how @command{guix time-machine} would build it.
@end defvar

@node Fases de construção
@section Fases de construção

@cindex build phases, for packages
Almost all package build systems implement a notion @dfn{build phases}: a
sequence of actions that the build system executes, when you build the
package, leading to the installed byproducts in the store.  A notable
exception is the ``bare-bones'' @code{trivial-build-system} (@pxref{Sistemas de compilação}).

As discussed in the previous section, those build systems provide a standard
list of phases.  For @code{gnu-build-system}, the main build phases are the
following:

@table @code
@item set-paths
Define search path environment variables for all the input packages,
including @env{PATH} (@pxref{Caminhos de pesquisa}).

@item unpack
Unpack the source tarball, and change the current directory to the extracted
source tree.  If the source is actually a directory, copy it to the build
tree, and enter that directory.

@item patch-source-shebangs
Patch shebangs encountered in source files so they refer to the right store
file names.  For instance, this changes @code{#!/bin/sh} to
@code{#!/gnu/store/@dots{}-bash-4.3/bin/sh}.

@item configure
Run the @file{configure} script with a number of default options, such as
@option{--prefix=/gnu/store/@dots{}}, as well as the options specified by
the @code{#:configure-flags} argument.

@item build
Run @code{make} with the list of flags specified with @code{#:make-flags}.
If the @code{#:parallel-build?} argument is true (the default), build with
@code{make -j}.

@item marcar
Run @code{make check}, or some other target specified with
@code{#:test-target}, unless @code{#:tests? #f} is passed.  If the
@code{#:parallel-tests?} argument is true (the default), run @code{make
check -j}.

@item install
Run @code{make install} with the flags listed in @code{#:make-flags}.

@item patch-shebangs
Patch shebangs on the installed executable files.

@item strip
Strip debugging symbols from ELF files (unless @code{#:strip-binaries?} is
false), copying them to the @code{debug} output when available
(@pxref{Instalando arquivos de depuração}).

@cindex RUNPATH, validation
@anchor{phase-validate-runpath}
@item validate-runpath
Validate the @code{RUNPATH} of ELF binaries, unless
@code{#:validate-runpath?} is false (@pxref{Sistemas de compilação}).

This validation step consists in making sure that all the shared libraries
needed by an ELF binary, which are listed as @code{DT_NEEDED} entries in its
@code{PT_DYNAMIC} segment, appear in the @code{DT_RUNPATH} entry of that
binary.  In other words, it ensures that running or using those binaries
will not result in a ``file not found'' error at run time.  @xref{Options,
@option{-rpath},, ld, The GNU Linker}, for more information on
@code{RUNPATH}.

@end table

Other build systems have similar phases, with some variations.  For example,
@code{cmake-build-system} has same-named phases but its @code{configure}
phases runs @code{cmake} instead of @code{./configure}.  Others, such as
@code{python-build-system}, have a wholly different list of standard
phases.  All this code runs on the @dfn{build side}: it is evaluated when
you actually build the package, in a dedicated build process spawned by the
build daemon (@pxref{Invocando guix-daemon}).

Build phases are represented as association lists or ``alists''
(@pxref{Association Lists,,, guile, GNU Guile Reference Manual}) where each
key is a symbol for the name of the phase and the associated value is a
procedure that accepts an arbitrary number of arguments.  By convention,
those procedures receive information about the build in the form of
@dfn{keyword parameters}, which they can use or ignore.

@vindex %standard-phases
For example, here is how @code{(guix build gnu-build-system)} defines
@code{%standard-phases}, the variable holding its alist of build
phases@footnote{We present a simplified view of those build phases, but do
take a look at @code{(guix build gnu-build-system)} to see all the
details!}:

@lisp
;; The build phases of 'gnu-build-system'.

(define* (unpack #:key source #:allow-other-keys)
  ;; Extract the source tarball.
  (invoke "tar" "xvf" source))

(define* (configure #:key outputs #:allow-other-keys)
  ;; Run the 'configure' script.  Install to output "out".
  (let ((out (assoc-ref outputs "out")))
    (invoke "./configure"
            (string-append "--prefix=" out))))

(define* (build #:allow-other-keys)
  ;; Compile.
  (invoke "make"))

(define* (check #:key (test-target "check") (tests? #true)
                #:allow-other-keys)
  ;; Run the test suite.
  (if tests?
      (invoke "make" test-target)
      (display "test suite not run\n")))

(define* (install #:allow-other-keys)
  ;; Install files to the prefix 'configure' specified.
  (invoke "make" "install"))

(define %standard-phases
  ;; The list of standard phases (quite a few are omitted
  ;; for brevity).  Each element is a symbol/procedure pair.
  (list (cons 'unpack unpack)
        (cons 'configure configure)
        (cons 'build build)
        (cons 'check check)
        (cons 'install install)))
@end lisp

This shows how @code{%standard-phases} is defined as a list of
symbol/procedure pairs (@pxref{Pairs,,, guile, GNU Guile Reference
Manual}).  The first pair associates the @code{unpack} procedure with the
@code{unpack} symbol---a name; the second pair defines the @code{configure}
phase similarly, and so on.  When building a package that uses
@code{gnu-build-system} with its default list of phases, those phases are
executed sequentially.  You can see the name of each phase started and
completed in the build log of packages that you build.

Let's now look at the procedures themselves.  Each one is defined with
@code{define*}: @code{#:key} lists keyword parameters the procedure accepts,
possibly with a default value, and @code{#:allow-other-keys} specifies that
other keyword parameters are ignored (@pxref{Optional Arguments,,, guile,
GNU Guile Reference Manual}).

The @code{unpack} procedure honors the @code{source} parameter, which the
build system uses to pass the file name of the source tarball (or version
control checkout), and it ignores other parameters.  The @code{configure}
phase only cares about the @code{outputs} parameter, an alist mapping
package output names to their store file name (@pxref{Pacotes com múltiplas saídas}).  It extracts the file name of for @code{out}, the default output,
and passes it to @command{./configure} as the installation prefix, meaning
that @command{make install} will eventually copy all the files in that
directory (@pxref{Configuration, configuration and makefile conventions,,
standards, GNU Coding Standards}).  @code{build} and @code{install} ignore
all their arguments.  @code{check} honors the @code{test-target} argument,
which specifies the name of the Makefile target to run tests; it prints a
message and skips tests when @code{tests?} is false.

@cindex build phases, customizing
The list of phases used for a particular package can be changed with the
@code{#:phases} parameter of the build system.  Changing the set of build
phases boils down to building a new alist of phases based on the
@code{%standard-phases} alist described above.  This can be done with
standard alist procedures such as @code{alist-delete} (@pxref{SRFI-1
Association Lists,,, guile, GNU Guile Reference Manual}); however, it is
more convenient to do so with @code{modify-phases} (@pxref{Construir utilitários,
@code{modify-phases}}).

Here is an example of a package definition that removes the @code{configure}
phase of @code{%standard-phases} and inserts a new phase before the
@code{build} phase, called @code{set-prefix-in-makefile}:

@lisp
(define-public example
  (package
    (name "example")
    ;; other fields omitted
    (build-system gnu-build-system)
    (arguments
     (list
      #:phases
      #~(modify-phases %standard-phases
          (delete 'configure)
          (add-before 'build 'set-prefix-in-makefile
            (lambda* (#:key inputs #:allow-other-keys)
              ;; Modify the makefile so that its
              ;; 'PREFIX' variable points to #$output and
              ;; 'XMLLINT' points to the correct path.
              (substitute* "Makefile"
                (("PREFIX =.*")
                 (string-append "PREFIX = " #$output "\n"))
                (("XMLLINT =.*")
                 (string-append "XMLLINT = "
                                (search-input-file inputs "/bin/xmllint")
                                "\n"))))))))))
@end lisp

The new phase that is inserted is written as an anonymous procedure,
introduced with @code{lambda*}; it looks for the @file{xmllint} executable
under a @file{/bin} directory among the package's inputs (@pxref{Referência do package}).  It also honors the @code{outputs} parameter we have seen
before.  @xref{Construir utilitários}, for more about the helpers used by this
phase, and for more examples of @code{modify-phases}.

@quotation Dica
You can inspect the code associated with a package's @code{#:phases}
argument interactively, at the REPL (@pxref{Usando Guix interativamente}).
@end quotation

@cindex code staging
@cindex staging, of code
Keep in mind that build phases are code evaluated at the time the package is
actually built.  This explains why the whole @code{modify-phases} expression
above is quoted (it comes after the @code{#~} or hash-tilde): it is
@dfn{staged} for later execution.  @xref{Expressões-G}, for an explanation
of code staging and the @dfn{code strata} involved.

@node Construir utilitários
@section Construir utilitários

As soon as you start writing non-trivial package definitions
(@pxref{Definindo pacotes}) or other build actions (@pxref{Expressões-G}),
you will likely start looking for helpers for ``shell-like''
actions---creating directories, copying and deleting files recursively,
manipulating build phases, and so on.  The @code{(guix build utils)} module
provides such utility procedures.

Most build systems load @code{(guix build utils)} (@pxref{Sistemas de compilação}).
Thus, when writing custom build phases for your package definitions, you can
usually assume those procedures are in scope.

When writing G-expressions, you can import @code{(guix build utils)} on the
``build side'' using @code{with-imported-modules} and then put it in scope
with the @code{use-modules} form (@pxref{Using Guile Modules,,, guile, GNU
Guile Reference Manual}):

@lisp
(with-imported-modules '((guix build utils))  ;import it
  (computed-file "empty-tree"
                 #~(begin
                     ;; Put it in scope.
                     (use-modules (guix build utils))

                     ;; Happily use its 'mkdir-p' procedure.
                     (mkdir-p (string-append #$output "/a/b/c")))))
@end lisp

The remainder of this section is the reference for most of the utility
procedures provided by @code{(guix build utils)}.

@c TODO Document what's missing.

@subsection Dealing with Store File Names

This section documents procedures that deal with store file names.

@deffn {Procedure} %store-directory
Return the directory name of the store.
@end deffn

@deffn {Procedure} store-file-name? file
Return true if @var{file} is in the store.
@end deffn

@deffn {Procedure} strip-store-file-name file
Strip the @file{/gnu/store} and hash from @var{file}, a store file name.
The result is typically a @code{"@var{package}-@var{version}"} string.
@end deffn

@deffn {Procedure} package-name->name+version name
Given @var{name}, a package name like @code{"foo-0.9.1b"}, return two
values: @code{"foo"} and @code{"0.9.1b"}.  When the version part is
unavailable, @var{name} and @code{#f} are returned.  The first hyphen
followed by a digit is considered to introduce the version part.
@end deffn

@subsection File Types

The procedures below deal with files and file types.

@deffn {Procedure} directory-exists? dir
Return @code{#t} if @var{dir} exists and is a directory.
@end deffn

@deffn {Procedure} executable-file? file
Return @code{#t} if @var{file} exists and is executable.
@end deffn

@deffn {Procedure} symbolic-link? file
Return @code{#t} if @var{file} is a symbolic link (aka. a ``symlink'').
@end deffn

@deffn {Procedure} elf-file? file
@deffnx {Procedure} ar-file? file
@deffnx {Procedure} gzip-file? file
Return @code{#t} if @var{file} is, respectively, an ELF file, an @code{ar}
archive (such as a @file{.a} static library), or a gzip file.
@end deffn

@deffn {Procedure} reset-gzip-timestamp file [#:keep-mtime? #t]
If @var{file} is a gzip file, reset its embedded timestamp (as with
@command{gzip --no-name}) and return true.  Otherwise return @code{#f}.
When @var{keep-mtime?} is true, preserve @var{file}'s modification time.
@end deffn

@subsection File Manipulation

The following procedures and macros help create, modify, and delete files.
They provide functionality comparable to common shell utilities such as
@command{mkdir -p}, @command{cp -r}, @command{rm -r}, and @command{sed}.
They complement Guile's extensive, but low-level, file system interface
(@pxref{POSIX,,, guile, GNU Guile Reference Manual}).

@defmac with-directory-excursion directory body @dots{}
Run @var{body} with @var{directory} as the process's current directory.

Essentially, this macro changes the current directory to @var{directory}
before evaluating @var{body}, using @code{chdir} (@pxref{Processes,,, guile,
GNU Guile Reference Manual}).  It changes back to the initial directory when
the dynamic extent of @var{body} is left, be it @i{via} normal procedure
return or @i{via} a non-local exit such as an exception.
@end defmac

@deffn {Procedure} mkdir-p dir
Create directory @var{dir} and all its ancestors.
@end deffn

@deffn {Procedure} install-file file directory
Create @var{directory} if it does not exist and copy @var{file} in there
under the same name.
@end deffn

@deffn {Procedure} make-file-writable file
Make @var{file} writable for its owner.
@end deffn

@deffn {Procedure} copy-recursively source destination @
  [#:log (current-output-port)] [#:follow-symlinks? #f] @ [#:copy-file
copy-file] [#:keep-mtime? #f] [#:keep-permissions? #t] @ [#:select? (const
#t)] Copy @var{source} directory to @var{destination}.  Follow symlinks if
@var{follow-symlinks?} is true; otherwise, just preserve them.  Call
@var{copy-file} to copy regular files.  Call @var{select?}, taking two
arguments, @var{file} and @var{stat}, for each entry in @var{source}, where
@var{file} is the entry's absolute file name and @var{stat} is the result of
@code{lstat} (or @code{stat} if @var{follow-symlinks?} is true); exclude
entries for which @var{select?} does not return true.  When
@var{keep-mtime?} is true, keep the modification time of the files in
@var{source} on those of @var{destination}.  When @var{keep-permissions?} is
true, preserve file permissions.  Write verbose output to the @var{log}
port.
@end deffn

@deffn {Procedure} delete-file-recursively dir [#:follow-mounts? #f]
Delete @var{dir} recursively, like @command{rm -rf}, without following
symlinks.  Don't follow mount points either, unless @var{follow-mounts?} is
true.  Report but ignore errors.
@end deffn

@defmac substitute* file @
  ((regexp match-var@dots{}) body@dots{}) @dots{} Substitute @var{regexp} in
@var{file} by the string returned by @var{body}.  @var{body} is evaluated
with each @var{match-var} bound to the corresponding positional regexp
sub-expression.  For example:

@lisp
(substitute* file
  (("hello")
   "good morning\n")
  (("foo([a-z]+)bar(.*)$" all letters end)
   (string-append "baz" letters end)))
@end lisp

Here, anytime a line of @var{file} contains @code{hello}, it is replaced by
@code{good morning}.  Anytime a line of @var{file} matches the second
regexp, @code{all} is bound to the complete match, @code{letters} is bound
to the first sub-expression, and @code{end} is bound to the last one.

When one of the @var{match-var} is @code{_}, no variable is bound to the
corresponding match substring.

Alternatively, @var{file} may be a list of file names, in which case they
are all subject to the substitutions.

Be careful about using @code{$} to match the end of a line; by itself it
won't match the terminating newline of a line.  For example, to match a
whole line ending with a backslash, one needs a regex like
@code{"(.*)\\\\\n$"}.
@end defmac

@subsection File Search

@cindex file, searching
This section documents procedures to search and filter files.

@deffn {Procedure} file-name-predicate regexp
Return a predicate that returns true when passed a file name whose base name
matches @var{regexp}.
@end deffn

@deffn {Procedure} find-files dir [pred] @
  [#:stat lstat] [#:directories? #f] [#:fail-on-error? #f] Return the
lexicographically sorted list of files under @var{dir} for which @var{pred}
returns true.  @var{pred} is passed two arguments: the absolute file name,
and its stat buffer; the default predicate always returns true.  @var{pred}
can also be a regular expression, in which case it is equivalent to
@code{(file-name-predicate @var{pred})}.  @var{stat} is used to obtain file
information; using @code{lstat} means that symlinks are not followed.  If
@var{directories?} is true, then directories will also be included.  If
@var{fail-on-error?} is true, raise an exception upon error.
@end deffn

Here are a few examples where we assume that the current directory is the
root of the Guix source tree:

@lisp
;; List all the regular files in the current directory.
(find-files ".")
@result{} ("./.dir-locals.el" "./.gitignore" @dots{})

;; List all the .scm files under gnu/services.
(find-files "gnu/services" "\\.scm$")
@result{} ("gnu/services/admin.scm" "gnu/services/audio.scm" @dots{})

;; List ar files in the current directory.
(find-files "." (lambda (file stat) (ar-file? file)))
@result{} ("./libformat.a" "./libstore.a" @dots{})
@end lisp

@deffn {Procedure} which program
Return the complete file name for @var{program} as found in @code{$PATH}, or
@code{#f} if @var{program} could not be found.
@end deffn

@deffn {Procedure} search-input-file inputs name
@deffnx {Procedure} search-input-directory inputs name
Return the complete file name for @var{name} as found in @var{inputs};
@code{search-input-file} searches for a regular file and
@code{search-input-directory} searches for a directory.  If @var{name} could
not be found, an exception is raised.

Here, @var{inputs} must be an association list like @code{inputs} and
@code{native-inputs} as available to build phases (@pxref{Fases de construção}).
@end deffn

Here is a (simplified) example of how @code{search-input-file} is used in a
build phase of the @code{wireguard-tools} package:

@lisp
(add-after 'install 'wrap-wg-quick
  (lambda* (#:key inputs outputs #:allow-other-keys)
    (let ((coreutils (string-append (assoc-ref inputs "coreutils")
                                    "/bin")))
      (wrap-program (search-input-file outputs "bin/wg-quick")
        #:sh (search-input-file inputs "bin/bash")
        `("PATH" ":" prefix ,(list coreutils))))))
@end lisp

@subsection Program Invocation

@cindex program invocation, from Scheme
@cindex invoking programs, from Scheme
You'll find handy procedures to spawn processes in this module, essentially
convenient wrappers around Guile's @code{system*} (@pxref{Processes,
@code{system*},, guile, GNU Guile Reference Manual}).

@deffn {Procedure} invoke program args@dots{}
Invoke @var{program} with the given @var{args}.  Raise an
@code{&invoke-error} exception if the exit code is non-zero; otherwise
return @code{#t}.

The advantage compared to @code{system*} is that you do not need to check
the return value.  This reduces boilerplate in shell-script-like snippets
for instance in package build phases.
@end deffn

@deffn {Procedure} invoke-error? c
Return true if @var{c} is an @code{&invoke-error} condition.
@end deffn

@deffn {Procedure} invoke-error-program c
@deffnx {Procedure} invoke-error-arguments c
@deffnx {Procedure} invoke-error-exit-status c
@deffnx {Procedure} invoke-error-term-signal c
@deffnx {Procedure} invoke-error-stop-signal c
Access specific fields of @var{c}, an @code{&invoke-error} condition.
@end deffn

@deffn {Procedure} report-invoke-error c [port]
Report to @var{port} (by default the current error port) about @var{c}, an
@code{&invoke-error} condition, in a human-friendly way.

Typical usage would look like this:

@lisp
(use-modules (srfi srfi-34) ;for 'guard'
             (guix build utils))

(guard (c ((invoke-error? c)
           (report-invoke-error c)))
  (invoke "date" "--imaginary-option"))

@print{} command "date" "--imaginary-option" failed with status 1
@end lisp
@end deffn

@deffn {Procedure} invoke/quiet program args@dots{}
Invoke @var{program} with @var{args} and capture @var{program}'s standard
output and standard error.  If @var{program} succeeds, print nothing and
return the unspecified value; otherwise, raise a @code{&message} error
condition that includes the status code and the output of @var{program}.

Here's an example:

@lisp
(use-modules (srfi srfi-34) ;for 'guard'
             (srfi srfi-35) ;for 'message-condition?'
             (guix build utils))

(guard (c ((message-condition? c)
           (display (condition-message c))))
  (invoke/quiet "date")  ;all is fine
  (invoke/quiet "date" "--imaginary-option"))

@print{} 'date --imaginary-option' exited with status 1; output follows:

    date: unrecognized option '--imaginary-option'
    Try 'date --help' for more information.
@end lisp
@end deffn

@subsection Fases de construção

@cindex fases de construção
The @code{(guix build utils)} also contains tools to manipulate build phases
as used by build systems (@pxref{Sistemas de compilação}).  Build phases are
represented as association lists or ``alists'' (@pxref{Association Lists,,,
guile, GNU Guile Reference Manual}) where each key is a symbol naming the
phase and the associated value is a procedure (@pxref{Fases de construção}).

Guile core and the @code{(srfi srfi-1)} module both provide tools to
manipulate alists.  The @code{(guix build utils)} module complements those
with tools written with build phases in mind.

@cindex build phases, modifying
@defmac modify-phases phases clause@dots{}
Modify @var{phases} sequentially as per each @var{clause}, which may have
one of the following forms:

@lisp
(delete @var{old-phase-name})
(replace @var{old-phase-name} @var{new-phase})
(add-before @var{old-phase-name} @var{new-phase-name} @var{new-phase})
(add-after @var{old-phase-name} @var{new-phase-name} @var{new-phase})
@end lisp

Where every @var{phase-name} above is an expression evaluating to a symbol,
and @var{new-phase} an expression evaluating to a procedure.
@end defmac

The example below is taken from the definition of the @code{grep} package.
It adds a phase to run after the @code{install} phase, called
@code{fix-egrep-and-fgrep}.  That phase is a procedure (@code{lambda*} is
for anonymous procedures) that takes a @code{#:outputs} keyword argument and
ignores extra keyword arguments (@pxref{Optional Arguments,,, guile, GNU
Guile Reference Manual}, for more on @code{lambda*} and optional and keyword
arguments.)  The phase uses @code{substitute*} to modify the installed
@file{egrep} and @file{fgrep} scripts so that they refer to @code{grep} by
its absolute file name:

@lisp
(modify-phases %standard-phases
  (add-after 'install 'fix-egrep-and-fgrep
    ;; Patch 'egrep' and 'fgrep' to execute 'grep' via its
    ;; absolute file name instead of searching for it in $PATH.
    (lambda* (#:key outputs #:allow-other-keys)
      (let* ((out (assoc-ref outputs "out"))
             (bin (string-append out "/bin")))
        (substitute* (list (string-append bin "/egrep")
                           (string-append bin "/fgrep"))
          (("^exec grep")
           (string-append "exec " bin "/grep")))))))
@end lisp

In the example below, phases are modified in two ways: the standard
@code{configure} phase is deleted, presumably because the package does not
have a @file{configure} script or anything similar, and the default
@code{install} phase is replaced by one that manually copies the executable
files to be installed:

@lisp
(modify-phases %standard-phases
  (delete 'configure)      ;no 'configure' script
  (replace 'install
    (lambda* (#:key outputs #:allow-other-keys)
      ;; The package's Makefile doesn't provide an "install"
      ;; rule so do it by ourselves.
      (let ((bin (string-append (assoc-ref outputs "out")
                                "/bin")))
        (install-file "footswitch" bin)
        (install-file "scythe" bin)))))
@end lisp

@c TODO: Add more examples.

@subsection Wrappers

@cindex program wrappers
@cindex wrapping programs
It is not unusual for a command to require certain environment variables to
be set for proper functioning, typically search paths (@pxref{Caminhos de pesquisa}).  Failing to do that, the command might fail to find files or other
commands it relies on, or it might pick the ``wrong'' ones---depending on
the environment in which it runs.  Examples include:

@itemize
@item
a shell script that assumes all the commands it uses are in @env{PATH};

@item
a Guile program that assumes all its modules are in @env{GUILE_LOAD_PATH}
and @env{GUILE_LOAD_COMPILED_PATH};

@item
a Qt application that expects to find certain plugins in
@env{QT_PLUGIN_PATH}.
@end itemize

For a package writer, the goal is to make sure commands always work the same
rather than depend on some external settings.  One way to achieve that is to
@dfn{wrap} commands in a thin script that sets those environment variables,
thereby ensuring that those run-time dependencies are always found.  The
wrapper would be used to set @env{PATH}, @env{GUILE_LOAD_PATH}, or
@env{QT_PLUGIN_PATH} in the examples above.

To ease that task, the @code{(guix build utils)} module provides a couple of
helpers to wrap commands.

@deffn {Procedure} wrap-program program [#:sh sh] [#:rest variables]
Make a wrapper for @var{program}.  @var{variables} should look like this:

@lisp
'(@var{variable} @var{delimiter} @var{position} @var{list-of-directories})
@end lisp

where @var{delimiter} is optional.  @code{:} will be used if @var{delimiter}
is not given.

For example, this call:

@lisp
(wrap-program "foo"
              '("PATH" ":" = ("/gnu/.../bar/bin"))
              '("CERT_PATH" suffix ("/gnu/.../baz/certs"
                                    "/qux/certs")))
@end lisp

will copy @file{foo} to @file{.foo-real} and create the file @file{foo} with
the following contents:

@example
#!location/of/bin/bash
export PATH="/gnu/.../bar/bin"
export CERT_PATH="$CERT_PATH$@{CERT_PATH:+:@}/gnu/.../baz/certs:/qux/certs"
exec -a $0 location/of/.foo-real "$@@"
@end example

If @var{program} has previously been wrapped by @code{wrap-program}, the
wrapper is extended with definitions for @var{variables}.  If it is not,
@var{sh} will be used as the interpreter.
@end deffn

@deffn {Procedure} wrap-script program [#:guile guile] [#:rest variables]
Wrap the script @var{program} such that @var{variables} are set first.  The
format of @var{variables} is the same as in the @code{wrap-program}
procedure.  This procedure differs from @code{wrap-program} in that it does
not create a separate shell script.  Instead, @var{program} is modified
directly by prepending a Guile script, which is interpreted as a comment in
the script's language.

Special encoding comments as supported by Python are recreated on the second
line.

Note that this procedure can only be used once per file as Guile scripts are
not supported.
@end deffn

@node Caminhos de pesquisa
@section Caminhos de pesquisa

@cindex search path
Many programs and libraries look for input data in a @dfn{search path}, a
list of directories: shells like Bash look for executables in the command
search path, a C compiler looks for @file{.h} files in its header search
path, the Python interpreter looks for @file{.py} files in its search path,
the spell checker has a search path for dictionaries, and so on.

Search paths can usually be defined or overridden @i{via} environment
variables (@pxref{Environment Variables,,, libc, The GNU C Library Reference
Manual}).  For example, the search paths mentioned above can be changed by
defining the @env{PATH}, @env{C_INCLUDE_PATH}, @env{PYTHONPATH} (or
@env{GUIX_PYTHONPATH}), and @env{DICPATH} environment variables---you know,
all these something-PATH variables that you need to get right or things
``won't be found''.

You may have noticed from the command line that Guix ``knows'' which search
path environment variables should be defined, and how.  When you install
packages in your default profile, the file
@file{~/.guix-profile/etc/profile} is created, which you can ``source'' from
the shell to set those variables.  Likewise, if you ask @command{guix shell}
to create an environment containing Python and NumPy, a Python library, and
if you pass it the @option{--search-paths} option, it will tell you about
@env{PATH} and @env{GUIX_PYTHONPATH} (@pxref{Invocando guix shell}):

@example
$ guix shell python python-numpy --pure --search-paths
export PATH="/gnu/store/@dots{}-profile/bin"
export GUIX_PYTHONPATH="/gnu/store/@dots{}-profile/lib/python3.9/site-packages"
@end example

When you omit @option{--search-paths}, it defines these environment
variables right away, such that Python can readily find NumPy:

@example
$ guix shell python python-numpy -- python3
Python 3.9.6 (default, Jan  1 1970, 00:00:01)
[GCC 10.3.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import numpy
>>> numpy.version.version
'1.20.3'
@end example

For this to work, the definition of the @code{python} package
@emph{declares} the search path it cares about and its associated
environment variable, @env{GUIX_PYTHONPATH}.  It looks like this:

@lisp
(package
  (name "python")
  (version "3.9.9")
  ;; some fields omitted...
  (native-search-paths
   (list (search-path-specification
          (variable "GUIX_PYTHONPATH")
          (files (list "lib/python/3.9/site-packages"))))))
@end lisp

What this @code{native-search-paths} field says is that, when the
@code{python} package is used, the @env{GUIX_PYTHONPATH} environment
variable must be defined to include all the
@file{lib/python/3.9/site-packages} sub-directories encountered in its
environment.  (The @code{native-} bit means that, if we are in a
cross-compilation environment, only native inputs may be added to the search
path; @pxref{Referência do package, @code{search-paths}}.)  In the NumPy example
above, the profile where @code{python} appears contains exactly one such
sub-directory, and @env{GUIX_PYTHONPATH} is set to that.  When there are
several @file{lib/python/3.9/site-packages}---this is the case in package
build environments---they are all added to @env{GUIX_PYTHONPATH}, separated
by colons (@code{:}).

@quotation Nota
Notice that @env{GUIX_PYTHONPATH} is specified as part of the definition of
the @code{python} package, and @emph{not} as part of that of
@code{python-numpy}.  This is because this environment variable ``belongs''
to Python, not NumPy: Python actually reads the value of that variable and
honors it.

Corollary: if you create a profile that does not contain @code{python},
@code{GUIX_PYTHONPATH} will @emph{not} be defined, even if it contains
packages that provide @file{.py} files:

@example
$ guix shell python-numpy --search-paths --pure
export PATH="/gnu/store/@dots{}-profile/bin"
@end example

This makes a lot of sense if we look at this profile in isolation: no
software in this profile would read @env{GUIX_PYTHONPATH}.
@end quotation

Of course, there are many variations on that theme: some packages honor more
than one search path, some use separators other than colon, some accumulate
several directories in their search path, and so on.  A more complex example
is the search path of libxml2: the value of the @env{XML_CATALOG_FILES}
environment variable is space-separated, it must contain a list of
@file{catalog.xml} files (not directories), which are to be found in
@file{xml} sub-directories---nothing less.  The search path specification
looks like this:

@c This is defined at (guix search-paths) as $XML_CATALOG_FILES.
@lisp
(search-path-specification
 (variable "XML_CATALOG_FILES")
 (separator " ")
 (files '("xml"))
 (file-pattern "^catalog\\.xml$")
 (file-type 'regular))
@end lisp

Worry not, search path specifications are usually not this tricky.

The @code{(guix search-paths)} module defines the data type of search path
specifications and a number of helper procedures.  Below is the reference of
search path specifications.

@deftp {Tipo de dados} search-path-specification
The data type for search path specifications.

@table @asis
@item @code{variable}
The name of the environment variable for this search path (a string).

@item @code{files}
The list of sub-directories (strings) that should be added to the search
path.

@item @code{separator} (default: @code{":"})
The string used to separate search path components.

As a special case, a @code{separator} value of @code{#f} specifies a
``single-component search path''---in other words, a search path that cannot
contain more than one element.  This is useful in some cases, such as the
@code{SSL_CERT_DIR} variable (honored by OpenSSL, cURL, and a few other
packages) or the @code{ASPELL_DICT_DIR} variable (honored by the GNU Aspell
spell checker), both of which must point to a single directory.

@item @code{file-type} (default: @code{'directory})
The type of file being matched---@code{'directory} or @code{'regular},
though it can be any symbol returned by @code{stat:type} (@pxref{File System, @code{stat},, guile, GNU Guile Reference Manual}).

In the @env{XML_CATALOG_FILES} example above, we would match regular files;
in the Python example, we would match directories.

@item @code{file-pattern} (default: @code{#f})
This must be either @code{#f} or a regular expression specifying files to be
matched @emph{within} the sub-directories specified by the @code{files}
field.

Again, the @env{XML_CATALOG_FILES} example shows a situation where this is
needed.
@end table
@end deftp

Some search paths are not tied by a single package but to many packages.  To
reduce duplications, some of them are pre-defined in @code{(guix
search-paths)}.

@defvar $SGML_CATALOG_FILES
@defvarx $XML_CATALOG_FILES
These two search paths indicate where the
@url{https://www.oasis-open.org/specs/a401.htm,TR9401 catalog}@footnote{
Alternatively known as SGML catalog.} or
@url{https://www.oasis-open.org/committees/download.php/14809/xml-catalogs.html,
XML catalog} files can be found.
@end defvar

@defvar $SSL_CERT_DIR
@defvarx $SSL_CERT_FILE
These two search paths indicate where X.509 certificates can be found
(@pxref{Certificados X.509}).
@end defvar

These pre-defined search paths can be used as in the following example:

@lisp
(package
  (name "curl")
  ;; some fields omitted ...
  (native-search-paths (list $SSL_CERT_DIR $SSL_CERT_FILE)))
@end lisp

How do you turn search path specifications on one hand and a bunch of
directories on the other hand in a set of environment variable definitions?
That's the job of @code{evaluate-search-paths}.

@deffn {Procedure} evaluate-search-paths search-paths directories [getenv]
Evaluate @var{search-paths}, a list of search-path specifications, for
@var{directories}, a list of directory names, and return a list of
specification/value pairs.  Use @var{getenv} to determine the current
settings and report only settings not already effective.
@end deffn

The @code{(guix profiles)} provides a higher-level helper procedure,
@code{load-profile}, that sets the environment variables of a profile.

@node O armazém
@section O armazém

@cindex store
@cindex itens do armazém
@cindex store paths

Conceptually, the @dfn{store} is the place where derivations that have been
built successfully are stored---by default, @file{/gnu/store}.
Sub-directories in the store are referred to as @dfn{store items} or
sometimes @dfn{store paths}.  The store has an associated database that
contains information such as the store paths referred to by each store path,
and the list of @emph{valid} store items---results of successful builds.
This database resides in @file{@var{localstatedir}/guix/db}, where
@var{localstatedir} is the state directory specified @i{via}
@option{--localstatedir} at configure time, usually @file{/var}.

The store is @emph{always} accessed by the daemon on behalf of its clients
(@pxref{Invocando guix-daemon}).  To manipulate the store, clients connect to
the daemon over a Unix-domain socket, send requests to it, and read the
result---these are remote procedure calls, or RPCs.

@quotation Nota
Users must @emph{never} modify files under @file{/gnu/store} directly.  This
would lead to inconsistencies and break the immutability assumptions of
Guix's functional model (@pxref{Introdução}).

@xref{Invocando guix gc, @command{guix gc --verify}}, for information on how
to check the integrity of the store and attempt recovery from accidental
modifications.
@end quotation

The @code{(guix store)} module provides procedures to connect to the daemon,
and to perform RPCs.  These are described below.  By default,
@code{open-connection}, and thus all the @command{guix} commands, connect to
the local daemon or to the URI specified by the @env{GUIX_DAEMON_SOCKET}
environment variable.

@defvr {Environment Variable} GUIX_DAEMON_SOCKET
When set, the value of this variable should be a file name or a URI
designating the daemon endpoint.  When it is a file name, it denotes a
Unix-domain socket to connect to.  In addition to file names, the supported
URI schemes are:

@table @code
@item file
@itemx unix
These are for Unix-domain sockets.
@code{file:///var/guix/daemon-socket/socket} is equivalent to
@file{/var/guix/daemon-socket/socket}.

@item guix
@cindex daemon, acesso remoto
@cindex acesso remoto ao daemon
@cindex daemon, configuração de cluster
@cindex clusters, configuração do daemon
These URIs denote connections over TCP/IP, without encryption nor
authentication of the remote host.  The URI must specify the host name and
optionally a port number (by default port 44146 is used):

@example
guix://master.guix.example.org:1234
@end example

This setup is suitable on local networks, such as clusters, where only
trusted nodes may connect to the build daemon at
@code{master.guix.example.org}.

The @option{--listen} option of @command{guix-daemon} can be used to
instruct it to listen for TCP connections (@pxref{Invocando guix-daemon,
@option{--listen}}).

@item ssh
@cindex SSH access to build daemons
These URIs allow you to connect to a remote daemon over SSH@.  This feature
requires Guile-SSH (@pxref{Requisitos}) and a working @command{guile}
binary in @env{PATH} on the destination machine.  It supports public key and
GSSAPI authentication.  A typical URL might look like this:

@example
ssh://charlie@@guix.example.org:22
@end example

As for @command{guix copy}, the usual OpenSSH client configuration files are
honored (@pxref{Invocando guix copy}).
@end table

Additional URI schemes may be supported in the future.

@c XXX: Remove this note when the protocol incurs fewer round trips
@c and when (guix derivations) no longer relies on file system access.
@quotation Nota
The ability to connect to remote build daemons is considered experimental as
of @value{VERSION}.  Please get in touch with us to share any problems or
suggestions you may have (@pxref{Contribuindo}).
@end quotation
@end defvr

@deffn {Procedure} open-connection [uri] [#:reserve-space? #t]
Connect to the daemon over the Unix-domain socket at @var{uri} (a string).
When @var{reserve-space?} is true, instruct it to reserve a little bit of
extra space on the file system so that the garbage collector can still
operate should the disk become full.  Return a server object.

@var{file} defaults to @code{%default-socket-path}, which is the normal
location given the options that were passed to @command{configure}.
@end deffn

@deffn {Procedure} close-connection server
Close the connection to @var{server}.
@end deffn

@defvar current-build-output-port
This variable is bound to a SRFI-39 parameter, which refers to the port
where build and error logs sent by the daemon should be written.
@end defvar

Procedures that make RPCs all take a server object as their first argument.

@cindex invalid store items
@deffn {Procedure} valid-path? server path
Return @code{#t} when @var{path} designates a valid store item and @code{#f}
otherwise (an invalid item may exist on disk but still be invalid, for
instance because it is the result of an aborted or failed build).

A @code{&store-protocol-error} condition is raised if @var{path} is not
prefixed by the store directory (@file{/gnu/store}).
@end deffn

@deffn {Procedure} add-text-to-store server name text [references]
Add @var{text} under file @var{name} in the store, and return its store
path.  @var{references} is the list of store paths referred to by the
resulting store path.
@end deffn

@deffn {Procedure} build-derivations store derivations [mode]
Build @var{derivations}, a list of @code{<derivation>} objects, @file{.drv}
file names, or derivation/output pairs, using the specified
@var{mode}---@code{(build-mode normal)} by default.
@end deffn

Note that the @code{(guix monads)} module provides a monad as well as
monadic versions of the above procedures, with the goal of making it more
convenient to work with code that accesses the store (@pxref{A mônada do armazém}).

@c FIXME
@i{This section is currently incomplete.}

@node Derivações
@section Derivações

@cindex derivations
Low-level build actions and the environment in which they are performed are
represented by @dfn{derivations}.  A derivation contains the following
pieces of information:

@itemize
@item
The outputs of the derivation---derivations produce at least one file or
directory in the store, but may produce more.

@item
@cindex build-time dependencies
@cindex dependencies, build-time
The inputs of the derivation---i.e., its build-time dependencies---which may
be other derivations or plain files in the store (patches, build scripts,
etc.).

@item
The system type targeted by the derivation---e.g., @code{x86_64-linux}.

@item
The file name of a build script in the store, along with the arguments to be
passed.

@item
A list of environment variables to be defined.

@end itemize

@cindex derivation path
Derivations allow clients of the daemon to communicate build actions to the
store.  They exist in two forms: as an in-memory representation, both on the
client- and daemon-side, and as files in the store whose name end in
@file{.drv}---these files are referred to as @dfn{derivation paths}.
Derivations paths can be passed to the @code{build-derivations} procedure to
perform the build actions they prescribe (@pxref{O armazém}).

@cindex fixed-output derivations
Operations such as file downloads and version-control checkouts for which
the expected content hash is known in advance are modeled as
@dfn{fixed-output derivations}.  Unlike regular derivations, the outputs of
a fixed-output derivation are independent of its inputs---e.g., a source
code download produces the same result regardless of the download method and
tools being used.

@cindex references
@cindex run-time dependencies
@cindex dependencies, run-time
The outputs of derivations---i.e., the build results---have a set of
@dfn{references}, as reported by the @code{references} RPC or the
@command{guix gc --references} command (@pxref{Invocando guix gc}).
References are the set of run-time dependencies of the build results.
References are a subset of the inputs of the derivation; this subset is
automatically computed by the build daemon by scanning all the files in the
outputs.

The @code{(guix derivations)} module provides a representation of
derivations as Scheme objects, along with procedures to create and otherwise
manipulate derivations.  The lowest-level primitive to create a derivation
is the @code{derivation} procedure:

@deffn {Procedure} derivation store name builder args @
  [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @ [#:recursive? #f]
[#:inputs '()] [#:env-vars '()] @ [#:system (%current-system)]
[#:references-graphs #f] @ [#:allowed-references #f]
[#:disallowed-references #f] @ [#:leaked-env-vars #f] [#:local-build? #f] @
[#:substitutable? #t] [#:properties '()] Build a derivation with the given
arguments, and return the resulting @code{<derivation>} object.

When @var{hash} and @var{hash-algo} are given, a @dfn{fixed-output
derivation} is created---i.e., one whose result is known in advance, such as
a file download.  If, in addition, @var{recursive?} is true, then that fixed
output may be an executable file or a directory and @var{hash} must be the
hash of an archive containing this output.

When @var{references-graphs} is true, it must be a list of file name/store
path pairs.  In that case, the reference graph of each store path is
exported in the build environment in the corresponding file, in a simple
text format.

When @var{allowed-references} is true, it must be a list of store items or
outputs that the derivation's output may refer to.  Likewise,
@var{disallowed-references}, if true, must be a list of things the outputs
may @emph{not} refer to.

When @var{leaked-env-vars} is true, it must be a list of strings denoting
environment variables that are allowed to ``leak'' from the daemon's
environment to the build environment.  This is only applicable to
fixed-output derivations---i.e., when @var{hash} is true.  The main use is
to allow variables such as @code{http_proxy} to be passed to derivations
that download files.

When @var{local-build?} is true, declare that the derivation is not a good
candidate for offloading and should rather be built locally (@pxref{Configuração de descarregamento de daemon}).  This is the case for small derivations where the costs of
data transfers would outweigh the benefits.

When @var{substitutable?} is false, declare that substitutes of the
derivation's output should not be used (@pxref{Substitutos}).  This is
useful, for instance, when building packages that capture details of the
host CPU instruction set.

@var{properties} must be an association list describing ``properties'' of
the derivation.  It is kept as-is, uninterpreted, in the derivation.
@end deffn

@noindent
Here's an example with a shell script as its builder, assuming @var{store}
is an open connection to the daemon, and @var{bash} points to a Bash
executable in the store:

@lisp
(use-modules (guix utils)
             (guix store)
             (guix derivations))

(let ((builder   ; add the Bash script to the store
        (add-text-to-store store "my-builder.sh"
                           "echo hello world > $out\n" '())))
  (derivation store "foo"
              bash `("-e" ,builder)
              #:inputs `((,bash) (,builder))
              #:env-vars '(("HOME" . "/homeless"))))
@result{} #<derivation /gnu/store/@dots{}-foo.drv => /gnu/store/@dots{}-foo>
@end lisp

As can be guessed, this primitive is cumbersome to use directly.  A better
approach is to write build scripts in Scheme, of course! The best course of
action for that is to write the build code as a ``G-expression'', and to
pass it to @code{gexp->derivation}.  For more information,
@pxref{Expressões-G}.

Once upon a time, @code{gexp->derivation} did not exist and constructing
derivations with build code written in Scheme was achieved with
@code{build-expression->derivation}, documented below.  This procedure is
now deprecated in favor of the much nicer @code{gexp->derivation}.

@deffn {Procedure} build-expression->derivation store name exp @
       [#:system (%current-system)] [#:inputs '()] @ [#:outputs '("out")] [#:hash
#f] [#:hash-algo #f] @ [#:recursive? #f] [#:env-vars '()] [#:modules '()] @
[#:references-graphs #f] [#:allowed-references #f] @
[#:disallowed-references #f] @ [#:local-build? #f] [#:substitutable? #t]
[#:guile-for-build #f] Return a derivation that executes Scheme expression
@var{exp} as a builder for derivation @var{name}.  @var{inputs} must be a
list of @code{(name drv-path sub-drv)} tuples; when @var{sub-drv} is
omitted, @code{"out"} is assumed.  @var{modules} is a list of names of Guile
modules from the current search path to be copied in the store, compiled,
and made available in the load path during the execution of
@var{exp}---e.g., @code{((guix build utils) (guix build gnu-build-system))}.

@var{exp} is evaluated in an environment where @code{%outputs} is bound to a
list of output/path pairs, and where @code{%build-inputs} is bound to a list
of string/output-path pairs made from @var{inputs}.  Optionally,
@var{env-vars} is a list of string pairs specifying the name and value of
environment variables visible to the builder.  The builder terminates by
passing the result of @var{exp} to @code{exit}; thus, when @var{exp} returns
@code{#f}, the build is considered to have failed.

@var{exp} is built using @var{guile-for-build} (a derivation).  When
@var{guile-for-build} is omitted or is @code{#f}, the value of the
@code{%guile-for-build} fluid is used instead.

See the @code{derivation} procedure for the meaning of
@var{references-graphs}, @var{allowed-references},
@var{disallowed-references}, @var{local-build?}, and @var{substitutable?}.
@end deffn

@noindent
Here's an example of a single-output derivation that creates a directory
containing one file:

@lisp
(let ((builder '(let ((out (assoc-ref %outputs "out")))
                  (mkdir out)    ; create /gnu/store/@dots{}-goo
                  (call-with-output-file (string-append out "/test")
                    (lambda (p)
                      (display '(hello guix) p))))))
  (build-expression->derivation store "goo" builder))

@result{} #<derivation /gnu/store/@dots{}-goo.drv => @dots{}>
@end lisp


@node A mônada do armazém
@section A mônada do armazém

@cindex monad

The procedures that operate on the store described in the previous sections
all take an open connection to the build daemon as their first argument.
Although the underlying model is functional, they either have side effects
or depend on the current state of the store.

The former is inconvenient: the connection to the build daemon has to be
carried around in all those functions, making it impossible to compose
functions that do not take that parameter with functions that do.  The
latter can be problematic: since store operations have side effects and/or
depend on external state, they have to be properly sequenced.

@cindex monadic values
@cindex monadic functions
This is where the @code{(guix monads)} module comes in.  This module
provides a framework for working with @dfn{monads}, and a particularly
useful monad for our uses, the @dfn{store monad}.  Monads are a construct
that allows two things: associating ``context'' with values (in our case,
the context is the store), and building sequences of computations (here
computations include accesses to the store).  Values in a monad---values
that carry this additional context---are called @dfn{monadic values};
procedures that return such values are called @dfn{monadic procedures}.

Consider this ``normal'' procedure:

@lisp
(define (sh-symlink store)
  ;; Return a derivation that symlinks the 'bash' executable.
  (let* ((drv (package-derivation store bash))
         (out (derivation->output-path drv))
         (sh  (string-append out "/bin/bash")))
    (build-expression->derivation store "sh"
                                  `(symlink ,sh %output))))
@end lisp

Using @code{(guix monads)} and @code{(guix gexp)}, it may be rewritten as a
monadic function:

@lisp
(define (sh-symlink)
  ;; Same, but return a monadic value.
  (mlet %store-monad ((drv (package->derivation bash)))
    (gexp->derivation "sh"
                      #~(symlink (string-append #$drv "/bin/bash")
                                 #$output))))
@end lisp

There are several things to note in the second version: the @code{store}
parameter is now implicit and is ``threaded'' in the calls to the
@code{package->derivation} and @code{gexp->derivation} monadic procedures,
and the monadic value returned by @code{package->derivation} is @dfn{bound}
using @code{mlet} instead of plain @code{let}.

As it turns out, the call to @code{package->derivation} can even be omitted
since it will take place implicitly, as we will see later
(@pxref{Expressões-G}):

@lisp
(define (sh-symlink)
  (gexp->derivation "sh"
                    #~(symlink (string-append #$bash "/bin/bash")
                               #$output)))
@end lisp

@c See
@c <https://syntaxexclamation.wordpress.com/2014/06/26/escaping-continuations/>
@c for the funny quote.
Calling the monadic @code{sh-symlink} has no effect.  As someone once said,
``you exit a monad like you exit a building on fire: by running''.  So, to
exit the monad and get the desired effect, one must use
@code{run-with-store}:

@lisp
(run-with-store (open-connection) (sh-symlink))
@result{} /gnu/store/...-sh-symlink
@end lisp

Note that the @code{(guix monad-repl)} module extends the Guile REPL with
new ``commands'' to make it easier to deal with monadic procedures:
@code{run-in-store}, and @code{enter-store-monad} (@pxref{Usando Guix interativamente}).  The former is used to ``run'' a single monadic value
through the store:

@example
scheme@@(guile-user)> ,run-in-store (package->derivation hello)
$1 = #<derivation /gnu/store/@dots{}-hello-2.9.drv => @dots{}>
@end example

The latter enters a recursive REPL, where all the return values are
automatically run through the store:

@example
scheme@@(guile-user)> ,enter-store-monad
store-monad@@(guile-user) [1]> (package->derivation hello)
$2 = #<derivation /gnu/store/@dots{}-hello-2.9.drv => @dots{}>
store-monad@@(guile-user) [1]> (text-file "foo" "Hello!")
$3 = "/gnu/store/@dots{}-foo"
store-monad@@(guile-user) [1]> ,q
scheme@@(guile-user)>
@end example

@noindent
Note that non-monadic values cannot be returned in the @code{store-monad}
REPL.

Other meta-commands are available at the REPL, such as @code{,build} to
build a file-like object (@pxref{Usando Guix interativamente}).

The main syntactic forms to deal with monads in general are provided by the
@code{(guix monads)} module and are described below.

@defmac with-monad monad body @dots{}
Evaluate any @code{>>=} or @code{return} forms in @var{body} as being in
@var{monad}.
@end defmac

@defmac return val
Return a monadic value that encapsulates @var{val}.
@end defmac

@defmac >>= mval mproc @dots{}
@dfn{Bind} monadic value @var{mval}, passing its ``contents'' to monadic
procedures @var{mproc}@dots{}@footnote{This operation is commonly referred
to as ``bind'', but that name denotes an unrelated procedure in Guile.  Thus
we use this somewhat cryptic symbol inherited from the Haskell language.}.
There can be one @var{mproc} or several of them, as in this example:

@lisp
(run-with-state
    (with-monad %state-monad
      (>>= (return 1)
           (lambda (x) (return (+ 1 x)))
           (lambda (x) (return (* 2 x)))))
  'some-state)

@result{} 4
@result{} some-state
@end lisp
@end defmac

@defmac mlet monad ((var mval) @dots{}) body @dots{}
@defmacx mlet* monad ((var mval) @dots{}) body @dots{}
Bind the variables @var{var} to the monadic values @var{mval} in @var{body},
which is a sequence of expressions.  As with the bind operator, this can be
thought of as ``unpacking'' the raw, non-monadic value ``contained'' in
@var{mval} and making @var{var} refer to that raw, non-monadic value within
the scope of the @var{body}.  The form (@var{var} -> @var{val}) binds
@var{var} to the ``normal'' value @var{val}, as per @code{let}.  The binding
operations occur in sequence from left to right.  The last expression of
@var{body} must be a monadic expression, and its result will become the
result of the @code{mlet} or @code{mlet*} when run in the @var{monad}.

@code{mlet*} is to @code{mlet} what @code{let*} is to @code{let}
(@pxref{Local Bindings,,, guile, GNU Guile Reference Manual}).
@end defmac

@defmac mbegin monad mexp @dots{}
Bind @var{mexp} and the following monadic expressions in sequence, returning
the result of the last expression.  Every expression in the sequence must be
a monadic expression.

This is akin to @code{mlet}, except that the return values of the monadic
expressions are ignored.  In that sense, it is analogous to @code{begin},
but applied to monadic expressions.
@end defmac

@defmac mwhen condition mexp0 mexp* @dots{}
When @var{condition} is true, evaluate the sequence of monadic expressions
@var{mexp0}..@var{mexp*} as in an @code{mbegin}.  When @var{condition} is
false, return @code{*unspecified*} in the current monad.  Every expression
in the sequence must be a monadic expression.
@end defmac

@defmac munless condition mexp0 mexp* @dots{}
When @var{condition} is false, evaluate the sequence of monadic expressions
@var{mexp0}..@var{mexp*} as in an @code{mbegin}.  When @var{condition} is
true, return @code{*unspecified*} in the current monad.  Every expression in
the sequence must be a monadic expression.
@end defmac

@cindex state monad
The @code{(guix monads)} module provides the @dfn{state monad}, which allows
an additional value---the state---to be @emph{threaded} through monadic
procedure calls.

@defvar %state-monad
The state monad.  Procedures in the state monad can access and change the
state that is threaded.

Consider the example below.  The @code{square} procedure returns a value in
the state monad.  It returns the square of its argument, but also increments
the current state value:

@lisp
(define (square x)
  (mlet %state-monad ((count (current-state)))
    (mbegin %state-monad
      (set-current-state (+ 1 count))
      (return (* x x)))))

(run-with-state (sequence %state-monad (map square (iota 3))) 0)
@result{} (0 1 4)
@result{} 3
@end lisp

When ``run'' through @code{%state-monad}, we obtain that additional state
value, which is the number of @code{square} calls.
@end defvar

@deffn {Monadic Procedure} current-state
Return the current state as a monadic value.
@end deffn

@deffn {Monadic Procedure} set-current-state @var{value}
Set the current state to @var{value} and return the previous state as a
monadic value.
@end deffn

@deffn {Monadic Procedure} state-push @var{value}
Push @var{value} to the current state, which is assumed to be a list, and
return the previous state as a monadic value.
@end deffn

@deffn {Monadic Procedure} state-pop
Pop a value from the current state and return it as a monadic value.  The
state is assumed to be a list.
@end deffn

@deffn {Procedure} run-with-state mval [state]
Run monadic value @var{mval} starting with @var{state} as the initial
state.  Return two values: the resulting value, and the resulting state.
@end deffn

The main interface to the store monad, provided by the @code{(guix store)}
module, is as follows.

@defvar %store-monad
The store monad---an alias for @code{%state-monad}.

Values in the store monad encapsulate accesses to the store.  When its
effect is needed, a value of the store monad must be ``evaluated'' by
passing it to the @code{run-with-store} procedure (see below).
@end defvar

@deffn {Procedure} run-with-store store mval @
  [#:guile-for-build] [#:system (%current-system)] Run @var{mval}, a monadic
value in the store monad, in @var{store}, an open store connection.
@end deffn

@deffn {Monadic Procedure} text-file @var{name} @var{text} [@var{references}]
Return as a monadic value the absolute file name in the store of the file
containing @var{text}, a string.  @var{references} is a list of store items
that the resulting text file refers to; it defaults to the empty list.
@end deffn

@deffn {Monadic Procedure} binary-file @var{name} @var{data} [@var{references}]
Return as a monadic value the absolute file name in the store of the file
containing @var{data}, a bytevector.  @var{references} is a list of store
items that the resulting binary file refers to; it defaults to the empty
list.
@end deffn

@deffn {Monadic Procedure} interned-file @var{file} [@var{name}] @
         [#:recursive? #t] [#:select? (const #t)] Return the name of @var{file} once
interned in the store.  Use @var{name} as its store name, or the basename of
@var{file} if @var{name} is omitted.

When @var{recursive?} is true, the contents of @var{file} are added
recursively; if @var{file} designates a flat file and @var{recursive?} is
true, its contents are added, and its permission bits are kept.

When @var{recursive?} is true, call @code{(@var{select?} @var{file}
@var{stat})} for each directory entry, where @var{file} is the entry's
absolute file name and @var{stat} is the result of @code{lstat}; exclude
entries for which @var{select?} does not return true.

The example below adds a file to the store, under two different names:

@lisp
(run-with-store (open-connection)
  (mlet %store-monad ((a (interned-file "README"))
                      (b (interned-file "README" "LEGU-MIN")))
    (return (list a b))))

@result{} ("/gnu/store/rwm@dots{}-README" "/gnu/store/44i@dots{}-LEGU-MIN")
@end lisp

@end deffn

The @code{(guix packages)} module exports the following package-related
monadic procedures:

@deffn {Monadic Procedure} package-file @var{package} [@var{file}] @
       [#:system (%current-system)] [#:target #f] @ [#:output "out"] Return as a
monadic value in the absolute file name of @var{file} within the
@var{output} directory of @var{package}.  When @var{file} is omitted, return
the name of the @var{output} directory of @var{package}.  When @var{target}
is true, use it as a cross-compilation target triplet.

Note that this procedure does @emph{not} build @var{package}.  Thus, the
result might or might not designate an existing file.  We recommend not
using this procedure unless you know what you are doing.
@end deffn

@deffn {Monadic Procedure} package->derivation @var{package} [@var{system}]
@deffnx {Monadic Procedure} package->cross-derivation @var{package} @
          @var{target} [@var{system}] Monadic version of @code{package-derivation} and
@code{package-cross-derivation} (@pxref{Definindo pacotes}).
@end deffn


@node Expressões-G
@section Expressões-G

@cindex G-expression
@cindex build code quoting
So we have ``derivations'', which represent a sequence of build actions to
be performed to produce an item in the store (@pxref{Derivações}).  These
build actions are performed when asking the daemon to actually build the
derivations; they are run by the daemon in a container (@pxref{Invocando guix-daemon}).

@cindex code staging
@cindex staging, of code
@cindex strata of code
It should come as no surprise that we like to write these build actions in
Scheme.  When we do that, we end up with two @dfn{strata} of Scheme
code@footnote{The term @dfn{stratum} in this context was coined by Manuel
Serrano et al.@: in the context of their work on Hop.  Oleg Kiselyov, who
has written insightful
@url{http://okmij.org/ftp/meta-programming/#meta-scheme, essays and code on
this topic}, refers to this kind of code generation as @dfn{staging}.}: the
``host code''---code that defines packages, talks to the daemon, etc.---and
the ``build code''---code that actually performs build actions, such as
making directories, invoking @command{make}, and so on (@pxref{Fases de construção}).

To describe a derivation and its build actions, one typically needs to embed
build code inside host code.  It boils down to manipulating build code as
data, and the homoiconicity of Scheme---code has a direct representation as
data---comes in handy for that.  But we need more than the normal
@code{quasiquote} mechanism in Scheme to construct build expressions.

The @code{(guix gexp)} module implements @dfn{G-expressions}, a form of
S-expressions adapted to build expressions.  G-expressions, or @dfn{gexps},
consist essentially of three syntactic forms: @code{gexp}, @code{ungexp},
and @code{ungexp-splicing} (or simply: @code{#~}, @code{#$}, and
@code{#$@@}), which are comparable to @code{quasiquote}, @code{unquote}, and
@code{unquote-splicing}, respectively (@pxref{Expression Syntax,
@code{quasiquote},, guile, GNU Guile Reference Manual}).  However, there are
major differences:

@itemize
@item
Gexps are meant to be written to a file and run or manipulated by other
processes.

@item
When a high-level object such as a package or derivation is unquoted inside
a gexp, the result is as if its output file name had been introduced.

@item
Gexps carry information about the packages or derivations they refer to, and
these dependencies are automatically added as inputs to the build processes
that use them.
@end itemize

@cindex lowering, of high-level objects in gexps
This mechanism is not limited to package and derivation objects:
@dfn{compilers} able to ``lower'' other high-level objects to derivations or
files in the store can be defined, such that these objects can also be
inserted into gexps.  For example, a useful type of high-level objects that
can be inserted in a gexp is ``file-like objects'', which make it easy to
add files to the store and to refer to them in derivations and such (see
@code{local-file} and @code{plain-file} below).

To illustrate the idea, here is an example of a gexp:

@lisp
(define build-exp
  #~(begin
      (mkdir #$output)
      (chdir #$output)
      (symlink (string-append #$coreutils "/bin/ls")
               "list-files")))
@end lisp

This gexp can be passed to @code{gexp->derivation}; we obtain a derivation
that builds a directory containing exactly one symlink to
@file{/gnu/store/@dots{}-coreutils-8.22/bin/ls}:

@lisp
(gexp->derivation "the-thing" build-exp)
@end lisp

As one would expect, the @code{"/gnu/store/@dots{}-coreutils-8.22"} string
is substituted to the reference to the @var{coreutils} package in the actual
build code, and @var{coreutils} is automatically made an input to the
derivation.  Likewise, @code{#$output} (equivalent to @code{(ungexp
output)}) is replaced by a string containing the directory name of the
output of the derivation.

@cindex compilação cruzada
In a cross-compilation context, it is useful to distinguish between
references to the @emph{native} build of a package---that can run on the
host---versus references to cross builds of a package.  To that end, the
@code{#+} plays the same role as @code{#$}, but is a reference to a native
package build:

@lisp
(gexp->derivation "vi"
   #~(begin
       (mkdir #$output)
       (mkdir (string-append #$output "/bin"))
       (system* (string-append #+coreutils "/bin/ln")
                "-s"
                (string-append #$emacs "/bin/emacs")
                (string-append #$output "/bin/vi")))
   #:target "aarch64-linux-gnu")
@end lisp

@noindent
In the example above, the native build of @var{coreutils} is used, so that
@command{ln} can actually run on the host; but then the cross-compiled build
of @var{emacs} is referenced.

@cindex imported modules, for gexps
@findex with-imported-modules
Another gexp feature is @dfn{imported modules}: sometimes you want to be
able to use certain Guile modules from the ``host environment'' in the gexp,
so those modules should be imported in the ``build environment''.  The
@code{with-imported-modules} form allows you to express that:

@lisp
(let ((build (with-imported-modules '((guix build utils))
               #~(begin
                   (use-modules (guix build utils))
                   (mkdir-p (string-append #$output "/bin"))))))
  (gexp->derivation "empty-dir"
                    #~(begin
                        #$build
                        (display "success!\n")
                        #t)))
@end lisp

@noindent
In this example, the @code{(guix build utils)} module is automatically
pulled into the isolated build environment of our gexp, such that
@code{(use-modules (guix build utils))} works as expected.

@cindex module closure
@findex source-module-closure
Usually you want the @emph{closure} of the module to be imported---i.e., the
module itself and all the modules it depends on---rather than just the
module; failing to do that, attempts to use the module will fail because of
missing dependent modules.  The @code{source-module-closure} procedure
computes the closure of a module by looking at its source file headers,
which comes in handy in this case:

@lisp
(use-modules (guix modules))   ;for 'source-module-closure'

(with-imported-modules (source-module-closure
                         '((guix build utils)
                           (gnu build image)))
  (gexp->derivation "something-with-vms"
                    #~(begin
                        (use-modules (guix build utils)
                                     (gnu build image))
                        @dots{})))
@end lisp

@cindex extensions, for gexps
@findex with-extensions
In the same vein, sometimes you want to import not just pure-Scheme modules,
but also ``extensions'' such as Guile bindings to C libraries or other
``full-blown'' packages.  Say you need the @code{guile-json} package
available on the build side, here's how you would do it:

@lisp
(use-modules (gnu packages guile))  ;for 'guile-json'

(with-extensions (list guile-json)
  (gexp->derivation "something-with-json"
                    #~(begin
                        (use-modules (json))
                        @dots{})))
@end lisp

The syntactic form to construct gexps is summarized below.

@defmac #~@var{exp}
@defmacx (gexp @var{exp})
Return a G-expression containing @var{exp}.  @var{exp} may contain one or
more of the following forms:

@table @code
@item #$@var{obj}
@itemx (ungexp @var{obj})
Introduce a reference to @var{obj}.  @var{obj} may have one of the supported
types, for example a package or a derivation, in which case the
@code{ungexp} form is replaced by its output file name---e.g.,
@code{"/gnu/store/@dots{}-coreutils-8.22}.

If @var{obj} is a list, it is traversed and references to supported objects
are substituted similarly.

If @var{obj} is another gexp, its contents are inserted and its dependencies
are added to those of the containing gexp.

If @var{obj} is another kind of object, it is inserted as is.

@item #$@var{obj}:@var{saída}
@itemx (ungexp @var{obj} @var{saída})
This is like the form above, but referring explicitly to the @var{output} of
@var{obj}---this is useful when @var{obj} produces multiple outputs
(@pxref{Pacotes com múltiplas saídas}).

Sometimes a gexp unconditionally refers to the @code{"out"} output, but the
user of that gexp would still like to insert a reference to another output.
The @code{gexp-input} procedure aims to address that.  @xref{gexp-input}.

@item #+@var{obj}
@itemx #+@var{obj}:output
@itemx (ungexp-native @var{obj})
@itemx (ungexp-native @var{obj} @var{output})
Same as @code{ungexp}, but produces a reference to the @emph{native} build
of @var{obj} when used in a cross compilation context.

@item #$output[:@var{saída}]
@itemx (ungexp output [@var{saída}])
Insert a reference to derivation output @var{output}, or to the main output
when @var{output} is omitted.

This only makes sense for gexps passed to @code{gexp->derivation}.

@item #$@@@var{lst}
@itemx (ungexp-splicing @var{lst})
Like the above, but splices the contents of @var{lst} inside the containing
list.

@item #+@@@var{lst}
@itemx (ungexp-native-splicing @var{lst})
Like the above, but refers to native builds of the objects listed in
@var{lst}.

@end table

G-expressions created by @code{gexp} or @code{#~} are run-time objects of
the @code{gexp?} type (see below).
@end defmac

@defmac with-imported-modules modules body@dots{}
Mark the gexps defined in @var{body}@dots{} as requiring @var{modules} in
their execution environment.

Each item in @var{modules} can be the name of a module, such as @code{(guix
build utils)}, or it can be a module name, followed by an arrow, followed by
a file-like object:

@lisp
`((guix build utils)
  (guix gcrypt)
  ((guix config) => ,(scheme-file "config.scm"
                                  #~(define-module @dots{}))))
@end lisp

@noindent
In the example above, the first two modules are taken from the search path,
and the last one is created from the given file-like object.

This form has @emph{lexical} scope: it has an effect on the gexps directly
defined in @var{body}@dots{}, but not on those defined, say, in procedures
called from @var{body}@dots{}.
@end defmac

@defmac with-extensions extensions body@dots{}
Mark the gexps defined in @var{body}@dots{} as requiring @var{extensions} in
their build and execution environment.  @var{extensions} is typically a list
of package objects such as those defined in the @code{(gnu packages guile)}
module.

Concretely, the packages listed in @var{extensions} are added to the load
path while compiling imported modules in @var{body}@dots{}; they are also
added to the load path of the gexp returned by @var{body}@dots{}.
@end defmac

@deffn {Procedure} gexp? obj
Return @code{#t} if @var{obj} is a G-expression.
@end deffn

G-expressions are meant to be written to disk, either as code building some
derivation, or as plain files in the store.  The monadic procedures below
allow you to do that (@pxref{A mônada do armazém}, for more information about
monads).

@deffn {Monadic Procedure} gexp->derivation @var{name} @var{exp} @
       [#:system (%current-system)] [#:target #f] [#:graft? #t] @ [#:hash #f]
[#:hash-algo #f] @ [#:recursive? #f] [#:env-vars '()] [#:modules '()] @
[#:module-path @code{%load-path}] @ [#:effective-version "2.2"] @
[#:references-graphs #f] [#:allowed-references #f] @
[#:disallowed-references #f] @ [#:leaked-env-vars #f] @ [#:script-name
(string-append @var{name} "-builder")] @ [#:deprecation-warnings #f] @
[#:local-build? #f] [#:substitutable? #t] @ [#:properties '()]
[#:guile-for-build #f] Return a derivation @var{name} that runs @var{exp} (a
gexp) with @var{guile-for-build} (a derivation) on @var{system}; @var{exp}
is stored in a file called @var{script-name}.  When @var{target} is true, it
is used as the cross-compilation target triplet for packages referred to by
@var{exp}.

@var{modules} is deprecated in favor of @code{with-imported-modules}.  Its
meaning is to make @var{modules} available in the evaluation context of
@var{exp}; @var{modules} is a list of names of Guile modules searched in
@var{module-path} to be copied in the store, compiled, and made available in
the load path during the execution of @var{exp}---e.g., @code{((guix build
utils) (guix build gnu-build-system))}.

@var{effective-version} determines the string to use when adding extensions
of @var{exp} (see @code{with-extensions}) to the search path---e.g.,
@code{"2.2"}.

@var{graft?} determines whether packages referred to by @var{exp} should be
grafted when applicable.

When @var{references-graphs} is true, it must be a list of tuples of one of
the following forms:

@example
(@var{file-name} @var{obj})
(@var{file-name} @var{obj} @var{output})
(@var{file-name} @var{gexp-input})
(@var{file-name} @var{store-item})
@end example

The right-hand-side of each element of @var{references-graphs} is
automatically made an input of the build process of @var{exp}.  In the build
environment, each @var{file-name} contains the reference graph of the
corresponding item, in a simple text format.

@var{allowed-references} must be either @code{#f} or a list of output names
and packages.  In the latter case, the list denotes store items that the
result is allowed to refer to.  Any reference to another store item will
lead to a build error.  Similarly for @var{disallowed-references}, which can
list items that must not be referenced by the outputs.

@var{deprecation-warnings} determines whether to show deprecation warnings
while compiling modules.  It can be @code{#f}, @code{#t}, or
@code{'detailed}.

The other arguments are as for @code{derivation} (@pxref{Derivações}).
@end deffn

@cindex file-like objects
The @code{local-file}, @code{plain-file}, @code{computed-file},
@code{program-file}, and @code{scheme-file} procedures below return
@dfn{file-like objects}.  That is, when unquoted in a G-expression, these
objects lead to a file in the store.  Consider this G-expression:

@lisp
#~(system* #$(file-append glibc "/sbin/nscd") "-f"
           #$(local-file "/tmp/my-nscd.conf"))
@end lisp

The effect here is to ``intern'' @file{/tmp/my-nscd.conf} by copying it to
the store.  Once expanded, for instance @i{via} @code{gexp->derivation}, the
G-expression refers to that copy under @file{/gnu/store}; thus, modifying or
removing the file in @file{/tmp} does not have any effect on what the
G-expression does.  @code{plain-file} can be used similarly; it differs in
that the file content is directly passed as a string.

@deffn {Procedure} local-file file [name] [#:recursive? #f] [#:select? (const #t)]
Return an object representing local file @var{file} to add to the store;
this object can be used in a gexp.  If @var{file} is a literal string
denoting a relative file name, it is looked up relative to the source file
where it appears; if @var{file} is not a literal string, it is looked up
relative to the current working directory at run time.  @var{file} will be
added to the store under @var{name}--by default the base name of @var{file}.

When @var{recursive?} is true, the contents of @var{file} are added
recursively; if @var{file} designates a flat file and @var{recursive?} is
true, its contents are added, and its permission bits are kept.

When @var{recursive?} is true, call @code{(@var{select?} @var{file}
@var{stat})} for each directory entry, where @var{file} is the entry's
absolute file name and @var{stat} is the result of @code{lstat}; exclude
entries for which @var{select?} does not return true.

@findex assume-valid-file-name
@var{file} can be wrapped in the @code{assume-valid-file-name} syntactic
keyword. When this is done, there will not be a warning when
@code{local-file} is used with a non-literal path.  The path is still looked
up relative to the current working directory at run time.  Wrapping is done
like this:

@lisp
(define alice-key-file-path "alice.pub")
;; ...
(local-file (assume-valid-file-name alice-key-file-path))
@end lisp

@cindex relative file name, in @code{local-file}
@findex assume-source-relative-file-name
@var{file} can be wrapped in the @code{assume-source-relative-file-name}
syntactic keyword.  When this is done, the file name will be looked up
relative to the source file where it appears even when it is not a string
literal.

This is the declarative counterpart of the @code{interned-file} monadic
procedure (@pxref{A mônada do armazém, @code{interned-file}}).
@end deffn

@deffn {Procedure} plain-file name content
Return an object representing a text file called @var{name} with the given
@var{content} (a string or a bytevector) to be added to the store.

This is the declarative counterpart of @code{text-file}.
@end deffn

@deffn {Procedure} computed-file @var{name} @var{gexp} @
  [#:guile] [#:local-build? #t] [#:options '()] Return an object representing
the store item @var{name}, a file or directory computed by @var{gexp}.  When
@var{local-build?} is true (the default), the derivation is built locally.
@var{options} is a list of additional arguments to pass to
@code{gexp->derivation}.

This is the declarative counterpart of @code{gexp->derivation}.
@end deffn

@deffn {Monadic Procedure} gexp->script @var{name} @var{exp} @
  [#:guile (default-guile)] [#:module-path %load-path] @ [#:system
(%current-system)] [#:target 'current] Return an executable script
@var{name} that runs @var{exp} using @var{guile}, with @var{exp}'s imported
modules in its search path.  Look up @var{exp}'s modules in
@var{module-path}.

The example below builds a script that simply invokes the @command{ls}
command:

@lisp
(use-modules (guix gexp) (gnu packages base))

(gexp->script "list-files"
              #~(execl #$(file-append coreutils "/bin/ls")
                       "ls"))
@end lisp

When ``running'' it through the store (@pxref{A mônada do armazém,
@code{run-with-store}}), we obtain a derivation that produces an executable
file @file{/gnu/store/@dots{}-list-files} along these lines:

@example
#!/gnu/store/@dots{}-guile-2.0.11/bin/guile -ds
!#
(execl "/gnu/store/@dots{}-coreutils-8.22"/bin/ls" "ls")
@end example
@end deffn

@deffn {Procedure} program-file name exp [#:guile #f] [#:module-path %load-path]
Return an object representing the executable store item @var{name} that runs
@var{gexp}.  @var{guile} is the Guile package used to execute that script.
Imported modules of @var{gexp} are looked up in @var{module-path}.

This is the declarative counterpart of @code{gexp->script}.
@end deffn

@deffn {Monadic Procedure} gexp->file @var{name} @var{exp} @
            [#:set-load-path? #t] [#:module-path %load-path] @ [#:splice? #f] [#:guile
(default-guile)] @ [#:system (%current-system)] [#:target 'current] Return a
derivation that builds a file @var{name} containing @var{exp}.  When
@var{splice?} is true, @var{exp} is considered to be a list of expressions
that will be spliced in the resulting file.

When @var{set-load-path?} is true, emit code in the resulting file to set
@code{%load-path} and @code{%load-compiled-path} to honor @var{exp}'s
imported modules.  Look up @var{exp}'s modules in @var{module-path}.

The resulting file holds references to all the dependencies of @var{exp} or
a subset thereof.
@end deffn

@deffn {Procedure} scheme-file name exp [#:splice? #f] @
           [#:guile #f] [#:set-load-path? #t] Return an object representing the Scheme
file @var{name} that contains @var{exp}.  @var{guile} is the Guile package
used to produce that file.

This is the declarative counterpart of @code{gexp->file}.
@end deffn

@deffn {Monadic Procedure} text-file* @var{name} @var{text} @dots{}
Return as a monadic value a derivation that builds a text file containing
all of @var{text}.  @var{text} may list, in addition to strings, objects of
any type that can be used in a gexp: packages, derivations, local file
objects, etc.  The resulting store file holds references to all these.

This variant should be preferred over @code{text-file} anytime the file to
create will reference items from the store.  This is typically the case when
building a configuration file that embeds store file names, like this:

@lisp
(define (profile.sh)
  ;; Return the name of a shell script in the store that
  ;; initializes the 'PATH' environment variable.
  (text-file* "profile.sh"
              "export PATH=" coreutils "/bin:"
              grep "/bin:" sed "/bin\n"))
@end lisp

In this example, the resulting @file{/gnu/store/@dots{}-profile.sh} file
will reference @var{coreutils}, @var{grep}, and @var{sed}, thereby
preventing them from being garbage-collected during its lifetime.
@end deffn

@deffn {Procedure} mixed-text-file name text @dots{}
Return an object representing store file @var{name} containing @var{text}.
@var{text} is a sequence of strings and file-like objects, as in:

@lisp
(mixed-text-file "profile"
                 "export PATH=" coreutils "/bin:" grep "/bin")
@end lisp

This is the declarative counterpart of @code{text-file*}.
@end deffn

@deffn {Procedure} file-union name files [#:dangling-symlinks? #f]
Return a @code{<computed-file>} that builds a directory containing all of
@var{files}.  Each item in @var{files} must be a two-element list where the
first element is the file name to use in the new directory, and the second
element is a gexp denoting the target file.  @code{#:dangling-symlinks?}
controls if gexps must lower to an existing file.  Here's an example:

@lisp
(file-union "etc"
            `(("hosts" ,(plain-file "hosts"
                                    "127.0.0.1 localhost"))
              ("bashrc" ,(plain-file "bashrc"
                                     "alias ls='ls --color=auto'"))))
@end lisp

This yields an @code{etc} directory containing these two files.
@end deffn

@deffn {Procedure} symlink-to target
Return a @code{<computed-file>} that is a symbolic link to target.  Note,
that the target does not need to exist at the build time.  One of uses is to
put arbitrary symlinks into user's home:

@lisp
(service home-files-service-type
  `(("Sync" ,(symlink-to "/storage/Sync"))))
@end lisp
@end deffn

@deffn {Procedure} directory-union name things
Return a directory that is the union of @var{things}, where @var{things} is
a list of file-like objects denoting directories.  For example:

@lisp
(directory-union "guile+emacs" (list guile emacs))
@end lisp

yields a directory that is the union of the @code{guile} and @code{emacs}
packages.
@end deffn

@deffn {Procedure} file-append obj suffix @dots{}
Return a file-like object that expands to the concatenation of @var{obj} and
@var{suffix}, where @var{obj} is a lowerable object and each @var{suffix} is
a string.

As an example, consider this gexp:

@lisp
(gexp->script "run-uname"
              #~(system* #$(file-append coreutils
                                        "/bin/uname")))
@end lisp

The same effect could be achieved with:

@lisp
(gexp->script "run-uname"
              #~(system* (string-append #$coreutils
                                        "/bin/uname")))
@end lisp

There is one difference though: in the @code{file-append} case, the
resulting script contains the absolute file name as a string, whereas in the
second case, the resulting script contains a @code{(string-append @dots{})}
expression to construct the file name @emph{at run time}.
@end deffn

@defmac let-system system body@dots{}
@defmacx let-system (system target) body@dots{}
Bind @var{system} to the currently targeted system---e.g.,
@code{"x86_64-linux"}---within @var{body}.

In the second case, additionally bind @var{target} to the current
cross-compilation target---a GNU triplet such as
@code{"arm-linux-gnueabihf"}---or @code{#f} if we are not cross-compiling.

@code{let-system} is useful in the occasional case where the object spliced
into the gexp depends on the target system, as in this example:

@lisp
#~(system*
   #+(let-system system
       (cond ((string-prefix? "armhf-" system)
              (file-append qemu "/bin/qemu-system-arm"))
             ((string-prefix? "x86_64-" system)
              (file-append qemu "/bin/qemu-system-x86_64"))
             (else
              (error "dunno!"))))
   "-net" "user" #$image)
@end lisp
@end defmac

@defmac with-parameters ((parameter value) @dots{}) exp
This macro is similar to the @code{parameterize} form for dynamically-bound
@dfn{parameters} (@pxref{Parameters,,, guile, GNU Guile Reference Manual}).
The key difference is that it takes effect when the file-like object
returned by @var{exp} is lowered to a derivation or store item.

A typical use of @code{with-parameters} is to force the system in effect for
a given object:

@lisp
(with-parameters ((%current-system "i686-linux"))
  coreutils)
@end lisp

The example above returns an object that corresponds to the i686 build of
Coreutils, regardless of the current value of @code{%current-system}.
@end defmac

@anchor{gexp-input}
@deffn {Procedure} gexp-input @var{obj} [@var{output}] [#:native? #f]
Return a @dfn{gexp input} record for the given @var{output} of file-like
object @var{obj}, with @code{#:native?} determining whether this is a native
reference (as with @code{ungexp-native}) or not.

This procedure is helpful when you want to pass a reference to a specific
output of an object to some procedure that may not know about that output.
For example, assume you have this procedure, which takes one file-like
object:

@lisp
(define (make-symlink target)
  (computed-file "the-symlink"
                 #~(symlink #$target #$output)))
@end lisp

Here @code{make-symlink} can only ever refer to the default output of
@var{target}---the @code{"out"} output (@pxref{Pacotes com múltiplas saídas}).  To have it refer to, say, the @code{"lib"} output of the
@code{hwloc} package, you can call it like so:

@lisp
(make-symlink (gexp-input hwloc "lib"))
@end lisp

You can also compose it like any other file-like object:

@lisp
(make-symlink
  (file-append (gexp-input hwloc "lib") "/lib/libhwloc.so"))
@end lisp
@end deffn

Of course, in addition to gexps embedded in ``host'' code, there are also
modules containing build tools.  To make it clear that they are meant to be
used in the build stratum, these modules are kept in the @code{(guix build
@dots{})} name space.

@cindex lowering, of high-level objects in gexps
Internally, high-level objects are @dfn{lowered}, using their compiler, to
either derivations or store items.  For instance, lowering a package yields
a derivation, and lowering a @code{plain-file} yields a store item.  This is
achieved using the @code{lower-object} monadic procedure.

@deffn {Monadic Procedure} lower-object @var{obj} [@var{system}] @
           [#:target #f] Return as a value in @code{%store-monad} the derivation or
store item corresponding to @var{obj} for @var{system}, cross-compiling for
@var{target} if @var{target} is true.  @var{obj} must be an object that has
an associated gexp compiler, such as a @code{<package>}.
@end deffn

@deffn {Procedure} gexp->approximate-sexp gexp
Sometimes, it may be useful to convert a G-exp into a S-exp.  For example,
some linters (@pxref{Invocando guix lint}) peek into the build phases of a
package to detect potential problems.  This conversion can be achieved with
this procedure.  However, some information can be lost in the process.  More
specifically, lowerable objects will be silently replaced with some
arbitrary object -- currently the list @code{(*approximate*)}, but this may
change.
@end deffn

@node Invocando guix repl
@section Invocando @command{guix repl}

@cindex @command{guix repl}
@cindex REPL, read-eval-print loop, script
The @command{guix repl} command makes it easier to program Guix in Guile by
launching a Guile @dfn{read-eval-print loop} (REPL) for interactive
programming (@pxref{Using Guile Interactively,,, guile, GNU Guile Reference
Manual}), or by running Guile scripts (@pxref{Running Guile Scripts,,,
guile, GNU Guile Reference Manual}).  Compared to just launching the
@command{guile} command, @command{guix repl} guarantees that all the Guix
modules and all its dependencies are available in the search path.

A sintaxe geral é:

@example
guix repl @var{options} [@var{file} @var{args}]
@end example

When a @var{file} argument is provided, @var{file} is executed as a Guile
script:

@example
guix repl my-script.scm
@end example

To pass arguments to the script, use @code{--} to prevent them from being
interpreted as arguments to @command{guix repl} itself:

@example
guix repl -- my-script.scm --input=foo.txt
@end example

To make a script executable directly from the shell, using the guix
executable that is on the user's search path, add the following two lines at
the top of the script:

@example
@code{#!/usr/bin/env -S guix repl --}
@code{!#}
@end example

To make a script that launches an interactive REPL directly from the shell,
use the @code{--interactive} flag:

@example
@code{#!/usr/bin/env -S guix repl --interactive}
@code{!#}
@end example

Without a file name argument, a Guile REPL is started, allowing for
interactive use (@pxref{Usando Guix interativamente}):

@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
In addition, @command{guix repl} implements a simple machine-readable REPL
protocol for use by @code{(guix inferior)}, a facility to interact with
@dfn{inferiors}, separate processes running a potentially different revision
of Guix.

As opções disponíveis são as seguintes:

@table @code
@item --list-types
Display the @var{TYPE} options for @command{guix repl --type=TYPE} and exit.

@item --type=@var{type}
@itemx -t @var{tipo}
Start a REPL of the given @var{TYPE}, which can be one of the following:

@table @code
@item guile
This is default, and it spawns a standard full-featured Guile REPL.
@item machine
Spawn a REPL that uses the machine-readable protocol.  This is the protocol
that the @code{(guix inferior)} module speaks.
@end table

@item --listen=@var{endpoint}
By default, @command{guix repl} reads from standard input and writes to
standard output.  When this option is passed, it will instead listen for
connections on @var{endpoint}.  Here are examples of valid options:

@table @code
@item --listen=tcp:37146
Accept connections on localhost on port 37146.

@item --listen=unix:/tmp/socket
Accept connections on the Unix-domain socket @file{/tmp/socket}.
@end table

@item --interactive
@itemx -i
Launch the interactive REPL after @var{file} is executed.

@item --load-path=@var{directory}
@itemx -L @var{diretório}
Add @var{directory} to the front of the package module search path
(@pxref{Módulos de pacote}).

This allows users to define their own packages and make them visible to the
script or REPL.

@item -q
Inhibit loading of the @file{~/.guile} file.  By default, that configuration
file is loaded when spawning a @code{guile} REPL.
@end table

@node Usando Guix interativamente
@section Usando Guix interativamente

@cindex interactive use
@cindex REPL, read-eval-print loop
The @command{guix repl} command gives you access to a warm and friendly
@dfn{read-eval-print loop} (REPL) (@pxref{Invocando guix repl}).  If you're
getting into Guix programming---defining your own packages, writing
manifests, defining services for Guix System or Guix Home, etc.---you will
surely find it convenient to toy with ideas at the REPL.

If you use Emacs, the most convenient way to do that is with Geiser
(@pxref{A configuração perfeita}), but you do not have to use Emacs to enjoy the
REPL@.  When using @command{guix repl} or @command{guile} in the terminal,
we recommend using Readline for completion and Colorized to get colorful
output.  To do that, you can run:

@example
guix install guile guile-readline guile-colorized
@end example

@noindent
... and then create a @file{.guile} file in your home directory containing
this:

@lisp
(use-modules (ice-9 readline) (ice-9 colorized))

(activate-readline)
(activate-colorized)
@end lisp

The REPL lets you evaluate Scheme code; you type a Scheme expression at the
prompt, and the REPL prints what it evaluates to:

@example
$ guix repl
scheme@@(guix-user)> (+ 2 3)
$1 = 5
scheme@@(guix-user)> (string-append "a" "b")
$2 = "ab"
@end example

It becomes interesting when you start fiddling with Guix at the REPL.  The
first thing you'll want to do is to ``import'' the @code{(guix)} module,
which gives access to the main part of the programming interface, and
perhaps a bunch of useful Guix modules.  You could type @code{(use-modules
(guix))}, which is valid Scheme code to import a module (@pxref{Using Guile
Modules,,, guile, GNU Guile Reference Manual}), but the REPL provides the
@code{use} @dfn{command} as a shorthand notation (@pxref{REPL Commands,,,
guile, GNU Guile Reference Manual}):

@example
scheme@@(guix-user)> ,use (guix)
scheme@@(guix-user)> ,use (gnu packages base)
@end example

Notice that REPL commands are introduced by a leading comma.  A REPL command
like @code{use} is not valid Scheme code; it's interpreted specially by the
REPL.

Guix extends the Guile REPL with additional commands for convenience.  Among
those, the @code{build} command comes in handy: it ensures that the given
file-like object is built, building it if needed, and returns its output
file name(s).  In the example below, we build the @code{coreutils} and
@code{grep} packages, as well as a ``computed file'' (@pxref{Expressões-G,
@code{computed-file}}), and we use the @code{scandir} procedure to list the
files in Grep's @code{/bin} directory:

@example
scheme@@(guix-user)> ,build coreutils
$1 = "/gnu/store/@dots{}-coreutils-8.32-debug"
$2 = "/gnu/store/@dots{}-coreutils-8.32"
scheme@@(guix-user)> ,build grep
$3 = "/gnu/store/@dots{}-grep-3.6"
scheme@@(guix-user)> ,build (computed-file "x" #~(mkdir #$output))
building /gnu/store/@dots{}-x.drv...
$4 = "/gnu/store/@dots{}-x"
scheme@@(guix-user)> ,use(ice-9 ftw)
scheme@@(guix-user)> (scandir (string-append $3 "/bin"))
$5 = ("." ".." "egrep" "fgrep" "grep")
@end example

As a packager, you may be willing to inspect the build phases or flags of a
given package; this is particularly useful when relying a lot on inheritance
to define package variants (@pxref{Definindo variantes de pacote}) or when
package arguments are a result of some computation, both of which can make
it harder to foresee what ends up in the package arguments.  Additional
commands let you inspect those package arguments:

@example
scheme@@(guix-user)> ,phases grep
$1 = (modify-phases %standard-phases
       (add-after 'install 'fix-egrep-and-fgrep
         (lambda* (#:key outputs #:allow-other-keys)
           (let* ((out (assoc-ref outputs "out"))
                  (bin (string-append out "/bin")))
             (substitute* (list (string-append bin "/egrep")
                                (string-append bin "/fgrep"))
               (("^exec grep")
                (string-append "exec " bin "/grep")))))))
scheme@@(guix-user)> ,configure-flags findutils
$2 = (list "--localstatedir=/var")
scheme@@(guix-user)> ,make-flags binutils
$3 = '("MAKEINFO=true")
@end example

At a lower-level, a useful command is @code{lower}: it takes a file-like
object and ``lowers'' it into a derivation (@pxref{Derivações}) or a store
file:

@example
scheme@@(guix-user)> ,lower grep
$6 = #<derivation /gnu/store/@dots{}-grep-3.6.drv => /gnu/store/@dots{}-grep-3.6 7f0e639115f0>
scheme@@(guix-user)> ,lower (plain-file "x" "Hello!")
$7 = "/gnu/store/@dots{}-x"
@end example

The full list of REPL commands can be seen by typing @code{,help guix} and
is given below for reference.

@deffn {REPL command} build @var{object}
Lower @var{object} and build it if it's not already built, returning its
output file name(s).
@end deffn

@deffn {REPL command} build-options @var{options}
Set build options for rest of the REPL commands to @var{options}.  Must be a
list of keywords with values accepted by procedure @code{(@@ (guix store)
set-build-options)}.  An example would be:

@example
,build-options '(#:offload? #f)
@end example
@end deffn

@deffn {REPL command} graft? @var{graft?}
Set whether grafts should be performed as part of the build.  Equivalent to
@code{--no-grafts} argument to @code{guix build}.
@end deffn

@deffn {REPL command} lower @var{object}
Lower @var{object} into a derivation or store file name and return it.
@end deffn

@deffn {REPL command} verbosity @var{level}
Change build verbosity to @var{level}.

This is similar to the @option{--verbosity} command-line option
(@pxref{Opções de compilação comuns}): level 0 means total silence, level 1 shows
build events only, and higher levels print build logs.
@end deffn

@deffn {REPL command} phases @var{package}
@deffnx {REPL command} configure-flags @var{package}
@deffnx {REPL command} make-flags @var{package}
These REPL commands return the value of one element of the @code{arguments}
field of @var{package} (@pxref{Referência do package}): the first one show the
staged code associated with @code{#:phases} (@pxref{Fases de construção}), the
second shows the code for @code{#:configure-flags}, and @code{,make-flags}
returns the code for @code{#:make-flags}.
@end deffn

@deffn {REPL command} run-in-store @var{exp}
Run @var{exp}, a monadic expression, through the store monad.  @xref{A mônada do armazém}, for more information.
@end deffn

@deffn {REPL command} enter-store-monad
Enter a new REPL to evaluate monadic expressions (@pxref{A mônada do armazém}).
You can quit this ``inner'' REPL by typing @code{,q}.
@end deffn

@c *********************************************************************
@node Utilitários
@chapter Utilitários

This section describes Guix command-line utilities.  Some of them are
primarily targeted at developers and users who write new package
definitions, while others are more generally useful.  They complement the
Scheme programming interface of Guix in a convenient way.

@menu
* Invocando guix build::     Compilando pacotes a partir da linha de 
                               comando.
* Invocando guix edit::      Editando definições de pacote.
* Invocando guix download::  Baixando um arquivo e imprimindo seu hash.
* Invocando guix hash::      Computando a hash criptográfica de um arquivo.
* Invocando guix import::    Importando definições de pacote.
* Invocando guix refresh::   Atualizando definições de pacotes.
* Invocando guix style::     Styling package definitions.
* Invocando guix lint::      Encontrando erros nas definições de pacote.
* Invocando guix size::      Perfilando uso de disco.
* Invocando guix graph::     Visualizando o grafo de pacotes.
* Invocando guix publish::   Compartilhando substitutos.
* Invocando guix challenge::  Desafiando servidores substitutos.
* Invocando guix copy::      Copiando para e de um armazém remoto.
* Invocando guix container::  Isolação de processo.
* Invocando guix weather::   Acessando disponibilidade de substituto.
* Invocando guix processes::  Listando processos do cliente.
@end menu

@node Invocando guix build
@section Invocando @command{guix build}

@cindex package building
@cindex @command{guix build}
The @command{guix build} command builds packages or derivations and their
dependencies, and prints the resulting store paths.  Note that it does not
modify the user's profile---this is the job of the @command{guix package}
command (@pxref{Invocando guix package}).  Thus, it is mainly useful for
distribution developers.

A sintaxe geral é:

@example
guix build @var{options} @var{package-or-derivation}@dots{}
@end example

As an example, the following command builds the latest versions of Emacs and
of Guile, displays their build logs, and finally displays the resulting
directories:

@example
guix build emacs guile
@end example

Similarly, the following command builds all the available packages:

@example
guix build --quiet --keep-going \
  $(guix package -A | awk '@{ print $1 "@@" $2 @}')
@end example

@var{package-or-derivation} may be either the name of a package found in the
software distribution such as @code{coreutils} or @code{coreutils@@8.20}, or
a derivation such as @file{/gnu/store/@dots{}-coreutils-8.19.drv}.  In the
former case, a package with the corresponding name (and optionally version)
is searched for among the GNU distribution modules (@pxref{Módulos de pacote}).

Alternatively, the @option{--expression} option may be used to specify a
Scheme expression that evaluates to a package; this is useful when
disambiguating among several same-named packages or package variants is
needed.

There may be zero or more @var{options}.  The available options are
described in the subsections below.

@menu
* Opções de compilação comuns::  Opções de compilação para a maioria dos 
                                   comandos.
* Opções de transformação de pacote::  Criando variantes de pacotes.
* Opções de compilação adicional::  Opções específicas para "guix build".
* Depurando falhas de compilação::  Experiência de empacotamento na vida 
                                      real.
@end menu

@node Opções de compilação comuns
@subsection Opções de compilação comuns

A number of options that control the build process are common to
@command{guix build} and other commands that can spawn builds, such as
@command{guix package} or @command{guix archive}.  These are the following:

@table @code

@item --load-path=@var{directory}
@itemx -L @var{diretório}
Add @var{directory} to the front of the package module search path
(@pxref{Módulos de pacote}).

This allows users to define their own packages and make them visible to the
command-line tools.

@item --keep-failed
@itemx -K
Keep the build tree of failed builds.  Thus, if a build fails, its build
tree is kept under @file{/tmp}, in a directory whose name is shown at the
end of the build log.  This is useful when debugging build issues.
@xref{Depurando falhas de compilação}, for tips and tricks on how to debug build
issues.

This option implies @option{--no-offload}, and it has no effect when
connecting to a remote daemon with a @code{guix://} URI (@pxref{O armazém,
the @env{GUIX_DAEMON_SOCKET} variable}).

@item --keep-going
@itemx -k
Keep going when some of the derivations fail to build; return only once all
the builds have either completed or failed.

The default behavior is to stop as soon as one of the specified derivations
has failed.

@item --dry-run
@itemx -n
Do not build the derivations.

@anchor{fallback-option}
@item --fallback
When substituting a pre-built binary fails, fall back to building packages
locally (@pxref{Falha na substituição}).

@item --substitute-urls=@var{urls}
@anchor{client-substitute-urls}
Consider @var{urls} the whitespace-separated list of substitute source URLs,
overriding the default list of URLs of @command{guix-daemon}
(@pxref{daemon-substitute-urls,, @command{guix-daemon} URLs}).

This means that substitutes may be downloaded from @var{urls}, provided they
are signed by a key authorized by the system administrator
(@pxref{Substitutos}).

When @var{urls} is the empty string, substitutes are effectively disabled.

@item --no-substitutes
Não use substitutos para compilar produtos. Ou seja, sempre crie coisas
localmente, em vez de permitir downloads de binários pré-compilados
(@pxref{Substitutos}).

@item --no-grafts
Do not ``graft'' packages.  In practice, this means that package updates
available as grafts are not applied.  @xref{Atualizações de segurança}, for more
information on grafts.

@item --rounds=@var{n}
Build each derivation @var{n} times in a row, and raise an error if
consecutive build results are not bit-for-bit identical.

This is a useful way to detect non-deterministic builds processes.
Non-deterministic build processes are a problem because they make it
practically impossible for users to @emph{verify} whether third-party
binaries are genuine.  @xref{Invocando guix challenge}, for more.

Quando usado em conjunto com @option{--keep-failed}, uma saída de comparação
é mantida no armazém, sob  @file{/gnu/store/@dots{}-check}. Isso facilita
procurar por diferenças entre os dois resultados.

@item --no-offload
Não use compilações de offload para outras máquinas (@pxref{Configuração de descarregamento de daemon}). Ou seja, sempre compile as coisas localmente em vez de descarregar
compilações para máquinas remotas.

@item --max-silent-time=@var{segundos}
Quando o processo de compilação ou substituição permanecer em silêncio por
mais de @var{segundos}, encerra-o e relata uma falha de compilação.

By default, the daemon's setting is honored (@pxref{Invocando guix-daemon,
@option{--max-silent-time}}).

@item --timeout=@var{segundos}
Da mesma forma, quando o processo de compilação ou substituição durar mais
que @var{segundos}, encerra-o e relata uma falha de compilação.

By default, the daemon's setting is honored (@pxref{Invocando guix-daemon,
@option{--timeout}}).

@c Note: This option is actually not part of %standard-build-options but
@c most programs honor it.
@cindex verbosity, of the command-line tools
@cindex build logs, verbosity
@item -v @var{level}
@itemx --verbosity=@var{level}
Use the given verbosity @var{level}, an integer.  Choosing 0 means that no
output is produced, 1 is for quiet output; 2 is similar to 1 but it
additionally displays download URLs; 3 shows all the build log output on
standard error.

@item --cores=@var{n}
@itemx -c @var{n}
Allow the use of up to @var{n} CPU cores for the build.  The special value
@code{0} means to use as many CPU cores as available.

@item --max-jobs=@var{n}
@itemx -M @var{n}
Allow at most @var{n} build jobs in parallel.  @xref{Invocando guix-daemon,
@option{--max-jobs}}, for details about this option and the equivalent
@command{guix-daemon} option.

@item --debug=@var{level}
Produce debugging output coming from the build daemon.  @var{level} must be
an integer between 0 and 5; higher means more verbose output.  Setting a
level of 4 or more may be helpful when debugging setup issues with the build
daemon.

@end table

Behind the scenes, @command{guix build} is essentially an interface to the
@code{package-derivation} procedure of the @code{(guix packages)} module,
and to the @code{build-derivations} procedure of the @code{(guix
derivations)} module.

In addition to options explicitly passed on the command line, @command{guix
build} and other @command{guix} commands that support building honor the
@env{GUIX_BUILD_OPTIONS} environment variable.

@defvr {Environment Variable} GUIX_BUILD_OPTIONS
Users can define this variable to a list of command line options that will
automatically be used by @command{guix build} and other @command{guix}
commands that can perform builds, as in the example below:

@example
$ export GUIX_BUILD_OPTIONS="--no-substitutes -c 2 -L /foo/bar"
@end example

These options are parsed independently, and the result is appended to the
parsed command-line options.
@end defvr


@node Opções de transformação de pacote
@subsection Opções de transformação de pacote

@cindex variantes de pacotes
Another set of command-line options supported by @command{guix build} and
also @command{guix package} are @dfn{package transformation options}.  These
are options that make it possible to define @dfn{package variants}---for
instance, packages built from different source code.  This is a convenient
way to create customized packages on the fly without having to type in the
definitions of package variants (@pxref{Definindo pacotes}).

Package transformation options are preserved across upgrades: @command{guix
upgrade} attempts to apply transformation options initially used when
creating the profile to the upgraded packages.

The available options are listed below.  Most commands support them and also
support a @option{--help-transform} option that lists all the available
options and a synopsis (these options are not shown in the @option{--help}
output for brevity).

@table @code

@cindex performance, tuning code
@cindex optimization, of package code
@cindex tuning, of package code
@cindex SIMD support
@cindex tunable packages
@cindex package multi-versioning
@item --tune[=@var{cpu}]
Use versions of the packages marked as ``tunable'' optimized for @var{cpu}.
When @var{cpu} is @code{native}, or when it is omitted, tune for the CPU on
which the @command{guix} command is running.

Valid @var{cpu} names are those recognized by the underlying compiler, by
default the GNU Compiler Collection.  On x86_64 processors, this includes
CPU names such as @code{nehalem}, @code{haswell}, and @code{skylake}
(@pxref{x86 Options, @code{-march},, gcc, Using the GNU Compiler Collection
(GCC)}).

As new generations of CPUs come out, they augment the standard instruction
set architecture (ISA) with additional instructions, in particular
instructions for single-instruction/multiple-data (SIMD)  parallel
processing.  For example, while Core2 and Skylake CPUs both implement the
x86_64 ISA, only the latter supports AVX2 SIMD instructions.

The primary gain one can expect from @option{--tune} is for programs that
can make use of those SIMD capabilities @emph{and} that do not already have
a mechanism to select the right optimized code at run time.  Packages that
have the @code{tunable?} property set are considered @dfn{tunable packages}
by the @option{--tune} option; a package definition with the property set
looks like this:

@lisp
(package
  (name "hello-simd")
  ;; ...

  ;; This package may benefit from SIMD extensions so
  ;; mark it as "tunable".
  (properties '((tunable? . #t))))
@end lisp

Other packages are not considered tunable.  This allows Guix to use generic
binaries in the cases where tuning for a specific CPU is unlikely to provide
any gain.

Tuned packages are built with @code{-march=@var{CPU}}; under the hood, the
@option{-march} option is passed to the actual wrapper by a compiler
wrapper.  Since the build machine may not be able to run code for the target
CPU micro-architecture, the test suite is not run when building a tuned
package.

To reduce rebuilds to the minimum, tuned packages are @emph{grafted} onto
packages that depend on them (@pxref{Atualizações de segurança, grafts}).  Thus,
using @option{--no-grafts} cancels the effect of @option{--tune}.

We call this technique @dfn{package multi-versioning}: several variants of
tunable packages may be built, one for each CPU variant.  It is the
coarse-grain counterpart of @dfn{function multi-versioning} as implemented
by the GNU tool chain (@pxref{Function Multiversioning,,, gcc, Using the GNU
Compiler Collection (GCC)}).

@item --with-source=@var{fonte}
@itemx --with-source=@var{pacote}=@var{fonte}
@itemx --with-source=@var{package}@@@var{version}=@var{source}
Use @var{source} as the source of @var{package}, and @var{version} as its
version number.  @var{source} must be a file name or a URL, as for
@command{guix download} (@pxref{Invocando guix download}).

When @var{package} is omitted, it is taken to be the package name specified
on the command line that matches the base of @var{source}---e.g., if
@var{source} is @code{/src/guile-2.0.10.tar.gz}, the corresponding package
is @code{guile}.

Likewise, when @var{version} is omitted, the version string is inferred from
@var{source}; in the previous example, it is @code{2.0.10}.

This option allows users to try out versions of packages other than the one
provided by the distribution.  The example below downloads
@file{ed-1.7.tar.gz} from a GNU mirror and uses that as the source for the
@code{ed} package:

@example
guix build ed --with-source=mirror://gnu/ed/ed-1.4.tar.gz
@end example

As a developer, @option{--with-source} makes it easy to test release
candidates, and even to test their impact on packages that depend on them:

@example
guix build elogind --with-source=@dots{}/shepherd-0.9.0rc1.tar.gz
@end example

@dots{} or to build from a checkout in a pristine environment:

@example
$ git clone git://git.sv.gnu.org/guix.git
$ guix build guix --with-source=guix@@1.0=./guix
@end example

@item --with-input=@var{pacote}=@var{substituto}
Replace dependency on @var{package} by a dependency on @var{replacement}.
@var{package} must be a package name, and @var{replacement} must be a
package specification such as @code{guile} or @code{guile@@1.8}.

For instance, the following command builds Guix, but replaces its dependency
on the current stable version of Guile with a dependency on the legacy
version of Guile, @code{guile@@2.2}:

@example
guix build --with-input=guile=guile@@2.2 guix
@end example

This is a recursive, deep replacement.  So in this example, both @code{guix}
and its dependency @code{guile-json} (which also depends on @code{guile})
get rebuilt against @code{guile@@2.2}.

This is implemented using the @code{package-input-rewriting/spec} Scheme
procedure (@pxref{Definindo pacotes, @code{package-input-rewriting/spec}}).

@item --with-graft=@var{package}=@var{replacement}
This is similar to @option{--with-input} but with an important difference:
instead of rebuilding the whole dependency chain, @var{replacement} is built
and then @dfn{grafted} onto the binaries that were initially referring to
@var{package}.  @xref{Atualizações de segurança}, for more information on grafts.

For example, the command below grafts version 3.5.4 of GnuTLS onto Wget and
all its dependencies, replacing references to the version of GnuTLS they
currently refer to:

@example
guix build --with-graft=gnutls=gnutls@@3.5.4 wget
@end example

This has the advantage of being much faster than rebuilding everything.  But
there is a caveat: it works if and only if @var{package} and
@var{replacement} are strictly compatible---for example, if they provide a
library, the application binary interface (ABI) of those libraries must be
compatible.  If @var{replacement} is somehow incompatible with
@var{package}, then the resulting package may be unusable.  Use with care!

@cindex debugging info, rebuilding
@item --with-debug-info=@var{package}
Build @var{package} in a way that preserves its debugging info and graft it
onto packages that depend on it.  This is useful if @var{package} does not
already provide debugging info as a @code{debug} output (@pxref{Instalando arquivos de depuração}).

For example, suppose you're experiencing a crash in Inkscape and would like
to see what's up in GLib, a library deep down in Inkscape's dependency
graph.  GLib lacks a @code{debug} output, so debugging is tough.
Fortunately, you rebuild GLib with debugging info and tack it on Inkscape:

@example
guix install inkscape --with-debug-info=glib
@end example

Only GLib needs to be recompiled so this takes a reasonable amount of time.
@xref{Instalando arquivos de depuração}, for more info.

@quotation Nota
Under the hood, this option works by passing the @samp{#:strip-binaries? #f}
to the build system of the package of interest (@pxref{Sistemas de compilação}).
Most build systems support that option but some do not.  In that case, an
error is raised.

Likewise, if a C/C++ package is built without @code{-g} (which is rarely the
case), debugging info will remain unavailable even when
@code{#:strip-binaries?} is false.
@end quotation

@cindex tool chain, changing the build tool chain of a package
@item --with-c-toolchain=@var{package}=@var{toolchain}
This option changes the compilation of @var{package} and everything that
depends on it so that they get built with @var{toolchain} instead of the
default GNU tool chain for C/C++.

Considere este exemplo:

@example
guix build octave-cli \
  --with-c-toolchain=fftw=gcc-toolchain@@10 \
  --with-c-toolchain=fftwf=gcc-toolchain@@10
@end example

The command above builds a variant of the @code{fftw} and @code{fftwf}
packages using version 10 of @code{gcc-toolchain} instead of the default
tool chain, and then builds a variant of the GNU@tie{}Octave command-line
interface using them.  GNU@tie{}Octave itself is also built with
@code{gcc-toolchain@@10}.

This other example builds the Hardware Locality (@code{hwloc}) library and
its dependents up to @code{intel-mpi-benchmarks} with the Clang C compiler:

@example
guix build --with-c-toolchain=hwloc=clang-toolchain \
           intel-mpi-benchmarks
@end example

@quotation Nota
There can be application binary interface (ABI) incompatibilities among tool
chains.  This is particularly true of the C++ standard library and run-time
support libraries such as that of OpenMP@.  By rebuilding all dependents
with the same tool chain, @option{--with-c-toolchain} minimizes the risks of
incompatibility but cannot entirely eliminate them.  Choose @var{package}
wisely.
@end quotation

@item --with-git-url=@var{pacote}=@var{url}
@cindex Git, using the latest commit
@cindex latest commit, building
Build @var{package} from the latest commit of the @code{master} branch of
the Git repository at @var{url}.  Git sub-modules of the repository are
fetched, recursively, if @var{package} @code{source} is not a Git
repository, otherwise it depends on the inherited value of
@code{recursive?}.

For example, the following command builds the NumPy Python library against
the latest commit of the master branch of Python itself:

@example
guix build python-numpy \
  --with-git-url=python=https://github.com/python/cpython
@end example

This option can also be combined with @option{--with-branch} or
@option{--with-commit} (see below).

@cindex integração contínua
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{pacote}=@var{ramo}
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{Referência do origin}) or a @code{git-checkout} object, the
repository URL is taken from that @code{source}.  Otherwise you have to use
@option{--with-git-url} to specify the URL of the Git repository.

For instance, the following command builds @code{guile-sqlite3} from the
latest commit of its @code{master} branch, and then builds @code{guix}
(which depends on it) and @code{cuirass} (which depends on @code{guix})
against this specific @code{guile-sqlite3} build:

@example
guix build --with-branch=guile-sqlite3=master cuirass
@end example

@item --with-commit=@var{pacote}=@var{commit}
This is similar to @option{--with-branch}, except that it builds from
@var{commit} rather than the tip of a branch.  @var{commit} must be a valid
Git commit SHA1 identifier, a tag, or a @command{git describe} style
identifier such as @code{1.0-3-gabc123}.

@item --with-patch=@var{package}=@var{file}
Add @var{file} to the list of patches applied to @var{package}, where
@var{package} is a spec such as @code{python@@3.8} or @code{glibc}.
@var{file} must contain a patch; it is applied with the flags specified in
the @code{origin} of @var{package} (@pxref{Referência do origin}), which by
default includes @code{-p1} (@pxref{patch Directories,,, diffutils,
Comparing and Merging Files}).

As an example, the command below rebuilds Coreutils with the GNU C Library
(glibc) patched with the given patch:

@example
guix build coreutils --with-patch=glibc=./glibc-frob.patch
@end example

In this example, glibc itself as well as everything that leads to Coreutils
in the dependency graph is rebuilt.

@cindex configure flags, changing them
@item --with-configure-flag=@var{package}=@var{flag}
Append @var{flag} to the configure flags of @var{package}, where
@var{package} is a spec such as @code{guile@@3.0} or @code{glibc}.  The
build system of @var{package} must support the @code{#:configure-flags}
argument.

For example, the command below builds GNU@tie{}Hello with the configure flag
@code{--disable-nls}:

@example
guix build hello --with-configure-flag=hello=--disable-nls
@end example

The following command passes an extra flag to @command{cmake} as it builds
@code{lapack}:

@example
guix build lapack \
  --with-configure-flag=lapack=-DBUILD_SHARED_LIBS=OFF
@end example

@quotation Nota
Under the hood, this option works by passing the @samp{#:configure-flags}
argument to the build system of the package of interest (@pxref{Sistemas de compilação}).  Most build systems support that option but some do not.  In that
case, an error is raised.
@end quotation

@cindex upstream, latest version
@item --with-latest=@var{package}
@itemx --with-version=@var{package}=@var{version}
So you like living on the bleeding edge? The @option{--with-latest} option
is for you! It replaces occurrences of @var{package} in the dependency graph
with its latest upstream version, as reported by @command{guix refresh}
(@pxref{Invocando guix refresh}).

It does so by determining the latest upstream release of @var{package} (if
possible), downloading it, and authenticating it @emph{if} it comes with an
OpenPGP signature.

As an example, the command below builds Guix against the latest version of
Guile-JSON:

@example
guix build guix --with-latest=guile-json
@end example

The @option{--with-version} works similarly except that it lets you specify
that you want precisely @var{version}, assuming that version exists
upstream.  For example, to spawn a development environment with SciPy built
against version 1.22.4 of NumPy (skipping its test suite because hey, we're
not gonna wait this long), you would run:

@example
guix shell python python-scipy --with-version=python-numpy=1.22.4
@end example

@quotation Aviso
Because they depend on source code published at a given point in time on
upstream servers, deployments made with @option{--with-latest} and
@option{--with-version} may be non-reproducible: source might disappear or
be modified in place on the servers.

To deploy old software versions without compromising on reproducibility,
@pxref{Invocando guix time-machine, @command{guix time-machine}}.
@end quotation

There are limitations.  First, in cases where the tool cannot or does not
know how to authenticate source code, you are at risk of running malicious
code; a warning is emitted in this case.  Second, this option simply changes
the source used in the existing package definitions, which is not always
sufficient: there might be additional dependencies that need to be added,
patches to apply, and more generally the quality assurance work that Guix
developers normally do will be missing.

You've been warned! When those limitations are acceptable, it's a snappy way
to stay on top.  We encourage you to submit patches updating the actual
package definitions once you have successfully tested an upgrade with
@option{--with-latest} (@pxref{Contribuindo}).

@cindex test suite, skipping
@item --without-tests=@var{package}
Build @var{package} without running its tests.  This can be useful in
situations where you want to skip the lengthy test suite of a intermediate
package, or if a package's test suite fails in a non-deterministic fashion.
It should be used with care because running the test suite is a good way to
ensure a package is working as intended.

Turning off tests leads to a different store item.  Consequently, when using
this option, anything that depends on @var{package} must be rebuilt, as in
this example:

@example
guix install --without-tests=python python-notebook
@end example

The command above installs @code{python-notebook} on top of @code{python}
built without running its test suite.  To do so, it also rebuilds everything
that depends on @code{python}, including @code{python-notebook} itself.

Internally, @option{--without-tests} relies on changing the @code{#:tests?}
option of a package's @code{check} phase (@pxref{Sistemas de compilação}).  Note that
some packages use a customized @code{check} phase that does not respect a
@code{#:tests? #f} setting.  Therefore, @option{--without-tests} has no
effect on these packages.

@end table

Wondering how to achieve the same effect using Scheme code, for example in
your manifest, or how to write your own package transformation?
@xref{Definindo variantes de pacote}, for an overview of the programming
interfaces available.

@node Opções de compilação adicional
@subsection Opções de compilação adicional

The command-line options presented below are specific to @command{guix
build}.

@table @code

@item --quiet
@itemx -q
Build quietly, without displaying the build log; this is equivalent to
@option{--verbosity=0}.  Upon completion, the build log is kept in
@file{/var} (or similar) and can always be retrieved using the
@option{--log-file} option.

@item --file=@var{arquivo}
@itemx -f @var{arquivo}
Build the package, derivation, or other file-like object that the code
within @var{file} evaluates to (@pxref{Expressões-G, file-like objects}).

As an example, @var{file} might contain a package definition like this
(@pxref{Definindo pacotes}):

@lisp
@include package-hello.scm
@end lisp

The @var{file} may also contain a JSON representation of one or more package
definitions.  Running @code{guix build -f} on @file{hello.json} with the
following contents would result in building the packages @code{myhello} and
@code{greeter}:

@example
@verbatiminclude package-hello.json
@end example

@item --manifest=@var{manifest}
@itemx -m @var{manifest}
Build all packages listed in the given @var{manifest}
(@pxref{profile-manifest, @option{--manifest}}).

@item --expression=@var{expr}
@itemx -e @var{expr}
Build the package or derivation @var{expr} evaluates to.

For example, @var{expr} may be @code{(@@ (gnu packages guile)  guile-1.8)},
which unambiguously designates this specific variant of version 1.8 of
Guile.

Alternatively, @var{expr} may be a G-expression, in which case it is used as
a build program passed to @code{gexp->derivation} (@pxref{Expressões-G}).

Lastly, @var{expr} may refer to a zero-argument monadic procedure
(@pxref{A mônada do armazém}).  The procedure must return a derivation as a
monadic value, which is then passed through @code{run-with-store}.

@item --development
@itemx -D
Build the ``development environment'' (build dependencies) of the following
package.

For example, the following command builds the inputs of @code{hello}, but
@emph{not} @code{hello} itself, and also builds @code{guile}:

@example
guix build -D hello guile
@end example

Notice that @option{-D} (or @option{--development}) only applies to the
immediately following package on the command line.  Under the hood, it uses
@code{package->development-manifest} (@pxref{package-development-manifest,
@code{package->development-manifest}}).

@quotation Nota
The effect of combining @option{--development} with @option{--target} (for
cross-compilation) may not be what you expect: it will cross-compile all the
dependencies of the given package when it is built natively.
@end quotation

@cindex dependents of a package, building them
@cindex building the dependents of a package
@anchor{build-dependents}
@item --dependents[=@var{depth}]
@itemx -P @var{depth}
Build the dependents of the following package.  By default, build all the
direct and indirect dependents; when @var{depth} is provided, limit to
dependents at that distance: 1 for direct dependents, 2 for dependents of
dependents, and so on.

For example, the command below builds @emph{all} the dependents of libgit2:

@example
guix build --dependents libgit2
@end example

To build all the packages that directly depend on NumPy, run:

@example
guix build -P1 python-numpy
@end example

The list of dependents is computed in the same way as with @command{guix
refresh --list-dependent} (@pxref{Invocando guix refresh}).

@item --source
@itemx -S
Build the source derivations of the packages, rather than the packages
themselves.

For instance, @code{guix build -S gcc} returns something like
@file{/gnu/store/@dots{}-gcc-4.7.2.tar.bz2}, which is the GCC source
tarball.

The returned source tarball is the result of applying any patches and code
snippets specified in the package @code{origin} (@pxref{Definindo pacotes}).

@cindex source, verification
As with other derivations, the result of building a source derivation can be
verified using the @option{--check} option (@pxref{build-check}).  This is
useful to validate that a (potentially already built or substituted, thus
cached) package source matches against its declared hash.

Note that @command{guix build -S} compiles the sources only of the specified
packages.  They do not include the sources of statically linked dependencies
and by themselves are insufficient for reproducing the packages.

@item --sources
Fetch and return the source of @var{package-or-derivation} and all their
dependencies, recursively.  This is a handy way to obtain a local copy of
all the source code needed to build @var{packages}, allowing you to
eventually build them even without network access.  It is an extension of
the @option{--source} option and can accept one of the following optional
argument values:

@table @code
@item package
This value causes the @option{--sources} option to behave in the same way as
the @option{--source} option.

@item all
Build the source derivations of all packages, including any source that
might be listed as @code{inputs}.  This is the default value.

@example
$ guix build --sources tzdata
The following derivations will be built:
   /gnu/store/@dots{}-tzdata2015b.tar.gz.drv
   /gnu/store/@dots{}-tzcode2015b.tar.gz.drv
@end example

@item transitive
Build the source derivations of all packages, as well of all transitive
inputs to the packages.  This can be used e.g.@: to prefetch package source
for later offline building.

@example
$ guix build --sources=transitive tzdata
The following derivations will be built:
   /gnu/store/@dots{}-tzcode2015b.tar.gz.drv
   /gnu/store/@dots{}-findutils-4.4.2.tar.xz.drv
   /gnu/store/@dots{}-grep-2.21.tar.xz.drv
   /gnu/store/@dots{}-coreutils-8.23.tar.xz.drv
   /gnu/store/@dots{}-make-4.1.tar.xz.drv
   /gnu/store/@dots{}-bash-4.3.tar.xz.drv
@dots{}
@end example

@end table

@item --system=@var{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
The @option{--system} flag is for @emph{native} compilation and must not be
confused with cross-compilation.  See @option{--target} below for
information on cross-compilation.
@end quotation

An example use of this is on Linux-based systems, which can emulate
different personalities.  For instance, passing @option{--system=i686-linux}
on an @code{x86_64-linux} system or @option{--system=armhf-linux} on an
@code{aarch64-linux} system allows you to build packages in a complete
32-bit environment.

@quotation Nota
Building for an @code{armhf-linux} system is unconditionally enabled on
@code{aarch64-linux} machines, although certain aarch64 chipsets do not
allow for this functionality, notably the ThunderX.
@end quotation

Similarly, when transparent emulation with QEMU and @code{binfmt_misc} is
enabled (@pxref{Serviços de virtualização, @code{qemu-binfmt-service-type}}),
you can build for any system for which a QEMU @code{binfmt_misc} handler is
installed.

Builds for a system other than that of the machine you are using can also be
offloaded to a remote machine of the right architecture.  @xref{Configuração de descarregamento de daemon}, for more information on offloading.

@item --target=@var{tripleto}
@cindex compilação cruzada
Cross-build for @var{triplet}, which must be a valid GNU triplet, such as
@code{"aarch64-linux-gnu"} (@pxref{Specifying Target Triplets, GNU
configuration triplets,, autoconf, Autoconf}).

@item --list-systems
List all the supported systems, that can be passed as an argument to
@option{--system}.

@item --list-targets
List all the supported targets, that can be passed as an argument to
@option{--target}.

@anchor{build-check}
@item --check
@cindex determinismo, verificação
@cindex reprodutibilidade, verificação
Rebuild @var{package-or-derivation}, which are already available in the
store, and raise an error if the build results are not bit-for-bit
identical.

This mechanism allows you to check whether previously installed substitutes
are genuine (@pxref{Substitutos}), or whether the build result of a package
is deterministic.  @xref{Invocando guix challenge}, for more background
information and tools.

Quando usado em conjunto com @option{--keep-failed}, uma saída de comparação
é mantida no armazém, sob  @file{/gnu/store/@dots{}-check}. Isso facilita
procurar por diferenças entre os dois resultados.

@item --repair
@cindex repairing store items
@cindex corrupção, recuperando-se de
Attempt to repair the specified store items, if they are corrupt, by
re-downloading or rebuilding them.

This operation is not atomic and thus restricted to @code{root}.

@item --derivations
@itemx -d
Return the derivation paths, not the output paths, of the given packages.

@item --root=@var{arquivo}
@itemx -r @var{arquivo}
@cindex GC roots, adding
@cindex garbage collector roots, adding
Make @var{file} a symlink to the result, and register it as a garbage
collector root.

Consequently, the results of this @command{guix build} invocation are
protected from garbage collection until @var{file} is removed.  When that
option is omitted, build results are eligible for garbage collection as soon
as the build completes.  @xref{Invocando guix gc}, for more on GC roots.

@item --log-file
@cindex build logs, access
Return the build log file names or URLs for the given
@var{package-or-derivation}, or raise an error if build logs are missing.

This works regardless of how packages or derivations are specified.  For
instance, the following invocations are equivalent:

@example
guix build --log-file $(guix build -d guile)
guix build --log-file $(guix build guile)
guix build --log-file guile
guix build --log-file -e '(@@ (gnu packages guile) guile-2.0)'
@end example

If a log is unavailable locally, and unless @option{--no-substitutes} is
passed, the command looks for a corresponding log on one of the substitute
servers.

So for instance, imagine you want to see the build log of GDB on
@code{aarch64}, but you are actually on an @code{x86_64} machine:

@example
$ guix build --log-file gdb -s aarch64-linux
https://@value{SUBSTITUTE-SERVER-1}/log/@dots{}-gdb-7.10
@end example

You can freely access a huge library of build logs!
@end table

@node Depurando falhas de compilação
@subsection Depurando falhas de compilação

@cindex build failures, debugging
When defining a new package (@pxref{Definindo pacotes}), you will probably
find yourself spending some time debugging and tweaking the build until it
succeeds.  To do that, you need to operate the build commands yourself in an
environment as close as possible to the one the build daemon uses.

To that end, the first thing to do is to use the @option{--keep-failed} or
@option{-K} option of @command{guix build}, which will keep the failed build
tree in @file{/tmp} or whatever directory you specified as @env{TMPDIR}
(@pxref{Opções de compilação comuns, @option{--keep-failed}}).

From there on, you can @command{cd} to the failed build tree and source the
@file{environment-variables} file, which contains all the environment
variable definitions that were in place when the build failed.  So let's say
you're debugging a build failure in package @code{foo}; a typical session
would look like this:

@example
$ guix build foo -K
@dots{} @i{build fails}
$ cd /tmp/guix-build-foo.drv-0
$ source ./environment-variables
$ cd foo-1.2
@end example

Now, you can invoke commands as if you were the daemon (almost) and
troubleshoot your build process.

Sometimes it happens that, for example, a package's tests pass when you run
them manually but they fail when the daemon runs them.  This can happen
because the daemon runs builds in containers where, unlike in our
environment above, network access is missing, @file{/bin/sh} does not exist,
etc. (@pxref{Configuração do ambiente de compilação}).

In such cases, you may need to inspect the build process from within a
container similar to the one the build daemon creates:

@example
$ guix build -K foo
@dots{}
$ cd /tmp/guix-build-foo.drv-0
$ guix shell --no-grafts -C -D foo strace gdb
[env]# source ./environment-variables
[env]# cd foo-1.2
@end example

Here, @command{guix shell -C} creates a container and spawns a new shell in
it (@pxref{Invocando guix shell}).  The @command{strace gdb} part adds the
@command{strace} and @command{gdb} commands to the container, which you may
find handy while debugging.  The @option{--no-grafts} option makes sure we
get the exact same environment, with ungrafted packages (@pxref{Atualizações de segurança}, for more info on grafts).

To get closer to a container like that used by the build daemon, we can
remove @file{/bin/sh} (you'll first need to pass the
@option{--writable-root} option to @command{guix shell}):

@example
[env]# rm /bin/sh
@end example

(Don't worry, this is harmless: this is all happening in the throw-away
container created by @command{guix shell}.)

The @command{strace} command is probably not in the search path, but we can
run:

@example
[env]# $GUIX_ENVIRONMENT/bin/strace -f -o log make check
@end example

In this way, not only you will have reproduced the environment variables the
daemon uses, you will also be running the build process in a container
similar to the one the daemon uses.


@node Invocando guix edit
@section Invocando @command{guix edit}

@cindex @command{guix edit}
@cindex package definition, editing
So many packages, so many source files! The @command{guix edit} command
facilitates the life of users and packagers by pointing their editor at the
source file containing the definition of the specified packages.  For
instance:

@example
guix edit gcc@@4.9 vim
@end example

@noindent
launches the program specified in the @env{VISUAL} or in the @env{EDITOR}
environment variable to view the recipe of GCC@tie{}4.9.3 and that of Vim.

If you are using a Guix Git checkout (@pxref{Compilando do git}), or have
created your own packages on @env{GUIX_PACKAGE_PATH} (@pxref{Módulos de pacote}), you will be able to edit the package recipes.  In other cases,
you will be able to examine the read-only recipes for packages currently in
the store.

Instead of @env{GUIX_PACKAGE_PATH}, the command-line option
@option{--load-path=@var{directory}} (or in short @option{-L
@var{directory}}) allows you to add @var{directory} to the front of the
package module search path and so make your own packages visible.

@node Invocando guix download
@section Invocando @command{guix download}

@cindex @command{guix download}
@cindex downloading package sources
When writing a package definition, developers typically need to download a
source tarball, compute its SHA256 hash, and write that hash in the package
definition (@pxref{Definindo pacotes}).  The @command{guix download} tool
helps with this task: it downloads a file from the given URI, adds it to the
store, and prints both its file name in the store and its SHA256 hash.

The fact that the downloaded file is added to the store saves bandwidth:
when the developer eventually tries to build the newly defined package with
@command{guix build}, the source tarball will not have to be downloaded
again because it is already in the store.  It is also a convenient way to
temporarily stash files, which may be deleted eventually (@pxref{Invocando guix gc}).

The @command{guix download} command supports the same URIs as used in
package definitions.  In particular, it supports @code{mirror://} URIs.
@code{https} URIs (HTTP over TLS) are supported @emph{provided} the Guile
bindings for GnuTLS are available in the user's environment; when they are
not available, an error is raised.  @xref{Guile Preparations, how to install
the GnuTLS bindings for Guile,, gnutls-guile, GnuTLS-Guile}, for more
information.

@command{guix download} verifies HTTPS server certificates by loading the
certificates of X.509 authorities from the directory pointed to by the
@env{SSL_CERT_DIR} environment variable (@pxref{Certificados X.509}), unless
@option{--no-check-certificate} is used.

Alternatively, @command{guix download} can also retrieve a Git repository,
possibly a specific commit, tag, or branch.

The following options are available:

@table @code
@item --hash=@var{algorithm}
@itemx -H @var{algorithm}
Compute a hash using the specified @var{algorithm}.  @xref{Invocando guix hash}, for more information.

@item --format=@var{fmt}
@itemx -f @var{fmt}
Write the hash in the format specified by @var{fmt}.  For more information
on the valid values for @var{fmt}, @pxref{Invocando guix hash}.

@item --no-check-certificate
Do not validate the X.509 certificates of HTTPS servers.

When using this option, you have @emph{absolutely no guarantee} that you are
communicating with the authentic server responsible for the given URL, which
makes you vulnerable to ``man-in-the-middle'' attacks.

@item --output=@var{arquivo}
@itemx -o @var{arquivo}
Save the downloaded file to @var{file} instead of adding it to the store.

@item --git
@itemx -g
Checkout the Git repository at the latest commit on the default branch.

@item --commit=@var{commit-or-tag}
Checkout the Git repository at @var{commit-or-tag}.

@var{commit-or-tag} can be either a tag or a commit defined in the Git
repository.

@item --branch=@var{ramo}
Checkout the Git repository at @var{branch}.

The repository will be checked out at the latest commit of @var{branch},
which must be a valid branch of the Git repository.

@item --recursive
@itemx -r
Recursively clone the Git repository.
@end table

@node Invocando guix hash
@section Invocando @command{guix hash}

@cindex @command{guix hash}
The @command{guix hash} command computes the hash of a file.  It is
primarily a convenience tool for anyone contributing to the distribution: it
computes the cryptographic hash of one or more files, which can be used in
the definition of a package (@pxref{Definindo pacotes}).

A sintaxe geral é:

@example
guix hash @var{option} @var{file} ...
@end example

When @var{file} is @code{-} (a hyphen), @command{guix hash} computes the
hash of data read from standard input.  @command{guix hash} has the
following options:

@table @code

@item --hash=@var{algorithm}
@itemx -H @var{algorithm}
Compute a hash using the specified @var{algorithm}, @code{sha256} by
default.

@var{algorithm} must be the name of a cryptographic hash algorithm supported
by Libgcrypt @i{via} Guile-Gcrypt---e.g., @code{sha512} or @code{sha3-256}
(@pxref{Hash Functions,,, guile-gcrypt, Guile-Gcrypt Reference Manual}).

@item --format=@var{fmt}
@itemx -f @var{fmt}
Write the hash in the format specified by @var{fmt}.

Supported formats: @code{base64}, @code{nix-base32}, @code{base32},
@code{base16} (@code{hex} and @code{hexadecimal} can be used as well).

If the @option{--format} option is not specified, @command{guix hash} will
output the hash in @code{nix-base32}.  This representation is used in the
definitions of packages.

@item --recursive
@itemx -r
The @option{--recursive} option is deprecated in favor of
@option{--serializer=nar} (see below); @option{-r} remains accepted as a
convenient shorthand.

@item --serializer=@var{type}
@itemx -S @var{type}
Compute the hash on @var{file} using @var{type} serialization.

@var{type} may be one of the following:

@table @code
@item none
This is the default: it computes the hash of a file's contents.

@item nar
@c FIXME: Replace xref above with xref to an ``Archive'' section when
@c it exists.
Compute the hash of a ``normalized archive'' (or ``nar'') containing
@var{file}, including its children if it is a directory.  Some of the
metadata of @var{file} is part of the archive; for instance, when @var{file}
is a regular file, the hash is different depending on whether @var{file} is
executable or not.  Metadata such as time stamps have no impact on the hash
(@pxref{Invocando guix archive}, for more info on the nar format).

@item git
Compute the hash of the file or directory as a Git ``tree'', following the
same method as the Git version control system.
@end table

@item --exclude-vcs
@itemx -x
When combined with @option{--recursive}, exclude version control system
directories (@file{.bzr}, @file{.git}, @file{.hg}, etc.).

@vindex git-fetch
As an example, here is how you would compute the hash of a Git checkout,
which is useful when using the @code{git-fetch} method (@pxref{Referência do origin}):

@example
$ git clone http://example.org/foo.git
$ cd foo
$ guix hash -x --serializer=nar .
@end example
@end table

@node Invocando guix import
@section Invoking @command{guix import}

@cindex importing packages
@cindex package import
@cindex package conversion
@cindex Invoking @command{guix import}
The @command{guix import} command is useful for people who would like to add
a package to the distribution with as little work as possible---a legitimate
demand.  The command knows of a few repositories from which it can
``import'' package metadata.  The result is a package definition, or a
template thereof, in the format we know (@pxref{Definindo pacotes}).

A sintaxe geral é:

@example
guix import [@var{global-options}@dots{}] @var{importer} @var{package} [@var{options}@dots{}]
@end example

@var{importer} specifies the source from which to import package metadata,
and @var{options} specifies a package identifier and other options specific
to @var{importer}. @command{guix import} itself has the following
@var{global-options}:

@table @code
@item --insert=@var{file}
@itemx -i @var{file}
Insert the package definition(s) that the @var{importer} generated into the
specified @var{file}, either in alphabetical order among existing package
definitions, or at the end of the file otherwise.
@end table

Some of the importers rely on the ability to run the @command{gpgv}
command.  For these, GnuPG must be installed and in @code{$PATH}; run
@code{guix install gnupg} if needed.

Currently, the available ``importers'' are:

@table @code
@item gnu
Import metadata for the given GNU package.  This provides a template for the
latest version of that GNU package, including the hash of its source
tarball, and its canonical synopsis and description.

Additional information such as the package dependencies and its license
needs to be figured out manually.

For example, the following command returns a package definition for
GNU@tie{}Hello:

@example
guix import gnu hello
@end example

Specific command-line options are:

@table @code
@item --key-download=@var{policy}
As for @command{guix refresh}, specify the policy to handle missing OpenPGP
keys when verifying the package signature.  @xref{Invocando guix refresh,
@option{--key-download}}.
@end table

@item pypi
@cindex pypi
Import metadata from the @uref{https://pypi.python.org/, Python Package
Index}.  Information is taken from the JSON-formatted description available
at @code{pypi.python.org} and usually includes all the relevant information,
including package dependencies.  For maximum efficiency, it is recommended
to install the @command{unzip} utility, so that the importer can unzip
Python wheels and gather data from them.

The command below imports metadata for the latest version of the
@code{itsdangerous} Python package:

@example
guix import pypi itsdangerous
@end example

You can also ask for a specific version:

@example
guix import pypi itsdangerous@@1.1.0
@end example

@table @code
@item --recursive
@itemx -r
Traverse the dependency graph of the given upstream package recursively and
generate package expressions for all those packages that are not yet in
Guix.
@end table

@item gem
@cindex gem
Import metadata from @uref{https://rubygems.org/, RubyGems}.  Information is
taken from the JSON-formatted description available at @code{rubygems.org}
and includes most relevant information, including runtime dependencies.
There are some caveats, however.  The metadata doesn't distinguish between
synopses and descriptions, so the same string is used for both fields.
Additionally, the details of non-Ruby dependencies required to build native
extensions is unavailable and left as an exercise to the packager.

The command below imports metadata for the @code{rails} Ruby package:

@example
guix import gem rails
@end example

You can also ask for a specific version:

@example
guix import gem rails@@7.0.4
@end example

@table @code
@item --recursive
@itemx -r
Traverse the dependency graph of the given upstream package recursively and
generate package expressions for all those packages that are not yet in
Guix.
@end table

@item minetest
@cindex minetest
@cindex ContentDB
Import metadata from @uref{https://content.minetest.net, ContentDB}.
Information is taken from the JSON-formatted metadata provided through
@uref{https://content.minetest.net/help/api/, ContentDB's API} and includes
most relevant information, including dependencies.  There are some caveats,
however.  The license information is often incomplete.  The commit hash is
sometimes missing.  The descriptions are in the Markdown format, but Guix
uses Texinfo instead.  Texture packs and subgames are unsupported.

The command below imports metadata for the Mesecons mod by Jeija:

@example
guix import minetest Jeija/mesecons
@end example

The author name can also be left out:

@example
guix import minetest mesecons
@end example

@table @code
@item --recursive
@itemx -r
Traverse the dependency graph of the given upstream package recursively and
generate package expressions for all those packages that are not yet in
Guix.
@end table

@item cpan
@cindex CPAN
Import metadata from @uref{https://www.metacpan.org/, MetaCPAN}.
Information is taken from the JSON-formatted metadata provided through
@uref{https://fastapi.metacpan.org/, MetaCPAN's API} and includes most
relevant information, such as module dependencies.  License information
should be checked closely.  If Perl is available in the store, then the
@code{corelist} utility will be used to filter core modules out of the list
of dependencies.

The command below imports metadata for the Acme::Boolean Perl module:

@example
guix import cpan Acme::Boolean
@end example

Like many other importers, the @code{cpan} importer supports recursive
imports:

@table @code
@item --recursive
@itemx -r
Traverse the dependency graph of the given upstream package recursively and
generate package expressions for all those packages that are not yet in
Guix.
@end table

@item cran
@cindex CRAN
@cindex Bioconductor
Import metadata from @uref{https://cran.r-project.org/, CRAN}, the central
repository for the @uref{https://r-project.org, GNU@tie{}R statistical and
graphical environment}.

Information is extracted from the @file{DESCRIPTION} file of the package.

The command below imports metadata for the Cairo R package:

@example
guix import cran Cairo
@end example

You can also ask for a specific version:

@example
guix import cran rasterVis@@0.50.3
@end example

When @option{--recursive} is added, the importer will traverse the
dependency graph of the given upstream package recursively and generate
package expressions for all those packages that are not yet in Guix.

When @option{--style=specification} is added, the importer will generate
package definitions whose inputs are package specifications instead of
references to package variables.  This is useful when generated package
definitions are to be appended to existing user modules, as the list of used
package modules need not be changed.  The default is
@option{--style=variable}.

When @option{--prefix=license:} is added, the importer will prefix license
atoms with @code{license:}, allowing a prefixed import of @code{(guix
licenses)}.

When @option{--archive=bioconductor} is added, metadata is imported from
@uref{https://www.bioconductor.org/, Bioconductor}, a repository of R
packages for the analysis and comprehension of high-throughput genomic data
in bioinformatics.

Information is extracted from the @file{DESCRIPTION} file contained in the
package archive.

The command below imports metadata for the GenomicRanges R package:

@example
guix import cran --archive=bioconductor GenomicRanges
@end example

Finally, you can also import R packages that have not yet been published on
CRAN or Bioconductor as long as they are in a git repository.  Use
@option{--archive=git} followed by the URL of the git repository:

@example
guix import cran --archive=git https://github.com/immunogenomics/harmony
@end example

@item texlive
@cindex TeX Live
@cindex CTAN
Import TeX package information from the TeX Live package database for TeX
packages that are part of the @uref{https://www.tug.org/texlive/, TeX Live
distribution}.

Information about the package is obtained from the TeX Live package
database, a plain text file that is included in the @code{texlive-scripts}
package.  The source code is downloaded from possibly multiple locations in
the SVN repository of the Tex Live project.  Note that therefore SVN must be
installed and in @code{$PATH}; run @code{guix install subversion} if needed.

The command below imports metadata for the @code{fontspec} TeX package:

@example
guix import texlive fontspec
@end example

Additional options include:

@table @code
@item --recursive
@itemx -r
Traverse the dependency graph of the given upstream package recursively and
generate package expressions for all those packages that are not yet in
Guix.
@end table

@item json
@cindex JSON, import
Import package metadata from a local JSON file.  Consider the following
example package definition in JSON format:

@example
@{
  "name": "hello",
  "version": "2.10",
  "source": "mirror://gnu/hello/hello-2.10.tar.gz",
  "build-system": "gnu",
  "home-page": "https://www.gnu.org/software/hello/",
  "synopsis": "Hello, GNU world: An example GNU package",
  "description": "GNU Hello prints a greeting.",
  "license": "GPL-3.0+",
  "native-inputs": ["gettext"]
@}
@end example

The field names are the same as for the @code{<package>} record
(@xref{Definindo pacotes}).  References to other packages are provided as
JSON lists of quoted package specification strings such as @code{guile} or
@code{guile@@2.0}.

The importer also supports a more explicit source definition using the
common fields for @code{<origin>} records:

@example
@{
  @dots{}
  "source": @{
    "method": "url-fetch",
    "uri": "mirror://gnu/hello/hello-2.10.tar.gz",
    "sha256": @{
      "base32": "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i"
    @}
  @}
  @dots{}
@}
@end example

The command below reads metadata from the JSON file @code{hello.json} and
outputs a package expression:

@example
guix import json hello.json
@end example

@item hackage
@cindex hackage
Import metadata from the Haskell community's central package archive
@uref{https://hackage.haskell.org/, Hackage}.  Information is taken from
Cabal files and includes all the relevant information, including package
dependencies.

Specific command-line options are:

@table @code
@item --stdin
@itemx -s
Read a Cabal file from standard input.
@item --no-test-dependencies
@itemx -t
Do not include dependencies required only by the test suites.
@item --cabal-environment=@var{alist}
@itemx -e @var{alist}
@var{alist} is a Scheme alist defining the environment in which the Cabal
conditionals are evaluated.  The accepted keys are: @code{os}, @code{arch},
@code{impl} and a string representing the name of a flag.  The value
associated with a flag has to be either the symbol @code{true} or
@code{false}.  The value associated with other keys has to conform to the
Cabal file format definition.  The default value associated with the keys
@code{os}, @code{arch} and @code{impl} is @samp{linux}, @samp{x86_64} and
@samp{ghc}, respectively.
@item --recursive
@itemx -r
Traverse the dependency graph of the given upstream package recursively and
generate package expressions for all those packages that are not yet in
Guix.
@end table

The command below imports metadata for the latest version of the HTTP
Haskell package without including test dependencies and specifying the value
of the flag @samp{network-uri} as @code{false}:

@example
guix import hackage -t -e "'((\"network-uri\" . false))" HTTP
@end example

A specific package version may optionally be specified by following the
package name by an at-sign and a version number as in the following example:

@example
guix import hackage mtl@@2.1.3.1
@end example

@item stackage
@cindex stackage
The @code{stackage} importer is a wrapper around the @code{hackage} one.  It
takes a package name, looks up the package version included in a long-term
support (LTS) @uref{https://www.stackage.org, Stackage} release and uses the
@code{hackage} importer to retrieve its metadata.  Note that it is up to you
to select an LTS release compatible with the GHC compiler used by Guix.

Specific command-line options are:

@table @code
@item --no-test-dependencies
@itemx -t
Do not include dependencies required only by the test suites.
@item --lts-version=@var{versão}
@itemx -l @var{versão}
@var{version} is the desired LTS release version.  If omitted the latest
release is used.
@item --recursive
@itemx -r
Traverse the dependency graph of the given upstream package recursively and
generate package expressions for all those packages that are not yet in
Guix.
@end table

The command below imports metadata for the HTTP Haskell package included in
the LTS Stackage release version 7.18:

@example
guix import stackage --lts-version=7.18 HTTP
@end example

@item elpa
@cindex elpa
Import metadata from an Emacs Lisp Package Archive (ELPA) package repository
(@pxref{Packages,,, emacs, The GNU Emacs Manual}).

Specific command-line options are:

@table @code
@item --archive=@var{repo}
@itemx -a @var{repo}
@var{repo} identifies the archive repository from which to retrieve the
information.  Currently the supported repositories and their identifiers
are:
@itemize -
@item
@uref{https://elpa.gnu.org/packages, GNU}, selected by the @code{gnu}
identifier.  This is the default.

Packages from @code{elpa.gnu.org} are signed with one of the keys contained
in the GnuPG keyring at @file{share/emacs/25.1/etc/package-keyring.gpg} (or
similar) in the @code{emacs} package (@pxref{Package Installation, ELPA
package signatures,, emacs, The GNU Emacs Manual}).

@item
@uref{https://elpa.nongnu.org/nongnu/, NonGNU}, selected by the
@code{nongnu} identifier.

@item
@uref{https://stable.melpa.org/packages, MELPA-Stable}, selected by the
@code{melpa-stable} identifier.

@item
@uref{https://melpa.org/packages, MELPA}, selected by the @code{melpa}
identifier.
@end itemize

@item --recursive
@itemx -r
Traverse the dependency graph of the given upstream package recursively and
generate package expressions for all those packages that are not yet in
Guix.
@end table

@item crate
@cindex crate
Import metadata from the crates.io Rust package repository
@uref{https://crates.io, crates.io}, as in this example:

@example
guix import crate blake2-rfc
@end example

The crate importer also allows you to specify a version string:

@example
guix import crate constant-time-eq@@0.1.0
@end example

Additional options include:

@table @code
@item --allow-yanked
If no non-yanked version of a crate is available, use the latest yanked
version instead instead of aborting.
@item --lockfile=@var{file}
@itemx -f @var{arquivo}
When @option{--lockfile} is specified, the importer will ignore other
options and won't output package expressions, instead importing source
expressions from @var{file}, a @file{Cargo.lock} file.

@xref{Packaging Rust Crates,,, guix-cookbook, GNU Guix Cookbook}, for
packaging workflow utilizing it.
@end table

@item elm
@cindex elm
Import metadata from the Elm package repository
@uref{https://package.elm-lang.org, package.elm-lang.org}, as in this
example:

@example
guix import elm elm-explorations/webgl
@end example

The Elm importer also allows you to specify a version string:

@example
guix import elm elm-explorations/webgl@@1.1.3
@end example

Additional options include:

@table @code
@item --recursive
@itemx -r
Traverse the dependency graph of the given upstream package recursively and
generate package expressions for all those packages that are not yet in
Guix.
@end table

@item npm-binary
@cindex npm
@cindex Node.js
Import metadata from the @uref{https://registry.npmjs.org, npm Registry}, as
in this example:

@example
guix import npm-binary buffer-crc32
@end example

The npm-binary importer also allows you to specify a version string:

@example
guix import npm-binary buffer-crc32@@1.0.0
@end example

@quotation Nota
Generated package expressions skip the build step of the
@code{node-build-system}. As such, generated package expressions often refer
to transpiled or generated files, instead of being built from source.
@end quotation

Additional options include:

@table @code
@item --recursive
@itemx -r
Traverse the dependency graph of the given upstream package recursively and
generate package expressions for all those packages that are not yet in
Guix.
@end table

@item opam
@cindex OPAM
@cindex OCaml
Import metadata from the @uref{https://opam.ocaml.org/, OPAM} package
repository used by the OCaml community.

Additional options include:

@table @code
@item --recursive
@itemx -r
Traverse the dependency graph of the given upstream package recursively and
generate package expressions for all those packages that are not yet in
Guix.
@end table

@item composer
@cindex Composer
@cindex PHP
Import metadata from the @uref{https://getcomposer.org/, Composer} package
archive used by the PHP community, as in this example:

@example
guix import composer phpunit/phpunit
@end example

Additional options include:

@table @code
@item --recursive
@itemx -r
Traverse the dependency graph of the given upstream package recursively and
generate package expressions for all those packages that are not yet in
Guix.
@item --repo
By default, packages are searched in the official OPAM repository.  This
option, which can be used more than once, lets you add other repositories
which will be searched for packages.  It accepts as valid arguments:

@itemize
@item the name of a known repository - can be one of @code{opam},
      @code{coq} (equivalent to @code{coq-released}), @code{coq-core-dev},
@code{coq-extra-dev} or @code{grew}.
@item the URL of a repository as expected by the
      @code{opam repository add} command (for instance, the URL equivalent of the
above @code{opam} name would be @uref{https://opam.ocaml.org}).
@item the path to a local copy of a repository (a directory containing a
      @file{packages/} sub-directory).
@end itemize

Repositories are assumed to be passed to this option by order of
preference.  The additional repositories will not replace the default
@code{opam} repository, which is always kept as a fallback.

Also, please note that versions are not compared across repositories.  The
first repository (from left to right) that has at least one version of a
given package will prevail over any others, and the version imported will be
the latest one found @emph{in this repository only}.

@end table

@item go
@cindex go
Import metadata for a Go module using @uref{https://proxy.golang.org,
proxy.golang.org}.

@example
guix import go gopkg.in/yaml.v2
@end example

It is possible to use a package specification with a @code{@@VERSION} suffix
to import a specific version.

Additional options include:

@table @code
@item --recursive
@itemx -r
Traverse the dependency graph of the given upstream package recursively and
generate package expressions for all those packages that are not yet in
Guix.
@item --pin-versions
When using this option, the importer preserves the exact versions of the Go
modules dependencies instead of using their latest available versions.  This
can be useful when attempting to import packages that recursively depend on
former versions of themselves to build.  When using this mode, the symbol of
the package is made by appending the version to its name, so that multiple
versions of the same package can coexist.
@end table

@item egg
@cindex egg
Import metadata for @uref{https://wiki.call-cc.org/eggs, CHICKEN eggs}.  The
information is taken from @file{PACKAGE.egg} files found in the
@uref{git://code.call-cc.org/eggs-5-all, eggs-5-all} Git repository.
However, it does not provide all the information that we need, there is no
``description'' field, and the licenses used are not always precise (BSD is
often used instead of BSD-N).

@example
guix import egg sourcehut
@end example

You can also ask for a specific version:

@example
guix import egg arrays@@1.0
@end example

Additional options include:
@table @code
@item --recursive
@itemx -r
Traverse the dependency graph of the given upstream package recursively and
generate package expressions for all those packages that are not yet in
Guix.
@end table

@item hexpm
@cindex hexpm
Import metadata from the hex.pm Erlang and Elixir package repository
@uref{https://hex.pm, hex.pm}, as in this example:

@example
guix import hexpm stun
@end example

The importer tries to determine the build system used by the package.

The hexpm importer also allows you to specify a version string:

@example
guix import hexpm cf@@0.3.0
@end example

Additional options include:

@table @code
@item --recursive
@itemx -r
Traverse the dependency graph of the given upstream package recursively and
generate package expressions for all those packages that are not yet in
Guix.
@end table
@end table

The structure of the @command{guix import} code is modular.  It would be
useful to have more importers for other package formats, and your help is
welcome here (@pxref{Contribuindo}).

@node Invocando guix refresh
@section Invocando @command{guix refresh}

@cindex @command{guix refresh}
The primary audience of the @command{guix refresh} command is packagers.  As
a user, you may be interested in the @option{--with-latest} option, which
can bring you package update superpowers built upon @command{guix refresh}
(@pxref{Opções de transformação de pacote, @option{--with-latest}}).  By
default, @command{guix refresh} reports any packages provided by the
distribution that are outdated compared to the latest upstream version, like
this:

@example
$ guix refresh
gnu/packages/gettext.scm:29:13: gettext would be upgraded from 0.18.1.1 to 0.18.2.1
gnu/packages/glib.scm:77:12: glib would be upgraded from 2.34.3 to 2.37.0
@end example

Alternatively, one can specify packages to consider, in which case a warning
is emitted for packages that lack an updater:

@example
$ guix refresh coreutils guile guile-ssh
gnu/packages/ssh.scm:205:2: warning: no updater for guile-ssh
gnu/packages/guile.scm:136:12: guile would be upgraded from 2.0.12 to 2.0.13
@end example

@command{guix refresh} browses the upstream repository of each package and
determines the highest version number of the releases therein.  The command
knows how to update specific types of packages: GNU packages, ELPA packages,
etc.---see the documentation for @option{--type} below.  There are many
packages, though, for which it lacks a method to determine whether a new
upstream release is available.  However, the mechanism is extensible, so
feel free to get in touch with us to add a new method!

If for some reason you don't want to update to the latest version, you can
update to a specific version by appending an equal sign and the desired
version number to the package specification.  Note that not all updaters
support this; an error is reported when an updater cannot refresh to the
specified version.

@example
$ guix refresh -u guile=3.0.4
@dots{}
gnu/packages/guile.scm:392:2: guile: updating from version 3.0.3 to version 3.0.4...
@dots{}
$ guix refresh -u guile@@2.0=2.0.12
@dots{}
gnu/packages/guile.scm:147:2: guile: updating from version 2.0.10 to version 2.0.12...
@dots{}
@end example

@cindex target version, guix refresh
In some specific cases, you may have many packages specified via a manifest
or a module selection which should all be updated together; for these cases,
the @option{--target-version} option can be provided to have them all
refreshed to the same version, as shown in the examples below:

@example
$ guix refresh qtbase qtdeclarative --target-version=6.5.2
gnu/packages/qt.scm:1248:13: qtdeclarative would be upgraded from 6.3.2 to 6.5.2
gnu/packages/qt.scm:584:2: qtbase would be upgraded from 6.3.2 to 6.5.2
@end example

@example
$ guix refresh --manifest=qt5-manifest.scm --target-version=5.15.10
gnu/packages/qt.scm:1173:13: qtxmlpatterns would be upgraded from 5.15.8 to 5.15.10
gnu/packages/qt.scm:1202:13: qtdeclarative would be upgraded from 5.15.8 to 5.15.10
gnu/packages/qt.scm:1762:13: qtserialbus would be upgraded from 5.15.8 to 5.15.10
gnu/packages/qt.scm:2070:13: qtquickcontrols2 would be upgraded from 5.15.8 to 5.15.10
@dots{}
@end example

@example
$ guix refresh -s module:kde-plasma --target-version=6.3.6
[@dots{}] plasma-systemmonitor would be upgraded from 6.3.4 to 6.3.6
[@dots{}] plasma-workspace-wallpapers would be upgraded from 6.3.4 to 6.3.6
[@dots{}] plasma-browser-integration would be upgraded from 6.3.4 to 6.3.6
@dots{}
@end example

@cindex partial target version, guix refresh
The @option{--target-version} option accepts partial version prefixes, which
can be useful to update to the latest major or major-minor prefixed version:

@example
$ guix refresh qtbase@@5 qtdeclarative@@5 --target-version=5
gnu/packages/qt.scm:1472:13: qtdeclarative would be upgraded from 5.15.8 to 5.15.10
gnu/packages/qt.scm:452:13: qtbase would be upgraded from 5.15.8 to 5.15.10
@end example

@cindex partial version specification, guix refresh
A per-package equivalent to --target-version is made available by prefixing
the version specification with the @samp{~} (tilde) character.  For example:

@example
$ guix refresh bash=~5 guile=~3
gnu/packages/guile.scm:354:13: guile would be upgraded from 3.0.9 to 3.0.10
gnu/packages/bash.scm:150:15: bash would be upgraded from 5.1.16 to 5.2.37
@end example

Sometimes the upstream name differs from the package name used in Guix, and
@command{guix refresh} needs a little help.  Most updaters honor the
@code{upstream-name} property in package definitions, which can be used to
that effect:

@lisp
(define-public network-manager
  (package
    (name "network-manager")
    ;; @dots{}
    (properties '((upstream-name . "NetworkManager")))))
@end lisp

When passed @option{--update}, it modifies distribution source files to
update the version numbers and source code hashes of those package
definitions, as well as possibly their inputs (@pxref{Definindo pacotes}).
This is achieved by downloading each package's latest source tarball and its
associated OpenPGP signature, authenticating the downloaded tarball against
its signature using @command{gpgv}, and finally computing its hash---note
that GnuPG must be installed and in @code{$PATH}; run @code{guix install
gnupg} if needed.

You might also want to update definitions that correspond to the packages
installed in your profile:

@example
$ ./pre-inst-env guix refresh -u \
       $(guix package --list-installed | cut -f1)
@end example

When considering whether to upgrade a package, it is sometimes convenient to
know which packages would be affected by the upgrade and should be checked
for compatibility.  For this the @option{--list-dependent} option may be
used when passing @command{guix refresh} one or more package names.

When the public key used to sign the tarball is missing from the user's
keyring, an attempt is made to automatically retrieve it from a public key
server; when this is successful, the key is added to the user's keyring;
otherwise, @command{guix refresh} reports an error.

The following options are supported:

@table @code

@item --recursive
Consider the packages specified, and all the packages upon which they
depend.

@example
$ guix refresh --recursive coreutils
gnu/packages/acl.scm:40:13: acl would be upgraded from 2.2.53 to 2.3.1
gnu/packages/m4.scm:30:12: 1.4.18 is already the latest version of m4
gnu/packages/xml.scm:68:2: warning: no updater for expat
gnu/packages/multiprecision.scm:40:12: 6.1.2 is already the latest version of gmp
@dots{}
@end example

@item --expression=@var{expr}
@itemx -e @var{expr}
Considere o pacote que @var{expr} avalia.

This is useful to precisely refer to a package, as in this example:

@example
guix refresh -l -e '(@@@@ (gnu packages commencement) glibc-final)'
@end example

This command lists the dependents of the ``final'' libc (essentially all the
packages).

@item --update
@itemx -u
Update distribution source files (package definitions) in place.  This is
usually run from a checkout of the Guix source tree (@pxref{Executando guix antes dele ser instalado}):

@example
./pre-inst-env guix refresh -s non-core -u
@end example

@xref{Definindo pacotes}, for more information on package definitions.  You
can also run it on packages from a third-party channel:

@example
guix refresh -L /path/to/channel -u @var{package}
@end example

@xref{Criando um canal}, on how to create a channel.

This command updates the version and source code hash of the package.
Depending on the updater being used, it can also update the various
@samp{inputs} fields of the package.  In some cases, the updater might get
inputs wrong---it might not know about an extra input that's necessary, or
it might add an input that should be avoided.

@cindex @code{updater-extra-inputs}, package property
@cindex @code{updater-ignored-inputs}, package property
To address that, packagers can add properties stating inputs that should be
added to those found by the updater or inputs that should be ignored: the
@code{updater-extra-inputs} and @code{updater-ignored-inputs} properties
pertain to ``regular'' inputs, and there are equivalent properties for
@samp{native} and @samp{propagated} inputs.  In the example below, we tell
the updater that we need @samp{openmpi} as an additional input:

@lisp
(define-public python-mpi4py
  (package
    (name "python-mpi4py")
    ;; @dots{}
    (inputs (list openmpi))
    (properties
     '((updater-extra-inputs . ("openmpi"))))))
@end lisp

That way, @command{guix refresh -u python-mpi4py} will leave the
@samp{openmpi} input, even if it is not among the inputs it would normally
add.

@item --select=[@var{subset}]
@itemx -s @var{subset}
Select all the packages in @var{subset}, one of @code{core}, @code{non-core}
or @code{module:@var{name}}.

The @code{core} subset refers to all the packages at the core of the
distribution---i.e., packages that are used to build ``everything else''.
This includes GCC, libc, Binutils, Bash, etc.  Usually, changing one of
these packages in the distribution entails a rebuild of all the others.
Thus, such updates are an inconvenience to users in terms of build time or
bandwidth used to achieve the upgrade.

The @code{non-core} subset refers to the remaining packages.  It is
typically useful in cases where an update of the core packages would be
inconvenient.

The @code{module:@var{name}} subset refers to all the packages in a
specified guile module.  The module can be specified as @code{module:guile}
or @code{module:(gnu packages guile)}, the former is a shorthand for the
later.

@item --manifest=@var{arquivo}
@itemx -m @var{arquivo}
Select all the packages from the manifest in @var{file}.  This is useful to
check if any packages of the user manifest can be updated.

@item --type=@var{updater}
@itemx -t @var{updater}
Select only packages handled by @var{updater} (may be a comma-separated list
of updaters).  Currently, @var{updater} may be one of:

@table @code
@item gnu
the updater for GNU packages;
@item savannah
the updater for packages hosted at @uref{https://savannah.gnu.org,
Savannah};
@item sourceforge
the updater for packages hosted at @uref{https://sourceforge.net,
SourceForge};
@item gnome
the updater for GNOME packages;
@item kde
the updater for KDE packages;
@item xorg
the updater for X.org packages;
@item kernel.org
the updater for packages hosted on kernel.org;
@item egg
the updater for @uref{https://wiki.call-cc.org/eggs/, Egg} packages;
@item elpa
the updater for @uref{https://elpa.gnu.org/, ELPA} packages;
@item cran
the updater for @uref{https://cran.r-project.org/, CRAN} packages;
@item bioconductor
the updater for @uref{https://www.bioconductor.org/, Bioconductor} R
packages;
@item cpan
the updater for @uref{https://www.cpan.org/, CPAN} packages;
@item pypi
the updater for @uref{https://pypi.python.org, PyPI} packages.
@item gem
the updater for @uref{https://rubygems.org, RubyGems} packages.
@item github
the updater for @uref{https://github.com, GitHub} packages.

The @code{github} updater uses the @uref{https://developer.github.com/v3/,
GitHub API} to query for new releases.  When used repeatedly e.g.@: when
refreshing all packages, GitHub will eventually refuse to answer any further
API requests.  By default 60 API requests per hour are allowed, and a full
refresh on all GitHub packages in Guix requires more than this.
Authentication with GitHub through the use of an API token alleviates these
limits.  To use an API token, set the environment variable
@env{GUIX_GITHUB_TOKEN} to a token procured from
@uref{https://github.com/settings/tokens} or otherwise.
@item hackage
the updater for @uref{https://hackage.haskell.org, Hackage} packages.
@item stackage
the updater for @uref{https://www.stackage.org, Stackage} packages.
@item crate
the updater for @uref{https://crates.io, Crates} packages.
@item launchpad
the updater for @uref{https://launchpad.net, Launchpad} packages.

@item generic-html
a generic updater that crawls, by default, the HTML page where the source
tarball of the package is hosted, when applicable.  Behavior can be
customized with the following package properties:

@table @code
@item release-monitoring-url
an alternate URL to crawl;

@item release-file-regexp
an regular expression matching release file names, whose first subexpression
must correspond to the version string.
@end table

Here is an example package with a custom release monitoring URL and a regexp
matching an unconventional release file name (it's unconventional due to the
use of upper case letter and the lack of a hyphen before the version
string):

@lisp
(package
  ;; @dots{}
  (home-page "http://example.org/software/the-package.html")
  (properties
    `((release-monitoring-url . ,home-page)
      (release-file-regexp . "ThePackage([0-9\\.]+)\\.tgz"))))
@end lisp

@item generic-git
a generic updater for packages hosted on Git repositories.  It tries to be
smart about parsing Git tag names, but if it is not able to parse the tag
name and compare tags correctly, users can define the following properties
for a package.

@itemize
@item @code{release-tag-prefix}: a regular expression for matching a prefix of
the tag name.

@item @code{release-tag-suffix}: a regular expression for matching a suffix of
the tag name.

@item @code{release-tag-version-delimiter}: a string used as the delimiter in
the tag name for separating the numbers of the version.

@item @code{accept-pre-releases}: by default, the updater will ignore
pre-releases; to make it also look for pre-releases, set the this property
to @code{#t}.

@end itemize

@lisp
(package
  (name "foo")
  ;; ...
  (properties
    '((release-tag-prefix . "^release0-")
      (release-tag-suffix . "[a-z]?$")
      (release-tag-version-delimiter . ":"))))
@end lisp


@end table

For instance, the following command only checks for updates of Emacs
packages hosted at @code{elpa.gnu.org} and for updates of CRAN packages:

@example
$ guix refresh --type=elpa,cran
gnu/packages/statistics.scm:819:13: r-testthat would be upgraded from 0.10.0 to 0.11.0
gnu/packages/emacs.scm:856:13: emacs-auctex would be upgraded from 11.88.6 to 11.88.9
@end example

@item --list-updaters
List available updaters and exit (see @option{--type} above).

For each updater, display the fraction of packages it covers; at the end,
display the fraction of packages covered by all these updaters.

@item --list-dependent
@itemx -l
List top-level dependent packages that would need to be rebuilt as a result
of upgrading one or more packages.

@xref{Invocando guix graph, the @code{reverse-package} type of @command{guix
graph}}, for information on how to visualize the list of dependents of a
package.

@xref{build-dependents, @command{guix build --dependents}}, for a convenient
way to build all the dependents of a package.

Be aware that the @option{--list-dependent} option only @emph{approximates}
the rebuilds that would be required as a result of an upgrade.  More
rebuilds might be required under some circumstances.

@example
$ guix refresh --list-dependent flex
Building the following 120 packages would ensure 213 dependent packages are rebuilt:
hop@@2.4.0 emacs-geiser@@0.13 notmuch@@0.18 mu@@0.9.9.5 cflow@@1.4 idutils@@4.6 @dots{}
@end example

The command above lists a set of packages that could be built to check for
compatibility with an upgraded @code{flex} package.

@item --list-transitive
@itemx -T
List all the packages which one or more packages depend upon.

@example
$ guix refresh --list-transitive flex
flex@@2.6.4 depends on the following 25 packages: perl@@5.28.0 help2man@@1.47.6
bison@@3.0.5 indent@@2.2.10 tar@@1.30 gzip@@1.9 bzip2@@1.0.6 xz@@5.2.4 file@@5.33 @dots{}
@end example

The command above lists a set of packages which, when changed, would cause
@code{flex} to be rebuilt.

@item --load-path=@var{directory}
@itemx -L @var{diretório}
Add @var{directory} to the front of the package module search path
(@pxref{Módulos de pacote}).

This allows users to define their own packages and make them visible to the
command-line tools.

@end table

The following options can be used to customize GnuPG operation:

@table @code

@item --gpg=@var{command}
Use @var{command} as the GnuPG 2.x command.  @var{command} is searched for
in @code{$PATH}.

@item --keyring=@var{file}
Use @var{file} as the keyring for upstream keys.  @var{file} must be in the
@dfn{keybox format}.  Keybox files usually have a name ending in @file{.kbx}
and the GNU@tie{}Privacy Guard (GPG) can manipulate these files
(@pxref{kbxutil, @command{kbxutil},, gnupg, Using the GNU Privacy Guard},
for information on a tool to manipulate keybox files).

When this option is omitted, @command{guix refresh} uses
@file{~/.config/guix/upstream/trustedkeys.kbx} as the keyring for upstream
signing keys.  OpenPGP signatures are checked against keys from this
keyring; missing keys are downloaded to this keyring as well (see
@option{--key-download} below).

You can fetch keys to a specific keybox file like this:

@example
gpg --no-default-keyring --keyring mykeyring.kbx \
  --recv-keys @value{OPENPGP-SIGNING-KEY-ID}
@end example

@xref{GPG Configuration Options, @option{--keyring},, gnupg, Using the GNU
Privacy Guard}, for more information on GPG's @option{--keyring} option.

@item --key-download=@var{policy}
Handle missing OpenPGP keys according to @var{policy}, which may be one of:

@table @code
@item always
Always download missing OpenPGP keys from the key server, and add them to
the user's GnuPG keyring.

@item never
Never try to download missing OpenPGP keys.  Instead just bail out.

@item interactive
When a package signed with an unknown OpenPGP key is encountered, ask the
user whether to download it or not.

@item auto
Automatically selects the @code{interactive} policy when the standard input
is connected to a pseudo terminal (TTY), else @code{always}.  This is the
default behavior.
@end table

@item --key-server=@var{host}
Use @var{host} as the OpenPGP key server when importing a public key.

@end table

@node Invocando guix style
@section Invoking @command{guix style}

@cindex @command{guix style}
@cindex styling rules
@cindex lint, code style
@cindex format, code style
@cindex format conventions
The @command{guix style} command helps users and packagers alike style their
package definitions and configuration files according to the latest
fashionable trends.  It can either reformat whole files, with the
@option{--whole-file} option, or apply specific @dfn{styling rules} to
individual package definitions.  The command currently provides the
following styling rules:

@itemize
@item
formatting package definitions according to the project's conventions
(@pxref{Formatação de código});

@item
rewriting package inputs to the ``new style'', as explained below.
@end itemize

The way package inputs are written is going through a transition
(@pxref{Referência do package}, for more on package inputs).  Until version
1.3.0, package inputs were written using the ``old style'', where each input
was given an explicit label, most of the time the package name:

@lisp
(package
  ;; @dots{}
  ;; The "old style" (deprecated).
  (inputs `(("libunistring" ,libunistring)
            ("libffi" ,libffi))))
@end lisp

Today, the old style is deprecated and the preferred style looks like this:

@lisp
(package
  ;; @dots{}
  ;; The "new style".
  (inputs (list libunistring libffi)))
@end lisp

Likewise, uses of @code{alist-delete} and friends to manipulate inputs is
now deprecated in favor of @code{modify-inputs} (@pxref{Definindo variantes de pacote}, for more info on @code{modify-inputs}).

In the vast majority of cases, this is a purely mechanical change on the
surface syntax that does not even incur a package rebuild.  Running
@command{guix style -S inputs} can do that for you, whether you're working
on packages in Guix proper or in an external channel.

A sintaxe geral é:

@example
guix style [@var{options}] @var{package}@dots{}
@end example

This causes @command{guix style} to analyze and rewrite the definition of
@var{package}@dots{} or, when @var{package} is omitted, of @emph{all} the
packages.  The @option{--styling} or @option{-S} option allows you to select
the style rule, the default rule being @code{format}---see below.

To reformat entire source files, the syntax is:

@example
guix style --whole-file @var{file}@dots{}
@end example

The available options are listed below.

@table @code
@item --dry-run
@itemx -n
Show source file locations that would be edited but do not modify them.

@item --whole-file
@itemx -f
Reformat the given files in their entirety.  In that case, subsequent
arguments are interpreted as file names (rather than package names), and the
@option{--styling} option has no effect.

As an example, here is how you might reformat your operating system
configuration (you need write permissions for the file):

@example
guix style -f /etc/config.scm
@end example

@item --alphabetical-sort
@itemx -A
Place the top-level package definitions in the given files in alphabetical
order.  Package definitions with matching names are placed with versions in
descending order.  This option only has an effect in combination with
@option{--whole-file}.

@item --styling=@var{rule}
@itemx -S @var{rule}
Apply @var{rule}, one of the following styling rules:

@table @code
@item format
Format the given package definition(s)---this is the default styling rule.
For example, a packager running Guix on a checkout (@pxref{Executando guix antes dele ser instalado}) might want to reformat the definition of the
Coreutils package like so:

@example
./pre-inst-env guix style coreutils
@end example

@item inputs
Rewrite package inputs to the ``new style'', as described above.  This is
how you would rewrite inputs of package @code{whatnot} in your own channel:

@example
guix style -L ~/my/channel -S inputs whatnot
@end example

Rewriting is done in a conservative way: preserving comments and bailing out
if it cannot make sense of the code that appears in an inputs field.  The
@option{--input-simplification} option described below provides fine-grain
control over when inputs should be simplified.

@item arguments
Rewrite package arguments to use G-expressions (@pxref{Expressões-G}).  For
example, consider this package definition:

@lisp
(define-public my-package
  (package
    ;; @dots{}
    (arguments      ;old-style quoted arguments
     '(#:make-flags '("V=1")
       #:phases (modify-phases %standard-phases
                  (delete 'build))))))
@end lisp

@noindent
Running @command{guix style -S arguments} on this package would rewrite its
@code{arguments} field like to:

@lisp
(define-public my-package
  (package
    ;; @dots{}
    (arguments
      (list #:make-flags #~'("V=1")
            #:phases #~(modify-phases %standard-phases
                         (delete 'build))))))
@end lisp

Note that changes made by the @code{arguments} rule do not entail a rebuild
of the affected packages.  Furthermore, if a package definition happens to
be using G-expressions already, @command{guix style} leaves it unchanged.

@item git-source
If the @code{home-page} is a Git repository (as per
@code{git-repository-url?}), and the actual Git repository is tagged with
@code{version} or @code{(string-append ``v'' version)}, change the package
origin to the @code{git-fetch} method (@pxref{Referência do origin}).  Consider
this example:

@lisp
(define-public guile-json-4
  (package
    (inherit guile-json-3)
    (name "guile-json")
    (version "4.7.3")
    (source (origin
              (method url-fetch)
              (uri (string-append "mirror://savannah/guile-json/guile-json-"
                                  version ".tar.gz"))
              (sha256
               (base32
                "127k2xc07w1gnyqs40z4865l8p3ra5xgpcn569dz04lxsa709fiq"))))))
@end lisp

@noindent
Running @command{guix style -S git-source} on this package would rewrite its
@code{source} field like to:

@lisp
(define-public guile-json-4
  (package
    (inherit guile-json-3)
    (name "guile-json")
    (version "4.7.3")
    (source (origin
              (method git-fetch)
              (uri (git-reference (url
                                   "https://github.com/aconchillo/guile-json")
                                  (commit version)))
              (file-name (git-file-name name version))
              (sha256 (base32
                       "0akhm8xjv8fl55fyq0w6c9c6hi5j7mifjx01w07np7qg1cjl9f06"))))))
@end lisp

@end table

@item --list-stylings
@itemx -l
List and describe the available styling rules and exit.

@item --load-path=@var{directory}
@itemx -L @var{diretório}
Add @var{directory} to the front of the package module search path
(@pxref{Módulos de pacote}).

@item --expression=@var{expr}
@itemx -e @var{expr}
Style the package @var{expr} evaluates to.

Por exemplo, executando:

@example
guix style -e '(@@ (gnu packages gcc) gcc-5)'
@end example

styles the @code{gcc-5} package definition.

@item --input-simplification=@var{policy}
When using the @code{inputs} styling rule, with @samp{-S inputs}, this
option specifies the package input simplification policy for cases where an
input label does not match the corresponding package name.  @var{policy} may
be one of the following:

@table @code
@item silent
Simplify inputs only when the change is ``silent'', meaning that the package
does not need to be rebuilt (its derivation is unchanged).

@item safe
Simplify inputs only when that is ``safe'' to do: the package might need to
be rebuilt, but the change is known to have no observable effect.

@item always
Simplify inputs even when input labels do not match package names, and even
if that might have an observable effect.
@end table

The default is @code{silent}, meaning that input simplifications do not
trigger any package rebuild.
@end table

@node Invocando guix lint
@section Invocando @command{guix lint}

@cindex @command{guix lint}
@cindex package, checking for errors
The @command{guix lint} command is meant to help package developers avoid
common errors and use a consistent style.  It runs a number of checks on a
given set of packages in order to find common mistakes in their
definitions.  Available @dfn{checkers} include (see @option{--list-checkers}
for a complete list):

@table @code
@item synopsis
@itemx description
Validate certain typographical and stylistic rules about package
descriptions and synopses.

@item inputs-should-be-native
Identify inputs that should most likely be native inputs.

@item source
@itemx home-page
@itemx mirror-url
@itemx github-url
@itemx source-file-name
Probe @code{home-page} and @code{source} URLs and report those that are
invalid.  Suggest a @code{mirror://} URL when applicable.  If the
@code{source} URL redirects to a GitHub URL, recommend usage of the GitHub
URL@.  Check that the source file name is meaningful, e.g.@: is not just a
version number or ``git-checkout'', without a declared @code{file-name}
(@pxref{Referência do 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 misplaced-flags
Parse the @code{make-flags} and @code{configure-flags} to check for any
flags which should be set with another flag as part of the build-system.
For example,

@lisp
(build-system cmake-build-system)
(arguments
 (list #:configure-flags #~(list "-DCMAKE_BUILD_TYPE=RELEASE"
                                 "-DTESTS=ON")))
@end lisp

should instead be written as:

@lisp
(build-system cmake-build-system)
(arguments
 (list #:build-type "RELEASE"
       #:configure-flags #~(list "-DTESTS=ON")))
@end lisp

@item derivation
Check that the derivation of the given packages can be successfully computed
for all the supported systems (@pxref{Derivações}).

@item profile-collisions
Check whether installing the given packages in a profile would lead to
collisions.  Collisions occur when several packages with the same name but a
different version or a different store file name are propagated.
@xref{Referência do package, @code{propagated-inputs}}, for more information on
propagated inputs.

@item archival
@cindex Software Heritage, source code archive
@cindex archival of source code, Software Heritage
Checks whether the package's source code is archived at
@uref{https://www.softwareheritage.org, Software Heritage}.

When the source code that is not archived comes from a version-control
system (VCS)---e.g., it's obtained with @code{git-fetch}, send Software
Heritage a ``save'' request so that it eventually archives it.  This ensures
that the source will remain available in the long term, and that Guix can
fall back to Software Heritage should the source code disappear from its
original host.  The status of recent ``save'' requests can be
@uref{https://archive.softwareheritage.org/save/#requests, viewed on-line}.

When source code is a tarball obtained with @code{url-fetch}, simply print a
message when it is not archived.  As of this writing, Software Heritage does
not allow requests to save arbitrary tarballs; we are working on ways to
ensure that non-VCS source code is also archived.

Software Heritage
@uref{https://archive.softwareheritage.org/api/#rate-limiting, limits the
request rate per IP address}.  When the limit is reached, @command{guix
lint} prints a message and the @code{archival} checker stops doing anything
until that limit has been reset.

@item cve
@cindex security vulnerabilities
@cindex CVE, Common Vulnerabilities and Exposures
Report known vulnerabilities found in the Common Vulnerabilities and
Exposures (CVE) databases of the current and past year
@uref{https://nvd.nist.gov/vuln/data-feeds, published by the US NIST}.

To view information about a particular vulnerability, visit pages such as:

@itemize
@item
@indicateurl{https://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-YYYY-ABCD}
@item
@indicateurl{https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-YYYY-ABCD}
@end itemize

@noindent
where @code{CVE-YYYY-ABCD} is the CVE identifier---e.g.,
@code{CVE-2015-7554}.

Package developers can specify in package recipes the
@uref{https://nvd.nist.gov/products/cpe,Common Platform Enumeration (CPE)}
name and version of the package when they differ from the name or version
that Guix uses, as in this example:

@lisp
(package
  (name "grub")
  ;; @dots{}
  ;; CPE calls this package "grub2".
  (properties '((cpe-name . "grub2")
                (cpe-version . "2.3"))))
@end lisp

A CVE alert can be a false positive when its CPE name matches the one in
Guix, while actually referring to a distinct product.  These alerts can be
addressed by setting the correct CPE vendor, or when no vendors apply, by
ignoring alerts from irrelevant vendors, as in these examples:

@lisp
(package
  (name "halibut")
  ;; @dots{}
  (properties '((cpe-vendor . "halibut_project"))))

(package
  (name "cvs")
  ;; @dots{}
  (properties '((lint-hidden-cpe-vendors . ("jenkins"
                                            "vendor2")))))
@end lisp

@c See <https://www.openwall.com/lists/oss-security/2017/03/15/3>.
Finally, some entries in the CVE database do not specify which version of a
package they apply to, and would thus ``stick around'' forever.  Package
developers who found CVE alerts and verified they can be ignored can declare
them as in this example:

@lisp
(package
  (name "t1lib")
  ;; @dots{}
  ;; These CVEs no longer apply and can be safely ignored.
  (properties `((lint-hidden-cve . ("CVE-2011-0433"
                                    "CVE-2011-1553"
                                    "CVE-2011-1554"
                                    "CVE-2011-5244")))))
@end lisp

@item formatting
Warn about obvious source code formatting issues: trailing white space, use
of tabulations, etc.

@item input-labels
Report old-style input labels that do not match the name of the
corresponding package.  This aims to help migrate from the ``old input
style''.  @xref{Referência do package}, for more information on package inputs
and input styles.  @xref{Invocando guix style}, on how to migrate to the new
style.
@end table

A sintaxe geral é:

@example
guix lint @var{opções} @var{pacote}@dots{}
@end example

If no package is given on the command line, then all packages are checked.
The @var{options} may be zero or more of the following:

@table @code
@item --list-checkers
@itemx -l
List and describe all the available checkers that will be run on packages
and exit.

@item --checkers
@itemx -c
Only enable the checkers specified in a comma-separated list using the names
returned by @option{--list-checkers}.

@item --exclude
@itemx -x
Only disable the checkers specified in a comma-separated list using the
names returned by @option{--list-checkers}.

@item --expression=@var{expr}
@itemx -e @var{expr}
Considere o pacote que @var{expr} avalia.

This is useful to unambiguously designate packages, as in this example:

@example
guix lint -c archival -e '(@@ (gnu packages guile) guile-3.0)'
@end example

@item --no-network
@itemx -n
Only enable the checkers that do not depend on Internet access.

@item --load-path=@var{directory}
@itemx -L @var{diretório}
Add @var{directory} to the front of the package module search path
(@pxref{Módulos de pacote}).

This allows users to define their own packages and make them visible to the
command-line tools.

@end table

@node Invocando guix size
@section Invocando @command{guix size}

@cindex size
@cindex package size
@cindex closure
@cindex @command{guix size}
The @command{guix size} command helps package developers profile the disk
usage of packages.  It is easy to overlook the impact of an additional
dependency added to a package, or the impact of using a single output for a
package that could easily be split (@pxref{Pacotes com múltiplas saídas}).  Such are the typical issues that @command{guix size} can
highlight.

The command can be passed one or more package specifications such as
@code{gcc@@4.8} or @code{guile:debug}, or a file name in the store.
Consider this example:

@example
$ guix size coreutils
store item                               total    self
/gnu/store/@dots{}-gcc-5.5.0-lib           60.4    30.1  38.1%
/gnu/store/@dots{}-glibc-2.27              30.3    28.8  36.6%
/gnu/store/@dots{}-coreutils-8.28          78.9    15.0  19.0%
/gnu/store/@dots{}-gmp-6.1.2               63.1     2.7   3.4%
/gnu/store/@dots{}-bash-static-4.4.12       1.5     1.5   1.9%
/gnu/store/@dots{}-acl-2.2.52              61.1     0.4   0.5%
/gnu/store/@dots{}-attr-2.4.47             60.6     0.2   0.3%
/gnu/store/@dots{}-libcap-2.25             60.5     0.2   0.2%
total: 78.9 MiB
@end example

@cindex closure
The store items listed here constitute the @dfn{transitive closure} of
Coreutils---i.e., Coreutils and all its dependencies, recursively---as would
be returned by:

@example
$ guix gc -R /gnu/store/@dots{}-coreutils-8.23
@end example

Here the output shows three columns next to store items.  The first column,
labeled ``total'', shows the size in mebibytes (MiB) of the closure of the
store item---that is, its own size plus the size of all its dependencies.
The next column, labeled ``self'', shows the size of the item itself.  The
last column shows the ratio of the size of the item itself to the space
occupied by all the items listed here.

In this example, we see that the closure of Coreutils weighs in at
79@tie{}MiB, most of which is taken by libc and GCC's run-time support
libraries.  (That libc and GCC's libraries represent a large fraction of the
closure is not a problem @i{per se} because they are always available on the
system anyway.)

Since the command also accepts store file names, assessing the size of a
build result is straightforward:

@example
guix size $(guix system build config.scm)
@end example

When the package(s) passed to @command{guix size} are available in the
store@footnote{More precisely, @command{guix size} looks for the
@emph{ungrafted} variant of the given package(s), as returned by @code{guix
build @var{package} --no-grafts}.  @xref{Atualizações de segurança}, for information
on grafts.}, @command{guix size} queries the daemon to determine its
dependencies, and measures its size in the store, similar to @command{du -ms
--apparent-size} (@pxref{du invocation,,, coreutils, GNU Coreutils}).

When the given packages are @emph{not} in the store, @command{guix size}
reports information based on the available substitutes
(@pxref{Substitutos}).  This makes it possible to profile the disk usage of
store items that are not even on disk, only available remotely.

You can also specify several package names:

@example
$ guix size coreutils grep sed bash
store item                               total    self
/gnu/store/@dots{}-coreutils-8.24          77.8    13.8  13.4%
/gnu/store/@dots{}-grep-2.22               73.1     0.8   0.8%
/gnu/store/@dots{}-bash-4.3.42             72.3     4.7   4.6%
/gnu/store/@dots{}-readline-6.3            67.6     1.2   1.2%
@dots{}
total: 102.3 MiB
@end example

@noindent
In this example we see that the combination of the four packages takes
102.3@tie{}MiB in total, which is much less than the sum of each closure
since they have a lot of dependencies in common.

When looking at the profile returned by @command{guix size}, you may find
yourself wondering why a given package shows up in the profile at all.  To
understand it, you can use @command{guix graph --path -t references} to
display the shortest path between the two packages (@pxref{Invocando guix graph}).

The available options are:

@table @option

@item --substitute-urls=@var{urls}
Use substitute information from @var{urls}.  @xref{client-substitute-urls,
the same option for @code{guix build}}.

@item --sort=@var{key}
Sort lines according to @var{key}, one of the following options:

@table @code
@item self
the size of each item (the default);
@item closure
the total size of the item's closure.
@end table

@item --map-file=@var{arquivo}
Write a graphical map of disk usage in PNG format to @var{file}.

For the example above, the map looks like this:

@image{images/coreutils-size-map,5in,, map of Coreutils disk usage produced
by @command{guix size}}

This option requires that
@uref{https://wingolog.org/software/guile-charting/, Guile-Charting} be
installed and visible in Guile's module search path.  When that is not the
case, @command{guix size} fails as it tries to load it.

@item --system=@var{sistema}
@itemx -s @var{sistema}
Consider packages for @var{system}---e.g., @code{x86_64-linux}.

@item --load-path=@var{directory}
@itemx -L @var{diretório}
Add @var{directory} to the front of the package module search path
(@pxref{Módulos de pacote}).

This allows users to define their own packages and make them visible to the
command-line tools.
@end table

@node Invocando guix graph
@section Invocando @command{guix graph}

@cindex DAG
@cindex @command{guix graph}
@cindex dependências de pacotes
Packages and their dependencies form a @dfn{graph}, specifically a directed
acyclic graph (DAG).  It can quickly become difficult to have a mental model
of the package DAG, so the @command{guix graph} command provides a visual
representation of the DAG@.  By default, @command{guix graph} emits a DAG
representation in the input format of @uref{https://www.graphviz.org/,
Graphviz}, so its output can be passed directly to the @command{dot} command
of Graphviz.  It can also emit an HTML page with embedded JavaScript code to
display a ``chord diagram'' in a Web browser, using the
@uref{https://d3js.org/, d3.js} library, or emit Cypher queries to construct
a graph in a graph database supporting the
@uref{https://www.opencypher.org/, openCypher} query language.  With
@option{--path}, it simply displays the shortest path between two packages.
The general syntax is:

@example
guix graph @var{opções} @var{pacote}@dots{}
@end example

For example, the following command generates a PDF file representing the
package DAG for the GNU@tie{}Core Utilities, showing its build-time
dependencies:

@example
guix graph coreutils | dot -Tpdf > dag.pdf
@end example

The output looks like this:

@image{images/coreutils-graph,2in,,Dependency graph of the GNU Coreutils}

Nice little graph, no?

You may find it more pleasant to navigate the graph interactively with
@command{xdot} (from the @code{xdot} package):

@example
guix graph coreutils | xdot -
@end example

But there is more than one graph! The one above is concise: it is the graph
of package objects, omitting implicit inputs such as GCC, libc, grep, etc.
It is often useful to have such a concise graph, but sometimes one may want
to see more details.  @command{guix graph} supports several types of graphs,
allowing you to choose the level of detail:

@table @code
@item package
This is the default type used in the example above.  It shows the DAG of
package objects, excluding implicit dependencies.  It is concise, but
filters out many details.

@item reverse-package
This shows the @emph{reverse} DAG of packages.  For example:

@example
guix graph --type=reverse-package ocaml
@end example

...@: yields the graph of packages that @emph{explicitly} depend on OCaml
(if you are also interested in cases where OCaml is an implicit dependency,
see @code{reverse-bag} below).

Note that for core packages this can yield huge graphs.  If all you want is
to know the number of packages that depend on a given package, use
@command{guix refresh --list-dependent} (@pxref{Invocando guix refresh,
@option{--list-dependent}}).

@item bag-emerged
This is the package DAG, @emph{including} implicit inputs.

For instance, the following command:

@example
guix graph --type=bag-emerged coreutils
@end example

...@: yields this bigger graph:

@image{images/coreutils-bag-graph,,5in,Detailed dependency graph of the GNU
Coreutils}

At the bottom of the graph, we see all the implicit inputs of
@var{gnu-build-system} (@pxref{Sistemas de compilação, @code{gnu-build-system}}).

Now, note that the dependencies of these implicit inputs---that is, the
@dfn{bootstrap dependencies} (@pxref{Inicializando})---are not shown here,
for conciseness.

@item bag
Similar to @code{bag-emerged}, but this time including all the bootstrap
dependencies.

@item bag-with-origins
Similar to @code{bag}, but also showing origins and their dependencies.

@item reverse-bag
This shows the @emph{reverse} DAG of packages.  Unlike
@code{reverse-package}, it also takes implicit dependencies into account.
For example:

@example
guix graph -t reverse-bag dune
@end example

@noindent
...@: yields the graph of all packages that depend on Dune, directly or
indirectly.  Since Dune is an @emph{implicit} dependency of many packages
@i{via} @code{dune-build-system}, this shows a large number of packages,
whereas @code{reverse-package} would show very few if any.

@item derivation
This is the most detailed representation: It shows the DAG of derivations
(@pxref{Derivações}) and plain store items.  Compared to the above
representation, many additional nodes are visible, including build scripts,
patches, Guile modules, etc.

For this type of graph, it is also possible to pass a @file{.drv} file name
instead of a package name, as in:

@example
guix graph -t derivation $(guix system build -d my-config.scm)
@end example

@item module
This is the graph of @dfn{package modules} (@pxref{Módulos de pacote}).  For
example, the following command shows the graph for the package module that
defines the @code{guile} package:

@example
guix graph -t module guile | xdot -
@end example
@end table

All the types above correspond to @emph{build-time dependencies}.  The
following graph type represents the @emph{run-time dependencies}:

@table @code
@item references
This is the graph of @dfn{references} of a package output, as returned by
@command{guix gc --references} (@pxref{Invocando guix gc}).

If the given package output is not available in the store, @command{guix
graph} attempts to obtain dependency information from substitutes.

Here you can also pass a store file name instead of a package name.  For
example, the command below produces the reference graph of your profile
(which can be big!):

@example
guix graph -t references $(readlink -f ~/.guix-profile)
@end example

@item referrers
This is the graph of the @dfn{referrers} of a store item, as returned by
@command{guix gc --referrers} (@pxref{Invocando guix gc}).

This relies exclusively on local information from your store.  For instance,
let us suppose that the current Inkscape is available in 10 profiles on your
machine; @command{guix graph -t referrers inkscape} will show a graph rooted
at Inkscape and with those 10 profiles linked to it.

It can help determine what is preventing a store item from being garbage
collected.

@end table

@cindex shortest path, between packages
Often, the graph of the package you are interested in does not fit on your
screen, and anyway all you want to know is @emph{why} that package actually
depends on some seemingly unrelated package.  The @option{--path} option
instructs @command{guix graph} to display the shortest path between two
packages (or derivations, or store items, etc.):

@example
$ guix graph --path emacs libunistring
emacs@@26.3
mailutils@@3.9
libunistring@@0.9.10
$ guix graph --path -t derivation emacs libunistring
/gnu/store/@dots{}-emacs-26.3.drv
/gnu/store/@dots{}-mailutils-3.9.drv
/gnu/store/@dots{}-libunistring-0.9.10.drv
$ guix graph --path -t references emacs libunistring
/gnu/store/@dots{}-emacs-26.3
/gnu/store/@dots{}-libidn2-2.2.0
/gnu/store/@dots{}-libunistring-0.9.10
@end example

Sometimes you still want to visualize the graph but would like to trim it so
it can actually be displayed.  One way to do it is via the
@option{--max-depth} (or @option{-M}) option, which lets you specify the
maximum depth of the graph.  In the example below, we visualize only
@code{libreoffice} and the nodes whose distance to @code{libreoffice} is at
most 2:

@example
guix graph -M 2 libreoffice | xdot -f fdp -
@end example

Mind you, that's still a big ball of spaghetti, but at least @command{dot}
can render it quickly and it can be browsed somewhat.

The available options are the following:

@table @option
@item --type=@var{type}
@itemx -t @var{tipo}
Produce a graph output of @var{type}, where @var{type} must be one of the
values listed above.

@item --list-types
Lista os tipos de grafos disponíveis.

@item --backend=@var{backend}
@itemx -b @var{backend}
Produce a graph using the selected @var{backend}.

@item --list-backends
Lista os backends de grafos disponíveis.

Currently, the available backends are Graphviz and d3.js.

@item --path
Display the shortest path between two nodes of the type specified by
@option{--type}.  The example below shows the shortest path between
@code{libreoffice} and @code{llvm} according to the references of
@code{libreoffice}:

@example
$ guix graph --path -t references libreoffice llvm
/gnu/store/@dots{}-libreoffice-6.4.2.2
/gnu/store/@dots{}-libepoxy-1.5.4
/gnu/store/@dots{}-mesa-19.3.4
/gnu/store/@dots{}-llvm-9.0.1
@end example

@item --expression=@var{expr}
@itemx -e @var{expr}
Considere o pacote que @var{expr} avalia.

This is useful to precisely refer to a package, as in this example:

@example
guix graph -e '(@@@@ (gnu packages commencement) gnu-make-final)'
@end example

@item --system=@var{sistema}
@itemx -s @var{sistema}
Display the graph for @var{system}---e.g., @code{i686-linux}.

The package dependency graph is largely architecture-independent, but there
are some architecture-dependent bits that this option allows you to
visualize.

@item --load-path=@var{directory}
@itemx -L @var{diretório}
Add @var{directory} to the front of the package module search path
(@pxref{Módulos de pacote}).

This allows users to define their own packages and make them visible to the
command-line tools.
@end table

On top of that, @command{guix graph} supports all the usual package
transformation options (@pxref{Opções de transformação de pacote}).  This makes
it easy to view the effect of a graph-rewriting transformation such as
@option{--with-input}.  For example, the command below outputs the graph of
@code{git} once @code{openssl} has been replaced by @code{libressl}
everywhere in the graph:

@example
guix graph git --with-input=openssl=libressl
@end example

So many possibilities, so much fun!

@node Invocando guix publish
@section Invocando @command{guix publish}

@cindex @command{guix publish}
The purpose of @command{guix publish} is to enable users to easily share
their store with others, who can then use it as a substitute server
(@pxref{Substitutos}).

When @command{guix publish} runs, it spawns an HTTP server which allows
anyone with network access to obtain substitutes from it.  This means that
any machine running Guix can also act as if it were a build farm, since the
HTTP interface is compatible with Cuirass, the software behind the
@code{@value{SUBSTITUTE-SERVER-1}} build farm.

For security, each substitute is signed, allowing recipients to check their
authenticity and integrity (@pxref{Substitutos}).  Because @command{guix
publish} uses the signing key of the system, which is only readable by the
system administrator, it must be started as root; the @option{--user} option
makes it drop root privileges early on.

The signing key pair must be generated before @command{guix publish} is
launched, using @command{guix archive --generate-key} (@pxref{Invocando guix archive}).

When the @option{--advertise} option is passed, the server advertises its
availability on the local network using multicast DNS (mDNS) and DNS service
discovery (DNS-SD), currently @i{via} Guile-Avahi (@pxref{Top,,,
guile-avahi, Using Avahi in Guile Scheme Programs}).

A sintaxe geral é:

@example
guix publish @var{options}@dots{}
@end example

Running @command{guix publish} without any additional arguments will spawn
an HTTP server on port 8080:

@example
guix publish
@end example

@cindex socket activation, for @command{guix publish}
@command{guix publish} can also be started following the systemd ``socket
activation'' protocol (@pxref{Service De- and Constructors,
@code{make-systemd-constructor},, shepherd, The GNU Shepherd Manual}).

Once a publishing server has been authorized, the daemon may download
substitutes from it.  @xref{Obtendo substitutos de outros servidores}.

By default, @command{guix publish} compresses archives on the fly as it
serves them.  This ``on-the-fly'' mode is convenient in that it requires no
setup and is immediately available.  However, when serving lots of clients,
we recommend using the @option{--cache} option, which enables caching of the
archives before they are sent to clients---see below for details.  The
@command{guix weather} command provides a handy way to check what a server
provides (@pxref{Invocando guix weather}).

As a bonus, @command{guix publish} also serves as a content-addressed mirror
for source files referenced in @code{origin} records (@pxref{Referência do origin}).  For instance, assuming @command{guix publish} is running on
@code{example.org}, the following URL returns the raw
@file{hello-2.10.tar.gz} file with the given SHA256 hash (represented in
@code{nix-base32} format, @pxref{Invocando guix hash}):

@example
http://example.org/file/hello-2.10.tar.gz/sha256/0ssi1@dots{}ndq1i
@end example

Obviously, these URLs only work for files that are in the store; in other
cases, they return 404 (``Not Found'').

@cindex build logs, publication
Build logs are available from @code{/log} URLs like:

@example
http://example.org/log/gwspk@dots{}-guile-2.2.3
@end example

@noindent
When @command{guix-daemon} is configured to save compressed build logs, as
is the case by default (@pxref{Invocando guix-daemon}), @code{/log} URLs
return the compressed log as-is, with an appropriate @code{Content-Type}
and/or @code{Content-Encoding} header.  We recommend running
@command{guix-daemon} with @option{--log-compression=gzip} since Web
browsers can automatically decompress it, which is not the case with Bzip2
compression.

The following options are available:

@table @code
@item --port=@var{porta}
@itemx -p @var{porta}
Ouve requisições HTTP na @var{porta}.

@item --listen=@var{host}
Listen on the network interface for @var{host}.  The default is to accept
connections from any interface.

@item --user=@var{usuário}
@itemx -u @var{usuário}
Change privileges to @var{user} as soon as possible---i.e., once the server
socket is open and the signing key has been read.

@item --compression[=@var{method}[:@var{level}]]
@itemx -C [@var{method}[:@var{level}]]
Compress data using the given @var{method} and @var{level}.  @var{method} is
one of @code{lzip}, @code{zstd}, and @code{gzip}; when @var{method} is
omitted, @code{gzip} is used.

When @var{level} is zero, disable compression.  The range 1 to 9 corresponds
to different compression levels: 1 is the fastest, and 9 is the best
(CPU-intensive).  The default is 3.

Usually, @code{lzip} compresses noticeably better than @code{gzip} for a
small increase in CPU usage; see
@uref{https://nongnu.org/lzip/lzip_benchmark.html,benchmarks on the lzip Web
page}.  However, @code{lzip} achieves low decompression throughput (on the
order of 50@tie{}MiB/s on modern hardware), which can be a bottleneck for
someone who downloads over a fast network connection.

The compression ratio of @code{zstd} is between that of @code{lzip} and that
of @code{gzip}; its main advantage is a
@uref{https://facebook.github.io/zstd/,high decompression speed}.

Unless @option{--cache} is used, compression occurs on the fly and the
compressed streams are not cached.  Thus, to reduce load on the machine that
runs @command{guix publish}, it may be a good idea to choose a low
compression level, to run @command{guix publish} behind a caching proxy, or
to use @option{--cache}.  Using @option{--cache} has the advantage that it
allows @command{guix publish} to add @code{Content-Length} HTTP header to
its responses.

This option can be repeated, in which case every substitute gets compressed
using all the selected methods, and all of them are advertised.  This is
useful when users may not support all the compression methods: they can
select the one they support.

@item --cache=@var{directory}
@itemx -c @var{directory}
Cache archives and meta-data (@code{.narinfo} URLs) to @var{directory} and
only serve archives that are in cache.

When this option is omitted, archives and meta-data are created on-the-fly.
This can reduce the available bandwidth, especially when compression is
enabled, since this may become CPU-bound.  Another drawback of the default
mode is that the length of archives is not known in advance, so
@command{guix publish} does not add a @code{Content-Length} HTTP header to
its responses, which in turn prevents clients from knowing the amount of
data being downloaded.

Conversely, when @option{--cache} is used, the first request for a store
item (@i{via} a @code{.narinfo} URL) triggers a background process to
@dfn{bake} the archive---computing its @code{.narinfo} and compressing the
archive, if needed.  Once the archive is cached in @var{directory},
subsequent requests succeed and are served directly from the cache, which
guarantees that clients get the best possible bandwidth.

That first @code{.narinfo} request nonetheless returns 200, provided the
requested store item is ``small enough'', below the cache bypass
threshold---see @option{--cache-bypass-threshold} below.  That way, clients
do not have to wait until the archive is baked.  For larger store items, the
first @code{.narinfo} request returns 404, meaning that clients have to wait
until the archive is baked.

The ``baking'' process is performed by worker threads.  By default, one
thread per CPU core is created, but this can be customized.  See
@option{--workers} below.

When @option{--ttl} is used, cached entries are automatically deleted when
they have expired.

@item --workers=@var{N}
When @option{--cache} is used, request the allocation of @var{N} worker
threads to ``bake'' archives.

@item --ttl=@var{ttl}
Produce @code{Cache-Control} HTTP headers that advertise a time-to-live
(TTL) of @var{ttl}.  @var{ttl} must denote a duration: @code{5d} means 5
days, @code{1m} means 1 month, and so on.

This allows the user's Guix to keep substitute information in cache for
@var{ttl}.  However, note that @code{guix publish} does not itself guarantee
that the store items it provides will indeed remain available for as long as
@var{ttl}.

Additionally, when @option{--cache} is used, cached entries that have not
been accessed for @var{ttl} and that no longer have a corresponding item in
the store, may be deleted.

@item --negative-ttl=@var{ttl}
Similarly produce @code{Cache-Control} HTTP headers to advertise the
time-to-live (TTL) of @emph{negative} lookups---missing store items, for
which the HTTP 404 code is returned.  By default, no negative TTL is
advertised.

This parameter can help adjust server load and substitute latency by
instructing cooperating clients to be more or less patient when a store item
is missing.

@item --cache-bypass-threshold=@var{size}
When used in conjunction with @option{--cache}, store items smaller than
@var{size} are immediately available, even when they are not yet in cache.
@var{size} is a size in bytes, or it can be suffixed by @code{M} for
megabytes and so on.  The default is @code{10M}.

``Cache bypass'' allows you to reduce the publication delay for clients at
the expense of possibly additional I/O and CPU use on the server side:
depending on the client access patterns, those store items can end up being
baked several times until a copy is available in cache.

Increasing the threshold may be useful for sites that have few users, or to
guarantee that users get substitutes even for store items that are not
popular.

@item --nar-path=@var{path}
Use @var{path} as the prefix for the URLs of ``nar'' files (@pxref{Invocando guix archive, normalized archives}).

By default, nars are served at a URL such as
@code{/nar/gzip/@dots{}-coreutils-8.25}.  This option allows you to change
the @code{/nar} part to @var{path}.

@item --public-key=@var{file}
@itemx --private-key=@var{file}
Use the specific @var{file}s as the public/private key pair used to sign the
store items being published.

The files must correspond to the same key pair (the private key is used for
signing and the public key is merely advertised in the signature metadata).
They must contain keys in the canonical s-expression format as produced by
@command{guix archive --generate-key} (@pxref{Invocando guix archive}).  By
default, @file{/etc/guix/signing-key.pub} and
@file{/etc/guix/signing-key.sec} are used.

@item --repl[=@var{port}]
@itemx -r [@var{porta}]
Spawn a Guile REPL server (@pxref{REPL Servers,,, guile, GNU Guile Reference
Manual}) on @var{port} (37146 by default).  This is used primarily for
debugging a running @command{guix publish} server.
@end table

Enabling @command{guix publish} on Guix System is a one-liner: just
instantiate a @code{guix-publish-service-type} service in the
@code{services} field of the @code{operating-system} declaration
(@pxref{guix-publish-service-type, @code{guix-publish-service-type}}).

If you are instead running Guix on a ``foreign distro'', follow these
instructions:

@itemize
@item
If your host distro uses the systemd init system:

@example
# ln -s ~root/.guix-profile/lib/systemd/system/guix-publish.service \
        /etc/systemd/system/
# systemctl start guix-publish && systemctl enable guix-publish
@end example

@item
Se sua distro hospedeira usa o sistema init Upstart:

@example
# ln -s ~root/.guix-profile/lib/upstart/system/guix-publish.conf /etc/init/
# start guix-publish
@end example

@item
Otherwise, proceed similarly with your distro's init system.
@end itemize

@node Invocando guix challenge
@section Invocando @command{guix challenge}

@cindex compilações reproduzíveis
@cindex verifiable builds
@cindex @command{guix challenge}
@cindex challenge
Do the binaries provided by this server really correspond to the source code
it claims to build? Is a package build process deterministic? These are the
questions the @command{guix challenge} command attempts to answer.

The former is obviously an important question: Before using a substitute
server (@pxref{Substitutos}), one had better @emph{verify} that it provides
the right binaries, and thus @emph{challenge} it.  The latter is what
enables the former: If package builds are deterministic, then independent
builds of the package should yield the exact same result, bit for bit; if a
server provides a binary different from the one obtained locally, it may be
either corrupt or malicious.

We know that the hash that shows up in @file{/gnu/store} file names is the
hash of all the inputs of the process that built the file or
directory---compilers, libraries, build scripts,
etc. (@pxref{Introdução}).  Assuming deterministic build processes, one
store file name should map to exactly one build output.  @command{guix
challenge} checks whether there is, indeed, a single mapping by comparing
the build outputs of several independent builds of any given store item.

The command output looks like this:

@smallexample
$ guix challenge \
  --substitute-urls="https://@value{SUBSTITUTE-SERVER-1} https://guix.example.org" \
  openssl git pius coreutils grep
updating substitutes from 'https://@value{SUBSTITUTE-SERVER-1}'... 100.0%
updating substitutes from 'https://guix.example.org'... 100.0%
/gnu/store/@dots{}-openssl-1.0.2d contents differ:
  local hash: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q
  https://@value{SUBSTITUTE-SERVER-1}/nar/@dots{}-openssl-1.0.2d: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q
  https://guix.example.org/nar/@dots{}-openssl-1.0.2d: 1zy4fmaaqcnjrzzajkdn3f5gmjk754b43qkq47llbyak9z0qjyim
  differing files:
    /lib/libcrypto.so.1.1
    /lib/libssl.so.1.1

/gnu/store/@dots{}-git-2.5.0 contents differ:
  local hash: 00p3bmryhjxrhpn2gxs2fy0a15lnip05l97205pgbk5ra395hyha
  https://@value{SUBSTITUTE-SERVER-1}/nar/@dots{}-git-2.5.0: 069nb85bv4d4a6slrwjdy8v1cn4cwspm3kdbmyb81d6zckj3nq9f
  https://guix.example.org/nar/@dots{}-git-2.5.0: 0mdqa9w1p6cmli6976v4wi0sw9r4p5prkj7lzfd1877wk11c9c73
  differing file:
    /libexec/git-core/git-fsck

/gnu/store/@dots{}-pius-2.1.1 contents differ:
  local hash: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax
  https://@value{SUBSTITUTE-SERVER-1}/nar/@dots{}-pius-2.1.1: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax
  https://guix.example.org/nar/@dots{}-pius-2.1.1: 1cy25x1a4fzq5rk0pmvc8xhwyffnqz95h2bpvqsz2mpvlbccy0gs
  differing file:
    /share/man/man1/pius.1.gz

@dots{}

5 store items were analyzed:
  - 2 (40.0%) were identical
  - 3 (60.0%) differed
  - 0 (0.0%) were inconclusive
@end smallexample

@noindent
In this example, @command{guix challenge} queries all the substitute servers
for each of the fives packages specified on the command line.  It then
reports those store items for which the servers obtained a result different
from the local build (if it exists) and/or different from one another; here,
the @samp{local hash} lines indicate that a local build result was available
for each of these packages and shows its hash.

@cindex non-determinism, in package builds
As an example, @code{guix.example.org} always gets a different answer.
Conversely, @code{@value{SUBSTITUTE-SERVER-1}} agrees with local builds,
except in the case of Git.  This might indicate that the build process of
Git is non-deterministic, meaning that its output varies as a function of
various things that Guix does not fully control, in spite of building
packages in isolated environments (@pxref{Recursos}).  Most common sources
of non-determinism include the addition of timestamps in build results, the
inclusion of random numbers, and directory listings sorted by inode number.
See @uref{https://reproducible-builds.org/docs/}, for more information.

To find out what is wrong with this Git binary, the easiest approach is to
run:

@example
guix challenge git \
  --diff=diffoscope \
  --substitute-urls="https://@value{SUBSTITUTE-SERVER-1} https://guix.example.org"
@end example

This automatically invokes @command{diffoscope}, which displays detailed
information about files that differ.

Alternatively, we can do something along these lines (@pxref{Invocando guix archive}):

@example
$ wget -q -O - https://@value{SUBSTITUTE-SERVER-1}/nar/lzip/@dots{}-git-2.5.0 \
   | lzip -d | guix archive -x /tmp/git
$ diff -ur --no-dereference /gnu/store/@dots{}-git.2.5.0 /tmp/git
@end example

This command shows the difference between the files resulting from the local
build, and the files resulting from the build on
@code{@value{SUBSTITUTE-SERVER-1}} (@pxref{Overview, Comparing and Merging
Files,, diffutils, Comparing and Merging Files}).  The @command{diff}
command works great for text files.  When binary files differ, a better
option is @uref{https://diffoscope.org/, Diffoscope}, a tool that helps
visualize differences for all kinds of files.

Once you have done that work, you can tell whether the differences are due
to a non-deterministic build process or to a malicious server.  We try hard
to remove sources of non-determinism in packages to make it easier to verify
substitutes, but of course, this is a process that involves not just Guix,
but a large part of the free software community.  In the meantime,
@command{guix challenge} is one tool to help address the problem.

If you are writing packages for Guix, you are encouraged to check whether
@code{@value{SUBSTITUTE-SERVER-1}} and other substitute servers obtain the
same build result as you did with:

@example
guix challenge @var{package}
@end example

A sintaxe geral é:

@example
guix challenge @var{options} @var{argument}@dots{}
@end example

@noindent
where @var{argument} is a package specification such as @code{guile@@2.0} or
@code{glibc:debug} or, alternatively, a store file name as returned, for
example, by @command{guix build} or @command{guix gc --list-live}.

When a difference is found between the hash of a locally-built item and that
of a server-provided substitute, or among substitutes provided by different
servers, the command displays it as in the example above and its exit code
is 2 (other non-zero exit codes denote other kinds of errors).

The one option that matters is:

@table @code

@item --substitute-urls=@var{urls}
Consider @var{urls} the whitespace-separated list of substitute source URLs
to compare to.

@item --diff=@var{mode}
Upon mismatches, show differences according to @var{mode}, one of:

@table @asis
@item @code{simple} (the default)
Show the list of files that differ.

@item @code{diffoscope}
@itemx @var{comando}
Invoke @uref{https://diffoscope.org/, Diffoscope}, passing it two
directories whose contents do not match.

When @var{command} is an absolute file name, run @var{command} instead of
Diffoscope.

@item @code{none}
Do not show further details about the differences.
@end table

Thus, unless @option{--diff=none} is passed, @command{guix challenge}
downloads the store items from the given substitute servers so that it can
compare them.

@item --verbose
@itemx -v
Show details about matches (identical contents) in addition to information
about mismatches.

@end table

@node Invocando guix copy
@section Invocando @command{guix copy}

@cindex @command{guix copy}
@cindex copy, of store items, over SSH
@cindex SSH, copy of store items
@cindex sharing store items across machines
@cindex transferring store items across machines
The @command{guix copy} command copies items from the store of one machine
to that of another machine over a secure shell (SSH)
connection@footnote{This command is available only when Guile-SSH was
found.  @xref{Requisitos}, for details.}.  For example, the following
command copies the @code{coreutils} package, the user's profile, and all
their dependencies over to @var{host}, logged in as @var{user}:

@example
guix copy --to=@var{user}@@@var{host} \
          coreutils $(readlink -f ~/.guix-profile)
@end example

If some of the items to be copied are already present on @var{host}, they
are not actually sent.

The command below retrieves @code{libreoffice} and @code{gimp} from
@var{host}, assuming they are available there:

@example
guix copy --from=@var{host} libreoffice gimp
@end example

The SSH connection is established using the Guile-SSH client, which is
compatible with OpenSSH: it honors @file{~/.ssh/known_hosts} and
@file{~/.ssh/config}, and uses the SSH agent for authentication.

The key used to sign items that are sent must be accepted by the remote
machine.  Likewise, the key used by the remote machine to sign items you are
retrieving must be in @file{/etc/guix/acl} so it is accepted by your own
daemon.  @xref{Invocando guix archive}, for more information about store item
authentication.

A sintaxe geral é:

@example
guix copy [--to=@var{spec}|--from=@var{spec}] @var{items}@dots{}
@end example

You must always specify one of the following options:

@table @code
@item --to=@var{spec}
@itemx --from=@var{spec}
Specify the host to send to or receive from.  @var{spec} must be an SSH spec
such as @code{example.org}, @code{charlie@@example.org}, or
@code{charlie@@example.org:2222}.
@end table

The @var{items} can be either package names, such as @code{gimp}, or store
items, such as @file{/gnu/store/@dots{}-idutils-4.6}.

When specifying the name of a package to send, it is first built if needed,
unless @option{--dry-run} was specified.  Common build options are supported
(@pxref{Opções de compilação comuns}).


@node Invocando guix container
@section Invocando @command{guix container}
@cindex container
@cindex @command{guix container}
@quotation Nota
As of version @value{VERSION}, this tool is experimental.  The interface is
subject to radical change in the future.
@end quotation

The purpose of @command{guix container} is to manipulate processes running
within an isolated environment, commonly known as a ``container'', typically
created by the @command{guix shell} (@pxref{Invocando guix shell}) and
@command{guix system container} (@pxref{Invocando guix system}) commands.

A sintaxe geral é:

@example
guix container @var{action} @var{options}@dots{}
@end example

@var{action} specifies the operation to perform with a container, and
@var{options} specifies the context-specific arguments for the action.

The following actions are available:

@table @code
@item exec
Execute a command within the context of a running container.

The syntax is:

@example
guix container exec @var{pid} @var{program} @var{arguments}@dots{}
@end example

@var{pid} specifies the process ID of the running container.  @var{program}
specifies an executable file name within the root file system of the
container.  @var{arguments} are the additional options that will be passed
to @var{program}.

The following command launches an interactive login shell inside a Guix
system container, started by @command{guix system container}, and whose
process ID is 9001:

@example
guix container exec 9001 /run/current-system/profile/bin/bash --login
@end example

Note that the @var{pid} cannot be the parent process of a container.  It
must be PID 1 of the container or one of its child processes.

@end table

@node Invocando guix weather
@section Invocando @command{guix weather}

@cindex @command{guix weather}
Occasionally you're grumpy because substitutes are lacking and you end up
building packages by yourself (@pxref{Substitutos}).  The @command{guix
weather} command reports on substitute availability on the specified servers
so you can have an idea of whether you'll be grumpy today.  It can sometimes
be useful info as a user, but it is primarily useful to people running
@command{guix publish} (@pxref{Invocando guix publish}).  Sometimes
substitutes @emph{are} available but they are not authorized on your system;
@command{guix weather} reports it so you can authorize them if you want
(@pxref{Obtendo substitutos de outros servidores}).

@cindex statistics, for substitutes
@cindex availability of substitutes
@cindex substitute availability
@cindex weather, substitute availability
Here's a sample run:

@example
$ guix weather --substitute-urls=https://guix.example.org
computing 5,872 package derivations for x86_64-linux...
looking for 6,128 store items on https://guix.example.org..
updating substitutes from 'https://guix.example.org'... 100.0%
https://guix.example.org
  43.4% substitutes available (2,658 out of 6,128)
  7,032.5 MiB of nars (compressed)
  19,824.2 MiB on disk (uncompressed)
  0.030 seconds per request (182.9 seconds in total)
  33.5 requests per second

  9.8% (342 out of 3,470) of the missing items are queued
  867 queued builds
      x86_64-linux: 518 (59.7%)
      i686-linux: 221 (25.5%)
      aarch64-linux: 128 (14.8%)
  build rate: 23.41 builds per hour
      x86_64-linux: 11.16 builds per hour
      i686-linux: 6.03 builds per hour
      aarch64-linux: 6.41 builds per hour
@end example

@cindex continuous integration, statistics
As you can see, it reports the fraction of all the packages for which
substitutes are available on the server---regardless of whether substitutes
are enabled, and regardless of whether this server's signing key is
authorized.  It also reports the size of the compressed archives (``nars'')
provided by the server, the size the corresponding store items occupy in the
store (assuming deduplication is turned off), and the server's throughput.
The second part gives continuous integration (CI) statistics, if the server
supports it.  In addition, using the @option{--coverage} option,
@command{guix weather} can list ``important'' package substitutes missing on
the server (see below).

To achieve that, @command{guix weather} queries over HTTP(S) meta-data
(@dfn{narinfos}) for all the relevant store items.  Like @command{guix
challenge}, it ignores signatures on those substitutes, which is innocuous
since the command only gathers statistics and cannot install those
substitutes.

A sintaxe geral é:

@example
guix weather @var{options}@dots{} [@var{packages}@dots{}]
@end example

When @var{packages} is omitted, @command{guix weather} checks the
availability of substitutes for @emph{all} the packages, or for those
specified with @option{--manifest}; otherwise it only considers the
specified packages.  It is also possible to query specific system types with
@option{--system}.  @command{guix weather} exits with a non-zero code when
the fraction of available substitutes is below 100%.

The available options are listed below.

@table @code
@item --substitute-urls=@var{urls}
@var{urls} is the space-separated list of substitute server URLs to query.
When this option is omitted, the URLs specified with the
@option{--substitute-urls} option of @command{guix-daemon} are used or, as a
last resort, the default set of substitute URLs.

@item --system=@var{sistema}
@itemx -s @var{sistema}
Query substitutes for @var{system}---e.g., @code{aarch64-linux}.  This
option can be repeated, in which case @command{guix weather} will query
substitutes for several system types.

@item --manifest=@var{arquivo}
Instead of querying substitutes for all the packages, only ask for those
specified in @var{file}.  @var{file} must contain a @dfn{manifest}, as with
the @code{-m} option of @command{guix package} (@pxref{Invocando guix package}).

This option can be repeated several times, in which case the manifests are
concatenated.

@item --expression=@var{expr}
@itemx -e @var{expr}
Considere o pacote que @var{expr} avalia.

A typical use case for this option is specifying a package that is hidden
and thus cannot be referred to in the usual way, as in this example:

@example
guix weather -e '(@@@@ (gnu packages rust) rust-bootstrap)'
@end example

This option can be repeated.

@item --coverage[=@var{contagem}]
@itemx -c [@var{contagem}]
Report on substitute coverage for packages: list packages with at least
@var{count} dependents (zero by default) for which substitutes are
unavailable.  Dependent packages themselves are not listed: if @var{b}
depends on @var{a} and @var{a} has no substitutes, only @var{a} is listed,
even though @var{b} usually lacks substitutes as well.  The result looks
like this:

@example
$ guix weather --substitute-urls=@value{SUBSTITUTE-URLS} -c 10
computing 8,983 package derivations for x86_64-linux...
looking for 9,343 store items on @value{SUBSTITUTE-URLS}...
updating substitutes from '@value{SUBSTITUTE-URLS}'... 100.0%
@value{SUBSTITUTE-URLS}
  64.7% substitutes available (6,047 out of 9,343)
@dots{}
2502 packages are missing from '@value{SUBSTITUTE-URLS}' for 'x86_64-linux', among which:
    58  kcoreaddons@@5.49.0      /gnu/store/@dots{}-kcoreaddons-5.49.0
    46  qgpgme@@1.11.1           /gnu/store/@dots{}-qgpgme-1.11.1
    37  perl-http-cookiejar@@0.008  /gnu/store/@dots{}-perl-http-cookiejar-0.008
    @dots{}
@end example

What this example shows is that @code{kcoreaddons} and presumably the 58
packages that depend on it have no substitutes at
@code{@value{SUBSTITUTE-SERVER-1}}; likewise for @code{qgpgme} and the 46
packages that depend on it.

If you are a Guix developer, or if you are taking care of this build farm,
you'll probably want to have a closer look at these packages: they may
simply fail to build.

@item --display-missing
Display the list of store items for which substitutes are missing.
@end table

@node Invocando guix processes
@section Invocando @command{guix processes}

@cindex @command{guix processes}
The @command{guix processes} command can be useful to developers and system
administrators, especially on multi-user machines and on build farms: it
lists the current sessions (connections to the daemon), as well as
information about the processes involved@footnote{Remote sessions, when
@command{guix-daemon} is started with @option{--listen} specifying a TCP
endpoint, are @emph{not} listed.}.  Here's an example of the information it
returns:

@example
$ sudo guix processes
SessionPID: 19002
ClientPID: 19090
ClientCommand: guix shell python

SessionPID: 19402
ClientPID: 19367
ClientCommand: guix publish -u guix-publish -p 3000 -C 9 @dots{}

SessionPID: 19444
ClientPID: 19419
ClientCommand: cuirass --cache-directory /var/cache/cuirass @dots{}
LockHeld: /gnu/store/@dots{}-perl-ipc-cmd-0.96.lock
LockHeld: /gnu/store/@dots{}-python-six-bootstrap-1.11.0.lock
LockHeld: /gnu/store/@dots{}-libjpeg-turbo-2.0.0.lock
ChildPID: 20495
ChildCommand: guix offload x86_64-linux 7200 1 28800
ChildPID: 27733
ChildCommand: guix offload x86_64-linux 7200 1 28800
ChildPID: 27793
ChildCommand: guix offload x86_64-linux 7200 1 28800
@end example

In this example we see that @command{guix-daemon} has three clients:
@command{guix shell}, @command{guix publish}, and the Cuirass continuous
integration tool; their process identifier (PID) is given by the
@code{ClientPID} field.  The @code{SessionPID} field gives the PID of the
@command{guix-daemon} sub-process of this particular session.

The @code{LockHeld} fields show which store items are currently locked by
this session, which corresponds to store items being built or substituted
(the @code{LockHeld} field is not displayed when @command{guix processes} is
not running as root).  Last, by looking at the @code{ChildPID} and
@code{ChildCommand} fields, we understand that these three builds are being
offloaded (@pxref{Configuração de descarregamento de daemon}).

The output is in Recutils format so we can use the handy @command{recsel}
command to select sessions of interest (@pxref{Selection Expressions,,,
recutils, GNU recutils manual}).  As an example, the command shows the
command line and PID of the client that triggered the build of a Perl
package:

@example
$ sudo guix processes | \
    recsel -p ClientPID,ClientCommand -e 'LockHeld ~ "perl"'
ClientPID: 19419
ClientCommand: cuirass --cache-directory /var/cache/cuirass @dots{}
@end example

Additional options are listed below.

@table @code
@item --format=@var{formato}
@itemx -f @var{formato}
Produza saída no @var{formato} especificado, um dos seguintes:

@table @code
@item recutils
The default option.  It outputs a set of Session recutils records that
include each @code{ChildProcess} as a field.

@item normalized
Normalize the output records into record sets (@pxref{Record Sets,,,
recutils, GNU recutils manual}).  Normalizing into record sets allows joins
across record types.  The example below lists the PID of each
@code{ChildProcess} and the associated PID for @code{Session} that spawned
the @code{ChildProcess} where the @code{Session} was started using
@command{guix build}.

@example
$ guix processes --format=normalized | \
    recsel \
    -j Session \
    -t ChildProcess \
    -p Session.PID,PID \
    -e 'Session.ClientCommand ~ "guix build"'
PID: 4435
Session_PID: 4278

PID: 4554
Session_PID: 4278

PID: 4646
Session_PID: 4278
@end example
@end table
@end table

@node Arquiteturas estrangeiras
@chapter Arquiteturas estrangeiras

You can target computers of different CPU architectures when producing
packages (@pxref{Invocando guix package}), packs (@pxref{Invocando guix pack})
or full systems (@pxref{Invocando guix system}).

GNU Guix supports two distinct mechanisms to target foreign architectures:

@enumerate
@item
The traditional
@uref{https://en.wikipedia.org/wiki/Cross_compiler,cross-compilation}
mechanism.
@item
The native building mechanism which consists in building using the CPU
instruction set of the foreign system you are targeting.  It often requires
emulation, using the QEMU program for instance.
@end enumerate

@menu
* Compilação cruzada::       Compilação cruzada para outra arquitetura.
* Construções nativas::      Targeting another architecture through native 
                               builds.
@end menu

@node Compilação cruzada
@section Compilação cruzada

@cindex arquiteturas estrangeiras
The commands supporting cross-compilation are proposing the
@option{--list-targets} and @option{--target} options.

The @option{--list-targets} option lists all the supported targets that can
be passed as an argument to @option{--target}.

@example
$ guix build --list-targets
The available targets are:

   - aarch64-linux-gnu
   - arm-linux-gnueabihf
   - avr
   - i586-pc-gnu
   - i686-linux-gnu
   - i686-w64-mingw32
   - loongarch64-linux-gnu
   - mips64el-linux-gnu
   - or1k-elf
   - powerpc-linux-gnu
   - powerpc64le-linux-gnu
   - riscv64-linux-gnu
   - x86_64-linux-gnu
   - x86_64-linux-gnux32
   - x86_64-w64-mingw32
   - xtensa-ath9k-elf
@end example

Targets are specified as GNU triplets (@pxref{Specifying Target Triplets,
GNU configuration triplets,, autoconf, Autoconf}).

Those triplets are passed to GCC and the other underlying compilers possibly
involved when building a package, a system image or any other GNU Guix
output.

@example
$ guix build --target=aarch64-linux-gnu hello
/gnu/store/9926by9qrxa91ijkhw9ndgwp4bn24g9h-hello-2.12

$ file /gnu/store/9926by9qrxa91ijkhw9ndgwp4bn24g9h-hello-2.12/bin/hello
/gnu/store/9926by9qrxa91ijkhw9ndgwp4bn24g9h-hello-2.12/bin/hello: ELF
64-bit LSB executable, ARM aarch64 @dots{}
@end example

The major benefit of cross-compilation is that there are no performance
penalty compared to emulation using QEMU.  There are however higher risks
that some packages fail to cross-compile because fewer users are using this
mechanism extensively.

@node Construções nativas
@section Construções nativas

The commands that support impersonating a specific system have the
@option{--list-systems} and @option{--system} options.

The @option{--list-systems} option lists all the supported systems that can
be passed as an argument to @option{--system}.

@example
$ guix build --list-systems
The available systems are:

   - x86_64-linux [current]
   - aarch64-linux
   - armhf-linux
   - i586-gnu
   - i686-linux
   - mips64el-linux
   - powerpc-linux
   - powerpc64le-linux
   - riscv64-linux

$ guix build --system=i686-linux hello
/gnu/store/cc0km35s8x2z4pmwkrqqjx46i8b1i3gm-hello-2.12

$ file /gnu/store/cc0km35s8x2z4pmwkrqqjx46i8b1i3gm-hello-2.12/bin/hello
/gnu/store/cc0km35s8x2z4pmwkrqqjx46i8b1i3gm-hello-2.12/bin/hello: ELF
32-bit LSB executable, Intel 80386 @dots{}
@end example

In the above example, the current system is @var{x86_64-linux}.  The
@var{hello} package is however built for the @var{i686-linux} system.

This is possible because the @var{i686} CPU instruction set is a subset of
the @var{x86_64}, hence @var{i686} targeting binaries can be run on
@var{x86_64}.

Still in the context of the previous example, if picking the
@var{aarch64-linux} system and the @command{guix build
--system=aarch64-linux hello} has to build some derivations, an extra step
might be needed.

The @var{aarch64-linux} targeting binaries cannot directly be run on a
@var{x86_64-linux} system.  An emulation layer is requested.  The GNU Guix
daemon can take advantage of the Linux kernel
@uref{https://en.wikipedia.org/wiki/Binfmt_misc,binfmt_misc} mechanism for
that.  In short, the Linux kernel can defer the execution of a binary
targeting a foreign platform, here @var{aarch64-linux}, to a userspace
program, usually an emulator.

There is a service that registers QEMU as a backend for the
@code{binfmt_misc} mechanism (@pxref{Serviços de virtualização,
@code{qemu-binfmt-service-type}}).  On Debian based foreign distributions,
the alternative would be the @code{qemu-user-static} package.

If the @code{binfmt_misc} mechanism is not setup correctly, the building
will fail this way:

@example
$ guix build --system=armhf-linux hello --check
@dots{}
@ unsupported-platform /gnu/store/jjn969pijv7hff62025yxpfmc8zy0aq0-hello-2.12.drv aarch64-linux
while setting up the build environment: a `aarch64-linux' is required to
build `/gnu/store/jjn969pijv7hff62025yxpfmc8zy0aq0-hello-2.12.drv', but
I am a `x86_64-linux'@dots{}
@end example

whereas, with the @code{binfmt_misc} mechanism correctly linked with QEMU,
one can expect to see:

@example
$ guix build --system=armhf-linux hello --check
/gnu/store/13xz4nghg39wpymivlwghy08yzj97hlj-hello-2.12
@end example

The main advantage of native building compared to cross-compiling, is that
more packages are likely to build correctly.  However it comes at a price:
compilation backed by QEMU is @emph{way slower} than cross-compilation,
because every instruction needs to be emulated.

The availability of substitutes for the architecture targeted by the
@code{--system} option can mitigate this problem.  An other way to work
around it is to install GNU Guix on a machine whose CPU supports the
targeted instruction set, and set it up as an offload machine (@pxref{Configuração de descarregamento de daemon}).

@node Configuração do sistema
@chapter Configuração do sistema

@cindex configuração do sistema
Guix System supports a consistent whole-system configuration mechanism.  By
that we mean that all aspects of the global system configuration---such as
the available system services, timezone and locale settings, user
accounts---are declared in a single place.  Such a @dfn{system
configuration} can be @dfn{instantiated}---i.e., effected.

@c Yes, we're talking of Puppet, Chef, & co. here.  ↑
Uma das vantages de colocar todas as configurações do sistema sob controle
do Guix é que ele permite atualizações transacionais do sistema, o que torna
possível o retrocesso a uma instanciação anterior do sistema, caso algo de
errado com a nova (@pxref{Recursos}).  Outra vantagem é que ele facilita a
replicação da mesma configuração em máquinas diferentes, ou em momentos
diferentesm sem ter que passar por outras ferramentas de administração
adicionais por cima das ferramentas do sistema.

This section describes this mechanism.  First we focus on the system
administrator's viewpoint---explaining how the system is configured and
instantiated.  Then we show how this mechanism can be extended, for instance
to support new system services.

@menu
* Começando com o Sistema::  Seus primeiros passos.
* Usando o sistema de configuração::  Personalizando seu sistema GNU.
* Referência do operating-system::  Detalhe das declarações do 
                                      operating-system.
* Sistemas de arquivos::     Configurando montagens de sistema de arquivos.
* Dispositivos mapeados::    Processamento extra de dispositivo de bloco.
* Espaço de troca (swap)::   Apoiando a RAM com espaço em disco.
* Contas de usuário::        Especificando contas de usuários.
* Disposição do teclado::    Como o sistema interpreta pressionamento de 
                               teclas.
* Localidades::              Configurações de idioma e de convenção 
                               cultural.
* Serviços::                 Especificando serviços de sistema.
* Privileged Programs::      Programs running with elevated privileges.
* Certificados X.509::       Autenticando servidores HTTPS.
* Name Service Switch::      Configurando name service switch do libc.
* Disco de RAM inicial::     Inicialização do Linux-Libre.
* Configuração do carregador de inicialização::  Configurando o 
                                                   "bootloader".
* Invocando guix system::    Inicializando uma configuração de sistema.
* Invocando guix deploy::    Implantando uma configuração de sistema em um 
                               host remoto.
* Executando Guix em uma VM::  Como executar Guix System em uma máquina 
                                 virtual.
* Definindo serviços::       Adicionando novas definições de serviço.
@end menu

@node Começando com o Sistema
@section Começando

@cindex system configuration file
@cindex configuration file, of the system
You're reading this section probably because you have just installed Guix
System (@pxref{Instalação do sistema}) and would like to know where to go from
here.  If you're already familiar with GNU/Linux system administration, the
way Guix System is configured is very different from what you're used to:
you won't install a system service by running @command{guix install}, you
won't configure services by modifying files under @file{/etc}, and you won't
create user accounts by invoking @command{useradd}; instead, all these
aspects are spelled out in a @dfn{system configuration file}.

The first step with Guix System is thus to write the @dfn{system
configuration file}; luckily, system installation already generated one for
you and stored it under @file{/etc/config.scm}.

@quotation Nota
You can store your system configuration file anywhere you like---it doesn't
have to be at @file{/etc/config.scm}.  It's a good idea to keep it under
version control, for instance in a @uref{https://git-scm.com/book/en/, Git
repository}.
@end quotation

The @emph{entire} configuration of the system---user accounts, system
services, timezone, locale settings---is declared in this file, which
follows this template:

@lisp
(use-modules (gnu))
(use-package-modules @dots{})
(use-service-modules @dots{})

(operating-system
  (host-name @dots{})
  (timezone @dots{})
  (locale @dots{})
  (bootloader @dots{})
  (file-systems @dots{})
  (users @dots{})
  (packages @dots{})
  (services @dots{}))
@end lisp

This configuration file is in fact a Scheme program; the first lines pull in
modules providing variables you might need in the rest of the file---e.g.,
packages, services, etc.  The @code{operating-system} form declares the
system configuration as a @dfn{record} with a number of @dfn{fields}.
@xref{Usando o sistema de configuração}, to view complete examples and learn
what to put in there.

The second step, once you have this configuration file, is to test it.  Of
course, you can skip this step if you're feeling lucky---you choose! To do
that, pass your configuration file to @command{guix system vm} (no need to
be root, you can do that as a regular user):

@example
guix system vm /etc/config.scm
@end example

@noindent
This command returns the name of a shell script that starts a virtual
machine (VM) running the system @emph{as described in the configuration
file}:

@example
/gnu/store/@dots{}-run-vm.sh
@end example

@noindent
In this VM, you can log in as @code{root} with no password.  That's a good
way to check that your configuration file is correct and that it gives the
expected result, without touching your system.  @xref{Invocando guix system},
for more information.

@quotation Nota
When using @command{guix system vm}, aspects tied to your hardware such as
file systems and mapped devices are overridden because they cannot be
meaningfully tested in the VM@.  Other aspects such as static network
configuration (@pxref{Networking Setup,
@code{static-networking-service-type}}) are @emph{not} overridden but they
may not work inside the VM@.
@end quotation

@cindex system instantiation
@cindex reconfiguring the system
The third step, once you're happy with your configuration, is to
@dfn{instantiate} it---make this configuration effective on your system.  To
do that, run:

@example
sudo guix system reconfigure /etc/config.scm
@end example

@cindex upgrading system services
@cindex system services, upgrading
@noindent
This operation is @dfn{transactional}: either it succeeds and you end up
with an upgraded system, or it fails and nothing has changed.  Note that it
does @emph{not} restart system services that were already running.  Thus, to
upgrade those services, you have to reboot or to explicitly restart them;
for example, to restart the secure shell (SSH) daemon, you would run:

@example
sudo herd restart sshd
@end example

@quotation Nota
System services are managed by the Shepherd (@pxref{Jump Start,,, shepherd,
The GNU Shepherd Manual}).  The @code{herd} command lets you inspect, start,
and stop services.  To view the status of services, run:

@example
sudo herd status
@end example

To view detailed information about a given service, add its name to the
command:

@example
sudo herd status sshd
@end example

@xref{Serviços}, for more information.
@end quotation

@cindex provenance, of the system
The system records its @dfn{provenance}---the configuration file and
channels that were used to deploy it.  You can view it like so:

@example
guix system describe
@end example

Additionally, @command{guix system reconfigure} preserves previous system
generations, which you can list:

@example
guix system list-generations
@end example

@noindent
@cindex roll back, for the system
Crucially, that means that you can always @emph{roll back} to an earlier
generation should something go wrong! When you eventually reboot, you'll
notice a sub-menu in the bootloader that reads ``Old system generations'':
it's what allows you to boot @emph{an older generation of your system},
should the latest generation be ``broken'' or otherwise unsatisfying.  You
can also ``permanently'' roll back, like so:

@example
sudo guix system roll-back
@end example

@noindent
Alternatively, you can use @command{guix system switch-generation} to switch
to a specific generation.

Once in a while, you'll want to delete old generations that you do not need
anymore to allow @dfn{garbage collection} to free space (@pxref{Invocando guix gc}).  For example, to remove generations older than 4 months, run:

@example
sudo guix system delete-generations 4m
@end example

From there on, anytime you want to change something in the system
configuration, be it adding a user account or changing parameters of a
service, you will first update your configuration file and then run
@command{guix system reconfigure} as shown above.
@cindex upgrade, of the system
Likewise, to @emph{upgrade} system software, you first fetch an up-to-date
Guix and then reconfigure your system with that new Guix:

@example
guix pull
sudo guix system reconfigure /etc/config.scm
@end example

@noindent
We recommend doing that regularly so that your system includes the latest
security updates (@pxref{Atualizações de segurança}).

@c See <https://lists.gnu.org/archive/html/guix-devel/2019-01/msg00268.html>.
@quotation Nota
@cindex sudo vs. @command{guix pull}
@command{sudo guix} runs your user's @command{guix} command and @emph{not}
root's, because @command{sudo} leaves @env{PATH} unchanged.

The difference matters here, because @command{guix pull} updates the
@command{guix} command and package definitions only for the user it is run
as.  This means that if you choose to use @command{guix system reconfigure}
in root's login shell, you'll need to @command{guix pull} separately.
@end quotation

That's it! If you're getting started with Guix entirely, @pxref{Começando}.  The next sections dive in more detail into the crux of the
matter: system configuration.

@node Usando o sistema de configuração
@section Usando o sistema de configuração

The previous section showed the overall workflow you would follow when
administering a Guix System machine (@pxref{Começando com o Sistema}).  Let's now see in more detail what goes into the system
configuration file.

The operating system is configured by providing an @code{operating-system}
declaration in a file that can then be passed to the @command{guix system}
command (@pxref{Invocando guix system}), as we've seen before.  A simple
setup, with the default Linux-Libre kernel, initial RAM disk, and a couple
of system services added to those provided by default looks like this:

@findex operating-system
@lisp
@include os-config-bare-bones.texi
@end lisp

The configuration is declarative.  It is code in the Scheme programming
language; the whole @code{(operating-system @dots{})} expression produces a
@dfn{record} with a number of @dfn{fields}.  Some of the fields defined
above, such as @code{host-name} and @code{bootloader}, are mandatory.
Others, such as @code{packages} and @code{services}, can be omitted, in
which case they get a default value.  @xref{Referência do operating-system}, for
details about all the available fields.

Below we discuss the meaning of some of the most important fields.

@quotation Troubleshooting
The configuration file is a Scheme program and you might get the syntax or
semantics wrong as you get started.  Syntactic issues such as misplaced
parentheses can often be identified by reformatting your file:

@example
guix style -f config.scm
@end example

The Cookbook has a short section to get started with the Scheme programming
language that explains the fundamentals, which you will find helpful when
hacking your configuration.  @xref{A Scheme Crash Course,,, guix-cookbook,
GNU Guix Cookbook}.
@end quotation

@unnumberedsubsec Carregador de inicialização

@cindex legacy boot, on Intel machines
@cindex BIOS boot, on Intel machines
@cindex UEFI boot
@cindex EFI boot
The @code{bootloader} field describes the method that will be used to boot
your system.  Machines based on Intel processors can boot in ``legacy'' BIOS
mode, as in the example above.  However, more recent machines rely instead
on the @dfn{Unified Extensible Firmware Interface} (UEFI) to boot.  In that
case, the @code{bootloader} field should contain something along these
lines:

@lisp
(bootloader-configuration
  (bootloader grub-efi-bootloader)
  (targets '("/boot/efi")))
@end lisp

@xref{Configuração do carregador de inicialização}, for more information on the available
configuration options.

@unnumberedsubsec Globally-Visible Packages

@vindex %base-packages
The @code{packages} field lists packages that will be globally visible on
the system, for all user accounts---i.e., in every user's @env{PATH}
environment variable---in addition to the per-user profiles (@pxref{Invocando guix package}).  The @code{%base-packages} variable provides all the tools
one would expect for basic user and administrator tasks---including the GNU
Core Utilities, the GNU Networking Utilities, the @command{mg} lightweight
text editor, @command{find}, @command{grep}, etc.  The example above adds
GNU@tie{}Screen to those, taken from the @code{(gnu packages screen)} module
(@pxref{Módulos de pacote}).  The @code{(list package output)} syntax can be
used to add a specific output of a package:

@lisp
(use-modules (gnu packages))
(use-modules (gnu packages dns))

(operating-system
  ;; ...
  (packages (cons (list isc-bind "utils")
                  %base-packages)))
@end lisp

@findex specification->package
Referring to packages by variable name, like @code{isc-bind} above, has the
advantage of being unambiguous; it also allows typos and such to be
diagnosed right away as ``unbound variables''.  The downside is that one
needs to know which module defines which package, and to augment the
@code{use-package-modules} line accordingly.  To avoid that, one can use the
@code{specification->package} procedure of the @code{(gnu packages)} module,
which returns the best package for a given name or name and version:

@lisp
(use-modules (gnu packages))

(operating-system
  ;; ...
  (packages (append (map specification->package
                         '("tcpdump" "htop" "gnupg@@2.0"))
                    %base-packages)))
@end lisp

@findex specifications->packages
When a package has more than one output it can be a challenge to refer to a
specific output instead of just to the standard @code{out} output.  For
these situations one can use the @code{specifications->packages} procedure
from the @code{(gnu packages)} module.  For example:

@lisp
(use-modules (gnu packages))

(operating-system
  ;; ...
  (packages (append (specifications->packages
                      '("git" "git:send-email"))
                    %base-packages)))

@end lisp

@unnumberedsubsec Serviços do sistema

@cindex services
@vindex %base-services
The @code{services} field lists @dfn{system services} to be made available
when the system starts (@pxref{Serviços}).  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{Serviços de Rede, @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{Definindo serviços}).

@cindex customization, of services
@findex modify-services
Occasionally, instead of using the base services as is, you will want to
customize them.  To do this, use @code{modify-services} (@pxref{Referência de Service, @code{modify-services}}) to modify the list.

@anchor{auto-login to TTY} For example, suppose you want to modify @code{guix-daemon} and Mingetty (the
console log-in) in the @code{%base-services} list (@pxref{Serviços básicos,
@code{%base-services}}).  To do that, you can write the following in your
operating system declaration:

@lisp
(define %my-services
  ;; My very own list of services.
  (modify-services %base-services
    (guix-service-type config =>
                       (guix-configuration
                        (inherit config)
                        ;; Fetch substitutes from example.org.
                        (substitute-urls
                          (list "https://example.org/guix"
                                "https://ci.guix.gnu.org"))))
    (mingetty-service-type config =>
                           (mingetty-configuration
                            (inherit config)
                            ;; Automatically log in as "guest".
                            (auto-login "guest")))))

(operating-system
  ;; @dots{}
  (services %my-services))
@end lisp

This changes the configuration---i.e., the service parameters---of the
@code{guix-service-type} instance, and that of all the
@code{mingetty-service-type} instances in the @code{%base-services} list
(@pxref{Auto-Login to a Specific TTY, see the cookbook for how to auto-login
one user to a specific TTY,, guix-cookbook, GNU Guix Cookbook})).  Observe
how this is accomplished: first, we arrange for the original configuration
to be bound to the identifier @code{config} in the @var{body}, and then we
write the @var{body} so that it evaluates to the desired configuration.  In
particular, notice how we use @code{inherit} to create a new configuration
which has the same values as the old configuration, but with a few
modifications.

@cindex disco criptografado
The configuration for a typical ``desktop'' usage, with an encrypted root
partition, a swap file on the root partition, the X11 display server, GNOME
and Xfce (users can choose which of these desktop environments to use at the
log-in screen by pressing @kbd{F1}), network management, power management,
and more, would look like this:

@lisp
@include os-config-desktop.texi
@end lisp

Um sistema gráfico com uma escolha de gerenciadores de janelas leves em vez
de ambientes de desktop completos teria a seguinte aparência:

@lisp
@include os-config-lightweight-desktop.texi
@end lisp

Este exemplo faz referência ao sistema de arquivos @file{/boot/efi} por seu
UUID, @code{1234-ABCD}. Substitua esse UUID pelo UUID correto no seu
sistema, conforme retornado pelo comando @command{blkid}.

@xref{Serviços de desktop}, for the exact list of services provided by
@code{%desktop-services}.

Again, @code{%desktop-services} is just a list of service objects.  If you
want to remove services from there, you can do so using the procedures for
list filtering (@pxref{SRFI-1 Filtering and Partitioning,,, guile, GNU Guile
Reference Manual}).  For instance, the following expression returns a list
that contains all the services in @code{%desktop-services} minus the Avahi
service:

@lisp
(remove (lambda (service)
          (eq? (service-kind service) avahi-service-type))
        %desktop-services)
@end lisp

Alternatively, the @code{modify-services} macro can be used:

@lisp
(modify-services %desktop-services
  (delete avahi-service-type))
@end lisp

@unnumberedsubsec Inspecting Services

@cindex troubleshooting, for system services
@cindex inspecting system services
@cindex system services, inspecting
As you work on your system configuration, you might wonder why some system
service doesn't show up or why the system is not as you expected.  There are
several ways to inspect and troubleshoot problems.

@cindex dependency graph, of Shepherd services
First, you can inspect the dependency graph of Shepherd services like so:

@example
guix system shepherd-graph /etc/config.scm | \
  guix shell xdot -- xdot -
@end example

This lets you visualize the Shepherd services as defined in
@file{/etc/config.scm}.  Each box is a service as would be shown by
@command{sudo herd status} on the running system, and each arrow denotes a
dependency (in the sense that if service @var{A} depends on @var{B}, then
@var{B} must be started before @var{A}).

@cindex extension graph, of services
Not all ``services'' are Shepherd services though, since Guix System uses a
broader definition of the term (@pxref{Serviços}).  To visualize system
services and their relations at a higher level, run:

@example
guix system extension-graph /etc/config.scm | \
  guix shell xdot -- xdot -
@end example

This lets you view the @dfn{service extension graph}: how services
``extend'' each other, for instance by contributing to their configuration.
@xref{Composição de serviço}, to understand the meaning of this graph.

Last, you may also find it useful to inspect your system configuration at
the REPL (@pxref{Usando Guix interativamente}).  Here is an example session:

@example
$ guix repl
scheme@@(guix-user)> ,use (gnu)
scheme@@(guix-user)> (define os (load "config.scm"))
scheme@@(guix-user)> ,pp (map service-kind (operating-system-services os))
$1 = (#<service-type localed cabba93>
      @dots{})
@end example

@xref{Referência de Service}, to learn about the Scheme interface to manipulate
and inspect services.

@unnumberedsubsec Instantiating the System

@cindex system instantiation
@cindex reconfiguring the system
Assuming the @code{operating-system} declaration is stored in the
@file{config.scm} file, the @command{sudo guix system reconfigure
config.scm} command instantiates that configuration, and makes it the
default boot entry.  @xref{Começando com o Sistema}, for an
overview.

The normal way to change the system configuration is by updating this file
and re-running @command{guix system reconfigure}.  One should never have to
touch files in @file{/etc} or to run commands that modify the system state
such as @command{useradd} or @command{grub-install}.  In fact, you must
avoid that since that would not only void your warranty but also prevent you
from rolling back to previous versions of your system, should you ever need
to.

@unnumberedsubsec The Programming Interface

At the Scheme level, the bulk of an @code{operating-system} declaration is
instantiated with the following monadic procedure (@pxref{A mônada do armazém}):

@deffn {Monadic Procedure} operating-system-derivation os
Return a derivation that builds @var{os}, an @code{operating-system} object
(@pxref{Derivações}).

The output of the derivation is a single directory that refers to all the
packages, configuration files, and other supporting files needed to
instantiate @var{os}.
@end deffn

This procedure is provided by the @code{(gnu system)} module.  Along with
@code{(gnu services)} (@pxref{Serviços}), this module contains the guts of
Guix System.  Make sure to visit it!


@node Referência do operating-system
@section @code{operating-system} Reference

This section summarizes all the options available in @code{operating-system}
declarations (@pxref{Usando o sistema de configuração}).

@deftp {Tipo de dados} operating-system
This is the data type representing an operating system configuration.  By
that, we mean all the global system configuration, not per-user
configuration (@pxref{Usando o sistema de configuração}).

@table @asis
@item @code{kernel} (default: @code{linux-libre})
@c footnote duplicated in @pxref{Instalação}
The package object of the operating system kernel to use@footnote{Currently
only the Linux-libre kernel is fully supported.  Using GNU@tie{}mach with
the GNU@tie{}Hurd is experimental and only available when building a virtual
machine disk image.}.

@cindex hurd
@item @code{hurd} (default: @code{#f})
The package object of the Hurd to be started by the kernel.  When this field
is set, produce a GNU/Hurd operating system.  In that case, @code{kernel}
must also be set to the @code{gnumach} package---the microkernel the Hurd
runs on.

@quotation Aviso
This feature is experimental and only supported for disk images.
@end quotation

@item @code{kernel-loadable-modules} (default: '())
A list of objects (usually packages) to collect loadable kernel modules
from--e.g. @code{(list ddcci-driver-linux)}.

@item @code{kernel-arguments} (default: @code{%default-kernel-arguments})
List of strings or gexps representing additional arguments to pass on the
command-line of the kernel---e.g., @code{("console=ttyS0")}.

@item @code{bootloader}
The system bootloader configuration object.  @xref{Configuração do carregador de inicialização}.

@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} (padrão: @code{#f})
This field specifies the keyboard layout to use in the console.  It can be
either @code{#f}, in which case the default keyboard layout is used (usually
US English), or a @code{<keyboard-layout>} record. @xref{Disposição do teclado},
for more information.

This keyboard layout is in effect as soon as the kernel has booted.  For
instance, it is the keyboard layout in effect when you type a passphrase if
your root file system is on a @code{luks-device-mapping} mapped device
(@pxref{Dispositivos mapeados}).

@quotation Nota
This does @emph{not} specify the keyboard layout used by the bootloader, nor
that used by the graphical display server.  @xref{Configuração do carregador de inicialização},
for information on how to specify the bootloader's keyboard layout.  @xref{X Window}, for information on how to specify the keyboard layout used by the X
Window System.
@end quotation

@item @code{initrd-modules} (default: @code{%base-initrd-modules})
@cindex initrd
@cindex initial RAM disk
The list of Linux kernel modules that need to be available in the initial
RAM disk.  @xref{Disco de RAM inicial}.

@item @code{initrd} (default: @code{base-initrd})
A procedure that returns an initial RAM disk for the Linux kernel.  This
field is provided to support low-level customization and should rarely be
needed for casual use.  @xref{Disco de RAM inicial}.

@item @code{firmware} (default: @code{%base-firmware})
@cindex firmware
List of firmware packages loadable by the operating system kernel.

The default includes firmware needed for Atheros- and Broadcom-based WiFi
devices (Linux-libre modules @code{ath9k} and @code{b43-open},
respectively).  @xref{Considerações de hardware}, for more info on supported
hardware.

@item @code{host-name}
The host name.

@item @code{mapped-devices} (default: @code{'()})
A list of mapped devices.  @xref{Dispositivos mapeados}.

@item @code{file-systems}
A list of file systems.  @xref{Sistemas de arquivos}.

@item @code{swap-devices} (default: @code{'()})
@cindex swap devices
A list of swap spaces.  @xref{Espaço de troca (swap)}.

@item @code{users} (default: @code{%base-user-accounts})
@itemx @code{groups} (default: @code{%base-groups})
List of user accounts and groups.  @xref{Contas de usuário}.

If the @code{users} list lacks a user account with UID@tie{}0, a ``root''
account with UID@tie{}0 is automatically added.

@item @code{skeletons} (default: @code{(default-skeletons)})
A list of target file name/file-like object tuples (@pxref{Expressões-G,
file-like objects}).  These are the skeleton files that will be added to the
home directory of newly-created user accounts.

For instance, a valid value may look like this:

@lisp
`((".bashrc" ,(plain-file "bashrc" "echo Hello\n"))
  (".guile" ,(plain-file "guile"
                         "(use-modules (ice-9 readline))
                          (activate-readline)")))
@end lisp

@item @code{issue} (default: @code{%default-issue})
A string denoting the contents of the @file{/etc/issue} file, which is
displayed when users log in on a text console.

@item @code{packages} (default: @code{%base-packages})
A list of packages to be installed in the global profile, which is
accessible at @file{/run/current-system/profile}.  Each element is either a
package variable or a package/output tuple.  Here's a simple example of
both:

@lisp
(cons* git                     ; the default "out" output
       (list git "send-email") ; another output of git
       %base-packages)         ; the default set
@end lisp

The default set includes core utilities and it is good practice to install
non-core utilities in user profiles (@pxref{Invocando guix package}).

@item @code{timezone} (default: @code{"Etc/UTC"})
A timezone identifying string---e.g., @code{"Europe/Paris"}.

You can run the @command{tzselect} command to find out which timezone string
corresponds to your region.  Choosing an invalid timezone name causes
@command{guix system} to fail.

@item @code{locale} (default: @code{"en_US.utf8"})
The name of the default locale (@pxref{Locale Names,,, libc, The GNU C
Library Reference Manual}).  @xref{Localidades}, for more information.

@item @code{locale-definitions} (default: @code{%default-locale-definitions})
The list of locale definitions to be compiled and that may be used at run
time.  @xref{Localidades}.

@item @code{locale-libcs} (default: @code{(list @var{glibc})})
The list of GNU@tie{}libc packages whose locale data and tools are used to
build the locale definitions.  @xref{Localidades}, for compatibility
considerations that justify this option.

@item @code{name-service-switch} (default: @code{%default-nss})
Configuration of the libc name service switch (NSS)---a
@code{<name-service-switch>} object.  @xref{Name Service Switch}, for
details.

@item @code{services} (default: @code{%base-services})
A list of service objects denoting system services.  @xref{Serviços}.

@anchor{operating-system-essential-services}
@cindex essential services
@item @code{essential-services} (default: ...)
The list of ``essential services''---i.e., things like instances of
@code{system-service-type} (@pxref{Referência de Service}) and
@code{host-name-service-type}, which are derived from the operating system
definition itself.  As a user you should @emph{never} need to touch this
field.

@item @code{pam-services} (default: @code{(base-pam-services)})
@cindex PAM
@cindex pluggable authentication modules
@c FIXME: Add xref to PAM services section.
Linux @dfn{pluggable authentication module} (PAM) services.

@item @code{privileged-programs} (default: @code{%default-privileged-programs})
List of @code{<privileged-program>}.  @xref{Privileged Programs}, for more
information.

@item @code{sudoers-file} (default: @code{%sudoers-specification})
@cindex sudoers file
The contents of the @file{/etc/sudoers} file as a file-like object
(@pxref{Expressões-G, @code{local-file} and @code{plain-file}}).

This file specifies which users can use the @command{sudo} command, what
they are allowed to do, and what privileges they may gain.  The default is
that only @code{root} and members of the @code{wheel} group may use
@code{sudo}.

@end table

@defmac this-operating-system
When used in the @emph{lexical scope} of an operating system field
definition, this identifier resolves to the operating system being defined.

The example below shows how to refer to the operating system being defined
in the definition of the @code{label} field:

@lisp
(use-modules (gnu) (guix))

(operating-system
  ;; ...
  (label (package-full-name
          (operating-system-kernel this-operating-system))))
@end lisp

It is an error to refer to @code{this-operating-system} outside an operating
system definition.
@end defmac

@end deftp

@node Sistemas de arquivos
@section Sistemas de arquivos

The list of file systems to be mounted is specified in the
@code{file-systems} field of the operating system declaration (@pxref{Usando o sistema de configuração}).  Each file system is declared using the
@code{file-system} form, like this:

@lisp
(file-system
  (mount-point "/home")
  (device "/dev/sda3")
  (type "ext4"))
@end lisp

As usual, some of the fields are mandatory---those shown in the example
above---while others can be omitted.  These are described below.

@deftp {Tipo de dados} file-system
Objects of this type represent file systems to be mounted.  They contain the
following members:

@table @asis
@item @code{tipo}
This is a string specifying the type of the file system---e.g.,
@code{"ext4"}.

@item @code{mount-point}
This designates the place where the file system is to be mounted.

@item @code{device}
This names the ``source'' of the file system.  It can be one of three
things: a file system label, a file system UUID, or the name of a
@file{/dev} node.  Labels and UUIDs offer a way to refer to file systems
without having to hard-code their actual device name@footnote{Note that,
while it is tempting to use @file{/dev/disk/by-uuid} and similar device
names to achieve the same result, this is not recommended: These special
device nodes are created by the udev daemon and may be unavailable at the
time the device is mounted.}.

@findex file-system-label
File system labels are created using the @code{file-system-label} procedure,
UUIDs are created using @code{uuid}, and @file{/dev} nodes are plain
strings.  Here's an example of a file system referred to by its label, as
shown by the @command{e2label} command:

@lisp
(file-system
  (mount-point "/home")
  (type "ext4")
  (device (file-system-label "my-home")))
@end lisp

@findex uuid
UUIDs are converted from their string representation (as shown by the
@command{tune2fs -l} command) using the @code{uuid} form@footnote{The
@code{uuid} form expects 16-byte UUIDs as defined in
@uref{https://tools.ietf.org/html/rfc4122, RFC@tie{}4122}.  This is the form
of UUID used by the ext2 family of file systems and others, but it is
different from ``UUIDs'' found in FAT file systems, for instance.}, like
this:

@lisp
(file-system
  (mount-point "/home")
  (type "ext4")
  (device (uuid "4dab5feb-d176-45de-b287-9b0a6e4c01cb")))
@end lisp

When the source of a file system is a mapped device (@pxref{Dispositivos mapeados}), its @code{device} field @emph{must} refer to the mapped device
name---e.g., @file{"/dev/mapper/root-partition"}.  This is required so that
the system knows that mounting the file system depends on having the
corresponding device mapping established.

@item @code{flags} (default: @code{'()})
This is a list of symbols denoting mount flags.  Recognized flags include
@code{read-only}, @code{bind-mount}, @code{no-dev} (disallow access to
special files), @code{no-suid} (ignore setuid and setgid bits),
@code{no-atime} (do not update file access times), @code{no-diratime}
(likewise for directories only), @code{strict-atime} (update file access
time), @code{lazy-time} (only update time on the in-memory version of the
file inode), @code{no-exec} (disallow program execution), @code{remount}
(remount a mounted file system), and @code{shared} (make the mount shared).
@xref{Mount-Unmount-Remount,,, libc, The GNU C Library Reference Manual},
for more information on these flags.

@item @code{options} (padrão: @code{#f})
This is either @code{#f}, or a string denoting mount options passed to the
file system driver.  @xref{Mount-Unmount-Remount,,, libc, The GNU C Library
Reference Manual}, for details.

Run @command{man 8 mount} for options for various file systems, but beware
that what it lists as file-system-independent ``mount options'' are in fact
flags, and belong in the @code{flags} field described above.

The @code{file-system-options->alist} and @code{alist->file-system-options}
procedures from @code{(gnu system file-systems)} can be used to convert file
system options given as an association list to the string representation,
and vice-versa.

@item @code{mount?} (padrão: @code{#t})
This value indicates whether to automatically mount the file system when the
system is brought up.  When set to @code{#f}, the file system gets an entry
in @file{/etc/fstab} (read by the @command{mount} command) but is not
automatically mounted.

@item @code{needed-for-boot?} (default: @code{#f})
This Boolean value indicates whether the file system is needed when
booting.  If that is true, then the file system is mounted when the initial
RAM disk (initrd) is loaded.  This is always the case, for instance, for the
root file system.

@item @code{check?} (padrão: @code{#t})
This Boolean indicates whether the file system should be checked for errors
before being mounted.  How and when this happens can be further adjusted
with the following options.

@item @code{skip-check-if-clean?} (default: @code{#t})
When true, this Boolean indicates that a file system check triggered by
@code{check?} may exit early if the file system is marked as ``clean'',
meaning that it was previously correctly unmounted and should not contain
errors.

Setting this to false will always force a full consistency check when
@code{check?} is true.  This may take a very long time and is not
recommended on healthy systems---in fact, it may reduce reliability!

Conversely, some primitive file systems like @code{fat} do not keep track of
clean shutdowns and will perform a full scan regardless of the value of this
option.

@item @code{repair} (default: @code{'preen})
When @code{check?} finds errors, it can (try to) repair them and continue
booting.  This option controls when and how to do so.

If false, try not to modify the file system at all.  Checking certain file
systems like @code{jfs} may still write to the device to replay the
journal.  No repairs will be attempted.

If @code{#t}, try to repair any errors found and assume ``yes'' to all
questions.  This will fix the most errors, but may be risky.

If @code{'preen}, repair only errors that are safe to fix without human
interaction.  What that means is left up to the developers of each file
system and may be equivalent to ``none'' or ``all''.

@item @code{create-mount-point?} (default: @code{#f})
When true, the mount point is created if it does not exist yet.

@item @code{mount-may-fail?} (default: @code{#f})
When true, this indicates that mounting this file system can fail but that
should not be considered an error.  This is useful in unusual cases; an
example of this is @code{efivarfs}, a file system that can only be mounted
on EFI/UEFI systems.

@item @code{dependencies} (padrão: @code{'()})
This is a list of @code{<file-system>} or @code{<mapped-device>} objects
representing file systems that must be mounted or mapped devices that must
be opened before (and unmounted or closed after) this one.

As an example, consider a hierarchy of mounts: @file{/sys/fs/cgroup} is a
dependency of @file{/sys/fs/cgroup/cpu} and @file{/sys/fs/cgroup/memory}.

Another example is a file system that depends on a mapped device, for
example for an encrypted partition (@pxref{Dispositivos mapeados}).

@item @code{shepherd-requirements} (default: @code{'()})
This is a list of symbols denoting Shepherd requirements that must be met
before mounting the file system.

As an example, an NFS file system would typically have a requirement for
@code{networking}.  In some situations, requiring @code{networking} might
not be sufficient as @code{networking} being marked as started does
@emph{not} imply the network has already been configured and in working
order (for example, when using @code{dhcp-client-service-type}).  For such
cases, adding a requirement on a custom @code{network-online} service may be
necessary.  A sample @code{network-online} one-shot Shepherd service
implementation is provided below:

@lisp
(simple-service 'network-online shepherd-root-service-type
  (list
   (shepherd-service
    (requirement '(networking))
    (provision '(network-online))
    (documentation "Wait for the network to come up.")
    (start #~(lambda _
               (let* ((cmd
                       "set -eux
c=0
while ! /run/setuid-programs/ping -qc1 -W1 example.org; do
	sleep 1
	[ \"$((c += 1))\" -lt 30 ] || exit 1  # Limit the wait time
done
")
                    (status (system cmd)))
               (= 0 (status:exit-val status)))))
    (one-shot? #t))))
@end lisp

Typically, file systems are mounted before most other Shepherd services are
started.  However, file systems with a non-empty shepherd-requirements field
are mounted after Shepherd services have begun.  Any Shepherd service that
depends on a file system with a non-empty shepherd-requirements field must
depend on it directly and not on the generic symbol @code{file-systems}.
@end table
@end deftp

@deffn {Procedure} file-system-label str
This procedure returns an opaque file system label from @var{str}, a string:

@lisp
(file-system-label "home")
@result{} #<file-system-label "home">
@end lisp

File system labels are used to refer to file systems by label rather than by
device name.  See above for examples.
@end deffn

The @code{(gnu system file-systems)} exports the following useful variables.

@defvar %base-file-systems
These are essential file systems that are required on normal systems, such
as @code{%pseudo-terminal-file-system} and @code{%immutable-store} (see
below).  Operating system declarations should always contain at least these.
@end defvar

@defvar %pseudo-terminal-file-system
This is the file system to be mounted as @file{/dev/pts}.  It supports
@dfn{pseudo-terminals} created @i{via} @code{openpty} and similar functions
(@pxref{Pseudo-Terminals,,, libc, The GNU C Library Reference Manual}).
Pseudo-terminals are used by terminal emulators such as @command{xterm}.
@end defvar

@defvar %shared-memory-file-system
This file system is mounted as @file{/dev/shm} and is used to support memory
sharing across processes (@pxref{Memory-mapped I/O, @code{shm_open},, libc,
The GNU C Library Reference Manual}).
@end defvar

@defvar %immutable-store
This file system performs a read-only ``bind mount'' of @file{/gnu/store},
making it read-only for all the users including @code{root}.  This prevents
against accidental modification by software running as @code{root} or by
system administrators.

The daemon itself is still able to write to the store: it remounts it
read-write in its own ``name space.''
@end defvar

@defvar %binary-format-file-system
The @code{binfmt_misc} file system, which allows handling of arbitrary
executable file types to be delegated to user space.  This requires the
@code{binfmt.ko} kernel module to be loaded.
@end defvar

@defvar %fuse-control-file-system
The @code{fusectl} file system, which allows unprivileged users to mount and
unmount user-space FUSE file systems.  This requires the @code{fuse.ko}
kernel module to be loaded.
@end defvar

The @code{(gnu system uuid)} module provides tools to deal with file system
``unique identifiers'' (UUIDs).

@deffn {Procedure} uuid str [type]
Return an opaque UUID (unique identifier) object of the given @var{type} (a
symbol) by parsing @var{str} (a string):

@lisp
(uuid "4dab5feb-d176-45de-b287-9b0a6e4c01cb")
@result{} #<<uuid> type: dce bv: @dots{}>

(uuid "1234-ABCD" 'fat)
@result{} #<<uuid> type: fat bv: @dots{}>
@end lisp

@var{type} may be one of @code{dce}, @code{iso9660}, @code{fat},
@code{ntfs}, or one of the commonly found synonyms for these.

UUIDs are another way to unambiguously refer to file systems in operating
system configuration.  See the examples above.
@end deffn


@menu
* Sistema de arquivos Btrfs::  Sistema de arquivos Btrfs
@end menu

@node Sistema de arquivos Btrfs
@subsection Sistema de arquivos Btrfs

The Btrfs has special features, such as subvolumes, that merit being
explained in more details.  The following section attempts to cover basic as
well as complex uses of a Btrfs file system with the Guix System.

In its simplest usage, a Btrfs file system can be described, for example,
by:

@lisp
(file-system
  (mount-point "/home")
  (type "btrfs")
  (device (file-system-label "my-home")))
@end lisp

The example below is more complex, as it makes use of a Btrfs subvolume,
named @code{rootfs}.  The parent Btrfs file system is labeled
@code{my-btrfs-pool}, and is located on an encrypted device (hence the
dependency on @code{mapped-devices}):

@lisp
(file-system
  (device (file-system-label "my-btrfs-pool"))
  (mount-point "/")
  (type "btrfs")
  (options "subvol=rootfs")
  (dependencies mapped-devices))
@end lisp

Some bootloaders, for example GRUB, only mount a Btrfs partition at its top
level during the early boot, and rely on their configuration to refer to the
correct subvolume path within that top level.  The bootloaders operating in
this way typically produce their configuration on a running system where the
Btrfs partitions are already mounted and where the subvolume information is
readily available.  As an example, @command{grub-mkconfig}, the
configuration generator command shipped with GRUB, reads
@file{/proc/self/mountinfo} to determine the top-level path of a subvolume.

The Guix System produces a bootloader configuration using the operating
system configuration as its sole input; it is therefore necessary to extract
the subvolume name on which @file{/gnu/store} lives (if any)  from that
operating system configuration.  To better illustrate, consider a subvolume
named 'rootfs' which contains the root file system data.  In such situation,
the GRUB bootloader would only see the top level of the root Btrfs
partition, e.g.:

@example
/                   (top level)
├── rootfs          (subvolume directory)
    ├── gnu         (normal directory)
        ├── store   (normal directory)
[...]
@end example

Thus, the subvolume name must be prepended to the @file{/gnu/store} path of
the kernel, initrd binaries and any other files referred to in the GRUB
configuration that must be found during the early boot.

The next example shows a nested hierarchy of subvolumes and directories:

@example
/                   (top level)
├── rootfs          (subvolume)
    ├── gnu         (normal directory)
        ├── store   (subvolume)
[...]
@end example

This scenario would work without mounting the 'store' subvolume.  Mounting
'rootfs' is sufficient, since the subvolume name matches its intended mount
point in the file system hierarchy.  Alternatively, the 'store' subvolume
could be referred to by setting the @code{subvol} option to either
@code{/rootfs/gnu/store} or @code{rootfs/gnu/store}.

Finally, a more contrived example of nested subvolumes:

@example
/                           (top level)
├── root-snapshots          (subvolume)
    ├── root-current        (subvolume)
        ├── guix-store      (subvolume)
[...]
@end example

Here, the 'guix-store' subvolume doesn't match its intended mount point, so
it is necessary to mount it.  The subvolume must be fully specified, by
passing its file name to the @code{subvol} option.  To illustrate, the
'guix-store' subvolume could be mounted on @file{/gnu/store} by using a file
system declaration such as:

@lisp
(file-system
  (device (file-system-label "btrfs-pool-1"))
  (mount-point "/gnu/store")
  (type "btrfs")
  (options "subvol=root-snapshots/root-current/guix-store,\
compress-force=zstd,space_cache=v2"))
@end lisp

@node Dispositivos mapeados
@section Dispositivos mapeados

@cindex device mapping
@cindex mapped devices
The Linux kernel has a notion of @dfn{device mapping}: a block device, such
as a hard disk partition, can be @dfn{mapped} into another device, usually
in @code{/dev/mapper/}, with additional processing over the data that flows
through it@footnote{Note that the GNU@tie{}Hurd makes no difference between
the concept of a ``mapped device'' and that of a file system: both boil down
to @emph{translating} input/output operations made on a file to operations
on its backing store.  Thus, the Hurd implements mapped devices, like file
systems, using the generic @dfn{translator} mechanism (@pxref{Translators,,,
hurd, The GNU Hurd Reference Manual}).}.  A typical example is encryption
device mapping: all writes to the mapped device are encrypted, and all reads
are deciphered, transparently.  Guix extends this notion by considering any
device or set of devices that are @dfn{transformed} in some way to create a
new device; for instance, RAID devices are obtained by @dfn{assembling}
several other devices, such as hard disks or partitions, into a new one that
behaves as one partition.

Mapped devices are declared using the @code{mapped-device} form, defined as
follows; for examples, see below.

@deftp {Tipo de dados} mapped-device
Objects of this type represent device mappings that will be made when the
system boots up.

@table @code
@item source
This is either a string specifying the name of the block device to be
mapped, such as @code{"/dev/sda3"}, or a list of such strings when several
devices need to be assembled for creating a new one.  In case of LVM this is
a string specifying name of the volume group to be mapped.

@item target
This string specifies the name of the resulting mapped device.  For kernel
mappers such as encrypted devices of type @code{luks-device-mapping},
specifying @code{"my-partition"} leads to the creation of the
@code{"/dev/mapper/my-partition"} device.  For RAID devices of type
@code{raid-device-mapping}, the full device name such as @code{"/dev/md0"}
needs to be given.  LVM logical volumes of type @code{lvm-device-mapping}
need to be specified as @code{"VGNAME-LVNAME"}.

@item targets
This list of strings specifies names of the resulting mapped devices in case
there are several.  The format is identical to @var{target}.

@item tipo
This must be a @code{mapped-device-kind} object, which specifies how
@var{source} is mapped to @var{target}.

@item arguments
This is a list of arguments specific to @var{type} that are passed to its
@code{open}, @code{close}, and @code{check} procedures.

As an example, @code{luks-device-mapping} supports keyword arguments---see
below for details.
@end table
@end deftp

@defvar luks-device-mapping
This defines LUKS block device encryption using the @command{cryptsetup}
command from the package with the same name.  It relies on the
@code{dm-crypt} Linux kernel module.

The following options may be passed @i{via} the @code{arguments} field of a
mapped device:

@table @code
@item #:key-file
If @code{file} is provided, unlocking is first attempted using that key
file.  This has an advantage of not requiring a password entry, so it can be
used (for example) to unlock RAID arrays automatically on boot.  If key file
unlock fails, password unlock is attempted as well.  Key file is not stored
in the store and needs to be available at the given location at the time of
the unlock attempt.

@lisp
;; Following definition would be equivalent to running:
;;   cryptsetup open --key-file /crypto.key /dev/sdb1 data
(mapped-device
 (source "/dev/sdb1")
 (target "data")
 (type luks-device-mapping)
 (arguments '(#:key-file "/crypto.key")))
@end lisp

@item #:allow-discards?
@code{allow-discards?} allows the use of discard (TRIM) requests for the
underlying device.  This is useful for solid state drives.  However, this
option can have a negative security impact because it can make file system
level operations visible on the physical device.  For more information,
refer to the description of the @code{--allow-discards} option in the
@code{cryptsetup-open(8)} man page.

@item #:extra-options
List of additional command-line options for the @code{cryptsetup open}
command.  See the @code{cryptsetup-open(8)} man page for a list of supported
options.

For example, here is how you could specify the
@option{--perf-no_read_workqueue} and @option{--perf-no_write_workqueue}
options, along with @option{--allow-discards}:

@lisp
(mapped-device
  (source "/dev/sdb1")
  (target "data")
  (type luks-device-mapping)
  (arguments '(#:allow-discards? #t
               #:extra-options
               ("--perf-no_read_workqueue"
                "--perf-no_write_workqueue"))))
@end lisp

@end table
@end defvar

@defvar raid-device-mapping
This defines a RAID device, which is assembled using the @code{mdadm}
command from the package with the same name.  It requires a Linux kernel
module for the appropriate RAID level to be loaded, such as @code{raid456}
for RAID-4, RAID-5 or RAID-6, or @code{raid10} for RAID-10.
@end defvar

@cindex LVM, logical volume manager
@defvar lvm-device-mapping
This defines one or more logical volumes for the Linux
@uref{https://www.sourceware.org/lvm2/, Logical Volume Manager (LVM)}.  The
volume group is activated by the @command{vgchange} command from the
@code{lvm2} package.
@end defvar

@cindex disk encryption
@cindex LUKS
The following example specifies a mapping from @file{/dev/sda3} to
@file{/dev/mapper/home} using LUKS---the
@url{https://gitlab.com/cryptsetup/cryptsetup,Linux Unified Key Setup}, a
standard mechanism for disk encryption.  The @file{/dev/mapper/home} device
can then be used as the @code{device} of a @code{file-system} declaration
(@pxref{Sistemas de arquivos}).

@lisp
(mapped-device
  (source "/dev/sda3")
  (target "home")
  (type luks-device-mapping))
@end lisp

Alternatively, to become independent of device numbering, one may obtain the
LUKS UUID (@dfn{unique identifier}) of the source device by a command like:

@example
cryptsetup luksUUID /dev/sda3
@end example

and use it as follows:

@lisp
(mapped-device
  (source (uuid "cb67fc72-0d54-4c88-9d4b-b225f30b0f44"))
  (target "home")
  (type luks-device-mapping))
@end lisp

@cindex swap encryption
It is also desirable to encrypt swap space, since swap space may contain
sensitive data.  One way to accomplish that is to use a swap file in a file
system on a device mapped via LUKS encryption.  In this way, the swap file
is encrypted because the entire device is encrypted.  @xref{Espaço de troca (swap)}, or
@xref{Preparando para instalação,,Disk Partitioning}, for an example.

A RAID device formed of the partitions @file{/dev/sda1} and @file{/dev/sdb1}
may be declared as follows:

@lisp
(mapped-device
  (source (list "/dev/sda1" "/dev/sdb1"))
  (target "/dev/md0")
  (type raid-device-mapping))
@end lisp

The @file{/dev/md0} device can then be used as the @code{device} of a
@code{file-system} declaration (@pxref{Sistemas de arquivos}).  Note that the RAID
level need not be given; it is chosen during the initial creation and
formatting of the RAID device and is determined automatically later.

LVM logical volumes ``alpha'' and ``beta'' from volume group ``vg0'' can be
declared as follows:

@lisp
(mapped-device
  (source "vg0")
  (targets (list "vg0-alpha" "vg0-beta"))
  (type lvm-device-mapping))
@end lisp

Devices @file{/dev/mapper/vg0-alpha} and @file{/dev/mapper/vg0-beta} can
then be used as the @code{device} of a @code{file-system} declaration
(@pxref{Sistemas de arquivos}).

@node Espaço de troca (swap)
@section Espaço de troca (swap)
@cindex swap space

Swap space, as it is commonly called, is a disk area specifically designated
for paging: the process in charge of memory management (the Linux kernel or
Hurd's default pager) can decide that some memory pages stored in RAM which
belong to a running program but are unused should be stored on disk
instead.  It unloads those from the RAM, freeing up precious fast memory,
and writes them to the swap space.  If the program tries to access that very
page, the memory management process loads it back into memory for the
program to use.

A common misconception about swap is that it is only useful when small
amounts of RAM are available to the system.  However, it should be noted
that kernels often use all available RAM for disk access caching to make I/O
faster, and thus paging out unused portions of program memory will expand
the RAM available for such caching.

For a more detailed description of how memory is managed from the viewpoint
of a monolithic kernel, @pxref{Memory Concepts,,, libc, The GNU C Library
Reference Manual}.

The Linux kernel has support for swap partitions and swap files: the former
uses a whole disk partition for paging, whereas the second uses a file on a
file system for that (the file system driver needs to support it).  On a
comparable setup, both have the same performance, so one should consider
ease of use when deciding between them.  Partitions are ``simpler'' and do
not need file system support, but need to be allocated at disk formatting
time (logical volumes notwithstanding), whereas files can be allocated and
deallocated at any time.

@cindex hibernation
@cindex suspend to disk
Swap space is also required to put the system into @dfn{hibernation} (also
called @dfn{suspend to disk}), whereby memory is dumped to swap before
shutdown so it can be restored when the machine is eventually restarted.
Hibernation uses at most half the size of the RAM in the configured swap
space.  The Linux kernel needs to know about the swap space to be used to
resume from hibernation on boot (@i{via} a kernel argument).  When using a
swap file, its offset in the device holding it also needs to be given to the
kernel; that value has to be updated if the file is initialized again as
swap---e.g., because its size was changed.

Note that swap space is not zeroed on shutdown, so sensitive data (such as
passwords) may linger on it if it was paged out.  As such, you should
consider having your swap reside on an encrypted device (@pxref{Dispositivos mapeados}).

@deftp {Tipo de dados} swap-space
Objects of this type represent swap spaces.  They contain the following
members:

@table @asis
@item @code{target}
The device or file to use, either a UUID, a @code{file-system-label} or a
string, as in the definition of a @code{file-system} (@pxref{Sistemas de arquivos}).

@item @code{dependencies} (padrão: @code{'()})
A list of @code{file-system} or @code{mapped-device} objects, upon which the
availability of the space depends.  Note that just like for
@code{file-system} objects, dependencies which are needed for boot and
mounted in early userspace are not managed by the Shepherd, and so
automatically filtered out for you.

@item @code{priority} (default: @code{#f})
Only supported by the Linux kernel.  Either @code{#f} to disable swap
priority, or an integer between 0 and 32767.  The kernel will first use swap
spaces of higher priority when paging, and use same priority spaces on a
round-robin basis.  The kernel will use swap spaces without a set priority
after prioritized spaces, and in the order that they appeared in (not
round-robin).

@item @code{discard?} (default: @code{#f})
Only supported by the Linux kernel.  When true, the kernel will notify the
disk controller of discarded pages, for example with the TRIM operation on
Solid State Drives.

@end table
@end deftp

Here are some examples:

@lisp
(swap-space (target (uuid "4dab5feb-d176-45de-b287-9b0a6e4c01cb")))
@end lisp

Use the swap partition with the given UUID@.  You can learn the UUID of a
Linux swap partition by running @command{swaplabel @var{device}}, where
@var{device} is the @file{/dev} file name of that partition.

@lisp
(swap-space
  (target (file-system-label "swap"))
  (dependencies mapped-devices))
@end lisp

Use the partition with label @code{swap}, which can be found after all the
@var{mapped-devices} mapped devices have been opened.  Again, the
@command{swaplabel} command allows you to view and change the label of a
Linux swap partition.

Here's a more involved example with the corresponding @code{file-systems}
part of an @code{operating-system} declaration.

@lisp
(file-systems
  (list (file-system
          (device (file-system-label "root"))
          (mount-point "/")
          (type "ext4"))
        (file-system
          (device (file-system-label "btrfs"))
          (mount-point "/btrfs")
          (type "btrfs"))))

(swap-devices
  (list
    (swap-space
      (target "/btrfs/swapfile")
      (dependencies (filter (file-system-mount-point-predicate "/btrfs")
                            file-systems)))))
@end lisp

Use the file @file{/btrfs/swapfile} as swap space, which depends on the file
system mounted at @file{/btrfs}.  Note how we use Guile's filter to select
the file system in an elegant fashion!

@lisp
(swap-devices
  (list
    (swap-space
      (target "/dev/mapper/my-swap")
      (dependencies mapped-devices))))

(kernel-arguments
  (cons* "resume=/dev/mapper/my-swap"
         %default-kernel-arguments))
@end lisp

The above snippet of an @code{operating-system} declaration enables the
mapped device @file{/dev/mapper/my-swap} (which may be part of an encrypted
device) as swap space, and tells the kernel to use it for hibernation via
the @code{resume} kernel argument (@pxref{Referência do operating-system},
@code{kernel-arguments}).

@lisp
(swap-devices
  (list
    (swap-space
      (target "/swapfile")
      (dependencies (filter (file-system-mount-point-predicate "/")
                            file-systems)))))

(kernel-arguments
  (cons* "resume=/dev/sda3"        ;device that holds /swapfile
         "resume_offset=92514304"  ;offset of /swapfile on device
         %default-kernel-arguments))
@end lisp

This other snippet of @code{operating-system} enables the swap file
@file{/swapfile} for hibernation by telling the kernel about the partition
containing it (@code{resume} argument) and its offset on that partition
(@code{resume_offset} argument).  The latter value can be found in the
output of the command @command{filefrag -e} as the first number right under
the @code{physical_offset} column header (the second command extracts its
value directly):

@smallexample
$ sudo filefrag -e /swapfile
Filesystem type is: ef53
File size of /swapfile is 2463842304 (601524 blocks of 4096 bytes)
 ext:     logical_offset:        physical_offset: length:   expected: flags:
   0:        0..    2047:   92514304..  92516351:   2048:
@dots{}
$ sudo filefrag -e /swapfile | grep '^ *0:' | cut -d: -f3 | cut -d. -f1
   92514304
@end smallexample

@node Contas de usuário
@section Contas de usuário

@cindex usuários
@cindex accounts
@cindex user accounts
User accounts and groups are entirely managed through the
@code{operating-system} declaration.  They are specified with the
@code{user-account} and @code{user-group} forms:

@lisp
(user-account
  (name "alice")
  (group "users")
  (supplementary-groups '("wheel"   ;allow use of sudo, etc.
                          "audio"   ;sound card
                          "video"   ;video devices such as webcams
                          "cdrom")) ;the good ol' CD-ROM
  (comment "Bob's sister"))
@end lisp

Here's a user account that uses a different shell and a custom home
directory (the default would be @file{"/home/bob"}):

@lisp
(user-account
  (name "bob")
  (group "users")
  (comment "Alice's bro")
  (shell (file-append zsh "/bin/zsh"))
  (home-directory "/home/robert"))
@end lisp

When booting or upon completion of @command{guix system reconfigure}, the
system ensures that only the user accounts and groups specified in the
@code{operating-system} declaration exist, and with the specified
properties.  Thus, account or group creations or modifications made by
directly invoking commands such as @command{useradd} are lost upon
reconfiguration or reboot.  This ensures that the system remains exactly as
declared.

@deftp {Tipo de dados} user-account
Objects of this type represent user accounts.  The following members may be
specified:

@table @asis
@item @code{name}
The name of the user account.

@item @code{group}
@cindex groups
This is the name (a string) or identifier (a number) of the user group this
account belongs to.

@item @code{supplementary-groups} (default: @code{'()})
Optionally, this can be defined as a list of group names that this account
belongs to.

@item @code{uid} (padrão: @code{#f})
This is the user ID for this account (a number), or @code{#f}.  In the
latter case, a number is automatically chosen by the system when the account
is created.

@item @code{comment} (default: @code{""})
A comment about the account, such as the account owner's full name.

Note that, for non-system accounts, users are free to change their real name
as it appears in @file{/etc/passwd} using the @command{chfn} command.  When
they do, their choice prevails over the system administrator's choice;
reconfiguring does @emph{not} change their name.

@item @code{home-directory}
This is the name of the home directory for the account.

@item @code{create-home-directory?} (default: @code{#t})
Indicates whether the home directory of this account should be created if it
does not exist yet.

@item @code{shell} (default: Bash)
This is a G-expression denoting the file name of a program to be used as the
shell (@pxref{Expressões-G}).  For example, you would refer to the Bash
executable like this:

@lisp
(file-append bash "/bin/bash")
@end lisp

@noindent
... and to the Zsh executable like that:

@lisp
(file-append zsh "/bin/zsh")
@end lisp

@item @code{system?} (padrão: @code{#f})
This Boolean value indicates whether the account is a ``system'' account.
System accounts are sometimes treated specially; for instance, graphical
login managers do not list them.

@anchor{user-account-password}
@cindex password, for user accounts
@item @code{password} (padrão: @code{#f})
You would normally leave this field to @code{#f}, initialize user passwords
as @code{root} with the @command{passwd} command, and then let users change
it with @command{passwd}.  Passwords set with @command{passwd} are of course
preserved across reboot and reconfiguration.

If you @emph{do} want to set an initial password for an account, then this
field must contain the encrypted password, as a string.  You can use the
@code{crypt} procedure for this purpose:

@lisp
(user-account
  (name "charlie")
  (group "users")

  ;; Specify a SHA-512-hashed initial password.
  (password (crypt "InitialPassword!" "$6$abc")))
@end lisp

@quotation 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 groups
User group declarations are even simpler:

@lisp
(user-group (name "students"))
@end lisp

@deftp {Tipo de dados} user-group
This type is for, well, user groups.  There are just a few fields:

@table @asis
@item @code{name}
The name of the group.

@item @code{id} (default: @code{#f})
The group identifier (a number).  If @code{#f}, a new number is
automatically allocated when the group is created.

@item @code{system?} (padrão: @code{#f})
This Boolean value indicates whether the group is a ``system'' group.
System groups have low numerical IDs.

@item @code{password} (padrão: @code{#f})
What, user groups can have a password? Well, apparently yes.  Unless
@code{#f}, this field specifies the password of the group.

@end table
@end deftp

For convenience, a variable lists all the basic user groups one may expect:

@defvar %base-groups
This is the list of basic user groups that users and/or packages expect to
be present on the system.  This includes groups such as ``root'', ``wheel'',
and ``users'', as well as groups used to control access to specific devices
such as ``audio'', ``disk'', and ``cdrom''.
@end defvar

@defvar %base-user-accounts
This is the list of basic system accounts that programs may expect to find
on a GNU/Linux system, such as the ``nobody'' account.

Note that the ``root'' account is not included here.  It is a special-case
and is automatically added whether or not it is specified.
@end defvar

@cindex containers, subordinate IDs
The Linux kernel also implements @dfn{subordinate user and group IDs}, or
``subids'', which are used to map the ID of a user and group to several IDs
inside separate name spaces---inside ``containers''.
@xref{subordinate-user-group-ids, the subordinate user and group ID
service}, for information on how to configure it.

@node Disposição do teclado
@section Disposição do teclado

@cindex disposição do teclado
@cindex keymap
To specify what each key of your keyboard does, you need to tell the
operating system what @dfn{keyboard layout} you want to use.  The default,
when nothing is specified, is the US English QWERTY layout for 105-key PC
keyboards.  However, German speakers will usually prefer the German QWERTZ
layout, French speakers will want the AZERTY layout, and so on; hackers
might prefer Dvorak or bépo, and they might even want to further customize
the effect of some of the keys.  This section explains how to get that done.

@cindex disposição do teclado, definição
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{Configuração do carregador de inicialização, @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{Referência do operating-system,
@code{keyboard-layout}}).

@item
The @emph{graphical display server}, usually Xorg, also has its own idea of
the keyboard layout (@pxref{X Window, @code{keyboard-layout}}).
@end itemize

Guix allows you to configure all three separately but, fortunately, it
allows you to share the same keyboard layout for all three components.

@cindex XKB, disposições do 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.

@deffn {Procedure} keyboard-layout name [variant] [#:model] [#:options '()]
Return a new keyboard layout with the given @var{name} and @var{variant}.

@var{name} must be a string such as @code{"fr"}; @var{variant} must be a
string such as @code{"bepo"} or @code{"nodeadkeys"}.  See the
@code{xkeyboard-config} package for valid options.
@end deffn

Here are a few examples:

@lisp
;; The German QWERTZ layout.  Here we assume a standard
;; "pc105" keyboard model.
(keyboard-layout "de")

;; The bépo variant of the French layout.
(keyboard-layout "fr" "bepo")

;; The Catalan layout.
(keyboard-layout "es" "cat")

;; Arabic layout with "Alt-Shift" to switch to US layout.
(keyboard-layout "ar,us" #:options '("grp:alt_shift_toggle"))

;; The Latin American Spanish layout.  In addition, the
;; "Caps Lock" key is used as an additional "Ctrl" key,
;; and the "Menu" key is used as a "Compose" key to enter
;; accented letters.
(keyboard-layout "latam"
                 #:options '("ctrl:nocaps" "compose:menu"))

;; The Russian layout for a ThinkPad keyboard.
(keyboard-layout "ru" #:model "thinkpad")

;; The "US international" layout, which is the US layout plus
;; dead keys to enter accented characters.  This is for an
;; Apple MacBook keyboard.
(keyboard-layout "us" "intl" #:model "macbook78")
@end lisp

See the @file{share/X11/xkb} directory of the @code{xkeyboard-config}
package for a complete list of supported layouts, variants, and models.

@cindex disposição do teclado, configuração
Let's say you want your system to use the Turkish keyboard layout throughout
your system---bootloader, console, and Xorg.  Here's what your system
configuration would look like:

@findex set-xorg-configuration
@lisp
;; Using the Turkish layout for the bootloader, the console,
;; and for Xorg.

(operating-system
  ;; ...
  (keyboard-layout (keyboard-layout "tr"))  ;for the console
  (bootloader (bootloader-configuration
                (bootloader grub-efi-bootloader)
                (targets '("/boot/efi"))
                (keyboard-layout keyboard-layout))) ;for GRUB
  (services (cons (set-xorg-configuration
                    (xorg-configuration             ;for Xorg
                      (keyboard-layout keyboard-layout)))
                  %desktop-services)))
@end lisp

In the example above, for GRUB and for Xorg, we just refer to the
@code{keyboard-layout} field defined above, but we could just as well refer
to a different layout.  The @code{set-xorg-configuration} procedure
communicates the desired Xorg configuration to the graphical log-in manager,
by default GDM.

We've discussed how to specify the @emph{default} keyboard layout of your
system when it starts, but you can also adjust it at run time:

@itemize
@item
If you're using GNOME, its settings panel has a ``Region & Language'' entry
where you can select one or more keyboard layouts.

@item
Under Xorg, the @command{setxkbmap} command (from the same-named package)
allows you to change the current layout.  For example, this is how you would
change the layout to US Dvorak:

@example
setxkbmap us dvorak
@end example

@item
The @code{loadkeys} command changes the keyboard layout in effect in the
Linux console.  However, note that @code{loadkeys} does @emph{not} use the
XKB keyboard layout categorization described above.  The command below loads
the French bépo layout:

@example
loadkeys fr-bepo
@end example
@end itemize

@node Localidades
@section Localidades

@cindex localidade
A @dfn{locale} defines cultural conventions for a particular language and
region of the world (@pxref{Locales,,, libc, The GNU C Library Reference
Manual}).  Each locale has a name that typically has the form
@code{@var{language}_@var{territory}.@var{codeset}}---e.g.,
@code{fr_LU.utf8} designates the locale for the French language, with
cultural conventions from Luxembourg, and using the UTF-8 encoding.

@cindex locale definition
Usually, you will want to specify the default locale for the machine using
the @code{locale} field of the @code{operating-system} declaration
(@pxref{Referência do operating-system, @code{locale}}).

The selected locale is automatically added to the @dfn{locale definitions}
known to the system if needed, with its codeset inferred from its
name---e.g., @code{bo_CN.utf8} will be assumed to use the @code{UTF-8}
codeset.  Additional locale definitions can be specified in the
@code{locale-definitions} slot of @code{operating-system}---this is useful,
for instance, if the codeset could not be inferred from the locale name.
The default set of locale definitions includes some widely used locales, but
not all the available locales, in order to save space.

For instance, to add the North Frisian locale for Germany, the value of that
field may be:

@lisp
(cons (locale-definition
        (name "fy_DE.utf8") (source "fy_DE"))
      %default-locale-definitions)
@end lisp

Likewise, to save space, one might want @code{locale-definitions} to list
only the locales that are actually used, as in:

@lisp
(list (locale-definition
        (name "ja_JP.eucjp") (source "ja_JP")
        (charset "EUC-JP")))
@end lisp

@vindex LOCPATH
The compiled locale definitions are available at
@file{/run/current-system/locale/X.Y}, where @code{X.Y} is the libc version,
which is the default location where the GNU@tie{}libc provided by Guix looks
for locale data.  This can be overridden using the @env{LOCPATH} environment
variable (@pxref{locales-and-locpath, @env{LOCPATH} and locale packages}).

The @code{locale-definition} form is provided by the @code{(gnu system
locale)} module.  Details are given below.

@deftp {Tipo de dados} locale-definition
This is the data type of a locale definition.

@table @asis

@item @code{name}
The name of the locale.  @xref{Locale Names,,, libc, The GNU C Library
Reference Manual}, for more information on locale names.

@item @code{source}
The name of the source for that locale.  This is typically the
@code{@var{language}_@var{territory}} part of the locale name.

@item @code{charset} (default: @code{"UTF-8"})
The ``character set'' or ``code set'' for that locale,
@uref{https://www.iana.org/assignments/character-sets, as defined by IANA}.

@end table
@end deftp

@defvar %default-locale-definitions
A list of commonly used UTF-8 locales, used as the default value of the
@code{locale-definitions} field of @code{operating-system} declarations.

@cindex locale name
@cindex normalized codeset in locale names
These locale definitions use the @dfn{normalized codeset} for the part that
follows the dot in the name (@pxref{Using gettextized software, normalized
codeset,, libc, The GNU C Library Reference Manual}).  So for instance it
has @code{uk_UA.utf8} but @emph{not}, say, @code{uk_UA.UTF-8}.
@end defvar

@subsection Locale Data Compatibility Considerations

@cindex incompatibility, of locale data
@code{operating-system} declarations provide a @code{locale-libcs} field to
specify the GNU@tie{}libc packages that are used to compile locale
declarations (@pxref{Referência do operating-system}).  ``Why would I care?'',
you may ask.  Well, it turns out that the binary format of locale data is
occasionally incompatible from one libc version to another.

@c See <https://sourceware.org/ml/libc-alpha/2015-09/msg00575.html>
@c and <https://lists.gnu.org/archive/html/guix-devel/2015-08/msg00737.html>.
For instance, a program linked against libc version 2.21 is unable to read
locale data produced with libc 2.22; worse, that program @emph{aborts}
instead of simply ignoring the incompatible locale data@footnote{Versions
2.23 and later of GNU@tie{}libc will simply skip the incompatible locale
data, which is already an improvement.}.  Similarly, a program linked
against libc 2.22 can read most, but not all, of the locale data from libc
2.21 (specifically, @env{LC_COLLATE} data is incompatible); thus calls to
@code{setlocale} may fail, but programs will not abort.

The ``problem'' with Guix is that users have a lot of freedom: They can
choose whether and when to upgrade software in their profiles, and might be
using a libc version different from the one the system administrator used to
build the system-wide locale data.

Fortunately, unprivileged users can also install their own locale data and
define @env{GUIX_LOCPATH} accordingly (@pxref{locales-and-locpath,
@env{GUIX_LOCPATH} and locale packages}).

Still, it is best if the system-wide locale data at
@file{/run/current-system/locale} is built for all the libc versions
actually in use on the system, so that all the programs can access it---this
is especially crucial on a multi-user system.  To do that, the administrator
can specify several libc packages in the @code{locale-libcs} field of
@code{operating-system}:

@lisp
(use-package-modules base)

(operating-system
  ;; @dots{}
  (locale-libcs (list glibc-2.21 (canonical-package glibc))))
@end lisp

This example would lead to a system containing locale definitions for both
libc 2.21 and the current version of libc in
@file{/run/current-system/locale}.


@node Serviços
@section Serviços

@cindex serviços de sistema
An important part of preparing an @code{operating-system} declaration is
listing @dfn{system services} and their configuration (@pxref{Usando o sistema de configuração}).  System services are typically daemons launched when
the system boots, or other actions needed at that time---e.g., configuring
network access.

Guix has a broad definition of ``service'' (@pxref{Composição de serviço}),
but many services are managed by the GNU@tie{}Shepherd (@pxref{Serviços 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

The above command, run as @code{root}, lists the currently defined
services.  The @command{herd doc} command shows a synopsis of the given
service and its associated actions:

@example
# herd doc nscd
Run libc's name service cache daemon (nscd).

# herd doc nscd action invalidate
invalidate: Invalidate the given cache--e.g., 'hosts' for host name lookups.
@end example

The @command{start}, @command{stop}, and @command{restart} sub-commands have
the effect you would expect.  For instance, the commands below stop the nscd
service and restart the Xorg display server:

@example
# herd stop nscd
Service nscd has been stopped.
# herd restart xorg-server
Service xorg-server has been stopped.
Service xorg-server has been started.
@end example

@cindex configuration, action for shepherd services
@cindex configuration file, of a shepherd service
For some services, @command{herd configuration} returns the name of the
service's configuration file, which can be handy to inspect its
configuration:

@example
# herd configuration sshd
/gnu/store/@dots{}-sshd_config
@end example

The following sections document the available services, starting with the
core services, that may be used in an @code{operating-system} declaration.

@menu
* Serviços básicos::         Serviços essenciais do sistema.
* Execução de trabalho agendado::  O serviço mcron.
* Rotação de log::           Archiving and deleting old logs.
* Networking Setup::         Configurando interfaces de rede.
* Serviços de Rede::         Firewall, SSH daemon, etc.
* Atualizações sem supervisão::  Atualizações automatizadas do sistema.
* X Window::                 Exibição gráfica.
* Serviços de impressão::    Suporte a impressora local e remota.
* Serviços de desktop::      Serviços de D-Bus e desktop.
* Serviços de som::          Serviços ALSA e Pulseaudio.
* File Search Services::     Ferramentas para procurar arquivos.
* Serviços de bancos de dados::  Banco de dados SQL, armazenamentos de valor 
                                   chave, etc.
* Serviços de correio::      IMAP, POP3, SMTP e tudo isso.
* Serviços de mensageria::   Serviços de mensageria.
* Serviços de telefonia::    Serviços de telefonia.
* Serviços de compartilhamento de arquivos::  Serviços de compartilhamento 
                                                de arquivos.
* Serviços de monitoramento::  Serviços de monitoramento.
* Serviços Kerberos::        Serviços Kerberos.
* Serviços LDAP::            Serviços LDAP.
* Serviços web::             Servidores Web.
* High Availability Services::  High availability services.
* Serviços de certificado::  Certificados TLS via Let's Encrypt.
* Serviços DNS::             Deamons DNS.
* VNC Services::             VNC daemons.
* Serviços VPN::             Deamons VPN.
* Sistema de arquivos de rede::  Serviços relacionados a NFS.
* Samba Services::           Serviços Samba.
* Integração Contínua::      Os serviços Cuirass e Laminar.
* Serviços de gerenciamento de energia::  Extending battery life, etc.
* Serviços de áudio::        O MPD.
* Serviços de virtualização::  Serviços de virtualização.
* Serviços de controlando versão::  Fornecendo acesso remoto a repositórios 
                                      Git.
* Serviços de jogos::        Servidores de jogos.
* Serviço de montagem PAM::  Serviço para montar volumes ao efetuar login.
* Serviços Guix::            Serviços relacionados especificamente ao Guix.
* Serviços Linux::           Serviços vinculados ao kernel Linux.
* Serviços Hurd::            Serviços específicos para um Sistema Hurd.
* Serviços diversos::        Outros serviços.
@end menu

@node Serviços básicos
@subsection Serviços básicos

The @code{(gnu services base)} module provides definitions for the basic
services that one expects from the system.  The services exported by this
module are listed below.

@defvar %base-services
This variable contains a list of basic services (@pxref{Tipos de Service e Serviços}, for more information on service objects) one would expect from
the system: a login service (mingetty) on each tty, syslogd, the libc name
service cache daemon (nscd), the udev device manager, and more.

This is the default value of the @code{services} field of
@code{operating-system} declarations.  Usually, when customizing a system,
you will want to append services to @code{%base-services}, like this:

@lisp
(append (list (service avahi-service-type)
              (service openssh-service-type))
        %base-services)
@end lisp
@end defvar

@defvar special-files-service-type
This is the service that sets up ``special files'' such as @file{/bin/sh};
an instance of it is part of @code{%base-services}.

The value associated with @code{special-files-service-type} services must be
a list of two-element lists where the first element is the ``special file''
and the second element is its target.  By default it is:

@cindex @file{/bin/sh}
@cindex @file{sh}, in @file{/bin}
@lisp
`(("/bin/sh" ,(file-append bash "/bin/sh"))
  ("/usr/bin/env" ,(file-append coreutils "/bin/env")))
@end lisp

@cindex @file{/usr/bin/env}
@cindex @file{env}, in @file{/usr/bin}
If you want to add, say, @code{/bin/bash} to your system, you can change it
to:

@lisp
`(("/bin/sh" ,(file-append bash "/bin/sh"))
  ("/usr/bin/env" ,(file-append coreutils "/bin/env"))
  ("/bin/bash" ,(file-append bash "/bin/bash")))
@end lisp

Since this is part of @code{%base-services}, you can use
@code{modify-services} to customize the set of special files (@pxref{Referência de Service, @code{modify-services}}).  But the simple way to add a special
file is @i{via} the @code{extra-special-file} procedure (see below).
@end defvar

@deffn {Procedure} extra-special-file file target
Use @var{target} as the ``special file'' @var{file}.

For example, adding the following lines to the @code{services} field of your
operating system declaration leads to a @file{/usr/bin/env} symlink:

@lisp
(extra-special-file "/usr/bin/env"
                    (file-append coreutils "/bin/env"))
@end lisp

This procedure is meant for @code{/bin/sh}, @code{/usr/bin/env} and similar
targets.  In particular, use for targets under @code{/etc} might not work as
expected if the target is managed by Guix in other ways.

The special files persist on your system even after the
@code{extra-special-file} call has been removed from your system config and
the system has been reconfigured.  The special files need to be removed
manually.
@end deffn

@defvar host-name-service-type
Type of the service that sets the system host name, whose value is a
string. This service is included in @code{operating-system} by default
(@pxref{operating-system-essential-services,@code{essential-services}}).
@end defvar

@defvar console-font-service-type
Install the given fonts on the specified ttys (fonts are per virtual console
on the kernel Linux).  The value of this service is a list of tty/font
pairs.  The font can be the name of a font provided by the @code{kbd}
package or any valid argument to @command{setfont}, as in this example:

@lisp
`(("tty1" . "LatGrkCyr-8x16")
  ("tty2" . ,(file-append
                font-tamzen
                "/share/kbd/consolefonts/TamzenForPowerline10x20.psf"))
  ("tty3" . ,(file-append
                font-terminus
                "/share/consolefonts/ter-132n"))) ; for HDPI
@end lisp
@end defvar

@defvar hosts-service-type
Type of the service that populates the entries for (@file{/etc/hosts}).
This service type can be @emph{extended} by passing it a list of @code{host}
records.

The example below shows how to add two entries to @file{/etc/hosts}:

@c TRANSLATORS: The domain names below SHOULD NOT be translated.
@c They're domains reserved for use in documentation. (RFC6761 Section 6.5)
@c The addresses used are explained in RFC3849 and RFC5737.
@lisp
(simple-service 'add-extra-hosts
                hosts-service-type
                (list (host "192.0.2.1" "example.com"
                            '("example.net" "example.org"))
                      (host "2001:db8::1" "example.com"
                            '("example.net" "example.org"))))
@end lisp

@quotation Nota
@cindex @file{/etc/hosts} default entries
By default @file{/etc/hosts} comes with the following entries:
@example
127.0.0.1 localhost @var{host-name}
::1       localhost @var{host-name}
@end example

For most setups this is what you want though if you find yourself in the
situation where you want to change the default entries, you can do so in
@code{operating-system} via @code{modify-services} (@pxref{Referência de Service,@code{modify-services}}).

The following example shows how to unset @var{host-name} from being an alias
of @code{localhost}.
@lisp
(operating-system
  ;; @dots{}

  (essential-services
   (modify-services
     (operating-system-default-essential-services this-operating-system)
     (hosts-service-type config => (list
                                     (host "127.0.0.1" "localhost")
                                     (host "::1"       "localhost"))))))
@end lisp
@end quotation
@end defvar


@deffn {Procedure} host @var{address} @var{canonical-name} [@var{aliases}]
Return a new record for the host at @var{address} with the given
@var{canonical-name} and possibly @var{aliases}.

@var{address} must be a string denoting a valid IPv4 or IPv6 address, and
@var{canonical-name} and the strings listed in @var{aliases} must be valid
host names.
@end deffn

@defvar login-service-type
Type of the service that provides a console login service, whose value is a
@code{<login-configuration>} object.
@end defvar

@deftp {Tipo de dados} login-configuration
Data type representing the configuration of login, which specifies the
@acronym{MOTD, message of the day}, among other things.

@table @asis

@item @code{motd}
@cindex message of the day
A file-like object containing the ``message of the day''.

@item @code{allow-empty-passwords?} (default: @code{#t})
Allow empty passwords by default so that first-time users can log in when
the 'root' account has just been created.

@end table
@end deftp

@defvar mingetty-service-type
Type of the service that runs Mingetty, an implementation of the virtual
console log-in.  The value for this service is a
@code{<mingetty-configuration>} object.
@end defvar

@deftp {Tipo de dados} mingetty-configuration
Data type representing the configuration of Mingetty, which specifies the
tty to run, among other things.

@table @asis
@item @code{tty}
The name of the console this Mingetty runs on---e.g., @code{"tty1"}.

@item @code{auto-login} (default: @code{#f})
When true, this field must be a string denoting the user name under which
the system automatically logs in.  When it is @code{#f}, a user name and
password must be entered to log in.

@item @code{login-program} (default: @code{#f})
This must be either @code{#f}, in which case the default log-in program is
used (@command{login} from the Shadow tool suite), or a gexp denoting the
name of the log-in program.

@item @code{login-pause?} (default: @code{#f})
When set to @code{#t} in conjunction with @var{auto-login}, the user will
have to press a key before the log-in shell is launched.

@item @code{clear-on-logout?} (default: @code{#t})
When set to @code{#t}, the screen will be cleared before showing the login
prompt.  The field name is bit unfortunate, since it controls clearing also
before the initial login, not just after a logout.

@item @code{delay} (default: @code{#f})
When set to a number, sleep that many seconds after startup.

@item @code{print-issue} (default: @code{#t})
When set to @code{#t}, write out a new line and the content of
@file{/etc/issue}.  Value of @code{'no-nl} can be used to suppress the new
line.

@item @code{print-hostname} (default: @code{#t})
When set to @code{#t}, print the host name before the login prompt.  The
host name is printed up to the first dot.  Can be set to @code{'long} to
print the full host name.

@item @code{nice} (default: @code{#f})
When set to a number, change the process priority using @code{nice}.

@item @code{working-directory} (default: @code{#f})
When set to a string, change into that directory before calling the login
program.

@item @code{root-directory} (default: @code{#f})
When set to a string, use this directory at the process's root directory.

@item @code{shepherd-requirement}
List of shepherd requirements.  Unless you know what you are doing, it is
recommended to extend the default list instead of overriding it.

As an example, when using auto-login on a system with elogind, it is
necessary to wait on the @code{'dbus-system} service:

@lisp
(modify-services %base-services
  (mingetty-service-type config =>
                         (mingetty-configuration
                          (inherit config)
                          ;; Automatically log in as "guest".
                          (auto-login "guest")
                          (shepherd-requirement
                           (cons 'dbus-system
                                 (mingetty-configuration-shepherd-requirement
                                  config))))))
@end lisp

@item @code{mingetty} (default: @var{mingetty})
The Mingetty package to use.

@end table
@end deftp

@defvar agetty-service-type
Type of the service that runs agetty, which implements virtual and serial
console log-in.  The value for this service is a
@code{<agetty-configuration>} object.
@end defvar

@deftp {Tipo de dados} agetty-configuration
Data type representing the configuration of agetty, which specifies the tty
to run, among other things@footnote{See the @code{agetty(8)} man page for
more information.}.

@table @asis
@item @code{tty}
The name of the console this agetty runs on, as a string---e.g.,
@code{"ttyS0"}.  This argument is optional, it will default to a reasonable
default serial port used by the kernel Linux.

For this, if there is a value for an option @code{agetty.tty} in the kernel
command line, agetty will extract the device name of the serial port from it
and use that.

If not and if there is a value for an option @code{console} with a tty in
the Linux command line, agetty will extract the device name of the serial
port from it and use that.

In both cases, agetty will leave the other serial device settings (baud rate
etc.)@: alone---in the hope that Linux pinned them to the correct values.

@item @code{baud-rate} (default: @code{#f})
A string containing a comma-separated list of one or more baud rates, in
descending order.

@item @code{term} (default: @code{#f})
A string containing the value used for the @env{TERM} environment variable.

@item @code{eight-bits?} (default: @code{#f})
When @code{#t}, the tty is assumed to be 8-bit clean, and parity detection
is disabled.

@item @code{auto-login} (default: @code{#f})
When passed a login name, as a string, the specified user will be logged in
automatically without prompting for their login name or password.

@item @code{no-reset?} (default: @code{#f})
When @code{#t}, don't reset terminal cflags (control modes).

@item @code{host} (default: @code{#f})
This accepts a string containing the ``login_host'', which will be written
into the @file{/var/run/utmpx} file.

@item @code{remote?} (padrão: @code{#f})
When set to @code{#t} in conjunction with @var{host}, this will add an
@code{-r} fakehost option to the command line of the login program specified
in @var{login-program}.

@item @code{flow-control?} (default: @code{#f})
When set to @code{#t}, enable hardware (RTS/CTS) flow control.

@item @code{no-issue?} (padrão: @code{#f})
When set to @code{#t}, the contents of the @file{/etc/issue} file will not
be displayed before presenting the login prompt.

@item @code{init-string} (default: @code{#f})
This accepts a string that will be sent to the tty or modem before sending
anything else.  It can be used to initialize a modem.

@item @code{no-clear?} (padrão: @code{#f})
When set to @code{#t}, agetty will not clear the screen before showing the
login prompt.

@item @code{login-program} (default: (file-append shadow "/bin/login"))
This must be either a gexp denoting the name of a log-in program, or unset,
in which case the default value is the @command{login} from the Shadow tool
suite.

@item @code{local-line} (default: @code{#f})
Control the CLOCAL line flag.  This accepts one of three symbols as
arguments, @code{'auto}, @code{'always}, or @code{'never}.  If @code{#f},
the default value chosen by agetty is @code{'auto}.

@item @code{extract-baud?} (default: @code{#f})
When set to @code{#t}, instruct agetty to try to extract the baud rate from
the status messages produced by certain types of modems.

@item @code{skip-login?} (default: @code{#f})
When set to @code{#t}, do not prompt the user for a login name.  This can be
used with @var{login-program} field to use non-standard login systems.

@item @code{no-newline?} (padrão: @code{#f})
When set to @code{#t}, do not print a newline before printing the
@file{/etc/issue} file.

@c Is this dangerous only when used with login-program, or always?
@item @code{login-options} (default: @code{#f})
This option accepts a string containing options that are passed to the login
program.  When used with the @var{login-program}, be aware that a malicious
user could try to enter a login name containing embedded options that could
be parsed by the login program.

@item @code{login-pause} (default: @code{#f})
When set to @code{#t}, wait for any key before showing the login prompt.
This can be used in conjunction with @var{auto-login} to save memory by
lazily spawning shells.

@item @code{chroot} (default: @code{#f})
Change root to the specified directory.  This option accepts a directory
path as a string.

@item @code{hangup?} (padrão: @code{#f})
Use the Linux system call @code{vhangup} to do a virtual hangup of the
specified terminal.

@item @code{keep-baud?} (default: @code{#f})
When set to @code{#t}, try to keep the existing baud rate.  The baud rates
from @var{baud-rate} are used when agetty receives a @key{BREAK} character.

@item @code{timeout} (default: @code{#f})
When set to an integer value, terminate if no user name could be read within
@var{timeout} seconds.

@item @code{detect-case?} (default: @code{#f})
When set to @code{#t}, turn on support for detecting an uppercase-only
terminal.  This setting will detect a login name containing only uppercase
letters as indicating an uppercase-only terminal and turn on some
upper-to-lower case conversions.  Note that this will not support Unicode
characters.

@item @code{wait-cr?} (default: @code{#f})
When set to @code{#t}, wait for the user or modem to send a carriage-return
or linefeed character before displaying @file{/etc/issue} or login prompt.
This is typically used with the @var{init-string} option.

@item @code{no-hints?} (padrão: @code{#f})
When set to @code{#t}, do not print hints about Num, Caps, and Scroll locks.

@item @code{no-hostname?} (default: @code{#f})
By default, the hostname is printed.  When this option is set to @code{#t},
no hostname will be shown at all.

@item @code{long-hostname?} (default: @code{#f})
By default, the hostname is only printed until the first dot.  When this
option is set to @code{#t}, the fully qualified hostname by
@code{gethostname} or @code{getaddrinfo} is shown.

@item @code{erase-characters} (default: @code{#f})
This option accepts a string of additional characters that should be
interpreted as backspace when the user types their login name.

@item @code{kill-characters} (default: @code{#f})
This option accepts a string that should be interpreted to mean ``ignore all
previous characters'' (also called a ``kill'' character) when the user types
their login name.

@item @code{chdir} (default: @code{#f})
This option accepts, as a string, a directory path that will be changed to
before login.

@item @code{delay} (default: @code{#f})
This options accepts, as an integer, the number of seconds to sleep before
opening the tty and displaying the login prompt.

@item @code{nice} (default: @code{#f})
This option accepts, as an integer, the nice value with which to run the
@command{login} program.

@item @code{extra-options} (default: @code{'()})
This option provides an ``escape hatch'' for the user to provide arbitrary
command-line arguments to @command{agetty} as a list of strings.

@item @code{shepherd-requirement} (default: @code{'()})
The option can be used to provides extra shepherd requirements (for example
@code{'syslogd}) to the respective @code{'term-}* shepherd service.

@end table
@end deftp

@defvar kmscon-service-type
Type of the service that runs
@uref{https://www.freedesktop.org/wiki/Software/kmscon,kmscon}, which
implements virtual console log-in.  The value for this service is a
@code{<kmscon-configuration>} object.
@end defvar

@deftp {Tipo de dados} kmscon-configuration
Data type representing the configuration of Kmscon, which specifies the tty
to run, among other things.

@table @asis
@item @code{virtual-terminal}
The name of the console this Kmscon runs on---e.g., @code{"tty1"}.

@item @code{login-program} (default: @code{#~(string-append #$shadow "/bin/login")})
A gexp denoting the name of the log-in program.  The default log-in program
is @command{login} from the Shadow tool suite.

@item @code{login-arguments} (default: @code{'("-p")})
A list of arguments to pass to @command{login}.

@item @code{auto-login} (default: @code{#f})
When passed a login name, as a string, the specified user will be logged in
automatically without prompting for their login name or password.

@item @code{hardware-acceleration?} (default: #f)
Whether to use hardware acceleration.

@item @code{font-engine} (default: @code{"pango"})
Font engine used in Kmscon.

@item @code{font-size} (default: @code{12})
Font size used in Kmscon.

@item @code{keyboard-layout} (padrão: @code{#f})
If this is @code{#f}, Kmscon uses the default keyboard layout---usually US
English (``qwerty'') for a 105-key PC keyboard.

Otherwise this must be a @code{keyboard-layout} object specifying the
keyboard layout.  @xref{Disposição do teclado}, for more information on how to
specify the keyboard layout.

@item @code{kmscon} (default: @var{kmscon})
The Kmscon package to use.

@end table
@end deftp

@cindex @abbr{nscd, name service cache daemon}
@defvar nscd-service-type
Type of the service that runs the libc @abbr{nscd, name service cache
daemon}, whose value is an @code{<nscd-configuration>} object.

For convenience, the Shepherd service for nscd provides the following
actions:

@table @code
@item invalidate
@cindex nscd, cache invalidation
@cindex cache invalidation, nscd
This invalidate the given cache.  For instance, running:

@example
herd invalidate nscd hosts
@end example

@noindent
invalidates the host name lookup cache of nscd.

@item statistics
Running @command{herd statistics nscd} displays information about nscd usage
and caches.
@end table
@end defvar

@deftp {Tipo de dados} nscd-configuration
Data type representing the @abbr{nscd, name service cache daemon}
configuration.

@table @asis

@item @code{name-services} (default: @code{'()})
List of packages denoting @dfn{name services} that must be visible to the
nscd---e.g., @code{(list @var{nss-mdns})}.

@item @code{glibc} (default: @var{glibc})
Package object denoting the GNU C Library providing the @command{nscd}
command.

@item @code{log-file} (default: @code{#f})
Name of the nscd log file.  Debugging output goes to that file when
@code{debug-level} is strictly positive, or to standard error if it is
@code{#f}.  Regular messages are written to syslog when @code{debug-level}
is zero, regardless of the value of @code{log-file}.

@item @code{debug-level} (default: @code{0})
Integer denoting the debugging levels.  Higher numbers mean that more
debugging output is logged.

@item @code{caches} (default: @code{%nscd-default-caches})
List of @code{<nscd-cache>} objects denoting things to be cached; see below.

@end table
@end deftp

@deftp {Tipo de dados} nscd-cache
Data type representing a cache database of nscd and its parameters.

@table @asis

@item @code{database}
This is a symbol representing the name of the database to be cached.  Valid
values are @code{passwd}, @code{group}, @code{hosts}, and @code{services},
which designate the corresponding NSS database (@pxref{NSS Basics,,, libc,
The GNU C Library Reference Manual}).

@item @code{positive-time-to-live}
@itemx @code{negative-time-to-live} (default: @code{20})
A number representing the number of seconds during which a positive or
negative lookup result remains in cache.

@item @code{check-files?} (default: @code{#t})
Whether to check for updates of the files corresponding to @var{database}.

For instance, when @var{database} is @code{hosts}, setting this flag
instructs nscd to check for updates in @file{/etc/hosts} and to take them
into account.

@item @code{persistent?} (padrão: @code{#t})
Whether the cache should be stored persistently on disk.

@item @code{shared?} (padrão: @code{#t})
Whether the cache should be shared among users.

@item @code{max-database-size} (default: 32@tie{}MiB)
Maximum size in bytes of the database cache.

@c XXX: 'suggested-size' and 'auto-propagate?' seem to be expert
@c settings, so leave them out.

@end table
@end deftp

@defvar %nscd-default-caches
List of @code{<nscd-cache>} objects used by default by
@code{nscd-configuration} (see above).

It enables persistent and aggressive caching of service and host name
lookups.  The latter provides better host name lookup performance,
resilience in the face of unreliable name servers, and also better
privacy---often the result of host name lookups is in local cache, so
external name servers do not even need to be queried.
@end defvar

@cindex syslog, with external syslogd
@cindex logging, syslog
@defvar syslog-service-type
Type of the service that runs the syslog daemon (@command{syslogd}), whose
value is a @code{<syslog-configuration>} object (see below).

@quotation Nota
This service is redundant with and for the most part superseded by
@code{shepherd-system-log-service-type} (@pxref{shepherd-system-log, the
Shepherd system log}).
@end quotation
@end defvar

To have a modified @code{syslog-configuration} come into effect after
reconfiguring your system, the @samp{reload} action should be preferred to
restarting the service, as many services such as the login manager depend on
it and would be restarted as well:

@example
# herd reload syslog
@end example

which will cause the running @command{syslogd} process to reload its
configuration.

@deftp {Tipo de dados} syslog-configuration
Data type representing the configuration of the syslog daemon.

@table @asis
@item @code{syslogd} (default: @code{#~(string-append #$inetutils "/libexec/syslogd")})
The syslog daemon to use.

@item @code{config-file} (default: @code{%default-syslog.conf})
The syslog configuration file to use.  @xref{syslogd invocation,,,
inetutils, GNU Inetutils}, for more information on the configuration file
syntax.

@item @code{extra-options} (default: @code{'()})
List of extra command-line options for @command{syslog}.

@end table
@end deftp

@defvar guix-service-type
This is the type of the service that runs the build daemon,
@command{guix-daemon} (@pxref{Invocando guix-daemon}).  Its value must be a
@code{guix-configuration} record as described below.
@end defvar

@anchor{guix-configuration-type}
@deftp {Tipo de dados} guix-configuration
This data type represents the configuration of the Guix build daemon.
@xref{Invocando guix-daemon}, for more information.

@table @asis
@item @code{guix} (default: @var{guix})
The Guix package to use.  @xref{Customizing the System-Wide Guix} to learn
how to provide a package with a pre-configured set of channels.

@cindex unprivileged @command{guix-daemon}
@cindex rootless @command{guix-daemon}
@item @code{privileged?} (default: @code{#t})
Whether to run @command{guix-daemon} as root.

When true, @command{guix-daemon} runs with root privileges and build
processes run under unprivileged user accounts as specified by
@code{build-group} and @code{build-accounts} (see below); when false,
@command{guix-daemon} run as the @code{guix-daemon} user, which is
unprivileged, and so do build processes.  The unprivileged or ``rootless''
mode can reduce the impact of some classes of vulnerabilities that could
affect the daemon.

The default is currently @code{#t} (@command{guix-daemon} runs with root
privileges) but may eventually be changed to @code{#f}.

@quotation Aviso
When changing this option, @file{/gnu/store}, @file{/var/guix}, and
@file{/etc/guix} have their ownership automatically changed by the
@code{guix-ownership} service to either the @code{guix-daemon} user or the
@code{root} user (@pxref{unprivileged-daemon-migration}).

This can take a while, especially if @file{/gnu/store} is big; it cannot be
interrupted and @command{guix-daemon} cannot be used until it has completed.
@end quotation

@xref{Configuração do ambiente de compilação}, for more information on the two ways to run
@command{guix-daemon}.

@item @code{build-group} (default: @code{"guixbuild"})
Name of the group for build user accounts.

@item @code{build-accounts} (default: @code{10})
Number of build user accounts to create.

@item @code{chroot?} (default: @code{'default})
The value should be one of @code{#t} or @code{#f}, in which case chroot is
enabled or disabled, respectively; or it should be @code{'default}, which
amounts to @code{#f} in Docker containers (so that they can be run in
non-privileged mode)  or @code{#t} otherwise.

@item @code{authorize-key?} (default: @code{#t})
@cindex substitutos, autenticação dela
Whether to authorize the substitute keys listed in
@code{authorized-keys}---by default that of
@code{@value{SUBSTITUTE-SERVER-1}} and @code{@value{SUBSTITUTE-SERVER-2}}
(@pxref{Substitutos}).

When @code{authorize-key?} is true, @file{/etc/guix/acl} cannot be changed
by invoking @command{guix archive --authorize}.  You must instead adjust
@code{guix-configuration} as you wish and reconfigure the system.  This
ensures that your operating system configuration file is self-contained.

@quotation Nota
When booting or reconfiguring to a system where @code{authorize-key?} is
true, the existing @file{/etc/guix/acl} file is backed up as
@file{/etc/guix/acl.bak} if it was determined to be a manually modified
file.  This is to facilitate migration from earlier versions, which allowed
for in-place modifications to @file{/etc/guix/acl}.
@end quotation

@vindex %default-authorized-guix-keys
@item @code{authorized-keys} (default: @code{%default-authorized-guix-keys})
The list of authorized key files for archive imports, as a list of
string-valued gexps (@pxref{Invocando guix archive}).  By default, it
contains that of @code{@value{SUBSTITUTE-SERVER-1}} and
@code{@value{SUBSTITUTE-SERVER-2}} (@pxref{Substitutos}).  See
@code{substitute-urls} below for an example on how to change it.

@item @code{use-substitutes?} (default: @code{#t})
Whether to use substitutes.

@item @code{substitute-urls} (default: @code{%default-substitute-urls})
The list of URLs where to look for substitutes by default.

Suppose you would like to fetch substitutes from @code{guix.example.org} in
addition to @code{@value{SUBSTITUTE-SERVER-1}}.  You will need to do two
things: (1) add @code{guix.example.org} to @code{substitute-urls}, and (2)
authorize its signing key, having done appropriate checks (@pxref{Autorização de servidor substituto}).  The configuration below does exactly that:

@lisp
(guix-configuration
  (substitute-urls
   (append (list "https://guix.example.org")
           %default-substitute-urls))
  (authorized-keys
   (append (list (local-file "./guix.example.org-key.pub"))
           %default-authorized-guix-keys)))
@end lisp

This example assumes that the file @file{./guix.example.org-key.pub}
contains the public key that @code{guix.example.org} uses to sign
substitutes.

@item @code{generate-substitute-key?} (default: @code{#t})
Whether to generate a @dfn{substitute key pair} under
@file{/etc/guix/signing-key.pub} and @file{/etc/guix/signing-key.sec} if
there is not already one.

This key pair is used when exporting store items, for instance with
@command{guix publish} (@pxref{Invocando guix publish}) or @command{guix
archive} (@pxref{Invocando guix archive}).  Generating a key pair takes a few
seconds when enough entropy is available and is only done once; you might
want to turn it off for instance in a virtual machine that does not need it
and where the extra boot time is a problem.

@anchor{guix-configuration-channels}
@item @code{channels} (default: @code{#f})
List of channels to be specified in @file{/etc/guix/channels.scm}, which is
what @command{guix pull} uses by default (@pxref{Invocando guix pull}).

@quotation Nota
When reconfiguring a system, the existing @file{/etc/guix/channels.scm} file
is backed up as @file{/etc/guix/channels.scm.bak} if it was determined to be
a manually modified file.  This is to facilitate migration from earlier
versions, which allowed for in-place modifications to
@file{/etc/guix/channels.scm}.
@end quotation

@item @code{max-silent-time} (default: @code{3600})
@itemx @code{timeout} (default: @code{(* 3600 24)})
The number of seconds of silence and the number of seconds of activity,
respectively, after which a build process times out.  A value of zero
disables the timeout.

@item @code{log-compression} (default: @code{'gzip})
The type of compression used for build logs---one of @code{gzip},
@code{bzip2}, or @code{none}.

@item @code{discover?} (default: @code{#f})
Se deve descobrir servidores substitutos na rede local usando mDNS e DNS-SD.

@anchor{guix-configuration-build-machines}
@item @code{build-machines} (default: @code{#f})
This field must be either @code{#f} or a list of gexps evaluating to a
@code{build-machine} record or to a list of @code{build-machine} records
(@pxref{Configuração de descarregamento de daemon}).

When it is @code{#f}, the @file{/etc/guix/machines.scm} file is left
untouched.  Otherwise, the list of of gexps is written to
@file{/etc/guix/machines.scm}; if a previously-existing file is found, it is
backed up as @file{/etc/guix/machines.scm.bak}.  This allows you to declare
build machines for offloading directly in the operating system declaration,
like so:

@lisp
(guix-configuration
  (build-machines
    (list #~(build-machine (name "foo.example.org") @dots{})
          #~(build-machine (name "bar.example.org") @dots{}))))
@end lisp

Additional build machines may be added @i{via} the @code{guix-extension}
mechanism (see below).

@item @code{extra-options} (default: @code{'()})
List of extra command-line options for @command{guix-daemon}.

@item @code{log-file} (default: @code{"/var/log/guix-daemon.log"})
File where @command{guix-daemon}'s standard output and standard error are
written.

@cindex HTTP proxy, for @code{guix-daemon}
@cindex proxy, for @code{guix-daemon} HTTP access
@item @code{http-proxy} (default: @code{#f})
The URL of the HTTP and HTTPS proxy used for downloading fixed-output
derivations and substitutes.

It is also possible to change the daemon's proxy at run time through the
@code{set-http-proxy} action, which restarts it:

@example
herd set-http-proxy guix-daemon http://localhost:8118
@end example

To clear the proxy settings, run:

@example
herd set-http-proxy guix-daemon
@end example

@item @code{tmpdir} (default: @code{#f})
A directory path where the @command{guix-daemon} will perform builds.

@item @code{environment} (default: @code{'()})
Environment variables to be set before starting the daemon, as a list of
@code{key=value} strings.

@item @code{socket-directory-permissions} (default: @code{#o755})
Permissions to set for the directory @file{/var/guix/daemon-socket}.  This,
together with @code{socket-directory-group} and
@code{socket-directory-user}, determines who can connect to the build daemon
via its Unix socket.  TCP socket operation is unaffected by these.

@item @code{socket-directory-user} (default: @code{#f})
@itemx @code{socket-directory-group} (default: @code{#f})
User and group owning the @file{/var/guix/daemon-socket} directory or
@code{#f} to keep the user or group as root.

@end table
@end deftp

@deftp {Tipo de dados} guix-extension
This data type represents the parameters of the Guix build daemon that are
extendable. This is the type of the object that must be used within a guix
service extension.  @xref{Composição de serviço}, for more information.

@table @asis
@item @code{authorized-keys} (default: @code{'()})
A list of file-like objects where each element contains a public key.

@item @code{substitute-urls} (default: @code{'()})
A list of strings where each element is a substitute URL.

@item @code{build-machines} (default: @code{'()})
A list of gexps that evaluate to @code{build-machine} records or to a list
of @code{build-machine} records.  (@pxref{Configuração de descarregamento de daemon}).

Using this field, a service may add new build machines to receive builds
offloaded by the daemon.  This is useful for a service such as
@code{hurd-vm-service-type}, which can make a GNU/Hurd virtual machine
directly usable for offloading (@pxref{hurd-vm,
@code{hurd-vm-service-type}}).

@item @code{chroot-directories} (default: @code{'()})
A list of file-like objects or strings pointing to additional directories
the build daemon can use.
@end table
@end deftp

@defvar udev-service-type
Type of the service that runs udev, a service which populates the
@file{/dev} directory dynamically, whose value is a
@code{<udev-configuration>} object.

Since the file names for udev rules and hardware description files matter,
the configuration items for rules and hardware cannot simply be plain
file-like objects with the rules content, because the name would be
ignored.  Instead, they are directory file-like objects that contain
optional rules in @file{lib/udev/rules.d} and optional hardware files in
@file{lib/udev/hwdb.d}.  This way, the service can be configured with whole
packages from which to take rules and hwdb files.

The @code{udev-service-type} can be @emph{extended} with file-like
directories that respect this hierarchy.  For convenience, the
@code{udev-rule} and @code{file->udev-rule} can be used to construct udev
rules, while @code{udev-hardware} and @code{file->udev-hardware} can be used
to construct hardware description files.

In an @code{operating-system} declaration, this service type can be
@emph{extended} using procedures @code{udev-rules-service} and
@code{udev-hardware-service}.
@end defvar

@deftp {Tipo de dados} udev-configuration
Data type representing the configuration of udev.

@table @code
@item udev (default: @code{eudev}) (type: file-like)
Package object of the udev service.  This package is used at run-time, when
compiled for the target system.  In order to generate the @file{hwdb.bin}
hardware index, it is also used when generating the system definition,
compiled for the current system.

@item debug? (default: @code{#f}) (type: boolean)
Whether to enable debug output.  The debug output is written to the system
log, @file{/var/log/messages}.

@item rules (default: @code{'()}) (type: list-of-file-like)
List of file-like objects denoting udev rule files under a sub-directory.

@item hardware (default: @code{'()}) (type: list-of-file-like)
List of file-like objects denoting udev hardware description files under a
sub-directory.

@end table
@end deftp

@deffn {Procedure} udev-rule @var{file-name} @var{contents}
Return a udev-rule file named @var{file-name} containing the rules defined
by the @var{contents} literal.

In the following example, a rule for a USB device is defined to be stored in
the file @file{90-usb-thing.rules}.  The rule runs a script upon detecting a
USB device with a given product identifier.

@lisp
(define %example-udev-rule
  (udev-rule
    "90-usb-thing.rules"
    (string-append "ACTION==\"add\", SUBSYSTEM==\"usb\", "
                   "ATTR@{product@}==\"Example\", "
                   "RUN+=\"/path/to/script\"")))
@end lisp
@end deffn

@deffn {Procedure} udev-hardware @var{file-name} @var{contents}
Return a udev hardware description file named @var{file-name} containing the
hardware information @var{contents}.
@end deffn

@deffn {Procedure} udev-rules-service @var{name} @var{rules} [#:groups '()]
Return a service that extends @code{udev-service-type} with @var{rules} and
@code{account-service-type} with @var{groups} as system groups.  This works
by creating a singleton service type @code{@var{name}-udev-rules}, of which
the returned service is an instance.

Here we show how it can be used to extend @code{udev-service-type} with the
previously defined rule @code{%example-udev-rule}.

@lisp
(operating-system
 ;; @dots{}
 (services
   (cons (udev-rules-service 'usb-thing %example-udev-rule)
         %desktop-services)))
@end lisp
@end deffn

@deffn {Procedure} udev-hardware-service @var{name} @var{hardware}
Return a service that extends @code{udev-service-type} with @var{hardware}.
The service name is @code{@var{name}-udev-hardware}.
@end deffn

@deffn {Procedure} file->udev-rule @var{file-name} @var{file}
Return a udev-rule file named @var{file-name} containing the rules defined
within @var{file}, a file-like object.

The following example showcases how we can use an existing rule file.

@lisp
(use-modules (guix download)     ;for url-fetch
             (guix packages)     ;for origin
             @dots{})

(define %android-udev-rules
  (file->udev-rule
    "51-android-udev.rules"
    (let ((version "20170910"))
      (origin
       (method url-fetch)
       (uri (string-append "https://raw.githubusercontent.com/M0Rf30/"
                           "android-udev-rules/" version "/51-android.rules"))
       (sha256
        (base32 "0lmmagpyb6xsq6zcr2w1cyx9qmjqmajkvrdbhjx32gqf1d9is003"))))))
@end lisp
@end deffn

Since guix package definitions can be included in @var{rules} in order to
use all their rules under the @file{lib/udev/rules.d} sub-directory, then in
lieu of the previous @var{file->udev-rule} example, we could have used the
@var{android-udev-rules} package which exists in Guix in the @code{(gnu
packages android)} module.

@deffn {Procedure} file->udev-hardware @var{file-name} @var{file}
Return a udev hardware description file named @var{file-name} containing the
rules defined within @var{file}, a file-like object.
@end deffn

The following example shows how to use the @var{android-udev-rules} package
so that the Android tool @command{adb} can detect devices without root
privileges.  It also details how to create the @code{adbusers} group, which
is required for the proper functioning of the rules defined within the
@code{android-udev-rules} package.  To create such a group, we must define
it both as part of the @code{supplementary-groups} of our
@code{user-account} declaration, as well as in the @var{groups} of the
@code{udev-rules-service} procedure.

@lisp
(use-modules (gnu packages android)  ;for android-udev-rules
             (gnu system shadow)     ;for user-group
             @dots{})

(operating-system
  ;; @dots{}
  (users (cons (user-account
                ;; @dots{}
                (supplementary-groups
                 '("adbusers"   ;for adb
                   "wheel" "netdev" "audio" "video")))))
  ;; @dots{}
  (services
    (cons (udev-rules-service 'android android-udev-rules
                              #:groups '("adbusers"))
          %desktop-services)))
@end lisp

@defvar urandom-seed-service-type
Save some entropy in @code{%random-seed-file} to seed @file{/dev/urandom}
when rebooting.  It also tries to seed @file{/dev/urandom} from
@file{/dev/hwrng} while booting, if @file{/dev/hwrng} exists and is
readable.
@end defvar

@defvar %random-seed-file
This is the name of the file where some random bytes are saved by
@var{urandom-seed-service} to seed @file{/dev/urandom} when rebooting.  It
defaults to @file{/var/lib/random-seed}.
@end defvar

@cindex mouse
@cindex gpm
@defvar gpm-service-type
This is the type of the service that runs GPM, the @dfn{general-purpose
mouse daemon}, which provides mouse support to the Linux console.  GPM
allows users to use the mouse in the console, notably to select, copy, and
paste text.

The value for services of this type must be a @code{gpm-configuration} (see
below).  This service is not part of @code{%base-services}.
@end defvar

@deftp {Tipo de dados} gpm-configuration
Data type representing the configuration of GPM.

@table @asis
@item @code{options} (default: @code{%default-gpm-options})
Command-line options passed to @command{gpm}.  The default set of options
instruct @command{gpm} to listen to mouse events on @file{/dev/input/mice}.
@xref{Command Line,,, gpm, gpm manual}, for more information.

@item @code{gpm} (default: @code{gpm})
O pacote GPM a ser usado.

@end table
@end deftp

@anchor{guix-publish-service-type}
@defvar guix-publish-service-type
This is the service type for @command{guix publish} (@pxref{Invocando guix publish}).  Its value must be a @code{guix-publish-configuration} object, as
described below.

This assumes that @file{/etc/guix} already contains a signing key pair as
created by @command{guix archive --generate-key} (@pxref{Invocando guix archive}).  If that is not the case, the service will fail to start.
@end defvar

@deftp {Tipo de dados} guix-publish-configuration
Data type representing the configuration of the @code{guix publish} service.

@table @asis
@item @code{guix} (default: @code{guix})
The Guix package to use.

@item @code{port} (padrão: @code{80})
The TCP port to listen for connections.

@item @code{host} (default: @code{"localhost"})
The host (and thus, network interface) to listen to.  Use @code{"0.0.0.0"}
to listen on all the network interfaces.

@item @code{advertise?} (default: @code{#f})
When true, advertise the service on the local network @i{via} the DNS-SD
protocol, using Avahi.

This allows neighboring Guix devices with discovery on (see
@code{guix-configuration} above) to discover this @command{guix publish}
instance and to automatically download substitutes from it.

@item @code{compression} (default: @code{'(("gzip" 3) ("zstd" 3))})
This is a list of compression method/level tuple used when compressing
substitutes.  For example, to compress all substitutes with @emph{both} lzip
at level 7 and gzip at level 9, write:

@lisp
'(("lzip" 7) ("gzip" 9))
@end lisp

Level 9 achieves the best compression ratio at the expense of increased CPU
usage, whereas level 1 achieves fast compression.  @xref{Invocando guix publish}, for more information on the available compression methods and the
tradeoffs involved.

An empty list disables compression altogether.

@item @code{nar-path} (default: @code{"nar"})
The URL path at which ``nars'' can be fetched.  @xref{Invocando guix publish,
@option{--nar-path}}, for details.

@item @code{cache} (default: @code{#f})
When it is @code{#f}, disable caching and instead generate archives on
demand.  Otherwise, this should be the name of a directory---e.g.,
@code{"/var/cache/guix/publish"}---where @command{guix publish} caches
archives and meta-data ready to be sent.  @xref{Invocando guix publish,
@option{--cache}}, for more information on the tradeoffs involved.

@item @code{workers} (default: @code{#f})
When it is an integer, this is the number of worker threads used for
caching; when @code{#f}, the number of processors is used.  @xref{Invocando guix publish, @option{--workers}}, for more information.

@item @code{cache-bypass-threshold} (default: 10 MiB)
When @code{cache} is true, this is the maximum size in bytes of a store item
for which @command{guix publish} may bypass its cache in case of a cache
miss.  @xref{Invocando guix publish, @option{--cache-bypass-threshold}}, for
more information.

@item @code{ttl} (default: @code{#f})
When it is an integer, this denotes the @dfn{time-to-live} in seconds of the
published archives.  @xref{Invocando guix publish, @option{--ttl}}, for more
information.

@item @code{negative-ttl} (default: @code{#f})
When it is an integer, this denotes the @dfn{time-to-live} in seconds for
the negative lookups.  @xref{Invocando guix publish,
@option{--negative-ttl}}, for more information.
@end table
@end deftp

@defvar rngd-service-type
Type of the service that runs rng-tools rngd, whose value is an
@code{<rngd-configuration>} object.
@end defvar

@deftp {Tipo de dados} rngd-configuration
Data type representing the configuration of rngd.

@table @asis
@item @code{rng-tools} (default: @code{rng-tools}) (type: file-like)
Package object of the rng-tools rngd.

@item @code{device} (default: @var{"/dev/hwrng"}) (type: string)
Path of the device to add to the kernel's entropy pool.  The service will
fail if @var{device} does not exist.

@end table
@end deftp

@cindex session limits
@cindex ulimit
@cindex priority
@cindex realtime
@cindex jackd
@cindex nofile
@cindex open file descriptors
@anchor{pam-limits-service-type}
@defvar pam-limits-service-type
Type of the service that installs a configuration file for the
@uref{http://linux-pam.org/Linux-PAM-html/sag-pam_limits.html,
@code{pam_limits} module}.  The value for this service type is a list of
@code{pam-limits-entry} values, which can be used to specify @code{ulimit}
limits and @code{nice} priority limits to user sessions.  By default, the
value is the empty list.

The following limits definition sets two hard and soft limits for all login
sessions of users in the @code{realtime} group:

@lisp
(service pam-limits-service-type
         (list
          (pam-limits-entry "@@realtime" 'both 'rtprio 99)
          (pam-limits-entry "@@realtime" 'both 'memlock 'unlimited)))
@end lisp

The first entry increases the maximum realtime priority for non-privileged
processes; the second entry lifts any restriction of the maximum address
space that can be locked in memory.  These settings are commonly used for
real-time audio systems.

Another useful example is raising the maximum number of open file
descriptors that can be used:

@lisp
(service pam-limits-service-type
         (list
          (pam-limits-entry "*" 'both 'nofile 100000)))
@end lisp

In the above example, the asterisk means the limit should apply to any
user.  It is important to ensure the chosen value doesn't exceed the maximum
system value visible in the @file{/proc/sys/fs/file-max} file, else the
users would be prevented from login in.  For more information about the
Pluggable Authentication Module (PAM) limits, refer to the @samp{pam_limits}
man page from the @code{linux-pam} package.
@end defvar

@defvar greetd-service-type
@uref{https://git.sr.ht/~kennylevinsen/greetd, @code{greetd}} is a minimal
and flexible login manager daemon, that makes no assumptions about what you
want to launch.

If you can run it from your shell in a TTY, greetd can start it. If it can
be taught to speak a simple JSON-based IPC protocol, then it can be a
geeter.

@code{greetd-service-type} provides necessary infrastructure for logging in
users, including:

@itemize @bullet
@item
@code{greetd} PAM service

@item
Special variation of @code{pam-mount} to mount @code{XDG_RUNTIME_DIR}
@end itemize

Here is an example of switching from @code{mingetty-service-type} to
@code{greetd-service-type}, and how different terminals could be:

@lisp
  (append
   (modify-services %base-services
     ;; greetd-service-type provides "greetd" PAM service
     (delete login-service-type)
     ;; and can be used in place of mingetty-service-type
     (delete mingetty-service-type))
   (list
    (service greetd-service-type
             (greetd-configuration
              (terminals
               (list
                ;; we can make any terminal active by default
                (greetd-terminal-configuration (terminal-vt "1") (terminal-switch #t))
                ;; we can make environment without XDG_RUNTIME_DIR set
                ;; even provide our own environment variables
                (greetd-terminal-configuration
                 (terminal-vt "2")
                 (default-session-command
                   (greetd-agreety-session
                    (command
                     (greetd-user-session
                      (extra-env '(("MY_VAR" . "1")))
                      (xdg-env? #f))))))
                ;; we can use different shell instead of default bash
                (greetd-terminal-configuration
                 (terminal-vt "3")
                 (default-session-command
                   (greetd-agreety-session
                    (command
                     (greetd-user-session
                      (command (file-append zsh "/bin/zsh"))
                      (command-args '("-l"))
                      (extra-env '(("MY_VAR" . "1")))
                      (xdg-env? #f))))))
                ;; we can use any other executable command as greeter
                (greetd-terminal-configuration
                 (terminal-vt "4")
                 (default-session-command (program-file "my-noop-greeter" #~(exit))))
                (greetd-terminal-configuration (terminal-vt "5"))
                (greetd-terminal-configuration (terminal-vt "6"))))))
    ;; mingetty-service-type can be used in parallel
    ;; if needed to do so, do not (delete login-service-type)
    ;; as illustrated above
    #| (service mingetty-service-type (mingetty-configuration (tty "tty8"))) |#))
@end lisp
@end defvar

@deftp {Tipo de dados} greetd-configuration
Configuration record for the @code{greetd-service-type}.
@table @asis

@item @code{motd}
A file-like object containing the ``message of the day''.

@item @code{allow-empty-passwords?} (default: @code{#t})
Allow empty passwords by default so that first-time users can log in when
the 'root' account has just been created.

@item @code{terminals} (default: @code{'()})
List of @code{greetd-terminal-configuration} per terminal for which
@code{greetd} should be started.

@item @code{greeter-supplementary-groups} (default: @code{'()})
List of groups which should be added to @code{greeter} user. For instance:
@lisp
(greeter-supplementary-groups '("seat" "video"))
@end lisp
Note that this example will fail if @code{seat} group does not exist.
@end table
@end deftp

@deftp {Tipo de dados} greetd-terminal-configuration
Configuration record for per terminal greetd daemon service.

@table @asis
@item @code{greetd} (default: @code{greetd})
The greetd package to use.

@item @code{extra-shepherd-requirement} (default: @code{'()})
This option can be used to provide a list of @emph{additional} symbols
naming Shepherd services that this service will depend on, such as
@code{'seatd} or @code{'elogind} when the terminal session is a graphical
greeter.

@item @code{config-file-name}
Configuration file name to use for greetd daemon. Generally, autogenerated
derivation based on @code{terminal-vt} value.

@item @code{log-file-name}
Log file name to use for greetd daemon. Generally, autogenerated name based
on @code{terminal-vt} value.

@item @code{terminal-vt} (default: @samp{"7"})
The VT to run on. Use of a specific VT with appropriate conflict avoidance
is recommended.

@item @code{terminal-switch} (default: @code{#f})
Make this terminal active on start of @code{greetd}.

@item @code{source-profile?} (default: @code{#t})
Whether to source @file{/etc/profile} and @file{~/.profile}, when they
exist.

@item @code{initial-session-user} (default: @samp{#f})
The user to use for running the initial session, if any.

@item @code{initial-session-command} (default: @code{#f})
The command to run the first time the greeter starts up, to auto-login.  For
that to be useful, you should also set @code{initial-session-user}.  Then,
greetd will automatically log in with that user and execute that command.
When you eventually log out again, the regular greeter will appear.

@item @code{default-session-user} (default: @samp{"greeter"})
The user to use for running the greeter.

@item @code{default-session-command} (default: @code{(greetd-agreety-session)})
Can be either @code{greetd-agreety-session},
@code{greetd-wlgreet-sway-session}, @code{greetd-gtkgreet-sway-session} or a
file-like object to use as greeter.

@end table
@end deftp

@deftp {Data Type} greetd-user-session
Configuration record for the user session command.  Greeters require the
user command to be specified in some or another way.
@code{greetd-user-session} provides a common command for that.  Users should
prefer POSIX shell commands like @command{bash}, which can start an actual
user terminal shell, window manager or desktop environment with their own
mechanism, for example via @file{~/.bashrc} in the case of Bash.

@table @asis
@item @code{command} (default: @code{(file-append bash "/bin/bash")})
Command to be started by @command{agreety} on successful login.

@item @code{command-args} (default: @code{'("-l")})
Command arguments to pass to command.

@item @code{extra-env} (default: @code{'()})
Extra environment variables to set on login.

@item @code{xdg-session-type} (default: @code{"tty"})
Specify the value of @code{XDG_SESSION_TYPE}.  The user environment may
adapt depending on its value (normally by using @file{.bashrc} or similar).

@item @code{xdg-env?} (default: @code{#t})
If true @code{XDG_RUNTIME_DIR} and @code{XDG_SESSION_TYPE} will be set
before starting command.  One should note that, @code{extra-env} variables
are set right after mentioned variables, so that they can be overridden.

@end table
@end deftp

@deftp {Tipo de dados} greetd-agreety-session
Configuration record for the agreety greetd greeter.

@table @asis
@item @code{agreety} (default: @code{greetd})
The package providing the @command{agreety} command.

@item @code{command} (default: @code{(greetd-user-session)})
Command to be started by @command{agreety} on successful login, an instance
of @code{greetd-user-session}.

@end table
@end deftp

@deftp {Data Type} greetd-wlgreet-configuration
Generic configuration record for the wlgreet greetd greeter.

@table @asis
@item @code{output-mode} (default: @code{"all"})
Option to use for @code{outputMode} in the TOML configuration file.

@item @code{scale} (default: @code{1})
Option to use for @code{scale} in the TOML configuration file.

@item @code{background} (default: @code{'(0 0 0 0.9)})
RGBA list to use as the background colour of the login prompt.

@item @code{headline} (default: @code{'(1 1 1 1)})
RGBA list to use as the headline colour of the UI popup.

@item @code{prompt} (default: @code{'(1 1 1 1)})
RGBA list to use as the prompt colour of the UI popup.

@item @code{prompt-error} (default: @code{'(1 1 1 1)})
RGBA list to use as the error colour of the UI popup.

@item @code{border} (default: @code{'(1 1 1 1)})
RGBA list to use as the border colour of the UI popup.

@end table
@end deftp

@deftp {Tipo de dados} greetd-wlgreet-sway-session
Sway-specific configuration record for the wlgreet greetd greeter.

@table @asis
@item @code{wlgreet-session} (default: @code{(greetd-wlgreet-session)})
A @code{greetd-wlgreet-session} record for generic wlgreet configuration, on
top of the Sway-specific @code{greetd-wlgreet-sway-session}.

@item @code{sway} (default: @code{sway})
The package providing the @command{sway} command.

@item @code{sway-configuration} (default: #f)
File-like object providing an additional Sway configuration file to be
prepended to the mandatory part of the configuration.

@item @code{wlgreet} (default: @code{wlgreet})
The package providing the @command{wlgreet} command.

@item @code{wlgreet-configuration} (default: @code{(greetd-wlgreet-configuration)})
Configuration of @code{wlgreet} represented by
@code{greetd-wlgreet-configuration}.

@item @code{command} (default: @code{(greetd-user-session)})
Command to be started by @command{wlgreet} on successful login, an instance
of @code{greetd-user-session}.

@end table

Here is an example of a greetd configuration that uses wlgreet and Sway:

@lisp
  (greetd-configuration
   ;; The graphical greeter requires additional group membership.
   (greeter-supplementary-groups (list "video" "input" "seat"))
   (terminals
    (list (greetd-terminal-configuration
           ;; Sway requires seatd service.
           (extra-shepherd-requirement '(seatd))
           (terminal-vt "1")
           (terminal-switch #t)
           (default-session-command
            (greetd-wlgreet-sway-session
             (sway-configuration
              ;; Optional extra sway configuration.
              (local-file "sway-greetd.conf"))))))))
@end lisp
@end deftp

@deftp {Data Type} greetd-gtkgreet-sway-session
Configuration record for the gtkgreet greetd greeter.  It can be used as
follows:

@lisp
  (greetd-configuration
   ;; The graphical greeter requires additional groups membership.
   (greeter-supplementary-groups (list "video" "input" "seat"))
   (terminals
    (list (greetd-terminal-configuration
           ;; Sway requires the seatd service.
           (extra-shepherd-requirement '(seatd))
           (terminal-vt "1")
           (terminal-switch #t)
           (default-session-command
            (greetd-gtkgreet-sway-session
             (command
              (greetd-user-session
               ;; Optionally signal to .bashrc that we want the Wayland
               ;; compositor.
               (xdg-session-type "wayland")))))))))
@end lisp

@table @asis
@item @code{sway} (default: @code{sway})
The package providing the @command{sway} and @command{swaymsg} commands.

@item @code{sway-configuration} (default: @code{#f})
Extra file-like configuration for sway to be included before executing the
greeter.

@item @code{gtkgreet} (default: @code{gtkgreet})
The package providing the @command{gtkgreet} command.

@item @code{gtkgreet-style} (default: @code{#f})
Extra file-like CSS stylesheet to customize the GTK look.

@item @code{command} (default: @code{(greetd-user-session)})
The command to be started by @command{gtkgreet} on successful login, an
instance of @code{greetd-user-session}.

@end table
@end deftp

@node Execução de trabalho agendado
@subsection Execução de trabalho agendado

@cindex cron
@cindex scheduling jobs
It is often useful to have system tasks run periodically.  This can be
achieved by defining Shepherd @dfn{timers} or by using the historical and
somewhat less flexible mcron service.

@subsubsection Shepherd Timers

@cindex timers, Shepherd
@cindex Shepherd timers
The Shepherd supports running jobs periodically by defining @dfn{timers}, a
special kind of service.  A Shepherd timer can be defined like another
Shepherd service, but with specific @code{start} and @code{stop} methods
(@pxref{Serviços de Shepherd}):

@lisp
;; Defining a timer, verbosely.
(shepherd-service
 (provision '(updatedb))
 (requirement '(user-processes))
 (modules '((shepherd service timer)))
 (start #~(make-timer-constructor
           ;; Everyday at 3AM (using Vixie cron syntax).
           (cron-string->calendar-event "0 3 * * *")
           (command '(#$(file-append findutils "/bin/updatedb")))
           #:wait-for-termination? #t))
 (stop #~(make-timer-destructor))
 (documentation "Periodically run 'updatedb'.")
 (actions (list shepherd-trigger-action)))
@end lisp

This is quite some boilerplate so you can instead use this equivalent
shorthand notation:

@lisp
;; Equivalent timer definition, but shorter.
(shepherd-timer '(updatedb) "0 3 * * *"
                #~(#$(file-append findutils "/bin/updatedb"))
                #:requirement '(user-processes))
@end lisp

This procedure is defined as follows.

@anchor{shepherd-timer-procedure}
@deffn {Procedure} shepherd-timer @var{provision} @var{schedule} @
         @var{command} [#:requirement '()] @ [#:documentation
%default-timer-documentation] Return a Shepherd service with the given
@var{provision} periodically running @var{command}, a list-valued gexp,
according to @var{schedule}, a string in Vixie cron syntax or a gexp
providing a Shepherd calendar event.  @var{documentation} is the string that
appears when running @code{herd doc @var{service}}.
@end deffn

The example below shows how to define a timer and to add it to your
operating system configuration.

@lisp
(use-modules (gnu))
(use-service-modules shepherd)
(use-package-modules base)

(define updatedb-timer
  ;; Run 'updatedb' at 3AM everyday.
  (shepherd-timer '(updatedb)
                  "0 3 * * *"  ;Vixie cron syntax
                  #~(#$(file-append findutils "/bin/updatedb")
                     "--prunepaths=/tmp /var/tmp /gnu/store")
                  #:requirement '(user-processes)))

(define garbage-collection-timer
  ;; Run 'guix gc' everyday at 5AM.
  (shepherd-timer '(garbage-collection)
                  #~(calendar-event #:hours '(5) #:minutes '(0))
                  #~("/run/current-system/profile/bin/guix"
                     "gc" "-F" "10G")
                  #:requirement '(guix-daemon)))

(operating-system
  ;; @dots{}

  ;; Extend the Shepherd service with additional timers
  ;; using 'simple-service'.
  (services (cons (simple-service 'my-timers
                                   shepherd-root-service-type
                                   (list garbage-collection-timer
                                         updatedb-timer))
                  %base-services)))
@end lisp

The resulting system contains these two services, which can be inspected
with @command{herd status}.  They can also be triggered manually:

@example
herd trigger garbage-collection
@end example

@xref{Timers,,, shepherd, The GNU Shepherd Manual} for more information on
Shepherd timers.

@anchor{mcron-service}
@subsubsection Mcron

@cindex mcron
Alternatively, 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.  It is overall less convenient than Shepherd timers:
individual jobs cannot depend on specific Shepherd services, logging is
coarse-grain (one file for all the jobs), jobs may not be inspected,
updated, or triggered manually.

@quotation Nota
For the reasons given above, we recommend using Shepherd timers rather than
mcron for your periodic tasks.
@end quotation

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{Invocando 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{Expressões-G}).

@lisp
(use-modules (guix) (gnu) (gnu services mcron))
(use-package-modules base idutils)

(define updatedb-job
  ;; Run 'updatedb' at 3AM every day.  Here we write the
  ;; job's action as a Scheme procedure.
  #~(job '(next-hour '(3))
         (lambda ()
           (system* (string-append #$findutils "/bin/updatedb")
                    "--prunepaths=/tmp /var/tmp /gnu/store"))
         "updatedb"))

(define garbage-collector-job
  ;; Collect garbage 5 minutes after midnight every day.
  ;; The job's action is a shell command.
  #~(job "5 0 * * *"            ;Vixie cron syntax
         "guix gc -F 1G"))

(define idutils-job
  ;; Update the index database as user "charlie" at 12:15PM
  ;; and 19:15PM.  This runs from the user's home directory.
  #~(job '(next-minute-from (next-hour '(12 19)) '(15))
         (string-append #$idutils "/bin/mkid src")
         #:user "charlie"))

(operating-system
  ;; @dots{}

  ;; %BASE-SERVICES already includes an instance of
  ;; 'mcron-service-type', which we extend with additional
  ;; jobs using 'simple-service'.
  (services (cons (simple-service 'my-cron-jobs
                                   mcron-service-type
                                   (list garbage-collector-job
                                         updatedb-job
                                         idutils-job))
                  %base-services)))
@end lisp

@quotation Dica
When providing the action of a job specification as a procedure, you should
provide an explicit name for the job via the optional 3rd argument as done
in the @code{updatedb-job} example above.  Otherwise, the job would appear
as ``Lambda function'' in the output of @command{herd schedule mcron}, which
is not nearly descriptive enough!
@end quotation

@quotation Dica
Avoid calling the Guile procedures @code{execl}, @code{execle} or
@code{execlp} inside a job specification, else mcron won't be able to output
the completion status of the job.
@end quotation

For more complex jobs defined in Scheme where you need control over the top
level, for instance to introduce a @code{use-modules} form, you can move
your code to a separate program using the @code{program-file} procedure of
the @code{(guix gexp)} module (@pxref{Expressões-G}).  The example below
illustrates that.

@lisp
(define %battery-alert-job
  ;; Beep when the battery percentage falls below %MIN-LEVEL.
  #~(job
     '(next-minute (range 0 60 1))
     #$(program-file
        "battery-alert.scm"
        (with-imported-modules (source-module-closure
                                '((guix build utils)))
          #~(begin
              (use-modules (guix build utils)
                           (ice-9 popen)
                           (ice-9 regex)
                           (ice-9 textual-ports)
                           (srfi srfi-2))

              (define %min-level 20)

              (setenv "LC_ALL" "C")     ;ensure English output
              (and-let* ((input-pipe (open-pipe*
                                      OPEN_READ
                                      #$(file-append acpi "/bin/acpi")))
                         (output (get-string-all input-pipe))
                         (m (string-match "Discharging, ([0-9]+)%" output))
                         (level (string->number (match:substring m 1)))
                         ((< level %min-level)))
                (format #t "warning: Battery level is low (~a%)~%" level)
                (invoke #$(file-append beep "/bin/beep") "-r5")))))))
@end lisp

@xref{Guile Syntax, mcron job specifications,, mcron, GNU@tie{}mcron}, for
more information on mcron job specifications.  Below is the reference of the
mcron service.

On a running system, you can use the @code{schedule} action of the service
to visualize the mcron jobs that will be executed next:

@example
# herd schedule mcron
@end example

@noindent
The example above lists the next five tasks that will be executed, but you
can also specify the number of tasks to display:

@example
# herd schedule mcron 10
@end example

@defvar mcron-service-type
This is the type of the @code{mcron} service, whose value is an
@code{mcron-configuration} object.

This service type can be the target of a service extension that provides
additional job specifications (@pxref{Composição de serviço}).  In other
words, it is possible to define services that provide additional mcron jobs
to run.
@end defvar

@c Generated via (generate-documentation) at the bottom of (gnu services
@c mcron).
@c %start of fragment
@deftp {Tipo de dados} mcron-configuration
Available @code{mcron-configuration} fields are:

@table @asis
@item @code{mcron} (default: @code{mcron}) (type: file-like)
The mcron package to use.

@item @code{jobs} (default: @code{'()}) (type: list-of-gexps)
This is a list of gexps (@pxref{Expressões-G}), where each gexp corresponds
to an mcron job specification (@pxref{Syntax, mcron job specifications,,
mcron,GNU@tie{}mcron}).

@item @code{log?} (default: @code{#t}) (type: boolean)
Log messages to standard output.

@item @code{log-file} (default: @code{"/var/log/mcron.log"}) (type: string)
Log file location.

@item @code{log-format} (default: @code{"~1@@*~a ~a: ~a~%"}) (type: string)
@code{(ice-9 format)} format string for log messages.  The default value
produces messages like @samp{@var{pid} @var{name}: @var{message}}
(@pxref{Invoking mcron, Invoking,, mcron,GNU@tie{}mcron}).  Each message is
also prefixed by a timestamp by GNU Shepherd.

@item @code{date-format} (type: maybe-string)
@code{(srfi srfi-19)} format string for date.

@end table
@end deftp
@c %end of fragment

@node Rotação de log
@subsection Rotação de log

@cindex log rotation
@cindex logging
Log files such as those found in @file{/var/log} tend to grow endlessly, so
it's a good idea to @dfn{rotate} them once in a while---i.e., archive their
contents in separate files, possibly compressed.  The @code{(gnu services
admin)} module provides an interface to the log rotation service provided by
the Shepherd (@pxref{Log Rotation Service,,, shepherd, The GNU Shepherd
Manual}).

This log rotation service is made available through
@code{log-rotation-service-type}, which takes a
@code{log-rotation-configuration} record as its value.  By default, this
provides @code{log-rotation}, a Shepherd ``timed service'' that runs
periodically---once a week by default.  It automatically knows about the log
files produced by Shepherd services and can be taught about external log
files.  You can inspect the service and see when it's going to run the usual
way:

@example
$ sudo herd status log-rotation
Status of log-rotation:
  It is running since Mon 09 Dec 2024 03:27:47 PM CET (2 days ago).
  @dots{}

Upcoming timer alarms:
  Sun 15 Dec 2024 10:00:00 PM CET (in 4 days)
  Sun 22 Dec 2024 10:00:00 PM CET (in 11 days)
  Sun 29 Dec 2024 10:00:00 PM CET (in 18 days)
@end example

You can also list files subject to rotation with @command{herd files
log-rotation} and trigger rotation manually with @command{herd trigger
log-rotation}.

This service is part of @code{%base-services}, and thus enabled by default,
with the default settings.

@defvar log-rotation-service-type
This is the type of the log rotation service.  Its associated value must be
a @code{log-rotation-configuration} record, as discussed below.
@end defvar

@c %start of fragment
@anchor{log-rotation-configuration}

@deftp {Data Type} log-rotation-configuration
Available @code{log-rotation-configuration} fields are:

@table @asis
@item @code{provision} (default: @code{(log-rotation)}) (type: list-of-symbols)
The name(s) of the log rotation Shepherd service.

@item @code{requirement} (default: @code{(user-processes)}) (type: list-of-symbols)
Dependencies of the log rotation Shepherd service.

@item @code{calendar-event} (type: gexp)
Gexp containing the @dfn{calendar event} when log rotation occurs.
@xref{Timers,,,shepherd,The GNU Shepherd Manual}, for more information on
calendar events.

@item @code{external-log-files} (default: @code{()}) (type: list-of-strings)
List of file names, external log files that should also be rotated.

@item @code{compression} (default: @code{zstd}) (type: gexp-or-symbol)
The compression method used for rotated log files, one of @code{'none},
@code{'gzip}, and @code{'zstd}.  Alternatively, it can be a gexp that
evaluates to a procedure; that procedure gets called with the file to be
rotated.

@item @code{expiry} (type: gexp-or-integer)
Age in seconds after which a log file is deleted.

@item @code{size-threshold} (type: gexp-or-integer)
Size in bytes below which a log file is @emph{not} rotated.

@end table

@end deftp


@c %end of fragment

Some log files just need to be deleted periodically once they are old,
without any other criterion and without any archival step.  This is the case
of build logs stored by @command{guix-daemon} under
@file{/var/log/guix/drvs} (@pxref{Invocando guix-daemon}).  The
@code{log-cleanup} service addresses this use case.  For example,
@code{%base-services} (@pxref{Serviços básicos}) includes the following:

@lisp
;; Periodically delete old build logs.
(service log-cleanup-service-type
         (log-cleanup-configuration
          (directory "/var/log/guix/drvs")))
@end lisp

That ensures build logs do not accumulate endlessly.

@defvar log-cleanup-service-type
This is the type of the service to delete old logs.  Its value must be a
@code{log-cleanup-configuration} record as described below.
@end defvar

@deftp {Tipo de dados} log-cleanup-configuration
Data type representing the log cleanup configuration

@table @asis
@item @code{directory}
Name of the directory containing log files.

@item @code{expiry} (default: @code{(* 6 30 24 3600)})
Age in seconds after which a file is subject to deletion (six months by
default).

@item @code{schedule} (default: @code{"30 12 01,08,15,22 * *"})
Schedule of the log cleanup job written either as a string in traditional
cron syntax or as a gexp representing a Shepherd calendar event
(@pxref{Timers,,, shepherd, The GNU Shepherd Manual}).
@end table
@end deftp

@cindex logging, anonymization
@subheading Anonip Service

Anonip is a privacy filter that removes IP address from web server logs.
This service creates a FIFO and filters any written lines with anonip before
writing the filtered log to a target file.

The following example sets up the FIFO
@file{/var/run/anonip/https.access.log} and writes the filtered log file
@file{/var/log/anonip/https.access.log}.

@lisp
(service anonip-service-type
         (anonip-configuration
           (input  "/var/run/anonip/https.access.log")
           (output "/var/log/anonip/https.access.log")))
@end lisp

Configure your web server to write its logs to the FIFO at
@file{/var/run/anonip/https.access.log} and collect the anonymized log file
at @file{/var/web-logs/https.access.log}.

@deftp {Tipo de dados} anonip-configuration
Este tipo de dado representa a configuração do anonip. Ele possui os
seguintes parâmetros:

@table @asis
@item @code{anonip} (default: @code{anonip})
The anonip package to use.

@item @code{input}
The file name of the input log file to process.  The service creates a FIFO
of this name.  The web server should write its logs to this FIFO.

@item @code{output}
The file name of the processed log file.  This file is subject to log
rotation @i{via} the Shepherd's log rotation service (@pxref{Rotação de log}).
@end table

The following optional settings may be provided:

@table @code
@item debug?
Print debug messages when @code{#true}.

@item skip-private?
When @code{#true} do not mask addresses in private ranges.

@item column
A 1-based indexed column number.  Assume IP address is in the specified
column (default is 1).

@item replacement
Replacement string in case address parsing fails, e.g. @code{"0.0.0.0"}.

@item ipv4mask
Number of bits to mask in IPv4 addresses.

@item ipv6mask
Number of bits to mask in IPv6 addresses.

@item increment
Increment the IP address by the given number.  By default this is zero.

@item delimiter
Log delimiter string.

@item regex
Regular expression for detecting IP addresses.  Use this instead of
@code{column}.
@end table
@end deftp


@node Networking Setup
@subsection Networking Setup

The @code{(gnu services networking)} module provides services to configure
network interfaces and set up networking on your machine.  Those services
provide different ways for you to set up your machine: by declaring a static
network configuration, by running a Dynamic Host Configuration Protocol
(DHCP) client, or by running daemons such as NetworkManager and Connman that
automate the whole process, automatically adapt to connectivity changes, and
provide a high-level user interface.

On a laptop, NetworkManager and Connman are by far the most convenient
options, which is why the default desktop services include NetworkManager
(@pxref{Serviços de desktop, @code{%desktop-services}}).  For a server, or for
a virtual machine or a container, static network configuration or a simple
DHCP client are often more appropriate.

This section describes the various network setup services available,
starting with static network configuration.

@defvar static-networking-service-type
This is the type for statically-configured network interfaces.  Its value
must be a list of @code{static-networking} records.  Each of them declares a
set of @dfn{addresses}, @dfn{routes}, and @dfn{links}, as shown below.

@cindex network interface controller (NIC)
@cindex NIC, networking interface controller
Here is the simplest configuration, with only one network interface
controller (NIC) and only IPv4 connectivity:

@lisp
;; Static networking for one NIC, IPv4-only.
(service static-networking-service-type
         (list (static-networking
                (addresses
                 (list (network-address
                        (device "eno1")
                        (value "10.0.2.15/24"))))
                (routes
                 (list (network-route
                        (destination "default")
                        (gateway "10.0.2.2"))))
                (name-servers '("10.0.2.3")))))
@end lisp

The snippet above can be added to the @code{services} field of your
operating system configuration (@pxref{Usando o sistema de configuração}).  It
will configure your machine to have 10.0.2.15 as its IP address, with a
24-bit netmask for the local network---meaning that any 10.0.2.@var{x}
address is on the local area network (LAN).  Traffic to addresses outside
the local network is routed @i{via} 10.0.2.2.  Host names are resolved by
sending domain name system (DNS) queries to 10.0.2.3.
@end defvar

@deftp {Tipo de dados} static-networking
This is the data type representing a static network configuration.

As an example, here is how you would declare the configuration of a machine
with a single network interface controller (NIC) available as @code{eno1},
and with one IPv4 and one IPv6 address:

@lisp
;; Network configuration for one NIC, IPv4 + IPv6.
(static-networking
 (addresses (list (network-address
                   (device "eno1")
                   (value "10.0.2.15/24"))
                  (network-address
                   (device "eno1")
                   (value "2001:123:4567:101::1/64"))))
 (routes (list (network-route
                (destination "default")
                (gateway "10.0.2.2"))
               (network-route
                (destination "default")
                (gateway "2020:321:4567:42::1"))))
 (name-servers '("10.0.2.3")))
@end lisp

If you are familiar with the @command{ip} command of the
@uref{https://wiki.linuxfoundation.org/networking/iproute2, @code{iproute2}
package} found on Linux-based systems, the declaration above is equivalent
to typing:

@example
ip address add 10.0.2.15/24 dev eno1
ip address add 2001:123:4567:101::1/64 dev eno1
ip route add default via inet 10.0.2.2
ip route add default via inet6 2020:321:4567:42::1
@end example

Run @command{man 8 ip} for more info.  Venerable GNU/Linux users will
certainly know how to do it with @command{ifconfig} and @command{route}, but
we'll spare you that.

The available fields of this data type are as follows:

@table @asis
@item @code{addresses}
@itemx @code{links} (default: @code{'()})
@itemx @code{routes} (default: @code{'()})
The list of @code{network-address}, @code{network-link}, and
@code{network-route} records for this network (see below).

@item @code{name-servers} (default: @code{'()})
The list of IP addresses (strings) of domain name servers.  These IP
addresses go to @file{/etc/resolv.conf}.

@item @code{provision} (default: @code{'(networking)})
If true, this should be a list of symbols for the Shepherd service
corresponding to this network configuration.

@item @code{requirement} (default @code{'()})
The list of Shepherd services depended on.
@end table
@end deftp

@deftp {Tipo de dados} network-address
This is the data type representing the IP address of a network interface.

@table @code
@item device
The name of the network interface for this address---e.g., @code{"eno1"}.

@item value
The actual IP address and network mask, in
@uref{https://en.wikipedia.org/wiki/CIDR#CIDR_notation, @acronym{CIDR,
Classless Inter-Domain Routing} notation}, as a string.

For example, @code{"10.0.2.15/24"} denotes IPv4 address 10.0.2.15 on a
24-bit sub-network---all 10.0.2.@var{x} addresses are on the same local
network.

@item ipv6?
Whether @code{value} denotes an IPv6 address.  By default this is
automatically determined.
@end table
@end deftp

@deftp {Tipo de dados} network-route
This is the data type representing a network route.

@table @asis
@item @code{destination}
The route destination (a string), either an IP address and network mask or
@code{"default"} to denote the default route.

@item @code{source} (default: @code{#f})
The route source.

@item @code{device} (default: @code{#f})
The device used for this route---e.g., @code{"eno2"}.

@item @code{ipv6?} (default: auto)
Whether this is an IPv6 route.  By default this is automatically determined
based on @code{destination} or @code{gateway}.

@item @code{gateway} (default: @code{#f})
IP address (a string) through which traffic is routed.
@end table
@end deftp

@deftp {Tipo de dados} network-link
Data type for a network link (@pxref{Link,,, guile-netlink, Guile-Netlink
Manual}).  During startup, network links are employed to construct or modify
existing or virtual ethernet links.  These ethernet links can be identified
by their @var{name} or @var{mac-address}.  If there is a need to create
virtual interface, @var{name} and @var{type} fields are required.

@table @code
@item name
The name of the link---e.g., @code{"v0p0"} (default: @code{#f}).

@item tipo
A symbol denoting the type of the link---e.g., @code{'veth} (default:
@code{#f}).

@item mac-address
The mac-address of the link---e.g., @code{"98:11:22:33:44:55"} (default:
@code{#f}).

@item arguments
List of arguments for this type of link.
@end table
@end deftp

Consider a scenario where a server equipped with a network interface which
has multiple ports.  These ports are connected to a switch, which supports
@uref{https://en.wikipedia.org/wiki/Link_aggregation, link aggregation}
(also known as bonding or NIC teaming).  The switch uses port channels to
consolidate multiple physical interfaces into one logical interface to
provide higher bandwidth, load balancing, and link redundancy.  When a port
is added to a LAG (or link aggregation group), it inherits the properties of
the port-channel.  Some of these properties are VLAN membership, trunk
status, and so on.

@uref{https://en.wikipedia.org/wiki/Virtual_LAN, VLAN} (or virtual local
area network) is a logical network that is isolated from other VLANs on the
same physical network.  This can be used to segregate traffic, improve
security, and simplify network management.

With all that in mind let's configure our static network for the server.  We
will bond two existing interfaces together using 802.3ad schema and on top
of it, build a VLAN interface with id 1055.  We assign a static ip to our
new VLAN interface.

@lisp
(static-networking
 (links (list (network-link
               (name "bond0")
               (type 'bond)
               (arguments '((mode . "802.3ad")
                            (miimon . 100)
                            (lacp-active . "on")
                            (lacp-rate . "fast"))))

              (network-link
               (mac-address "98:11:22:33:44:55")
               (arguments '((master . "bond0"))))

              (network-link
               (mac-address "98:11:22:33:44:56")
               (arguments '((master . "bond0"))))

              (network-link
               (name "bond0.1055")
               (type 'vlan)
               (arguments '((id . 1055)
                            (link . "bond0"))))))
 (addresses (list (network-address
                   (value "192.168.1.4/24")
                   (device "bond0.1055")))))
@end lisp

@cindex loopback device
@defvar %loopback-static-networking
This is the @code{static-networking} record representing the ``loopback
device'', @code{lo}, for IP addresses 127.0.0.1 and ::1, and providing the
@code{loopback} Shepherd service.
@end defvar

@cindex networking, with QEMU
@cindex QEMU, networking
@defvar %qemu-static-networking
This is the @code{static-networking} record representing network setup when
using QEMU's user-mode network stack on @code{eth0} (@pxref{Using the user
mode network stack,,, qemu, QEMU Documentation}).
@end defvar

@cindex DHCP, networking service
@defvar dhcp-client-service-type
This is the type of services that run @var{dhclient}, the ISC Dynamic Host
Configuration Protocol (DHCP) client.
@end defvar

@deftp {Tipo de dados} dhcp-client-configuration
Data type representing the configuration of the ISC DHCP client service.

@table @asis
@item @code{package} (default: @code{isc-dhcp})
The ISC DHCP client package to use.

@item @code{interfaces} (default: @code{'all})
Either @code{'all} or the list of interface names that the ISC DHCP client
should listen on---e.g., @code{'("eno1")}.

When set to @code{'all}, the ISC DHCP client listens on all the available
non-loopback interfaces that can be activated.  Otherwise the ISC DHCP
client listens only on the specified interfaces.

@item @code{config-file} (default: @code{#f})
The configuration file for the ISC DHCP client.

@item @code{version} (default: @code{"4"})
The DHCP protocol version to use, as a string.  Accepted values are
@code{"4"} or @code{"6"} for DHCPv4 or DHCPv6, respectively, as well as
@code{"4o6"}, for DHCPv4 over DHCPv6 (as specified by RFC 7341).

@item @code{shepherd-requirement} (default: @code{'()})
@itemx @code{shepherd-provision} (default: @code{'(networking)})
This option can be used to provide a list of symbols naming Shepherd
services that this service will depend on, such as @code{'wpa-supplicant} or
@code{'iwd} if you require authenticated access for encrypted WiFi or
Ethernet networks.

Likewise, @code{shepherd-provision} is a list of Shepherd service names
(symbols) provided by this service.  You might want to change the default
value if you intend to run several ISC DHCP clients, only one of which
provides the @code{networking} Shepherd service.
@end table
@end deftp

@cindex DHCPCD, networking service

@defvar dhcpcd-service-type
This the type for a service running @command{dhcpcd}, a @acronym{DHCP,
Dynamic Host Configuration Protocol} client that can be used as a
replacement for the historical ISC client supported by
@code{dhcp-client-service-type}.

Its value must be a @code{dhcpcd-configuration} record, as described below.
As an example, consider the following setup which runs @command{dhcpcd} with
a local @acronym{DNS, Domain Name System} resolver:

@lisp
(service dhcpcd-service-type
  (dhcpcd-configuration
    (option '("rapid_commit" "interface_mtu"))
    (no-option '("nd_rdnss"
                 "dhcp6_name_servers"
                 "domain_name_servers"
                 "domain_name"
                 "domain_search"))
    (static '("domain_name_servers=127.0.0.1"))
    (no-hook '("hostname"))))
@end lisp
@end defvar


@c %start of fragment

@deftp {Data Type} dhcpcd-configuration
Available @code{dhcpcd-configuration} fields are:

@table @asis
@item @code{interfaces} (default: @code{()}) (type: list)
List of networking interfaces---e.g., @code{"eth0"}---to start a DHCP client
for.  If no interface is specified (i.e., the list is empty) then
@command{dhcpcd} discovers available Ethernet interfaces, that can be
configured, automatically.

@item @code{command-arguments} (default: @code{("-q" "-q")}) (type: list)
List of additional command-line options.

@item @code{host-name} (default: @code{""}) (type: maybe-string)
Host name to send via DHCP, defaults to the current system host name.

@item @code{duid} (default: @code{""}) (type: maybe-string)
DHCPv4 clients require a unique client identifier, this option uses the
DHCPv6 Unique Identifier as a DHCPv4 client identifier as well.  For more
information, refer to @uref{https://www.rfc-editor.org/rfc/rfc4361,RFC 4361}
and @code{dhcpcd.conf(5)}.

@item @code{persistent?} (default: @code{#t}) (type: boolean)
When true, automatically de-configure the interface when @command{dhcpcd}
exits.

@item @code{option} (default: @code{("rapid_commit" "domain_name_servers" "domain_name" "domain_search" "host_name" "classless_static_routes" "interface_mtu")}) (type: list-of-strings)
List of options to request from the server.

@item @code{require} (default: @code{("dhcp_server_identifier")}) (type: list-of-strings)
List of options to require in responses.

@item @code{slaac} (default: @code{"private"}) (type: maybe-string)
Interface identifier used for SLAAC generated IPv6 addresses.

@item @code{no-option} (default: @code{()}) (type: list-of-strings)
List of options to remove from the message before it's processed.

@item @code{no-hook} (default: @code{()}) (type: list-of-strings)
List of hook script which should not be invoked.

@item @code{static} (default: @code{()}) (type: list-of-strings)
DHCP client can request different options from a DHCP server, through
@code{static} it is possible to configure static values for selected
options.  For example, @code{"domain_name_servers=127.0.0.1"}.

@item @code{vendor-class-id} (type: maybe-string)
Set the DHCP Vendor Class (e.g., @code{MSFT}).  For more information, refer
to @uref{https://www.rfc-editor.org/rfc/rfc2132#section-9.13,RFC 2132}.

@item @code{client-id} (type: maybe-string)
Use the interface hardware address or the given string as a client
identifier, this is mutually exclusive with the @code{duid} option.

@item @code{extra-content} (type: maybe-string)
Extra content to append to the configuration as-is.

@item @code{shepherd-provision} (default: @code{(networking)}) (type: list-of-symbols)
This is a list of symbols naming Shepherd services provided by this service.

@item @code{shepherd-requirement} (default: @code{()}) (type: list-of-symbols)
This is a list of symbols naming Shepherd services that this service will
depend on.

@end table

@end deftp


@c %end of fragment

@cindex NetworkManager

@defvar network-manager-service-type
This is the service type for the
@uref{https://wiki.gnome.org/Projects/NetworkManager, NetworkManager}
service. The value for this service type is a
@code{network-manager-configuration} record.

This service is part of @code{%desktop-services} (@pxref{Serviços de desktop}).
@end defvar

@deftp {Tipo de dados} network-manager-configuration
Data type representing the configuration of NetworkManager.

@table @asis
@item @code{network-manager} (default: @code{network-manager})
The NetworkManager package to use.

@item @code{shepherd-requirement} (default: @code{'(wireless-daemon)})
This option can be used to provide a list of symbols naming Shepherd
services that this service will depend on. The default
@code{'wireless-daemon} is provided by @code{'wpa-supplicant-service-type}
and @code{'iwd-service-type}.  Make sure you have one of these
configured. Note, that @code{%desktop-services} already include
@code{wpa-supplicant-service-type}.

@item @code{dns} (default: @code{"default"})
Processing mode for DNS, which affects how NetworkManager uses the
@code{resolv.conf} configuration file.

@table @samp
@item default
NetworkManager will update @code{resolv.conf} to reflect the nameservers
provided by currently active connections.

@item dnsmasq
NetworkManager will run @code{dnsmasq} as a local caching nameserver, using
a @dfn{conditional forwarding} configuration if you are connected to a VPN,
and then update @code{resolv.conf} to point to the local nameserver.

With this setting, you can share your network connection.  For example when
you want to share your network connection to another laptop @i{via} an
Ethernet cable, you can open @command{nm-connection-editor} and configure
the Wired connection's method for IPv4 and IPv6 to be ``Shared to other
computers'' and reestablish the connection (or reboot).

You can also set up a @dfn{host-to-guest connection} to QEMU VMs
(@pxref{Instalando Guix em uma VM}).  With a host-to-guest connection, you can
e.g.@: access a Web server running on the VM (@pxref{Serviços web}) from a
Web browser on your host system, or connect to the VM @i{via} SSH
(@pxref{Serviços de Rede, @code{openssh-service-type}}).  To set up a
host-to-guest connection, run this command once:

@example
nmcli connection add type tun \
 connection.interface-name tap0 \
 tun.mode tap tun.owner $(id -u) \
 ipv4.method shared \
 ipv4.addresses 172.28.112.1/24
@end example

Then each time you launch your QEMU VM (@pxref{Executando Guix em uma VM}), pass
@option{-nic tap,ifname=tap0,script=no,downscript=no} to
@command{qemu-system-...}.

@item none
NetworkManager will not modify @code{resolv.conf}.
@end table

@item @code{vpn-plugins} (default: @code{'()})
This is the list of available plugins for virtual private networks (VPNs).
An example of this is the @code{network-manager-openvpn} package, which
allows NetworkManager to manage VPNs @i{via} OpenVPN.

@item @code{extra-configuration-files} (default: @code{'()})
A list of two-element lists; the first element of each list is a file name
(as a string), and the second is a file-like object.  Used to specify
configuration files which will be added to the
@file{/etc/NetworkManager/conf.d}.  NetworkManager will read additional
configuration from this directory.  For details on configuration file
precedence and the configuration file format, see @samp{man 5
NetworkManager.conf}.

For example, to add two files named @file{001-basic.conf} and
@file{002-unmanaged.conf}:

@lisp
(service network-manager-service-type
         (network-manager-configuration
          (extra-configuration-files
           `(("001-basic.conf" ,(local-file "basic.conf"))
             ("002-unmanaged.conf" ,(plain-file "constructed-unmanaged.conf"
                                                "\
[keyfile]
unmanaged-devices=interface-name:wlo1_ap\n"))))))
@end lisp

@end table
@end deftp

@cindex Connman
@defvar connman-service-type
This is the service type to run @url{https://01.org/connman,Connman}, a
network connection manager.

Its value must be a @code{connman-configuration} record as in this example:

@lisp
(service connman-service-type
         (connman-configuration
           (disable-vpn? #t)))
@end lisp

See below for details about @code{connman-configuration}.
@end defvar

@deftp {Tipo de dados} connman-configuration
Data Type representing the configuration of connman.

@table @asis
@item @code{connman} (default: @var{connman})
The connman package to use.

@item @code{shepherd-requirement} (default: @code{'()})
This option can be used to provide a list of symbols naming Shepherd
services that this service will depend on, such as @code{'wpa-supplicant} or
@code{'iwd} if you require authenticated access for encrypted WiFi or
Ethernet networks.

@item @code{disable-vpn?} (default: @code{#f})
When true, disable connman's vpn plugin.

@item @code{general-configuration} (default: @code{(connman-general-configuration)})
Configuration serialized to @file{main.conf} and passed as @option{--config}
to @command{connmand}.

@end table
@end deftp

@c %start of fragment

@deftp {Tipo de dados} connman-general-configuration
Available @code{connman-general-configuration} fields are:

@table @asis
@item @code{input-request-timeout} (type: maybe-number)
Set input request timeout.  Default is 120 seconds.  The request for inputs
like passphrase will timeout after certain amount of time.  Use this setting
to increase the value in case of different user interface designs.

@item @code{browser-launch-timeout} (type: maybe-number)
Set browser launch timeout.  Default is 300 seconds.  The request for
launching a browser for portal pages will timeout after certain amount of
time.  Use this setting to increase the value in case of different user
interface designs.

@item @code{background-scanning?} (type: maybe-boolean)
Enable background scanning.  Default is true.  If wifi is disconnected, the
background scanning will follow a simple back off mechanism from 3s up to 5
minutes.  Then, it will stay in 5 minutes unless user specifically asks for
scanning through a D-Bus call.  If so, the mechanism will start again from
3s.  This feature activates also the background scanning while being
connected, which is required for roaming on wifi.  When
@code{background-scanning?} is false, ConnMan will not perform any scan
regardless of wifi is connected or not, unless it is requested by the user
through a D-Bus call.

@item @code{use-gateways-as-timeservers?} (type: maybe-boolean)
Assume that service gateways also function as timeservers.  Default is
false.

@item @code{fallback-timeservers} (type: maybe-list)
List of Fallback timeservers.  These timeservers are used for NTP sync when
there are no timeservers set by the user or by the service, and when
@code{use-gateways-as-timeservers?} is @code{#f}.  These can contain a mixed
combination of fully qualified domain names, IPv4 and IPv6 addresses.

@item @code{fallback-nameservers} (type: maybe-list)
List of fallback nameservers appended to the list of nameservers given by
the service.  The nameserver entries must be in numeric format, host names
are ignored.

@item @code{default-auto-connect-technologies} (type: maybe-list)
List of technologies that are marked autoconnectable by default.  The
default value for this entry when empty is @code{"ethernet"}, @code{"wifi"},
@code{"cellular"}.  Services that are automatically connected must have been
set up and saved to storage beforehand.

@item @code{default-favourite-technologies} (type: maybe-list)
List of technologies that are marked favorite by default.  The default value
for this entry when empty is @code{"ethernet"}.  Connects to services from
this technology even if not setup and saved to storage.

@item @code{always-connected-technologies} (type: maybe-list)
List of technologies which are always connected regardless of
preferred-technologies setting (@code{auto-connect?} @code{#t}).  The
default value is empty and this feature is disabled unless explicitly
enabled.

@item @code{preferred-technologies} (type: maybe-list)
List of preferred technologies from the most preferred one to the least
preferred one.  Services of the listed technology type will be tried one by
one in the order given, until one of them gets connected or they are all
tried.  A service of a preferred technology type in state 'ready' will get
the default route when compared to another preferred type further down the
list with state 'ready' or with a non-preferred type; a service of a
preferred technology type in state 'online' will get the default route when
compared to either a non-preferred type or a preferred type further down in
the list.

@item @code{network-interface-blacklist} (type: maybe-list)
List of blacklisted network interfaces.  Found interfaces will be compared
to the list and will not be handled by ConnMan, if their first characters
match any of the list entries.  Default value is @code{"vmnet"},
@code{"vboxnet"}, @code{"virbr"}, @code{"ifb"}.

@item @code{allow-hostname-updates?} (type: maybe-boolean)
Allow ConnMan to change the system hostname.  This can happen for example if
we receive DHCP hostname option.  Default value is @code{#t}.

@item @code{allow-domainname-updates?} (type: maybe-boolean)
Allow connman to change the system domainname.  This can happen for example
if we receive DHCP domainname option.  Default value is @code{#t}.

@item @code{single-connected-technology?} (type: maybe-boolean)
Keep only a single connected technology at any time.  When a new service is
connected by the user or a better one is found according to
preferred-technologies, the new service is kept connected and all the other
previously connected services are disconnected.  With this setting it does
not matter whether the previously connected services are in 'online' or
'ready' states, the newly connected service is the only one that will be
kept connected.  A service connected by the user will be used until going
out of network coverage.  With this setting enabled applications will notice
more network breaks than normal.  Note this options can't be used with
VPNs.  Default value is @code{#f}.

@item @code{tethering-technologies} (type: maybe-list)
List of technologies that are allowed to enable tethering.  The default
value is @code{"wifi"}, @code{"bluetooth"}, @code{"gadget"}.  Only those
technologies listed here are used for tethering.  If one wants to tether
ethernet, then add @code{"ethernet"} in the list.  Note that if ethernet
tethering is enabled, then a DHCP server is started on all ethernet
interfaces.  Tethered ethernet should never be connected to corporate or
home network as it will disrupt normal operation of these networks.  Due to
this ethernet is not tethered by default.  Do not activate ethernet
tethering unless you really know what you are doing.

@item @code{persistent-tethering-mode?} (type: maybe-boolean)
Restore earlier tethering status when returning from offline mode,
re-enabling a technology, and after restarts and reboots.  Default value is
@code{#f}.

@item @code{enable-6to4?} (type: maybe-boolean)
Automatically enable anycast 6to4 if possible.  This is not recommended, as
the use of 6to4 will generally lead to a severe degradation of connection
quality.  See RFC6343.  Default value is @code{#f} (as recommended by
RFC6343 section 4.1).

@item @code{vendor-class-id} (type: maybe-string)
Set DHCP option 60 (Vendor Class ID) to the given string.  This option can
be used by DHCP servers to identify specific clients without having to rely
on MAC address ranges, etc.

@item @code{enable-online-check?} (type: maybe-boolean)
Enable or disable use of HTTP GET as an online status check.  When a service
is in a READY state, and is selected as default, ConnMan will issue an HTTP
GET request to verify that end-to-end connectivity is successful.  Only then
the service will be transitioned to ONLINE state.  If this setting is false,
the default service will remain in READY state.  Default value is @code{#t}.

@item @code{online-check-ipv4-url} (type: maybe-string)
IPv4 URL used during the online status check.  Please refer to the README
for more detailed information.  Default value is
@uref{http://ipv4.connman.net/online/status.html}.

@item @code{online-check-ipv6-url} (type: maybe-string)
IPv6 URL used during the online status check.  Please refer to the README
for more detailed information.  Default value is
@uref{http://ipv6.connman.net/online/status.html}.

@item @code{online-check-initial-interval} (type: maybe-number)
Range of intervals between two online check requests.  Please refer to the
README for more detailed information.  Default value is @samp{1}.

@item @code{online-check-max-interval} (type: maybe-number)
Range of intervals between two online check requests.  Please refer to the
README for more detailed information.  Default value is @samp{1}.

@item @code{enable-online-to-ready-transition?} (type: maybe-boolean)
WARNING: This is an experimental feature.  In addition to
@code{enable-online-check} setting, enable or disable use of HTTP GET to
detect the loss of end-to-end connectivity.  If this setting is @code{#f},
when the default service transitions to ONLINE state, the HTTP GET request
is no more called until next cycle, initiated by a transition of the default
service to DISCONNECT state.  If this setting is @code{#t}, the HTTP GET
request keeps being called to guarantee that end-to-end connectivity is
still successful.  If not, the default service will transition to READY
state, enabling another service to become the default one, in replacement.
Default value is @code{#f}.

@item @code{auto-connect-roaming-services?} (type: maybe-boolean)
Automatically connect roaming services.  This is not recommended unless you
know you won't have any billing problem.  Default value is @code{#f}.

@item @code{address-conflict-detection?} (type: maybe-boolean)
Enable or disable the implementation of IPv4 address conflict detection
according to RFC5227.  ConnMan will send probe ARP packets to see if an IPv4
address is already in use before assigning the address to an interface.  If
an address conflict occurs for a statically configured address, an IPv4LL
address will be chosen instead (according to RFC3927).  If an address
conflict occurs for an address offered via DHCP, ConnMan sends a DHCP
DECLINE once and for the second conflict resorts to finding an IPv4LL
address.  Default value is @code{#f}.

@item @code{localtime} (type: maybe-string)
Path to localtime file.  Defaults to @file{/etc/localtime}.

@item @code{regulatory-domain-follows-timezone?} (type: maybe-boolean)
Enable regulatory domain to be changed along timezone changes.  With this
option set to true each time the timezone changes the first present ISO3166
country code is read from @file{/usr/share/zoneinfo/zone1970.tab} and set as
regulatory domain value.  Default value is @code{#f}.

@item @code{resolv-conf} (type: maybe-string)
Path to resolv.conf file.  If the file does not exist, but intermediate
directories exist, it will be created.  If this option is not set, it tries
to write into @file{/var/run/connman/resolv.conf} if it fails
(@file{/var/run/connman} does not exist or is not writeable).  If you do not
want to update resolv.conf, you can set @file{/dev/null}.

@end table

@end deftp

@cindex WPA Supplicant
@defvar wpa-supplicant-service-type
This is the service type to run @url{https://w1.fi/wpa_supplicant/,WPA
supplicant}, an authentication daemon required to authenticate against
encrypted WiFi or ethernet networks.
@end defvar

@deftp {Tipo de dados} wpa-supplicant-configuration
Data type representing the configuration of WPA Supplicant.

It takes the following parameters:

@table @asis
@item @code{wpa-supplicant} (default: @code{wpa-supplicant})
The WPA Supplicant package to use.

@item @code{shepherd-requirement} (default: @code{(user-processes loopback syslogd)}
List of services that should be started before WPA Supplicant starts.

@item @code{shepherd-provision} (default: @code{(wpa-supplicant wireless-daemon)}) (type: list-of-symbols)
The name(s) of the service.

@item @code{dbus?} (padrão: @code{#t})
Whether to listen for requests on D-Bus.

@item @code{pid-file} (default: @code{"/var/run/wpa_supplicant.pid"})
Where to store the PID file.

@item @code{interface} (default: @code{#f})
If this is set, it must specify the name of a network interface that WPA
supplicant will control.

@item @code{config-file} (default: @code{#f})
Optional configuration file to use.

@item @code{extra-options} (default: @code{'()})
List of additional command-line arguments to pass to the daemon.
@end table
@end deftp

@cindex iwd, iNet Wireless Daemon
@defvar iwd-service-type
This is the service type to run iwd, the @uref{https://iwd.wiki.kernel.org/,
iNet Wireless Daemon}, a daemon required to authenticate against encrypted
WiFi networks.
@end defvar

@quotation Aviso
By default @code{iwd} removes and re-creates interfaces it manages.  It
doesn't play nicely with @code{dhcp-client-service-type} that enumerates
wireless interfaces before starting the Shepherd service.  Use either
@code{dhcpcd-service-type} or the @code{iwd}'s built-in DHCP client (see
@code{enable-network-configuration} option below).
@end quotation

@quotation Aviso
@code{iwd-service-type} conflicts with @code{wpa-supplicant-service-type}.
Make sure only one is configured.
@end quotation

@c %start of fragment

@deftp {Data Type} iwd-configuration
Available @code{iwd-configuration} fields are:

@table @asis
@item @code{iwd} (default: @code{iwd}) (type: file-like)
The IWD package to use.

@item @code{interfaces} (default: @code{()}) (type: list-of-strings)
If this is set, it must specify @dfn{glob patterns} matching network
interfaces that IWD will control.

@item @code{ignored-interfaces} (default: @code{()}) (type: list-of-strings)
If this is set, it must specify @dfn{glob patterns} matching network
interfaces that IWD will not manage.

@item @code{phys} (default: @code{()}) (type: list-of-strings)
If this is set, it must specify @dfn{glob patterns} matching network PHYs
names that IWD will control.

@item @code{ignored-phys} (default: @code{()}) (type: list-of-strings)
If this is set, it must specify @dfn{glob patterns} matching network PHYs
names that IWD will not manage.

@item @code{shepherd-requirement} (default: @code{()}) (type: list-of-symbols)
Shepherd requirements the service should depend on.

@item @code{shepherd-provision} (default: @code{(iwd wireless-daemon)}) (type: list-of-symbols)
The name(s) of the service.

@item @code{config} (type: iwd-settings)
Configuration settings.

@end table

@end deftp


@c %end of fragment

@c %start of fragment

@deftp {Data Type} iwd-settings
Available @code{iwd-settings} fields are:

@table @asis
@item @code{general} (type: iwd-general-settings)
General settings.

@item @code{network} (default: @code{(iwd-network-settings)}) (type: maybe-iwd-network-settings)
Network settings.

@item @code{scan} (type: maybe-iwd-scan-settings)
Scan settings.

@item @code{extra-config} (default: @code{()}) (type: list-of-strings)
Extra configuration values to append to the IWD configuration file.

@end table

@end deftp


@c %end of fragment

@c %start of fragment

@deftp {Data Type} iwd-general-settings
Available @code{iwd-general-settings} fields are:

@table @asis
@item @code{enable-network-configuration?} (default: @code{#f}) (type: boolean)
Setting this option to true enables @code{iwd} to configure the network
interfaces with the IP addresses.

@item @code{extra-options} (default: @code{()}) (type: alist)
An association list of option symbols/strings to string values to be
appended to the General settings group.

@end table

@end deftp


@c %end of fragment

@c %start of fragment

@deftp {Data Type} iwd-network-settings
Available @code{iwd-network-settings} fields are:

@table @asis
@item @code{enable-ipv6?} (default: @code{#t}) (type: boolean)
Sets the global default that tells @code{iwd} whether it should configure
IPv6 addresses and routes

@item @code{name-resolving-service} (default: @code{none}) (type: resolving-service)
Configures a DNS resolution method used by the system.

@item @code{extra-options} (default: @code{()}) (type: alist)
An association list of option symbols/strings to string values to be
appended to the Network settings group.

@end table

@end deftp


@c %end of fragment

@c %start of fragment

@deftp {Data Type} iwd-scan-settings
Available @code{iwd-scan-settings} fields are:

@table @asis
@item @code{disable-periodic-scan?} (default: @code{#f}) (type: boolean)
Setting this option to @code{#t} will prevent @code{iwd} from issuing the
periodic scans for the available networks while disconnected.

@item @code{initial-periodic-scan-interval} (default: @code{10}) (type: number)
The initial periodic scan interval upon disconnect (in seconds).

@item @code{maximum-periodic-scan-interval} (default: @code{300}) (type: number)
The maximum periodic scan interval (in seconds).

@item @code{disable-roaming-scan?} (default: @code{#f}) (type: boolean)
Setting this option to @code{#t} will prevent @code{iwd} from trying to scan
when roaming decisions are activated.

@item @code{extra-options} (default: @code{()}) (type: alist)
An association list of option symbols/strings to string values to be
appended to the Scan settings group.

@end table

@end deftp


@c %end of fragment

@cindex ModemManager
Some networking devices such as modems require special care, and this is
what the services below focus on.

@defvar modem-manager-service-type
This is the service type for the
@uref{https://wiki.gnome.org/Projects/ModemManager, ModemManager} service.
The value for this service type is a @code{modem-manager-configuration}
record.

This service is part of @code{%desktop-services} (@pxref{Serviços de desktop}).
@end defvar

@deftp {Tipo de dados} modem-manager-configuration
Data type representing the configuration of ModemManager.

@table @asis
@item @code{modem-manager} (default: @code{modem-manager})
The ModemManager package to use.

@end table
@end deftp

@cindex USB_ModeSwitch
@cindex Modeswitching

@defvar usb-modeswitch-service-type
This is the service type for the
@uref{https://www.draisberghof.de/usb_modeswitch/, USB_ModeSwitch} service.
The value for this service type is a @code{usb-modeswitch-configuration}
record.

When plugged in, some USB modems (and other USB devices) initially present
themselves as a read-only storage medium and not as a modem.  They need to
be @dfn{modeswitched} before they are usable.  The USB_ModeSwitch service
type installs udev rules to automatically modeswitch these devices when they
are plugged in.

This service is part of @code{%desktop-services} (@pxref{Serviços de desktop}).
@end defvar

@deftp {Tipo de dados} usb-modeswitch-configuration
Data type representing the configuration of USB_ModeSwitch.

@table @asis
@item @code{usb-modeswitch} (default: @code{usb-modeswitch})
The USB_ModeSwitch package providing the binaries for modeswitching.

@item @code{usb-modeswitch-data} (default: @code{usb-modeswitch-data})
The package providing the device data and udev rules file used by
USB_ModeSwitch.

@item @code{config-file} (default: @code{#~(string-append #$usb-modeswitch:dispatcher "/etc/usb_modeswitch.conf")})
Which config file to use for the USB_ModeSwitch dispatcher.  By default the
config file shipped with USB_ModeSwitch is used which disables logging to
@file{/var/log} among other default settings.  If set to @code{#f}, no
config file is used.

@end table
@end deftp


@node Serviços de Rede
@subsection Serviços de Rede

The @code{(gnu services networking)} module discussed in the previous
section provides services for more advanced setups: providing a DHCP service
for others to use, filtering packets with iptables or nftables, running a
WiFi access point with @command{hostapd}, running the @command{inetd}
``superdaemon'', and more.  This section describes those.

@defvar dhcpd-service-type
This type defines a service that runs a DHCP daemon.  To create a service of
this type, you must supply a @code{<dhcpd-configuration>}.  For example:

@lisp
(service dhcpd-service-type
         (dhcpd-configuration
          (config-file (local-file "my-dhcpd.conf"))
          (interfaces '("enp0s25"))))
@end lisp
@end defvar

@deftp {Tipo de dados} dhcpd-configuration
@table @asis
@item @code{package} (default: @code{isc-dhcp})
The package that provides the DHCP daemon.  This package is expected to
provide the daemon at @file{sbin/dhcpd} relative to its output directory.
The default package is the @uref{https://www.isc.org/dhcp/, ISC's DHCP
server}.
@item @code{config-file} (default: @code{#f})
The configuration file to use.  This is required.  It will be passed to
@code{dhcpd} via its @code{-cf} option.  This may be any ``file-like''
object (@pxref{Expressões-G, file-like objects}).  See @code{man
dhcpd.conf} for details on the configuration file syntax.
@item @code{version} (default: @code{"4"})
The DHCP version to use.  The ISC DHCP server supports the values ``4'',
``6'', and ``4o6''.  These correspond to the @code{dhcpd} program options
@code{-4}, @code{-6}, and @code{-4o6}.  See @code{man dhcpd} for details.
@item @code{run-directory} (default: @code{"/run/dhcpd"})
The run directory to use.  At service activation time, this directory will
be created if it does not exist.
@item @code{pid-file} (default: @code{"/run/dhcpd/dhcpd.pid"})
The PID file to use.  This corresponds to the @code{-pf} option of
@code{dhcpd}.  See @code{man dhcpd} for details.
@item @code{interfaces} (default: @code{'()})
The names of the network interfaces on which dhcpd should listen for
broadcasts.  If this list is not empty, then its elements (which must be
strings) will be appended to the @code{dhcpd} invocation when starting the
daemon.  It may not be necessary to explicitly specify any interfaces here;
see @code{man dhcpd} for details.
@end table
@end deftp

@cindex hostapd service, for Wi-Fi access points
@cindex Wi-Fi access points, hostapd service
@defvar hostapd-service-type
This is the service type to run the @uref{https://w1.fi/hostapd/, hostapd}
daemon to set up WiFi (IEEE 802.11) access points and authentication
servers.  Its associated value must be a @code{hostapd-configuration} as
shown below:

@lisp
;; Use wlan1 to run the access point for "My Network".
(service hostapd-service-type
         (hostapd-configuration
          (interface "wlan1")
          (ssid "My Network")
          (channel 12)))
@end lisp
@end defvar

@deftp {Tipo de dados} hostapd-configuration
This data type represents the configuration of the hostapd service, with the
following fields:

@table @asis
@item @code{package} (default: @code{hostapd})
The hostapd package to use.

@item @code{interface} (default: @code{"wlan0"})
The network interface to run the WiFi access point.

@item @code{ssid}
The SSID (@dfn{service set identifier}), a string that identifies this
network.

@item @code{broadcast-ssid?} (default: @code{#t})
Whether to broadcast this SSID.

@item @code{channel} (default: @code{1})
The WiFi channel to use.

@item @code{driver} (default: @code{"nl80211"})
The driver interface type.  @code{"nl80211"} is used with all Linux mac80211
drivers.  Use @code{"none"} if building hostapd as a standalone RADIUS
server that does not control any wireless/wired driver.

@item @code{extra-settings} (default: @code{""})
Extra settings to append as-is to the hostapd configuration file.  See
@uref{https://w1.fi/cgit/hostap/plain/hostapd/hostapd.conf} for the
configuration file reference.
@end table
@end deftp

@defvar simulated-wifi-service-type
This is the type of a service to simulate WiFi networking, which can be
useful in virtual machines for testing purposes.  The service loads the
Linux kernel
@uref{https://www.kernel.org/doc/html/latest/networking/mac80211_hwsim/mac80211_hwsim.html,
@code{mac80211_hwsim} module} and starts hostapd to create a pseudo WiFi
network that can be seen on @code{wlan0}, by default.

The service's value is a @code{hostapd-configuration} record.
@end defvar


@cindex iptables
@defvar iptables-service-type
This is the service type to set up an iptables configuration.  iptables is a
packet filtering framework supported by the Linux kernel.  This service
supports configuring iptables for both IPv4 and IPv6.  A simple example
configuration rejecting all incoming connections except those to the ssh
port 22 is shown below.

@lisp
(service iptables-service-type
         (iptables-configuration
          (ipv4-rules (plain-file "iptables.rules" "*filter
:INPUT ACCEPT
:FORWARD ACCEPT
:OUTPUT ACCEPT
-A INPUT -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT
-A INPUT -p tcp --dport 22 -j ACCEPT
-A INPUT -j REJECT --reject-with icmp-port-unreachable
COMMIT
"))
          (ipv6-rules (plain-file "ip6tables.rules" "*filter
:INPUT ACCEPT
:FORWARD ACCEPT
:OUTPUT ACCEPT
-A INPUT -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT
-A INPUT -p tcp --dport 22 -j ACCEPT
-A INPUT -j REJECT --reject-with icmp6-port-unreachable
COMMIT
"))))
@end lisp
@end defvar

@deftp {Tipo de dados} iptables-configuration
The data type representing the configuration of iptables.

@table @asis
@item @code{iptables} (default: @code{iptables})
The iptables package that provides @code{iptables-restore} and
@code{ip6tables-restore}.
@item @code{ipv4-rules} (default: @code{%iptables-accept-all-rules})
The iptables rules to use.  It will be passed to @code{iptables-restore}.
This may be any ``file-like'' object (@pxref{Expressões-G, file-like
objects}).
@item @code{ipv6-rules} (default: @code{%iptables-accept-all-rules})
The ip6tables rules to use.  It will be passed to @code{ip6tables-restore}.
This may be any ``file-like'' object (@pxref{Expressões-G, file-like
objects}).
@end table
@end deftp

@cindex nftables
@cindex firewall, nftables
@defvar nftables-service-type
This is the service type to set up a nftables configuration.  nftables is a
netfilter project that aims to replace the iptables, ip6tables, arptables
and ebtables framework.  It provides a new packet filtering framework, a new
user-space utility @command{nft}, and a compatibility layer for iptables.
This service comes with a default ruleset, @code{%default-nftables-ruleset},
that rejects all incoming connections except those to the SSH port 22
(TCP).  To use it, simply write:

@lisp
(service nftables-service-type)
@end lisp
@end defvar

@c %start of fragment

@deftp {Tipo de dados} nftables-configuration
Available @code{nftables-configuration} fields are:

@table @asis
@item @code{package} (default: @code{nftables}) (type: file-like)
The @code{nftables} package to use.

@item @code{debug-levels} (type: maybe-list-of-debug-levels)
A list of debug levels, for enabling debugging output.  Valid debug level
values are the @samp{scanner}, @samp{parser}, @samp{eval}, @samp{netlink},
@samp{mnl}, @samp{proto-ctx}, @samp{segtree} or @samp{all} symbols.

@item @code{ruleset} (type: file-like)
A file-like object containing the complete nftables ruleset.  The default
ruleset rejects all incoming connections except those to TCP port 22, with
connections from the loopback interface are allowed.

@end table

@end deftp


@c %end of fragment

@cindex NTP (Network Time Protocol), service
@cindex ntpd, service for the Network Time Protocol daemon
@cindex real time clock
@defvar ntp-service-type
This is the type of the service running the @uref{https://www.ntp.org,
Network Time Protocol (NTP)} daemon, @command{ntpd}.  The daemon will keep
the system clock synchronized with that of the specified NTP servers.

The value of this service is an @code{ntpd-configuration} object, as
described below.
@end defvar

@deftp {Tipo de dados} ntp-configuration
This is the data type for the NTP service configuration.

@table @asis
@item @code{servers} (default: @code{%ntp-servers})
This is the list of servers (@code{<ntp-server>} records) with which
@command{ntpd} will be synchronized.  See the @code{ntp-server} data type
definition below.

@item @code{allow-large-adjustment?} (default: @code{#t})
This determines whether @command{ntpd} is allowed to make an initial
adjustment of more than 1,000 seconds.

@item @code{ntp} (default: @code{ntp})
The NTP package to use.
@end table
@end deftp

@defvar %ntp-servers
List of host names used as the default NTP servers.  These are servers of
the @uref{https://www.ntppool.org/en/, NTP Pool Project}.
@end defvar

@deftp {Tipo de dados} ntp-server
The data type representing the configuration of a NTP server.

@table @asis
@item @code{type} (default: @code{'server})
The type of the NTP server, given as a symbol.  One of @code{'pool},
@code{'server}, @code{'peer}, @code{'broadcast} or @code{'manycastclient}.

@item @code{address}
The address of the server, as a string.

@item @code{options}
NTPD options to use with that specific server, given as a list of option
names and/or of option names and values tuples.  The following example
define a server to use with the options @option{iburst} and @option{prefer},
as well as @option{version} 3 and a @option{maxpoll} time of 16 seconds.

@example
(ntp-server
 (type 'server)
 (address "some.ntp.server.org")
 (options `(iburst (version 3) (maxpoll 16) prefer))))
@end example
@end table
@end deftp

@cindex OpenNTPD
@defvar openntpd-service-type
Run the @command{ntpd}, the Network Time Protocol (NTP) daemon, as
implemented by @uref{http://www.openntpd.org, OpenNTPD}.  The daemon will
keep the system clock synchronized with that of the given servers.

@lisp
(service
 openntpd-service-type
 (openntpd-configuration
  (listen-on '("127.0.0.1" "::1"))
  (sensor '("udcf0 correction 70000"))
  (constraint-from '("www.gnu.org"))
  (constraints-from '("https://www.google.com/"))))

@end lisp
@end defvar

@defvar %openntpd-servers
This variable is a list of the server addresses defined in
@code{%ntp-servers}.
@end defvar

@deftp {Tipo de dados} openntpd-configuration
@table @asis
@item @code{openntpd} (default: @code{openntpd})
The openntpd package to use.
@item @code{listen-on} (default: @code{'("127.0.0.1" "::1")})
A list of local IP addresses or hostnames the ntpd daemon should listen on.
@item @code{query-from} (default: @code{'()})
A list of local IP address the ntpd daemon should use for outgoing queries.
@item @code{sensor} (default: @code{'()})
Specify a list of timedelta sensor devices ntpd should use.  @code{ntpd}
will listen to each sensor that actually exists and ignore non-existent
ones.  See @uref{https://man.openbsd.org/ntpd.conf, upstream documentation}
for more information.
@item @code{server} (default: @code{'()})
Specify a list of IP addresses or hostnames of NTP servers to synchronize
to.
@item @code{servers} (default: @code{%openntp-servers})
Specify a list of IP addresses or hostnames of NTP pools to synchronize to.
@item @code{constraint-from} (default: @code{'()})
@code{ntpd} can be configured to query the ‘Date’ from trusted HTTPS servers
via TLS.  This time information is not used for precision but acts as an
authenticated constraint, thereby reducing the impact of unauthenticated NTP
man-in-the-middle attacks.  Specify a list of URLs, IP addresses or
hostnames of HTTPS servers to provide a constraint.
@item @code{constraints-from} (default: @code{'()})
As with constraint from, specify a list of URLs, IP addresses or hostnames
of HTTPS servers to provide a constraint.  Should the hostname resolve to
multiple IP addresses, @code{ntpd} will calculate a median constraint from
all of them.
@end table
@end deftp

@cindex inetd
@defvar inetd-service-type
This service runs the @command{inetd} (@pxref{inetd invocation,,, inetutils,
GNU Inetutils}) daemon.  @command{inetd} listens for connections on internet
sockets, and lazily starts the specified server program when a connection is
made on one of these sockets.

The value of this service is an @code{inetd-configuration} object.  The
following example configures the @command{inetd} daemon to provide the
built-in @command{echo} service, as well as an smtp service which forwards
smtp traffic over ssh to a server @code{smtp-server} behind a gateway
@code{hostname}:

@lisp
(service
 inetd-service-type
 (inetd-configuration
  (entries (list
            (inetd-entry
             (name "echo")
             (socket-type 'stream)
             (protocol "tcp")
             (wait? #f)
             (user "root"))
            (inetd-entry
             (node "127.0.0.1")
             (name "smtp")
             (socket-type 'stream)
             (protocol "tcp")
             (wait? #f)
             (user "root")
             (program (file-append openssh "/bin/ssh"))
             (arguments
              '("ssh" "-qT" "-i" "/path/to/ssh_key"
                "-W" "smtp-server:25" "user@@hostname")))))))
@end lisp

See below for more details about @code{inetd-configuration}.
@end defvar

@deftp {Tipo de dados} inetd-configuration
Data type representing the configuration of @command{inetd}.

@table @asis
@item @code{program} (default: @code{(file-append inetutils "/libexec/inetd")})
The @command{inetd} executable to use.

@item @code{entries} (default: @code{'()})
A list of @command{inetd} service entries.  Each entry should be created by
the @code{inetd-entry} constructor.
@end table
@end deftp

@deftp {Tipo de dados} inetd-entry
Data type representing an entry in the @command{inetd} configuration.  Each
entry corresponds to a socket where @command{inetd} will listen for
requests.

@table @asis
@item @code{node} (default: @code{#f})
Optional string, a comma-separated list of local addresses @command{inetd}
should use when listening for this service.  @xref{Configuration file,,,
inetutils, GNU Inetutils} for a complete description of all options.
@item @code{name}
A string, the name must correspond to an entry in @code{/etc/services}.
@item @code{socket-type}
One of @code{'stream}, @code{'dgram}, @code{'raw}, @code{'rdm} or
@code{'seqpacket}.
@item @code{protocol}
A string, must correspond to an entry in @code{/etc/protocols}.
@item @code{wait?} (padrão: @code{#t})
Whether @command{inetd} should wait for the server to exit before listening
to new service requests.
@item @code{user}
A string containing the user (and, optionally, group) name of the user as
whom the server should run.  The group name can be specified in a suffix,
separated by a colon or period, i.e.@: @code{"user"}, @code{"user:group"} or
@code{"user.group"}.
@item @code{program} (default: @code{"internal"})
The server program which will serve the requests, or @code{"internal"} if
@command{inetd} should use a built-in service.
@item @code{arguments} (padrão: @code{'()})
A list strings or file-like objects, which are the server program's
arguments, starting with the zeroth argument, i.e.@: the name of the program
itself.  For @command{inetd}'s internal services, this entry must be
@code{'()} or @code{'("internal")}.
@end table

@xref{Configuration file,,, inetutils, GNU Inetutils} for a more detailed
discussion of each configuration field.
@end deftp

@cindex opendht, distributed hash table network service
@cindex dhtproxy, for use with jami
@defvar opendht-service-type
This is the type of the service running a @uref{https://opendht.net,
OpenDHT} node, @command{dhtnode}.  The daemon can be used to host your own
proxy service to the distributed hash table (DHT), for example to connect to
with Jami, among other applications.

@quotation Importante
When using the OpenDHT proxy server, the IP addresses it ``sees'' from the
clients should be addresses reachable from other peers.  In practice this
means that a publicly reachable address is best suited for a proxy server,
outside of your private network.  For example, hosting the proxy server on a
IPv4 private local network and exposing it via port forwarding could work
for external peers, but peers local to the proxy would have their private
addresses shared with the external peers, leading to connectivity problems.
@end quotation

The value of this service is a @code{opendht-configuration} object, as
described below.
@end defvar

@c The fields documentation has been auto-generated using the
@c configuration->documentation procedure from
@c (gnu services configuration).
@deftp {Tipo de dados} opendht-configuration
Available @code{opendht-configuration} fields are:

@table @asis
@item @code{opendht} (default: @code{opendht}) (type: file-like)
The @code{opendht} package to use.

@item @code{peer-discovery?} (default: @code{#f}) (type: boolean)
Whether to enable the multicast local peer discovery mechanism.

@item @code{enable-logging?} (default: @code{#f}) (type: boolean)
Whether to enable logging messages to syslog.  It is disabled by default as
it is rather verbose.

@item @code{debug?} (default: @code{#f}) (type: boolean)
Whether to enable debug-level logging messages.  This has no effect if
logging is disabled.

@item @code{bootstrap-host} (default: @code{"bootstrap.jami.net:4222"}) (type: maybe-string)
The node host name that is used to make the first connection to the
network.  A specific port value can be provided by appending the
@code{:PORT} suffix.  By default, it uses the Jami bootstrap nodes, but any
host can be specified here.  It's also possible to disable bootstrapping by
explicitly setting this field to the @code{%unset-value} value.

@item @code{port} (default: @code{4222}) (type: maybe-number)
The UDP port to bind to.  When left unspecified, an available port is
automatically selected.

@item @code{proxy-server-port} (type: maybe-number)
Spawn a proxy server listening on the specified port.

@item @code{proxy-server-port-tls} (type: maybe-number)
Spawn a proxy server listening to TLS connections on the specified port.

@end table
@end deftp

@cindex Tor
@defvar tor-service-type
Type for a service that runs the @uref{https://torproject.org, Tor}
anonymous networking daemon.  The service is configured using a
@code{<tor-configuration>} record.  By default, the Tor daemon runs as the
@code{tor} unprivileged user, which is a member of the @code{tor} group.

@cindex onion services, for Tor
Services of this type can be extended by other services to specify
@dfn{onion services} (in addition to those already specified in
@code{tor-configuration}) as in this example:

@lisp
(simple-service 'my-extra-onion-service tor-service-type
                (list (tor-onion-service-configuration
                        (name "extra-onion-service")
                        (mapping '((80 "127.0.0.1:8080"))))))
@end lisp
@end defvar

@deftp {Tipo de dados} tor-configuration
@table @asis
@item @code{tor} (default: @code{tor})
The package that provides the Tor daemon.  This package is expected to
provide the daemon at @file{bin/tor} relative to its output directory.  The
default package is the @uref{https://www.torproject.org, Tor Project's}
implementation.

@item @code{config-file} (default: @code{(plain-file "empty" "")})
The configuration file to use.  It will be appended to a default
configuration file, and the final configuration file will be passed to
@code{tor} via its @code{-f} option.  This may be any ``file-like'' object
(@pxref{Expressões-G, file-like objects}).  See @code{man tor} for details
on the configuration file syntax.

@item @code{hidden-services} (default: @code{'()})
The list of @code{<tor-onion-service-configuration>} records to use.  For
any onion service you include in this list, appropriate configuration to
enable the onion service will be automatically added to the default
configuration file.

@item @code{socks-socket-type} (default: @code{'tcp})
The default socket type that Tor should use for its SOCKS socket.  This must
be either @code{'tcp} or @code{'unix}.  If it is @code{'tcp}, then by
default Tor will listen on TCP port 9050 on the loopback interface (i.e.,
localhost).  If it is @code{'unix}, then Tor will listen on the UNIX domain
socket @file{/var/run/tor/socks-sock}, which will be made writable by
members of the @code{tor} group.

If you want to customize the SOCKS socket in more detail, leave
@code{socks-socket-type} at its default value of @code{'tcp} and use
@code{config-file} to override the default by providing your own
@code{SocksPort} option.

@item @code{control-socket?} (default: @code{#f})
Whether or not to provide a ``control socket'' by which Tor can be
controlled to, for instance, dynamically instantiate tor onion services.  If
@code{#t}, Tor will listen for control commands on the UNIX domain socket
@file{/var/run/tor/control-sock}, which will be made writable by members of
the @code{tor} group.

@item @code{transport-plugins} (default: @code{'()})
The list of @code{<tor-transport-plugin>} records to use.  For any transport
plugin you include in this list, appropriate configuration line to enable
transport plugin will be automatically added to the default configuration
file.

@item @code{auto-start?} (default: @code{#t})
Whether or not to start the Tor daemon on boot.

@end table
@end deftp

@cindex onion service, tor
@deftp {Tipo de dados} tor-onion-service-configuration
Data Type representing a Tor @dfn{Onion Service} configuration.  See
@url{https://community.torproject.org/onion-services/, the Tor project's
documentation} for more information.  Available
@code{tor-onion-service-configuration} fields are:

@table @asis
@item @code{name} (type: string)
Name for this Onion Service.  This creates a
@file{/var/lib/tor/hidden-services/@var{name}} directory, where the
@file{hostname} file contains the @indicateurl{.onion} host name for this
Onion Service.

@item @code{mapping} (type: alist)
Association list of port to address mappings.  The following example:
@lisp
'((22 "127.0.0.1:22")
  (80 "127.0.0.1:8080"))
@end lisp
maps ports 22 and 80 of the Onion Service to the local ports 22 and 8080.

@end table
@end deftp

@cindex pluggable transports, tor
@deftp {Tipo de dados} tor-transport-plugin
Data type representing a Tor pluggable transport plugin in
@code{tor-configuration}.  Plugguble transports are programs that disguise
Tor traffic, which can be useful in case Tor is censored.  See the the Tor
project's @url{https://tb-manual.torproject.org/circumvention/,
documentation} and @url{https://spec.torproject.org/pt-spec/index.html,
specification} for more information.

Each transport plugin corresponds either to @code{ClientTransportPlugin ...}
or to @code{ServerTransportPlugin ...} line in the default configuration
file, see @command{man tor}.  Available @code{tor-transport-plugin} fields
are:

@table @asis
@item @code{role} (default: @code{'client})
This must be either @code{'client} or @code{'server}.  Otherwise, an error
is raised.  Set the @code{'server} value if you want to run a bridge to help
censored users connect to the Tor network, see
@url{https://community.torproject.org/relay/setup/bridge/, the Tor project's
bridge guide}.  Set the @code{'client} value if you want to connect to
somebody else's bridge, see @url{https://bridges.torproject.org/, the Tor
project's ``Get Bridges'' page}.  In both cases the required additional
configuration should be provided via @code{#:config-file} option of
@code{tor-configuration}.
@item @code{protocol} (default: @code{"obfs4"})
A string that specifies a pluggable transport protocol.
@item @code{program}
This must be a ``file-like'' object or a string pointing to the pluggable
transport plugin executable.  This option allows the Tor daemon run inside
the container to access the executable and all the references (e.g. package
dependencies) attached to it.
@end table

Suppose you would like Tor daemon to use obfs4 type obfuscation and to
connect to Tor network via obfs4 bridge (a nonpublic Tor relay with support
for obfs4 type obfuscation). Then you may go to
@url{https://bridges.torproject.org/, https://bridges.torproject.org/} and
get there a couple of bridge lines (each starts with @code{obfs4 ...})  and
use these lines in tor-service-type configuration as follows:
@lisp
(service tor-service-type
	 (tor-configuration
	  (config-file (plain-file "torrc"
				   "\
UseBridges 1
Bridge obfs4 ...
Bridge obfs4 ..."))
	  (transport-plugins
	   (list (tor-transport-plugin
		  (program (file-append lyrebird "/bin/lyrebird")))))))
@end lisp
@end deftp

The @code{(gnu services rsync)} module provides the following services:

You might want an rsync daemon if you have files that you want available so
anyone (or just yourself) can download existing files or upload new files.

@defvar rsync-service-type
This is the service type for the @uref{https://rsync.samba.org, rsync}
daemon, The value for this service type is a @command{rsync-configuration}
record as in this example:

@lisp
;; Export two directories over rsync.  By default rsync listens on
;; all the network interfaces.
(service rsync-service-type
         (rsync-configuration
           (modules (list (rsync-module
                            (name "music")
                            (file-name "/srv/zik")
                            (read-only? #f))
                          (rsync-module
                            (name "movies")
                            (file-name "/home/charlie/movies"))))))
@end lisp

See below for details about @code{rsync-configuration}.
@end defvar

@deftp {Tipo de dados} rsync-configuration
Data type representing the configuration for @code{rsync-service}.

@table @asis
@item @code{package} (default: @var{rsync})
@code{rsync} package to use.

@item @code{address} (default: @code{#f})
IP address on which @command{rsync} listens for incoming connections.  If
unspecified, it defaults to listening on all available addresses.

@item @code{port-number} (default: @code{873})
TCP port on which @command{rsync} listens for incoming connections.  If port
is less than @code{1024} @command{rsync} needs to be started as the
@code{root} user and group.

@item @code{pid-file} (default: @code{"/var/run/rsyncd/rsyncd.pid"})
Name of the file where @command{rsync} writes its PID.

@item @code{lock-file} (default: @code{"/var/run/rsyncd/rsyncd.lock"})
Name of the file where @command{rsync} writes its lock file.

@item @code{log-file} (default: @code{"/var/log/rsyncd.log"})
Name of the file where @command{rsync} writes its log file.

@item @code{user} (default: @code{"root"})
Owner of the @code{rsync} process.

@item @code{group} (default: @code{"root"})
Group of the @code{rsync} process.

@item @code{uid} (default: @code{"rsyncd"})
User name or user ID that file transfers to and from that module should take
place as when the daemon was run as @code{root}.

@item @code{gid} (default: @code{"rsyncd"})
Group name or group ID that will be used when accessing the module.

@item @code{modules} (default: @code{%default-modules})
List of ``modules''---i.e., directories exported over rsync.  Each element
must be a @code{rsync-module} record, as described below.
@end table
@end deftp

@deftp {Tipo de dados} rsync-module
This is the data type for rsync ``modules''.  A module is a directory
exported over the rsync protocol.  The available fields are as follows:

@table @asis
@item @code{name}
The module name.  This is the name that shows up in URLs.  For example, if
the module is called @code{music}, the corresponding URL will be
@code{rsync://host.example.org/music}.

@item @code{file-name}
Name of the directory being exported.

@item @code{comment} (default: @code{""})
Comment associated with the module.  Client user interfaces may display it
when they obtain the list of available modules.

@item @code{read-only?} (default: @code{#t})
Whether or not client will be able to upload files.  If this is false, the
uploads will be authorized if permissions on the daemon side permit it.

@item @code{chroot?} (default: @code{#t})
When this is true, the rsync daemon changes root to the module's directory
before starting file transfers with the client.  This improves security, but
requires rsync to run as root.

@item @code{timeout} (default: @code{300})
Idle time in seconds after which the daemon closes a connection with the
client.
@end table
@end deftp

@cindex Syncthing, file synchronization service
@cindex backup service, Syncthing
The @code{(gnu services syncthing)} module provides the following services:
@cindex syncthing

You might want a Syncthing daemon if you have files between two or more
computers and want to sync them in real time, safely protected from prying
eyes.

@defvar syncthing-service-type
This is the service type for the @uref{https://syncthing.net/, syncthing}
daemon, The value for this service type is a
@command{syncthing-configuration} record as in this example:

@lisp
(service syncthing-service-type
         (syncthing-configuration (user "alice")))
@end lisp

@quotation Nota
This service is also available for Guix Home, where it runs directly with
your user privileges (@pxref{Networking Home Services,
@code{home-syncthing-service-type}}).
@end quotation

See below for details about @code{syncthing-configuration}.
@end defvar

@deftp {Tipo de dados} syncthing-configuration
Data type representing the configuration for @code{syncthing-service-type}.

@table @asis
@item @code{syncthing} (default: @var{syncthing})
@code{syncthing} package to use.

@item @code{arguments} (default: @var{'()})
List of command-line arguments passing to @code{syncthing} binary.

@item @code{logflags} (default: @var{0})
Sum of logging flags, see
@uref{https://docs.syncthing.net/users/syncthing.html#cmdoption-logflags,
Syncthing documentation logflags}.

@item @code{user} (default: @var{#f})
The user as which the Syncthing service is to be run.  This assumes that the
specified user exists.

@item @code{group} (default: @var{"users"})
The group as which the Syncthing service is to be run.  This assumes that
the specified group exists.

@item @code{home} (default: @var{#f})
Sets the @code{HOME} variable for the Syncthing daemon.  The default is
@file{$HOME} of the specified Syncthing @code{user}.

@item @code{config-file} (default: @var{#f})
Either a file-like object that resolves to a Syncthing configuration XML
file, or a @code{syncthing-config-file} record (see below).  If set to
@code{#f}, Guix will not try to generate a config file, and Syncthing will
generate a default configuration which will not be touched on reconfigure.
Specifying this in a system service moves Syncthing's common configuration
and data directory (@code{--home} in
@uref{https://docs.syncthing.net/users/syncthing.html}) to
@file{/var/lib/syncthing-<user>}.

When used as a home service, syncthing configuration will be populated in
@file{~/.local/state/syncthing/}.  Old Syncthing installs may have files in
@file{$XDG_CONFIG_HOME/syncthing/} (usually @file{~/.config/syncthing/}),
which will override configuration in @file{~/.local/state/syncthing} managed
by this service.  In such cases, you should move the contents of
@file{$XDG_CONFIG_HOME/syncthing/} into @file{~/.local/state/syncthing/}.

@end table
@end deftp

This section documents a subset of the Syncthing configuration
options—specifically those related to Guix or those affecting how your
computer will connect to other computers over the network (such as Syncthing
relays or discovery servers).  The configuration is fully documented in the
upstream @uref{https://docs.syncthing.net/users/config.html, Syncthing
config documentation}; camelCase there is converted to kebab-case here.  If
you are migrating from a Syncthing-managed configuration to one managed by
Guix, you can check what changes were introduced by @code{diff}ing the
respective @file{config.xml} files.  Note that you will need to add
whitespace with 4-space indentation to the file generated by Guix, using the
@code{xmllint} program from the @code{libxml2} package like so:

@example
XMLLINT_INDENT="    " xmllint --format /path/to/new/config.xml | diff /path/to/old/config.xml -
@end example

When generating a configuration file through Guix, you can still temporarily
modify Syncthing from the GUI or through @code{introducer} and
@code{autoAcceptFolders} mechanisms, but such changes will be reset on
reconfigure.

@deftp {Data Type} syncthing-config-file
Data type representing the configuration file read by the Syncthing daemon.

@table @asis
@item @code{folders} (default: @code{(list (syncthing-folder (id "default") (label "Default Folder") (path "~/Sync")))}
The default here is the same as Syncthing's default.  The value should be a
list of @code{syncthing-folder}s.

@item @code{devices} (default: @code{'()}
This should be a list of @code{syncthing-device}s.  Guix will automatically
add any devices specified in any `folders' to this list.  There are
instances when you want to connect to a device despite not (initially)
sharing any folders (such as a device with autoAcceptFolders).  In such
instances, you should specify those devices here.  If multiple versions of
the same device (as determined by comparing device ID) are discovered, the
one in this list is prioritized.  Otherwise, the first instance in the first
folder is used.

@item @code{gui-enabled?} (default: @code{#t})
By default, any user on the computer can access the GUI and make changes to
Syncthing.  If you leave this enabled, you should probably set
@code{gui-user} and @code{gui-password} (see below).

@item @code{gui-tls?} (default: @code{#f})
@item @code{gui-debugging?} (default: @code{#f})
@item @code{gui-send-basic-authorization-prompt?} (default: @code{#f})
@item @code{gui-address} (default: @code{"127.0.0.1:8384"})
@item @code{gui-user} (default: @code{#f})
@item @code{gui-password} (default: @code{#f})
A bcrypt hash of the GUI password.  Remember that this will be globally
exposed in @file{/gnu/store}.

@item @code{gui-apikey} (default: @code{#f})
You must specify this to use the Syncthing REST interface.  This key is kept
in @file{/gnu/store} and is accessible to all users of the system.

@item @code{gui-theme} (default: @code{"default"})
@item @code{ldap-enabled?} (default: @code{#f})
@item @code{ldap-address} (default: @code{""})
@item @code{ldap-bind-dn} (default: @code{""})
@item @code{ldap-transport} (default: @code{""})
@item @code{ldap-insecure-skip-verify} (default: @code{""})
@item @code{ldap-search-base-dn} (default: @code{""})
@item @code{ldap-search-filter} (default: @code{""})
@item @code{listen-address} (default: @code{"default"})
@item @code{global-announce-server} (default: @code{"default"})
@item @code{global-announce-enabled?} (default: @code{#t})
Global discovery servers can be used to help connect devices at unknown IP
addresses by storing the last known IP address.

@item @code{local-announce-enabled?} (default: @code{#t})
This makes devices find each other very easily on the same LAN.  Often, this
will allow you to just plug an Ethernet between two devices, or connect one
device to the other's hotspot and start syncing.

@item @code{local-announce-port} (default: @code{21027})
@item @code{local-announce-mac-address} (default: @code{"[ff12::8384]:21027"})
@item @code{max-send-kbps} (default: @code{0})
@item @code{max-receive-kbps} (default: @code{0})
@item @code{reconnection-interval-seconds} (default: @code{60})
@item @code{relays-enabled?} (default: @code{#t})
This option allows your Syncthing instance to use a global network of
@uref{https://docs.syncthing.net/users/relaying.html, relays} to enable
syncing between devices when all other methods fail.  As always, Syncthing
traffic is encrypted in transport and the relays are unable to decrypt it.

@item @code{relay-reconnect-interval-minutes} (default: @code{10})
@item @code{start-browser?} (default: @code{#t})
@item @code{nat-enabled?} (default: @code{#t})
@item @code{nat-lease-minutes} (default: @code{60})
@item @code{nat-renewal-minutes} (default: @code{30})
@item @code{nat-timeout-seconds} (default: @code{10})
@item @code{usage-reporting-accepted} (default: @code{0})
Options whose names begin with `usage-reporting-' control usage reporting.
Set to -1 to disable, or to a positive value to enable.  The default (0)
disables reporting, but causes a usage reporting consent prompt to be
displayed in the Syncthing GUI.

@item @code{usage-reporting-seen} (default: @code{0})
@item @code{usage-reporting-unique-id} (default: @code{""})
@item @code{usage-reporting-url} (default: @code{"https://data.syncthing.net/newdata"})
@item @code{usage-reporting-post-insecurely?} (default: @code{#f})
@item @code{usage-reporting-initial-delay-seconds} (default: @code{1800})
@item @code{auto-upgrade-interval-hours} (default: @code{12})
@item @code{upgrade-to-pre-releases?} (default: @code{#f})
@item @code{keep-temporaries-hours} (default: @code{24})
@item @code{cache-ignored-files?} (default: @code{#f})
@item @code{progress-update-interval-seconds} (default: @code{5})
@item @code{limit-bandwidth-in-lan?} (default: @code{#f})
@item @code{min-home-disk-free-unit} (default: @code{"%"})
@item @code{min-home-disk-free} (default: @code{1})
@item @code{releases-url} (default: @code{"https://upgrades.syncthing.net/meta.json"})
@item @code{overwrite-remote-device-names-on-connect?} (default: @code{#f})
@item @code{temp-index-min-blocks} (default: @code{10})
@item @code{unacked-notification-id} (default: @code{"authenticationUserAndPassword"})
@item @code{traffic-class} (default: @code{0})
@item @code{set-low-priority?} (default: @code{#t})
@item @code{max-folder-concurrency} (default: @code{0})
@item @code{crash-reporting-url} (default: @code{"https://crash.syncthing.net/newcrash"})
@item @code{crash-reporting-enabled?} (default: @code{#t})
@item @code{stun-keepalive-start-seconds} (default: @code{180})
@item @code{stun-keepalive-min-seconds} (default: @code{20})
@item @code{stun-server} (default: @code{"default"})
@item @code{database-tuning} (default: @code{"auto"})
@item @code{max-concurrent-incoming-request-kib} (default: @code{0})
@item @code{announce-lan-addresses?} (default: @code{#t})
@item @code{send-full-index-on-upgrade?} (default: @code{#f})
@item @code{connection-limit-enough} (default: @code{0})
@item @code{connection-limit-max} (default: @code{0})
@item @code{insecure-allow-old-tls-versions?} (default: @code{#f})
@item @code{connection-priority-tcp-lan} (default: @code{10})
@item @code{connection-priority-quic-lan} (default: @code{20})
@item @code{connection-priority-tcp-wan} (default: @code{30})
@item @code{connection-priority-quic-wan} (default: @code{40})
@item @code{connection-priority-relay} (default: @code{50})
@item @code{connection-priority-upgrade-threshold} (default: @code{0})
@item @code{default-folder} (default: @code{(syncthing-folder (label ""))})
@itemx @code{default-device} (default: @code{(syncthing-device (id ""))})
@itemx @code{default-ignores} (default: @code{"")})
Options whose names begin with `default-' above do not affect folders and
devices added through the Guix configuration interface.  They will, however,
affect folders and devices that are added through the Syncthing GUI, by an
@code{introducer}, or a device with @code{auto-accept-folders}.
@end table
@end deftp

@deftp {Data Type} syncthing-folder
Data type representing a folder to be synchronized.

@table @asis
@item @code{id} (default: @code{#f})
This ID cannot match the ID of any other folder on this device.  If left
unspecified, it will default to the label (see below).

@item @code{label}
A human readable label for the folder.

@item @code{path}
The path at which to store this folder.

@item @code{type} (default: @code{"sendreceive"})
@item @code{rescan-interval-seconds} (default: @code{3600})
@item @code{file-system-watcher-enabled?} (default: @code{#t})
@item @code{file-system-watcher-delay-seconds} (default: @code{10})
@item @code{file-system-watcher-timeout-seconds} (default: @code{0})
@item @code{ignore-permissions?} (default: @code{#f})
@item @code{auto-normalize?} (default: @code{#t})
@item @code{devices} (default: @code{'()})
This should be a list of other Syncthing devices.  You do not need to
specify the current device.  Each device can be listed as a a
@code{syncthing-device} record or a @code{syncthing-folder-device} record if
you want files to be encrypted on disk.  See below.

@item @code{filesystem-type} (default: @code{"basic"})
@item @code{min-disk-free-unit} (default: @code{"%"})
@item @code{min-disk-free} (default: @code{1})
@item @code{versioning-type} (default: @code{#f})
@item @code{versioning-file-system-path} (default: @code{""})
@item @code{versioning-file-system-type} (default: @code{"basic"})
@item @code{versioning-cleanup-interval-seconds} (default: @code{3600})
@item @code{versioning-cleanout-days} (default: @code{#f})
@item @code{versioning-keep} (default: @code{#f})
@item @code{versioning-max-age} (default: @code{#f})
@item @code{versioning-command} (default: @code{#f})
@item @code{copiers} (default: @code{0})
@item @code{puller-max-pending-kib} (default: @code{0})
@item @code{hashers} (default: @code{0})
@item @code{order} (default: @code{"random"})
@item @code{ignore-delete?} (default: @code{#f})
@item @code{scan-progress-interval-seconds} (default: @code{0})
@item @code{puller-pause-seconds} (default: @code{0})
@item @code{max-conflicts} (default: @code{10})
@item @code{disable-sparse-files?} (default: @code{#f})
@item @code{disable-temp-indexes?} (default: @code{#f})
@item @code{paused?} (default: @code{#f})
@item @code{weak-hash-threshold-percentage} (default: @code{25})
@item @code{marker-name} (default: @code{".stfolder"})
@item @code{copy-ownership-from-parent?} (default: @code{#f})
@item @code{mod-time-window-seconds} (default: @code{0})
@item @code{max-concurrent-writes} (default: @code{2})
@item @code{disable-fsync?} (default: @code{#f})
@item @code{block-pull-order} (default: @code{"standard"})
@item @code{copy-range-method} (default: @code{"standard"})
@item @code{case-sensitive-file-system?} (default: @code{#f})
@item @code{junctions-as-dirs?} (default: @code{#f})
@item @code{sync-ownership?} (default: @code{#f})
@item @code{send-ownership?} (default: @code{#f})
@item @code{sync-xattrs?} (default: @code{#f})
@item @code{send-xattrs?} (default: @code{#f})
@item @code{xattr-filter-max-single-entry-size} (default: @code{1024})
@item @code{xattr-filter-max-total-size} (default: @code{4096})
@end table
@end deftp

@deftp {Data Type} syncthing-device
Data type representing a device to synchronize folders with.

@table @asis
@item @code{id}
A long hash representing the keys generated by Syncthing on the first
launch.  You can obtain this from the Syncthing GUI or by inspecting an
existing Syncthing configuration file.

@item @code{name} (default: @code{""})
A human readable device name for viewing in the GUI or in Scheme.

@item @code{compression} (default: @code{"metadata"})
@item @code{introducer?} (default: @code{#f})
@item @code{skip-introduction-removals?} (default: @code{#f})
@item @code{introduced-by} (default: @code{""})
@item @code{addresses} (default: @code{'("dynamic")})
List of addresses at which to search for this device.  When the special
value ``dynamic'' is included, Syncthing will search for the device locally
as well as via the Syncthing project's
@uref{https://docs.syncthing.net/users/security.html#global-discovery,
global discovery} servers.

@item @code{paused?} (default: @code{#f})
@item @code{auto-accept-folders?} (default: @code{#f})
@item @code{max-send-kbps} (default: @code{0})
@item @code{max-receive-kbps} (default: @code{0})
@item @code{max-request-kib} (default: @code{0})
@item @code{untrusted?} (default: @code{#f})
@item @code{remote-gui-port} (default: @code{0})
@item @code{num-connections} (default: @code{0})

@end table
@end deftp

@deftp {Data Type} syncthing-folder-device
This data type offers two folder-specific device options:
@code{introduced-by} and @code{encryption-password}.

@code{syncthing-folder-device} corresponds to the
@uref{https://docs.syncthing.net/users/config.html#config-option-folder.device,
`device'} option in the upstream `folder' element.

If you don't need to use these options, then you can just use
@code{syncthing-device} instead of @code{syncthing-folder-device} in the
@code{devices} field of a @code{syncthing-folder} instance.

@table @asis
@item @code{device}
The @code{syncthing-device} for which this configuration applies.

@item @code{introduced-by} (default: @code{""})
The name of the device that "introduced" our device to the device sharing
this folder.  This is only used when "introduced" devices are removed by the
introducer.  See @uref{https://docs.syncthing.net/users/introducer.html,
Syncthing introductions}.

@item @code{encryption-password} (default: @code{""})
The password used to encrypt data that is synchronized to untrusted devices.

Beware: specifying this field will include this password as plain text (not
encrypted) and globally visible in @file{/gnu/store/}.  If the
encryption-password is non-empty, then it will be used as a password to
encrypt file chunks as they are synchronized to untrusted devices.  For more
information on syncing to devices you don't totally trust, see Syncthing's
documentation on @uref{https://docs.syncthing.net/users/untrusted.html,
Untrusted (Encrypted) Devices}.  Note that data transfer is always encrypted
while in transport ("end-to-end encryption"), regardless of this setting.

@end table
@end deftp

Here is a more complex example configuration for illustrative purposes:

@lisp
(service syncthing-service-type
         (let ((laptop (syncthing-device (id "VHOD2D6-...-7XRMDEN")))
               (desktop (syncthing-device (id "64SAZ37-...-FZJ5GUA")
                                          (addresses '("tcp://example.com"))))
               (bob-desktop (syncthing-device (id "KYIMEGO-...-FT77EAO"))))
           (syncthing-configuration
            (user "alice")
            (config-file
             (syncthing-config-file
               (folders (list (syncthing-folder
                               (label "some-files")
                               (path "~/data")
                               (devices (list desktop laptop)))
                              (syncthing-folder
                               (label "critical-files")
                               (path "~/secrets")
                               (devices
                                (list desktop
                                      laptop
                                      (syncthing-folder-device
                                       (device bob-desktop)
                                       (encryption-password "mypassword"))))))))))))
@end lisp


Furthermore, @code{(gnu services ssh)} provides the following services.
@cindex SSH
@cindex SSH server
@defvar openssh-service-type
This is the type for the @uref{http://www.openssh.org, OpenSSH} secure shell
daemon, @command{sshd}.  Its value must be an @code{openssh-configuration}
record as in this example:

@lisp
(service openssh-service-type
         (openssh-configuration
           (x11-forwarding? #t)
           (permit-root-login 'prohibit-password)
           (authorized-keys
             `(("alice" ,(local-file "alice.pub"))
               ("bob" ,(local-file "bob.pub"))))))
@end lisp

See below for details about @code{openssh-configuration}.

This service can be extended with extra authorized keys, as in this example:

@lisp
(service-extension openssh-service-type
                   (const `(("charlie"
                             ,(local-file "charlie.pub")))))
@end lisp
@end defvar

@deftp {Tipo de dados} openssh-configuration
This is the configuration record for OpenSSH's @command{sshd}.

@table @asis
@item @code{openssh} (default @var{openssh})
The OpenSSH package to use.

@item @code{pid-file} (default: @code{"/var/run/sshd.pid"})
Name of the file where @command{sshd} writes its PID.

@item @code{port-number} (default: @code{22})
TCP port on which @command{sshd} listens for incoming connections.

@item @code{max-connections} (default: @code{200})
Hard limit on the maximum number of simultaneous client connections,
enforced by the inetd-style Shepherd service (@pxref{Service De- and Constructors, @code{make-inetd-constructor},, shepherd, The GNU Shepherd
Manual}).

@item @code{permit-root-login} (default: @code{#f})
This field determines whether and when to allow logins as root.  If
@code{#f}, root logins are disallowed; if @code{#t}, they are allowed.  If
it's the symbol @code{'prohibit-password}, then root logins are permitted
but not with password-based authentication.

@item @code{allow-empty-passwords?} (default: @code{#f})
When true, users with empty passwords may log in.  When false, they may not.

@item @code{password-authentication?} (default: @code{#t})
When true, users may log in with their password.  When false, they have
other authentication methods.

@item @code{public-key-authentication?} (default: @code{#t})
When true, users may log in using public key authentication.  When false,
users have to use other authentication method.

Authorized public keys are stored in @file{~/.ssh/authorized_keys}.  This is
used only by protocol version 2.

@item @code{x11-forwarding?} (padrão: @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?} (padrão: @code{#t})
Whether to allow agent forwarding.

@item @code{allow-tcp-forwarding?} (padrão: @code{#t})
Whether to allow TCP forwarding.

@item @code{gateway-ports?} (padrão: @code{#f})
Whether to allow gateway ports.

@item @code{challenge-response-authentication?} (default: @code{#f})
Specifies whether challenge response authentication is allowed (e.g.@: via
PAM).

@item @code{use-pam?} (default: @code{#t})
Enables the Pluggable Authentication Module interface.  If set to @code{#t},
this will enable PAM authentication using
@code{challenge-response-authentication?} and
@code{password-authentication?}, in addition to PAM account and session
module processing for all authentication types.

Because PAM challenge response authentication usually serves an equivalent
role to password authentication, you should disable either
@code{challenge-response-authentication?} or
@code{password-authentication?}.

@item @code{print-last-log?} (default: @code{#t})
Specifies whether @command{sshd} should print the date and time of the last
user login when a user logs in interactively.

@item @code{subsystems} (default: @code{'(("sftp" "internal-sftp"))})
Configures external subsystems (e.g.@: file transfer daemon).

This is a list of two-element lists, each of which containing the subsystem
name and a command (with optional arguments) to execute upon subsystem
request.

The command @command{internal-sftp} implements an in-process SFTP server.
Alternatively, one can specify the @command{sftp-server} command:
@lisp
(service openssh-service-type
         (openssh-configuration
          (subsystems
           `(("sftp" ,(file-append openssh "/libexec/sftp-server"))))))
@end lisp

@item @code{accepted-environment} (default: @code{'()})
List of strings describing which environment variables may be exported.

Each string gets on its own line.  See the @code{AcceptEnv} option in
@code{man sshd_config}.

This example allows ssh-clients to export the @env{COLORTERM} variable.  It
is set by terminal emulators, which support colors.  You can use it in your
shell's resource file to enable colors for the prompt and commands if this
variable is set.

@lisp
(service openssh-service-type
         (openssh-configuration
           (accepted-environment '("COLORTERM"))))
@end lisp

@item @code{authorized-keys} (default: @code{'()})
@cindex authorized keys, SSH
@cindex SSH authorized keys
This is the list of authorized keys.  Each element of the list is a user
name followed by one or more file-like objects that represent SSH public
keys.  For example:

@lisp
(openssh-configuration
  (authorized-keys
    `(("rekado" ,(local-file "rekado.pub"))
      ("chris" ,(local-file "chris.pub"))
      ("root" ,(local-file "rekado.pub") ,(local-file "chris.pub")))))
@end lisp

@noindent
registers the specified public keys for user accounts @code{rekado},
@code{chris}, and @code{root}.

Additional authorized keys can be specified @i{via}
@code{service-extension}.

Note that this does @emph{not} interfere with the use of
@file{~/.ssh/authorized_keys}.

@item @code{generate-host-keys?} (default: @code{#t})
Whether to generate host key pairs with @command{ssh-keygen -A} under
@file{/etc/ssh} if there are none.

Generating key pairs takes a few seconds when enough entropy is available
and is only done once.  You might want to turn it off for instance in a
virtual machine that does not need it because host keys are provided in some
other way, and where the extra boot time is a problem.

@item @code{log-level} (default: @code{'info})
This is a symbol specifying the logging level: @code{quiet}, @code{fatal},
@code{error}, @code{info}, @code{verbose}, @code{debug}, etc.  See the man
page for @file{sshd_config} for the full list of level names.

@item @code{extra-content} (default: @code{""})
This field can be used to append arbitrary text to the configuration file.
It is especially useful for elaborate configurations that cannot be
expressed otherwise.  This configuration, for example, would generally
disable root logins, but permit them from one specific IP address:

@lisp
(openssh-configuration
  (extra-content "\
Match Address 192.168.0.1
  PermitRootLogin yes"))
@end lisp

@end table
@end deftp

@defvar dropbear-service-type
Type of the service that runs the
@url{https://matt.ucc.asn.au/dropbear/dropbear.html, Dropbear SSH daemon},
whose value is a @code{<dropbear-configuration>} object.

For example, to specify a Dropbear service listening on port 1234:

@lisp
(service dropbear-service-type (dropbear-configuration
                                 (port-number 1234)))
@end lisp
@end defvar

@deftp {Tipo de dados} dropbear-configuration
This data type represents the configuration of a Dropbear SSH daemon.

@table @asis
@item @code{dropbear} (default: @var{dropbear})
The Dropbear package to use.

@item @code{port-number} (default: 22)
The TCP port where the daemon waits for incoming connections.

@item @code{syslog-output?} (padrão: @code{#t})
Whether to enable syslog output.

@item @code{pid-file} (default: @code{"/var/run/dropbear.pid"})
File name of the daemon's PID file.

@item @code{root-login?} (default: @code{#f})
Whether to allow @code{root} logins.

@item @code{allow-empty-passwords?} (default: @code{#f})
Whether to allow empty passwords.

@item @code{password-authentication?} (default: @code{#t})
Whether to enable password-based authentication.
@end table
@end deftp

@cindex AutoSSH
@defvar autossh-service-type
This is the type for the @uref{https://www.harding.motd.ca/autossh, AutoSSH}
program that runs a copy of @command{ssh} and monitors it, restarting it as
necessary should it die or stop passing traffic.  AutoSSH can be run
manually from the command-line by passing arguments to the binary
@command{autossh} from the package @code{autossh}, but it can also be run as
a Guix service.  This latter use case is documented here.

AutoSSH can be used to forward local traffic to a remote machine using an
SSH tunnel, and it respects the @file{~/.ssh/config} of the user it is run
as.

For example, to specify a service running autossh as the user @code{pino}
and forwarding all local connections to port @code{8081} to
@code{remote:8081} using an SSH tunnel, add this call to the operating
system's @code{services} field:

@lisp
(service autossh-service-type
         (autossh-configuration
          (user "pino")
          (ssh-options (list "-T" "-N" "-L" "8081:localhost:8081" "remote.net"))))
@end lisp
@end defvar

@deftp {Tipo de dados} autossh-configuration
This data type represents the configuration of an AutoSSH service.

@table @asis

@item @code{user} (default @code{"autossh"})
The user as which the AutoSSH service is to be run.  This assumes that the
specified user exists.

@item @code{poll} (default @code{600})
Specifies the connection poll time in seconds.

@item @code{first-poll} (default @code{#f})
Specifies how many seconds AutoSSH waits before the first connection test.
After this first test, polling is resumed at the pace defined in
@code{poll}.  When set to @code{#f}, the first poll is not treated specially
and will also use the connection poll specified in @code{poll}.

@item @code{gate-time} (default @code{30})
Specifies how many seconds an SSH connection must be active before it is
considered successful.

@item @code{log-level} (default @code{1})
The log level, corresponding to the levels used by syslog---so @code{0} is
the most silent while @code{7} is the chattiest.

@item @code{max-start} (default @code{#f})
The maximum number of times SSH may be (re)started before AutoSSH exits.
When set to @code{#f}, no maximum is configured and AutoSSH may restart
indefinitely.

@item @code{message} (default @code{""})
The message to append to the echo message sent when testing connections.

@item @code{port} (padrão @code{"0"})
The ports used for monitoring the connection.  When set to @code{"0"},
monitoring is disabled.  When set to @code{"@var{n}"} where @var{n} is a
positive integer, ports @var{n} and @var{n}+1 are used for monitoring the
connection, such that port @var{n} is the base monitoring port and
@code{n+1} is the echo port.  When set to @code{"@var{n}:@var{m}"} where
@var{n} and @var{m} are positive integers, the ports @var{n} and @var{m} are
used for monitoring the connection, such that port @var{n} is the base
monitoring port and @var{m} is the echo port.

@item @code{ssh-options} (default @code{'()})
The list of command-line arguments to pass to @command{ssh} when it is run.
Options @option{-f} and @option{-M} are reserved for AutoSSH and may cause
undefined behaviour.

@end table
@end deftp

@cindex WebSSH
@defvar webssh-service-type
This is the type for the @uref{https://webssh.huashengdun.org/, WebSSH}
program that runs a web SSH client.  WebSSH can be run manually from the
command-line by passing arguments to the binary @command{wssh} from the
package @code{webssh}, but it can also be run as a Guix service.  This
latter use case is documented here.

For example, to specify a service running WebSSH on loopback interface on
port @code{8888} with reject policy with a list of allowed to connection
hosts, and NGINX as a reverse-proxy to this service listening for HTTPS
connection, add this call to the operating system's @code{services} field:

@lisp
(service webssh-service-type
  (webssh-configuration (address "127.0.0.1")
                        (port 8888)
                        (policy 'reject)
                        (known-hosts '("localhost ecdsa-sha2-nistp256 AAAA…"
                                       "127.0.0.1 ecdsa-sha2-nistp256 AAAA…"))))

(service nginx-service-type
         (nginx-configuration
          (server-blocks
           (list
            (nginx-server-configuration
             (inherit %webssh-configuration-nginx)
             (server-name '("webssh.example.com"))
             (listen '("443 ssl"))
             (ssl-certificate (letsencrypt-certificate "webssh.example.com"))
             (ssl-certificate-key (letsencrypt-key "webssh.example.com"))
             (locations
              (cons (nginx-location-configuration
                     (uri "/.well-known")
                     (body '("root /var/www;")))
                    (nginx-server-configuration-locations %webssh-configuration-nginx))))))))
@end lisp
@end defvar

@deftp {Tipo de dados} webssh-configuration
Data type representing the configuration for @code{webssh-service}.

@table @asis
@item @code{package} (default: @var{webssh})
@code{webssh} package to use.

@item @code{user-name} (default: @var{"webssh"})
User name or user ID that file transfers to and from that module should take
place.

@item @code{group-name} (default: @var{"webssh"})
Group name or group ID that will be used when accessing the module.

@item @code{address} (default: @var{#f})
IP address on which @command{webssh} listens for incoming connections.

@item @code{port} (padrão: @var{8888})
TCP port on which @command{webssh} listens for incoming connections.

@item @code{policy} (default: @var{#f})
Connection policy.  @var{reject} policy requires to specify
@var{known-hosts}.

@item @code{known-hosts} (default: @var{'()})
List of hosts which allowed for SSH connection from @command{webssh}.

@item @code{log-file} (default: @file{"/var/log/webssh.log"})
Name of the file where @command{webssh} writes its log file.

@item @code{log-level} (default: @var{#f})
Logging level.

@end table
@end deftp

@defvar block-facebook-hosts-service-type
This service type adds a list of known Facebook hosts to the
@file{/etc/hosts} file.  (@pxref{Host Names,,, libc, The GNU C Library
Reference Manual})  Each line contains an entry that maps a known server
name of the Facebook on-line service---e.g., @code{www.facebook.com}---to
unroutable IPv4 and IPv6 addresses.

This mechanism can prevent programs running locally, such as Web browsers,
from accessing Facebook.
@end defvar

The @code{(gnu services avahi)} provides the following definition.

@defvar avahi-service-type
This is the service that runs @command{avahi-daemon}, a system-wide
mDNS/DNS-SD responder that allows for service discovery and
``zero-configuration'' host name lookups (see @uref{https://avahi.org/}).
Its value must be an @code{avahi-configuration} record---see below.

This service extends the name service cache daemon (nscd) so that it can
resolve @code{.local} host names using
@uref{https://0pointer.de/lennart/projects/nss-mdns/, nss-mdns}.  @xref{Name Service Switch}, for information on host name resolution.

Additionally, add the @var{avahi} package to the system profile so that
commands such as @command{avahi-browse} are directly usable.
@end defvar

@deftp {Tipo de dados} avahi-configuration
Data type representation the configuration for Avahi.

@table @asis

@item @code{host-name} (padrão: @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?} (padrão: @code{#t})
When true, allow host names and services to be published (broadcast) over
the network.

@item @code{publish-workstation?} (padrão: @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?} (padrão: @code{#f})
When true, DNS-SD over unicast DNS is enabled.

@item @code{ipv4?} (default: @code{#t})
@itemx @code{ipv6?} (default: @code{#t})
These fields determine whether to use IPv4/IPv6 sockets.

@item @code{domains-to-browse} (default: @code{'()})
This is a list of domains to browse.
@end table
@end deftp

@defvar openvswitch-service-type
This is the type of the @uref{https://www.openvswitch.org, Open vSwitch}
service, whose value should be an @code{openvswitch-configuration} object.
@end defvar

@deftp {Tipo de dados} openvswitch-configuration
Data type representing the configuration of Open vSwitch, a multilayer
virtual switch which is designed to enable massive network automation
through programmatic extension.

@table @asis
@item @code{package} (default: @var{openvswitch})
Package object of the Open vSwitch.

@end table
@end deftp

@defvar pagekite-service-type
This is the service type for the @uref{https://pagekite.net, PageKite}
service, a tunneling solution for making localhost servers publicly visible,
even from behind restrictive firewalls or NAT without forwarded ports.  The
value for this service type is a @code{pagekite-configuration} record.

Here's an example exposing the local HTTP and SSH daemons:

@lisp
(service pagekite-service-type
         (pagekite-configuration
           (kites '("http:@@kitename:localhost:80:@@kitesecret"
                    "raw/22:@@kitename:localhost:22:@@kitesecret"))
           (extra-file "/etc/pagekite.rc")))
@end lisp
@end defvar

@deftp {Tipo de dados} pagekite-configuration
Data type representing the configuration of PageKite.

@table @asis
@item @code{package} (default: @var{pagekite})
Package object of PageKite.

@item @code{kitename} (default: @code{#f})
PageKite name for authenticating to the frontend server.

@item @code{kitesecret} (default: @code{#f})
Shared secret for authenticating to the frontend server.  You should
probably put this inside @code{extra-file} instead.

@item @code{frontend} (default: @code{#f})
Connect to the named PageKite frontend server instead of the
@uref{https://pagekite.net,,pagekite.net} service.

@item @code{kites} (default: @code{'("http:@@kitename:localhost:80:@@kitesecret")})
List of service kites to use.  Exposes HTTP on port 80 by default.  The
format is @code{proto:kitename:host:port:secret}.

@item @code{extra-file} (default: @code{#f})
Extra configuration file to read, which you are expected to create
manually.  Use this to add additional options and manage shared secrets
out-of-band.

@end table
@end deftp

@defvar yggdrasil-service-type
The service type for connecting to the
@uref{https://yggdrasil-network.github.io/, Yggdrasil network}, an
early-stage implementation of a fully end-to-end encrypted IPv6 network.

@quotation
Yggdrasil provides name-independent routing with cryptographically generated
addresses.  Static addressing means you can keep the same address as long as
you want, even if you move to a new location, or generate a new address (by
generating new keys) whenever you want.
@uref{https://yggdrasil-network.github.io/2018/07/28/addressing.html}
@end quotation

Pass it a value of @code{yggdrasil-configuration} to connect it to public
peers and/or local peers.

Here is an example using public peers and a static address.  The static
signing and encryption keys are defined in
@file{/etc/yggdrasil-private.conf} (the default value for
@code{config-file}).

@lisp
;; part of the operating-system declaration
(service yggdrasil-service-type
              (yggdrasil-configuration
               (autoconf? #f) ;; use only the public peers
               (json-config
               ;; choose one from
               ;; https://github.com/yggdrasil-network/public-peers
                '((peers . #("tcp://1.2.3.4:1337"))))
               ;; /etc/yggdrasil-private.conf is the default value for config-file
               ))
@end lisp
@example
# sample content for /etc/yggdrasil-private.conf
@{
  # Your private key. DO NOT share this with anyone!
  PrivateKey: 5c750...
@}
@end example
@end defvar

@deftp {Tipo de dados} yggdrasil-configuration
Data type representing the configuration of Yggdrasil.

@table @asis
@item @code{package} (default: @code{yggdrasil})
Package object of Yggdrasil.

@item @code{json-config} (default: @code{'()})
Contents of @file{/etc/yggdrasil.conf}.  Will be merged with
@file{/etc/yggdrasil-private.conf}.  Note that these settings are stored in
the Guix store, which is readable to all users. @strong{Do not store your
private keys in it}.  See the output of @code{yggdrasil -genconf} for a
quick overview of valid keys and their default values.

@item @code{autoconf?} (default: @code{#f})
Whether to use automatic mode.  Enabling it makes Yggdrasil use a dynamic IP
and peer with IPv6 neighbors.

@item @code{log-level} (default: @code{'info})
How much detail to include in logs.  Use @code{'debug} for more detail.

@item @code{log-to} (default: @code{'stdout})
Where to send logs.  By default, the service logs standard output to
@file{/var/log/yggdrasil.log}.  The alternative is @code{'syslog}, which
sends output to the running syslog service.

@item @code{config-file} (default: @code{"/etc/yggdrasil-private.conf"})
What HJSON file to load sensitive data from.  This is where private keys
should be stored, which are necessary to specify if you don't want a
randomized address after each restart.  Use @code{#f} to disable.  Options
defined in this file take precedence over @code{json-config}.  Use the
output of @code{yggdrasil -genconf} as a starting point.  To configure a
static address, delete everything except PrivateKey option.

@end table
@end deftp

@cindex IPFS
@defvar ipfs-service-type
The service type for connecting to the @uref{https://ipfs.io,IPFS network},
a global, versioned, peer-to-peer file system. Pass it a
@code{ipfs-configuration} to change the ports used for the gateway and API.

Here's an example configuration, using some non-standard ports:

@lisp
(service ipfs-service-type
         (ipfs-configuration
          (gateway "/ip4/127.0.0.1/tcp/8880")
          (api "/ip4/127.0.0.1/tcp/8881")))
@end lisp
@end defvar

@deftp {Tipo de dados} ipfs-configuration
Data type representing the configuration of IPFS.

@table @asis
@item @code{package} (default: @code{go-ipfs})
Package object of IPFS.

@item @code{gateway} (default: @code{"/ip4/127.0.0.1/tcp/8082"})
Address of the gateway, in ‘multiaddress’ format.

@item @code{api} (default: @code{"/ip4/127.0.0.1/tcp/5001"})
Address of the API endpoint, in ‘multiaddress’ format.
@end table
@end deftp

@cindex keepalived
@defvar keepalived-service-type
This is the type for the @uref{https://www.keepalived.org/, Keepalived}
routing software, @command{keepalived}.  Its value must be an
@code{keepalived-configuration} record as in this example for master
machine:

@lisp
(service keepalived-service-type
         (keepalived-configuration
           (config-file (local-file "keepalived-master.conf"))))
@end lisp

where @file{keepalived-master.conf}:

@example
vrrp_instance my-group @{
  state MASTER
  interface enp9s0
  virtual_router_id 100
  priority 100
  unicast_peer @{ 10.0.0.2 @}
  virtual_ipaddress @{
    10.0.0.4/24
  @}
@}
@end example

and for backup machine:

@lisp
(service keepalived-service-type
         (keepalived-configuration
          (config-file (local-file "keepalived-backup.conf"))))
@end lisp

where @file{keepalived-backup.conf}:

@example
vrrp_instance my-group @{
  state BACKUP
  interface enp9s0
  virtual_router_id 100
  priority 99
  unicast_peer @{ 10.0.0.3 @}
  virtual_ipaddress @{
    10.0.0.4/24
  @}
@}
@end example
@end defvar

@node Atualizações sem supervisão
@subsection Atualizações sem supervisão

@cindex unattended upgrades
@cindex upgrades, unattended
The @code{(gnu services admin)} module provides a service to perform
@emph{unattended upgrades}: periodically, the system automatically
reconfigures itself from the latest Guix.  Guix System has several
properties that make unattended upgrades safe:

@itemize
@item
upgrades are transactional (either the upgrade succeeds or it fails, but you
cannot end up with an ``in-between'' system state);
@item
the upgrade log is kept---you can view it with @command{guix system
list-generations}---and you can roll back to any previous generation, should
the upgraded system fail to behave as intended;
@item
channel code is authenticated so you know you can only run genuine code
(@pxref{Canais});
@item
@command{guix system reconfigure} prevents downgrades, which makes it immune
to @dfn{downgrade attacks}.
@end itemize

To set up unattended upgrades, add an instance of
@code{unattended-upgrade-service-type} like the one below to the list of
your operating system services:

@lisp
(service unattended-upgrade-service-type)
@end lisp

The defaults above set up weekly upgrades: every Sunday at midnight.  You do
not need to provide the operating system configuration file: it uses
@file{/run/current-system/configuration.scm}, which ensures it always uses
your latest configuration---@pxref{provenance-service-type}, for more
information about this file.

There are several things that can be configured, in particular the
periodicity and services (daemons) to be restarted upon completion.  When
the upgrade is successful, the service takes care of deleting system
generations older that some threshold, as per @command{guix system
delete-generations}.  See the reference below for details.

To ensure that upgrades are actually happening, you can run @command{guix
system describe}.  To investigate upgrade failures, visit the unattended
upgrade log file (see below).

@defvar unattended-upgrade-service-type
This is the service type for unattended upgrades.  It sets up a Shepherd
Timer (@pxref{Execução de trabalho agendado}) that runs @command{guix system
reconfigure} from the latest version of the specified channels.

Its value must be a @code{unattended-upgrade-configuration} record (see
below).
@end defvar

@deftp {Tipo de dados} unattended-upgrade-configuration
This data type represents the configuration of the unattended upgrade
service.  The following fields are available:

@table @asis
@item @code{schedule} (default: @code{"30 01 * * 0"})
This is the schedule of upgrades, expressed as a string in traditional cron
syntax or as a gexp evaluating to a Shepherd calendar event
(@pxref{Timers,,, shepherd, The GNU Shepherd Manual}).

@item @code{channels} (default: @code{#~%default-channels})
This gexp specifies the channels to use for the upgrade (@pxref{Canais}).
By default, the tip of the official @code{guix} channel is used.

@item @code{operating-system-file} (default: @code{"/run/current-system/configuration.scm"})
This field specifies the operating system configuration file to use.  The
default is to reuse the config file of the current configuration.

There are cases, though, where referring to
@file{/run/current-system/configuration.scm} is not enough, for instance
because that file refers to extra files (SSH public keys, extra
configuration files, etc.) @i{via} @code{local-file} and similar
constructs.  For those cases, we recommend something along these lines:

@lisp
(unattended-upgrade-configuration
  (operating-system-file
    (file-append (local-file "." "config-dir" #:recursive? #t)
                 "/config.scm")))
@end lisp

The effect here is to import all of the current directory into the store,
and to refer to @file{config.scm} within that directory.  Therefore, uses of
@code{local-file} within @file{config.scm} will work as expected.
@xref{Expressões-G}, for information about @code{local-file} and
@code{file-append}.

@item @code{operating-system-expression} (default: @code{#f})
This field specifies an expression that evaluates to the operating system to
use for the upgrade.  If no value is provided the
@code{operating-system-file} field value is used.

@lisp
(unattended-upgrade-configuration
  (operating-system-expression
    #~(@@ (guix system install) installation-os)))
@end lisp

@item @code{reboot?} (default: @code{#f})
This field specifies whether the system should reboot after completing an
unattended upgrade.

When @code{reboot?} is @code{#t}, services are not restarted before
rebooting.  This means that the value for @code{services-to-restart} is
ignored.  The updated services will be started after the system reboots.

@item @code{services-to-restart} (default: @code{'(unattended-upgrade)})
This field specifies the Shepherd services to restart when the upgrade
completes.

Those services are restarted right away upon completion, as with
@command{herd restart}, which ensures that the latest version is
running---remember that by default @command{guix system reconfigure} only
restarts services that are not currently running, which is conservative: it
minimizes disruption but leaves outdated services running.

Use @command{herd status} to find out candidates for restarting.
@xref{Serviços}, for general information about services.  Common services to
restart would include @code{ntpd} and @code{ssh-daemon}.

By default, the @code{unattended-upgrade} service is restarted.  This
ensures that the latest version of the unattended upgrade job will be used
next time.

@item @code{system-expiration} (default: @code{(* 3 30 24 3600)})
This is the expiration time in seconds for system generations.  System
generations older that this amount of time are deleted with @command{guix
system delete-generations} when an upgrade completes.

@quotation Nota
The unattended upgrade service does not run the garbage collector.  You will
probably want to set up your own mcron job to run @command{guix gc}
periodically.
@end quotation

@item @code{maximum-duration} (default: @code{3600})
Maximum duration in seconds for the upgrade; past that time, the upgrade
aborts.

This is primarily useful to ensure the upgrade does not end up rebuilding or
re-downloading ``the world''.

@item @code{log-file} (default: @code{"/var/log/unattended-upgrade.log"})
File where unattended upgrades are logged.
@end table
@end deftp

@node X Window
@subsection X Window

@cindex X11
@cindex X Window System
@cindex login manager
Support for the X Window graphical display system---specifically Xorg---is
provided by the @code{(gnu services xorg)} module.  Note that there is no
@code{xorg-service} procedure.  Instead, the X server is started by the
@dfn{login manager}, by default the GNOME Display Manager (GDM).

@cindex GDM
@cindex GNOME, login manager
@anchor{gdm}
GDM of course allows users to log in into window managers and desktop
environments other than GNOME; for those using GNOME, GDM is required for
features such as automatic screen locking.

@cindex gerenciadores de janelas
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{Referência do operating-system, system-wide packages}).

GDM also supports Wayland: it can itself use Wayland instead of X11 for its
user interface, and it can also start Wayland sessions.  Wayland support is
enabled by default.  To disable it, set @code{wayland?} to @code{#f} in
@code{gdm-configuration}.

@defvar gdm-service-type
This is the type for the @uref{https://wiki.gnome.org/Projects/GDM/, GNOME
Desktop Manager} (GDM), a program that manages graphical display servers and
handles graphical user logins.  Its value must be a @code{gdm-configuration}
(see below).

@cindex session types
GDM looks for @dfn{session types} described by the @file{.desktop} files in
@file{/run/current-system/profile/share/xsessions} (for X11 sessions) and
@file{/run/current-system/profile/share/wayland-sessions} (for Wayland
sessions) and allows users to choose a session from the log-in screen.
Packages such as @code{gnome}, @code{xfce}, @code{i3} and @code{sway}
provide @file{.desktop} files; adding them to the system-wide set of
packages automatically makes them available at the log-in screen.

In addition, @file{~/.xsession} files are honored.  When available,
@file{~/.xsession} must be an executable that starts a window manager and/or
other X clients.
@end defvar

@deftp {Tipo de dados} gdm-configuration
@table @asis
@item @code{auto-login?} (default: @code{#f})
@itemx @code{default-user} (default: @code{#f})
When @code{auto-login?} is false, GDM presents a log-in screen.

When @code{auto-login?} is true, GDM logs in directly as
@code{default-user}.

@item @code{auto-suspend?} (default @code{#t})
When true, GDM will automatically suspend to RAM when nobody is physically
connected.  When a machine is used via remote desktop or SSH, this should be
set to false to avoid GDM interrupting remote sessions or rendering the
machine unavailable.

@item @code{debug?} (default: @code{#f})
When true, GDM writes debug messages to its log.

@item @code{gnome-shell-assets} (default: ...)
List of GNOME Shell assets needed by GDM: icon theme, fonts, etc.

@item @code{xorg-configuration} (default: @code{(xorg-configuration)})
Configuration of the Xorg graphical server.

@item @code{x-session} (default: @code{(xinitrc)})
Script to run before starting a X session.

@item @code{xdmcp?} (default: @code{#f})
When true, enable the X Display Manager Control Protocol (XDMCP).  This
should only be enabled in trusted environments, as the protocol is not
secure.  When enabled, GDM listens for XDMCP queries on the UDP port 177.

@item @code{dbus-daemon} (default: @code{dbus-daemon-wrapper})
File name of the @code{dbus-daemon} executable.

@item @code{gdm} (default: @code{gdm})
The GDM package to use.

@item @code{wayland?} (default: @code{#t})
When true, enables Wayland in GDM, necessary to use Wayland sessions.

@item @code{wayland-session} (default: @code{gdm-wayland-session-wrapper})
The Wayland session wrapper to use, needed to setup the environment.
@end table
@end deftp

@defvar slim-service-type
This is the type for the SLiM graphical login manager for X11.

Like GDM, SLiM looks for session types described by @file{.desktop} files
and allows users to choose a session from the log-in screen using @kbd{F1}.
It also honors @file{~/.xsession} files.

Unlike GDM, SLiM does not spawn the user session on a different VT after
logging in, which means that you can only start one graphical session.  If
you want to be able to run multiple graphical sessions at the same time you
have to add multiple SLiM services to your system services.  The following
example shows how to replace the default GDM service with two SLiM services
on tty7 and tty8.

@lisp
(use-modules (gnu services)
             (gnu services desktop)
             (gnu services xorg))

(operating-system
  ;; ...
  (services (cons* (service slim-service-type (slim-configuration
                                               (display ":0")
                                               (vt "vt7")))
                   (service slim-service-type (slim-configuration
                                               (display ":1")
                                               (vt "vt8")))
                   (modify-services %desktop-services
                     (delete gdm-service-type)))))
@end lisp

@end defvar

@deftp {Tipo de dados} slim-configuration
Data type representing the configuration of @code{slim-service-type}.

@table @asis
@item @code{allow-empty-passwords?} (default: @code{#t})
Whether to allow logins with empty passwords.

@item @code{gnupg?} (default: @code{#f})
If enabled, @code{pam-gnupg} will attempt to automatically unlock the user's
GPG keys with the login password via @code{gpg-agent}.  The keygrips of all
keys to be unlocked should be written to @file{~/.pam-gnupg}, and can be
queried with @code{gpg -K --with-keygrip}.  Presetting passphrases must be
enabled by adding @code{allow-preset-passphrase} in
@file{~/.gnupg/gpg-agent.conf}.

@item @code{auto-login?} (default: @code{#f})
@itemx @code{default-user} (default: @code{""})
When @code{auto-login?} is false, SLiM presents a log-in screen.

When @code{auto-login?} is true, SLiM logs in directly as
@code{default-user}.

@item @code{theme} (default: @code{%default-slim-theme})
@itemx @code{theme-name} (default: @code{%default-slim-theme-name})
The graphical theme to use and its name.

@item @code{auto-login-session} (default: @code{#f})
If true, this must be the name of the executable to start as the default
session---e.g., @code{(file-append windowmaker "/bin/windowmaker")}.

If false, a session described by one of the available @file{.desktop} files
in @code{/run/current-system/profile} and @code{~/.guix-profile} will be
used.

@quotation 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{display} (default @code{":0"})
The display on which to start the Xorg graphical server.

@item @code{vt} (default @code{"vt7"})
The VT on which to start the Xorg graphical server.

@item @code{xauth} (default: @code{xauth})
The XAuth package to use.

@item @code{shepherd} (default: @code{shepherd})
The Shepherd package used when invoking @command{halt} and @command{reboot}.

@item @code{sessreg} (default: @code{sessreg})
The sessreg package used in order to register the session.

@item @code{slim} (default: @code{slim})
The SLiM package to use.
@end table
@end deftp

@defvar %default-theme
@defvarx %default-theme-name
The default SLiM theme and its name.
@end defvar


@cindex login manager
@cindex X11 login
@defvar sddm-service-type
This is the type of the service to run the
@uref{https://github.com/sddm/sddm,SDDM display manager}.  Its value must be
a @code{sddm-configuration} record (see below).

Here's an example use:

@lisp
(service sddm-service-type
         (sddm-configuration
           (auto-login-user "alice")
           (auto-login-session "xfce.desktop")))
@end lisp
@end defvar

@deftp {Tipo de dados} sddm-configuration
This data type represents the configuration of the SDDM login manager.  The
available fields are:

@table @asis
@item @code{sddm} (default: @code{sddm})
The SDDM package to use.

@quotation Nota
sddm has Qt6 enabled by default. If you want to still use a Qt5 theme, you
need to set it to @code{sddm-qt5}.
@end quotation

@item @code{display-server} (default: "x11")
Select display server to use for the greeter.  Valid values are @samp{"x11"}
or @samp{"wayland"}.

@item @code{numlock} (default: "on")
Valid values are @samp{"on"}, @samp{"off"} or @samp{"none"}.

@item @code{halt-command} (default @code{#~(string-append #$shepherd "/sbin/halt")})
Command to run when halting.

@item @code{reboot-command} (default @code{#~(string-append #$shepherd "/sbin/reboot")})
Command to run when rebooting.

@item @code{theme} (default "maldives")
Theme to use.  Default themes provided by SDDM are @samp{"elarun"},
@samp{"maldives"} or @samp{"maya"}.

@item @code{themes-directory} (default "/run/current-system/profile/share/sddm/themes")
Directory to look for themes.

@item @code{faces-directory} (default "/run/current-system/profile/share/sddm/faces")
Directory to look for faces.

@item @code{default-path} (default "/run/current-system/profile/bin")
Default PATH to use.

@item @code{minimum-uid} (default: 1000)
Minimum UID displayed in SDDM and allowed for log-in.

@item @code{maximum-uid} (default: 2000)
Maximum UID to display in SDDM.

@item @code{remember-last-user?} (default #t)
Remember last user.

@item @code{remember-last-session?} (default #t)
Remember last session.

@item @code{hide-users} (default "")
Usernames to hide from SDDM greeter.

@item @code{hide-shells} (default @code{#~(string-append #$shadow "/sbin/nologin")})
Users with shells listed will be hidden from the SDDM greeter.

@item @code{session-command} (default @code{#~(string-append #$sddm "/share/sddm/scripts/wayland-session")})
Script to run before starting a wayland session.

@item @code{sessions-directory} (default "/run/current-system/profile/share/wayland-sessions")
Directory to look for desktop files starting wayland sessions.

@item @code{xorg-configuration} (default @code{(xorg-configuration)})
Configuration of the Xorg graphical server.

@item @code{xauth-path} (default @code{#~(string-append #$xauth "/bin/xauth")})
Path to xauth.

@item @code{xephyr-path} (default @code{#~(string-append #$xorg-server "/bin/Xephyr")})
Path to Xephyr.

@item @code{xdisplay-start} (default @code{#~(string-append #$sddm "/share/sddm/scripts/Xsetup")})
Script to run after starting xorg-server.

@item @code{xdisplay-stop} (default @code{#~(string-append #$sddm "/share/sddm/scripts/Xstop")})
Script to run before stopping xorg-server.

@item @code{xsession-command} (default: @code{xinitrc})
Script to run before starting a X session.

@item @code{xsessions-directory} (default: "/run/current-system/profile/share/xsessions")
Directory to look for desktop files starting X sessions.

@item @code{minimum-vt} (default: 7)
Minimum VT to use.

@item @code{auto-login-user} (default "")
User account that will be automatically logged in.  Setting this to the
empty string disables auto-login.

@item @code{auto-login-session} (default "")
The @file{.desktop} file name to use as the auto-login session, or the empty
string.

@item @code{relogin?} (default #f)
Relogin after logout.

@end table
@end deftp

@cindex lightdm, graphical login manager
@cindex display manager, lightdm
@anchor{lightdm}
@defvar lightdm-service-type
This is the type of the service to run the
@url{https://github.com/canonical/lightdm,LightDM display manager}.  Its
value must be a @code{lightdm-configuration} record, which is documented
below.  Among its distinguishing features are TigerVNC integration for
easily remoting your desktop as well as support for the XDMCP protocol,
which can be used by remote clients to start a session from the login
manager.

In its most basic form, it can be used simply as:

@lisp
(service lightdm-service-type)
@end lisp

A more elaborate example making use of the VNC capabilities and enabling
more features and verbose logs could look like:

@lisp
(service lightdm-service-type
         (lightdm-configuration
          (allow-empty-passwords? #t)
          (xdmcp? #t)
          (vnc-server? #t)
          (vnc-server-command
           (file-append tigervnc-server "/bin/Xvnc"
                        "  -SecurityTypes None"))
          (seats
           (list (lightdm-seat-configuration
                  (name "*")
                  (user-session "ratpoison"))))))
@end lisp
@end defvar

@c The LightDM service documentation can be auto-generated via the
@c 'generate-doc' procedure at the bottom of the (gnu services lightdm)
@c module.
@c %start of fragment
@deftp {Tipo de dados} lightdm-configuration
Available @code{lightdm-configuration} fields are:

@table @asis
@item @code{lightdm} (default: @code{lightdm}) (type: file-like)
The lightdm package to use.

@item @code{allow-empty-passwords?} (default: @code{#f}) (type: boolean)
Whether users not having a password set can login.

@item @code{debug?} (default: @code{#f}) (type: boolean)
Enable verbose output.

@item @code{xorg-configuration} (type: xorg-configuration)
The default Xorg server configuration to use to generate the Xorg server
start script.  It can be refined per seat via the @code{xserver-command} of
the @code{<lightdm-seat-configuration>} record, if desired.

@item @code{greeters} (type: list-of-greeter-configurations)
The LightDM greeter configurations specifying the greeters to use.

@item @code{seats} (type: list-of-seat-configurations)
The seat configurations to use.  A LightDM seat is akin to a user.

@item @code{xdmcp?} (default: @code{#f}) (type: boolean)
Whether a XDMCP server should listen on port UDP 177.

@item @code{xdmcp-listen-address} (type: maybe-string)
The host or IP address the XDMCP server listens for incoming connections.
When unspecified, listen on for any hosts/IP addresses.

@item @code{vnc-server?} (default: @code{#f}) (type: boolean)
Whether a VNC server is started.

@item @code{vnc-server-command} (type: file-like)
The Xvnc command to use for the VNC server, it's possible to provide extra
options not otherwise exposed along the command, for example to disable
security:

@lisp
(vnc-server-command (file-append tigervnc-server "/bin/Xvnc"
                                 " -SecurityTypes None" ))
@end lisp

Or to set a PasswordFile for the classic (unsecure) VncAuth mechanism:

@lisp
(vnc-server-command (file-append tigervnc-server "/bin/Xvnc"
                                 " -PasswordFile /var/lib/lightdm/.vnc/passwd"))
@end lisp

The password file should be manually created using the @command{vncpasswd}
command.  Note that LightDM will create new sessions for VNC users, which
means they need to authenticate in the same way as local users would.

@item @code{vnc-server-listen-address} (type: maybe-string)
The host or IP address the VNC server listens for incoming connections.
When unspecified, listen for any hosts/IP addresses.

@item @code{vnc-server-port} (default: @code{5900}) (type: number)
The TCP port the VNC server should listen to.

@item @code{extra-config} (default: @code{'()}) (type: list-of-strings)
Extra configuration values to append to the LightDM configuration file.

@end table
@end deftp


@c %end of fragment
@c %start of fragment

@deftp {Tipo de dados} lightdm-gtk-greeter-configuration
Available @code{lightdm-gtk-greeter-configuration} fields are:

@table @asis
@item @code{lightdm-gtk-greeter} (default: @code{lightdm-gtk-greeter}) (type: file-like)
The lightdm-gtk-greeter package to use.

@item @code{assets} (default: @code{(adwaita-icon-theme gnome-themes-extra hicolor-icon-theme)}) (type: list-of-file-likes)
The list of packages complementing the greeter, such as package providing
icon themes.

@item @code{theme-name} (default: @code{"Adwaita"}) (type: string)
The name of the theme to use.

@item @code{icon-theme-name} (default: @code{"Adwaita"}) (type: string)
The name of the icon theme to use.

@item @code{cursor-theme-name} (default: @code{"Adwaita"}) (type: string)
The name of the cursor theme to use.

@item @code{cursor-theme-size} (default: @code{16}) (type: number)
The size to use for the cursor theme.

@item @code{allow-debugging?} (type: maybe-boolean)
Set to #t to enable debug log level.

@item @code{background} (type: file-like)
The background image to use.

@item @code{at-spi-enabled?} (default: @code{#f}) (type: boolean)
Enable accessibility support through the Assistive Technology Service
Provider Interface (AT-SPI).

@item @code{a11y-states} (default: @code{(contrast font keyboard reader)}) (type: list-of-a11y-states)
The accessibility features to enable, given as list of symbols.

@item @code{reader} (type: maybe-file-like)
The command to use to launch a screen reader.

@item @code{extra-config} (default: @code{'()}) (type: list-of-strings)
Extra configuration values to append to the LightDM GTK Greeter
configuration file.

@end table
@end deftp

@c %end of fragment
@c %start of fragment

@deftp {Tipo de dados} lightdm-seat-configuration
Available @code{lightdm-seat-configuration} fields are:

@table @asis
@item @code{name} (type: seat-name)
The name of the seat.  An asterisk (*) can be used in the name to apply the
seat configuration to all the seat names it matches.

@item @code{user-session} (type: maybe-string)
The session to use by default.  The session name must be provided as a
lowercase string, such as @code{"gnome"}, @code{"ratpoison"}, etc.

@item @code{type} (default: @code{local}) (type: seat-type)
The type of the seat, either the @code{local} or @code{xremote} symbol.

@item @code{autologin-user} (type: maybe-string)
The username to automatically log in with by default.

@item @code{greeter-session} (default: @code{lightdm-gtk-greeter}) (type: greeter-session)
The greeter session to use, specified as a symbol.  Currently, only
@code{lightdm-gtk-greeter} is supported.

@item @code{xserver-command} (type: maybe-file-like)
The Xorg server command to run.

@item @code{session-wrapper} (type: file-like)
The xinitrc session wrapper to use.

@item @code{extra-config} (default: @code{'()}) (type: list-of-strings)
Extra configuration values to append to the seat configuration section.

@end table
@end deftp
@c %end of fragment


@cindex Xorg, configuration
@deftp {Tipo de dados} xorg-configuration
This data type represents the configuration of the Xorg graphical display
server.  Note that there is no Xorg service; instead, the X server is
started by a ``display manager'' such as GDM, SDDM, LightDM or SLiM@.  Thus,
the configuration of these display managers aggregates an
@code{xorg-configuration} record.

@table @asis
@item @code{modules} (default: @code{%default-xorg-modules})
This is a list of @dfn{module packages} loaded by the Xorg server---e.g.,
@code{xf86-video-vesa}, @code{xf86-input-libinput}, 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 disposição do teclado, para Xorg
@cindex keymap, for Xorg
@item @code{keyboard-layout} (padrão: @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{Disposição do 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 {Procedure} set-xorg-configuration config [login-manager-service-type]
Tell the log-in manager (of type @var{login-manager-service-type}) to use
@var{config}, an @code{<xorg-configuration>} record.

Since the Xorg configuration is embedded in the log-in manager's
configuration---e.g., @code{gdm-configuration}---this procedure provides a
shorthand to set the Xorg configuration.
@end deffn

@deffn {Procedure} xorg-start-command [config]
Return a @code{startx} script in which the modules, fonts, etc. specified in
@var{config}, are available.  The result should be used in place of
@code{startx}.

Usually the X server is started by a login manager.
@end deffn

@deffn {Procedure} xorg-start-command-xinit [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} and should be invoked by the user from a tty after login.
Unlike @code{xorg-start-command}, this script calls xinit.  Therefore it
works well when executed from a tty.  This script can be set up as
@code{startx} using @code{startx-command-service-type} or
@code{home-startx-command-service-type}.  If you are using a desktop
environment, you are unlikely to need this procedure.
@end deffn


@defvar screen-locker-service-type
Type for a service that adds a package for a screen locker or screen saver
to the set of privileged programs and/or add a PAM entry for it.  The value
for this service is a @code{<screen-locker-configuration>} object.

While the default behavior is to setup both a privileged program and PAM
entry, these two methods are redundant.  Screen locker programs may not
execute when PAM is configured and @code{setuid} is set on their
executable.  In this case, @code{using-setuid?} can be set to @code{#f}.

For example, to make XlockMore usable:

@lisp
(service screen-locker-service-type
         (screen-locker-configuration
           (name "xlock")
           (program (file-append xlockmore "/bin/xlock"))))
@end lisp

makes the good ol' XlockMore usable.

For example, swaylock fails to execute when compiled with PAM support and
setuid enabled.  One can thus disable setuid:

@lisp
(service screen-locker-service-type
         (screen-locker-configuration
           (name "swaylock")
           (program (file-append swaylock "/bin/swaylock"))
           (using-pam? #t)
           (using-setuid? #f)))
@end lisp

@end defvar

@deftp {Tipo de dados} screen-locker-configuration
Available @code{screen-locker-configuration} fields are:

@table @asis
@item @code{name} (type: string)
Name of the screen locker.

@item @code{program} (type: file-like)
Path to the executable for the screen locker as a G-Expression.

@item @code{allow-empty-password?} (default: @code{#f}) (type: boolean)
Whether to allow empty passwords.

@item @code{using-pam?} (default: @code{#t}) (type: boolean)
Whether to setup PAM entry.

@item @code{using-setuid?} (default: @code{#t}) (type: boolean)
Whether to setup program as setuid binary.

@end table

@end deftp

@defvar startx-command-service-type
Add @command{startx} to the system profile putting it onto @env{PATH}.

The value for this service is a @code{<xorg-configuration>} object which is
passed to the @code{xorg-start-command-xinit} procedure producing the
@command{startx} used.  Default value is @code{(xorg-configuration)}.
@end defvar


@node Serviços de impressão
@subsection Serviços de impressão

@cindex printer support with CUPS
The @code{(gnu services cups)} module provides a Guix service definition for
the CUPS printing service.  To add printer support to a Guix system, add a
@code{cups-service} to the operating system definition:

@defvar cups-service-type
The service type for the CUPS print server.  Its value should be a valid
CUPS configuration (see below).  To use the default settings, simply write:
@lisp
(service cups-service-type)
@end lisp
@end defvar

The CUPS configuration controls the basic things about your CUPS
installation: what interfaces it listens on, what to do if a print job
fails, how much logging to do, and so on.  To actually add a printer, you
have to visit the @url{http://localhost:631} URL, or use a tool such as
GNOME's printer configuration services.  By default, configuring a CUPS
service will generate a self-signed certificate if needed, for secure
connections to the print server.

Suppose you want to enable the Web interface of CUPS and also add support
for Epson printers @i{via} the @code{epson-inkjet-printer-escpr} package and
for HP printers @i{via} the @code{hplip-minimal} package.  You can do that
directly, like this (you need to use the @code{(gnu packages cups)} module):

@lisp
(service cups-service-type
         (cups-configuration
           (web-interface? #t)
           (extensions
             (list cups-filters epson-inkjet-printer-escpr hplip-minimal))))
@end lisp

@quotation Nota
If you wish to use the Qt5 based GUI which comes with the hplip package then
it is suggested that you install the @code{hplip} package, either in your OS
configuration file or as your user.
@end quotation

The available configuration parameters follow.  Each parameter definition is
preceded by its type; for example, @samp{string-list foo} indicates that the
@code{foo} parameter should be specified as a list of strings.  There is
also a way to specify the configuration as a string, if you have an old
@code{cupsd.conf} file that you want to port over from some other system;
see the end for more details.

@c The following documentation was initially generated by
@c (generate-documentation) in (gnu services cups).  Manually maintained
@c documentation is better, so we shouldn't hesitate to edit below as
@c needed.  However if the change you want to make to this documentation
@c can be done in an automated way, it's probably easier to change
@c (generate-documentation) than to make it below and have to deal with
@c the churn as CUPS updates.


Available @code{cups-configuration} fields are:

@deftypevr {@code{cups-configuration} parameter} package cups
The CUPS package.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} package-list extensions (default: @code{(list brlaser cups-filters epson-inkjet-printer-escpr foomatic-filters hplip-minimal splix)})
Drivers and other extensions to the CUPS package.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} files-configuration files-configuration
Configuration of where to write logs, what directories to use for print
spools, and related privileged configuration parameters.

Available @code{files-configuration} fields are:

@deftypevr {@code{files-configuration} parameter} log-location access-log
Defines the access log filename.  Specifying a blank filename disables
access log generation.  The value @code{stderr} causes log entries to be
sent to the standard error file when the scheduler is running in the
foreground, or to the system log daemon when run in the background.  The
value @code{syslog} causes log entries to be sent to the system log daemon.
The server name may be included in filenames using the string @code{%s}, as
in @code{/var/log/cups/%s-access_log}.

Defaults to @samp{"/var/log/cups/access_log"}.
@end deftypevr

@deftypevr {@code{files-configuration} parameter} file-name cache-dir
Where CUPS should cache data.

Defaults to @samp{"/var/cache/cups"}.
@end deftypevr

@deftypevr {@code{files-configuration} parameter} string config-file-perm
Specifies the permissions for all configuration files that the scheduler
writes.

Note that the permissions for the printers.conf file are currently masked to
only allow access from the scheduler user (typically root).  This is done
because printer device URIs sometimes contain sensitive authentication
information that should not be generally known on the system.  There is no
way to disable this security feature.

Defaults to @samp{"0640"}.
@end deftypevr

@deftypevr {@code{files-configuration} parameter} log-location error-log
Defines the error log filename.  Specifying a blank filename disables error
log generation.  The value @code{stderr} causes log entries to be sent to
the standard error file when the scheduler is running in the foreground, or
to the system log daemon when run in the background.  The value
@code{syslog} causes log entries to be sent to the system log daemon.  The
server name may be included in filenames using the string @code{%s}, as in
@code{/var/log/cups/%s-error_log}.

Defaults to @samp{"/var/log/cups/error_log"}.
@end deftypevr

@deftypevr {@code{files-configuration} parameter} string fatal-errors
Specifies which errors are fatal, causing the scheduler to exit.  The kind
strings are:

@table @code
@item none
No errors are fatal.

@item all
All of the errors below are fatal.

@item browse
Browsing initialization errors are fatal, for example failed connections to
the DNS-SD daemon.

@item config
Configuration file syntax errors are fatal.

@item listen
Listen or Port errors are fatal, except for IPv6 failures on the loopback or
@code{any} addresses.

@item log
Log file creation or write errors are fatal.

@item permissions
Bad startup file permissions are fatal, for example shared TLS certificate
and key files with world-read permissions.
@end table

Defaults to @samp{"all -browse"}.
@end deftypevr

@deftypevr {@code{files-configuration} parameter} boolean file-device?
Specifies whether the file pseudo-device can be used for new printer
queues.  The URI @uref{file:///dev/null} is always allowed.

Defaults to @samp{#f}.
@end deftypevr

@deftypevr {@code{files-configuration} parameter} string group
Specifies the group name or ID that will be used when executing external
programs.

Defaults to @samp{"lp"}.
@end deftypevr

@deftypevr {@code{files-configuration} parameter} string log-file-group
Specifies the group name or ID that will be used for log files.

Defaults to @samp{"lpadmin"}.
@end deftypevr

@deftypevr {@code{files-configuration} parameter} string log-file-perm
Specifies the permissions for all log files that the scheduler writes.

Defaults to @samp{"0644"}.
@end deftypevr

@deftypevr {@code{files-configuration} parameter} log-location page-log
Defines the page log filename.  Specifying a blank filename disables page
log generation.  The value @code{stderr} causes log entries to be sent to
the standard error file when the scheduler is running in the foreground, or
to the system log daemon when run in the background.  The value
@code{syslog} causes log entries to be sent to the system log daemon.  The
server name may be included in filenames using the string @code{%s}, as in
@code{/var/log/cups/%s-page_log}.

Defaults to @samp{"/var/log/cups/page_log"}.
@end deftypevr

@deftypevr {@code{files-configuration} parameter} string remote-root
Specifies the username that is associated with unauthenticated accesses by
clients claiming to be the root user.  The default is @code{remroot}.

Defaults to @samp{"remroot"}.
@end deftypevr

@deftypevr {@code{files-configuration} parameter} file-name request-root
Specifies the directory that contains print jobs and other HTTP request
data.

Defaults to @samp{"/var/spool/cups"}.
@end deftypevr

@deftypevr {@code{files-configuration} parameter} sandboxing sandboxing
Specifies the level of security sandboxing that is applied to print filters,
backends, and other child processes of the scheduler; either @code{relaxed}
or @code{strict}.  This directive is currently only used/supported on macOS.

Defaults to @samp{strict}.
@end deftypevr

@deftypevr {@code{files-configuration} parameter} file-name server-keychain
Specifies the location of TLS certificates and private keys.  CUPS will look
for public and private keys in this directory: @file{.crt} files for
PEM-encoded certificates and corresponding @file{.key} files for PEM-encoded
private keys.

Defaults to @samp{"/etc/cups/ssl"}.
@end deftypevr

@deftypevr {@code{files-configuration} parameter} file-name server-root
Specifies the directory containing the server configuration files.

Defaults to @samp{"/etc/cups"}.
@end deftypevr

@deftypevr {@code{files-configuration} parameter} boolean sync-on-close?
Specifies whether the scheduler calls fsync(2) after writing configuration
or state files.

Defaults to @samp{#f}.
@end deftypevr

@deftypevr {@code{files-configuration} parameter} space-separated-string-list system-group
Specifies the group(s) to use for @code{@@SYSTEM} group authentication.
@end deftypevr

@deftypevr {@code{files-configuration} parameter} file-name temp-dir
Specifies the directory where temporary files are stored.

Defaults to @samp{"/var/spool/cups/tmp"}.
@end deftypevr

@deftypevr {@code{files-configuration} parameter} string user
Specifies the user name or ID that is used when running external programs.

Defaults to @samp{"lp"}.
@end deftypevr

@deftypevr {@code{files-configuration} parameter} string set-env
Set the specified environment variable to be passed to child processes.

Defaults to @samp{"variable value"}.
@end deftypevr
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} access-log-level access-log-level
Specifies the logging level for the AccessLog file.  The @code{config} level
logs when printers and classes are added, deleted, or modified and when
configuration files are accessed or updated.  The @code{actions} level logs
when print jobs are submitted, held, released, modified, or canceled, and
any of the conditions for @code{config}.  The @code{all} level logs all
requests.

Defaults to @samp{actions}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} boolean auto-purge-jobs?
Specifies whether to purge job history data automatically when it is no
longer required for quotas.

Defaults to @samp{#f}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} comma-separated-string-list browse-dns-sd-sub-types
Specifies a list of DNS-SD sub-types to advertise for each shared printer.

The default @samp{(list "_cups" "_print" "_universal")} tells clients that
CUPS sharing, IPP Everywhere, AirPrint, and Mopria are supported.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} browse-local-protocols browse-local-protocols
Specifies which protocols to use for local printer sharing.

Defaults to @samp{dnssd}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} boolean browse-web-if?
Specifies whether the CUPS web interface is advertised.

Defaults to @samp{#f}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} boolean browsing?
Specifies whether shared printers are advertised.

Defaults to @samp{#f}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} default-auth-type default-auth-type
Specifies the default type of authentication to use.

Defaults to @samp{Basic}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} default-encryption default-encryption
Specifies whether encryption will be used for authenticated requests.

Defaults to @samp{Required}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} string default-language
Specifies the default language to use for text and web content.

Defaults to @samp{"en"}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} string default-paper-size
Specifies the default paper size for new print queues.  @samp{"Auto"} uses a
locale-specific default, while @samp{"None"} specifies there is no default
paper size.  Specific size names are typically @samp{"Letter"} or
@samp{"A4"}.

Defaults to @samp{"Auto"}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} string default-policy
Specifies the default access policy to use.

Defaults to @samp{"default"}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} boolean default-shared?
Specifies whether local printers are shared by default.

Defaults to @samp{#t}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} non-negative-integer dirty-clean-interval
Specifies the delay for updating of configuration and state files, in
seconds.  A value of 0 causes the update to happen as soon as possible,
typically within a few milliseconds.

Defaults to @samp{30}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} error-policy error-policy
Specifies what to do when an error occurs.  Possible values are
@code{abort-job}, which will discard the failed print job; @code{retry-job},
which will retry the job at a later time; @code{retry-current-job}, which
retries the failed job immediately; and @code{stop-printer}, which stops the
printer.

Defaults to @samp{stop-printer}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} non-negative-integer filter-limit
Specifies the maximum cost of filters that are run concurrently, which can
be used to minimize disk, memory, and CPU resource problems.  A limit of 0
disables filter limiting.  An average print to a non-PostScript printer
needs a filter limit of about 200.  A PostScript printer needs about half
that (100).  Setting the limit below these thresholds will effectively limit
the scheduler to printing a single job at any time.

Defaults to @samp{0}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} non-negative-integer filter-nice
Specifies the scheduling priority of filters that are run to print a job.
The nice value ranges from 0, the highest priority, to 19, the lowest
priority.

Defaults to @samp{0}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} host-name-lookups host-name-lookups
Specifies whether to do reverse lookups on connecting clients.  The
@code{double} setting causes @code{cupsd} to verify that the hostname
resolved from the address matches one of the addresses returned for that
hostname.  Double lookups also prevent clients with unregistered addresses
from connecting to your server.  Only set this option to @code{#t} or
@code{double} if absolutely required.

Defaults to @samp{#f}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} non-negative-integer job-kill-delay
Specifies the number of seconds to wait before killing the filters and
backend associated with a canceled or held job.

Defaults to @samp{30}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} non-negative-integer job-retry-interval
Specifies the interval between retries of jobs in seconds.  This is
typically used for fax queues but can also be used with normal print queues
whose error policy is @code{retry-job} or @code{retry-current-job}.

Defaults to @samp{30}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} non-negative-integer job-retry-limit
Specifies the number of retries that are done for jobs.  This is typically
used for fax queues but can also be used with normal print queues whose
error policy is @code{retry-job} or @code{retry-current-job}.

Defaults to @samp{5}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} boolean keep-alive?
Specifies whether to support HTTP keep-alive connections.

Defaults to @samp{#t}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} non-negative-integer limit-request-body
Specifies the maximum size of print files, IPP requests, and HTML form
data.  A limit of 0 disables the limit check.

Defaults to @samp{0}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} multiline-string-list listen
Listens on the specified interfaces for connections.  Valid values are of
the form @var{address}:@var{port}, where @var{address} is either an IPv6
address enclosed in brackets, an IPv4 address, or @code{*} to indicate all
addresses.  Values can also be file names of local UNIX domain sockets.  The
Listen directive is similar to the Port directive but allows you to restrict
access to specific interfaces or networks.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} location-access-control-list location-access-controls
Specifies a set of additional access controls.

Available @code{location-access-controls} fields are:

@deftypevr {@code{location-access-controls} parameter} file-name path
Specifies the URI path to which the access control applies.
@end deftypevr

@deftypevr {@code{location-access-controls} parameter} access-control-list access-controls
Access controls for all access to this path, in the same format as the
@code{access-controls} of @code{operation-access-control}.

Defaults to @samp{'()}.
@end deftypevr

@deftypevr {@code{location-access-controls} parameter} method-access-control-list method-access-controls
Access controls for method-specific access to this path.

Defaults to @samp{'()}.

Available @code{method-access-controls} fields are:

@deftypevr {@code{method-access-controls} parameter} boolean reverse?
If @code{#t}, apply access controls to all methods except the listed
methods.  Otherwise apply to only the listed methods.

Defaults to @samp{#f}.
@end deftypevr

@deftypevr {@code{method-access-controls} parameter} method-list methods
Methods to which this access control applies.

Defaults to @samp{'()}.
@end deftypevr

@deftypevr {@code{method-access-controls} parameter} access-control-list access-controls
Access control directives, as a list of strings.  Each string should be one
directive, such as @samp{"Order allow,deny"}.

Defaults to @samp{'()}.
@end deftypevr
@end deftypevr
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} non-negative-integer log-debug-history
Specifies the number of debugging messages that are retained for logging if
an error occurs in a print job.  Debug messages are logged regardless of the
LogLevel setting.

Defaults to @samp{100}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} log-level log-level
Specifies the level of logging for the ErrorLog file.  The value @code{none}
stops all logging while @code{debug2} logs everything.

Defaults to @samp{info}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} log-time-format log-time-format
Specifies the format of the date and time in the log files.  The value
@code{standard} logs whole seconds while @code{usecs} logs microseconds.

Defaults to @samp{standard}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-clients
Specifies the maximum number of simultaneous clients that are allowed by the
scheduler.

Defaults to @samp{100}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-clients-per-host
Specifies the maximum number of simultaneous clients that are allowed from a
single address.

Defaults to @samp{100}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-copies
Specifies the maximum number of copies that a user can print of each job.

Defaults to @samp{9999}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-hold-time
Specifies the maximum time a job may remain in the @code{indefinite} hold
state before it is canceled.  A value of 0 disables cancellation of held
jobs.

Defaults to @samp{0}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-jobs
Specifies the maximum number of simultaneous jobs that are allowed.  Set to
0 to allow an unlimited number of jobs.

Defaults to @samp{500}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-jobs-per-printer
Specifies the maximum number of simultaneous jobs that are allowed per
printer.  A value of 0 allows up to @code{max-jobs} per printer.

Defaults to @samp{0}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-jobs-per-user
Specifies the maximum number of simultaneous jobs that are allowed per
user.  A value of 0 allows up to @code{max-jobs} per user.

Defaults to @samp{0}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-job-time
Specifies the maximum time a job may take to print before it is canceled, in
seconds.  Set to 0 to disable cancellation of ``stuck'' jobs.

Defaults to @samp{10800}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-log-size
Specifies the maximum size of the log files before they are rotated, in
bytes.  The value 0 disables log rotation.

Defaults to @samp{1048576}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-subscriptions
Specifies the maximum number of simultaneous event subscriptions that are
allowed.  Set to @samp{0} to allow an unlimited number of subscriptions.

Defaults to @samp{0}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-subscriptions-per-job
Specifies the maximum number of simultaneous event subscriptions that are
allowed per job.  A value of @samp{0} allows up to @code{max-subscriptions}
per job.

Defaults to @samp{0}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-subscriptions-per-printer
Specifies the maximum number of simultaneous event subscriptions that are
allowed per printer.  A value of @samp{0} allows up to
@code{max-subscriptions} per printer.

Defaults to @samp{0}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-subscriptions-per-user
Specifies the maximum number of simultaneous event subscriptions that are
allowed per user.  A value of @samp{0} allows up to @code{max-subscriptions}
per user.

Defaults to @samp{0}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} non-negative-integer multiple-operation-timeout
Specifies the maximum amount of time to allow between files in a multiple
file print job, in seconds.

Defaults to @samp{900}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} environment-variables environment-variables
Passes the specified environment variable(s) to child processes; a list of
strings.

Defaults to @samp{'()}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} policy-configuration-list policies
Specifies named access control policies.

Available @code{policy-configuration} fields are:

@deftypevr {@code{policy-configuration} parameter} string name
Name of the policy.
@end deftypevr

@deftypevr {@code{policy-configuration} parameter} string job-private-access
Specifies an access list for a job's private values.  @code{@@ACL} maps to
the printer's requesting-user-name-allowed or requesting-user-name-denied
values.  @code{@@OWNER} maps to the job's owner.  @code{@@SYSTEM} maps to
the groups listed for the @code{system-group} field of the
@code{files-configuration}, which is reified into the
@code{cups-files.conf(5)} file.  Other possible elements of the access list
include specific user names, and @code{@@@var{group}} to indicate members of
a specific group.  The access list may also be simply @code{all} or
@code{default}.

Defaults to @samp{"@@OWNER @@SYSTEM"}.
@end deftypevr

@deftypevr {@code{policy-configuration} parameter} string job-private-values
Specifies the list of job values to make private, or @code{all},
@code{default}, or @code{none}.

Defaults to @samp{"job-name job-originating-host-name
job-originating-user-name phone"}.
@end deftypevr

@deftypevr {@code{policy-configuration} parameter} string subscription-private-access
Specifies an access list for a subscription's private values.  @code{@@ACL}
maps to the printer's requesting-user-name-allowed or
requesting-user-name-denied values.  @code{@@OWNER} maps to the job's
owner.  @code{@@SYSTEM} maps to the groups listed for the
@code{system-group} field of the @code{files-configuration}, which is
reified into the @code{cups-files.conf(5)} file.  Other possible elements of
the access list include specific user names, and @code{@@@var{group}} to
indicate members of a specific group.  The access list may also be simply
@code{all} or @code{default}.

Defaults to @samp{"@@OWNER @@SYSTEM"}.
@end deftypevr

@deftypevr {@code{policy-configuration} parameter} string subscription-private-values
Specifies the list of job values to make private, or @code{all},
@code{default}, or @code{none}.

Defaults to @samp{"notify-events notify-pull-method notify-recipient-uri
notify-subscriber-user-name notify-user-data"}.
@end deftypevr

@deftypevr {@code{policy-configuration} parameter} operation-access-control-list access-controls
Access control by IPP operation.

Defaults to @samp{'()}.
@end deftypevr
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} boolean-or-non-negative-integer preserve-job-files
Specifies whether job files (documents) are preserved after a job is
printed.  If a numeric value is specified, job files are preserved for the
indicated number of seconds after printing.  Otherwise a boolean value
applies indefinitely.

Defaults to @samp{86400}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} boolean-or-non-negative-integer preserve-job-history
Specifies whether the job history is preserved after a job is printed.  If a
numeric value is specified, the job history is preserved for the indicated
number of seconds after printing.  If @code{#t}, the job history is
preserved until the MaxJobs limit is reached.

Defaults to @samp{#t}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} comma-separated-string-list-or-#f ready-paper-sizes
Specifies a list of potential paper sizes that are reported as ready, that
is: loaded.  The actual list will contain only the sizes that each printer
supports.

The default value of @code{#f} is a special case: CUPS will use @samp{(list
\"Letter\" \"Legal\" \"Tabloid\" \"4x6\" \"Env10\")} if the default paper
size is \"Letter\", and @samp{(list \"A3\" \"A4\" \"A5\" \"A6\" \"EnvDL\")}
otherwise.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} non-negative-integer reload-timeout
Specifies the amount of time to wait for job completion before restarting
the scheduler.

Defaults to @samp{30}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} string server-admin
Specifies the email address of the server administrator.

Defaults to @samp{"root@@localhost.localdomain"}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} host-name-list-or-* server-alias
The ServerAlias directive is used for HTTP Host header validation when
clients connect to the scheduler from external interfaces.  Using the
special name @code{*} can expose your system to known browser-based DNS
rebinding attacks, even when accessing sites through a firewall.  If the
auto-discovery of alternate names does not work, we recommend listing each
alternate name with a ServerAlias directive instead of using @code{*}.

Defaults to @samp{*}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} string server-name
Specifies the fully-qualified host name of the server.

Defaults to @samp{"localhost"}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} server-tokens server-tokens
Specifies what information is included in the Server header of HTTP
responses.  @code{None} disables the Server header.  @code{ProductOnly}
reports @code{CUPS}.  @code{Major} reports @code{CUPS 2}.  @code{Minor}
reports @code{CUPS 2.0}.  @code{Minimal} reports @code{CUPS 2.0.0}.
@code{OS} reports @code{CUPS 2.0.0 (@var{uname})} where @var{uname} is the
output of the @code{uname} command.  @code{Full} reports @code{CUPS 2.0.0
(@var{uname}) IPP/2.0}.

Defaults to @samp{Minimal}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} multiline-string-list ssl-listen
Listens on the specified interfaces for encrypted connections.  Valid values
are of the form @var{address}:@var{port}, where @var{address} is either an
IPv6 address enclosed in brackets, an IPv4 address, or @code{*} to indicate
all addresses.

Defaults to @samp{'()}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} ssl-options ssl-options
Sets encryption options.  By default, CUPS only supports encryption using
TLS v1.0 or higher using known secure cipher suites.  Security is reduced
when @code{Allow} options are used, and enhanced when @code{Deny} options
are used.  The @code{AllowRC4} option enables the 128-bit RC4 cipher suites,
which are required for some older clients.  The @code{AllowSSL3} option
enables SSL v3.0, which is required for some older clients that do not
support TLS v1.0.  The @code{DenyCBC} option disables all CBC cipher
suites.  The @code{DenyTLS1.0} option disables TLS v1.0 support - this sets
the minimum protocol version to TLS v1.1.

Defaults to @samp{'()}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} boolean strict-conformance?
Specifies whether the scheduler requires clients to strictly adhere to the
IPP specifications.

Defaults to @samp{#f}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} non-negative-integer timeout
Specifies the HTTP request timeout, in seconds.

Defaults to @samp{900}.

@end deftypevr

@deftypevr {@code{cups-configuration} parameter} boolean web-interface?
Specifies whether the web interface is enabled.

Defaults to @samp{#f}.
@end deftypevr

At this point you're probably thinking ``oh dear, Guix manual, I like you
but you can stop already with the configuration options''.  Indeed.
However, one more point: it could be that you have an existing
@code{cupsd.conf} that you want to use.  In that case, you can pass an
@code{opaque-cups-configuration} as the configuration of a
@code{cups-service-type}.

Available @code{opaque-cups-configuration} fields are:

@deftypevr {@code{opaque-cups-configuration} parameter} package cups
The CUPS package.
@end deftypevr

@deftypevr {@code{opaque-cups-configuration} parameter} string cupsd.conf
The contents of the @code{cupsd.conf}, as a string.
@end deftypevr

@deftypevr {@code{opaque-cups-configuration} parameter} string cups-files.conf
The contents of the @code{cups-files.conf} file, as a string.
@end deftypevr

For example, if your @code{cupsd.conf} and @code{cups-files.conf} are in
strings of the same name, you could instantiate a CUPS service like this:

@lisp
(service cups-service-type
         (opaque-cups-configuration
           (cupsd.conf cupsd.conf)
           (cups-files.conf cups-files.conf)))
@end lisp


@node Serviços de desktop
@subsection Serviços de desktop

The @code{(gnu services desktop)} module provides services that are usually
useful in the context of a ``desktop'' setup---that is, on a machine running
a graphical display server, possibly with graphical user interfaces, etc.
It also defines services that provide specific desktop environments like
GNOME, Xfce or MATE.

To simplify things, the module defines a variable containing the set of
services that users typically expect on a machine with a graphical
environment and networking:

@defvar %desktop-services
This is a list of services that builds upon @code{%base-services} and adds
or adjusts services for a typical ``desktop'' setup.

In particular, it adds a graphical login manager (@pxref{X Window,
@code{gdm-service-type}}), screen lockers, a network management tool
(@pxref{Serviços de Rede, @code{network-manager-service-type}}) with
modem support (@pxref{Serviços de Rede,
@code{modem-manager-service-type}}), energy and color management services,
the @code{elogind} login and seat manager, the Polkit privilege service, the
GeoClue location service, the AccountsService daemon that allows authorized
users change system passwords, a NTP client (@pxref{Serviços de Rede})
and the Avahi daemon.
@end defvar

The @code{%desktop-services} variable can be used as the @code{services}
field of an @code{operating-system} declaration (@pxref{Referência do operating-system, @code{services}}).

Additionally, the following procedures add one (or more!) desktop
environments to a system.

@itemize
@item @code{gnome-desktop-service-type} adds GNOME,
@item @code{plasma-desktop-service-type} adds KDE Plasma,
@item @code{enlightenment-desktop-service-type} adds Enlightenment,
@item @code{lxqt-desktop-service-type} adds LXQt,
@item @code{mate-desktop-service-type} adds MATE, and
@item @code{xfce-desktop-service-type} adds Xfce.
@end itemize

These service types add ``metapackages'' such as @code{gnome} or
@code{plasma} to the system profile, but most of them also set up other
useful services that mere packages can't do.

For example, they may elevate privileges on a limited number of
special-purpose system interfaces and programs.  This allows backlight
adjustment helpers, power management utilities, screen lockers, and other
integrated functionality to work as expected.

@defvar gnome-desktop-service-type
This is the type of the service that adds the @uref{https://www.gnome.org,
GNOME} desktop environment.  Its value is a
@code{gnome-desktop-configuration} object (see below).

This service adds the @code{gnome} package to the system profile, and
extends polkit with the actions from @code{gnome-settings-daemon}.
@end defvar

@deftp {Tipo de dados} gnome-desktop-configuration
Configuration record for the GNOME desktop environment.  Available
@code{gnome-desktop-configuration} fields are:

@table @asis
@item @code{core-services} (type: list-of-packages)
A list of packages that the GNOME Shell and applications may rely on.

@item @code{shell} (type: list-of-packages)
A list of packages that constitute the GNOME Shell, without applications.

@item @code{utilities} (type: list-of-packages)
A list of packages that serve as applications to use on top of the GNOME
Shell.

@item @code{gnome} (type: maybe-package)
This field used to be the only configuration point and specified a GNOME
meta-package to install system-wide.  Since the meta-package itself provides
neither sources nor the actual packages and is only used to propagate them,
this field is deprecated.

@item @code{extra-packages} (type: list-of-packages)
A list of GNOME-adjacent packages to also include.  This field is intended
for users to add their own packages to their GNOME experience.  Note, that
it already includes some packages that are considered essential by some
(most?) GNOME users.

@item @code{udev-ignorelist} (default: @code{()}) (type: list-of-strings)
A list of regular expressions denoting udev rules or hardware file names
provided by any package that should not be installed.  By default, every
udev rule and hardware file specified by any package referenced in the other
fields are installed.

@item @code{polkit-ignorelist} (default: @code{()}) (type: list-of-strings)
A list of regular expressions denoting polkit rules provided by any package
that should not be installed.  By default, every polkit rule added by any
package referenced in the other fields are installed.

@item @code{keyring} (type: gnome-keyring-configuration-or-#f)
A <gnome-keyring-configuration> record used to better integrate the GNOME
keyring with the system.  Refer to the documentation of the
@code{gnome-keyring-service-type} for more information.  If you'd rather
avoid integrating the GNOME keyring, you can set this to @code{#f}.

@end table
@end deftp

@defvar plasma-desktop-service-type
This is the type of the service that adds the
@uref{https://kde.org/plasma-desktop/, Plasma} desktop environment.  Its
value is a @code{plasma-desktop-configuration} object (see below).

This service adds the @code{plasma} package to the system profile.
@end defvar

@deftp {Tipo de dados} plasma-desktop-configuration
Configuration record for the Plasma desktop environment.

@table @asis
@item @code{plasma} (default: @code{plasma})
The Plasma package to use.
@end table
@end deftp

@defvar xfce-desktop-service-type
This is the type of a service to run the @uref{Xfce, https://xfce.org/}
desktop environment.  Its value is an @code{xfce-desktop-configuration}
object (see below).

This service adds the @code{xfce} package to the system profile, and extends
polkit with the ability for @code{thunar} to manipulate the file system as
root from within a user session, after the user has authenticated with the
administrator's password.

Note that @code{xfce4-panel} and its plugin packages should be installed in
the same profile to ensure compatibility.  When using this service, you
should add extra plugins (@code{xfce4-whiskermenu-plugin},
@code{xfce4-weather-plugin}, etc.) to the @code{packages} field of your
@code{operating-system}.
@end defvar

@deftp {Tipo de dados} xfce-desktop-configuration
Configuration record for the Xfce desktop environment.

@table @asis
@item @code{xfce} (default: @code{xfce})
The Xfce package to use.
@end table
@end deftp

@defvar mate-desktop-service-type
This is the type of the service that runs the
@uref{https://mate-desktop.org/, MATE desktop environment}.  Its value is a
@code{mate-desktop-configuration} object (see below).

This service adds the @code{mate} package to the system profile, and extends
polkit with the actions from @code{mate-settings-daemon}.
@end defvar

@deftp {Tipo de dados} mate-desktop-configuration
Configuration record for the MATE desktop environment.

@table @asis
@item @code{mate} (default: @code{mate})
The MATE package to use.
@end table
@end deftp

@defvar lxqt-desktop-service-type
This is the type of the service that runs the
@uref{https://lxqt-project.org, LXQt desktop environment}.  Its value is a
@code{lxqt-desktop-configuration} object (see below).

This service adds the @code{lxqt} package to the system profile.
@end defvar

@deftp {Tipo de dados} lxqt-desktop-configuration
Configuration record for the LXQt desktop environment.

@table @asis
@item @code{lxqt} (default: @code{lxqt})
The LXQT package to use.
@end table
@end deftp

@defvar sugar-desktop-service-type
This is the type of the service that runs the
@uref{https://www.sugarlabs.org, Sugar desktop environment}.  Its value is a
@code{sugar-desktop-configuration} object (see below).

This service adds the @code{sugar} package to the system profile, as well as
any selected Sugar activities.  By default it only includes a minimal set of
activities.
@end defvar

@deftp {Tipo de dados} sugar-desktop-configuration
Configuration record for the Sugar desktop environment.

@table @asis
@item @code{sugar} (default: @code{sugar})
The Sugar package to use.
@item @code{gobject-introspection} (default: @code{gobject-introspection})
The @code{gobject-introspection} package to use.  This package is used to
access libraries installed as dependencies of Sugar activities.
@item @code{activities} (default: @code{(list sugar-help-activity)})
A list of Sugar activities to install.
@end table
@end deftp

The following example configures the Sugar desktop environment with a number
of useful activities:

@lisp
(use-modules (gnu))
(use-package-modules sugar)
(use-service-modules desktop)
(operating-system
  ...
  (services (cons* (service sugar-desktop-service-type
                            (sugar-desktop-configuration
                              (activities (list sugar-browse-activity
                                                sugar-help-activity
                                                sugar-jukebox-activity
                                                sugar-typing-turtle-activity))))
                   %desktop-services))
  ...)
@end lisp

@defvar enlightenment-desktop-service-type
Return a service that adds the @code{enlightenment} package to the system
profile, and extends dbus with actions from @code{efl}.
@end defvar

@deftp {Tipo de dados} enlightenment-desktop-service-configuration
@table @asis
@item @code{enlightenment} (default: @code{enlightenment})
The enlightenment package to use.
@end table
@end deftp

Because the GNOME, Xfce and MATE desktop services pull in so many packages,
the default @code{%desktop-services} variable doesn't include any of them by
default.  To add GNOME, Xfce or MATE, just @code{cons} them onto
@code{%desktop-services} in the @code{services} field of your
@code{operating-system}:

@lisp
(use-modules (gnu))
(use-service-modules desktop)
(operating-system
  ...
  ;; cons* adds items to the list given as its last argument.
  (services (cons* (service gnome-desktop-service-type)
                   (service xfce-desktop-service-type)
                   %desktop-services))
  ...)
@end lisp

These desktop environments will then be available as options in the
graphical login window.

The actual service definitions included in @code{%desktop-services} and
provided by @code{(gnu services dbus)} and @code{(gnu services desktop)} are
described below.

@defvar dbus-root-service-type
Type for a service that runs the D-Bus ``system bus''.
@footnote{@uref{https://dbus.freedesktop.org/, D-Bus} is an inter-process
communication facility.  Its system bus is used to allow system services to
communicate and to be notified of system-wide events.}

The value for this service type is a @code{<dbus-configuration>} record.
@end defvar

@deftp {Tipo de dados} dbus-configuration
Data type representing the configuration for @code{dbus-root-service-type}.

@table @asis
@item @code{dbus} (default: @code{dbus}) (type: file-like)
Package object for dbus.

@item @code{services} (default: @code{'()}) (type: list)
List of packages that provide an @file{etc/dbus-1/system.d} directory
containing additional D-Bus configuration and policy files.  For example, to
allow avahi-daemon to use the system bus, @var{services} must be equal to
@code{(list avahi)}.

@item @code{verbose?} (default: @code{#f}) (type: boolean)
When @code{#t}, D-Bus is launched with environment variable
@samp{DBUS_VERBOSE} set to @samp{1}.  A verbose-enabled D-Bus package such
as @code{dbus-verbose} should be provided to @var{dbus} in this
scenario. The verbose output is logged to @file{/var/log/dbus-daemon.log}.

@end table
@end deftp

@subsubheading Elogind

@uref{https://github.com/elogind/elogind, Elogind} is a login and seat
management daemon that also handles most system-level power events for a
computer, for example suspending the system when a lid is closed, or
shutting it down when the power button is pressed.

It also provides a D-Bus interface that can be used to know which users are
logged in, know what kind of sessions they have open, suspend the system,
inhibit system suspend, reboot the system, and other tasks.

@defvar elogind-service-type
Type of the service that runs @command{elogind}, a login and seat management
daemon.  The value for this service is a @code{<elogind-configuration>}
object.
@end defvar

@c Auto-generated via (configuration->documentation 'elogind-configuration).
@c %start of fragment

@deftp {Tipo de dados} elogind-configuration
Available @code{elogind-configuration} fields are:

@table @asis
@item @code{elogind} (default: @code{elogind}) (type: file-like)
The elogind package to use.

@item @code{system-sleep-hook-files} (default: @code{()}) (type: list-of-file-likes)
A list of executables (file-like objects) that will be installed into the
@file{/etc/elogind/system-sleep} hook directory.  See `Hook directories' in
the @samp{loginctl(1)} man page for more information.

@item @code{system-shutdown-hook-files} (default: @code{()}) (type: list-of-file-likes)
A list of executables (file-like objects) that will be installed into the
@file{/etc/elogind/system-shutdown/} hook directory.

@item @code{allow-power-off-interrupts?} (default: @code{#f}) (type: maybe-boolean)
Whether the executables in elogind's hook directories (see above) can cause
a power-off action to be cancelled (interrupted) by printing an appropriate
error message to stdout.

@item @code{allow-suspend-interrupts?} (default: @code{#f}) (type: maybe-boolean)
Likewise as the @code{allow-power-off-interrupts?} option, but for the
suspend action.

@item @code{broadcast-power-off-interrupts?} (default: @code{#f}) (type: maybe-boolean)
Whether an interrupt of a power-off action is broadcasted.

@item @code{broadcast-suspend-interrupts?} (default: @code{#f}) (type: maybe-boolean)
Whether an interrupt of a suspend action is broadcasted.

@item @code{kill-user-processes?} (default: @code{#f}) (type: maybe-boolean)
Whether the processes of a user should be killed when the user logs out.

@item @code{kill-only-users} (type: maybe-list-of-user-names)
Usernames whose processes should be killed, regardless the value of
@code{kill-user-processes?}.

@item @code{kill-exclude-users} (default: @code{("root")}) (type: maybe-list-of-user-names)
Usernames whose processes should @emph{not} be killed, regardless the value
of @code{kill-user-processes?}.

@item @code{inhibit-delay-max-seconds} (default: @code{5}) (type: maybe-non-negative-integer)
The maximum time a system shutdown or sleep request is delayed due to an
inhibitor lock of type delay being active before the inhibitor is ignored
and the operation executes anyway.

@item @code{handle-power-key} (default: @code{poweroff}) (type: maybe-action)
The action done when the power key is pressed.  The compiled default is
@code{'poweroff}.

@item @code{handle-suspend-key} (default: @code{suspend}) (type: maybe-action)
The action done when the suspend key is pressed.  The

@item @code{handle-hibernate-key} (default: @code{hibernate}) (type: maybe-action)
The action done when the hibernate key is pressed.

@item @code{handle-lid-switch} (default: @code{suspend}) (type: maybe-action)
The action done when the lid is closed.

@item @code{handle-lid-switch-docked} (default: @code{ignore}) (type: maybe-action)
The action done when the lid is closed and the device docked.

@item @code{handle-lid-switch-external-power} (default: @code{suspend}) (type: maybe-action)
The action done when the lid is closed and the device is externally powered.

@item @code{power-key-ignore-inhibited?} (default: @code{#f}) (type: maybe-boolean)
Whether to ignore high-level inhibitor locks (shutdown, reboot, sleep or
idle) when the power key is pressed.

@item @code{suspend-key-ignore-inhibited?} (default: @code{#f}) (type: maybe-boolean)
Whether to ignore high-level inhibitor locks (shutdown, reboot, sleep or
idle) when the suspend key is pressed.

@item @code{hibernate-key-ignore-inhibited?} (default: @code{#f}) (type: maybe-boolean)
Whether to ignore high-level inhibitor locks (shutdown, reboot, sleep or
idle) when the hibernate key is pressed.

@item @code{lid-switch-ignore-inhibited?} (default: @code{#f}) (type: maybe-boolean)
Whether to ignore high-level inhibitor locks (shutdown, reboot, sleep or
idle) when the lid is closed.

@item @code{holdoff-timeout-seconds} (default: @code{30}) (type: maybe-non-negative-integer)
Specifies the number of seconds after system startup or system resume during
which elogind will hold off on reacting to lid events.

@item @code{idle-action} (default: @code{ignore}) (type: maybe-action)
Action to take when the system is idle.

@item @code{idle-action-seconds} (type: maybe-non-negative-integer)
The delay after which the action configured in @code{idle-action} is taken
after the system is idle.

@item @code{runtime-directory-size-percent} (type: maybe-percent)
Set the size limit, in percent, on the @env{XDG_RUNTIME_DIR} runtime
directory for each user who logs in.  This specifies the per-user size limit
relative to the amount of physical @acronym{RAM,read access memory}.  This
value takes precedence over that specified via
@code{runtime-directory-size}.

@item @code{runtime-directory-size} (type: maybe-non-negative-integer)
Set the size limit, in bytes, on the @env{XDG_RUNTIME_DIR} runtime directory
for each user who logs in.

@item @code{remove-ipc?} (default: @code{#t}) (type: maybe-boolean)
Whether @acronym{IPC,inter-process communication} objects belonging to the
user shall be removed when the user fully logs out.

@item @code{suspend-state} (default: @code{(mem standby freeze)}) (type: maybe-list-of-suspend-states)
The suspend state values to be write to @file{/sys/power/state} by elogind
when suspending the system.  They will be tried in turn, until one is
written without error.

@item @code{suspend-mode} (type: maybe-list-of-suspend-modes)
The suspend mode values to write to @file{/sys/power/mem_sleep} by elogind
when suspending the system.

@item @code{suspend-estimation-seconds} (default: @code{3600}) (type: maybe-non-negative-integer)
Cause the RTC alarm to wake the system after the specified time span to
measure the system battery capacity level and estimate the battery
discharging rate, which is used for estimating the time span until the
system battery charge level goes down to 5%.  This option is only used by
elogind when using the @code{'suspend-then-hibernate} action.

@item @code{hibernate-mode} (default: @code{(platform shutdown)}) (type: maybe-list-of-hibernation-modes)
The hibernation mode values to write to @file{/sys/power/disk} by elogind
when hibernating the system.

@item @code{hibernate-delay-seconds} (type: maybe-non-negative-integer)
The amount of time the system spends in suspend mode before the system is
automatically put into hibernate mode.

@item @code{hibernate-state} (type: maybe-list-of-strings)
Deprecated option.

@item @code{hybrid-sleep-state} (type: maybe-list-of-strings)
Deprecated option.

@item @code{hybrid-sleep-mode} (type: maybe-list-of-strings)
Deprecated option.

@end table

@end deftp


@c %end of fragment

@defvar accountsservice-service-type
Type for the service that runs AccountsService, a system service that can
list available accounts, change their passwords, and so on.  AccountsService
integrates with PolicyKit to enable unprivileged users to acquire the
capability to modify their system configuration.  See
@url{https://www.freedesktop.org/wiki/Software/AccountsService/,
AccountsService} for more information.

The value for this service is a file-like object, by default it is set to
@code{accountsservice} (the package object for AccountsService).
@end defvar

@defvar polkit-service-type
Type for the service that runs the
@url{https://www.freedesktop.org/wiki/Software/polkit/, Polkit privilege
management service}, which allows system administrators to grant access to
privileged operations in a structured way.  By querying the Polkit service,
a privileged system component can know when it should grant additional
capabilities to ordinary users.  For example, an ordinary user can be
granted the capability to suspend the system if the user is logged in
locally.

The value for this service is a @code{<polkit-configuration>} object.
@end defvar

@c TODO: Document <polkit-configuration>, preferably by refactoring this to use
@c       define-configuration and generating documentation from it.

@defvar polkit-wheel-service
Service that adds the @code{wheel} group as admins to the Polkit service.
This makes it so that users in the @code{wheel} group are queried for their
own passwords when performing administrative actions instead of
@code{root}'s, similar to the behaviour used by @code{sudo}.
@end defvar

@defvar upower-service-type
Service that runs @uref{https://upower.freedesktop.org/, @command{upowerd}},
a system-wide monitor for power consumption and battery levels, with the
given configuration settings.

It implements the @code{org.freedesktop.UPower} D-Bus interface, and is
notably used by GNOME.
@end defvar

@deftp {Tipo de dados} 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?} (padrão: @code{#f})
Enable the Watts Up Pro device.

@item @code{poll-batteries?} (padrão: @code{#t})
Enable polling the kernel for battery level changes.

@item @code{ignore-lid?} (padrão: @code{#f})
Ignore the lid state, this can be useful if it's incorrect on a device.

@item @code{use-percentage-for-policy?} (default: @code{#t})
Whether to use a policy based on battery percentage rather than on estimated
time left.  A policy based on battery percentage is usually more reliable.

@item @code{percentage-low} (default: @code{20})
When @code{use-percentage-for-policy?} is @code{#t}, this sets the
percentage at which the battery is considered low.

@item @code{percentage-critical} (default: @code{5})
When @code{use-percentage-for-policy?} is @code{#t}, this sets the
percentage at which the battery is considered critical.

@item @code{percentage-action} (default: @code{2})
When @code{use-percentage-for-policy?} is @code{#t}, this sets the
percentage at which action will be taken.

@item @code{time-low} (default: @code{1200})
When @code{use-time-for-policy?} is @code{#f}, this sets the time remaining
in seconds at which the battery is considered low.

@item @code{time-critical} (default: @code{300})
When @code{use-time-for-policy?} is @code{#f}, this sets the time remaining
in seconds at which the battery is considered critical.

@item @code{time-action} (default: @code{120})
When @code{use-time-for-policy?} is @code{#f}, this sets the time remaining
in seconds at which action will be taken.

@item @code{critical-power-action} (default: @code{'hybrid-sleep})
The action taken when @code{percentage-action} or @code{time-action} is
reached (depending on the configuration of
@code{use-percentage-for-policy?}).

Possible values are:

@itemize @bullet
@item
@code{'power-off}

@item
@code{'hibernate}

@item
@code{'hybrid-sleep}.
@end itemize

@end table
@end deftp

@defvar udisks-service-type
Type for the service that runs
@uref{https://udisks.freedesktop.org/docs/latest/, UDisks}, a @dfn{disk
management} daemon that provides user interfaces with notifications and ways
to mount/unmount disks.  Programs that talk to UDisks include the
@command{udisksctl} command, part of UDisks, and GNOME Disks.  Note that
Udisks relies on the @command{mount} command, so it will only be able to use
the file-system utilities installed in the system profile.  For example if
you want to be able to mount NTFS file-systems in read and write fashion,
you'll need to have @code{ntfs-3g} installed system-wide.

The value for this service is a @code{<udisks-configuration>} object.
@end defvar

@deftp {Tipo de dados} udisks-configuration
Data type representing the configuration for @code{udisks-service-type}.

@table @asis
@item @code{udisks} (default: @code{udisks}) (type: file-like)
Package object for UDisks.

@end table
@end deftp

@defvar gvfs-service-type
Type for the service that provides virtual file systems for GIO
applications, which enables support for @code{trash://}, @code{ftp://},
@code{sftp://} and many other location schemas in file managers like
Nautilus (GNOME Files) and Thunar.

The value for this service is a @code{<gvfs-configuration>} object.
@end defvar

@deftp {Tipo de dados} gvfs-configuration
Data type representing the configuration for @code{gvfs-service-type}.

@table @asis
@item @code{gvfs} (default: @code{gvfs}) (type: file-like)
Package object for GVfs.

@end table
@end deftp

@defvar colord-service-type
This is the type of the service that runs @command{colord}, a system service
with a D-Bus interface to manage the color profiles of input and output
devices such as screens and scanners.  It is notably used by the GNOME Color
Manager graphical tool.  See
@uref{https://www.freedesktop.org/software/colord/, the colord web site} for
more information.
@end defvar

@cindex scanner access
@defvar sane-service-type
This service provides access to scanners @i{via}
@uref{http://www.sane-project.org, SANE} by installing the necessary udev
rules and pluggable backends.  It is included in @code{%desktop-services}
(@pxref{Serviços de desktop}) and relies by default on @code{sane-backends}
package (see below) for hardware support.
@end defvar

@deftp {Data Type} sane-configuration
Data type representing the configuration for SANE.

@table @asis

@item @code{sane} (default: @code{sane})
Package containing SANE library.

@item @code{backends} (default: @code{(sane-backends)})
List of packages with pluggable SANE backends:

@itemize @bullet
@item
@code{sane-backends}: The default backend collection which supports many
recent scanners,

@item
@code{sane-airscan}: A backend that enables network scanners supporting eSCL
(Apple) or WSD, (Microsoft) protocols

@item
@code{hplip}: A backend containing drivers for older Hewlett-Packard
scanners,

@item
@code{utsushi}: A backend containing drivers for older Epson devices.

@end itemize

@end table
@end deftp

In order to use additional backends on a system which relies on
@code{%desktop-services}, you may use @code{modify-services} (@pxref{Referência de Service, @code{modify-services}}) as illustrated below:

@lisp
(use-modules (gnu))
(use-service-modules
  @dots{}
  desktop)
(use-package-modules
  @dots{}
  scanner)

(define %my-desktop-services
  ;; List of desktop services that supports a broader range of scanners.
  (modify-services %desktop-services
    (sane-service-type _ =>
      (sane-configuration
        (backends (list sane-backends sane-airscan))))))

(operating-system
  @dots{}
  (services %my-desktop-services))
@end lisp

@deffn {Procedure} geoclue-application name [#:allowed? #t] [#:system? #f] [#:users '()]
Return a configuration allowing an application to access GeoClue location
data.  @var{name} is the Desktop ID of the application, without the
@code{.desktop} part.  If @var{allowed?} is true, the application will have
access to location information by default.  The boolean @var{system?} value
indicates whether an application is a system component or not.  Finally
@var{users} is a list of UIDs of all users for which this application is
allowed location info access.  An empty users list means that all users are
allowed.
@end deffn

@defvar %standard-geoclue-applications
The standard list of well-known GeoClue application configurations, granting
authority to the GNOME date-and-time utility to ask for the current location
in order to set the time zone, and allowing the IceCat and Epiphany web
browsers to request location information.  IceCat and Epiphany both query
the user before allowing a web page to know the user's location.
@end defvar

@defvar geoclue-service-type
Type for the service that runs the
@url{https://wiki.freedesktop.org/www/Software/GeoClue/, GeoClue} location
service.  This service provides a D-Bus interface to allow applications to
request access to a user's physical location, and optionally to add
information to online location databases.

The value for this service is a @code{<geoclue-configuration>} object.
@end defvar

@c TODO: Document <geoclue-configuration>, preferably by refactoring this to use
@c       define-configuration and generating documentation from it.

@defvar iio-sensor-proxy-service-type
Type for the service that runs
@uref{https://gitlab.freedesktop.org/hadess/iio-sensor-proxy, IIO sensor
proxy}, a daemon that proxies low-level sensor data from Industrial I/O
(IIO) devices into a D-Bus interface.  It enables user-space applications,
such as desktop environments like GNOME and KDE, and services like GeoClue,
to access data from various sensors commonly found in devices like
ultrabooks and 2-in-1s.  This allows for:

@itemize @bullet
@item
Automatic screen rotation based on accelerometer data.
@item
Ambient brightness adjustment using light sensor data.
@item
Compass/direction information for location services (via GeoClue).
@end itemize

The value for this service is a @code{<iio-sensor-proxy-configuration>}
object.
@end defvar

@deftp {Data Type} iio-sensor-proxy-configuration
Data type representing the configuration for
@code{iio-sensor-proxy-service-type}.

@table @asis
@item @code{iio-sensor-proxy} (default: @code{iio-sensor-proxy}) (type: file-like)
Package object of iio-sensor-proxy.

@end table
@end deftp

@defvar bluetooth-service-type
This is the type for the @uref{https://bluez.org/, Linux Bluetooth Protocol
Stack} (BlueZ) system, which generates the @file{/etc/bluetooth/main.conf}
configuration file.  The value for this type is a
@command{bluetooth-configuration} record as in this example:

@lisp
(service bluetooth-service-type)
@end lisp

See below for details about @code{bluetooth-configuration}.
@end defvar

@deftp {Tipo de dados} bluetooth-configuration
Data type representing the configuration for @code{bluetooth-service}.

@table @asis
@item @code{bluez} (default: @code{bluez})
@code{bluez} package to use.

@item @code{name} (default: @code{"BlueZ"})
Default adapter name.

@item @code{class} (default: @code{#x000000})
Default device class. Only the major and minor device class bits are
considered.

@item @code{discoverable-timeout} (default: @code{180})
How long to stay in discoverable mode before going back to
non-discoverable. The value is in seconds.

@item @code{always-pairable?} (default: @code{#f})
Always allow pairing even if there are no agents registered.

@item @code{pairable-timeout} (default: @code{0})
How long to stay in pairable mode before going back to non-discoverable. The
value is in seconds.

@item @code{device-id} (default: @code{#f})
Use vendor id source (assigner), vendor, product and version information for
DID profile support. The values are separated by ":" and @var{assigner},
@var{VID}, @var{PID} and @var{version}.

Possible values are:

@itemize @bullet
@item
@code{#f} to disable it,

@item
@code{"assigner:1234:5678:abcd"}, where @var{assigner} is either @code{usb}
(default)  or @code{bluetooth}.

@end itemize

@item @code{reverse-service-discovery?} (default: @code{#t})
Do reverse service discovery for previously unknown devices that connect to
us. For BR/EDR this option is really only needed for qualification since the
BITE tester doesn't like us doing reverse SDP for some test cases, for LE
this disables the GATT client functionally so it can be used in system which
can only operate as peripheral.

@item @code{name-resolving?} (default: @code{#t})
Enable name resolving after inquiry. Set it to @code{#f} if you don't need
remote devices name and want shorter discovery cycle.

@item @code{debug-keys?} (default: @code{#f})
Enable runtime persistency of debug link keys. Default is false which makes
debug link keys valid only for the duration of the connection that they were
created for.

@item @code{controller-mode} (default: @code{'dual})
Restricts all controllers to the specified transport. @code{'dual} means
both BR/EDR and LE are enabled (if supported by the hardware).

Possible values are:

@itemize @bullet
@item
@code{'dual}

@item
@code{'bredr}

@item
@code{'le}

@end itemize

@item @code{multi-profile} (default: @code{'off})
Enables Multi Profile Specification support. This allows to specify if
system supports only Multiple Profiles Single Device (MPSD) configuration or
both Multiple Profiles Single Device (MPSD) and Multiple Profiles Multiple
Devices (MPMD) configurations.

Possible values are:

@itemize @bullet
@item
@code{'off}

@item
@code{'single}

@item
@code{'multiple}

@end itemize

@item @code{fast-connectable?} (padrão: @code{#f})
Permanently enables the Fast Connectable setting for adapters that support
it. When enabled other devices can connect faster to us, however the
tradeoff is increased power consumptions. This feature will fully work only
on kernel version 4.1 and newer.

@item @code{privacy} (default: @code{'off})
Default privacy settings.

@itemize @bullet
@item
@code{'off}: Disable local privacy

@item
@code{'network/on}: A device will only accept advertising packets from peer
devices that contain private addresses. It may not be compatible with some
legacy devices since it requires the use of RPA(s) all the time

@item
@code{'device}: A device in device privacy mode is only concerned about the
privacy of the device and will accept advertising packets from peer devices
that contain their Identity Address as well as ones that contain a private
address, even if the peer device has distributed its IRK in the past

@end itemize

and additionally, if @var{controller-mode} is set to @code{'dual}:

@itemize @bullet
@item
@code{'limited-network}: Apply Limited Discoverable Mode to advertising,
which follows the same policy as to BR/EDR that publishes the identity
address when discoverable, and Network Privacy Mode for scanning

@item
@code{'limited-device}: Apply Limited Discoverable Mode to advertising,
which follows the same policy as to BR/EDR that publishes the identity
address when discoverable, and Device Privacy Mode for scanning.

@end itemize

@item @code{just-works-repairing} (default: @code{'never})
Specify the policy to the JUST-WORKS repairing initiated by peer.

Possible values:
@itemize @bullet
@item
@code{'never}

@item
@code{'confirm}

@item
@code{'always}

@end itemize

@item @code{temporary-timeout} (default: @code{30})
How long to keep temporary devices around. The value is in seconds. @code{0}
disables the timer completely.

@item @code{refresh-discovery?} (default: @code{#t})
Enables the device to issue an SDP request to update known services when
profile is connected.

@item @code{experimental} (default: @code{#f})
Enables experimental features and interfaces, alternatively a list of UUIDs
can be given.

Possible values:

@itemize @bullet
@item
@code{#t}

@item
@code{#f}

@item
@code{(list (uuid <uuid-1>) (uuid <uuid-2>) ...)}.
@end itemize

List of possible UUIDs:
@itemize @bullet
@item
@code{d4992530-b9ec-469f-ab01-6c481c47da1c}: BlueZ Experimental Debug,

@item
@code{671b10b5-42c0-4696-9227-eb28d1b049d6}: BlueZ Experimental Simultaneous
Central and Peripheral,

@item
@code{15c0a148-c273-11ea-b3de-0242ac130004}: BlueZ Experimental LL privacy,

@item
@code{330859bc-7506-492d-9370-9a6f0614037f}: BlueZ Experimental Bluetooth
Quality Report,

@item
@code{a6695ace-ee7f-4fb9-881a-5fac66c629af}: BlueZ Experimental Offload
Codecs.
@end itemize

@item @code{remote-name-request-retry-delay} (default: @code{300})
The duration to avoid retrying to resolve a peer's name, if the previous try
failed.

@item @code{page-scan-type} (default: @code{#f})
BR/EDR Page scan activity type.

@item @code{page-scan-interval} (default: @code{#f})
BR/EDR Page scan activity interval.

@item @code{page-scan-window} (default: @code{#f})
BR/EDR Page scan activity window.

@item @code{inquiry-scan-type} (default: @code{#f})
BR/EDR Inquiry scan activity type.

@item @code{inquiry-scan-interval} (default: @code{#f})
BR/EDR Inquiry scan activity interval.

@item @code{inquiry-scan-window} (default: @code{#f})
BR/EDR Inquiry scan activity window.

@item @code{link-supervision-timeout} (default: @code{#f})
BR/EDR Link supervision timeout.

@item @code{page-timeout} (default: @code{#f})
BR/EDR Page timeout.

@item @code{min-sniff-interval} (default: @code{#f})
BR/EDR minimum sniff interval.

@item @code{max-sniff-interval} (default: @code{#f})
BR/EDR maximum sniff interval.

@item @code{min-advertisement-interval} (default: @code{#f})
LE minimum advertisement interval (used for legacy advertisement only).

@item @code{max-advertisement-interval} (default: @code{#f})
LE maximum advertisement interval (used for legacy advertisement only).

@item @code{multi-advertisement-rotation-interval} (default: @code{#f})
LE multiple advertisement rotation interval.

@item @code{scan-interval-auto-connect} (default: @code{#f})
LE scanning interval used for passive scanning supporting auto connect.

@item @code{scan-window-auto-connect} (default: @code{#f})
LE scanning window used for passive scanning supporting auto connect.

@item @code{scan-interval-suspend} (default: @code{#f})
LE scanning interval used for active scanning supporting wake from suspend.

@item @code{scan-window-suspend} (default: @code{#f})
LE scanning window used for active scanning supporting wake from suspend.

@item @code{scan-interval-discovery} (default: @code{#f})
LE scanning interval used for active scanning supporting discovery.

@item @code{scan-window-discovery} (default: @code{#f})
LE scanning window used for active scanning supporting discovery.

@item @code{scan-interval-adv-monitor} (default: @code{#f})
LE scanning interval used for passive scanning supporting the advertisement
monitor APIs.

@item @code{scan-window-adv-monitor} (default: @code{#f})
LE scanning window used for passive scanning supporting the advertisement
monitor APIs.

@item @code{scan-interval-connect} (default: @code{#f})
LE scanning interval used for connection establishment.

@item @code{scan-window-connect} (default: @code{#f})
LE scanning window used for connection establishment.

@item @code{min-connection-interval} (default: @code{#f})
LE default minimum connection interval. This value is superseded by any
specific value provided via the Load Connection Parameters interface.

@item @code{max-connection-interval} (default: @code{#f})
LE default maximum connection interval. This value is superseded by any
specific value provided via the Load Connection Parameters interface.

@item @code{connection-latency} (default: @code{#f})
LE default connection latency. This value is superseded by any specific
value provided via the Load Connection Parameters interface.

@item @code{connection-supervision-timeout} (default: @code{#f})
LE default connection supervision timeout. This value is superseded by any
specific value provided via the Load Connection Parameters interface.

@item @code{autoconnect-timeout} (default: @code{#f})
LE default autoconnect timeout. This value is superseded by any specific
value provided via the Load Connection Parameters interface.

@item @code{adv-mon-allowlist-scan-duration} (default: @code{300})
Allowlist scan duration during interleaving scan. Only used when scanning
for ADV monitors. The units are msec.

@item @code{adv-mon-no-filter-scan-duration} (default: @code{500})
No filter scan duration during interleaving scan. Only used when scanning
for ADV monitors. The units are msec.

@item @code{enable-adv-mon-interleave-scan?} (default: @code{#t})
Enable/Disable Advertisement Monitor interleave scan for power saving.

@item @code{cache} (default: @code{'always})
GATT attribute cache.

Possible values are:
@itemize @bullet
@item
@code{'always}: Always cache attributes even for devices not paired, this is
recommended as it is best for interoperability, with more consistent
reconnection times and enables proper tracking of notifications for all
devices

@item
@code{'yes}: Only cache attributes of paired devices

@item
@code{'no}: Never cache attributes.
@end itemize

@item @code{key-size} (default: @code{0})
Minimum required Encryption Key Size for accessing secured characteristics.

Possible values are:
@itemize @bullet
@item
@code{0}: Don't care

@item
@code{7 <= N <= 16}
@end itemize

@item @code{exchange-mtu} (default: @code{517})
Exchange MTU size. Possible values are:

@itemize @bullet
@item
@code{23 <= N <= 517}
@end itemize

@item @code{att-channels} (default: @code{3})
Number of ATT channels. Possible values are:

@itemize @bullet
@item
@code{1}: Disables EATT

@item
@code{2 <= N <= 5}
@end itemize

@item @code{session-mode} (default: @code{'basic})
AVDTP L2CAP signalling channel mode.

Possible values are:

@itemize @bullet
@item
@code{'basic}: Use L2CAP basic mode

@item
@code{'ertm}: Use L2CAP enhanced retransmission mode.
@end itemize

@item @code{stream-mode} (default: @code{'basic})
AVDTP L2CAP transport channel mode.

Possible values are:

@itemize @bullet
@item
@code{'basic}: Use L2CAP basic mode

@item
@code{'streaming}: Use L2CAP streaming mode.
@end itemize

@item @code{reconnect-uuids} (default: @code{'()})
The ReconnectUUIDs defines the set of remote services that should try to be
reconnected to in case of a link loss (link supervision timeout). The policy
plugin should contain a sane set of values by default, but this list can be
overridden here. By setting the list to empty the reconnection feature gets
disabled.

Possible values:

@itemize @bullet
@item
@code{'()}

@item
@code{(list (uuid <uuid-1>) (uuid <uuid-2>) ...)}.
@end itemize

@item @code{reconnect-attempts} (default: @code{7})
Defines the number of attempts to reconnect after a link lost. Setting the
value to 0 disables reconnecting feature.

@item @code{reconnect-intervals} (default: @code{'(1 2 4 8 16 32 64)})
Defines a list of intervals in seconds to use in between attempts. If the
number of attempts defined in @var{reconnect-attempts} is bigger than the
list of intervals the last interval is repeated until the last attempt.

@item @code{auto-enable?} (default: @code{#f})
Defines option to enable all controllers when they are found. This includes
adapters present on start as well as adapters that are plugged in later on.

@item @code{resume-delay} (default: @code{2})
Audio devices that were disconnected due to suspend will be reconnected on
resume. @var{resume-delay} determines the delay between when the controller
resumes from suspend and a connection attempt is made. A longer delay is
better for better co-existence with Wi-Fi. The value is in seconds.

@item @code{rssi-sampling-period} (default: @code{#xFF})
Default RSSI Sampling Period. This is used when a client registers an
advertisement monitor and leaves the RSSISamplingPeriod unset.

Possible values are:
@itemize @bullet
@item
@code{#x0}: Report all advertisements

@item
@code{N = #xXX}: Report advertisements every N x 100 msec (range: #x01 to
#xFE)

@item
@code{#xFF}: Report only one advertisement per device during monitoring
period.
@end itemize

@end table
@end deftp

@defvar gnome-keyring-service-type
This is the type of the service that adds the
@uref{https://wiki.gnome.org/Projects/GnomeKeyring, GNOME Keyring}.  Its
value is a @code{gnome-keyring-configuration} object (see below).  Note that
there is no need to use this service when using
@code{gnome-desktop-service-type}, which includes it.

This service adds the @code{gnome-keyring} package to the system profile and
extends PAM with entries using @code{pam_gnome_keyring.so}, unlocking a
user's login keyring when they log in or setting its password with passwd.
@end defvar

@deftp {Tipo de dados} gnome-keyring-configuration
Configuration record for the GNOME Keyring service.

@table @asis
@item @code{keyring} (default: @code{gnome-keyring})
The GNOME keyring package to use.

@item @code{pam-services}
A list of @code{(@var{service} . @var{kind})} pairs denoting PAM services to
extend, where @var{service} is the name of an existing service to extend and
@var{kind} is one of @code{login} or @code{passwd}.

If @code{login} is given, it adds an optional @code{pam_gnome_keyring.so} to
the auth block without arguments and to the session block with
@code{auto_start}.  If @code{passwd} is given, it adds an optional
@code{pam_gnome_keyring.so} to the password block without arguments.

By default, this field contains ``gdm-password'' with the value @code{login}
and ``passwd'' is with the value @code{passwd}.
@end table
@end deftp

@defvar kwallet-service-type
This is the type of the service that adds the
@uref{https://invent.kde.org/plasma/kwallet-pam, KWallet keyring}.  Its
value is a @code{kwallet-configuration} object (see below).  Note that,
contrary to @code{gnome-desktop-service-type}, which includes the respective
keyring for that service, @code{gnome-keyring-service-type},
@code{plasma-desktop-service-type} does not include
@code{kwallet-service-type}.

This service adds the @code{kwallet-pam} package to the system profile and
extends PAM with entries using @code{pam_kwallet5.so}.  It can unlock the
user's login keyring or set their password with @command{passwd} at the time
they log in.
@end defvar

@deftp {Data Type} kwallet-configuration
Configuration record for the KWallet Keyring service.

@table @asis
@item @code{keyring} (default: @code{kwallet-pam})
The KWallet keyring package to use.

@item @code{pam-services}
A list of @code{(@var{service} . @var{kind})} pairs denoting PAM services to
extend, where @var{service} is the name of an existing service to extend and
@var{kind} is one of @code{login} or @code{passwd} symbols.

If @code{login} is given, it adds an optional @code{pam_kwallet5.so} to the
auth block without arguments and to the session block with
@code{auto_start}.  If @code{passwd} is given, it adds an optional
@code{pam_kwallet5.so} to the password block without arguments.

By default, it takes for value an alist associating the @code{"sddm"} key
with the @code{'login} value, and the @code{"passwd"} key with the
@code{'passwd} value.
@end table
@end deftp

@defvar seatd-service-type
@uref{https://sr.ht/~kennylevinsen/seatd/, seatd} is a minimal seat
management daemon.

Seat management takes care of mediating access to shared devices (graphics,
input), without requiring the applications needing access to be root.

@lisp
(append
  (list
   ;; make sure seatd is running
   (service seatd-service-type))

  ;; normally one would want %base-services
  %base-services)

@end lisp

@code{seatd} operates over a UNIX domain socket, with @code{libseat}
providing the client side of the protocol.  Applications that acquire access
to the shared resources via @code{seatd} (e.g. @code{sway})  need to be able
to talk to this socket.  This can be achieved by adding the user they run
under to the group owning @code{seatd}'s socket (usually ``seat''), like so:

@lisp
(user-account
  (name "alice")
  (group "users")
  (supplementary-groups '("wheel"   ; allow use of sudo, etc.
                          "seat"    ; seat management
                          "audio"   ; sound card
                          "video"   ; video devices such as webcams
                          "cdrom")) ; the good ol' CD-ROM
  (comment "Bob's sister"))
@end lisp

Depending on your setup, you will have to not only add regular users, but
also system users to this group.  For instance, some greetd greeters require
graphics and therefore also need to negotiate with seatd.

@end defvar

@deftp {Tipo de dados} seatd-configuration
Configuration record for the seatd daemon service.

@table @asis
@item @code{seatd} (default: @code{seatd})
The seatd package to use.

@item @code{group} (default: @samp{"seat"})
Group to own the seatd socket.

@item @code{socket} (default: @samp{"/run/seatd.sock"})
Where to create the seatd socket.

@item @code{logfile} (default: @samp{"/var/log/seatd.log"})
Log file to write to.

@item @code{loglevel} (default: @samp{"error"})
Log level to output logs. Possible values: @samp{"silent"}, @samp{"error"},
@samp{"info"} and @samp{"debug"}.

@end table
@end deftp


@node Serviços de som
@subsection Serviços de som

@cindex sound support
@cindex ALSA
@cindex PulseAudio, sound support

The @code{(gnu services sound)} module provides a service to configure the
Advanced Linux Sound Architecture (ALSA) system, which makes PulseAudio the
preferred ALSA output driver.

@defvar alsa-service-type
This is the type for the @uref{https://alsa-project.org/, Advanced Linux
Sound Architecture} (ALSA) system, which generates the
@file{/etc/asound.conf} configuration file.  The value for this type is a
@command{alsa-configuration} record as in this example:

@lisp
(service alsa-service-type)
@end lisp

See below for details about @code{alsa-configuration}.
@end defvar

@deftp {Tipo de dados} alsa-configuration
Data type representing the configuration for @code{alsa-service}.

@table @asis
@item @code{alsa-plugins} (default: @var{alsa-plugins})
@code{alsa-plugins} package to use.

@item @code{pulseaudio?} (default: @var{#t})
Whether ALSA applications should transparently be made to use the
@uref{https://www.pulseaudio.org/, PulseAudio} sound server.

Using PulseAudio allows you to run several sound-producing applications at
the same time and to individual control them @i{via} @command{pavucontrol},
among other things.

@item @code{extra-options} (default: @var{""})
String to append to the @file{/etc/asound.conf} file.

@end table
@end deftp

Individual users who want to override the system configuration of ALSA can
do it with the @file{~/.asoundrc} file:

@example
# In guix, we have to specify the absolute path for plugins.
pcm_type.jack @{
  lib "/home/alice/.guix-profile/lib/alsa-lib/libasound_module_pcm_jack.so"
@}

# Routing ALSA to jack:
# <http://jackaudio.org/faq/routing_alsa.html>.
pcm.rawjack @{
  type jack
  playback_ports @{
    0 system:playback_1
    1 system:playback_2
  @}

  capture_ports @{
    0 system:capture_1
    1 system:capture_2
  @}
@}

pcm.!default @{
  type plug
  slave @{
    pcm "rawjack"
  @}
@}
@end example

See @uref{https://www.alsa-project.org/main/index.php/Asoundrc} for the
details.

@defvar pulseaudio-service-type
This is the type for the @uref{https://www.pulseaudio.org/, PulseAudio}
sound server.  It exists to allow system overrides of the default settings
via @code{pulseaudio-configuration}, see below.

@quotation Aviso
This service overrides per-user configuration files.  If you want PulseAudio
to honor configuration files in @file{~/.config/pulse}, you have to unset
the environment variables @env{PULSE_CONFIG} and @env{PULSE_CLIENTCONFIG} in
your @file{~/.bash_profile}.
@end quotation

@quotation Aviso
This service on its own does not ensure, that the @code{pulseaudio} package
exists on your machine.  It merely adds configuration files for it, as
detailed below.  In the (admittedly unlikely) case, that you find yourself
without a @code{pulseaudio} package, consider enabling it through the
@code{alsa-service-type} above.
@end quotation
@end defvar

@deftp {Tipo de dados} pulseaudio-configuration
Data type representing the configuration for @code{pulseaudio-service}.

@table @asis
@item @code{client-conf} (default: @code{'()})
List of settings to set in @file{client.conf}.  Accepts a list of strings or
symbol-value pairs.  A string will be inserted as-is with a newline added.
A pair will be formatted as ``key = value'', again with a newline added.

@item @code{daemon-conf} (default: @code{'((flat-volumes . no))})
List of settings to set in @file{daemon.conf}, formatted just like
@var{client-conf}.

@item @code{script-file} (default: @code{(file-append pulseaudio "/etc/pulse/default.pa")})
Script file to use as @file{default.pa}.  In case the
@code{extra-script-files} field below is used, an @code{.include} directive
pointing to @file{/etc/pulse/default.pa.d} is appended to the provided
script.

@item @code{extra-script-files} (default: @code{'()})
A list of file-like objects defining extra PulseAudio scripts to run at the
initialization of the @command{pulseaudio} daemon, after the main
@code{script-file}.  The scripts are deployed to the
@file{/etc/pulse/default.pa.d} directory; they should have the @samp{.pa}
file name extension.  For a reference of the available commands, refer to
@command{man pulse-cli-syntax}.

@item @code{system-script-file} (default: @code{(file-append pulseaudio "/etc/pulse/system.pa")})
Script file to use as @file{system.pa}.
@end table

The example below sets the default PulseAudio card profile, the default sink
and the default source to use for a old SoundBlaster Audigy sound card:
@lisp
(pulseaudio-configuration
 (extra-script-files
  (list (plain-file "audigy.pa"
                    (string-append "\
set-card-profile alsa_card.pci-0000_01_01.0 \
  output:analog-surround-40+input:analog-mono
set-default-source alsa_input.pci-0000_01_01.0.analog-mono
set-default-sink alsa_output.pci-0000_01_01.0.analog-surround-40\n")))))
@end lisp

Note that @code{pulseaudio-service-type} is part of
@code{%desktop-services}; if your operating system declaration was derived
from one of the desktop templates, you'll want to adjust the above example
to modify the existing @code{pulseaudio-service-type} via
@code{modify-services} (@pxref{Referência de Service, @code{modify-services}}),
instead of defining a new one.

@end deftp

@defvar ladspa-service-type
This service sets the @var{LADSPA_PATH} variable, so that programs, which
respect it, e.g.@: PulseAudio, can load LADSPA plugins.

The following example will setup the service to enable modules from the
@code{swh-plugins} package:

@lisp
(service ladspa-service-type
         (ladspa-configuration (plugins (list swh-plugins))))
@end lisp

See @uref{http://plugin.org.uk/ladspa-swh/docs/ladspa-swh.html} for the
details.

@end defvar

@subsubheading Speaker Safety Daemon System Service

@uref{https://github.com/AsahiLinux/speakersafetyd, Speaker Safety Daemon}
is a user-space daemon that implements an analogue of the Texas Instruments
Smart Amp speaker protection model.  It can be used to protect the speakers
on Apple Silicon devices.

@defvar speakersafetyd-service-type
This is the type for the @code{speakersafetyd} system service, whose value
is a @command{speakersafetyd-configuration} record.

@lisp
(service speakersafetyd-service-type)
@end lisp

See below for details about @code{speakersafetyd-configuration}.
@end defvar

@c %start of fragment
@deftp {Data Type} speakersafetyd-configuration
Available @code{speakersafetyd-configuration} fields are:

@table @asis
@item @code{blackbox-directory} (default: @code{"/var/lib/speakersafetyd/blackbox"}) (type: string)
The directory to which blackbox files are written when the speakers are
getting too hot.  The blackbox files contain audio and debug information
which the developers of @code{speakersafetyd} might ask for when reporting
bugs.

@item @code{configuration-directory} (type: file-like)
The base directory as a G-expression (@pxref{Expressões-G}) that contains
the configuration files of the speaker models.

@item @code{group} (default: @code{"speakersafetyd"}) (type: string)
The group to run the Speaker Safety Daemon as.

@item @code{log-file} (default: @code{"/var/log/speakersafetyd.log"}) (type: string)
The file name to the Speaker Safety Daemon log file.

@item @code{maximum-gain-reduction} (default: @code{7}) (type: integer)
Maximum gain reduction before panicking, useful for debugging.

@item @code{speakersafetyd} (default: @code{speakersafetyd}) (type: file-like)
The Speaker Safety Daemon package to use.

@item @code{user} (default: @code{"speakersafetyd"}) (type: string)
The user to run the Speaker Safety Daemon as.

@end table
@end deftp
@c %end of fragment

@node File Search Services
@subsection File Search Services

@cindex file search
@cindex searching for a file
The services in this section populate @dfn{file databases} that let you
search for files on your machine.  These services are provided by the
@code{(gnu services admin)} module.

The first one, @code{file-database-service-type}, periodically runs the
venerable @command{updatedb} command (@pxref{Invoking updatedb,,, find, GNU
Findutils}).  That command populates a database of file names that you can
then search with the @command{locate} command (@pxref{Invoking locate,,,
find, GNU Findutils}), as in this example:

@example
locate important-notes.txt
@end example

You can enable this service with its default settings by adding this snippet
to your operating system services:

@lisp
(service file-database-service-type)
@end lisp

This updates the database once a week, excluding files from
@file{/gnu/store}---these are more usefully handled by @command{guix locate}
(@pxref{Invocando guix locate}).  You can of course provide a custom
configuration, as described below.

@defvar file-database-service-type
This is the type of the file database service, which runs @command{updatedb}
periodically.  Its associated value must be a
@code{file-database-configuration} record, as described below.
@end defvar

@deftp {Tipo de dados} file-database-configuration
Record type for the @code{file-database-service-type} configuration, with
the following fields:

@table @asis
@item @code{package} (default: @code{findutils})
The package from which the @command{updatedb} command is taken.  Examples of
such packages are GNU@tie{}Findutils and Plocate.

@item @code{schedule} (default: @code{%default-file-database-update-schedule})
This is the schedule of database updates, expressed as a string in
traditional cron syntax or as a gexp evaluating to a Shepherd calendar event
(@pxref{Timers,,, shepherd, The GNU Shepherd Manual}).

@item @code{excluded-directories} (default @code{%default-file-database-excluded-directories})
List of regular expressions of directories to ignore when building the file
database.  By default, this includes @file{/tmp} and @file{/gnu/store}; the
latter should instead be indexed by @command{guix locate} (@pxref{Invocando guix locate}).  This list is passed to the @option{--prunepaths} option of
@command{updatedb} (@pxref{Invoking updatedb,,, find, GNU@tie{}Findutils}).
@end table
@end deftp

The second service, @code{package-database-service-type}, builds the
database used by @command{guix locate}, which lets you search for packages
that contain a given file (@pxref{Invocando guix locate}).  The service
periodically updates a system-wide database, which will be readily available
to anyone running @command{guix locate} on the system.  To use this service
with its default settings, add this snippet to your service list:

@lisp
(service package-database-service-type)
@end lisp

This will run @command{guix locate --update} once a week.

@defvar package-database-service-type
This is the service type for periodic @command{guix locate} updates
(@pxref{Invocando guix locate}).  Its value must be a
@code{package-database-configuration} record, as shown below.
@end defvar

@deftp {Tipo de dados} package-database-configuration
Data type to configure periodic package database updates.  It has the
following fields:

@table @asis
@item @code{package} (default: @code{guix})
The Guix package to use.

@item @code{schedule} (default: @code{%default-package-database-update-schedule})
This is the schedule of the periodic @command{guix locate --update} job,
expressed as a string in traditional cron syntax or as a gexp evaluating to
a Shepherd calendar event (@pxref{Timers,,, shepherd, The GNU Shepherd
Manual}).

@item @code{method} (default: @code{'store})
Indexing method for @command{guix locate}.  The default value,
@code{'store}, yields a more complete database but is relatively expensive
in terms of CPU and input/output.

@item @code{channels} (default: @code{#~%default-channels})
G-exp denoting the channels to use when updating the database
(@pxref{Canais}).
@end table
@end deftp


@node Serviços de bancos de dados
@subsection Serviços de bancos de dados

@cindex database
@cindex SQL
The @code{(gnu services databases)} module provides the following services.

@subsubheading PostgreSQL

@defvar postgresql-service-type
The service type for the PostgreSQL database server.  Its value should be a
valid @code{postgresql-configuration} object, documented below.  The
following example describes a PostgreSQL service with the default
configuration.

@lisp
(service postgresql-service-type
         (postgresql-configuration
          (postgresql postgresql)))
@end lisp

If the services fails to start, it may be due to an incompatible cluster
already present in @var{data-directory}.  Adjust it (or, if you don't need
the cluster anymore, delete @var{data-directory}), then restart the service.

Peer authentication is used by default and the @code{postgres} user account
has no shell (unless @code{allow-login?} is @code{#t}), which prevents the
direct execution of @code{psql} commands as this user.  To use @code{psql},
you can temporarily log in as @code{postgres} using a shell, create a
PostgreSQL superuser with the same name as one of the system users and then
create the associated database.

@example
sudo -u postgres -s /bin/sh
createuser --interactive
createdb $MY_USER_LOGIN      # Replace appropriately.
@end example
@end defvar

@deftp {Tipo de dados} postgresql-configuration
Data type representing the configuration for the
@code{postgresql-service-type}.

@table @asis
@item @code{postgresql}
PostgreSQL package to use for the service.

@item @code{port} (padrão: @code{5432})
Port on which PostgreSQL should listen.

@item @code{locale} (default: @code{"en_US.utf8"})
Locale to use as the default when creating the database cluster.

@item @code{config-file} (default: @code{(postgresql-config-file)})
The configuration file to use when running PostgreSQL@.  The default
behaviour uses the postgresql-config-file record with the default values for
the fields.

@item @code{log-directory} (default: @code{"/var/log/postgresql"})
The directory where @command{pg_ctl} output will be written in a file named
@code{"pg_ctl.log"}.  This file can be useful to debug PostgreSQL
configuration errors for instance.

@item @code{data-directory} (default: @code{"/var/lib/postgresql/data"})
Directory in which to store the data.

@item @code{extension-packages} (default: @code{'()})
@cindex postgresql extension-packages
Additional extensions are loaded from packages listed in
@var{extension-packages}.  Extensions are available at runtime.  For
instance, to create a geographic database using the @code{postgis}
extension, a user can configure the postgresql-service as in this example:

@cindex postgis
@lisp
(use-package-modules databases geo)

(operating-system
  ...
  ;; postgresql is required to run `psql' but postgis is not required for
  ;; proper operation.
  (packages (cons* postgresql %base-packages))
  (services
    (cons*
      (service postgresql-service-type
               (postgresql-configuration
                (postgresql postgresql)
                (extension-packages (list postgis))))
      %base-services)))
@end lisp

Then the extension becomes visible and you can initialise an empty
geographic database in this way:

@example
psql -U postgres
> create database postgistest;
> \connect postgistest;
> create extension postgis;
> create extension postgis_topology;
@end example

There is no need to add this field for contrib extensions such as hstore or
dblink as they are already loadable by postgresql.  This field is only
required to add extensions provided by other packages.

@item @code{create-account?} (default: @code{#t})
Whether or not the @code{postgres} user and group should be created.

@item @code{allow-login?} (default: @code{#f})
Whether or not to allow login into the created account.

@item @code{home-directory} (default: @code{"/var/empty"})
The home directory of the user.  It is strongly advised to change this if
you set @code{allow-login?} to @code{#t}.

@item @code{uid} (padrão: @code{#f})
Explicitly specify the UID of the @code{postgres} daemon account.  You
normally do not need to specify this, in which case a free UID will be
automatically assigned.

One situation where this option might be useful is if the
@var{data-directory} is located on a mounted network share.

@item @code{gid} (default: @code{#f})
Explicitly specify the GID of the @code{postgres} group.

@end table
@end deftp

@deftp {Tipo de dados} postgresql-config-file
Data type representing the PostgreSQL configuration file.  As shown in the
following example, this can be used to customize the configuration of
PostgreSQL@.  Note that you can use any G-expression or filename in place of
this record, if you already have a configuration file you'd like to use for
example.

@lisp
(service postgresql-service-type
         (postgresql-configuration
          (config-file
           (postgresql-config-file
            (log-destination "stderr")
            (hba-file
             (plain-file "pg_hba.conf"
                         "
local	all	all			trust
host	all	all	127.0.0.1/32 	md5
host	all	all	::1/128 	md5"))
            (extra-config
             '(("session_preload_libraries"     "auto_explain")
               ("random_page_cost"              2)
               ("auto_explain.log_min_duration" "100 ms")
               ("work_mem"                      "500 MB")
               ("logging_collector"             #t)
               ("log_directory"                 "/var/log/postgresql")))))))
@end lisp

@table @asis
@item @code{log-destination} (default: @code{"syslog"})
The logging method to use for PostgreSQL@.  Multiple values are accepted,
separated by commas.

@item @code{hba-file} (default: @code{%default-postgres-hba})
Filename or G-expression for the host-based authentication configuration.

@item @code{ident-file} (default: @code{%default-postgres-ident})
Filename or G-expression for the user name mapping configuration.

@item @code{socket-directory} (default: @code{"/var/run/postgresql"})
Specifies the directory of the Unix-domain socket(s) on which PostgreSQL is
to listen for connections from client applications. If set to @code{""}
PostgreSQL does not listen on any Unix-domain sockets, in which case only
TCP/IP sockets can be used to connect to the server.

By default, the @code{#false} value means the PostgreSQL default value will
be used, which is currently @samp{/tmp}.

@item @code{extra-config} (default: @code{'()})
List of additional keys and values to include in the PostgreSQL config
file.  Each entry in the list should be a list where the first element is
the key, and the remaining elements are the values.

The values can be numbers, booleans or strings and will be mapped to
PostgreSQL parameters types @code{Boolean}, @code{String}, @code{Numeric},
@code{Numeric with Unit} and @code{Enumerated} described
@uref{https://www.postgresql.org/docs/current/config-setting.html, here}.

@end table
@end deftp

@defvar postgresql-role-service-type
This service allows to create PostgreSQL roles and databases after
PostgreSQL service start.  Here is an example of its use.

@lisp
(service postgresql-role-service-type
            (postgresql-role-configuration
             (roles
              (list (postgresql-role
                     (name "test")
                     (create-database? #t))))))
@end lisp

This service can be extended with extra roles, as in this example:

@lisp
(service-extension postgresql-role-service-type
                   (const (list
                           (postgresql-role
                            (name "alice")
                            (create-database? #t)))))
@end lisp
@end defvar

@deftp {Tipo de dados} postgresql-role
PostgreSQL manages database access permissions using the concept of roles.
A role can be thought of as either a database user, or a group of database
users, depending on how the role is set up.  Roles can own database objects
(for example, tables) and can assign privileges on those objects to other
roles to control who has access to which objects.

@table @asis
@item @code{name}
The role name.

@item @code{permissions} (default: @code{'(createdb login)})
The role permissions list.  Supported permissions are @code{bypassrls},
@code{createdb}, @code{createrole}, @code{login}, @code{replication} and
@code{superuser}.

@item @code{create-database?} (default: @code{#f})
whether to create a database with the same name as the role.

@item @code{password-file} (default: @code{#f})
A string representing the path of a file that contains the password to be
set for the role.

@item @code{encoding} (default: @code{"UTF8"})
The character set to use for storing text in the database.

@item @code{collation} (default: @code{"en_US.utf8"})
The string sort order locale setting.

@item @code{ctype} (default: @code{"en_US.utf8"})
The character classification locale setting.

@item @code{template} (default: @code{"template1"})
The default template to copy the new database from when creating it.  Use
@code{"template0"} for a pristine database with no system-local
modifications.

@end table
@end deftp

@deftp {Tipo de dados} postgresql-role-configuration
Data type representing the configuration of
@var{postgresql-role-service-type}.

@table @asis
@item @code{host} (default: @code{"/var/run/postgresql"})
The PostgreSQL host to connect to.

@item @code{log} (default: @code{"/var/log/postgresql_roles.log"})
File name of the log file.

@item @code{shepherd-requirement} (default: @code{'(user-processes postgres)})

The Shepherd services dependencies to use.  Add extra dependencies to
@code{%default-postgresql-role-shepherd-requirement} to extend its value.

@item @code{roles} (default: @code{'()})
The initial PostgreSQL roles to create.
@end table
@end deftp

@subsubheading MariaDB/MySQL

@defvar mysql-service-type
This is the service type for a MySQL or MariaDB database server.  Its value
is a @code{mysql-configuration} object that specifies which package to use,
as well as various settings for the @command{mysqld} daemon.
@end defvar

@deftp {Tipo de dados} mysql-configuration
Data type representing the configuration of @var{mysql-service-type}.

@table @asis
@item @code{mysql} (default: @var{mariadb})
Package object of the MySQL database server, can be either @var{mariadb} or
@var{mysql}.

For MySQL, a temporary root password will be displayed at activation time.
For MariaDB, the root password is empty.

@item @code{bind-address} (default: @code{"127.0.0.1"})
The IP on which to listen for network connections.  Use @code{"0.0.0.0"} to
bind to all available network interfaces.

@item @code{port} (padrão: @code{3306})
TCP port on which the database server listens for incoming connections.

@item @code{socket} (default: @code{"/run/mysqld/mysqld.sock"})
Socket file to use for local (non-network) connections.

@item @code{extra-content} (default: @code{""})
Additional settings for the @file{my.cnf} configuration file.

@item @code{extra-environment} (default: @code{#~'()})
List of environment variables passed to the @command{mysqld} process.

@item @code{auto-upgrade?} (default: @code{#t})
Whether to automatically run @command{mysql_upgrade} after starting the
service.  This is necessary to upgrade the @dfn{system schema} after
``major'' updates (such as switching from MariaDB 10.4 to 10.5), but can be
disabled if you would rather do that manually.

@end table
@end deftp

@subsubheading Memcached

@defvar memcached-service-type
This is the service type for the @uref{https://memcached.org/, Memcached}
service, which provides a distributed in memory cache.  The value for the
service type is a @code{memcached-configuration} object.
@end defvar

@lisp
(service memcached-service-type)
@end lisp

@deftp {Tipo de dados} memcached-configuration
Data type representing the configuration of memcached.

@table @asis
@item @code{memcached} (default: @code{memcached})
The Memcached package to use.

@item @code{interfaces} (default: @code{'("0.0.0.0")})
Network interfaces on which to listen.

@item @code{tcp-port} (default: @code{11211})
Port on which to accept connections.

@item @code{udp-port} (default: @code{11211})
Port on which to accept UDP connections on, a value of 0 will disable
listening on a UDP socket.

@item @code{additional-options} (default: @code{'()})
Additional command line options to pass to @code{memcached}.
@end table
@end deftp

@subsubheading Redis

@uref{https://redis.io/, Redis} is an in-memory data store used by millions
of developers as a cache, vector database, document database, streaming
engine, and message broker. Redis has built-in replication and different
levels of on-disk persistence. It supports complex data types (for example,
strings, hashes, lists, sets, sorted sets, and JSON), with atomic operations
defined on those data types.

@defvar redis-service-type
Type of the service that runs @command{redis}, an in-memory data store.  The
value for this service is a @code{<redis-configuration>} object.
@end defvar

@c %start of fragment

@deftp {Tipo de dados} redis-configuration
Available @code{redis-configuration} fields are:

@table @asis
@item @code{redis} (default: @code{redis}) (type: package)
The Redis package to use.

@item @code{bind} (default: @code{"127.0.0.1"}) (type: string)
Network interface on which to listen.

@item @code{port} (default: @code{6379}) (type: number)
Port on which to accept connections on, a value of 0 will disable listening
on a TCP socket.

@item @code{working-directory} (default: @code{"/var/lib/redis"}) (type: string)
Directory in which to store the database and related files.

@item @code{config-file} (type: maybe-string)
Default location for config file.

@end table

@end deftp


@c %end of fragment

@node Serviços de correio
@subsection Serviços de correio

@cindex mail
@cindex e-mail
The @code{(gnu services mail)} module provides Guix service definitions for
email services: IMAP, POP3, and LMTP servers, as well as mail transport
agents (MTAs).  Lots of acronyms! These services are detailed in the
subsections below.

@subsubheading Dovecot Service

@defvar dovecot-service-type
Type for the service that runs the Dovecot IMAP/POP3/LMTP mail server, whose
value is a @code{<dovecot-configuration>} object.
@end defvar

By default, Dovecot does not need much configuration; the default
configuration object created by @code{(dovecot-configuration)} will suffice
if your mail is delivered to @code{~/Maildir}.  A self-signed certificate
will be generated for TLS-protected connections, though Dovecot will also
listen on cleartext ports by default.  There are a number of options,
though, which mail administrators might need to change, and as is the case
with other services, Guix allows the system administrator to specify these
parameters via a uniform Scheme interface.

For example, to specify that mail is located at @code{maildir~/.mail}, one
would instantiate the Dovecot service like this:

@lisp
(service dovecot-service-type
         (dovecot-configuration
           (mail-location "maildir:~/.mail")))
@end lisp

The available configuration parameters follow.  Each parameter definition is
preceded by its type; for example, @samp{string-list foo} indicates that the
@code{foo} parameter should be specified as a list of strings.  There is
also a way to specify the configuration as a string, if you have an old
@code{dovecot.conf} file that you want to port over from some other system;
see the end for more details.

@c The following documentation was initially generated by
@c (generate-documentation) in (gnu services mail).  Manually maintained
@c documentation is better, so we shouldn't hesitate to edit below as
@c needed.  However if the change you want to make to this documentation
@c can be done in an automated way, it's probably easier to change
@c (generate-documentation) than to make it below and have to deal with
@c the churn as dovecot updates.

Available @code{dovecot-configuration} fields are:

@deftypevr {@code{dovecot-configuration} parameter} package dovecot
The dovecot package.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} package-list extensions
A list of additional Dovecot plugin packages to make available at
runtime. During service activation, the @file{lib/dovecot} directory from
each specified package is combined with Dovecot's core modules into a
unified module directory.

For example, to enable Sieve filtering:

@lisp
(extensions (list dovecot-pigeonhole))
@end lisp

Each package in the list must provide its modules at @file{lib/dovecot}, as
this is where @code{make-dovecot-moduledir} expects to find its
extensions. The service combines these directories to create a unified
module structure.

The default value is an empty list, providing only core Dovecot
functionality.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} comma-separated-string-list listen
A list of IPs or hosts where to listen for connections.  @samp{*} listens on
all IPv4 interfaces, @samp{::} listens on all IPv6 interfaces.  If you want
to specify non-default ports or anything more complex, customize the address
and port fields of the @samp{inet-listener} of the specific services you are
interested in.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} protocol-configuration-list protocols
List of protocols we want to serve.  Available protocols include
@samp{imap}, @samp{pop3}, and @samp{lmtp}.

Available @code{protocol-configuration} fields are:

@deftypevr {@code{protocol-configuration} parameter} string name
The name of the protocol.
@end deftypevr

@deftypevr {@code{protocol-configuration} parameter} string auth-socket-path
UNIX socket path to the master authentication server to find users.  This is
used by imap (for shared users) and lda.  It defaults to
@samp{"/var/run/dovecot/auth-userdb"}.
@end deftypevr

@deftypevr {@code{protocol-configuration} parameter} boolean imap-metadata?
Whether to enable the @code{IMAP METADATA} extension as defined in
@uref{https://tools.ietf.org/html/rfc5464,RFC@tie{}5464}, which provides a
means for clients to set and retrieve per-mailbox, per-user metadata and
annotations over IMAP.

If this is @samp{#t}, you must also specify a dictionary @i{via} the
@code{mail-attribute-dict} setting.

Defaults to @samp{#f}.

@end deftypevr

@deftypevr {@code{protocol-configuration} parameter} space-separated-string-list managesieve-notify-capabilities
Which NOTIFY capabilities to report to clients that first connect to the
ManageSieve service, before authentication.  These may differ from the
capabilities offered to authenticated users.  If this field is left empty,
report what the Sieve interpreter supports by default.

Defaults to @samp{'()}.
@end deftypevr

@deftypevr {@code{protocol-configuration} parameter} space-separated-string-list managesieve-sieve-capability
Which SIEVE capabilities to report to clients that first connect to the
ManageSieve service, before authentication.  These may differ from the
capabilities offered to authenticated users.  If this field is left empty,
report what the Sieve interpreter supports by default.

Defaults to @samp{'()}.

@end deftypevr

@deftypevr {@code{protocol-configuration} parameter} space-separated-string-list mail-plugins
Space separated list of plugins to load.
@end deftypevr

@deftypevr {@code{protocol-configuration} parameter} non-negative-integer mail-max-userip-connections
Maximum number of IMAP connections allowed for a user from each IP address.
NOTE: The username is compared case-sensitively.  Defaults to @samp{10}.
@end deftypevr

@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} service-configuration-list services
List of services to enable.  Available services include @samp{imap},
@samp{imap-login}, @samp{pop3}, @samp{pop3-login}, @samp{auth}, and
@samp{lmtp}.

Available @code{service-configuration} fields are:

@deftypevr {@code{service-configuration} parameter} string kind
The service kind.  Valid values include @code{director}, @code{imap-login},
@code{pop3-login}, @code{lmtp}, @code{imap}, @code{pop3}, @code{auth},
@code{auth-worker}, @code{dict}, @code{tcpwrap}, @code{quota-warning}, or
anything else.
@end deftypevr

@deftypevr {@code{service-configuration} parameter} listener-configuration-list listeners
Listeners for the service.  A listener is either a
@code{unix-listener-configuration}, a @code{fifo-listener-configuration}, or
an @code{inet-listener-configuration}.  Defaults to @samp{'()}.

Available @code{unix-listener-configuration} fields are:

@deftypevr {@code{unix-listener-configuration} parameter} string path
Path to the file, relative to @code{base-dir} field.  This is also used as
the section name.
@end deftypevr

@deftypevr {@code{unix-listener-configuration} parameter} string mode
The access mode for the socket.  Defaults to @samp{"0600"}.
@end deftypevr

@deftypevr {@code{unix-listener-configuration} parameter} string user
The user to own the socket.  Defaults to @samp{""}.
@end deftypevr

@deftypevr {@code{unix-listener-configuration} parameter} string group
The group to own the socket.  Defaults to @samp{""}.
@end deftypevr


Available @code{fifo-listener-configuration} fields are:

@deftypevr {@code{fifo-listener-configuration} parameter} string path
Path to the file, relative to @code{base-dir} field.  This is also used as
the section name.
@end deftypevr

@deftypevr {@code{fifo-listener-configuration} parameter} string mode
The access mode for the socket.  Defaults to @samp{"0600"}.
@end deftypevr

@deftypevr {@code{fifo-listener-configuration} parameter} string user
The user to own the socket.  Defaults to @samp{""}.
@end deftypevr

@deftypevr {@code{fifo-listener-configuration} parameter} string group
The group to own the socket.  Defaults to @samp{""}.
@end deftypevr


Available @code{inet-listener-configuration} fields are:

@deftypevr {@code{inet-listener-configuration} parameter} string protocol
The protocol to listen for.
@end deftypevr

@deftypevr {@code{inet-listener-configuration} parameter} string address
The address on which to listen, or empty for all addresses.  Defaults to
@samp{""}.
@end deftypevr

@deftypevr {@code{inet-listener-configuration} parameter} non-negative-integer port
The port on which to listen.
@end deftypevr

@deftypevr {@code{inet-listener-configuration} parameter} boolean ssl?
Whether to use SSL for this service; @samp{yes}, @samp{no}, or
@samp{required}.  Defaults to @samp{#t}.
@end deftypevr

@end deftypevr

@deftypevr {@code{service-configuration} parameter} non-negative-integer client-limit
Maximum number of simultaneous client connections per process.  Once this
number of connections is received, the next incoming connection will prompt
Dovecot to spawn another process.  If set to 0, @code{default-client-limit}
is used instead.

Defaults to @samp{0}.

@end deftypevr

@deftypevr {@code{service-configuration} parameter} non-negative-integer service-count
Number of connections to handle before starting a new process.  Typically
the only useful values are 0 (unlimited) or 1.  1 is more secure, but 0 is
faster.  <doc/wiki/LoginProcess.txt>.  Defaults to @samp{1}.

@end deftypevr

@deftypevr {@code{service-configuration} parameter} non-negative-integer process-limit
Maximum number of processes that can exist for this service.  If set to 0,
@code{default-process-limit} is used instead.

Defaults to @samp{0}.

@end deftypevr

@deftypevr {@code{service-configuration} parameter} non-negative-integer process-min-avail
Number of processes to always keep waiting for more connections.  Defaults
to @samp{0}.
@end deftypevr

@deftypevr {@code{service-configuration} parameter} non-negative-integer vsz-limit
If you set @samp{service-count 0}, you probably need to grow this.  Defaults
to @samp{256000000}.
@end deftypevr

@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} dict-configuration dict
Dict configuration, as created by the @code{dict-configuration} constructor.

Available @code{dict-configuration} fields are:

@deftypevr {@code{dict-configuration} parameter} free-form-fields entries
A list of key-value pairs that this dict should hold.  Defaults to
@samp{'()}.
@end deftypevr

@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} passdb-configuration-list passdbs
A list of passdb configurations, each one created by the
@code{passdb-configuration} constructor.

Available @code{passdb-configuration} fields are:

@deftypevr {@code{passdb-configuration} parameter} string driver
The driver that the passdb should use.  Valid values include @samp{pam},
@samp{passwd}, @samp{shadow}, @samp{bsdauth}, and @samp{static}.  Defaults
to @samp{"pam"}.
@end deftypevr

@deftypevr {@code{passdb-configuration} parameter} space-separated-string-list args
Space separated list of arguments to the passdb driver.  Defaults to
@samp{""}.
@end deftypevr

@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} userdb-configuration-list userdbs
List of userdb configurations, each one created by the
@code{userdb-configuration} constructor.

Available @code{userdb-configuration} fields are:

@deftypevr {@code{userdb-configuration} parameter} string driver
The driver that the userdb should use.  Valid values include @samp{passwd}
and @samp{static}.  Defaults to @samp{"passwd"}.
@end deftypevr

@deftypevr {@code{userdb-configuration} parameter} space-separated-string-list args
Space separated list of arguments to the userdb driver.  Defaults to
@samp{""}.
@end deftypevr

@deftypevr {@code{userdb-configuration} parameter} free-form-args override-fields
Override fields from passwd.  Defaults to @samp{'()}.
@end deftypevr

@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} plugin-configuration plugin-configuration
Plug-in configuration, created by the @code{plugin-configuration}
constructor.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} list-of-namespace-configuration namespaces
List of namespaces.  Each item in the list is created by the
@code{namespace-configuration} constructor.

Available @code{namespace-configuration} fields are:

@deftypevr {@code{namespace-configuration} parameter} string name
Name for this namespace.
@end deftypevr

@deftypevr {@code{namespace-configuration} parameter} string type
Namespace type: @samp{private}, @samp{shared} or @samp{public}.  Defaults to
@samp{"private"}.
@end deftypevr

@deftypevr {@code{namespace-configuration} parameter} string separator
Hierarchy separator to use.  You should use the same separator for all
namespaces or some clients get confused.  @samp{/} is usually a good one.
The default however depends on the underlying mail storage format.  Defaults
to @samp{""}.
@end deftypevr

@deftypevr {@code{namespace-configuration} parameter} string prefix
Prefix required to access this namespace.  This needs to be different for
all namespaces.  For example @samp{Public/}.  Defaults to @samp{""}.
@end deftypevr

@deftypevr {@code{namespace-configuration} parameter} string location
Physical location of the mailbox. This is in the same format as
mail_location, which is also the default for it.  Defaults to @samp{""}.
@end deftypevr

@deftypevr {@code{namespace-configuration} parameter} boolean inbox?
There can be only one INBOX, and this setting defines which namespace has
it.  Defaults to @samp{#f}.
@end deftypevr

@deftypevr {@code{namespace-configuration} parameter} boolean hidden?
If namespace is hidden, it's not advertised to clients via NAMESPACE
extension.  You'll most likely also want to set @samp{list? #f}.  This is
mostly useful when converting from another server with different namespaces
which you want to deprecate but still keep working.  For example you can
create hidden namespaces with prefixes @samp{~/mail/}, @samp{~%u/mail/} and
@samp{mail/}.  Defaults to @samp{#f}.
@end deftypevr

@deftypevr {@code{namespace-configuration} parameter} boolean list?
Show the mailboxes under this namespace with the LIST command.  This makes
the namespace visible for clients that do not support the NAMESPACE
extension.  The special @code{children} value lists child mailboxes, but
hides the namespace prefix.  Defaults to @samp{#t}.
@end deftypevr

@deftypevr {@code{namespace-configuration} parameter} boolean subscriptions?
Namespace handles its own subscriptions.  If set to @code{#f}, the parent
namespace handles them.  The empty prefix should always have this as
@code{#t}).  Defaults to @samp{#t}.
@end deftypevr

@deftypevr {@code{namespace-configuration} parameter} mailbox-configuration-list mailboxes
List of predefined mailboxes in this namespace.  Defaults to @samp{'()}.

Available @code{mailbox-configuration} fields are:

@deftypevr {@code{mailbox-configuration} parameter} string name
Name for this mailbox.
@end deftypevr

@deftypevr {@code{mailbox-configuration} parameter} string auto
@samp{create} will automatically create this mailbox.  @samp{subscribe} will
both create and subscribe to the mailbox.  Defaults to @samp{"no"}.
@end deftypevr

@deftypevr {@code{mailbox-configuration} parameter} space-separated-string-list special-use
List of IMAP @code{SPECIAL-USE} attributes as specified by RFC 6154.  Valid
values are @code{\All}, @code{\Archive}, @code{\Drafts}, @code{\Flagged},
@code{\Junk}, @code{\Sent}, and @code{\Trash}.  Defaults to @samp{'()}.
@end deftypevr

@end deftypevr

@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} file-name base-dir
Base directory where to store runtime data.  Defaults to
@samp{"/var/run/dovecot/"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string login-greeting
Greeting message for clients.  Defaults to @samp{"Dovecot ready."}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list login-trusted-networks
List of trusted network ranges.  Connections from these IPs are allowed to
override their IP addresses and ports (for logging and for authentication
checks).  @samp{disable-plaintext-auth} is also ignored for these networks.
Typically you would specify your IMAP proxy servers here.  Defaults to
@samp{'()}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list login-access-sockets
List of login access check sockets (e.g.@: tcpwrap).  Defaults to
@samp{'()}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} boolean verbose-proctitle?
Show more verbose process titles (in ps).  Currently shows user name and IP
address.  Useful for seeing who is actually using the IMAP processes (e.g.@:
shared mailboxes or if the same uid is used for multiple accounts).
Defaults to @samp{#f}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} boolean shutdown-clients?
Should all processes be killed when Dovecot master process shuts down.
Setting this to @code{#f} means that Dovecot can be upgraded without forcing
existing client connections to close (although that could also be a problem
if the upgrade is e.g.@: due to a security fix).  Defaults to @samp{#t}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer doveadm-worker-count
If non-zero, run mail commands via this many connections to doveadm server,
instead of running them directly in the same process.  Defaults to @samp{0}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string doveadm-socket-path
UNIX socket or host:port used for connecting to doveadm server.  Defaults to
@samp{"doveadm-server"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list import-environment
List of environment variables that are preserved on Dovecot startup and
passed down to all of its child processes.  You can also give key=value
pairs to always set specific settings.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} boolean disable-plaintext-auth?
Disable LOGIN command and all other plaintext authentications unless SSL/TLS
is used (LOGINDISABLED capability).  Note that if the remote IP matches the
local IP (i.e.@: you're connecting from the same computer), the connection
is considered secure and plaintext authentication is allowed.  See also the
@samp{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}.  See also the
@samp{disable-plaintext-auth} setting.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list director-servers
List of IPs or hostnames to all director servers, including ourself.  Ports
can be specified as ip:port.  The default port is the same as what director
service's @samp{inet-listener} is using.  Defaults to @samp{'()}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list director-mail-servers
List of IPs or hostnames to all backend mail servers.  Ranges are allowed
too, like 10.0.0.10-10.0.0.30.  Defaults to @samp{'()}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string director-user-expire
How long to redirect users to a specific server after it no longer has any
connections.  Defaults to @samp{"15 min"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string director-username-hash
How the username is translated before being hashed.  Useful values include
%Ln if user can log in with or without @@domain, %Ld if mailboxes are shared
within domain.  Defaults to @samp{"%Lu"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string log-path
Log file to use for error messages.  @samp{syslog} logs to syslog,
@samp{/dev/stderr} logs to stderr.  Defaults to @samp{"syslog"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string info-log-path
Log file to use for informational messages.  Defaults to @samp{log-path}.
Defaults to @samp{""}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string debug-log-path
Log file to use for debug messages.  Defaults to @samp{info-log-path}.
Defaults to @samp{""}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string syslog-facility
Syslog facility to use if you're logging to syslog.  Usually if you don't
want to use @samp{mail}, you'll use local0..local7.  Also other standard
facilities are supported.  Defaults to @samp{"mail"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} boolean auth-verbose?
Log unsuccessful authentication attempts and the reasons why they failed.
Defaults to @samp{#f}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string auth-verbose-passwords
In case of password mismatches, log the attempted password.  Valid values
are no, plain and sha1.  sha1 can be useful for detecting brute force
password attempts vs.  user simply trying the same password over and over
again.  You can also truncate the value to n chars by appending ":n" (e.g.@:
sha1:6).  Defaults to @samp{"no"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} boolean auth-debug?
Even more verbose logging for debugging purposes.  Shows for example SQL
queries.  Defaults to @samp{#f}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} boolean auth-debug-passwords?
In case of password mismatches, log the passwords and used scheme so the
problem can be debugged.  Enabling this also enables @samp{auth-debug}.
Defaults to @samp{#f}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} boolean mail-debug?
Enable mail process debugging.  This can help you figure out why Dovecot
isn't finding your mails.  Defaults to @samp{#f}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} boolean verbose-ssl?
Show protocol level SSL errors.  Defaults to @samp{#f}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string log-timestamp
Prefix for each line written to log file.  % codes are in strftime(3)
format.  Defaults to @samp{"\"%b %d %H:%M:%S \""}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list login-log-format-elements
List of elements we want to log.  The elements which have a non-empty
variable value are joined together to form a comma-separated string.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string login-log-format
Login log format.  %s contains @samp{login-log-format-elements} string, %$
contains the data we want to log.  Defaults to @samp{"%$: %s"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string mail-log-prefix
Log prefix for mail processes.  See doc/wiki/Variables.txt for list of
possible variables you can use.  Defaults to
@samp{"\"%s(%u)<%@{pid@}><%@{session@}>: \""}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string deliver-log-format
Format to use for logging mail deliveries.  You can use variables:
@table @code
@item %$
Delivery status message (e.g.@: @samp{saved to INBOX})
@item %m
Mensagem-ID
@item %s
Assunto
@item %f
From address
@item %p
Physical size
@item %w
Virtual size.
@end table
Defaults to @samp{"msgid=%m: %$"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string mail-location
Location for users' mailboxes.  The default is empty, which means that
Dovecot tries to find the mailboxes automatically.  This won't work if the
user doesn't yet have any mail, so you should explicitly tell Dovecot the
full location.

If you're using mbox, giving a path to the INBOX file (e.g.@:
@file{/var/mail/%u}) isn't enough.  You'll also need to tell Dovecot where
the other mailboxes are kept.  This is called the @emph{root mail
directory}, and it must be the first path given in the @samp{mail-location}
setting.

There are a few special variables you can use, e.g.:

@table @samp
@item %u
nome de usuário
@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
diretório pessoal
@end table

See doc/wiki/Variables.txt for full list.  Some examples:
@table @samp
@item maildir:~/Maildir
@item mbox:~/mail:INBOX=/var/mail/%u
@item mbox:/var/mail/%d/%1n/%n:INDEX=/var/indexes/%d/%1n/%
@end table
Defaults to @samp{""}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string mail-uid
System user and group used to access mails.  If you use multiple, userdb can
override these by returning uid or gid fields.  You can use either numbers
or names.  <doc/wiki/UserIds.txt>.  Defaults to @samp{""}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string mail-gid

Defaults to @samp{""}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string mail-privileged-group
Group to enable temporarily for privileged operations.  Currently this is
used only with INBOX when either its initial creation or dotlocking fails.
Typically this is set to @samp{"mail"} to give access to @file{/var/mail}.
Defaults to @samp{""}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string mail-access-groups
Grant access to these supplementary groups for mail processes.  Typically
these are used to set up access to shared mailboxes.  Note that it may be
dangerous to set these if users can create symlinks (e.g.@: if @samp{mail}
group is set here, @code{ln -s /var/mail ~/mail/var} could allow a user to
delete others' mailboxes, or @code{ln -s /secret/shared/box ~/mail/mybox}
would allow reading it).  Defaults to @samp{""}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string mail-attribute-dict
The location of a dictionary used to store @code{IMAP METADATA} as defined
by @uref{https://tools.ietf.org/html/rfc5464, RFC@tie{}5464}.

The IMAP METADATA commands are available only if the ``imap'' protocol
configuration's @code{imap-metadata?} field is @samp{#t}.

Defaults to @samp{""}.

@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} boolean mail-full-filesystem-access?
Allow full file system access to clients.  There's no access checks other
than what the operating system does for the active UID/GID@.  It works with
both maildir and mboxes, allowing you to prefix mailboxes names with e.g.@:
@file{/path/} or @file{~user/}.  Defaults to @samp{#f}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} boolean mmap-disable?
Don't use @code{mmap()} at all.  This is required if you store indexes to
shared file systems (NFS or clustered file system).  Defaults to @samp{#f}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} boolean dotlock-use-excl?
Rely on @samp{O_EXCL} to work when creating dotlock files.  NFS supports
@samp{O_EXCL} since version 3, so this should be safe to use nowadays by
default.  Defaults to @samp{#t}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string mail-fsync
When to use fsync() or fdatasync() calls:
@table @code
@item optimized
Whenever necessary to avoid losing important data
@item always
Useful with e.g.@: NFS when @code{write()}s are delayed
@item never
Never use it (best performance, but crashes can lose data).
@end table
Defaults to @samp{"optimized"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} boolean mail-nfs-storage?
Mail storage exists in NFS@.  Set this to yes to make Dovecot flush NFS
caches whenever needed.  If you're using only a single mail server this
isn't needed.  Defaults to @samp{#f}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} boolean mail-nfs-index?
Mail index files also exist in NFS@.  Setting this to yes requires
@samp{mmap-disable? #t} and @samp{fsync-disable? #f}.  Defaults to
@samp{#f}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string lock-method
Locking method for index files.  Alternatives are fcntl, flock and dotlock.
Dotlocking uses some tricks which may create more disk I/O than other
locking methods.  NFS users: flock doesn't work, remember to change
@samp{mmap-disable}.  Defaults to @samp{"fcntl"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} file-name mail-temp-dir
Directory in which LDA/LMTP temporarily stores incoming mails >128 kB.
Defaults to @samp{"/tmp"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer first-valid-uid
Valid UID range for users.  This is mostly to make sure that users can't log
in as daemons or other system users.  Note that denying root logins is
hardcoded to dovecot binary and can't be done even if @samp{first-valid-uid}
is set to 0.  Defaults to @samp{500}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer last-valid-uid

Defaults to @samp{0}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer first-valid-gid
Valid GID range for users.  Users having non-valid GID as primary group ID
aren't allowed to log in.  If user belongs to supplementary groups with
non-valid GIDs, those groups are not set.  Defaults to @samp{1}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer last-valid-gid

Defaults to @samp{0}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mail-max-keyword-length
Maximum allowed length for mail keyword name.  It's only forced when trying
to create new keywords.  Defaults to @samp{50}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} colon-separated-file-name-list valid-chroot-dirs
List of directories under which chrooting is allowed for mail processes
(i.e.@: @file{/var/mail} will allow chrooting to @file{/var/mail/foo/bar}
too).  This setting doesn't affect @samp{login-chroot} @samp{mail-chroot} or
auth chroot settings.  If this setting is empty, @samp{/./} in home dirs are
ignored.  WARNING: Never add directories here which local users can modify,
that may lead to root exploit.  Usually this should be done only if you
don't allow shell access for users.  <doc/wiki/Chrooting.txt>.  Defaults to
@samp{'()}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string mail-chroot
Default chroot directory for mail processes.  This can be overridden for
specific users in user database by giving @samp{/./} in user's home
directory (e.g.@: @samp{/home/./user} chroots into @file{/home}).  Note that
usually there is no real need to do chrooting, Dovecot doesn't allow users
to access files outside their mail directory anyway.  If your home
directories are prefixed with the chroot directory, append @samp{/.} to
@samp{mail-chroot}.  <doc/wiki/Chrooting.txt>.  Defaults to @samp{""}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} file-name auth-socket-path
UNIX socket path to master authentication server to find users.  This is
used by imap (for shared users) and lda.  Defaults to
@samp{"/var/run/dovecot/auth-userdb"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} file-name mail-plugin-dir
Directory where to look up mail plugins.  Defaults to
@samp{"/usr/lib/dovecot"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list mail-plugins
List of plugins to load for all services.  Plugins specific to IMAP, LDA,
etc.@: are added to this list in their own .conf files.  Defaults to
@samp{'()}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mail-cache-min-mail-count
The minimum number of mails in a mailbox before updates are done to cache
file.  This allows optimizing Dovecot's behavior to do less disk writes at
the cost of more disk reads.  Defaults to @samp{0}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string mailbox-idle-check-interval
When IDLE command is running, mailbox is checked once in a while to see if
there are any new mails or other changes.  This setting defines the minimum
time to wait between those checks.  Dovecot can also use dnotify, inotify
and kqueue to find out immediately when changes occur.  Defaults to
@samp{"30 secs"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} boolean mail-save-crlf?
Save mails with CR+LF instead of plain LF@.  This makes sending those mails
take less CPU, especially with sendfile() syscall with Linux and FreeBSD@.
But it also creates a bit more disk I/O which may just make it slower.  Also
note that if other software reads the mboxes/maildirs, they may handle the
extra CRs wrong and cause problems.  Defaults to @samp{#f}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} boolean maildir-stat-dirs?
By default LIST command returns all entries in maildir beginning with a
dot.  Enabling this option makes Dovecot return only entries which are
directories.  This is done by stat()ing each entry, so it causes more disk
I/O.  (For systems setting struct @samp{dirent->d_type} this check is free
and it's done always regardless of this setting).  Defaults to @samp{#f}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} boolean maildir-copy-with-hardlinks?
When copying a message, do it with hard links whenever possible.  This makes
the performance much better, and it's unlikely to have any side effects.
Defaults to @samp{#t}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} boolean maildir-very-dirty-syncs?
Assume Dovecot is the only MUA accessing Maildir: Scan cur/ directory only
when its mtime changes unexpectedly or when we can't find the mail
otherwise.  Defaults to @samp{#f}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list mbox-read-locks
Which locking methods to use for locking mbox.  There are four available:

@table @code
@item dotlock
Create <mailbox>.lock file.  This is the oldest and most NFS-safe solution.
If you want to use /var/mail/ like directory, the users will need write
access to that directory.
@item dotlock-try
Same as dotlock, but if it fails because of permissions or because there
isn't enough disk space, just skip it.
@item fcntl
Use this if possible.  Works with NFS too if lockd is used.
@item flock
May not exist in all systems.  Doesn't work with NFS.
@item lockf
May not exist in all systems.  Doesn't work with NFS.
@end table

You can use multiple locking methods; if you do the order they're declared
in is important to avoid deadlocks if other MTAs/MUAs are using multiple
locking methods as well.  Some operating systems don't allow using some of
them simultaneously.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list mbox-write-locks

@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string mbox-lock-timeout
Maximum time to wait for lock (all of them) before aborting.  Defaults to
@samp{"5 mins"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string mbox-dotlock-change-timeout
If dotlock exists but the mailbox isn't modified in any way, override the
lock file after this much time.  Defaults to @samp{"2 mins"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} boolean mbox-dirty-syncs?
When mbox changes unexpectedly we have to fully read it to find out what
changed.  If the mbox is large this can take a long time.  Since the change
is usually just a newly appended mail, it'd be faster to simply read the new
mails.  If this setting is enabled, Dovecot does this but still safely
fallbacks to re-reading the whole mbox file whenever something in mbox isn't
how it's expected to be.  The only real downside to this setting is that if
some other MUA changes message flags, Dovecot doesn't notice it
immediately.  Note that a full sync is done with SELECT, EXAMINE, EXPUNGE
and CHECK commands.  Defaults to @samp{#t}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} boolean mbox-very-dirty-syncs?
Like @samp{mbox-dirty-syncs}, but don't do full syncs even with SELECT,
EXAMINE, EXPUNGE or CHECK commands.  If this is set, @samp{mbox-dirty-syncs}
is ignored.  Defaults to @samp{#f}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} boolean mbox-lazy-writes?
Delay writing mbox headers until doing a full write sync (EXPUNGE and CHECK
commands and when closing the mailbox).  This is especially useful for POP3
where clients often delete all mails.  The downside is that our changes
aren't immediately visible to other MUAs.  Defaults to @samp{#t}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mbox-min-index-size
If mbox size is smaller than this (e.g.@: 100k), don't write index files.
If an index file already exists it's still read, just not updated.  Defaults
to @samp{0}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mdbox-rotate-size
Maximum dbox file size until it's rotated.  Defaults to @samp{10000000}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string mdbox-rotate-interval
Maximum dbox file age until it's rotated.  Typically in days.  Day begins
from midnight, so 1d = today, 2d = yesterday, etc.  0 = check disabled.
Defaults to @samp{"1d"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} boolean mdbox-preallocate-space?
When creating new mdbox files, immediately preallocate their size to
@samp{mdbox-rotate-size}.  This setting currently works only in Linux with
some file systems (ext4, xfs).  Defaults to @samp{#f}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string mail-attachment-dir
sdbox and mdbox support saving mail attachments to external files, which
also allows single instance storage for them.  Other backends don't support
this for now.

WARNING: This feature hasn't been tested much yet.  Use at your own risk.

Directory root where to store mail attachments.  Disabled, if empty.
Defaults to @samp{""}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mail-attachment-min-size
Attachments smaller than this aren't saved externally.  It's also possible
to write a plugin to disable saving specific attachments externally.
Defaults to @samp{128000}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string mail-attachment-fs
File system backend to use for saving attachments:
@table @code
@item posix
No SiS done by Dovecot (but this might help FS's own deduplication)
@item sis posix
SiS with immediate byte-by-byte comparison during saving
@item sis-queue posix
SiS with delayed comparison and deduplication.
@end table
Defaults to @samp{"sis posix"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string mail-attachment-hash
Hash format to use in attachment filenames.  You can add any text and
variables: @code{%@{md4@}}, @code{%@{md5@}}, @code{%@{sha1@}},
@code{%@{sha256@}}, @code{%@{sha512@}}, @code{%@{size@}}.  Variables can be
truncated, e.g.@: @code{%@{sha256:80@}} returns only first 80 bits.
Defaults to @samp{"%@{sha1@}"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer default-process-limit

Defaults to @samp{100}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer default-client-limit

Defaults to @samp{1000}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer default-vsz-limit
Default VSZ (virtual memory size) limit for service processes.  This is
mainly intended to catch and kill processes that leak memory before they eat
up everything.  Defaults to @samp{256000000}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string default-login-user
Login user is internally used by login processes.  This is the most
untrusted user in Dovecot system.  It shouldn't have access to anything at
all.  Defaults to @samp{"dovenull"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string default-internal-user
Internal user is used by unprivileged processes.  It should be separate from
login user, so that login processes can't disturb other processes.  Defaults
to @samp{"dovecot"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string ssl?
SSL/TLS support: yes, no, required.  <doc/wiki/SSL.txt>.  Defaults to
@samp{"required"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string ssl-cert
PEM encoded X.509 SSL/TLS certificate (public key).  Defaults to
@samp{"</etc/dovecot/default.pem"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string ssl-key
PEM encoded SSL/TLS private key.  The key is opened before dropping root
privileges, so keep the key file unreadable by anyone but root.  Defaults to
@samp{"</etc/dovecot/private/default.pem"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string ssl-key-password
If key file is password protected, give the password here.  Alternatively
give it when starting dovecot with -p parameter.  Since this file is often
world-readable, you may want to place this setting instead to a different.
Defaults to @samp{""}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string ssl-ca
PEM encoded trusted certificate authority.  Set this only if you intend to
use @samp{ssl-verify-client-cert? #t}.  The file should contain the CA
certificate(s) followed by the matching CRL(s).  (e.g.@: @samp{ssl-ca
</etc/ssl/certs/ca.pem}).  Defaults to @samp{""}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} boolean ssl-require-crl?
Require that CRL check succeeds for client certificates.  Defaults to
@samp{#t}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} boolean ssl-verify-client-cert?
Request client to send a certificate.  If you also want to require it, set
@samp{auth-ssl-require-client-cert? #t} in auth section.  Defaults to
@samp{#f}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string ssl-cert-username-field
Which field from certificate to use for username.  commonName and
x500UniqueIdentifier are the usual choices.  You'll also need to set
@samp{auth-ssl-username-from-cert? #t}.  Defaults to @samp{"commonName"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string ssl-min-protocol
Minimum SSL protocol version to accept.  Defaults to @samp{"TLSv1"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string ssl-cipher-list
SSL ciphers to use.  Defaults to
@samp{"ALL:!kRSA:!SRP:!kDHd:!DSS:!aNULL:!eNULL:!EXPORT:!DES:!3DES:!MD5:!PSK:!RC4:!ADH:!LOW@@STRENGTH"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string ssl-crypto-device
SSL crypto device to use, for valid values run "openssl engine".  Defaults
to @samp{""}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string postmaster-address
Address to use when sending rejection mails.  %d expands to recipient
domain.  Defaults to @samp{"postmaster@@%d"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string hostname
Hostname to use in various parts of sent mails (e.g.@: in Message-Id)  and
in LMTP replies.  Default is the system's real hostname@@domain.  Defaults
to @samp{""}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} boolean quota-full-tempfail?
If user is over quota, return with temporary failure instead of bouncing the
mail.  Defaults to @samp{#f}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} file-name sendmail-path
Binary to use for sending mails.  Defaults to @samp{"/usr/sbin/sendmail"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string submission-host
If non-empty, send mails via this SMTP host[:port] instead of sendmail.
Defaults to @samp{""}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string rejection-subject
Subject: header to use for rejection mails.  You can use the same variables
as for @samp{rejection-reason} below.  Defaults to @samp{"Rejected: %s"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string rejection-reason
Human readable error message for rejection mails.  You can use variables:

@table @code
@item %n
CRLF
@item %r
reason
@item %s
original subject
@item %t
destinatário
@end table
Defaults to @samp{"Your message to <%t> was automatically rejected:%n%r"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string recipient-delimiter
Delimiter character between local-part and detail in email address.
Defaults to @samp{"+"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string lda-original-recipient-header
Header where the original recipient address (SMTP's RCPT TO: address) is
taken from if not available elsewhere.  With dovecot-lda -a parameter
overrides this.  A commonly used header for this is X-Original-To.  Defaults
to @samp{""}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} boolean lda-mailbox-autocreate?
Should saving a mail to a nonexistent mailbox automatically create it?.
Defaults to @samp{#f}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} boolean lda-mailbox-autosubscribe?
Should automatically created mailboxes be also automatically subscribed?.
Defaults to @samp{#f}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer imap-max-line-length
Maximum IMAP command line length.  Some clients generate very long command
lines with huge mailboxes, so you may need to raise this if you get "Too
long argument" or "IMAP command line too large" errors often.  Defaults to
@samp{64000}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string imap-logout-format
IMAP logout format string:
@table @code
@item %i
total number of bytes read from client
@item %o
total number of bytes sent to client.
@end table
See @file{doc/wiki/Variables.txt} for a list of all the variables you can
use.  Defaults to @samp{"in=%i out=%o deleted=%@{deleted@}
expunged=%@{expunged@} trashed=%@{trashed@} hdr_count=%@{fetch_hdr_count@}
hdr_bytes=%@{fetch_hdr_bytes@} body_count=%@{fetch_body_count@}
body_bytes=%@{fetch_body_bytes@}"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string imap-capability
Override the IMAP CAPABILITY response.  If the value begins with '+', add
the given capabilities on top of the defaults (e.g.@: +XFOO XBAR).  Defaults
to @samp{""}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string imap-idle-notify-interval
How long to wait between "OK Still here" notifications when client is
IDLEing.  Defaults to @samp{"2 mins"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string imap-id-send
ID field names and values to send to clients.  Using * as the value makes
Dovecot use the default value.  The following fields have default values
currently: name, version, os, os-version, support-url, support-email.
Defaults to @samp{""}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string imap-id-log
ID fields sent by client to log.  * means everything.  Defaults to
@samp{""}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list imap-client-workarounds
Workarounds for various client bugs:

@table @code
@item delay-newmail
Send EXISTS/RECENT new mail notifications only when replying to NOOP and
CHECK commands.  Some clients ignore them otherwise, for example OSX Mail
(<v2.1).  Outlook Express breaks more badly though, without this it may show
user "Message no longer in server" errors.  Note that OE6 still breaks even
with this workaround if synchronization is set to "Headers Only".

@item tb-extra-mailbox-sep
Thunderbird gets somehow confused with LAYOUT=fs (mbox and dbox) and adds
extra @samp{/} suffixes to mailbox names.  This option causes Dovecot to
ignore the extra @samp{/} instead of treating it as invalid mailbox name.

@item tb-lsub-flags
Show \Noselect flags for LSUB replies with LAYOUT=fs (e.g.@: mbox).  This
makes Thunderbird realize they aren't selectable and show them greyed out,
instead of only later giving "not selectable" popup error.
@end table
Defaults to @samp{'()}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string imap-urlauth-host
Host allowed in URLAUTH URLs sent by client.  "*" allows all.  Defaults to
@samp{""}.
@end deftypevr


Whew! Lots of configuration options.  The nice thing about it though is that
Guix has a complete interface to Dovecot's configuration language.  This
allows not only a nice way to declare configurations, but also offers
reflective capabilities as well: users can write code to inspect and
transform configurations from within Scheme.

However, it could be that you just want to get a @code{dovecot.conf} up and
running.  In that case, you can pass an @code{opaque-dovecot-configuration}
as the @code{#:config} parameter to @code{dovecot-service}.  As its name
indicates, an opaque configuration does not have easy reflective
capabilities.

Available @code{opaque-dovecot-configuration} fields are:

@deftypevr {@code{opaque-dovecot-configuration} parameter} package dovecot
The dovecot package.
@end deftypevr

@deftypevr {@code{opaque-dovecot-configuration} parameter} string string
The contents of the @code{dovecot.conf}, as a string.
@end deftypevr

For example, if your @code{dovecot.conf} is just the empty string, you could
instantiate a dovecot service like this:

@lisp
(dovecot-service #:config
                 (opaque-dovecot-configuration
                  (string "")))
@end lisp

@subsubheading OpenSMTPD Service

@defvar opensmtpd-service-type
This is the type of the @uref{https://www.opensmtpd.org, OpenSMTPD} service,
whose value should be an @code{opensmtpd-configuration} object as in this
example:

@lisp
(service opensmtpd-service-type
         (opensmtpd-configuration
           (config-file (local-file "./my-smtpd.conf"))))
@end lisp
@end defvar

@deftp {Tipo de dados} opensmtpd-configuration
Data type representing the configuration of opensmtpd.

@table @asis
@item @code{package} (default: @var{opensmtpd})
Package object of the OpenSMTPD SMTP server.

@item @code{shepherd-requirement} (default: @code{'()})
This option can be used to provide a list of symbols naming Shepherd
services that this service will depend on, such as @code{'networking} if you
want to configure OpenSMTPD to listen on non-loopback interfaces.

@item @code{config-file} (default: @code{%default-opensmtpd-config-file})
File-like object of the OpenSMTPD configuration file to use.  By default it
listens on the loopback network interface, and allows for mail from users
and daemons on the local machine, as well as permitting email to remote
servers.  Run @command{man smtpd.conf} for more information.

@item @code{log-file} (default: @code{"/var/log/mail.log"})
The file location for the OpenSMTPD log file.  Logging occurs in the
foreground via the Shepherd, i.e. OpenSMTPD does not detach.  When set to
@code{#f} OpenSMTPD will instead detach and log to the syslog.

@item @code{setgid-commands?} (default: @code{#t})
Make the following commands setgid to @code{smtpq} so they can be executed:
@command{smtpctl}, @command{sendmail}, @command{send-mail},
@command{makemap}, @command{mailq}, and @command{newaliases}.
@xref{Privileged Programs}, for more information on setgid programs.
@end table
@end deftp

@subsubheading Exim Service

@cindex mail transfer agent (MTA)
@cindex MTA (mail transfer agent)
@cindex SMTP

@defvar exim-service-type
This is the type of the @uref{https://exim.org, Exim} mail transfer agent
(MTA), whose value should be an @code{exim-configuration} object as in this
example:

@lisp
(service exim-service-type
         (exim-configuration
           (config-file (local-file "./my-exim.conf"))))
@end lisp
@end defvar

In order to use an @code{exim-service-type} service you must also have a
@code{mail-aliases-service-type} service present in your
@code{operating-system} (even if it has no aliases).

@deftp {Tipo de dados} exim-configuration
Data type representing the configuration of exim.

@table @asis
@item @code{package} (default: @var{exim})
Package object of the Exim server.

@item @code{config-file} (default: @code{#f})
File-like object of the Exim configuration file to use.  If its value is
@code{#f} then use the default configuration file from the package provided
in @code{package}.  The resulting configuration file is loaded after setting
the @code{exim_user} and @code{exim_group} configuration variables.

@end table
@end deftp

@subsubheading Getmail service

@cindex IMAP
@cindex POP

@defvar getmail-service-type
This is the type of the @uref{http://pyropus.ca/software/getmail/, Getmail}
mail retriever, whose value should be a @code{getmail-configuration}.
@end defvar

Available @code{getmail-configuration} fields are:

@deftypevr {@code{getmail-configuration} parameter} symbol name
A symbol to identify the getmail service.

Defaults to @samp{"unset"}.

@end deftypevr

@deftypevr {@code{getmail-configuration} parameter} package package
The getmail package to use.

@end deftypevr

@deftypevr {@code{getmail-configuration} parameter} string user
The user to run getmail as.

Defaults to @samp{"getmail"}.

@end deftypevr

@deftypevr {@code{getmail-configuration} parameter} string group
The group to run getmail as.

Defaults to @samp{"getmail"}.

@end deftypevr

@deftypevr {@code{getmail-configuration} parameter} string directory
The getmail directory to use.

Defaults to @samp{"/var/lib/getmail/default"}.

@end deftypevr

@deftypevr {@code{getmail-configuration} parameter} getmail-configuration-file rcfile
The getmail configuration file to use.

Available @code{getmail-configuration-file} fields are:

@deftypevr {@code{getmail-configuration-file} parameter} getmail-retriever-configuration retriever
What mail account to retrieve mail from, and how to access that account.

Available @code{getmail-retriever-configuration} fields are:

@deftypevr {@code{getmail-retriever-configuration} parameter} string type
The type of mail retriever to use.  Valid values include @samp{passwd} and
@samp{static}.

Defaults to @samp{"SimpleIMAPSSLRetriever"}.

@end deftypevr

@deftypevr {@code{getmail-retriever-configuration} parameter} string server
Username to login to the mail server with.

Defaults to @samp{unset}.

@end deftypevr

@deftypevr {@code{getmail-retriever-configuration} parameter} string username
Username to login to the mail server with.

Defaults to @samp{unset}.

@end deftypevr

@deftypevr {@code{getmail-retriever-configuration} parameter} non-negative-integer port
Port number to connect to.

Defaults to @samp{#f}.

@end deftypevr

@deftypevr {@code{getmail-retriever-configuration} parameter} string password
Override fields from passwd.

Defaults to @samp{""}.

@end deftypevr

@deftypevr {@code{getmail-retriever-configuration} parameter} list password-command
Override fields from passwd.

Defaults to @samp{'()}.

@end deftypevr

@deftypevr {@code{getmail-retriever-configuration} parameter} string keyfile
PEM-formatted key file to use for the TLS negotiation.

Defaults to @samp{""}.

@end deftypevr

@deftypevr {@code{getmail-retriever-configuration} parameter} string certfile
PEM-formatted certificate file to use for the TLS negotiation.

Defaults to @samp{""}.

@end deftypevr

@deftypevr {@code{getmail-retriever-configuration} parameter} string ca-certs
CA certificates to use.

Defaults to @samp{""}.

@end deftypevr

@deftypevr {@code{getmail-retriever-configuration} parameter} parameter-alist extra-parameters
Extra retriever parameters.

Defaults to @samp{'()}.

@end deftypevr

@end deftypevr

@deftypevr {@code{getmail-configuration-file} parameter} getmail-destination-configuration destination
What to do with retrieved messages.

Available @code{getmail-destination-configuration} fields are:

@deftypevr {@code{getmail-destination-configuration} parameter} string type
The type of mail destination.  Valid values include @samp{Maildir},
@samp{Mboxrd} and @samp{MDA_external}.

Defaults to @samp{unset}.

@end deftypevr

@deftypevr {@code{getmail-destination-configuration} parameter} string-or-filelike path
The path option for the mail destination.  The behaviour depends on the
chosen type.

Defaults to @samp{""}.

@end deftypevr

@deftypevr {@code{getmail-destination-configuration} parameter} parameter-alist extra-parameters
Extra destination parameters

Defaults to @samp{'()}.

@end deftypevr

@end deftypevr

@deftypevr {@code{getmail-configuration-file} parameter} getmail-options-configuration options
Configure getmail.

Available @code{getmail-options-configuration} fields are:

@deftypevr {@code{getmail-options-configuration} parameter} non-negative-integer verbose
If set to @samp{0}, getmail will only print warnings and errors.  A value of
@samp{1} means that messages will be printed about retrieving and deleting
messages.  If set to @samp{2}, getmail will print messages about each of its
actions.

Defaults to @samp{1}.

@end deftypevr

@deftypevr {@code{getmail-options-configuration} parameter} boolean read-all
If true, getmail will retrieve all available messages.  Otherwise it will
only retrieve messages it hasn't seen previously.

Defaults to @samp{#t}.

@end deftypevr

@deftypevr {@code{getmail-options-configuration} parameter} boolean delete
If set to true, messages will be deleted from the server after retrieving
and successfully delivering them.  Otherwise, messages will be left on the
server.

Defaults to @samp{#f}.

@end deftypevr

@deftypevr {@code{getmail-options-configuration} parameter} non-negative-integer delete-after
Getmail will delete messages this number of days after seeing them, if they
have been delivered.  This means messages will be left on the server this
number of days after delivering them.  A value of @samp{0} disabled this
feature.

Defaults to @samp{0}.

@end deftypevr

@deftypevr {@code{getmail-options-configuration} parameter} non-negative-integer delete-bigger-than
Delete messages larger than this of bytes after retrieving them, even if the
delete and delete-after options are disabled.  A value of @samp{0} disables
this feature.

Defaults to @samp{0}.

@end deftypevr

@deftypevr {@code{getmail-options-configuration} parameter} non-negative-integer max-bytes-per-session
Retrieve messages totalling up to this number of bytes before closing the
session with the server.  A value of @samp{0} disables this feature.

Defaults to @samp{0}.

@end deftypevr

@deftypevr {@code{getmail-options-configuration} parameter} non-negative-integer max-message-size
Don't retrieve messages larger than this number of bytes.  A value of
@samp{0} disables this feature.

Defaults to @samp{0}.

@end deftypevr

@deftypevr {@code{getmail-options-configuration} parameter} boolean delivered-to
If true, getmail will add a Delivered-To header to messages.

Defaults to @samp{#t}.

@end deftypevr

@deftypevr {@code{getmail-options-configuration} parameter} boolean received
If set, getmail adds a Received header to the messages.

Defaults to @samp{#t}.

@end deftypevr

@deftypevr {@code{getmail-options-configuration} parameter} string message-log
Getmail will record a log of its actions to the named file.  A value of
@samp{""} disables this feature.

Defaults to @samp{""}.

@end deftypevr

@deftypevr {@code{getmail-options-configuration} parameter} boolean message-log-syslog
If true, getmail will record a log of its actions using the system logger.

Defaults to @samp{#f}.

@end deftypevr

@deftypevr {@code{getmail-options-configuration} parameter} boolean message-log-verbose
If true, getmail will log information about messages not retrieved and the
reason for not retrieving them, as well as starting and ending information
lines.

Defaults to @samp{#f}.

@end deftypevr

@deftypevr {@code{getmail-options-configuration} parameter} parameter-alist extra-parameters
Extra options to include.

Defaults to @samp{'()}.

@end deftypevr

@end deftypevr

@end deftypevr

@deftypevr {@code{getmail-configuration} parameter} list idle
A list of mailboxes that getmail should wait on the server for new mail
notifications.  This depends on the server supporting the IDLE extension.

Defaults to @samp{'()}.

@end deftypevr

@deftypevr {@code{getmail-configuration} parameter} list environment-variables
Environment variables to set for getmail.

Defaults to @samp{'()}.

@end deftypevr

@subsubheading Mail Aliases Service

@cindex email aliases
@cindex aliases, for email addresses

@defvar mail-aliases-service-type
This is the type of the service which provides @code{/etc/aliases},
specifying how to deliver mail to users on this system.

@lisp
(service mail-aliases-service-type
         '(("postmaster" "bob")
           ("bob" "bob@@example.com" "bob@@example2.com")))
@end lisp
@end defvar

The configuration for a @code{mail-aliases-service-type} service is an
association list denoting how to deliver mail that comes to this system.
Each entry is of the form @code{(alias addresses ...)}, with @code{alias}
specifying the local alias and @code{addresses} specifying where to deliver
this user's mail.

The aliases aren't required to exist as users on the local system.  In the
above example, there doesn't need to be a @code{postmaster} entry in the
@code{operating-system}'s @code{user-accounts} in order to deliver the
@code{postmaster} mail to @code{bob} (which subsequently would deliver mail
to @code{bob@@example.com} and @code{bob@@example2.com}).

@subsubheading GNU Mailutils IMAP4 Daemon
@cindex GNU Mailutils IMAP4 Daemon

@defvar imap4d-service-type
This is the type of the GNU Mailutils IMAP4 Daemon (@pxref{imap4d,,,
mailutils, GNU Mailutils Manual}), whose value should be an
@code{imap4d-configuration} object as in this example:

@lisp
(service imap4d-service-type
         (imap4d-configuration
           (config-file (local-file "imap4d.conf"))))
@end lisp
@end defvar

@deftp {Tipo de dados} imap4d-configuration
Data type representing the configuration of @command{imap4d}.

@table @asis
@item @code{package} (default: @code{mailutils})
The package that provides @command{imap4d}.

@item @code{config-file} (default: @code{%default-imap4d-config-file})
File-like object of the configuration file to use, by default it will listen
on TCP port 143 of @code{localhost}.  @xref{Conf-imap4d,,, mailutils, GNU
Mailutils Manual}, for details.

@end table
@end deftp

@subsubheading Radicale Service
@cindex CalDAV
@cindex CardDAV

@defvar radicale-service-type
This is the type of the @uref{https://radicale.org, Radicale} CalDAV/CardDAV
server whose value should be a @code{radicale-configuration}.  The default
configuration matches the @uref{https://radicale.org/v3.html#configuration,
upstream documentation}.
@end defvar

@deftp {Tipo de dados} radicale-configuration
Data type representing the configuration of @command{radicale}.  Available
@code{radicale-configuration} fields are:

@table @asis
@item @code{package} (default: @code{radicale}) (type: package)
Package that provides @command{radicale}.

@item @code{auth} (default: @code{'()}) (type: radicale-auth-configuration)
Configuration for auth-related variables.

@deftp {Tipo de dados} radicale-auth-configuration
Data type representing the @code{auth} section of a @command{radicale}
configuration file.  Available @code{radicale-auth-configuration} fields
are:

@table @asis
@item @code{type} (default: @code{'none}) (type: symbol)
The method to verify usernames and passwords.  Options are @code{none},
@code{htpasswd}, @code{remote-user}, and @code{http-x-remote-user}.  This
value is tied to @code{htpasswd-filename} and @code{htpasswd-encryption}.

@item @code{htpasswd-filename} (default: @code{"/etc/radicale/users"}) (type: file-name)
Path to the htpasswd file.  Use htpasswd or similar to generate this file.

@item @code{htpasswd-encryption} (default: @code{'md5}) (type: symbol)
Encryption method used in the htpasswd file.  Options are @code{plain},
@code{bcrypt}, and @code{md5}.

@item @code{delay} (default: @code{1}) (type: non-negative-integer)
Average delay after failed login attempts in seconds.

@item @code{realm} (default: @code{"Radicale - Password Required"}) (type: string)
Message displayed in the client when a password is needed.

@end table

@end deftp

@item @code{encoding} (default: @code{'()}) (type: radicale-encoding-configuration)
Configuration for encoding-related variables.

@deftp {Tipo de dados} radicale-encoding-configuration
Data type representing the @code{encoding} section of a @command{radicale}
configuration file.  Available @code{radicale-encoding-configuration} fields
are:

@table @asis
@item @code{request} (default: @code{'utf-8}) (type: symbol)
Encoding for responding requests.

@item @code{stock} (default: @code{'utf-8}) (type: symbol)
Encoding for storing local collections.

@end table

@end deftp

@item @code{headers-file} (default: none) (type: file-like)
Custom HTTP headers.

@item @code{logging} (default: @code{'()}) (type: radicale-logging-configuration)
Configuration for logging-related variables.

@deftp {Tipo de dados} radicale-logging-configuration
Data type representing the @code{logging} section of a @command{radicale}
configuration file.  Available @code{radicale-logging-configuration} fields
are:

@table @asis
@item @code{level} (default: @code{'warning}) (type: symbol)
Set the logging level.  One of @code{debug}, @code{info}, @code{warning},
@code{error}, or @code{critical}.

@item @code{mask-passwords?} (default: @code{#t}) (type: boolean)
Whether to include passwords in logs.

@end table

@end deftp

@item @code{rights} (default: @code{'()}) (type: radicale-rights-configuration)
Configuration for rights-related variables.  This should be a
@code{radicale-rights-configuration}.

@deftp {Tipo de dados} radicale-rights-configuration
Data type representing the @code{rights} section of a @command{radicale}
configuration file.  Available @code{radicale-rights-configuration} fields
are:

@table @asis
@item @code{type} (default: @code{'owner-only}) (type: symbol)
Backend used to check collection access rights.  The recommended backend is
@code{owner-only}.  If access to calendars and address books outside the
home directory of users is granted, clients won't detect these collections
and will not show them to the user.  Choosing any other method is only
useful if you access calendars and address books directly via URL.  Options
are @code{authenticate}, @code{owner-only}, @code{owner-write}, and
@code{from-file}.

@item @code{file} (default: @code{""}) (type: file-name)
File for the rights backend @code{from-file}.

@end table

@end deftp

@item @code{server} (default: @code{'()}) (type: radicale-server-configuration)
Configuration for server-related variables.  Ignored if WSGI is used.

@deftp {Tipo de dados} radicale-server-configuration
Data type representing the @code{server} section of a @command{radicale}
configuration file.  Available @code{radicale-server-configuration} fields
are:

@table @asis
@item @code{hosts} (default: @code{(list "localhost:5232")}) (type: list-of-ip-addresses)
List of IP addresses that the server will bind to.

@item @code{max-connections} (default: @code{8}) (type: non-negative-integer)
Maximum number of parallel connections.  Set to 0 to disable the limit.

@item @code{max-content-length} (default: @code{100000000}) (type: non-negative-integer)
Maximum size of the request body in bytes.

@item @code{timeout} (default: @code{30}) (type: non-negative-integer)
Socket timeout in seconds.

@item @code{ssl?} (default: @code{#f}) (type: boolean)
Whether to enable transport layer encryption.

@item @code{certificate} (default: @code{"/etc/ssl/radicale.cert.pem"}) (type: file-name)
Path of the SSL certificate.

@item @code{key} (default: @code{"/etc/ssl/radicale.key.pem"}) (type: file-name)
Path to the private key for SSL.  Only effective if @code{ssl?} is
@code{#t}.

@item @code{certificate-authority} (default: @code{""}) (type: file-name)
Path to CA certificate for validating client certificates.  This can be used
to secure TCP traffic between Radicale and a reverse proxy.  If you want to
authenticate users with client-side certificates, you also have to write an
authentication plugin that extracts the username from the certificate.

@end table

@end deftp

@item @code{storage} (default: @code{'()}) (type: radicale-storage-configuration)
Configuration for storage-related variables.

@deftp {Tipo de dados} radicale-storage-configuration
Data type representing the @code{storage} section of a @command{radicale}
configuration file.  Available @code{radicale-storage-configuration} fields
are:

@table @asis
@item @code{type} (default: @code{'multifilesystem}) (type: symbol)
Backend used to store data.  Options are @code{multifilesystem} and
@code{multifilesystem-nolock}.

@item @code{filesystem-folder} (default: @code{"/var/lib/radicale/collections"}) (type: file-name)
Folder for storing local collections.  Created if not present.

@item @code{max-sync-token-age} (default: @code{2592000}) (type: non-negative-integer)
Delete sync-tokens that are older than the specified time in seconds.

@item @code{hook} (default: @code{""}) (type: string)
Command run after changes to storage.

@end table

@end deftp

@item @code{web-interface?} (default: @code{#t}) (type: boolean)
Whether to use Radicale's built-in web interface.

@end table

@end deftp

@subsubheading Rspamd Service
@cindex e-mail
@cindex spam

@defvar rspamd-service-type
This is the type of the @uref{https://rspamd.com/, Rspamd} filtering system
whose value should be a @code{rspamd-configuration}.
@end defvar

@c %start of fragment

@deftp {Tipo de dados} rspamd-configuration
Available @code{rspamd-configuration} fields are:

@table @asis
@item @code{package} (default: @code{rspamd}) (type: file-like)
The package that provides rspamd.

@item @code{config-file} (default: @code{%default-rspamd-config-file}) (type: file-like)
File-like object of the configuration file to use.  By default all workers
are enabled except fuzzy and they are bound to their usual ports, e.g
localhost:11334, localhost:11333 and so on

@item @code{local.d-files} (default: @code{()}) (type: directory-tree)
Configuration files in local.d, provided as a list of two element lists
where the first element is the filename and the second one is a file-like
object.  Settings in these files will be merged with the defaults.

@item @code{override.d-files} (default: @code{()}) (type: directory-tree)
Configuration files in override.d, provided as a list of two element lists
where the first element is the filename and the second one is a file-like
object.  Settings in these files will override the defaults.

@item @code{user} (default: @code{%default-rspamd-account}) (type: user-account)
The user to run rspamd as.

@item @code{group} (default: @code{%default-rspamd-group}) (type: user-group)
The group to run rspamd as.

@item @code{debug?} (default: @code{#f}) (type: boolean)
Force debug output.

@item @code{insecure?} (default: @code{#f}) (type: boolean)
Ignore running workers as privileged users.

@item @code{skip-template?} (default: @code{#f}) (type: boolean)
Do not apply Jinja templates.

@item @code{shepherd-requirements} (default: @code{(user-processes loopback)}) (type: list-of-symbols)
This is a list of symbols naming Shepherd services that this service will
depend on.

@end table

@end deftp


@c %end of fragment

@node Serviços de mensageria
@subsection Serviços de mensageria

@cindex messaging
@cindex jabber
@cindex XMPP
The @code{(gnu services messaging)} module provides Guix service definitions
for messaging services.  Currently it provides the following services:

@subsubheading Prosody Service

@defvar prosody-service-type
This is the type for the @uref{https://prosody.im, Prosody XMPP
communication server}.  Its value must be a @code{prosody-configuration}
record as in this example:

@lisp
(service prosody-service-type
         (prosody-configuration
          (modules-enabled (cons* "groups" "mam" %default-modules-enabled))
          (int-components
           (list
            (int-component-configuration
             (hostname "conference.example.net")
             (plugin "muc")
             (mod-muc (mod-muc-configuration)))))
          (virtualhosts
           (list
            (virtualhost-configuration
             (domain "example.net"))))))
@end lisp

See below for details about @code{prosody-configuration}.

@end defvar

By default, Prosody does not need much configuration.  Only one
@code{virtualhosts} field is needed: it specifies the domain you wish
Prosody to serve.

You can perform various sanity checks on the generated configuration with
the @code{prosodyctl check} command.

Prosodyctl will also help you to import certificates from the
@code{letsencrypt} directory so that the @code{prosody} user can access
them.  See @url{https://prosody.im/doc/letsencrypt}.

@example
prosodyctl --root cert import /etc/certs
@end example

The available configuration parameters follow.  Each parameter definition is
preceded by its type; for example, @samp{string-list foo} indicates that the
@code{foo} parameter should be specified as a list of strings.  Types
starting with @code{maybe-} denote parameters that won't show up in
@code{prosody.cfg.lua} when their value is left unspecified.

There is also a way to specify the configuration as a string, if you have an
old @code{prosody.cfg.lua} file that you want to port over from some other
system; see the end for more details.

The @code{file-object} type designates either a file-like object
(@pxref{Expressões-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
The Prosody package.
@end deftypevr

@deftypevr {@code{prosody-configuration} parameter} file-name data-path
Location of the Prosody data storage directory.  See
@url{https://prosody.im/doc/configure}.  Defaults to
@samp{"/var/lib/prosody"}.
@end deftypevr

@deftypevr {@code{prosody-configuration} parameter} file-object-list plugin-paths
Additional plugin directories.  They are searched in all the specified paths
in order.  See @url{https://prosody.im/doc/plugins_directory}.  Defaults to
@samp{'()}.
@end deftypevr

@deftypevr {@code{prosody-configuration} parameter} file-name certificates
Every virtual host and component needs a certificate so that clients and
servers can securely verify its identity.  Prosody will automatically load
certificates/keys from the directory specified here.  Defaults to
@samp{"/etc/prosody/certs"}.
@end deftypevr

@deftypevr {@code{prosody-configuration} parameter} string-list admins
This is a list of accounts that are admins for the server.  Note that you
must create the accounts separately.  See
@url{https://prosody.im/doc/admins} and
@url{https://prosody.im/doc/creating_accounts}.  Example: @code{(admins
'("user1@@example.com" "user2@@example.net"))} Defaults to @samp{'()}.
@end deftypevr

@deftypevr {@code{prosody-configuration} parameter} boolean use-libevent?
Enable use of libevent for better performance under high load.  See
@url{https://prosody.im/doc/libevent}.  Defaults to @samp{#f}.
@end deftypevr

@deftypevr {@code{prosody-configuration} parameter} module-list modules-enabled
This is the list of modules Prosody will load on startup.  It looks for
@code{mod_modulename.lua} in the plugins folder, so make sure that exists
too.  Documentation on modules can be found at:
@url{https://prosody.im/doc/modules}.  Defaults to @samp{'("roster"
"saslauth" "tls" "dialback" "disco" "carbons" "private" "blocklist" "vcard"
"version" "uptime" "time" "ping" "pep" "register" "admin_adhoc")}.
@end deftypevr

@deftypevr {@code{prosody-configuration} parameter} string-list modules-disabled
@samp{"offline"}, @samp{"c2s"} and @samp{"s2s"} are auto-loaded, but should
you want to disable them then add them to this list.  Defaults to
@samp{'()}.
@end deftypevr

@deftypevr {@code{prosody-configuration} parameter} file-object groups-file
Path to a text file where the shared groups are defined.  If this path is
empty then @samp{mod_groups} does nothing.  See
@url{https://prosody.im/doc/modules/mod_groups}.  Defaults to
@samp{"/var/lib/prosody/sharedgroups.txt"}.
@end deftypevr

@deftypevr {@code{prosody-configuration} parameter} boolean allow-registration?
Disable account creation by default, for security.  See
@url{https://prosody.im/doc/creating_accounts}.  Defaults to @samp{#f}.
@end deftypevr

@deftypevr {@code{prosody-configuration} parameter} maybe-ssl-configuration ssl
These are the SSL/TLS-related settings.  Most of them are disabled so to use
Prosody's defaults.  If you do not completely understand these options, do
not add them to your config, it is easy to lower the security of your server
using them.  See @url{https://prosody.im/doc/advanced_ssl_config}.

Available @code{ssl-configuration} fields are:

@deftypevr {@code{ssl-configuration} parameter} maybe-string protocol
This determines what handshake to use.
@end deftypevr

@deftypevr {@code{ssl-configuration} parameter} maybe-file-name key
Path to your private key file.
@end deftypevr

@deftypevr {@code{ssl-configuration} parameter} maybe-file-name certificate
Path to your certificate file.
@end deftypevr

@deftypevr {@code{ssl-configuration} parameter} file-object capath
Path to directory containing root certificates that you wish Prosody to
trust when verifying the certificates of remote servers.  Defaults to
@samp{"/etc/ssl/certs"}.
@end deftypevr

@deftypevr {@code{ssl-configuration} parameter} maybe-file-object cafile
Path to a file containing root certificates that you wish Prosody to trust.
Similar to @code{capath} but with all certificates concatenated together.
@end deftypevr

@deftypevr {@code{ssl-configuration} parameter} maybe-string-list verify
A list of verification options (these mostly map to OpenSSL's
@code{set_verify()} flags).
@end deftypevr

@deftypevr {@code{ssl-configuration} parameter} maybe-string-list options
A list of general options relating to SSL/TLS@.  These map to OpenSSL's
@code{set_options()}.  For a full list of options available in LuaSec, see
the LuaSec source.
@end deftypevr

@deftypevr {@code{ssl-configuration} parameter} maybe-non-negative-integer depth
How long a chain of certificate authorities to check when looking for a
trusted root certificate.
@end deftypevr

@deftypevr {@code{ssl-configuration} parameter} maybe-string ciphers
An OpenSSL cipher string.  This selects what ciphers Prosody will offer to
clients, and in what order.
@end deftypevr

@deftypevr {@code{ssl-configuration} parameter} maybe-file-name dhparam
A path to a file containing parameters for Diffie-Hellman key exchange.  You
can create such a file with: @code{openssl dhparam -out
/etc/prosody/certs/dh-2048.pem 2048}
@end deftypevr

@deftypevr {@code{ssl-configuration} parameter} maybe-string curve
Curve for Elliptic curve Diffie-Hellman.  Prosody's default is
@samp{"secp384r1"}.
@end deftypevr

@deftypevr {@code{ssl-configuration} parameter} maybe-string-list verifyext
A list of ``extra'' verification options.
@end deftypevr

@deftypevr {@code{ssl-configuration} parameter} maybe-string password
Password for encrypted private keys.
@end deftypevr

@end deftypevr

@deftypevr {@code{prosody-configuration} parameter} boolean c2s-require-encryption?
Whether to force all client-to-server connections to be encrypted or not.
See @url{https://prosody.im/doc/modules/mod_tls}.  Defaults to @samp{#f}.
@end deftypevr

@deftypevr {@code{prosody-configuration} parameter} string-list disable-sasl-mechanisms
Set of mechanisms that will never be offered.  See
@url{https://prosody.im/doc/modules/mod_saslauth}.  Defaults to
@samp{'("DIGEST-MD5")}.
@end deftypevr

@deftypevr {@code{prosody-configuration} parameter} string-list insecure-sasl-mechanisms
Set of mechanisms that will not be offered on unencrypted connections.  See
@url{https://prosody.im/doc/modules/mod_saslauth}.  Defaults to
@samp{'("PLAIN" "LOGIN")}.
@end deftypevr

@deftypevr {@code{prosody-configuration} parameter} boolean s2s-require-encryption?
Whether to force all server-to-server connections to be encrypted or not.
See @url{https://prosody.im/doc/modules/mod_tls}.  Defaults to @samp{#f}.
@end deftypevr

@deftypevr {@code{prosody-configuration} parameter} boolean s2s-secure-auth?
Whether to require encryption and certificate authentication.  This provides
ideal security, but requires servers you communicate with to support
encryption AND present valid, trusted certificates.  See
@url{https://prosody.im/doc/s2s#security}.  Defaults to @samp{#f}.
@end deftypevr

@deftypevr {@code{prosody-configuration} parameter} string-list s2s-insecure-domains
Many servers don't support encryption or have invalid or self-signed
certificates.  You can list domains here that will not be required to
authenticate using certificates.  They will be authenticated using DNS@.
See @url{https://prosody.im/doc/s2s#security}.  Defaults to @samp{'()}.
@end deftypevr

@deftypevr {@code{prosody-configuration} parameter} string-list s2s-secure-domains
Even if you leave @code{s2s-secure-auth?} disabled, you can still require
valid certificates for some domains by specifying a list here.  See
@url{https://prosody.im/doc/s2s#security}.  Defaults to @samp{'()}.
@end deftypevr

@deftypevr {@code{prosody-configuration} parameter} string authentication
Select the authentication backend to use.  The default provider stores
passwords in plaintext and uses Prosody's configured data storage to store
the authentication data.  If you do not trust your server please see
@url{https://prosody.im/doc/modules/mod_auth_internal_hashed} for
information about using the hashed backend.  See also
@url{https://prosody.im/doc/authentication} Defaults to
@samp{"internal_plain"}.
@end deftypevr

@deftypevr {@code{prosody-configuration} parameter} maybe-string log
Set logging options.  Advanced logging configuration is not yet supported by
the Prosody service.  See @url{https://prosody.im/doc/logging}.  Defaults to
@samp{"*syslog"}.
@end deftypevr

@deftypevr {@code{prosody-configuration} parameter} file-name pidfile
File to write pid in.  See @url{https://prosody.im/doc/modules/mod_posix}.
Defaults to @samp{"/var/run/prosody/prosody.pid"}.
@end deftypevr

@deftypevr {@code{prosody-configuration} parameter} maybe-non-negative-integer http-max-content-size
Maximum allowed size of the HTTP body (in bytes).
@end deftypevr

@deftypevr {@code{prosody-configuration} parameter} maybe-string http-external-url
Some modules expose their own URL in various ways.  This URL is built from
the protocol, host and port used.  If Prosody sits behind a proxy, the
public URL will be @code{http-external-url} instead.  See
@url{https://prosody.im/doc/http#external_url}.
@end deftypevr

@deftypevr {@code{prosody-configuration} parameter} virtualhost-configuration-list virtualhosts
A host in Prosody is a domain on which user accounts can be created.  For
example if you want your users to have addresses like
@samp{"john.smith@@example.com"} then you need to add a host
@samp{"example.com"}.  All options in this list will apply only to this
host.

@quotation Nota
The name @emph{virtual} host is used in configuration to avoid confusion
with the actual physical host that Prosody is installed on.  A single
Prosody instance can serve many domains, each one defined as a VirtualHost
entry in Prosody's configuration.  Conversely a server that hosts a single
domain would have just one VirtualHost entry.

See @url{https://prosody.im/doc/configure#virtual_host_settings}.
@end quotation

Available @code{virtualhost-configuration} fields are:

all these @code{prosody-configuration} fields: @code{admins},
@code{use-libevent?}, @code{modules-enabled}, @code{modules-disabled},
@code{groups-file}, @code{allow-registration?}, @code{ssl},
@code{c2s-require-encryption?}, @code{disable-sasl-mechanisms},
@code{insecure-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{insecure-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{insecure-sasl-mechanisms}, @code{s2s-require-encryption?},
@code{s2s-secure-auth?}, @code{s2s-insecure-domains},
@code{s2s-secure-domains}, @code{authentication}, @code{log},
@code{http-max-content-size}, @code{http-external-url}, @code{raw-content},
plus:
@deftypevr {@code{ext-component-configuration} parameter} string component-secret
Password which the component will use to log in.
@end deftypevr

@deftypevr {@code{ext-component-configuration} parameter} string hostname
Hostname of the component.
@end deftypevr

@end deftypevr

@deftypevr {@code{prosody-configuration} parameter} non-negative-integer-list component-ports
Port(s) Prosody listens on for component connections.  Defaults to
@samp{'(5347)}.
@end deftypevr

@deftypevr {@code{prosody-configuration} parameter} string component-interface
Interface Prosody listens on for component connections.  Defaults to
@samp{"127.0.0.1"}.
@end deftypevr

@deftypevr {@code{prosody-configuration} parameter} maybe-raw-content raw-content
Raw content that will be added to the configuration file.
@end deftypevr

It could be that you just want to get a @code{prosody.cfg.lua} up and
running.  In that case, you can pass an @code{opaque-prosody-configuration}
record as the value of @code{prosody-service-type}.  As its name indicates,
an opaque configuration does not have easy reflective capabilities.
Available @code{opaque-prosody-configuration} fields are:

@deftypevr {@code{opaque-prosody-configuration} parameter} package prosody
The prosody package.
@end deftypevr

@deftypevr {@code{opaque-prosody-configuration} parameter} string prosody.cfg.lua
The contents of the @code{prosody.cfg.lua} to use.
@end deftypevr

For example, if your @code{prosody.cfg.lua} is just the empty string, you
could instantiate a prosody service like this:

@lisp
(service prosody-service-type
         (opaque-prosody-configuration
          (prosody.cfg.lua "")))
@end lisp

@c end of Prosody auto-generated documentation

@subsubheading BitlBee Service

@cindex IRC (Internet Relay Chat)
@cindex IRC gateway
@url{https://bitlbee.org,BitlBee} is a gateway that provides an IRC
interface to a variety of messaging protocols such as XMPP.

@defvar bitlbee-service-type
This is the service type for the @url{https://bitlbee.org,BitlBee} IRC
gateway daemon.  Its value is a @code{bitlbee-configuration} (see below).

To have BitlBee listen on port 6667 on localhost, add this line to your
services:

@lisp
(service bitlbee-service-type)
@end lisp
@end defvar

@deftp {Tipo de dados} bitlbee-configuration
This is the configuration for BitlBee, with the following fields:

@table @asis
@item @code{interface} (default: @code{"127.0.0.1"})
@itemx @code{port} (padrão: @code{6667})
Listen on the network interface corresponding to the IP address specified in
@var{interface}, on @var{port}.

When @var{interface} is @code{127.0.0.1}, only local clients can connect;
when it is @code{0.0.0.0}, connections can come from any networking
interface.

@item @code{bitlbee} (default: @code{bitlbee})
The BitlBee package to use.

@item @code{plugins} (default: @code{'()})
List of plugin packages to use---e.g., @code{bitlbee-discord}.

@item @code{extra-settings} (default: @code{""})
Configuration snippet added as-is to the BitlBee configuration file.
@end table
@end deftp

@subsubheading ngIRCd service

@cindex IRCd, Internet Relay Chat daemon
@cindex IRC daemon service
@cindex IRC server service
@cindex IRC (Internet Relay Chat)

@url{https://ngircd.barton.de/, ngIRCd}, is a lightweight @acronym{IRCd,
Internet Relay Chat daemon}, which can be used to host your own IRC server.

@defvar ngircd-service-type
The service type for ngIRCd.  Its value is a @code{ngircd-configuration}
object, documented below.

In its most simple form, the service can be used with its default
configuration, like this:

@lisp
(service ngircd-service-type)
@end lisp

A slightly more complex example configuration could look like:

@lisp
(service ngircd-service-type
         (ngircd-configuration
          (channels
           (list (ngircd-channel
                  (name "#fruits")
                  (topic "All things fruits -- veggies are off-topic"))))
          (operators
           (list (ngircd-operator
                  (name "mikan")
                  (password "tomatoes-are-fruits/carrots-are-not"))))))
@end lisp
@end defvar

@c To regenerate the rest of this section documentation, use the
@c `ngircd-generate-documentation' procedure in
@c (gnu services messaging).
@c %start of fragment

@deftp {Data Type} ngircd-configuration
Available @code{ngircd-configuration} fields are:

@table @asis
@item @code{ngircd} (default: @code{ngircd}) (type: file-like)
The @code{ngircd} package to use.

@item @code{debug?} (default: @code{#f}) (type: boolean)
Turn on debugging messages.

@item @code{shepherd-requirement} (default: @code{(user-processes networking)}) (type: list-of-symbols)
Shepherd requirements the service should depend on.

@item @code{global} (type: ngircd-global)
A ngircd-global record object used to specify global options.

@item @code{limits} (type: maybe-ngircd-limits)
The ngircd-limits record object used to specify limits options.

@item @code{options} (type: ngircd-options)
The ngircd-options record object used to specify optional features and
configuration options.

@item @code{ssl} (type: maybe-ngircd-ssl)
The ngircd-ssl record object used to specify the SSL-related options.

@item @code{operators} (type: maybe-list-of-ngircd-operators)
A list of ngircd-operator record objects used to specify the operators.

@item @code{servers} (type: maybe-list-of-ngircd-servers)
A list of ngircd-server record objects used to specify other remote servers
to connect to.

@item @code{channels} (type: maybe-list-of-ngircd-channels)
A list of ngircd-channels record objects specifying pre-defined channels to
be created by the server when starting up.

@end table

@end deftp


@c %end of fragment

@c %start of fragment

@deftp {Data Type} ngircd-global
Available @code{ngircd-global} fields are:

@table @asis
@item @code{name} (type: maybe-string)
Server name in the IRC network.  This is an individual name of the IRC
server, it is not related to the DNS host name.  It must be unique in the
IRC network and must contain at least one dot (@samp{.}) character.  When
not set, ngIRCd tries to deduce a valid IRC server name from the local host
name.

@item @code{admin-info-1} (type: maybe-string)
First administrator information.

@item @code{admin-info-2} (type: maybe-string)
Second administrator information.

@item @code{admin-email} (type: maybe-string)
Email to reach administrators.

@item @code{help-file} (type: maybe-file-like)
File-like containing the ngIRCd help text.

@item @code{info} (type: maybe-string)
Info text of the server.  This will be shown by WHOIS and LINKS requests for
example.

@item @code{listen} (default: @code{("::" "0.0.0.0")}) (type: list-of-strings)
A list of IP address on which the server should listen.  By default it
listens on all configured IP addresses and interfaces.

@item @code{motd-file} (type: file-like)
Text file with the @i{message of the day} (MOTD).  This message will be
shown to all users connecting to the server.

@item @code{motd-phrase} (type: maybe-string)
A simple phrase (<127 chars) to use if you don't want to use a MOTD file.

@item @code{network} (type: maybe-string)
The name of the IRC network to which this server belongs.  This name is
optional, should only contain ASCII characters, and can't contain spaces.
It is only used to inform clients.

@item @code{password} (type: maybe-string)
Global password or all users needed to connect to the server.  By default,
no password is required.  PAM must be disabled for this option to have an
effect.

@item @code{pid-file} (default: @code{"/run/ngircd/ngircd.pid"}) (type: string)
The file name where the PID of ngIRCd should be written after it starts.

@item @code{ports} (default: @code{(6667)}) (type: list-of-ports)
Port number(s) on which the server should listen for @emph{unencrypted}
connections.

@item @code{server-uid} (default: @code{"ngircd"}) (type: string-or-number)
The user that the @command{ngircd} command should run as.

@item @code{server-gid} (default: @code{"ngircd"}) (type: string-or-number)
The group that the @command{ngircd} command should run as.

@end table

@end deftp


@c %end of fragment

@c %start of fragment

@deftp {Data Type} ngircd-limits
Available @code{ngircd-limits} fields are:

@table @asis
@item @code{connect-retry} (default: @code{60}) (type: maybe-number)
The number of seconds the server should wait before re-attempting to
establish a link to not yet (or no longer) connected servers.

@item @code{max-connections} (default: @code{0}) (type: maybe-number)
Maximum number of simultaneous in- and outbound connections the server is
allowed to accept.  There is no limit by default.

@item @code{max-connections-ip} (default: @code{5}) (type: maybe-number)
Maximum number of simultaneous connections from a single IP address that the
server will accept.  This configuration options lowers the risk of denial of
service attacks (DoS).  Set to 0 to remove the limit.

@item @code{max-joins} (default: @code{10}) (type: maybe-number)
Maximum number of channels a user can be member of.  Set to 0 to remove the
limit.

@item @code{max-list-size} (default: @code{100}) (type: maybe-number)
Maximum number of channels returned in response to a LIST command.

@item @code{ping-timeout} (default: @code{120}) (type: maybe-number)
Number of seconds of inactivity after which the server will send a PING to
the peer to test whether it is alive or not.

@item @code{pong-timeout} (default: @code{20}) (type: maybe-number)
If a client fails to answer a PING with a PONG within this amount of
seconds, it will be disconnected by the server.

@end table

@end deftp


@c %end of fragment

@c %start of fragment

@deftp {Data Type} ngircd-options
Available @code{ngircd-options} fields are:

@table @asis
@item @code{allowed-channel-types} (default: @code{"#&+"}) (type: maybe-string)
List of allowed channel types (channel prefixes) for newly created channels
on the local server.  By default, all supported channel types are allowed.

@item @code{allow-remote-oper?} (default: @code{#f}) (type: maybe-boolean)
If this option is active, IRC operators connected to remote servers are
allowed to control this local server using administrative commands, for
example like CONNECT, DIE, SQUIT, etc.

@item @code{connect-ipv4?} (default: @code{#t}) (type: maybe-boolean)
Set to @code{#f} to prevent ngIRCd from connecting to other IRC servers
using the IPv4 protocol, allowed by default.

@item @code{connect-ipv6?} (default: @code{#t}) (type: maybe-boolean)
Set to @code{#f} to prevent ngIRCd from connecting to other IRC servers
using the IPv6 protocol, allowed by default.

@item @code{dns?} (default: @code{#t}) (type: maybe-boolean)
Set to @code{#f} to disable DNS lookups when clients connect.  If you
configure the daemon to connect to other servers, ngIRCd may still perform a
DNS lookup if required.

@item @code{more-privacy?} (default: @code{#f}) (type: maybe-boolean)
Set this to @code{#t} to have ngIRCd censor user idle time, logon time as
well as the PART/QUIT messages (that sometimes used to inform everyone about
which client software is being used).  WHOWAS requests are also silently
ignored, and NAMES output doesn't list any clients for non-members.  This
option is most useful when ngIRCd is being used together with anonymizing
software such as TOR or I2P and one does not wish to make it too easy to
collect statistics on the users.

@item @code{notice-before-registration?} (default: @code{#f}) (type: maybe-boolean)
Normally ngIRCd doesn't send any messages to a client until it is
registered.  Enable this option to let the daemon send @samp{NOTICE *}
messages to clients while connecting.

@item @code{oper-can-use-mode?} (default: @code{#f}) (type: maybe-boolean)
Should IRC Operators be allowed to use the MODE command even if they are
not(!) channel-operators?

@item @code{oper-chan-p-auto-op?} (default: @code{#t}) (type: maybe-boolean)
Should IRC Operators get AutoOp (+o) in persistent (+P) channels?

@item @code{oper-server-mode?} (default: @code{#f}) (type: maybe-boolean)
If @code{open-can-use-mode?} is @code{#t}, this may lead the compatibility
problems with servers that run the ircd-irc2 software.  This option masks
mode requests by non-chanops as if they were coming from the server.  Only
enable this if you have ircd-irc2 servers in your IRC network.

@item @code{pam?} (default: @code{#f}) (type: boolean)
Set to @code{#t} to enable calls to the PAM library at runtime; all users
connecting without password are allowed to connect, all passwords given will
fail.  Users identified without PAM are registered with a tilde (@samp{~})
prepended to their user name.  This defaults to @code{#f} in Guix because
the service runs as an unprivileged user and thus cannot authenticate other
users via the @code{pam_unix} PAM module.

@item @code{pam-is-optional?} (default: @code{#f}) (type: maybe-boolean)
Set to @code{#t} to make PAM authentication optional, causing clients not
sending a password to still be able to connect, but won't become identified
and keep the tilder (@samp{~}) character prepended to their supplied user
name.

@item @code{require-auth-ping?} (default: @code{#f}) (type: maybe-boolean)
Set to @code{#t} to have ngIRCd send an authentication PING when a new
client connects, and register this client only after receiving the
corresponding PONG reply.

@end table

@end deftp


@c %end of fragment

@c %start of fragment

@deftp {Data Type} ngircd-ssl
Available @code{ngircd-ssl} fields are:

@table @asis
@item @code{cert-file} (type: maybe-string)
SSL certificate file of the private server key.

@item @code{key-file} (type: maybe-string)
File name of the SSL Server Key to be used for SSL connections, which is
required for SSL/TLS support.

@item @code{ca-file} (default: @code{"/etc/ssl/certs/ca-certificates.crt"}) (type: maybe-string)
A file listing all the certificates of the trusted Certificate Authorities.

@item @code{ports} (type: maybe-list-of-ports)
Like the global configuration's @code{port} option, except that ngIRCd will
expect incoming connections to be SSL/TLS encrypted.  Common port numbers
for SSL-encrypted IRC are 6669 and 6697.

@item @code{cipher-list} (type: maybe-string)
The GnuTLS cipher suites allowed for SSL/TLS connections, a value such as
@code{"SECURE128:-VERS-SSL3.0"}.  Refer to @samp{man 3 gnutls_priority_init}
for details.

@item @code{dh-file} (type: maybe-file-like)
A file-like containing the Diffie-Hellman parameters, which can be created
with GnuTLS via @samp{certtool --generate-dh-params}.  If this file is not
present, the Diffie-Hellman parameters will be computed on startup, which
may take some time.

@end table

@end deftp


@c %end of fragment

@c %start of fragment

@deftp {Data Type} ngircd-operator
Available @code{ngircd-operator} fields are:

@table @asis
@item @code{name} (type: string)
ID of the operator (may be different of the nickname).

@item @code{password} (type: string)
Password of the IRC operator.

@item @code{mask} (type: maybe-string)
Mask that is to be checked before an /OPER for this account is accepted, for
example: @code{"nick!ident@@*.example.com"}.

@end table

@end deftp


@c %end of fragment

@c %start of fragment

@deftp {Data Type} ngircd-server
Available @code{ngircd-server} fields are:

@table @asis
@item @code{name} (type: string)
IRC name of the remote server.

@item @code{host} (type: string)
Internet host name (or IP address) of the peer.

@item @code{my-password} (type: string)
Own password for this connection.  This password has to be configured as
@code{peer-password} on the other server and must not have @samp{:} as first
character.

@item @code{peer-password} (type: string)
Foreign password for this connection.  This password has to be configured as
@code{my-password} on the other server.

@item @code{bind} (type: maybe-string)
IP address to use as source IP for the outgoing connection.  The default is
to let the operating system decide.

@item @code{port} (type: maybe-port)
Port of the remote server to which ngIRCd should connect (active).  If no
port is assigned to a configured server, the daemon only waits for incoming
connections (passive, which is the default).

@item @code{group} (type: maybe-number)
Group of this server.

@item @code{passive?} (default: @code{#f}) (type: maybe-boolean)
Set to @code{#t} to disable automatic connection even if the port value is
specified.

@item @code{ssl-connect?} (default: @code{#f}) (type: maybe-boolean)
Set to @code{#t} to enforce the use of TLS to connect to the remote server.

@item @code{ssl-verify?} (default: @code{#t}) (type: maybe-boolean)
Set to @code{#f} to disable the verification of the TLS certificate
presented by the remote server.  This can be useful if the remote server
uses a self-signed certificate.  Beware that this degrades security by
enabling man-in-the-middle attacks, as the @emph{remote site is not verified
at all}.

@end table

@end deftp


@c %end of fragment

@c %start of fragment

@deftp {Data Type} ngircd-channel
Available @code{ngircd-channel} fields are:

@table @asis
@item @code{name} (type: string)
Name of the channel, including channel prefix ("#" or "&").

@item @code{topic} (type: maybe-string)
Topic for this channel.

@item @code{modes} (type: maybe-list-of-strings)
Initial channel modes, as used in MODE commands.  Modifying lists (ban list,
invite list, exception list) is supported.  If multiple MODE strings are
specified, they are evaluated in the order listed (left to right).

@item @code{key-file} (type: maybe-file-like)
Path and file name of a ngIRCd key file containing individual channel keys
for different users.  Refer to @samp{man 5 ngircd.conf} for more details.

@end table

@end deftp


@c %end of fragment

@subsubheading Pounce Service

@cindex IRC (Internet Relay Chat)
@cindex bouncer, IRC
@cindex Bounced Network Connection, BNC
@url{https://git.causal.agency/pounce/about/, pounce} is a multi-client,
TLS-only IRC bouncer.  It maintains a persistent connection to an IRC
server, acting as a proxy and buffer for a number of clients.

@defvar pounce-service-type
This is the service type for the pounce IRC bouncer.  Its value is a
@code{pounce-configuration} configuration instance, which is documented
below.

@cindex IRC bouncer configuration for Libera.Chat
@cindex Libera.Chat, IRC bouncer configuration
The following example configures pounce to act as an IRC bouncer for the
@url{https://libera.chat, Libera.Chat} server, using @acronym{CertFP, client
certificate fingerprint} authentication to avoid leaking a sensitive
password to the publicly readable store.  The equally sensitive TLS
certificate file should be created in-place or transferred using a secure
means such as SSH, prior to deploying the service.  The service activation
will ensure the ownership and permissions of the certificate/key files are
set correctly.  In the below example, it is placed at
@file{/etc/pounce/libera.pem} on the target machine.  Pounce itself can be
used to generate a TLS certificate, using the @samp{pounce -g libera.pem}
command, which concatenates both the private key and the public certificate
in the specified file name.  For more information regarding CertFP
authentication, refer to @samp{man pounce} or the Libera.Chat guide at
@url{https://libera.chat/guides/certfp}.

@lisp
(service pounce-service-type
         (pounce-configuration
          (host "irc.libera.chat")
          (client-cert "/etc/pounce/libera.pem")
          (nick "hannah")
          (join (list "#gnu" "#guix" "#guile" "#hurd"))))
@end lisp

Once deployed on the target machine, pounce will act as an IRC server
listening for TLS connections on the 6697 TCP port of the @samp{localhost}
address of that machine.  By default, a self-signed certificate for pounce
is created at @file{/var/lib/pounce/.config/pounce/localhost.cert}.  If you
plan to expose the bouncer to the public Internet, it is advisable to use a
@acronym{CA, Certificate Authority}-signed certificate, as can be obtained
using a certificate service (@pxref{Serviços de certificado}), so that IRC
clients can verify the certificate out of the box.  If you instead plan to
connect to the bouncer strictly via a secure connection, for example using a
@acronym{VPN, Virtual Private Network} or @acronym{SSH, Secure Shell}, then
it is acceptable to simply let your IRC client trust the auto-generated,
self-signed pounce certificate or even disable TLS certificate verification
in your client.

@cindex IRC bouncer configuration for OFTC
@cindex OFTC, IRC bouncer configuration
To connect to a second server, a second pounce instance is needed, taking
care to specify the @code{provision} field of its
@code{pounce-configuration} to avoid a name clash with the previous service,
along with a distinct @code{local-port} and @code{log-file}.  The following
example shows how to configure another bouncer, this time for the
@url{https://www.oftc.net, OFTC} IRC server.  Like in the previous example,
CertFP authentication is used, which can be configured similarly.  For more
details about using CertFP with the OFTC IRC server, refer to
@url{https://www.oftc.net/NickServ/CertFP/}.

@lisp
(service pounce-service-type
         (pounce-configuration
          (shepherd-provision '(pounce-oftc))
          (local-port 6698)
          (log-file "/var/log/pounce-oftc.log")
          (host "irc.oftc.net")
          (client-cert "/etc/pounce/oftc.pem")
          (nick "sena")
          (join (list "#gcc" "#glibc"))))
@end lisp

@end defvar

@c Auto-generated via (configuration->documentation 'pounce-configuration).
@c %start of fragment

@deftp {Data Type} pounce-configuration
Available @code{pounce-configuration} fields are:

@table @asis
@item @code{pounce} (default: @code{pounce}) (type: file-like)
The @code{pounce} package to use.

@item @code{shepherd-provision} (default: @code{(pounce)}) (type: list-of-symbols)
The name(s) of the service.

@item @code{shepherd-requirement} (default: @code{(user-processes networking)}) (type: list-of-symbols)
Shepherd requirements the service should depend on.

@item @code{log-file} (default: @code{"/var/log/pounce.log"}) (type: string)
The log file name to use.

@item @code{verbose?} (type: maybe-boolean)
When true, log IRC messages to standard output.

@item @code{local-host} (default: @code{"localhost"}) (type: maybe-string)
The host to bind to.

@item @code{local-port} (default: @code{6697}) (type: maybe-port)
The port to bind to.

@item @code{local-ca} (type: maybe-string)
Require clients to authenticate using a TLS client certificate either
contained in or signed by a certificate in the file loaded from
@code{local-ca}, a file name.  The file is reloaded when the SIGUSR1 signal
is received.

@item @code{local-cert} (type: maybe-string)
File name of the TLS certificate to load.  The file is reloaded when the
SIGUSR1 signal is received.  Unless specified, a self-signed certificate is
generated at @file{/var/lib/pounce/.config/pounce/@var{host}.pem}, where
@var{host} corresponds to the value of the @code{local-host} field.

@item @code{local-priv} (type: maybe-string)
File name of the private TLS key to load.  Unless specified, a key is
generated at @file{/var/lib/pounce/.config/pounce/@var{host}.key}, where
@var{host} corresponds to the value of the @code{local-host} field.

@item @code{local-pass} (type: maybe-string)
Require the server password pass for clients to connect.  The pass string
must be hashed using @samp{pounce -x}.

@item @code{size} (default: @code{4096}) (type: maybe-power-of-two)
Set the number of messages contained in the buffer to @var{size}.  This sets
the maximum number of recent messages which can be relayed to a reconnecting
client.  The size must be a power of two.

@item @code{bind} (type: maybe-string)
Host to bind the @emph{source} address to when connecting to the server.  To
connect from any address over IPv4 only, use @samp{0.0.0.0}.  To connect
from any address over IPv6 only, use @samp{::}.

@item @code{host} (type: string)
The host name to connect to.

@item @code{port} (type: maybe-port)
The port number to connect to.

@item @code{pass} (type: maybe-string)
Password to use to log in with the server.  The password must have been
hashed via the @samp{pounce -x} command.

@item @code{join} (type: maybe-list-of-strings)
The list of channels to join.

@item @code{mode} (type: maybe-string)
The user mode.

@item @code{user} (type: maybe-string)
To set the username.  The default username is the same as the nickname.

@item @code{nick} (default: @code{"pounce"}) (type: maybe-string)
Set nickname to @var{nick}.

@item @code{real} (type: maybe-string)
Set the real name.  The default is @code{nick}.

@item @code{away} (type: maybe-string)
The away status to use when no clients are connected and no other away
status has been set.

@item @code{quit} (type: maybe-string)
The message to use when quitting.

@item @code{no-names?} (type: maybe-boolean)
Do not request @samp{NAMES} for each channel when a client connects.  This
avoids already connected clients receiving unsolicited responses but
prevents new clients from populating user lists.

@item @code{queue-interval} (default: @code{200}) (type: maybe-number)
Set the server send queue interval in milliseconds.  The queue is used to
send automated messages from pounce to the server.  Messages from clients
are sent to the server directly.

@item @code{trust} (type: maybe-string)
File name of a certificate to trust.  When used, server name verification is
disabled.

@item @code{client-cert} (type: maybe-string)
The file name of the TLS client.  If the private key is in a separate file,
it is loaded with @code{client-priv}.  With @code{sasl-external?},
authenticate using SASL EXTERNAL.  Certificates can be generated with
@samp{pounce -g}.  For more details, refer to ``Generating Client
Certificates'' in @samp{man 1 pounce}.

@item @code{client-priv} (type: maybe-string)
The file name of the TLS client private key.

@item @code{sasl-plain} (type: maybe-pair)
A pair of the username and password in plain text to authenticate using SASL
PLAIN.  Since this method requires the account password in plain text, it is
recommended to use CertFP instead with @code{sasl-external}.

@item @code{sasl-external?} (type: maybe-boolean)
Authenticate using SASL EXTERNAL, also known as CertFP.  The TLS client
certificate is loaded from @code{client-cert}.

@end table

@end deftp


@c %end of fragment

@subsubheading Quassel Service

@cindex IRC (Internet Relay Chat)
@url{https://quassel-irc.org/,Quassel} is a distributed IRC client, meaning
that one or more clients can attach to and detach from the central core.

@defvar quassel-service-type
This is the service type for the @url{https://quassel-irc.org/,Quassel} IRC
backend daemon.  Its value is a @code{quassel-configuration} (see below).
@end defvar

@deftp {Tipo de dados} 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} (padrão: @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

@subsubheading Snuik Service

@cindex irc-bot
@cindex snuik
The @uref{https://gitlab.com/janneke/snuik, Snuik IRC bot} can be run as a
daemon to aid talking to users that are currently offline.  With the
@code{(gnu services messaging)} service, you can configure it by adding a
@code{snuik-service-type} service to the @code{services} field of your
operating system declaration.

@defvar snuik-service-type
This is the type of the Snuik service, whose value is a
@code{snuik-configuration} object.
@end defvar

Here is an example of a service and its configuration:

@lisp
(service snuik-service-type
         (snuik-configuration
          (password-file "/var/run/snuik/.password.snuik")
          (channels '("#bootstrappable"
                      "#dezyne"
                      "#guix-risc-v"
                      "#lilypond"))))
@end lisp

@deftp {Data Type} snuik-configuration
Available @code{snuik-configuration} fields are:

@table @asis
@item @code{snuik} (default: @code{snuik}) (type: package)
The Snuik package to use.

@item @code{server} (default: @code{"irc.libera.chat"})
The IRC server to connect to.

@item @code{port} (default: @code{6665}) (type: integer)
Port number used by the IRC server.

@item @code{nick} (default: @code{"snuik"}) (type: string)
The nickname for snuik to use.

@item @code{password} (default: @code{#f}) (type: string)
The password to use when logging in.

@item @code{password-file} (default: @code{".password.<nick>})
The file to read the password from to use when logging in.

@item @code{channels} (default: @code{'("##botchat")})
The channels for snuik to join, a list of strings.

@item @code{extra-options} (default: @code{'()})
Extra options will be passed to @command{snuik}, please run @command{snuik
--help } for more information.

@end table
@end deftp

@subsubheading Mosquitto Service

@url{https://mosquitto.org/,Mosquitto} is a lightweight message broker that
implements the MQTT protocol versions 5.0, 3.1.1 and 3.1.  It is suitable
for use on all devices from low power single board computers to full
servers.

@defvar mosquitto-service-type
This is the service type for the @url{https://mosquitto.org/,Mosquitto} MQTT
broker.  Its value is a @code{mosquitto-configuration} (see below).
@end defvar

@deftp {Data Type} mosquitto-configuration
This is the configuration for Mosquitto, with the following fields:

@table @asis
@item @code{package} (default: @code{mosquitto})
The Mosquitto package to use.

@item @code{config-file} (default: @code{#f})
The Mosquitto configuration file as a file-like object or the value
@code{#f} to use the default configuration.

@item @code{user} (default: @code{"mosquitto"})
Owner of the broker process.

@item @code{group} (default: @code{"mosquitto"})
Owner's group of the broker process.
@end table
@end deftp

@subsubheading Mollysocket Service

@url{https://github.com/mollyim/mollysocket,Mollysocket} is a UnifiedPush
provider for the messaging app @url{https://molly.im,Molly}, a fork of
Signal.

@defvar mollysocket-service-type
The Mollysocket service.  Takes @code{mollysocket-configuration} as its
value.  By default, this service listens on port 8020 for any Molly client.
@end defvar

@deftp {Data Type} mollysocket-configuration
The configuration for Mollysocket, with the following fields:

@table @asis
@item @code{package} (default: @code{mollysocket})
The Mollysocket package to use.

@item @code{host} (default: @code{"0.0.0.0"})
Address for the webserver to listen on. It is recommended that this be set
to localhost, and instead configure a TLS-supporting reverse proxy in front
of it.

@item @code{port} (default: @code{8020})
Port for the webserver to listen on.

@item @code{webserver} (default: @code{#t})
Whether the webserver sould be enabled. If disabled, the server is
considered to be in airgapped mode, and clients must be configured likewise.

@item @code{allowed-endpoints} (default: @code{'("*")})
Allowlist of UnifiedPush distributor endpoints, represented as IP addresses
or domain names. Addresses on the local network must be specified
explicitly.

@item @code{allowed-uuids} (default: @code{'("*")})
Allowlist of Signal account UUIDs.

@item @code{db} (default: @code{"/var/lib/mollysocket/db.sqlite"})
Path to the Mollysocket database. Will be created if it doesn't exist.

@item @code{vapid-key-file} (default: @code{"/var/lib/mollysocket/vapid.key"})
Path to the VAPID key used to authorize requests to the UnifiedPush
distributor.  Will be created if it doesn't exist.
@end table
@end deftp

@node Serviços de telefonia
@subsection Serviços de telefonia

@cindex telefonia, serviços
The @code{(gnu services telephony)} module contains Guix service definitions
for telephony services.  Currently it provides the following services:

@subsubheading Jami

@defvar jami-service-type
The service type for running Jami as a service.  It takes a
@code{jami-configuration} object as a value, documented below.  This section
describes how to configure a Jami server that can be used to host video (or
audio) conferences, among other uses.  The following example demonstrates
how to specify Jami account archives (backups) to be provisioned
automatically:

@lisp
(service jami-service-type
         (jami-configuration
          (accounts
           (list (jami-account
                  (archive "/etc/jami/unencrypted-account-1.gz"))
                 (jami-account
                  (archive "/etc/jami/unencrypted-account-2.gz"))))))
@end lisp

When the accounts field is specified, the Jami account files of the service
found under @file{/var/lib/jami} are recreated every time the service
starts.

Jami accounts and their corresponding backup archives can be generated using
the @code{jami} or @code{jami-gnome} Jami clients.  The accounts should not
be password-protected, but it is wise to ensure their files are only
readable by @samp{root}.

The next example shows how to declare that only some contacts should be
allowed to communicate with a given account:

@lisp
(service jami-service-type
         (jami-configuration
          (accounts
           (list (jami-account
                  (archive "/etc/jami/unencrypted-account-1.gz")
                  (peer-discovery? #t)
                  (rendezvous-point? #t)
                  (allowed-contacts
                   '("1dbcb0f5f37324228235564b79f2b9737e9a008f"
                     "2dbcb0f5f37324228235564b79f2b9737e9a008f")))))))
@end lisp

In this mode, only the declared @code{allowed-contacts} can initiate
communication with the Jami account.  This can be used, for example, with
rendezvous point accounts to create a private video conferencing space.

To put the system administrator in full control of the conferences hosted on
their system, the Jami service supports the following actions:

@example sh
# herd doc jami list-actions
(list-accounts
 list-account-details
 list-banned-contacts
 list-contacts
 list-moderators
 add-moderator
 ban-contact
 enable-account
 disable-account)
@end example

The above actions aim to provide the most valuable actions for moderation
purposes, not to cover the whole Jami API.  Users wanting to interact with
the Jami daemon from Guile may be interested in experimenting with the
@code{(gnu build jami-service)} module, which powers the above Shepherd
actions.

@c TODO: This should be auto-generated from the doc already defined on
@c the shepherd-actions themselves in (gnu services telephony).
The @code{add-moderator} and @code{ban-contact} actions accept a contact
@emph{fingerprint} (40 characters long hash) as first argument and an
account fingerprint or username as second argument:

@example sh
# herd add-moderator jami 1dbcb0f5f37324228235564b79f2b9737e9a008f \
  f3345f2775ddfe07a4b0d95daea111d15fbc1199

# herd list-moderators jami
Moderators for account f3345f2775ddfe07a4b0d95daea111d15fbc1199:
  - 1dbcb0f5f37324228235564b79f2b9737e9a008f

@end example

In the case of @code{ban-contact}, the second username argument is optional;
when omitted, the account is banned from all Jami accounts:

@example sh
# herd ban-contact jami 1dbcb0f5f37324228235564b79f2b9737e9a008f

# herd list-banned-contacts jami
Banned contacts for account f3345f2775ddfe07a4b0d95daea111d15fbc1199:
  - 1dbcb0f5f37324228235564b79f2b9737e9a008f

@end example

Banned contacts are also stripped from their moderation privileges.

The @code{disable-account} action allows to completely disconnect an account
from the network, making it unreachable, while @code{enable-account} does
the inverse.  They accept a single account username or fingerprint as first
argument:

@example sh
# herd disable-account jami f3345f2775ddfe07a4b0d95daea111d15fbc1199

# herd list-accounts jami
The following Jami accounts are available:
  - f3345f2775ddfe07a4b0d95daea111d15fbc1199 (dummy) [disabled]

@end example

The @code{list-account-details} action prints the detailed parameters of
each accounts in the Recutils format, which means the @command{recsel}
command can be used to select accounts of interest (@pxref{Selection
Expressions,,,recutils, GNU recutils manual}).  Note that period characters
(@samp{.}) found in the account parameter keys are mapped to underscores
(@samp{_}) in the output, to meet the requirements of the Recutils format.
The following example shows how to print the account fingerprints for all
accounts operating in the rendezvous point mode:

@example sh
# herd list-account-details jami | \
  recsel -p Account.username -e 'Account.rendezVous ~ "true"'
Account_username: f3345f2775ddfe07a4b0d95daea111d15fbc1199
@end example

The remaining actions should be self-explanatory.

The complete set of available configuration options is detailed below.
@end defvar

@c TODO: Ideally, the following fragments would be auto-generated at
@c build time, so that they needn't be manually duplicated.
@c Auto-generated via (configuration->documentation 'jami-configuration)
@deftp {Tipo de dados} jami-configuration
Available @code{jami-configuration} fields are:

@table @asis
@item @code{libjami} (default: @code{libjami}) (type: package)
The Jami daemon package to use.

@item @code{dbus} (default: @code{dbus-for-jami}) (type: package)
The D-Bus package to use to start the required D-Bus session.

@item @code{nss-certs} (default: @code{nss-certs}) (type: package)
The nss-certs package to use to provide TLS certificates.

@item @code{enable-logging?} (default: @code{#t}) (type: boolean)
Whether to enable logging to syslog.

@item @code{debug?} (default: @code{#f}) (type: boolean)
Whether to enable debug level messages.

@item @code{auto-answer?} (default: @code{#f}) (type: boolean)
Whether to force automatic answer to incoming calls.

@item @code{accounts} (type: maybe-jami-account-list)
A list of Jami accounts to be (re-)provisioned every time the Jami daemon
service starts.  When providing this field, the account directories under
@file{/var/lib/jami/} are recreated every time the service starts, ensuring
a consistent state.

@end table

@end deftp

@c Auto-generated via (configuration->documentation 'jami-account)
@deftp {Tipo de dados} jami-account
Available @code{jami-account} fields are:

@table @asis
@item @code{archive} (type: string-or-computed-file)
The account archive (backup) file name of the account.  This is used to
provision the account when the service starts.  The account archive should
@emph{not} be encrypted.  It is highly recommended to make it readable only
to the @samp{root} user (i.e., not in the store), to guard against leaking
the secret key material of the Jami account it contains.

@item @code{allowed-contacts} (type: maybe-account-fingerprint-list)
The list of allowed contacts for the account, entered as their 40 characters
long fingerprint.  Messages or calls from accounts not in that list will be
rejected.  When left specified, the configuration of the account archive is
used as-is with respect to contacts and public inbound calls/messaging
allowance, which typically defaults to allow any contact to communicate with
the account.

@item @code{moderators} (type: maybe-account-fingerprint-list)
The list of contacts that should have moderation privileges (to ban, mute,
etc.  other users) in rendezvous conferences, entered as their 40 characters
long fingerprint.  When left unspecified, the configuration of the account
archive is used as-is with respect to moderation, which typically defaults
to allow anyone to moderate.

@item @code{rendezvous-point?} (type: maybe-boolean)
Whether the account should operate in the rendezvous mode.  In this mode,
all the incoming audio/video calls are mixed into a conference.  When left
unspecified, the value from the account archive prevails.

@item @code{peer-discovery?} (type: maybe-boolean)
Whether peer discovery should be enabled.  Peer discovery is used to
discover other OpenDHT nodes on the local network, which can be useful to
maintain communication between devices on such network even when the
connection to the Internet has been lost.  When left unspecified, the value
from the account archive prevails.

@item @code{bootstrap-hostnames} (type: maybe-list-of-strings)
A list of hostnames or IPs pointing to OpenDHT nodes, that should be used to
initially join the OpenDHT network.  When left unspecified, the value from
the account archive prevails.

@item @code{name-server-uri} (type: maybe-string)
The URI of the name server to use, that can be used to retrieve the account
fingerprint for a registered username.

@end table

@end deftp

@subsubheading Mumble server

@cindex Mumble
@cindex Murmur
@cindex VoIP server
This section describes how to set up and run a @uref{https://mumble.info,
Mumble} server (formerly known as Murmur).

@defvar mumble-server-service-type

This is the service to run a Mumble server.  It takes a
@code{mumble-server-configuration} object as its value, defined below.
@end defvar

@deftp {Tipo de dados} mumble-server-configuration
The service type for the Mumble server.  An example configuration can look
like this:

@lisp
(service mumble-server-service-type
         (mumble-server-configuration
          (welcome-text
            "Welcome to this Mumble server running on Guix!")
          (cert-required? #t) ;disallow text password logins
          (ssl-cert "/etc/certs/mumble.example.com/fullchain.pem")
          (ssl-key "/etc/certs/mumble.example.com/privkey.pem")))
@end lisp

After reconfiguring your system, you can manually set the mumble-server
@code{SuperUser} password with the command that is printed during the
activation phase.

It is recommended to register a normal Mumble user account and grant it
admin or moderator rights.  You can use the @code{mumble} client to login as
new normal user, register yourself, and log out.  For the next step login
with the name @code{SuperUser} use the @code{SuperUser} password that you
set previously, and grant your newly registered mumble user administrator or
moderator rights and create some channels.

Available @code{mumble-server-configuration} fields are:

@table @asis
@item @code{package} (default: @code{mumble})
Package that contains @code{bin/mumble-server}.

@item @code{user} (default: @code{"mumble-server"})
User who will run the Mumble-Server server.

@item @code{group} (default: @code{"mumble-server"})
Group of the user who will run the mumble-server server.

@item @code{port} (padrão: @code{64738})
Port on which the server will listen.

@item @code{welcome-text} (default: @code{""})
Welcome text sent to clients when they connect.

@item @code{server-password} (default: @code{""})
Password the clients have to enter in order to connect.

@item @code{max-users} (default: @code{100})
Maximum of users that can be connected to the server at once.

@item @code{max-user-bandwidth} (default: @code{#f})
Maximum voice traffic a user can send per second.

@item @code{database-file} (default: @code{"/var/lib/mumble-server/db.sqlite"})
File name of the sqlite database.  The service's user will become the owner
of the directory.

@item @code{log-file} (default: @code{"/var/log/mumble-server/mumble-server.log"})
File name of the log file.  The service's user will become the owner of the
directory.

@item @code{autoban-attempts} (default: @code{10})
Maximum number of logins a user can make in @code{autoban-timeframe} without
getting auto banned for @code{autoban-time}.

@item @code{autoban-timeframe} (default: @code{120})
Timeframe for autoban in seconds.

@item @code{autoban-time} (default: @code{300})
Amount of time in seconds for which a client gets banned when violating the
autoban limits.

@item @code{opus-threshold} (default: @code{100})
Percentage of clients that need to support opus before switching over to
opus audio codec.

@item @code{channel-nesting-limit} (default: @code{10})
How deep channels can be nested at maximum.

@item @code{channelname-regex} (default: @code{#f})
A string in form of a Qt regular expression that channel names must conform
to.

@item @code{username-regex} (default: @code{#f})
A string in form of a Qt regular expression that user names must conform to.

@item @code{text-message-length} (default: @code{5000})
Maximum size in bytes that a user can send in one text chat message.

@item @code{image-message-length} (default: @code{(* 128 1024)})
Maximum size in bytes that a user can send in one image message.

@item @code{cert-required?} (default: @code{#f})
If it is set to @code{#t} clients that use weak password authentication will
not be accepted.  Users must have completed the certificate wizard to join.

@item @code{remember-channel?} (padrão: @code{#f})
Should mumble-server remember the last channel each user was in when they
disconnected and put them into the remembered channel when they rejoin.

@item @code{allow-html?} (default: @code{#f})
Should html be allowed in text messages, user comments, and channel
descriptions.

@item @code{allow-ping?} (default: @code{#f})
Setting to true exposes the current user count, the maximum user count, and
the server's maximum bandwidth per client to unauthenticated users.  In the
Mumble client, this information is shown in the Connect dialog.

Disabling this setting will prevent public listing of the server.

@item @code{bonjour?} (padrão: @code{#f})
Should the server advertise itself in the local network through the bonjour
protocol.

@item @code{send-version?} (default: @code{#f})
Should the mumble-server server version be exposed in ping requests.

@item @code{log-days} (default: @code{31})
Mumble also stores logs in the database, which are accessible via RPC.  The
default is 31 days of months, but you can set this setting to 0 to keep logs
forever, or -1 to disable logging to the database.

@item @code{obfuscate-ips?} (default: @code{#t})
Should logged ips be obfuscated to protect the privacy of users.

@item @code{ssl-cert} (default: @code{#f})
File name of the SSL/TLS certificate used for encrypted connections.

@lisp
(ssl-cert "/etc/certs/example.com/fullchain.pem")
@end lisp
@item @code{ssl-key} (default: @code{#f})
Filepath to the ssl private key used for encrypted connections.
@lisp
(ssl-key "/etc/certs/example.com/privkey.pem")
@end lisp

@item @code{ssl-dh-params} (default: @code{#f})
File name of a PEM-encoded file with Diffie-Hellman parameters for the
SSL/TLS encryption.  Alternatively you set it to @code{"@@ffdhe2048"},
@code{"@@ffdhe3072"}, @code{"@@ffdhe4096"}, @code{"@@ffdhe6144"} or
@code{"@@ffdhe8192"} to use bundled parameters from RFC 7919.

@item @code{ssl-ciphers} (default: @code{#f})
The @code{ssl-ciphers} option chooses the cipher suites to make available
for use in SSL/TLS.

This option is specified using
@uref{https://www.openssl.org/docs/apps/ciphers.html#CIPHER-LIST-FORMAT,
OpenSSL cipher list notation}.

It is recommended that you try your cipher string using 'openssl ciphers
<string>' before setting it here, to get a feel for which cipher suites you
will get.  After setting this option, it is recommend that you inspect your
Mumble server log to ensure that Mumble is using the cipher suites that you
expected it to.

@quotation Nota
Changing this option may impact the backwards compatibility of your
Mumble-Server server, and can remove the ability for older Mumble clients to
be able to connect to it.
@end quotation

@item @code{public-registration} (default: @code{#f})
Must be a @code{<mumble-server-public-registration-configuration>} record or
@code{#f}.

You can optionally register your server in the public server list that the
@code{mumble} client shows on startup.  You cannot register your server if
you have set a @code{server-password}, or set @code{allow-ping} to
@code{#f}.

It might take a few hours until it shows up in the public list.

@item @code{file} (padrão: @code{#f})
Optional alternative override for this configuration.
@end table
@end deftp

@deftp {Tipo de dados} mumble-server-public-registration-configuration
Configuration for public registration of a mumble-server service.

@table @asis
@item @code{name}
This is a display name for your server.  Not to be confused with the
hostname.

@item @code{password}
A password to identify your registration.  Subsequent updates will need the
same password.  Don't lose your password.

@item @code{url}
This should be a @code{http://} or @code{https://} link to your web site.

@item @code{hostname} (padrão: @code{#f})
By default your server will be listed by its IP address.  If it is set your
server will be linked by this host name instead.
@end table
@end deftp

@quotation Deprecation notice
Due to historical reasons, all of the above @code{mumble-server-} procedures
are also exported with the @code{murmur-} prefix.  It is recommended that
you switch to using @code{mumble-server-} going forward.
@end quotation

@node Serviços de compartilhamento de arquivos
@subsection Serviços de compartilhamento de arquivos

The @code{(gnu services file-sharing)} module provides services that assist
with transferring files over peer-to-peer file-sharing networks.

@subsubheading Transmission Daemon Service

@uref{https://transmissionbt.com/, Transmission} is a flexible BitTorrent
client that offers a variety of graphical and command-line interfaces.  A
@code{transmission-daemon-service-type} service provides Transmission's
headless variant, @command{transmission-daemon}, as a system service,
allowing users to share files via BitTorrent even when they are not logged
in.

@defvar transmission-daemon-service-type
The service type for the Transmission Daemon BitTorrent client. Its value
must be a @code{transmission-daemon-configuration} object as in this
example:

@lisp
(service transmission-daemon-service-type
         (transmission-daemon-configuration
          ;; Restrict access to the RPC ("control") interface
          (rpc-authentication-required? #t)
          (rpc-username "transmission")
          (rpc-password
           (transmission-password-hash
            "transmission" ; desired password
            "uKd1uMs9"))   ; arbitrary salt value

          ;; Accept requests from this and other hosts on the
          ;; local network
          (rpc-whitelist-enabled? #t)
          (rpc-whitelist '("::1" "127.0.0.1" "192.168.0.*"))

          ;; Limit bandwidth use during work hours
          (alt-speed-down (* 1024 2)) ;   2 MB/s
          (alt-speed-up 512)          ; 512 kB/s

          (alt-speed-time-enabled? #t)
          (alt-speed-time-day 'weekdays)
          (alt-speed-time-begin
           (+ (* 60 8) 30))           ; 8:30 am
          (alt-speed-time-end
           (+ (* 60 (+ 12 5)) 30))))  ; 5:30 pm
@end lisp
@end defvar

Once the service is started, users can interact with the daemon through its
Web interface (at @code{http://localhost:9091/}) or by using the
@command{transmission-remote} command-line tool, available in the
@code{transmission} package.  (Emacs users may want to also consider the
@code{emacs-transmission} package.)  Both communicate with the daemon
through its remote procedure call (RPC) interface, which by default is
available to all users on the system; you may wish to change this by
assigning values to the @code{rpc-authentication-required?},
@code{rpc-username} and @code{rpc-password} settings, as shown in the
example above and documented further below.

The value for @code{rpc-password} must be a password hash of the type
generated and used by Transmission clients.  This can be copied verbatim
from an existing @file{settings.json} file, if another Transmission client
is already being used.  Otherwise, the @code{transmission-password-hash} and
@code{transmission-random-salt} procedures provided by this module can be
used to obtain a suitable hash value.

@deffn {Procedure} transmission-password-hash password salt
Returns a string containing the result of hashing @var{password} together
with @var{salt}, in the format recognized by Transmission clients for their
@code{rpc-password} configuration setting.

@var{salt} must be an eight-character string.  The
@code{transmission-random-salt} procedure can be used to generate a suitable
salt value at random.
@end deffn

@deffn {Procedure} transmission-random-salt
Returns a string containing a random, eight-character salt value of the type
generated and used by Transmission clients, suitable for passing to the
@code{transmission-password-hash} procedure.
@end deffn

These procedures are accessible from within a Guile REPL started with the
@command{guix repl} command (@pxref{Invocando guix repl}).  This is useful
for obtaining a random salt value to provide as the second parameter to
`transmission-password-hash`, as in this example session:

@example
$ guix repl
scheme@@(guix-user)> ,use (gnu services file-sharing)
scheme@@(guix-user)> (transmission-random-salt)
$1 = "uKd1uMs9"
@end example

Alternatively, a complete password hash can generated in a single step:

@example
scheme@@(guix-user)> (transmission-password-hash "transmission"
(transmission-random-salt))
$2 = "@{c8bbc6d1740cd8dc819a6e25563b67812c1c19c9VtFPfdsX"
@end example

The resulting string can be used as-is for the value of @code{rpc-password},
allowing the password to be kept hidden even in the operating-system
configuration.

Torrent files downloaded by the daemon are directly accessible only to users
in the ``transmission'' user group, who receive read-only access to the
directory specified by the @code{download-dir} configuration setting (and
also the directory specified by @code{incomplete-dir}, if
@code{incomplete-dir-enabled?} is @code{#t}).  Downloaded files can be moved
to another directory or deleted altogether using
@command{transmission-remote} with its @code{--move} and
@code{--remove-and-delete} options.

If the @code{watch-dir-enabled?} setting is set to @code{#t}, users in the
``transmission'' group are able also to place @file{.torrent} files in the
directory specified by @code{watch-dir} to have the corresponding torrents
added by the daemon.  (The @code{trash-original-torrent-files?} setting
controls whether the daemon deletes these files after processing them.)

Some of the daemon's configuration settings can be changed temporarily by
@command{transmission-remote} and similar tools. To undo these changes, use
the service's @code{reload} action to have the daemon reload its settings
from disk:

@example
# herd reload transmission-daemon
@end example

The full set of available configuration settings is defined by the
@code{transmission-daemon-configuration} data type.

@deftp {Tipo de dados} transmission-daemon-configuration
The data type representing configuration settings for Transmission Daemon.
These correspond directly to the settings recognized by Transmission clients
in their @file{settings.json} file.
@end deftp

@c The following documentation was initially generated by
@c (generate-transmission-daemon-documentation) in (gnu services
@c file-sharing).  Manually maintained documentation is better, so we
@c shouldn't hesitate to edit below as needed.  However if the change
@c you want to make to this documentation can be done in an automated
@c way, it's probably easier to change (generate-documentation) than to
@c make it below and have to deal with the churn as Transmission Daemon
@c updates.

@c %start of fragment

Available @code{transmission-daemon-configuration} fields are:

@deftypevr {@code{transmission-daemon-configuration} parameter} package transmission
The Transmission package to use.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer stop-wait-period
The period, in seconds, to wait when stopping the service for
@command{transmission-daemon} to exit before killing its process.  This
allows the daemon time to complete its housekeeping and send a final update
to trackers as it shuts down.  On slow hosts, or hosts with a slow network
connection, this value may need to be increased.

Defaults to @samp{10}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} string download-dir
The directory to which torrent files are downloaded.

Defaults to @samp{"/var/lib/transmission-daemon/downloads"}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} boolean incomplete-dir-enabled?
If @code{#t}, files will be held in @code{incomplete-dir} while their
torrent is being downloaded, then moved to @code{download-dir} once the
torrent is complete.  Otherwise, files for all torrents (including those
still being downloaded) will be placed in @code{download-dir}.

Defaults to @samp{#f}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} maybe-string incomplete-dir
The directory in which files from incompletely downloaded torrents will be
held when @code{incomplete-dir-enabled?} is @code{#t}.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} umask umask
The file mode creation mask used for downloaded files.  (See the
@command{umask} man page for more information.)

Defaults to @samp{18}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} boolean rename-partial-files?
When @code{#t}, ``.part'' is appended to the name of partially downloaded
files.

Defaults to @samp{#t}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} preallocation-mode preallocation
The mode by which space should be preallocated for downloaded files, one of
@code{none}, @code{fast} (or @code{sparse}) and @code{full}.  Specifying
@code{full} will minimize disk fragmentation at a cost to file-creation
speed.

Defaults to @samp{fast}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} boolean watch-dir-enabled?
If @code{#t}, the directory specified by @code{watch-dir} will be watched
for new @file{.torrent} files and the torrents they describe added
automatically (and the original files removed, if
@code{trash-original-torrent-files?} is @code{#t}).

Defaults to @samp{#f}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} maybe-string watch-dir
The directory to be watched for @file{.torrent} files indicating new
torrents to be added, when @code{watch-dir-enabled} is @code{#t}.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} boolean trash-original-torrent-files?
When @code{#t}, @file{.torrent} files will be deleted from the watch
directory once their torrent has been added (see
@code{watch-directory-enabled?}).

Defaults to @samp{#f}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} boolean speed-limit-down-enabled?
When @code{#t}, the daemon's download speed will be limited to the rate
specified by @code{speed-limit-down}.

Defaults to @samp{#f}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer speed-limit-down
The default global-maximum download speed, in kilobytes per second.

Defaults to @samp{100}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} boolean speed-limit-up-enabled?
When @code{#t}, the daemon's upload speed will be limited to the rate
specified by @code{speed-limit-up}.

Defaults to @samp{#f}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer speed-limit-up
The default global-maximum upload speed, in kilobytes per second.

Defaults to @samp{100}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} boolean alt-speed-enabled?
When @code{#t}, the alternate speed limits @code{alt-speed-down} and
@code{alt-speed-up} are used (in place of @code{speed-limit-down} and
@code{speed-limit-up}, if they are enabled) to constrain the daemon's
bandwidth usage.  This can be scheduled to occur automatically at certain
times during the week; see @code{alt-speed-time-enabled?}.

Defaults to @samp{#f}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer alt-speed-down
The alternate global-maximum download speed, in kilobytes per second.

Defaults to @samp{50}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer alt-speed-up
The alternate global-maximum upload speed, in kilobytes per second.

Defaults to @samp{50}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} boolean alt-speed-time-enabled?
When @code{#t}, the alternate speed limits @code{alt-speed-down} and
@code{alt-speed-up} will be enabled automatically during the periods
specified by @code{alt-speed-time-day}, @code{alt-speed-time-begin} and
@code{alt-time-speed-end}.

Defaults to @samp{#f}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} day-list alt-speed-time-day
The days of the week on which the alternate-speed schedule should be used,
specified either as a list of days (@code{sunday}, @code{monday}, and so on)
or using one of the symbols @code{weekdays}, @code{weekends} or @code{all}.

Defaults to @samp{all}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer alt-speed-time-begin
The time of day at which to enable the alternate speed limits, expressed as
a number of minutes since midnight.

Defaults to @samp{540}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer alt-speed-time-end
The time of day at which to disable the alternate speed limits, expressed as
a number of minutes since midnight.

Defaults to @samp{1020}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} string bind-address-ipv4
The IP address at which to listen for peer connections, or ``0.0.0.0'' to
listen at all available IP addresses.

Defaults to @samp{"0.0.0.0"}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} string bind-address-ipv6
The IPv6 address at which to listen for peer connections, or ``::'' to
listen at all available IPv6 addresses.

Defaults to @samp{"::"}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} boolean peer-port-random-on-start?
If @code{#t}, when the daemon starts it will select a port at random on
which to listen for peer connections, from the range specified (inclusively)
by @code{peer-port-random-low} and @code{peer-port-random-high}.  Otherwise,
it listens on the port specified by @code{peer-port}.

Defaults to @samp{#f}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} port-number peer-port-random-low
The lowest selectable port number when @code{peer-port-random-on-start?} is
@code{#t}.

Defaults to @samp{49152}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} port-number peer-port-random-high
The highest selectable port number when @code{peer-port-random-on-start} is
@code{#t}.

Defaults to @samp{65535}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} port-number peer-port
The port on which to listen for peer connections when
@code{peer-port-random-on-start?} is @code{#f}.

Defaults to @samp{51413}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} boolean port-forwarding-enabled?
If @code{#t}, the daemon will attempt to configure port-forwarding on an
upstream gateway automatically using @acronym{UPnP} and @acronym{NAT-PMP}.

Defaults to @samp{#t}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} encryption-mode encryption
The encryption preference for peer connections, one of
@code{prefer-unencrypted-connections}, @code{prefer-encrypted-connections}
or @code{require-encrypted-connections}.

Defaults to @samp{prefer-encrypted-connections}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} maybe-string peer-congestion-algorithm
The TCP congestion-control algorithm to use for peer connections, specified
using a string recognized by the operating system in calls to
@code{setsockopt}.  When left unspecified, the operating-system default is
used.

Note that on GNU/Linux systems, the kernel must be configured to allow
processes to use a congestion-control algorithm not in the default set;
otherwise, it will deny these requests with ``Operation not permitted''.  To
see which algorithms are available on your system and which are currently
permitted for use, look at the contents of the files
@file{tcp_available_congestion_control} and
@file{tcp_allowed_congestion_control} in the @file{/proc/sys/net/ipv4}
directory.

As an example, to have Transmission Daemon use
@uref{http://www-ece.rice.edu/networks/TCP-LP/,the TCP Low Priority
congestion-control algorithm}, you'll need to modify your kernel
configuration to build in support for the algorithm, then update your
operating-system configuration to allow its use by adding a
@code{sysctl-service-type} service (or updating the existing one's
configuration) with lines like the following:

@lisp
(service sysctl-service-type
         (sysctl-configuration
          (settings
           ("net.ipv4.tcp_allowed_congestion_control" .
            "reno cubic lp"))))
@end lisp

The Transmission Daemon configuration can then be updated with

@lisp
(peer-congestion-algorithm "lp")
@end lisp

and the system reconfigured to have the changes take effect.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} tcp-type-of-service peer-socket-tos
The type of service to request in outgoing @acronym{TCP} packets, one of
@code{default}, @code{low-cost}, @code{throughput}, @code{low-delay} and
@code{reliability}.

Defaults to @samp{default}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer peer-limit-global
The global limit on the number of connected peers.

Defaults to @samp{200}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer peer-limit-per-torrent
The per-torrent limit on the number of connected peers.

Defaults to @samp{50}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer upload-slots-per-torrent
The maximum number of peers to which the daemon will upload data
simultaneously for each torrent.

Defaults to @samp{14}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer peer-id-ttl-hours
The maximum lifespan, in hours, of the peer ID associated with each public
torrent before it is regenerated.

Defaults to @samp{6}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} boolean blocklist-enabled?
When @code{#t}, the daemon will ignore peers mentioned in the blocklist it
has most recently downloaded from @code{blocklist-url}.

Defaults to @samp{#f}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} maybe-string blocklist-url
The URL of a peer blocklist (in @acronym{P2P}-plaintext or eMule @file{.dat}
format) to be periodically downloaded and applied when
@code{blocklist-enabled?} is @code{#t}.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} boolean download-queue-enabled?
If @code{#t}, the daemon will be limited to downloading at most
@code{download-queue-size} non-stalled torrents simultaneously.

Defaults to @samp{#t}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer download-queue-size
The size of the daemon's download queue, which limits the number of
non-stalled torrents it will download at any one time when
@code{download-queue-enabled?} is @code{#t}.

Defaults to @samp{5}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} boolean seed-queue-enabled?
If @code{#t}, the daemon will be limited to seeding at most
@code{seed-queue-size} non-stalled torrents simultaneously.

Defaults to @samp{#f}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer seed-queue-size
The size of the daemon's seed queue, which limits the number of non-stalled
torrents it will seed at any one time when @code{seed-queue-enabled?} is
@code{#t}.

Defaults to @samp{10}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} boolean queue-stalled-enabled?
When @code{#t}, the daemon will consider torrents for which it has not
shared data in the past @code{queue-stalled-minutes} minutes to be stalled
and not count them against its @code{download-queue-size} and
@code{seed-queue-size} limits.

Defaults to @samp{#t}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer queue-stalled-minutes
The maximum period, in minutes, a torrent may be idle before it is
considered to be stalled, when @code{queue-stalled-enabled?} is @code{#t}.

Defaults to @samp{30}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} boolean ratio-limit-enabled?
When @code{#t}, a torrent being seeded will automatically be paused once it
reaches the ratio specified by @code{ratio-limit}.

Defaults to @samp{#f}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-rational ratio-limit
The ratio at which a torrent being seeded will be paused, when
@code{ratio-limit-enabled?} is @code{#t}.

Defaults to @samp{2.0}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} boolean idle-seeding-limit-enabled?
When @code{#t}, a torrent being seeded will automatically be paused once it
has been idle for @code{idle-seeding-limit} minutes.

Defaults to @samp{#f}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer idle-seeding-limit
The maximum period, in minutes, a torrent being seeded may be idle before it
is paused, when @code{idle-seeding-limit-enabled?} is @code{#t}.

Defaults to @samp{30}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} boolean dht-enabled?
Enable @uref{http://bittorrent.org/beps/bep_0005.html,the distributed hash
table (@acronym{DHT}) protocol}, which supports the use of trackerless
torrents.

Defaults to @samp{#t}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} boolean lpd-enabled?
Enable @uref{https://en.wikipedia.org/wiki/Local_Peer_Discovery,local peer
discovery} (@acronym{LPD}), which allows the discovery of peers on the local
network and may reduce the amount of data sent over the public Internet.

Defaults to @samp{#f}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} boolean pex-enabled?
Enable @uref{https://en.wikipedia.org/wiki/Peer_exchange,peer exchange}
(@acronym{PEX}), which reduces the daemon's reliance on external trackers
and may improve its performance.

Defaults to @samp{#t}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} boolean utp-enabled?
Enable @uref{http://bittorrent.org/beps/bep_0029.html,the micro transport
protocol} (@acronym{uTP}), which aims to reduce the impact of BitTorrent
traffic on other users of the local network while maintaining full
utilization of the available bandwidth.

Defaults to @samp{#t}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} boolean rpc-enabled?
If @code{#t}, enable the remote procedure call (@acronym{RPC})  interface,
which allows remote control of the daemon via its Web interface, the
@command{transmission-remote} command-line client, and similar tools.

Defaults to @samp{#t}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} string rpc-bind-address
The IP address at which to listen for @acronym{RPC} connections, or
``0.0.0.0'' to listen at all available IP addresses.

Defaults to @samp{"0.0.0.0"}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} port-number rpc-port
The port on which to listen for @acronym{RPC} connections.

Defaults to @samp{9091}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} string rpc-url
The path prefix to use in the @acronym{RPC}-endpoint @acronym{URL}.

Defaults to @samp{"/transmission/"}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} boolean rpc-authentication-required?
When @code{#t}, clients must authenticate (see @code{rpc-username} and
@code{rpc-password}) when using the @acronym{RPC} interface.  Note this has
the side effect of disabling host-name whitelisting (see
@code{rpc-host-whitelist-enabled?}.

Defaults to @samp{#f}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} maybe-string rpc-username
The username required by clients to access the @acronym{RPC} interface when
@code{rpc-authentication-required?} is @code{#t}.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} maybe-transmission-password-hash rpc-password
The password required by clients to access the @acronym{RPC} interface when
@code{rpc-authentication-required?} is @code{#t}.  This must be specified
using a password hash in the format recognized by Transmission clients,
either copied from an existing @file{settings.json} file or generated using
the @code{transmission-password-hash} procedure.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} boolean rpc-whitelist-enabled?
When @code{#t}, @acronym{RPC} requests will be accepted only when they
originate from an address specified in @code{rpc-whitelist}.

Defaults to @samp{#t}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} string-list rpc-whitelist
The list of IP and IPv6 addresses from which @acronym{RPC} requests will be
accepted when @code{rpc-whitelist-enabled?} is @code{#t}.  Wildcards may be
specified using @samp{*}.

Defaults to @samp{'("127.0.0.1" "::1")}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} boolean rpc-host-whitelist-enabled?
When @code{#t}, @acronym{RPC} requests will be accepted only when they are
addressed to a host named in @code{rpc-host-whitelist}.  Note that requests
to ``localhost'' or ``localhost.'', or to a numeric address, are always
accepted regardless of these settings.

Note also this functionality is disabled when
@code{rpc-authentication-required?} is @code{#t}.

Defaults to @samp{#t}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} string-list rpc-host-whitelist
The list of host names recognized by the @acronym{RPC} server when
@code{rpc-host-whitelist-enabled?} is @code{#t}.

Defaults to @samp{'()}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} message-level message-level
The minimum severity level of messages to be logged (to
@file{/var/log/transmission.log}) by the daemon, one of @code{none} (no
logging), @code{error}, @code{info} and @code{debug}.

Defaults to @samp{info}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} boolean start-added-torrents?
When @code{#t}, torrents are started as soon as they are added; otherwise,
they are added in ``paused'' state.

Defaults to @samp{#t}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} boolean script-torrent-done-enabled?
When @code{#t}, the script specified by @code{script-torrent-done-filename}
will be invoked each time a torrent completes.

Defaults to @samp{#f}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} maybe-file-object script-torrent-done-filename
A file name or file-like object specifying a script to run each time a
torrent completes, when @code{script-torrent-done-enabled?} is @code{#t}.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} boolean scrape-paused-torrents-enabled?
When @code{#t}, the daemon will scrape trackers for a torrent even when the
torrent is paused.

Defaults to @samp{#t}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer cache-size-mb
The amount of memory, in megabytes, to allocate for the daemon's in-memory
cache.  A larger value may increase performance by reducing the frequency of
disk I/O.

Defaults to @samp{4}.

@end deftypevr

@deftypevr {@code{transmission-daemon-configuration} parameter} boolean prefetch-enabled?
When @code{#t}, the daemon will try to improve I/O performance by hinting to
the operating system which data is likely to be read next from disk to
satisfy requests from peers.

Defaults to @samp{#t}.

@end deftypevr


@c %end of fragment



@node Serviços de monitoramento
@subsection Serviços de monitoramento

@subsubheading Darkstat Service
@cindex darkstat
Darkstat is a packet sniffer that captures network traffic, calculates
statistics about usage, and serves reports over HTTP.

@defvar darkstat-service-type
This is the service type for the @uref{https://unix4lyfe.org/darkstat/,
darkstat} service, its value must be a @code{darkstat-configuration} record
as in this example:

@lisp
(service darkstat-service-type
         (darkstat-configuration
           (interface "eno1")))
@end lisp
@end defvar

@deftp {Tipo de dados} darkstat-configuration
Data type representing the configuration of @command{darkstat}.

@table @asis
@item @code{package} (default: @code{darkstat})
The darkstat package to use.

@item @code{interface}
Capture traffic on the specified network interface.

@item @code{port} (padrão: @code{"667"})
Bind the web interface to the specified port.

@item @code{bind-address} (default: @code{"127.0.0.1"})
Bind the web interface to the specified address.

@item @code{base} (default: @code{"/"})
Specify the path of the base URL@.  This can be useful if @command{darkstat}
is accessed via a reverse proxy.

@end table
@end deftp

@anchor{prometheus-node-exporter}
@subsubheading Prometheus Node Exporter Service
@cindex prometheus-node-exporter

The Prometheus ``node exporter'' makes hardware and operating system
statistics provided by the Linux kernel available for the Prometheus
monitoring system.  This service should be deployed on all physical nodes
and virtual machines, where monitoring these statistics is desirable.

@defvar prometheus-node-exporter-service-type
This is the service type for the
@uref{https://github.com/prometheus/node_exporter/,
prometheus-node-exporter} service, its value must be a
@code{prometheus-node-exporter-configuration}.

@lisp
(service prometheus-node-exporter-service-type)
@end lisp
@end defvar

@deftp {Tipo de dados} prometheus-node-exporter-configuration
Data type representing the configuration of @command{node_exporter}.

@table @asis
@item @code{package} (default: @code{go-github-com-prometheus-node-exporter})
The prometheus-node-exporter package to use.

@item @code{web-listen-address} (default: @code{":9100"})
Bind the web interface to the specified address.

@item @code{textfile-directory} (default: @code{"/var/lib/prometheus/node-exporter"})
This directory can be used to export metrics specific to this machine.
Files containing metrics in the text format, with the filename ending in
@code{.prom} should be placed in this directory.

@item @code{extra-options} (default: @code{'()})
Extra options to pass to the Prometheus node exporter.

@end table
@end deftp

@anchor{vnstat}
@subsubheading vnStat Network Traffic Monitor
@cindex vnstat

vnStat is a network traffic monitor that uses interface statistics provided
by the kernel rather than traffic sniffing.  This makes it a light resource
monitor, regardless of network traffic rate.

@defvar vnstat-service-type
This is the service type for the @uref{https://humdi.net/vnstat/,vnStat}
daemon and accepts a @code{vnstat-configuration} value.

The following example will configure the service with default values:

@lisp
(service vnstat-service-type)
@end lisp
@end defvar

@c %start of fragment
@deftp {Tipo de dados} vnstat-configuration
Available @code{vnstat-configuration} fields are:

@table @asis
@item @code{package} (default: @code{vnstat}) (type: file-like)
The vnstat package.

@item @code{database-directory} (default: @code{"/var/lib/vnstat"}) (type: string)
Specifies the directory where the database is to be stored.  A full path
must be given and a leading '/' isn't required.

@item @code{5-minute-hours} (default: @code{48}) (type: maybe-integer)
Data retention duration for the 5 minute resolution entries.  The
configuration defines for how many past hours entries will be stored.  Set
to @code{-1} for unlimited entries or to @code{0} to disable the data
collection of this resolution.

@item @code{64bit-interface-counters} (default: @code{-2}) (type: maybe-integer)
Select interface counter handling.  Set to @code{1} for defining that all
interfaces use 64-bit counters on the kernel side and @code{0} for defining
32-bit counter.  Set to @code{-1} for using the old style logic used in
earlier versions where counter values within 32-bits are assumed to be
32-bit and anything larger is assumed to be a 64-bit counter.  This may
produce false results if a 64-bit counter is reset within the 32-bits.  Set
to @code{-2} for using automatic detection based on available kernel
datastructures.

@item @code{always-add-new-interfaces?} (default: @code{#t}) (type: maybe-boolean)
Enable or disable automatic creation of new database entries for interfaces
not currently in the database even if the database file already exists when
the daemon is started.  New database entries will also get created for new
interfaces seen while the daemon is running.  Pseudo interfaces @samp{lo},
@samp{lo0} and @samp{sit0} are always excluded from getting added.

@item @code{bandwidth-detection?} (default: @code{#t}) (type: maybe-boolean)
Try to automatically detect @var{max-bandwidth} value for each monitored
interface.  Mostly only ethernet interfaces support this feature.
@var{max-bandwidth} will be used as fallback value if detection fails.  Any
interface specific @var{max-BW} configuration will disable the detection for
the specified interface.  In Linux, the detection is disabled for tun
interfaces due to the Linux kernel always reporting 10 Mbit regardless of
the used real interface.

@item @code{bandwidth-detection-interval} (default: @code{5}) (type: maybe-integer)
How often in minutes interface specific detection of @var{max-bandwidth} is
done for detecting possible changes when @var{bandwidth-detection} is
enabled.  Can be disabled by setting to @code{0}.  Value range:
@samp{0}..@samp{30}

@item @code{boot-variation} (default: @code{15}) (type: maybe-integer)
Time in seconds how much the boot time reported by system kernel can variate
between updates.  Value range: @samp{0}..@samp{300}

@item @code{check-disk-space?} (default: @code{#t}) (type: maybe-boolean)
Enable or disable the availability check of at least some free disk space
before a database write.

@item @code{create-directories?} (default: @code{#t}) (type: maybe-boolean)
Enable or disable the creation of directories when a configured path doesn't
exist.  This includes @var{database-directory}.

@item @code{daemon-group} (type: maybe-user-group)
Specify the group to which the daemon process should switch during startup.
Set to @code{%unset-value} to disable group switching.

@item @code{daemon-user} (type: maybe-user-account)
Specify the user to which the daemon process should switch during startup.
Set to @code{%unset-value} to disable user switching.

@item @code{daily-days} (default: @code{62}) (type: maybe-integer)
Data retention duration for the one day resolution entries.  The
configuration defines for how many past days entries will be stored.  Set to
@code{-1} for unlimited entries or to @code{0} to disable the data
collection of this resolution.

@item @code{database-synchronous} (default: @code{-1}) (type: maybe-integer)
Change the setting of the SQLite "synchronous" flag which controls how much
care is taken to ensure disk writes have fully completed when writing data
to the database before continuing other actions.  Higher values take extra
steps to ensure data safety at the cost of slower performance.  A value of
@code{0} will result in all handling being left to the filesystem itself.
Set to @code{-1} to select the default value according to database mode
controlled by @var{database-write-ahead-logging} setting.  See SQLite
documentation for more details regarding values from @code{1} to @code{3}.
Value range: @samp{-1}..@samp{3}

@item @code{database-write-ahead-logging?} (default: @code{#f}) (type: maybe-boolean)
Enable or disable SQLite Write-Ahead Logging mode for the database.  See
SQLite documentation for more details and note that support for read-only
operations isn't available in older SQLite versions.

@item @code{hourly-days} (default: @code{4}) (type: maybe-integer)
Data retention duration for the one hour resolution entries.  The
configuration defines for how many past days entries will be stored.  Set to
@code{-1} for unlimited entries or to @code{0} to disable the data
collection of this resolution.

@item @code{log-file} (type: maybe-string)
Specify log file path and name to be used if @var{use-logging} is set to
@code{1}.

@item @code{max-bandwidth} (type: maybe-integer)
Maximum bandwidth for all interfaces.  If the interface specific traffic
exceeds the given value then the data is assumed to be invalid and
rejected.  Set to 0 in order to disable the feature.  Value range:
@samp{0}..@samp{50000}

@item @code{max-bw} (type: maybe-alist)
Same as @var{max-bandwidth} but can be used for setting individual limits
for selected interfaces.  This is an association list of interfaces as
strings to integer values.  For example,
@lisp
(max-bw `(("eth0" .  15000)
          ("ppp0" .  10000)))
@end lisp
@var{bandwidth-detection} is disabled on an interface specific level for
each @var{max-bw} configuration.  Value range: @samp{0}..@samp{50000}

@item @code{monthly-months} (default: @code{25}) (type: maybe-integer)
Data retention duration for the one month resolution entries.  The
configuration defines for how many past months entries will be stored.  Set
to @code{-1} for unlimited entries or to @code{0} to disable the data
collection of this resolution.

@item @code{month-rotate} (default: @code{1}) (type: maybe-integer)
Day of month that months are expected to change.  Usually set to 1 but can
be set to alternative values for example for tracking monthly billed traffic
where the billing period doesn't start on the first day.  For example, if
set to 7, days of February up to and including the 6th will count for
January.  Changing this option will not cause existing data to be
recalculated.  Value range: @samp{1}..@samp{28}

@item @code{month-rotate-affects-years?} (default: @code{#f}) (type: maybe-boolean)
Enable or disable @var{month-rotate} also affecting yearly data.  Applicable
only when @var{month-rotate} has a value greater than one.

@item @code{offline-save-interval} (default: @code{30}) (type: maybe-integer)
How often in minutes cached interface data is saved to file when all
monitored interfaces are offline.  Value range:
@var{save-interval}..@samp{60}

@item @code{pid-file} (default: @code{"/var/run/vnstatd.pid"}) (type: maybe-string)
Specify pid file path and name to be used.

@item @code{poll-interval} (default: @code{5}) (type: maybe-integer)
How often in seconds interfaces are checked for status changes.  Value
range: @samp{2}..@samp{60}

@item @code{rescan-database-on-save?} (type: maybe-boolean)
Automatically discover added interfaces from the database and start
monitoring.  The rescan is done every @var{save-interval} or
@var{offline-save-interval} minutes depending on the current activity state.

@item @code{save-interval} (default: @code{5}) (type: maybe-integer)
How often in minutes cached interface data is saved to file.  Value range: (
@var{update-interval} / 60 )..@samp{60}

@item @code{save-on-status-change?} (default: @code{#t}) (type: maybe-boolean)
Enable or disable the additional saving to file of cached interface data
when the availability of an interface changes, i.e., when an interface goes
offline or comes online.

@item @code{time-sync-wait} (default: @code{5}) (type: maybe-integer)
How many minutes to wait during daemon startup for system clock to sync if
most recent database update appears to be in the future.  This may be needed
in systems without a real-time clock (RTC) which require some time after
boot to query and set the correct time.  @code{0} = wait disabled.  Value
range: @samp{0}..@samp{60}

@item @code{top-day-entries} (default: @code{20}) (type: maybe-integer)
Data retention duration for the top day entries.  The configuration defines
how many of the past top day entries will be stored.  Set to @code{-1} for
unlimited entries or to @code{0} to disable the data collection of this
resolution.

@item @code{trafficless-entries?} (default: @code{#t}) (type: maybe-boolean)
Create database entries even when there is no traffic during the entry's
time period.

@item @code{update-file-owner?} (default: @code{#t}) (type: maybe-boolean)
Enable or disable the update of file ownership during daemon process
startup.  During daemon startup, only database, log and pid files will be
modified if the user or group change feature ( @var{daemon-user} or
@var{daemon-group} ) is enabled and the files don't match the requested user
or group.  During manual database creation, this option will cause file
ownership to be inherited from the database directory if the directory
already exists.  This option only has effect when the process is started as
root or via sudo.

@item @code{update-interval} (default: @code{20}) (type: maybe-integer)
How often in seconds the interface data is updated.  Value range:
@var{poll-interval}..@samp{300}

@item @code{use-logging} (default: @code{2}) (type: maybe-integer)
Enable or disable logging.  Accepted values are: @code{0} = disabled,
@code{1} = logfile and @code{2} = syslog.

@item @code{use-utc?} (type: maybe-boolean)
Enable or disable using UTC as timezone in the database for all entries.
When enabled, all entries added to the database will use UTC regardless of
the configured system timezone.  When disabled, the configured system
timezone will be used.  Changing this setting will not result in already
existing data to be modified.

@item @code{yearly-years} (default: @code{-1}) (type: maybe-integer)
Data retention duration for the one year resolution entries.  The
configuration defines for how many past years entries will be stored.  Set
to @code{-1} for unlimited entries or to @code{0} to disable the data
collection of this resolution.

@end table
@end deftp
@c %end of fragment

@subsubheading Zabbix server
@cindex zabbix zabbix-server
Zabbix is a high performance monitoring system that can collect data from a
variety of sources and provide the results in a web-based interface.
Alerting and reporting is built-in, as well as @dfn{templates} for common
operating system metrics such as network utilization, CPU load, and disk
space consumption.

This service provides the central Zabbix monitoring service; you also need
@ref{zabbix-front-end,@code{zabbix-front-end-service-type}} to configure
Zabbix and display results, and optionally @ref{zabbix-agent,
@code{zabbix-agent-service-type}} on machines that should be monitored
(other data sources are supported, such as @ref{prometheus-node-exporter,
Prometheus Node Exporter}).

@defvar zabbix-server-service-type
This is the service type for the Zabbix server service.  Its value must be a
@code{zabbix-server-configuration} record, shown below.
@end defvar

@c %start of fragment

@deftp {Tipo de dados} zabbix-server-configuration
Available @code{zabbix-server-configuration} fields are:

@table @asis
@item @code{zabbix-server} (default: @code{zabbix-server}) (type: file-like)
The zabbix-server package.

@item @code{user} (default: @code{"zabbix"}) (type: string)
User who will run the Zabbix server.

@item @code{group} (default: @code{"zabbix"}) (type: string)
Group who will run the Zabbix server.

@item @code{db-host} (default: @code{"127.0.0.1"}) (type: string)
Database host name.

@item @code{db-name} (default: @code{"zabbix"}) (type: string)
Database name.

@item @code{db-user} (default: @code{"zabbix"}) (type: string)
Database user.

@item @code{db-password} (default: @code{""}) (type: string)
Database password.  Please, use @code{include-files} with
@code{DBPassword=SECRET} inside a specified file instead.

@item @code{db-port} (default: @code{5432}) (type: number)
Database port.

@item @code{log-type} (default: @code{""}) (type: string)
Specifies where log messages are written to:

@itemize @bullet

@item @code{system} - syslog.

@item @code{file} - file specified with @code{log-file} parameter.

@item @code{console} - standard output.

@end itemize

@item @code{log-file} (default: @code{"/var/log/zabbix/server.log"}) (type: string)
Log file name for @code{log-type} @code{file} parameter.

@item @code{pid-file} (default: @code{"/var/run/zabbix/zabbix_server.pid"}) (type: string)
Name of PID file.

@item @code{ssl-ca-location} (default: @code{"/etc/ssl/certs/ca-certificates.crt"}) (type: string)
The location of certificate authority (CA) files for SSL server certificate
verification.

@item @code{ssl-cert-location} (default: @code{"/etc/ssl/certs"}) (type: string)
Location of SSL client certificates.

@item @code{extra-options} (default: @code{""}) (type: extra-options)
Extra options will be appended to Zabbix server configuration file.

@item @code{include-files} (default: @code{'()}) (type: include-files)
You may include individual files or all files in a directory in the
configuration file.

@end table

@end deftp


@c %end of fragment

@anchor{zabbix-agent}
@subsubheading Zabbix agent
@cindex zabbix zabbix-agent

The Zabbix agent gathers information about the running system for the Zabbix
monitoring server.  It has a variety of built-in checks, and can be extended
with custom
@uref{https://www.zabbix.com/documentation/current/en/manual/config/items/userparameters,
@dfn{user parameters}}.

@defvar zabbix-agent-service-type
This is the service type for the Zabbix agent service.  Its value must be a
@code{zabbix-agent-configuration} record, shown below.
@end defvar

@c %start of fragment

@deftp {Tipo de dados} zabbix-agent-configuration
Available @code{zabbix-agent-configuration} fields are:

@table @asis
@item @code{zabbix-agent} (default: @code{zabbix-agentd}) (type: file-like)
The zabbix-agent package.

@item @code{user} (default: @code{"zabbix"}) (type: string)
User who will run the Zabbix agent.

@item @code{group} (default: @code{"zabbix"}) (type: string)
Group who will run the Zabbix agent.

@item @code{hostname} (default: @code{""}) (type: string)
Unique, case sensitive hostname which is required for active checks and must
match hostname as configured on the server.

@item @code{log-type} (default: @code{""}) (type: string)
Specifies where log messages are written to:

@itemize @bullet
@item
@code{system} - syslog.

@item @code{file} - file specified with
@code{log-file} parameter.

@item @code{console} - standard output.

@end itemize

@item @code{log-file} (default: @code{"/var/log/zabbix/agent.log"}) (type: string)
Log file name for @code{log-type} @code{file} parameter.

@item @code{pid-file} (default: @code{"/var/run/zabbix/zabbix_agent.pid"}) (type: string)
Name of PID file.

@item @code{server} (default: @code{'("127.0.0.1")}) (type: list)
List of IP addresses, optionally in CIDR notation, or hostnames of Zabbix
servers and Zabbix proxies.  Incoming connections will be accepted only from
the hosts listed here.

@item @code{server-active} (default: @code{'("127.0.0.1")}) (type: list)
List of IP:port (or hostname:port) pairs of Zabbix servers and Zabbix
proxies for active checks.  If port is not specified, default port is used.
If this parameter is not specified, active checks are disabled.

@item @code{extra-options} (default: @code{""}) (type: extra-options)
Extra options will be appended to Zabbix server configuration file.

@item @code{include-files} (default: @code{'()}) (type: include-files)
You may include individual files or all files in a directory in the
configuration file.

@end table

@end deftp


@c %end of fragment

@anchor{zabbix-front-end}
@subsubheading Zabbix front-end
@cindex zabbix zabbix-front-end

The Zabbix front-end provides a web interface to Zabbix.  It does not need
to run on the same machine as the Zabbix server.  This service works by
extending the @ref{PHP-FPM} and @ref{NGINX} services with the configuration
necessary for loading the Zabbix user interface.

@defvar zabbix-front-end-service-type
This is the service type for the Zabbix web frontend.  Its value must be a
@code{zabbix-front-end-configuration} record, shown below.
@end defvar

@c %start of fragment

@deftp {Tipo de dados} zabbix-front-end-configuration
Available @code{zabbix-front-end-configuration} fields are:

@table @asis
@item @code{zabbix-server} (default: @code{zabbix-server}) (type: file-like)
The Zabbix server package to use.

@item @code{nginx} (default: @code{'()}) (type: list)
List of @ref{nginx-server-configuration,@code{nginx-server-configuration}}
blocks for the Zabbix front-end.  When empty, a default that listens on port
80 is used.

@item @code{db-host} (default: @code{"localhost"}) (type: string)
Database host name.

@item @code{db-port} (default: @code{5432}) (type: number)
Database port.

@item @code{db-name} (default: @code{"zabbix"}) (type: string)
Database name.

@item @code{db-user} (default: @code{"zabbix"}) (type: string)
Database user.

@item @code{db-password} (default: @code{""}) (type: string)
Database password.  Please, use @code{db-secret-file} instead.

@item @code{db-secret-file} (default: @code{""}) (type: string)
Secret file which will be appended to @file{zabbix.conf.php} file.  This
file contains credentials for use by Zabbix front-end.  You are expected to
create it manually.

@item @code{zabbix-host} (default: @code{"localhost"}) (type: string)
Zabbix server hostname.

@item @code{zabbix-port} (default: @code{10051}) (type: number)
Zabbix server port.

@end table

@end deftp


@c %end of fragment

@node Serviços Kerberos
@subsection Serviços Kerberos
@cindex Kerberos

The @code{(gnu services kerberos)} module provides services relating to the
authentication protocol @dfn{Kerberos}.

@subsubheading Krb5 Service

Programs using a Kerberos client library normally expect a configuration
file in @file{/etc/krb5.conf}.  This service generates such a file from a
definition provided in the operating system declaration.  It does not cause
any daemon to be started.

No ``keytab'' files are provided by this service---you must explicitly
create them.  This service is known to work with the MIT client library,
@code{mit-krb5}.  Other implementations have not been tested.

@defvar krb5-service-type
A service type for Kerberos 5 clients.
@end defvar

@noindent
Here is an example of its use:
@lisp
(service krb5-service-type
         (krb5-configuration
          (default-realm "EXAMPLE.COM")
          (allow-weak-crypto? #t)
          (realms (list
                   (krb5-realm
                    (name "EXAMPLE.COM")
                    (admin-server "groucho.example.com")
                    (kdc "karl.example.com"))
                   (krb5-realm
                    (name "ARGRX.EDU")
                    (admin-server "kerb-admin.argrx.edu")
                    (kdc "keys.argrx.edu"))))))
@end lisp

@noindent
This example provides a Kerberos@tie{}5 client configuration which:
@itemize
@item Recognizes two realms, @i{viz:} ``EXAMPLE.COM'' and ``ARGRX.EDU'', both
of which have distinct administration servers and key distribution centers;
@item Will default to the realm ``EXAMPLE.COM'' if the realm is not explicitly
specified by clients;
@item Accepts services which only support encryption types known to be weak.
@end itemize

The @code{krb5-realm} and @code{krb5-configuration} types have many fields.
Only the most commonly used ones are described here.  For a full list, and
more detailed explanation of each, see the MIT
@uref{https://web.mit.edu/kerberos/krb5-devel/doc/admin/conf_files/krb5_conf.html,,krb5.conf}
documentation.


@deftp {Tipo de dados} 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 dados} krb5-configuration

@table @asis
@item @code{allow-weak-crypto?} (default: @code{#f})
If this flag is @code{#t} then services which only offer encryption
algorithms known to be weak will be accepted.

@item @code{default-realm} (default: @code{#f})
This field should be a string identifying the default Kerberos realm for the
client.  You should set this field to the name of your Kerberos realm.  If
this value is @code{#f} then a realm must be specified with every Kerberos
principal when invoking programs such as @command{kinit}.

@item @code{realms}
This should be a non-empty list of @code{krb5-realm} objects, which clients
may access.  Normally, one of them will have a @code{name} field matching
the @code{default-realm} field.
@end table
@end deftp


@subsubheading PAM krb5 Service
@cindex pam-krb5

The @code{pam-krb5} service allows for login authentication and password
management via Kerberos.  You will need this service if you want PAM enabled
applications to authenticate users using Kerberos.

@defvar pam-krb5-service-type
A service type for the Kerberos 5 PAM module.
@end defvar

@deftp {Tipo de dados} pam-krb5-configuration
Data type representing the configuration of the Kerberos 5 PAM module.  This
type has the following parameters:
@table @asis
@item @code{pam-krb5} (default: @code{pam-krb5})
The pam-krb5 package to use.

@item @code{minimum-uid} (default: @code{1000})
The smallest user ID for which Kerberos authentications should be
attempted.  Local accounts with lower values will silently fail to
authenticate.
@end table
@end deftp


@node Serviços LDAP
@subsection Serviços LDAP
@cindex LDAP

@subsubheading Authentication against LDAP with nslcd
@cindex nslcd, LDAP service

The @code{(gnu services authentication)} module provides the
@code{nslcd-service-type}, which can be used to authenticate against an LDAP
server.  In addition to configuring the service itself, you may want to add
@code{ldap} as a name service to the Name Service Switch. @xref{Name Service Switch} for detailed information.

Here is a simple operating system declaration with a default configuration
of the @code{nslcd-service-type} and a Name Service Switch configuration
that consults the @code{ldap} name service last:

@lisp
(use-service-modules authentication)
(use-modules (gnu system nss))
...
(operating-system
  ...
  (services
    (cons*
      (service nslcd-service-type)
      (service dhcp-client-service-type)
      %base-services))
  (name-service-switch
   (let ((services (list (name-service (name "db"))
                         (name-service (name "files"))
                         (name-service (name "ldap")))))
     (name-service-switch
      (inherit %mdns-host-lookup-nss)
      (password services)
      (shadow   services)
      (group    services)
      (netgroup services)
      (gshadow  services)))))
@end lisp

@c %start of generated documentation for nslcd-configuration

Available @code{nslcd-configuration} fields are:

@deftypevr {@code{nslcd-configuration} parameter} package nss-pam-ldapd
The @code{nss-pam-ldapd} package to use.

@end deftypevr

@deftypevr {@code{nslcd-configuration} parameter} maybe-number threads
The number of threads to start that can handle requests and perform LDAP
queries.  Each thread opens a separate connection to the LDAP server.  The
default is to start 5 threads.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{nslcd-configuration} parameter} string uid
This specifies the user id with which the daemon should be run.

Defaults to @samp{"nslcd"}.

@end deftypevr

@deftypevr {@code{nslcd-configuration} parameter} string gid
This specifies the group id with which the daemon should be run.

Defaults to @samp{"nslcd"}.

@end deftypevr

@deftypevr {@code{nslcd-configuration} parameter} log-option log
This option controls the way logging is done via a list containing SCHEME
and LEVEL@.  The SCHEME argument may either be the symbols @samp{none} or
@samp{syslog}, or an absolute file name.  The LEVEL argument is optional and
specifies the log level.  The log level may be one of the following symbols:
@samp{crit}, @samp{error}, @samp{warning}, @samp{notice}, @samp{info} or
@samp{debug}.  All messages with the specified log level or higher are
logged.

Defaults to @samp{'("/var/log/nslcd" info)}.

@end deftypevr

@deftypevr {@code{nslcd-configuration} parameter} list uri
The list of LDAP server URIs.  Normally, only the first server will be used
with the following servers as fall-back.

Defaults to @samp{'("ldap://localhost:389/")}.

@end deftypevr

@deftypevr {@code{nslcd-configuration} parameter} maybe-string ldap-version
The version of the LDAP protocol to use.  The default is to use the maximum
version supported by the LDAP library.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{nslcd-configuration} parameter} maybe-string binddn
Specifies the distinguished name with which to bind to the directory server
for lookups.  The default is to bind anonymously.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{nslcd-configuration} parameter} maybe-string bindpw
Specifies the credentials with which to bind.  This option is only
applicable when used with binddn.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{nslcd-configuration} parameter} maybe-string rootpwmoddn
Specifies the distinguished name to use when the root user tries to modify a
user's password using the PAM module.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{nslcd-configuration} parameter} maybe-string rootpwmodpw
Specifies the credentials with which to bind if the root user tries to
change a user's password.  This option is only applicable when used with
rootpwmoddn

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{nslcd-configuration} parameter} maybe-string sasl-mech
Specifies the SASL mechanism to be used when performing SASL authentication.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{nslcd-configuration} parameter} maybe-string sasl-realm
Specifies the SASL realm to be used when performing SASL authentication.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{nslcd-configuration} parameter} maybe-string sasl-authcid
Specifies the authentication identity to be used when performing SASL
authentication.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{nslcd-configuration} parameter} maybe-string sasl-authzid
Specifies the authorization identity to be used when performing SASL
authentication.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean sasl-canonicalize?
Determines whether the LDAP server host name should be canonicalised.  If
this is enabled the LDAP library will do a reverse host name lookup.  By
default, it is left up to the LDAP library whether this check is performed
or not.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{nslcd-configuration} parameter} maybe-string krb5-ccname
Set the name for the GSS-API Kerberos credentials cache.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{nslcd-configuration} parameter} string base
The directory search base.

Defaults to @samp{"dc=example,dc=com"}.

@end deftypevr

@deftypevr {@code{nslcd-configuration} parameter} scope-option scope
Specifies the search scope (subtree, onelevel, base or children).  The
default scope is subtree; base scope is almost never useful for name service
lookups; children scope is not supported on all servers.

Defaults to @samp{'(subtree)}.

@end deftypevr

@deftypevr {@code{nslcd-configuration} parameter} maybe-deref-option deref
Specifies the policy for dereferencing aliases.  The default policy is to
never dereference aliases.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean referrals
Specifies whether automatic referral chasing should be enabled.  The default
behaviour is to chase referrals.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{nslcd-configuration} parameter} list-of-map-entries maps
This option allows for custom attributes to be looked up instead of the
default RFC 2307 attributes.  It is a list of maps, each consisting of the
name of a map, the RFC 2307 attribute to match and the query expression for
the attribute as it is available in the directory.

Defaults to @samp{'()}.

@end deftypevr

@deftypevr {@code{nslcd-configuration} parameter} list-of-filter-entries filters
A list of filters consisting of the name of a map to which the filter
applies and an LDAP search filter expression.

Defaults to @samp{'()}.

@end deftypevr

@deftypevr {@code{nslcd-configuration} parameter} maybe-number bind-timelimit
Specifies the time limit in seconds to use when connecting to the directory
server.  The default value is 10 seconds.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{nslcd-configuration} parameter} maybe-number timelimit
Specifies the time limit (in seconds) to wait for a response from the LDAP
server.  A value of zero, which is the default, is to wait indefinitely for
searches to be completed.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{nslcd-configuration} parameter} maybe-number idle-timelimit
Specifies the period if inactivity (in seconds) after which the con‐ nection
to the LDAP server will be closed.  The default is not to time out
connections.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{nslcd-configuration} parameter} maybe-number reconnect-sleeptime
Specifies the number of seconds to sleep when connecting to all LDAP servers
fails.  By default one second is waited between the first failure and the
first retry.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{nslcd-configuration} parameter} maybe-number reconnect-retrytime
Specifies the time after which the LDAP server is considered to be
permanently unavailable.  Once this time is reached retries will be done
only once per this time period.  The default value is 10 seconds.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{nslcd-configuration} parameter} maybe-ssl-option ssl
Specifies whether to use SSL/TLS or not (the default is not to).  If
'start-tls is specified then StartTLS is used rather than raw LDAP over SSL.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{nslcd-configuration} parameter} maybe-tls-reqcert-option tls-reqcert
Specifies what checks to perform on a server-supplied certificate.  The
meaning of the values is described in the ldap.conf(5) manual page.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-cacertdir
Specifies the directory containing X.509 certificates for peer authen‐
tication.  This parameter is ignored when using GnuTLS.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-cacertfile
Specifies the path to the X.509 certificate for peer authentication.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-randfile
Specifies the path to an entropy source.  This parameter is ignored when
using GnuTLS.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-ciphers
Specifies the ciphers to use for TLS as a string.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-cert
Specifies the path to the file containing the local certificate for client
TLS authentication.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-key
Specifies the path to the file containing the private key for client TLS
authentication.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{nslcd-configuration} parameter} maybe-number pagesize
Set this to a number greater than 0 to request paged results from the LDAP
server in accordance with RFC2696.  The default (0) is to not request paged
results.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{nslcd-configuration} parameter} maybe-ignore-users-option nss-initgroups-ignoreusers
This option prevents group membership lookups through LDAP for the specified
users.  Alternatively, the value 'all-local may be used.  With that value
nslcd builds a full list of non-LDAP users on startup.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{nslcd-configuration} parameter} maybe-number nss-min-uid
This option ensures that LDAP users with a numeric user id lower than the
specified value are ignored.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{nslcd-configuration} parameter} maybe-number nss-uid-offset
This option specifies an offset that is added to all LDAP numeric user ids.
This can be used to avoid user id collisions with local users.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{nslcd-configuration} parameter} maybe-number nss-gid-offset
This option specifies an offset that is added to all LDAP numeric group
ids.  This can be used to avoid user id collisions with local groups.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean nss-nested-groups
If this option is set, the member attribute of a group may point to another
group.  Members of nested groups are also returned in the higher level group
and parent groups are returned when finding groups for a specific user.  The
default is not to perform extra searches for nested groups.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean nss-getgrent-skipmembers
If this option is set, the group member list is not retrieved when looking
up groups.  Lookups for finding which groups a user belongs to will remain
functional so the user will likely still get the correct groups assigned on
login.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean nss-disable-enumeration
If this option is set, functions which cause all user/group entries to be
loaded from the directory will not succeed in doing so.  This can
dramatically reduce LDAP server load in situations where there are a great
number of users and/or groups.  This option is not recommended for most
configurations.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{nslcd-configuration} parameter} maybe-string validnames
This option can be used to specify how user and group names are verified
within the system.  This pattern is used to check all user and group names
that are requested and returned from LDAP.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean ignorecase
This specifies whether or not to perform searches using case-insensitive
matching.  Enabling this could open up the system to authorization bypass
vulnerabilities and introduce nscd cache poisoning vulnerabilities which
allow denial of service.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean pam-authc-ppolicy
This option specifies whether password policy controls are requested and
handled from the LDAP server when performing user authentication.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{nslcd-configuration} parameter} maybe-string pam-authc-search
By default nslcd performs an LDAP search with the user's credentials after
BIND (authentication) to ensure that the BIND operation was successful.  The
default search is a simple check to see if the user's DN exists.  A search
filter can be specified that will be used instead.  It should return at
least one entry.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{nslcd-configuration} parameter} maybe-string pam-authz-search
This option allows flexible fine tuning of the authorisation check that
should be performed.  The search filter specified is executed and if any
entries match, access is granted, otherwise access is denied.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{nslcd-configuration} parameter} maybe-string pam-password-prohibit-message
If this option is set password modification using pam_ldap will be denied
and the specified message will be presented to the user instead.  The
message can be used to direct the user to an alternative means of changing
their password.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{nslcd-configuration} parameter} list pam-services
List of pam service names for which LDAP authentication should suffice.

Defaults to @samp{'()}.

@end deftypevr

@c %end of generated documentation for nslcd-configuration


@subsubheading LDAP Directory Server
@cindex LDAP, server

The @code{(gnu services ldap)} module provides the
@code{directory-server-service-type}, which can be used to create and launch
an LDAP server instance.

Here is an example configuration of the
@code{directory-server-service-type}:

@lisp
(use-service-modules ldap)

...
(operating-system
  ...
  (services
    (cons
      (service directory-server-service-type
               (directory-server-instance-configuration
                (slapd
                 (slapd-configuration
                  (root-password "@{PBKDF2_SHA256@}AAAgAG@dots{}ABSOLUTELYSECRET")))))
      %base-services)))
@end lisp

The root password should be generated with the @command{pwdhash} utility
that is provided by the @code{389-ds-base} package.

Note that changes to the directory server configuration will not be applied
to existing instances.  You will need to back up and restore server data
manually.  Only new directory server instances will be created upon system
reconfiguration.

@c %start of generated documentation for directory-server-instance-configuration
@deftp {Tipo de dados} directory-server-instance-configuration
Available @code{directory-server-instance-configuration} fields are:

@table @asis
@item @code{package} (default: @code{389-ds-base}) (type: file-like)
The @code{389-ds-base} package.

@item @code{config-version} (default: @code{2}) (type: number)
Sets the format version of the configuration file.  To use the INF file with
@command{dscreate}, this parameter must be 2.

@item @code{full-machine-name} (default: @code{"localhost"}) (type: string)
Sets the fully qualified hostname (FQDN) of this system.

@item @code{selinux} (default: @code{#false}) (type: boolean)
Enables SELinux detection and integration during the installation of this
instance.  If set to @code{#true}, @command{dscreate} auto-detects whether
SELinux is enabled.

@item @code{strict-host-checking} (default: @code{#true}) (type: boolean)
Sets whether the server verifies the forward and reverse record set in the
@code{full-machine-name} parameter.  When installing this instance with
GSSAPI authentication behind a load balancer, set this parameter to
@code{#false}.

@item @code{systemd} (default: @code{#false}) (type: boolean)
Enables systemd platform features.  If set to @code{#true},
@command{dscreate} auto-detects whether systemd is installed.

@item @code{slapd} (type: slapd-configuration)
Configuration of slapd.

@deftp {Tipo de dados} slapd-configuration
Available @code{slapd-configuration} fields are:

@table @asis
@item @code{instance-name} (default: @code{"localhost"}) (type: string)
Sets the name of the instance.  You can refer to this value in other
parameters of this INF file using the @code{@{instance_name@}} variable.
Note that this name cannot be changed after the installation!

@item @code{user} (default: @code{"dirsrv"}) (type: string)
Sets the user name the ns-slapd process will use after the service started.

@item @code{group} (default: @code{"dirsrv"}) (type: string)
Sets the group name the ns-slapd process will use after the service started.

@item @code{port} (default: @code{389}) (type: number)
Sets the TCP port the instance uses for LDAP connections.

@item @code{secure-port} (default: @code{636}) (type: number)
Sets the TCP port the instance uses for TLS-secured LDAP connections
(LDAPS).

@item @code{root-dn} (default: @code{"cn=Directory Manager"}) (type: string)
Sets the @dfn{Distinquished Name} (DN) of the administrator account for this
instance.

@item @code{root-password} (default: @code{"@{invalid@}YOU-SHOULD-CHANGE-THIS"}) (type: string)
Sets the password of the account specified in the @code{root-dn} parameter.
You can either set this parameter to a plain text password
@command{dscreate} hashes during the installation or to a
"@{algorithm@}hash" string generated by the @command{pwdhash} utility.  Note
that setting a plain text password can be a security risk if unprivileged
users can read this INF file!

@item @code{self-sign-cert} (default: @code{#true}) (type: boolean)
Sets whether the setup creates a self-signed certificate and enables TLS
encryption during the installation.  This is not suitable for production,
but it enables administrators to use TLS right after the installation.  You
can replace the self-signed certificate with a certificate issued by a
certificate authority.

@item @code{self-sign-cert-valid-months} (default: @code{24}) (type: number)
Set the number of months the issued self-signed certificate will be valid.

@item @code{backup-dir} (default: @code{"/var/lib/dirsrv/slapd-@{instance_name@}/bak"}) (type: string)
Set the backup directory of the instance.

@item @code{cert-dir} (default: @code{"/etc/dirsrv/slapd-@{instance_name@}"}) (type: string)
Sets the directory of the instance's Network Security Services (NSS)
database.

@item @code{config-dir} (default: @code{"/etc/dirsrv/slapd-@{instance_name@}"}) (type: string)
Sets the configuration directory of the instance.

@item @code{db-dir} (default: @code{"/var/lib/dirsrv/slapd-@{instance_name@}/db"}) (type: string)
Sets the database directory of the instance.

@item @code{initconfig-dir} (default: @code{"/etc/dirsrv/registry"}) (type: string)
Sets the directory of the operating system's rc configuration directory.

@item @code{ldif-dir} (default: @code{"/var/lib/dirsrv/slapd-@{instance_name@}/ldif"}) (type: string)
Sets the LDIF export and import directory of the instance.

@item @code{lock-dir} (default: @code{"/var/lock/dirsrv/slapd-@{instance_name@}"}) (type: string)
Sets the lock directory of the instance.

@item @code{log-dir} (default: @code{"/var/log/dirsrv/slapd-@{instance_name@}"}) (type: string)
Sets the log directory of the instance.

@item @code{run-dir} (default: @code{"/run/dirsrv"}) (type: string)
Sets PID directory of the instance.

@item @code{schema-dir} (default: @code{"/etc/dirsrv/slapd-@{instance_name@}/schema"}) (type: string)
Sets schema directory of the instance.

@item @code{tmp-dir} (default: @code{"/tmp"}) (type: string)
Sets the temporary directory of the instance.
@end table
@end deftp

@item @code{backend-userroot} (type: backend-userroot-configuration)
Configuration of the userroot backend.

@deftp {Tipo de dados} backend-userroot-configuration
Available @code{backend-userroot-configuration} fields are:

@table @asis
@item @code{create-suffix-entry?} (default: @code{#false}) (type: boolean)
Set this parameter to @code{#true} to create a generic root node entry for
the suffix in the database.

@item @code{require-index?} (default: @code{#false}) (type: boolean)
Set this parameter to @code{#true} to refuse unindexed searches in this
database.

@item @code{sample-entries} (default: @code{"no"}) (type: string)
Set this parameter to @code{"yes"} to add latest version of sample entries
to this database.  Or, use @code{"001003006"} to use the 1.3.6 version
sample entries.  Use this option, for example, to create a database for
testing purposes.

@item @code{suffix} (type: maybe-string)
Sets the root suffix stored in this database.  If you do not set the suffix
attribute the install process will not create the backend/suffix.  You can
also create multiple backends/suffixes by duplicating this section.

@end table
@end deftp
@end table
@end deftp
@c end of generated documentation for directory-server

@node Serviços web
@subsection Serviços web

@cindex web
@cindex www
@cindex HTTP
The @code{(gnu services web)} module provides the Apache HTTP Server, the
nginx web server, and also a fastcgi wrapper daemon.

@subsubheading Apache HTTP Server

@defvar httpd-service-type
Service type for the @uref{https://httpd.apache.org/,Apache HTTP} server
(@dfn{httpd}).  The value for this service type is a
@code{httpd-configuration} record.

A simple example configuration is given below.

@lisp
(service httpd-service-type
         (httpd-configuration
           (config
             (httpd-config-file
               (server-name "www.example.com")
               (document-root "/srv/http/www.example.com")))))
@end lisp

Other services can also extend the @code{httpd-service-type} to add to the
configuration.

@lisp
(simple-service 'www.example.com-server httpd-service-type
                (list
                  (httpd-virtualhost
                    "*:80"
                    (list (string-join '("ServerName www.example.com"
                                         "DocumentRoot /srv/http/www.example.com")
                                       "\n")))))
@end lisp
@end defvar

The details for the @code{httpd-configuration}, @code{httpd-module},
@code{httpd-config-file} and @code{httpd-virtualhost} record types are given
below.

@deftp {Tipo de dados} httpd-configuration
This data type represents the configuration for the httpd service.

@table @asis
@item @code{package} (default: @code{httpd})
The httpd package to use.

@item @code{pid-file} (default: @code{"/var/run/httpd"})
The pid file used by the shepherd-service.

@item @code{config} (default: @code{(httpd-config-file)})
The configuration file to use with the httpd service.  The default value is
a @code{httpd-config-file} record, but this can also be a different
G-expression that generates a file, for example a @code{plain-file}.  A file
outside of the store can also be specified through a string.

@end table
@end deftp

@deftp {Tipo de dados} httpd-module
This data type represents a module for the httpd service.

@table @asis
@item @code{name}
The name of the module.

@item @code{file}
The file for the module.  This can be relative to the httpd package being
used, the absolute location of a file, or a G-expression for a file within
the store, for example @code{(file-append mod-wsgi "/modules/mod_wsgi.so")}.

@end table
@end deftp

@defvar %default-httpd-modules
A default list of @code{httpd-module} objects.
@end defvar

@deftp {Tipo de dados} httpd-config-file
This data type represents a configuration file for the httpd service.

@table @asis
@item @code{modules} (default: @code{%default-httpd-modules})
The modules to load.  Additional modules can be added here, or loaded by
additional configuration.

For example, in order to handle requests for PHP files, you can use Apache’s
@code{mod_proxy_fcgi} module along with @code{php-fpm-service-type}:

@lisp
(service httpd-service-type
         (httpd-configuration
          (config
           (httpd-config-file
            (modules (cons*
                      (httpd-module
                       (name "proxy_module")
                       (file "modules/mod_proxy.so"))
                      (httpd-module
                       (name "proxy_fcgi_module")
                       (file "modules/mod_proxy_fcgi.so"))
                      %default-httpd-modules))
            (extra-config (list "\
<FilesMatch \\.php$>
    SetHandler \"proxy:unix:/var/run/php-fpm.sock|fcgi://localhost/\"
</FilesMatch>"))))))
(service php-fpm-service-type
         (php-fpm-configuration
          (socket "/var/run/php-fpm.sock")
          (socket-group "httpd")))
@end lisp

@item @code{server-root} (default: @code{httpd})
The @code{ServerRoot} in the configuration file, defaults to the httpd
package.  Directives including @code{Include} and @code{LoadModule} are
taken as relative to the server root.

@item @code{server-name} (default: @code{#f})
The @code{ServerName} in the configuration file, used to specify the request
scheme, hostname and port that the server uses to identify itself.

This doesn't need to be set in the server config, and can be specified in
virtual hosts.  The default is @code{#f} to not specify a @code{ServerName}.

@item @code{document-root} (default: @code{"/srv/http"})
The @code{DocumentRoot} from which files will be served.

@item @code{listen} (default: @code{'("80")})
The list of values for the @code{Listen} directives in the config file.  The
value should be a list of strings, when each string can specify the port
number to listen on, and optionally the IP address and protocol to use.

@item @code{pid-file} (default: @code{"/var/run/httpd"})
The @code{PidFile} to use.  This should match the @code{pid-file} set in the
@code{httpd-configuration} so that the Shepherd service is configured
correctly.

@item @code{error-log} (default: @code{"/var/log/httpd/error_log"})
The @code{ErrorLog} to which the server will log errors.

@item @code{user} (default: @code{"httpd"})
The @code{User} which the server will answer requests as.

@item @code{group} (default: @code{"httpd"})
The @code{Group} which the server will answer requests as.

@item @code{extra-config} (default: @code{(list "TypesConfig etc/httpd/mime.types")})
A flat list of strings and G-expressions which will be added to the end of
the configuration file.

Any values which the service is extended with will be appended to this list.

@end table
@end deftp

@deftp {Tipo de dados} httpd-virtualhost
This data type represents a virtualhost configuration block for the httpd
service.

These should be added to the extra-config for the httpd-service.

@lisp
(simple-service 'www.example.com-server httpd-service-type
                (list
                  (httpd-virtualhost
                    "*:80"
                    (list (string-join '("ServerName www.example.com"
                                          "DocumentRoot /srv/http/www.example.com")
                                       "\n")))))
@end lisp

@table @asis
@item @code{addresses-and-ports}
The addresses and ports for the @code{VirtualHost} directive.

@item @code{contents}
The contents of the @code{VirtualHost} directive, this should be a list of
strings and G-expressions.

@end table
@end deftp

@anchor{NGINX}
@subsubheading NGINX

@defvar nginx-service-type
Service type for the @uref{https://nginx.org/,NGinx} web server.  The value
for this service type is a @code{<nginx-configuration>} record.

A simple example configuration is given below.

@lisp
(service nginx-service-type
         (nginx-configuration
           (server-blocks
             (list (nginx-server-configuration
                     (server-name '("www.example.com"))
                     (root "/srv/http/www.example.com"))))))
@end lisp

In addition to adding server blocks to the service configuration directly,
this service can be extended by other services to add server blocks, as in
this example:

@lisp
(simple-service 'my-extra-server nginx-service-type
                (list (nginx-server-configuration
                        (root "/srv/http/extra-website")
                        (try-files (list "$uri" "$uri/index.html")))))
@end lisp
@end defvar

At startup, @command{nginx} has not yet read its configuration file, so it
uses a default file to log error messages.  If it fails to load its
configuration file, that is where error messages are logged.  After the
configuration file is loaded, the default error log file changes as per
configuration.  In our case, startup error messages can be found in
@file{/var/run/nginx/logs/error.log}, and after configuration in
@file{/var/log/nginx/error.log}.  The second location can be changed with
the @var{log-directory} configuration option.

@deftp {Tipo de dados} nginx-configuration
This data type represents the configuration for NGinx.  Some configuration
can be done through this and the other provided record types, or
alternatively, a config file can be provided.

@table @asis
@item @code{nginx} (default: @code{nginx})
The nginx package to use.

@item @code{shepherd-requirement} (default: @code{'()})
This is a list of symbols naming Shepherd services the nginx service will
depend on.

This is useful if you would like @command{nginx} to be started after a
back-end web server or a logging service such as Anonip has been started.

@item @code{log-directory} (default: @code{"/var/log/nginx"})
The directory to which NGinx will write log files.

@item @code{log-format} (default: @code{'combined}) (type: symbol)
Logging format for the access log. Nginx defaults to the httpd-like format
named @code{'combined}.  Other formats can be defined using
@code{log-formats}.

@item @code{log-formats} (default: @code{'()})
A list of additional @dfn{log formats} to define, the elements should be of
type @code{<nginx-log-format-configuration>}.

@item @code{log-level} (default: @code{'error}) (type: symbol)
Logging level for the error log, which can be any of the following values:
@code{'debug}, @code{'info}, @code{'notice}, @code{'warn}, @code{'error},
@code{'crit}, @code{'alert}, or @code{'emerg}.

@item @code{run-directory} (default: @code{"/var/run/nginx"})
The directory in which NGinx will create a pid file, and write temporary
files.

@item @code{server-blocks} (default: @code{'()})
A list of @dfn{server blocks} to create in the generated configuration file,
the elements should be of type @code{<nginx-server-configuration>}.

The following example would setup NGinx to serve @code{www.example.com} from
the @code{/srv/http/www.example.com} directory, without using HTTPS.
@lisp
(service nginx-service-type
         (nginx-configuration
           (server-blocks
             (list (nginx-server-configuration
                     (server-name '("www.example.com"))
                     (root "/srv/http/www.example.com"))))))
@end lisp

@item @code{upstream-blocks} (default: @code{'()})
A list of @dfn{upstream blocks} to create in the generated configuration
file, the elements should be of type @code{<nginx-upstream-configuration>}.

Configuring upstreams through the @code{upstream-blocks} can be useful when
combined with @code{locations} in the @code{<nginx-server-configuration>}
records.  The following example creates a server configuration with one
location configuration, that will proxy requests to a upstream
configuration, which will handle requests with two servers.

@lisp
(service
  nginx-service-type
  (nginx-configuration
    (server-blocks
      (list (nginx-server-configuration
              (server-name '("www.example.com"))
              (root "/srv/http/www.example.com")
              (locations
                (list
                  (nginx-location-configuration
                  (uri "/path1")
                  (body '("proxy_pass http://server-proxy;"))))))))
    (upstream-blocks
      (list (nginx-upstream-configuration
              (name "server-proxy")
              (servers (list "server1.example.com"
                             "server2.example.com")))))))
@end lisp

@item @code{file} (padrão: @code{#f})
If a configuration @var{file} is provided, this will be used, rather than
generating a configuration file from the provided @code{log-directory},
@code{run-directory}, @code{server-blocks} and @code{upstream-blocks}.  For
proper operation, these arguments should match what is in @var{file} to
ensure that the directories are created when the service is activated.

This can be useful if you have an existing configuration file, or it's not
possible to do what is required through the other parts of the
nginx-configuration record.

@item @code{server-names-hash-bucket-size} (default: @code{#f})
Bucket size for the server names hash tables, defaults to @code{#f} to use
the size of the processors cache line.

@item @code{server-names-hash-bucket-max-size} (default: @code{#f})
Maximum bucket size for the server names hash tables.

@item @code{stream} (default: @code{#f})
@code{<nginx-stream-configuration>} object describing stream server
directives.

@item @code{modules} (padrão: @code{'()})
List of nginx dynamic modules to load.  This should be a list of file names
of loadable modules, as in this example:

@lisp
(modules
 (list
  (file-append nginx-accept-language-module "\
/etc/nginx/modules/ngx_http_accept_language_module.so")
  (file-append nginx-lua-module "\
/etc/nginx/modules/ngx_http_lua_module.so")))
@end lisp

@item @code{lua-package-path} (default: @code{'()})
List of nginx lua packages to load.  This should be a list of package names
of loadable lua modules, as in this example:

@lisp
(lua-package-path (list lua-resty-core
                        lua-resty-lrucache
                        lua-resty-signal
                        lua-tablepool
                        lua-resty-shell))
@end lisp

@item @code{lua-package-cpath} (default: @code{'()})
List of nginx lua C packages to load.  This should be a list of package
names of loadable lua C modules, as in this example:

@lisp
(lua-package-cpath (list lua-resty-signal))
@end lisp

@item @code{global-directives} (default: @code{'((events . ()))})
Association list of global directives for the top level of the nginx
configuration.  Values may themselves be association lists.

@lisp
(global-directives
 `((worker_processes . 16)
   (pcre_jit . on)
   (events . ((worker_connections . 1024)))))
@end lisp

@item @code{extra-content} (default: @code{""})
Additional content to be appended to the @code{http} block.  Can either be a
value that can be lowered into a string or a list of such values.  In the
former case, it is inserted directly.  In the latter, it is prefixed with
indentation and suffixed with a newline.  Nested lists are flattened into
one line.

@lisp
(extra-content "include /etc/nginx/custom-config.conf;")
(extra-content `("include /etc/nginx/custom-config.conf;"
                 ("include " ,%custom-config.conf ";")))
@end lisp

@end table
@end deftp

@deftp {Data Type} nginx-log-format-configuration
Data type representing the configuration of a custom Nginx log format.  This
type has the following parameters:

@table @asis
@item @code{name} (type: symbol)
The name of the log format as a symbol.

@item @code{escape} (default: @code{'default}) (type: symbol)
The mode used to escape values of variables in the format.  The supported
values are:

@itemize
@item @code{'default}, to escape all characters outside of the ASCII
      printable range.
@item @code{'json}, to escape all characters invalid in JSON strings.
@item @code{'none}, to disable escaping.
@end itemize

@item @code{format} (type: string)
The format as accepted by the @code{log_format} directive.

@end table
@end deftp

@anchor{nginx-server-configuration}
@deftp {Tipo de dados} nginx-server-configuration
Data type representing the configuration of an nginx server block.  This
type has the following parameters:

@table @asis
@item @code{listen} (default: @code{'("80" "443 ssl")})
Each @code{listen} directive sets the address and port for IP, or the path
for a UNIX-domain socket on which the server will accept requests.  Both
address and port, or only address or only port can be specified.  An address
may also be a hostname, for example:

@lisp
'("127.0.0.1:8000" "127.0.0.1" "8000" "*:8000" "localhost:8000")
@end lisp

@item @code{server-name} (default: @code{(list 'default)})
A list of server names this server represents. @code{'default} represents
the default server for connections matching no other server.

@item @code{root} (default: @code{"/srv/http"})
Root of the website nginx will serve.

@item @code{locations} (default: @code{'()})
A list of @dfn{nginx-location-configuration} or
@dfn{nginx-named-location-configuration} records to use within this server
block.

@item @code{index} (default: @code{(list "index.html")})
Index files to look for when clients ask for a directory.  If it cannot be
found, Nginx will send the list of files in the directory.

@item @code{try-files} (default: @code{'()})
A list of files whose existence is checked in the specified order.
@code{nginx} will use the first file it finds to process the request.

@item @code{ssl-certificate} (default: @code{#f})
Where to find the certificate for secure connections.  Set it to @code{#f}
if you don't have a certificate or you don't want to use HTTPS.

@item @code{ssl-certificate-key} (default: @code{#f})
Where to find the private key for secure connections.  Set it to @code{#f}
if you don't have a key or you don't want to use HTTPS.

@item @code{server-tokens?} (default: @code{#f})
Whether the server should add its configuration to response.

@item @code{raw-content} (default: @code{'()})
A list of strings or file-like objects to be appended to the server block.
Each item is prefixed with indentation and suffixed with a new line.  Nested
lists are flattened.

@end table
@end deftp

@deftp {Tipo de dados} nginx-upstream-configuration
Data type representing the configuration of an nginx @code{upstream} block.
This type has the following parameters:

@table @asis
@item @code{name}
Name for this group of servers.

@item @code{servers}
Specify the addresses of the servers in the group.  The address can be
specified as a IP address (e.g.@: @samp{127.0.0.1}), domain name (e.g.@:
@samp{backend1.example.com}) or a path to a UNIX socket using the prefix
@samp{unix:}.  For addresses using an IP address or domain name, the default
port is 80, and a different port can be specified explicitly.

@item @code{extra-content}
Additional content to be appended to the upstream block.  Can be a string or
file-like object or list of thereof.  In case of list, each item is prefixed
with indentation and suffixed with a new line.  Nested lists are flattened.

@lisp
(extra-content "include /etc/nginx/custom-config.conf;")
(extra-content `("include /etc/nginx/custom-config.conf;"
                 ("include " ,%custom-config.conf ";")))
@end lisp

@end table
@end deftp

@deftp {Tipo de dados} 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 or file-like
objects.  Each item is prefixed with indentation and suffixed with a new
line.  Nested lists are flattened.

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 dados} 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

@deftp {Data Type} nginx-stream-configuration
Data type representing the configuration file context in which stream
directives are specified.  This type has the following parameters:

@table @asis
@item @code{upstream-blocks} (default: @code{'()})
A list of upstream blocks to create in the generated configuration file, the
elements should be of type @code{<nginx-upstream-configuration>}.

@item @code{server-blocks} (default: @code{'()})
A list of server blocks to create in the generated configuration file, the
elements should be of type @code{<nginx-server-configuration>}.

@item @code{extra-content} (default: @code{'()})
Additional content to be appended to the @code{stream} block.  Can either be
a value that can be lowered into a string or a list of such values.  In the
former case, it is inserted directly.  In the latter, it is prefixed with
indentation and suffixed with a newline.  Nested lists are flattened into
one line.

@end table
@end deftp

@subsubheading Varnish Cache
@cindex Varnish
Varnish is a fast cache server that sits in between web applications and end
users.  It proxies requests from clients and caches the accessed URLs such
that multiple requests for the same resource only creates one request to the
back-end.

@defvar varnish-service-type
Service type for the Varnish daemon.
@end defvar

@deftp {Tipo de dados} varnish-configuration
Data type representing the @code{varnish} service configuration.  This type
has the following parameters:

@table @asis
@item @code{package} (default: @code{varnish})
The Varnish package to use.

@item @code{name} (default: @code{"default"})
A name for this Varnish instance.  Varnish will create a directory in
@file{/var/varnish/} with this name and keep temporary files there.  If the
name starts with a forward slash, it is interpreted as an absolute directory
name.

Pass the @code{-n} argument to other Varnish programs to connect to the
named instance, e.g.@: @command{varnishncsa -n default}.

@item @code{backend} (default: @code{"localhost:8080"})
The backend to use.  This option has no effect if @code{vcl} is set.

@item @code{vcl} (default: #f)
The @dfn{VCL} (Varnish Configuration Language) program to run.  If this is
@code{#f}, Varnish will proxy @code{backend} using the default
configuration.  Otherwise this must be a file-like object with valid VCL
syntax.

@c Varnish does not support HTTPS, so keep this URL to avoid confusion.
For example, to mirror @url{https://www.gnu.org,www.gnu.org} with VCL you
can do something along these lines:

@lisp
(define %gnu-mirror
  (plain-file "gnu.vcl"
              "vcl 4.1;
backend gnu @{ .host = \"www.gnu.org\"; @}"))

(operating-system
  ;; @dots{}
  (services (cons (service varnish-service-type
                           (varnish-configuration
                            (listen '(":80"))
                            (vcl %gnu-mirror)))
                  %base-services)))
@end lisp

The configuration of an already running Varnish instance can be inspected
and changed using the @command{varnishadm} program.

Consult the @url{https://varnish-cache.org/docs/,Varnish User Guide} and
@url{https://book.varnish-software.com/4.0/,Varnish Book} for comprehensive
documentation on Varnish and its configuration language.

@item @code{listen} (default: @code{'("localhost:80")})
List of addresses Varnish will listen on.

@item @code{storage} (default: @code{'("malloc,128m")})
List of storage backends that will be available in VCL.

@item @code{parameters} (default: @code{'()})
List of run-time parameters in the form @code{'(("parameter" . "value"))}.

@item @code{extra-options} (default: @code{'()})
Additional arguments to pass to the @command{varnishd} process.

@end table
@end deftp

@subheading Whoogle Search
@cindex Whoogle Search

@uref{https://github.com/benbusby/whoogle-search, Whoogle Search} is a
self-hosted, ad-free, privacy-respecting meta search engine that collects
and displays Google search results.  By default, you can configure it by
adding this line to the @code{services} field of your operating system
declaration:

@lisp
(service whoogle-service-type)
@end lisp

As a result, Whoogle Search runs as local Web server, which you can access
by opening @indicateurl{http://localhost:5000} in your browser.  The
configuration reference is given below.

@defvar whoogle-service-type
Service type for Whoogle Search.  Its value must be a
@code{whoogle-configuration} record---see below.
@end defvar

@deftp {Tipo de dados} whoogle-configuration
Data type representing Whoogle Search service configuration.

@table @asis
@item @code{package} (default: @code{whoogle-search})
The Whoogle Search package to use.

@item @code{host} (default: @code{"127.0.0.1"})
The host address to run Whoogle on.

@item @code{port} (padrão: @code{5000})
The port where Whoogle will be exposed.

@item @code{environment-variables} (default: @code{'()})
A list of strings with the environment variables to configure Whoogle.  You
can consult
@uref{https://github.com/benbusby/whoogle-search/blob/main/whoogle.template.env,
its environment variables template} for the list of available options.

@end table
@end deftp

@subsubheading Patchwork
@cindex Patchwork
Patchwork is a patch tracking system.  It can collect patches sent to a
mailing list, and display them in a web interface.

@defvar patchwork-service-type
Service type for Patchwork.
@end defvar

The following example is an example of a minimal service for Patchwork, for
the @code{patchwork.example.com} domain.

@lisp
(service patchwork-service-type
         (patchwork-configuration
          (domain "patchwork.example.com")
          (settings-module
           (patchwork-settings-module
            (allowed-hosts (list domain))
            (default-from-email "patchwork@@patchwork.example.com")))
          (getmail-retriever-config
           (getmail-retriever-configuration
            (type "SimpleIMAPSSLRetriever")
            (server "imap.example.com")
            (port 993)
            (username "patchwork")
            (password-command
             (list (file-append coreutils "/bin/cat")
                   "/etc/getmail-patchwork-imap-password"))
            (extra-parameters
            '((mailboxes . ("Patches"))))))))

@end lisp

There are three records for configuring the Patchwork service.  The
@code{<patchwork-configuration>} relates to the configuration for Patchwork
within the HTTPD service.

The @code{settings-module} field within the @code{<patchwork-configuration>}
record can be populated with the @code{<patchwork-settings-module>} record,
which describes a settings module that is generated within the Guix store.

For the @code{database-configuration} field within the
@code{<patchwork-settings-module>}, the
@code{<patchwork-database-configuration>} must be used.

@deftp {Tipo de dados} patchwork-configuration
Data type representing the Patchwork service configuration.  This type has
the following parameters:

@table @asis
@item @code{patchwork} (default: @code{patchwork})
The Patchwork package to use.

@item @code{domain}
The domain to use for Patchwork, this is used in the HTTPD service virtual
host.

@item @code{settings-module}
The settings module to use for Patchwork.  As a Django application,
Patchwork is configured with a Python module containing the settings.  This
can either be an instance of the @code{<patchwork-settings-module>} record,
any other record that represents the settings in the store, or a directory
outside of the store.

@item @code{static-path}  (default: @code{"/static/"})
The path under which the HTTPD service should serve the static files.

@item @code{getmail-retriever-config}
The getmail-retriever-configuration record value to use with Patchwork.
Getmail will be configured with this value, the messages will be delivered
to Patchwork.

@end table
@end deftp

@deftp {Tipo de dados} patchwork-settings-module
Data type representing a settings module for Patchwork.  Some of these
settings relate directly to Patchwork, but others relate to Django, the web
framework used by Patchwork, or the Django Rest Framework library.  This
type has the following parameters:

@table @asis
@item @code{database-configuration} (default: @code{(patchwork-database-configuration)})
The database connection settings used for Patchwork.  See the
@code{<patchwork-database-configuration>} record type for more information.

@item @code{secret-key-file} (default: @code{"/etc/patchwork/django-secret-key"})
Patchwork, as a Django web application uses a secret key for
cryptographically signing values.  This file should contain a unique
unpredictable value.

If this file does not exist, it will be created and populated with a random
value by the patchwork-setup shepherd service.

This setting relates to Django.

@item @code{allowed-hosts}
A list of valid hosts for this Patchwork service.  This should at least
include the domain specified in the @code{<patchwork-configuration>} record.

This is a Django setting.

@item @code{default-from-email}
The email address from which Patchwork should send email by default.

This is a Patchwork setting.

@item @code{static-url} (default: @code{#f})
The URL to use when serving static assets.  It can be part of a URL, or a
full URL, but must end in a @code{/}.

If the default value is used, the @code{static-path} value from the
@code{<patchwork-configuration>} record will be used.

This is a Django setting.

@item @code{admins} (default: @code{'()})
Email addresses to send the details of errors that occur.  Each value should
be a list containing two elements, the name and then the email address.

This is a Django setting.

@item @code{debug?} (default: @code{#f})
Whether to run Patchwork in debug mode.  If set to @code{#t}, detailed error
messages will be shown.

This is a Django setting.

@item @code{enable-rest-api?} (default: @code{#t})
Whether to enable the Patchwork REST API.

This is a Patchwork setting.

@item @code{enable-xmlrpc?} (default: @code{#t})
Whether to enable the XML RPC API.

This is a Patchwork setting.

@item @code{force-https-links?} (default: @code{#t})
Whether to use HTTPS links on Patchwork pages.

This is a Patchwork setting.

@item @code{extra-settings} (default: @code{""})
Extra code to place at the end of the Patchwork settings module.

@end table
@end deftp

@deftp {Tipo de dados} patchwork-database-configuration
Data type representing the database configuration for Patchwork.

@table @asis
@item @code{engine} (default: @code{"django.db.backends.postgresql_psycopg2"})
The database engine to use.

@item @code{name} (default: @code{"patchwork"})
The name of the database to use.

@item @code{user} (default: @code{"httpd"})
The user to connect to the database as.

@item @code{password} (default: @code{""})
The password to use when connecting to the database.

@item @code{host} (default: @code{""})
The host to make the database connection to.

@item @code{port} (padrão: @code{""})
The port on which to connect to the database.

@end table
@end deftp

@subsubheading Mumi

@cindex Mumi, Debbugs Web interface
@cindex Debbugs, Mumi Web interface
@uref{https://codeberg.org/guix/mumi, Mumi} is a Web interface to the
Debbugs bug tracker, by default for @uref{https://bugs.gnu.org, the GNU
instance}.  Mumi is a Web server, but it also fetches and indexes mail
retrieved from Debbugs.

@defvar mumi-service-type
This is the service type for Mumi.
@end defvar

@deftp {Tipo de dados} mumi-configuration
Data type representing the Mumi service configuration.  This type has the
following fields:

@table @asis
@item @code{mumi} (default: @code{mumi})
The Mumi package to use.

@item @code{data-directory} (default: @file{"/var/mumi/data"})
Data directory to store Debbugs data from upstream Debbugs instance.

@item @code{rsync-remote}
Remote rsync path from which to download Debbugs data.  The remote is polled
every 5 minutes, unless a previous instance of rsync is already running.

@item @code{rsync-flags} (default: @code{'()})
Additional flags to pass to @command{rsync}.

@item @code{mailer?} (default: @code{#true})
Whether to enable or disable the mailer component.

@item @code{sender}
The email address used as the sender for comments.

@item @code{smtp}
A URI to configure the SMTP settings for Mailutils.  This could be something
like @code{sendmail:///path/to/bin/msmtp} or any other URI supported by
Mailutils.  @xref{SMTP Mailboxes, SMTP Mailboxes,, mailutils,
GNU@tie{}Mailutils}.

@item @code{pacotes}
List of @code{<mumi-package-configuration>} objects representing packages
configured on Mumi.

@end table
@end deftp

@deftp {Data Type} mumi-package-configuration
Data type representing the configuration of a package on Mumi.  This type
has the following fields:

@table @asis
@item @code{name}
Name of the package.

@item @code{display-name}
Display name used for this package in the web interface.

@item @code{debbugs-packages}
List of Debbugs packages this package refers to.

@item @code{bug-email-address}
Email address to send bug reports to.

@item @code{patch-email-address}
Email address to send patches to, if that is different from
@code{bug-email-address}.

@item @code{file-tags}
Association list mapping tags to filename regular expressions. Keys are tag
names, and values are lists of regular expressions.  For each entry of the
association list, the tag is applied if a filename referred to in a patch
matches any of the regular expressions.

@end table
@end deftp


@subsubheading FastCGI
@cindex fastcgi
@cindex fcgiwrap
FastCGI is an interface between the front-end and the back-end of a web
service.  It is a somewhat legacy facility; new web services should
generally just talk HTTP between the front-end and the back-end.  However
there are a number of back-end services such as PHP or the optimized HTTP
Git repository access that use FastCGI, so we have support for it in Guix.

To use FastCGI, you configure the front-end web server (e.g., nginx) to
dispatch some subset of its requests to the fastcgi backend, which listens
on a local TCP or UNIX socket.  There is an intermediary @code{fcgiwrap}
program that sits between the actual backend process and the web server.
The front-end indicates which backend program to run, passing that
information to the @code{fcgiwrap} process.

@defvar fcgiwrap-service-type
A service type for the @code{fcgiwrap} FastCGI proxy.
@end defvar

@deftp {Tipo de dados} fcgiwrap-configuration
Data type representing the configuration of the @code{fcgiwrap} service.
This type has the following parameters:
@table @asis
@item @code{package} (default: @code{fcgiwrap})
The fcgiwrap package to use.

@item @code{socket} (default: @code{tcp:127.0.0.1:9000})
The socket on which the @code{fcgiwrap} process should listen, as a string.
Valid @var{socket} values include @code{unix:@var{/path/to/unix/socket}},
@code{tcp:@var{dot.ted.qu.ad}:@var{port}} and
@code{tcp6:[@var{ipv6_addr}]:port}.

@item @code{user} (default: @code{fcgiwrap})
@itemx @code{group} (default: @code{fcgiwrap})
The user and group names, as strings, under which to run the @code{fcgiwrap}
process.  The @code{fastcgi} service will ensure that if the user asks for
the specific user or group names @code{fcgiwrap} that the corresponding user
and/or group is present on the system.

It is possible to configure a FastCGI-backed web service to pass HTTP
authentication information from the front-end to the back-end, and to allow
@code{fcgiwrap} to run the back-end process as a corresponding local user.
To enable this capability on the back-end, run @code{fcgiwrap} as the
@code{root} user and group.  Note that this capability also has to be
configured on the front-end as well.
@end table
@end deftp

@anchor{PHP-FPM}
@subsubheading PHP-FPM
@cindex php-fpm
PHP-FPM (FastCGI Process Manager) is an alternative PHP FastCGI
implementation with some additional features useful for sites of any size.

These features include:
@itemize @bullet
@item Adaptive process spawning
@item Basic statistics (similar to Apache's mod_status)
@item Advanced process management with graceful stop/start
@item Ability to start workers with different uid/gid/chroot/environment
and different php.ini (replaces safe_mode)
@item Stdout & stderr logging
@item Emergency restart in case of accidental opcode cache destruction
@item Accelerated upload support
@item Support for a "slowlog"
@item Enhancements to FastCGI, such as fastcgi_finish_request() -
a special function to finish request & flush all data while continuing to do
something time-consuming (video converting, stats processing, etc.)
@end itemize
...@: e muito mais.

@defvar php-fpm-service-type
A Service type for @code{php-fpm}.
@end defvar

@deftp {Tipo de dados} php-fpm-configuration
Data Type for php-fpm service configuration.
@table @asis
@item @code{php} (default: @code{php})
The php package to use.
@item @code{socket} (default: @code{(string-append "/var/run/php" (version-major (package-version php)) "-fpm.sock")})
The address on which to accept FastCGI requests.  Valid syntaxes are:
@table @asis
@item @code{"ip.add.re.ss:port"}
Listen on a TCP socket to a specific address on a specific port.
@item @code{"port"}
Listen on a TCP socket to all addresses on a specific port.
@item @code{"/path/to/unix/socket"}
Listen on a unix socket.
@end table

@item @code{user} (default: @code{php-fpm})
User who will own the php worker processes.
@item @code{group} (default: @code{php-fpm})
Group of the worker processes.
@item @code{socket-user} (default: @code{php-fpm})
User who can speak to the php-fpm socket.
@item @code{socket-group} (default: @code{nginx})
Group that can speak to the php-fpm socket.
@item @code{pid-file} (default: @code{(string-append "/var/run/php" (version-major (package-version php)) "-fpm.pid")})
The process id of the php-fpm process is written to this file once the
service has started.
@item @code{log-file} (default: @code{(string-append "/var/log/php" (version-major (package-version php)) "-fpm.log")})
Log for the php-fpm master process.
@item @code{process-manager} (default: @code{(php-fpm-dynamic-process-manager-configuration)})
Detailed settings for the php-fpm process manager.  Must be one of:
@table @asis
@item @code{<php-fpm-dynamic-process-manager-configuration>}
@item @code{<php-fpm-static-process-manager-configuration>}
@item @code{<php-fpm-on-demand-process-manager-configuration>}
@end table
@item @code{display-errors} (default @code{#f})
Determines whether php errors and warning should be sent to clients and
displayed in their browsers.  This is useful for local php development, but
a security risk for public sites, as error messages can reveal passwords and
personal data.
@item @code{timezone} (default @code{#f})
Specifies @code{php_admin_value[date.timezone]} parameter.
@item @code{workers-logfile} (default @code{(string-append "/var/log/php" (version-major (package-version php)) "-fpm.www.log")})
This file will log the @code{stderr} outputs of php worker processes.  Can
be set to @code{#f} to disable logging.
@item @code{file} (padrão @code{#f})
An optional override of the whole configuration.  You can use the
@code{mixed-text-file} function or an absolute filepath for it.
@item @code{php-ini-file} (default @code{#f})
An optional override of the default php settings.  It may be any
``file-like'' object (@pxref{Expressões-G, file-like objects}).  You can
use the @code{mixed-text-file} function or an absolute filepath for it.

For local development it is useful to set a higher timeout and memory limit
for spawned php processes.  This be accomplished with the following
operating system configuration snippet:
@lisp
(define %local-php-ini
  (plain-file "php.ini"
              "memory_limit = 2G
max_execution_time = 1800"))

(operating-system
  ;; @dots{}
  (services (cons (service php-fpm-service-type
                           (php-fpm-configuration
                            (php-ini-file %local-php-ini)))
                  %base-services)))
@end lisp

Consult the @url{https://www.php.net/manual/en/ini.core.php,core php.ini
directives} for comprehensive documentation on the acceptable @file{php.ini}
directives.
@end table
@end deftp

@deftp {Tipo de dados} php-fpm-dynamic-process-manager-configuration
Data Type for the @code{dynamic} php-fpm process manager.  With the
@code{dynamic} process manager, spare worker processes are kept around based
on its configured limits.
@table @asis
@item @code{max-children} (default: @code{5})
Maximum of worker processes.
@item @code{start-servers} (default: @code{2})
How many worker processes should be started on start-up.
@item @code{min-spare-servers} (default: @code{1})
How many spare worker processes should be kept around at minimum.
@item @code{max-spare-servers} (default: @code{3})
How many spare worker processes should be kept around at maximum.
@end table
@end deftp

@deftp {Tipo de dados} php-fpm-static-process-manager-configuration
Data Type for the @code{static} php-fpm process manager.  With the
@code{static} process manager, an unchanging number of worker processes are
created.
@table @asis
@item @code{max-children} (default: @code{5})
Maximum of worker processes.
@end table
@end deftp

@deftp {Tipo de dados} php-fpm-on-demand-process-manager-configuration
Data Type for the @code{on-demand} php-fpm process manager.  With the
@code{on-demand} process manager, worker processes are only created as
requests arrive.
@table @asis
@item @code{max-children} (default: @code{5})
Maximum of worker processes.
@item @code{process-idle-timeout} (default: @code{10})
The time in seconds after which a process with no requests is killed.
@end table
@end deftp


@deffn {Procedure} nginx-php-location [#:nginx-package nginx] @
  [socket (string-append "/var/run/php" @ (version-major (package-version
php)) "-fpm.sock")] A helper function to quickly add php to an
@code{nginx-server-configuration}.
@end deffn

A simple services setup for nginx with php can look like this:
@lisp
(services (cons* (service dhcp-client-service-type)
                 (service php-fpm-service-type)
                 (service nginx-service-type
                          (nginx-server-configuration
                           (server-name '("example.com"))
                           (root "/srv/http/")
                           (locations
                            (list (nginx-php-location)))
                           (listen '("80"))
                           (ssl-certificate #f)
                           (ssl-certificate-key #f)))
                 %base-services))
@end lisp

@cindex cat-avatar-generator
The cat avatar generator is a simple service to demonstrate the use of
php-fpm in @code{Nginx}.  It is used to generate cat avatar from a seed, for
instance the hash of a user's email address.

@deffn {Procedure} cat-avatar-generator-service @
       [#:cache-dir "/var/cache/cat-avatar-generator"] @ [#:package
cat-avatar-generator] @ [#:configuration (nginx-server-configuration)]
Returns an nginx-server-configuration that inherits @code{configuration}.
It extends the nginx configuration to add a server block that serves
@code{package}, a version of cat-avatar-generator.  During execution,
cat-avatar-generator will be able to use @code{cache-dir} as its cache
directory.
@end deffn

A simple setup for cat-avatar-generator can look like this:
@lisp
(services (cons* (cat-avatar-generator-service
                  #:configuration
                  (nginx-server-configuration
                    (server-name '("example.com"))))
                 ...
                 %base-services))
@end lisp

@subsubheading Hpcguix-web

@cindex hpcguix-web
The @uref{https://github.com/UMCUGenetics/hpcguix-web/, hpcguix-web} program
is a customizable web interface to browse Guix packages, initially designed
for users of high-performance computing (HPC)  clusters.

@defvar hpcguix-web-service-type
The service type for @code{hpcguix-web}.
@end defvar

@deftp {Tipo de dados} hpcguix-web-configuration
Data type for the hpcguix-web service configuration.

@table @asis
@item @code{specs} (default: @code{#f})
Either @code{#f} or a gexp (@pxref{Expressões-G}) specifying the
hpcguix-web service configuration as an @code{hpcguix-web-configuration}
record.  The main fields of that record type are:

@table @asis
@item @code{title-prefix} (default: @code{"hpcguix | "})
The page title prefix.

@item @code{guix-command} (default: @code{"guix"})
The @command{guix} command to use in examples that appear on HTML pages.

@item @code{package-filter-proc} (default: @code{(const #t)})
A procedure specifying how to filter packages that are displayed.

@item @code{package-page-extension-proc} (default: @code{(const '())})
Extension package for @code{hpcguix-web}.

@item @code{menu} (default: @code{'()})
Additional entry in page @code{menu}.

@item @code{channels} (default: @code{%default-channels})
List of channels from which the package list is built (@pxref{Canais}).

@item @code{package-list-expiration} (default: @code{(* 12 3600)})
The expiration time, in seconds, after which the package list is rebuilt
from the latest instances of the given channels.
@end table

See the hpcguix-web repository for a
@uref{https://github.com/UMCUGenetics/hpcguix-web/blob/master/hpcweb-configuration.scm,
complete example}.

@item @code{package} (default: @code{hpcguix-web})
The hpcguix-web package to use.

@item @code{address} (default: @code{"127.0.0.1"})
The IP address to listen to.

@item @code{port} (padrão: @code{5000})
The port number to listen to.
@end table
@end deftp

A typical hpcguix-web service declaration looks like this:

@lisp
(service hpcguix-web-service-type
         (hpcguix-web-configuration
          (specs
           #~(hpcweb-configuration
              (title-prefix "Guix-HPC - ")
              (menu '(("/about" "ABOUT")))))))
@end lisp

@quotation 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.

A certificate package, @code{nss-certs}, is provided by default as part of
@code{%base-packages}.  @ref{Certificados X.509}, for more information on
X.509 certificates.
@end quotation

@subsubheading gmnisrv

@cindex gmnisrv
The @uref{https://git.sr.ht/~sircmpwn/gmnisrv, gmnisrv} program is a simple
@uref{https://gemini.circumlunar.space/, Gemini} protocol server.

@defvar gmnisrv-service-type
This is the type of the gmnisrv service, whose value should be a
@code{gmnisrv-configuration} object, as in this example:

@lisp
(service gmnisrv-service-type
         (gmnisrv-configuration
           (config-file (local-file "./my-gmnisrv.ini"))))
@end lisp
@end defvar

@deftp {Tipo de dados} gmnisrv-configuration
Data type representing the configuration of gmnisrv.

@table @asis
@item @code{package} (default: @var{gmnisrv})
Package object of the gmnisrv server.

@item @code{config-file} (default: @code{%default-gmnisrv-config-file})
File-like object of the gmnisrv configuration file to use.  The default
configuration listens on port 1965 and serves files from
@file{/srv/gemini}.  Certificates are stored in
@file{/var/lib/gemini/certs}.  For more information, run @command{man
gmnisrv} and @command{man gmnisrv.ini}.

@end table
@end deftp

@subsubheading Agate

@cindex agate
The @uref{gemini://qwertqwefsday.eu/agate.gmi, Agate}
(@uref{https://github.com/mbrubeck/agate, GitHub page over HTTPS})  program
is a simple @uref{https://gemini.circumlunar.space/, Gemini} protocol server
written in Rust.

@defvar agate-service-type
This is the type of the agate service, whose value should be an
@code{agate-service-type} object, as in this example:

@lisp
(service agate-service-type
	 (agate-configuration
	   (content "/srv/gemini")
	   (certificates "/srv/gemini-certs")))
@end lisp

The example above represents the minimal tweaking necessary to get Agate up
and running.  Specifying the path to the certificate and key directory is
always necessary, as the Gemini protocol requires TLS by default.

If the specified @code{certificates} path is writable by Agate, and contains
no valid pre-generated key and certificate, Agate will try to generate them
on the first start.  In this case you should pass at least one hostname
using the @code{hostnames} option.  If the specified directory is read-only,
key and certificate should be pre-generated by the user.

To obtain a certificate and a key in DER format, you could, for example, use
OpenSSL, running commands similar to the following example:

@example
openssl genpkey -out key.der -outform DER -algorithm RSA \
    -pkeyopt rsa_keygen_bits:4096
openssl req -x509 -key key.der -outform DER -days 3650 -out cert.der \
    -subj "/CN=example.com"
@end example

Of course, you'll have to replace @i{example.com} with your own domain name,
and then point the Agate configuration towards the path of the directory
with the generated key and certificate using the @code{certificates} option.

@end defvar

@deftp {Tipo de dados} agate-configuration
Data type representing the configuration of Agate.

@table @asis
@item @code{package} (default: @code{agate})
The package object of the Agate server.

@item @code{content} (default: @file{"/srv/gemini"})
The directory from which Agate will serve files.

@item @code{certificates} (default: @file{"/srv/gemini-certs"})
Root of the certificate directory. Must be filled in with a value from the
user.

@item @code{addresses} (default: @code{'("[::]:1965" "0.0.0.0:1965")})
A list of the addresses to listen on.

@item @code{hostnames} (default: @code{'()})
Virtual hosts for the Gemini server. If multiple values are specified,
corresponding directory names should be present in the @code{content}
directory. Optional.

@item @code{languages} (default: @code{#f})
RFC 4646 language code(s) for text/gemini documents.  Optional.

@item @code{only-tls13?} (default: @code{#f})
Set to @code{#t} to disable support for TLSv1.2.

@item @code{serve-secret?} (default: @code{#f})
Set to @code{#t} to serve secret files (files/directories starting with a
dot).

@item @code{central-configuration?} (default: @code{#f})
Set to @code{#t} to look for the .meta configuration file in the
@code{content} root directory and will ignore @code{.meta} files in other
directories

@item @code{ed25519?} (default: @code{#f})
Set to @code{#t} to generate keys using the Ed25519 signature algorithm
instead of the default ECDSA.

@item @code{skip-port-check?} (default: @code{#f})
Set to @code{#t} to skip URL port check even when a @code{hostname} is
specified.

@item @code{log-ip?} (default: @code{#t})
Whether or not to output IP addresses when logging.

@item @code{user} (default: @code{"agate"})
Owner of the @code{agate} process.

@item @code{group} (default: @code{"agate"})
Owner's group of the @code{agate} process.

@item @code{log-file} (default: @file{"/var/log/agate.log"})
The file which should store the logging output of Agate.

@end table
@end deftp

@subsubheading Miniflux

@cindex miniflux
The @uref{https://miniflux.app/, Miniflux} is a minimalist RSS feed reader
with a web interface.

Depending on the configuration, an initial administrator user can be
pre-created on startup. To enable this, @code{create-admin?} should be set
to @code{#t}, and both @code{admin-username-file} and
@code{admin-password-file} should point to files containing the username and
password, respectively. However, it is recommended to manually change the
password to a secure one via the web UI after the initial service startup.

@defvar miniflux-service-type
This is the type of the Miniflux service. Its value must be a
@code{miniflux-configuration} record as in this example:

@lisp
(service miniflux-service-type
         (miniflux-configuration
          (listen-address "0.0.0.0:8080")
          (base-url "http://my-news-source.test")
          (create-administrator-account? #t)
          (administrator-account-name "/var/miniflux/initial-admin-username")
          (administrator-account-password "/var/miniflux/initial-admin-password")))
@end lisp

The details of the @code{miniflux-configuration} record type are given
below.

@end defvar

@deftp {Data Type} miniflux-configuration
Available @code{miniflux-configuration} fields are:

@table @asis
@item @code{listen-address} (default: @code{"127.0.0.1:8080"}) (type: string)
Address to listen on.  Use absolute path like
@code{"/var/run/miniflux/miniflux.sock"} for a Unix socket.

@item @code{base-url} (default: @code{"http://127.0.0.1/"}) (type: string)
Base URL to generate HTML links and base path for cookies.

@item @code{create-administrator-account?} (default: @code{#f}) (type: boolean)
Create an initial administrator account.

@item @code{administrator-account-name} (type: maybe-string-or-file-path)
Initial administrator account name as a string or an absolute path to a file
with an account name inside.

@item @code{administrator-account-password} (type: maybe-string-or-file-path)
Initial administrator account password as a string or an absolute path to a
file with a password inside.

@item @code{run-migrations?} (default: @code{#t}) (type: boolean)
Run database migrations during application startup.

@item @code{database-url} (default: @code{"host=/var/run/postgresql"}) (type: string)
PostgreSQL connection string.

@item @code{user} (default: @code{"miniflux"}) (type: string)
User name for Postgresql and system account.

@item @code{group} (default: @code{"miniflux"}) (type: string)
Group for the system account.

@item @code{log-file} (default: @code{"/var/log/miniflux.log"}) (type: string)
Path to the log file.

@item @code{extra-settings} (type: maybe-list)
Extra configuration parameters as a list of strings.

@end table
@end deftp

@node High Availability Services
@subsection High Availability Services

@cindex Message broker
@cindex Message streaming
The @code{(gnu services high-availability)} module provides RabbitMQ message
broker service.

@anchor{RabbitMQ}
@subsubheading RabbitMQ

@defvar rabbitmq-service-type
Service type for the @uref{https://www.rabbitmq.com/,RabbitMQ} web server.
The value for this service type is a @code{<rabbitmq-configuration>} record.

A simple example configuration is given below.

@lisp
(service rabbitmq-service-type
         (rabbitmq-configuration
           (rabbitmq-configuration
             (plugins '("rabbitmq_stream"
                        "rabbitmq_management"
                        "rabbitmq_prometheus")))))
@end lisp
@end defvar

At startup, RabbitMQ broker logs its initialization messages into
@file{/var/log/messages} file.  Once running, the logging messages can be
found in a logging file of a RabbitMQ node in @file{/var/log/rabbitmq}
directory.

@quotation Nota
The default configuration of the RabbitMQ service enables the RabbitMQ
broker to accept connections only on loopback interfaces.  However, enabling
certain plugins may open ports on all network interfaces.  See also
@url{https://www.rabbitmq.com/docs/networking#ports, RabbitMQ Port Access}.
@end quotation

@deftp {Data Type} rabbitmq-configuration
This data type represents the configuration for RabbitMQ.

@table @asis
@item @code{rabbitmq} (default: @code{rabbitmq})
The RabbitMQ package to use.

@item @code{config-file} (default: @code{%default-rabbitmq-config-file})
Configuration file for the RabbitMQ broker. See also
@url{https://www.rabbitmq.com/docs/configure, RabbitMQ Configuration}.

@item @code{data-directory} (default: @code{"/var/lib/rabbitmq/data"})
Directory with RabbitMQ broker data - a schema database, message stores,
cluster member information, and other persistent node state.

@item @code{plugins} (default: @code{'()})
A list of RabbitMQ plugins to enable.  View all available plugins using the
@command{rabbitmq-plugins list} command.

@end table
@end deftp

@node Serviços de certificado
@subsection Serviços de certificado

@cindex Web
@cindex HTTP, HTTPS
@cindex Let's Encrypt
@cindex TLS certificates
The @code{(gnu services certbot)} module provides a service to automatically
obtain a valid TLS certificate from the Let's Encrypt certificate
authority.  These certificates can then be used to serve content securely
over HTTPS or other TLS-based protocols, with the knowledge that the client
will be able to verify the server's authenticity.

@url{https://letsencrypt.org/, Let's Encrypt} provides the @code{certbot}
tool to automate the certification process.  This tool first securely
generates a key on the server.  It then makes a request to the Let's Encrypt
certificate authority (CA) to sign the key.  The CA checks that the request
originates from the host in question by using a challenge-response protocol,
requiring the server to provide its response over HTTP@.  If that protocol
completes successfully, the CA signs the key, resulting in a certificate.
That certificate is valid for a limited period of time, and therefore to
continue to provide TLS services, the server needs to periodically ask the
CA to renew its signature.

The certbot service automates this process: the initial key generation, the
initial certification request to the Let's Encrypt service, the web server
challenge/response integration, writing the certificate to disk, the
automated periodic renewals, and the deployment tasks associated with the
renewal (e.g.@: reloading services, copying keys with different
permissions).

Certbot is run twice a day, at a random minute within the hour.  It won't do
anything until your certificates are due for renewal or revoked, but running
it regularly would give your service a chance of staying online in case a
Let's Encrypt-initiated revocation happened for some reason.

By using this service, you agree to the ACME Subscriber Agreement, which can
be found there: @url{https://acme-v02.api.letsencrypt.org/directory}.

@defvar certbot-service-type
A service type for the @code{certbot} Let's Encrypt client.  Its value must
be a @code{certbot-configuration} record as in this example:

@lisp
(service certbot-service-type
         (certbot-configuration
          (email "foo@@example.net")
          (certificates
           (list
            (certificate-configuration
             (domains '("example.net" "www.example.net")))
            (certificate-configuration
             (domains '("bar.example.net")))))))
@end lisp

See below for details about @code{certbot-configuration}.
@end defvar

@deftp {Tipo de dados} certbot-configuration
Data type representing the configuration of the @code{certbot} service.
This type has the following parameters:

@table @asis
@item @code{package} (default: @code{certbot})
The certbot package to use.

@item @code{webroot} (default: @code{/var/www})
The directory from which to serve the Let's Encrypt challenge/response
files.

@item @code{certificates} (default: @code{'()})
A list of @code{certificates-configuration}s for which to generate
certificates and request signatures.  Each certificate has a @code{name} and
several @code{domains}.

@item @code{email} (default: @code{#f})
Optional email address used for registration and recovery contact.  Setting
this is encouraged as it allows you to receive important notifications about
the account and issued certificates.

@item @code{server} (default: @code{#f})
Optional URL of ACME server.  Setting this overrides certbot's default,
which is the Let's Encrypt server.

@item @code{rsa-key-size} (default: @code{2048})
Size of the RSA key.

@item @code{default-location} (default: @i{see below})
The default @code{nginx-location-configuration}.  Because @code{certbot}
needs to be able to serve challenges and responses, it needs to be able to
run a web server.  It does so by extending the @code{nginx} web service with
an @code{nginx-server-configuration} listening on the @var{domains} on port
80, and which has a @code{nginx-location-configuration} for the
@code{/.well-known/} URI path subspace used by Let's Encrypt.  @xref{Serviços 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 dados} certificate-configuration
Data type representing the configuration of a certificate.  This type has
the following parameters:

@table @asis
@item @code{name} (default: @i{see below})
This name is used by Certbot for housekeeping and in file paths; it doesn't
affect the content of the certificate itself.  To see certificate names, run
@code{certbot certificates}.

Its default is the first provided domain.

@item @code{domains} (default: @code{'()})
The first domain provided will be the subject CN of the certificate, and all
domains will be Subject Alternative Names on the certificate.

@item @code{challenge} (padrão: @code{#f})
The challenge type that has to be run by certbot.  If @code{#f} is
specified, default to the HTTP challenge.  If a value is specified, defaults
to the manual plugin (see @code{authentication-hook}, @code{cleanup-hook}
and the documentation at
@url{https://certbot.eff.org/docs/using.html#hooks}), and gives Let's
Encrypt permission to log the public IP address of the requesting machine.

@item @code{csr} (default: @code{#f})
File name of Certificate Signing Request (CSR) in DER or PEM format.  If
@code{#f} is specified, this argument will not be passed to certbot.  If a
value is specified, certbot will use it to obtain a certificate, instead of
using a self-generated CSR.  The domain-name(s) mentioned in @code{domains},
must be consistent with the domain-name(s) mentioned in CSR file.

@item @code{authentication-hook} (padrão: @code{#f})
Command to be run in a shell once for each certificate challenge to be
answered.  For this command, the shell variable @code{$CERTBOT_DOMAIN} will
contain the domain being authenticated, @code{$CERTBOT_VALIDATION} contains
the validation string and @code{$CERTBOT_TOKEN} contains the file name of
the resource requested when performing an HTTP-01 challenge.

@item @code{cleanup-hook} (padrão: @code{#f})
Command to be run in a shell once for each certificate challenge that have
been answered by the @code{authentication-hook}.  For this command, the
shell variables available in the @code{authentication-hook} script are still
available, and additionally @code{$CERTBOT_AUTH_OUTPUT} will contain the
standard output of the @code{authentication-hook} script.

@item @code{deploy-hook} (default: @code{#f})
Command to be run in a shell once for each successfully issued certificate.
For this command, the shell variable @code{$RENEWED_LINEAGE} will point to
the config live subdirectory (for example,
@samp{"/etc/letsencrypt/live/example.com"}) containing the new certificates
and keys; the shell variable @code{$RENEWED_DOMAINS} will contain a
space-delimited list of renewed certificate domains (for example,
@samp{"example.com www.example.com"}.

@item @code{dry-run?} (default: @code{#f})
Communicate with the ACME server but do not update certificates nor trigger
@code{deploy-hook}.  This is useful as a temporary setting to test the
challenge procedure, especially the @code{authentication-hook} and
@code{cleanup-hook} while working on them.  It's also a good idea to use the
Let's Encrypt staging server at
@url{https://acme-staging-v02.api.letsencrypt.org/directory} while testing,
which allows for higher rate limits, but with which @code{certbot} will
helpfully refuse to update certificates and recommend the @code{dry-run?}
option.  For example:

@lisp
(define %authentication-hook
  (program-file "authentication-hook"
    #~(let ((domain (getenv "CERTBOT_DOMAIN"))
            (token (getenv "CERTBOT_TOKEN")))
        (format #t "Hey, can you authenticate ~a with ~a for me?"
                domain token))))

(define %cleanup-hook
  (program-file "authentication-hook"
    #~(display "Bye")))

(service certbot-service-type
         (certbot-configuration
          (server "https://acme-staging-v02.api.letsencrypt.org/directory")
          (certificates
           (list
            (certificate-configuration
              (dry-run? #t)
              (authentication-hook %authentication-hook)
              (cleanup-hook %cleanup-hook)
              (domains '("example.net" "www.example.net")))))))
@end lisp

@item @code{start-self-signed?} (default: @code{#t})
Whether to generate an initial self-signed certificate during system
activation.  This option is particularly useful to allow @code{nginx} to
start before @code{certbot} has run, because @code{certbot} relies on
@code{nginx} running to perform HTTP challenges.

@end table
@end deftp

For each @code{certificate-configuration}, the certificate is saved to
@code{/etc/certs/@var{name}/fullchain.pem} and the key is saved to
@code{/etc/certs/@var{name}/privkey.pem}.
@node Serviços DNS
@subsection Serviços 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 Knot Service

An example configuration of an authoritative server for two zones, one
master and one slave, is:

@lisp
(define-zone-entries example.org.zone
;; Name TTL Class Type Data
  ("@@"  ""  "IN"  "A"  "127.0.0.1")
  ("@@"  ""  "IN"  "NS" "ns")
  ("ns" ""  "IN"  "A"  "127.0.0.1"))

(define master-zone
  (knot-zone-configuration
    (domain "example.org")
    (zone (zone-file
            (origin "example.org")
            (entries example.org.zone)))))

(define slave-zone
  (knot-zone-configuration
    (domain "plop.org")
    (dnssec-policy "default")
    (master (list "plop-master"))))

(define plop-master
  (knot-remote-configuration
    (id "plop-master")
    (address (list "208.76.58.171"))))

(operating-system
  ;; ...
  (services (cons* (service knot-service-type
                     (knot-configuration
                       (remotes (list plop-master))
                       (zones (list master-zone slave-zone))))
                   ;; ...
                   %base-services)))
@end lisp

@defvar knot-service-type
This is the type for the Knot DNS server.

Knot DNS is an authoritative DNS server, meaning that it can serve multiple
zones, that is to say domain names you would buy from a registrar.  This
server is not a resolver, meaning that it can only resolve names for which
it is authoritative.  This server can be configured to serve zones as a
master server or a slave server as a per-zone basis.  Slave zones will get
their data from masters, and will serve it as an authoritative server.  From
the point of view of a resolver, there is no difference between master and
slave.

The following data types are used to configure the Knot DNS server:
@end defvar

@deftp {Tipo de dados} knot-key-configuration
Data type representing a key.  This type has the following parameters:

@table @asis
@item @code{id} (default: @code{""})
An identifier for other configuration fields to refer to this key.  IDs must
be unique and must not be empty.

@item @code{algorithm} (padrão: @code{#f})
The algorithm to use.  Choose between @code{#f}, @code{'hmac-md5},
@code{'hmac-sha1}, @code{'hmac-sha224}, @code{'hmac-sha256},
@code{'hmac-sha384} and @code{'hmac-sha512}.

@item @code{secret} (default: @code{""})
The secret key itself.

@end table
@end deftp

@deftp {Tipo de dados} knot-acl-configuration
Data type representing an Access Control List (ACL) configuration.  This
type has the following parameters:

@table @asis
@item @code{id} (default: @code{""})
An identifier for other configuration fields to refer to this key.  IDs must
be unique and must not be empty.

@item @code{address} (default: @code{'()})
An ordered list of IP addresses, network subnets, or network ranges
represented with strings.  The query must match one of them.  Empty value
means that address match is not required.

@item @code{key} (default: @code{'()})
An ordered list of references to keys represented with strings.  The string
must match a key ID defined in a @code{knot-key-configuration}.  No key
means that a key is not require to match that ACL.

@item @code{action} (default: @code{'()})
An ordered list of actions that are permitted or forbidden by this ACL@.
Possible values are lists of zero or more elements from @code{'transfer},
@code{'notify} and @code{'update}.

@item @code{deny?} (padrão: @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 dados} zone-entry
Data type representing a record entry in a zone file.  This type has the
following parameters:

@table @asis
@item @code{name} (default: @code{"@@"})
The name of the record.  @code{"@@"} refers to the origin of the zone.
Names are relative to the origin of the zone.  For example, in the
@code{example.org} zone, @code{"ns.example.org"} actually refers to
@code{ns.example.org.example.org}.  Names ending with a dot are absolute,
which means that @code{"ns.example.org."} refers to @code{ns.example.org}.

@item @code{ttl} (default: @code{""})
The Time-To-Live (TTL) of this record.  If not set, the default TTL is used.

@item @code{class} (default: @code{"IN"})
The class of the record.  Knot currently supports only @code{"IN"} and
partially @code{"CH"}.

@item @code{type} (default: @code{"A"})
The type of the record.  Common types include A (IPv4 address), AAAA (IPv6
address), NS (Name Server) and MX (Mail eXchange).  Many other types are
defined.

@item @code{data} (default: @code{""})
The data contained in the record.  For instance an IP address associated
with an A record, or a domain name associated with an NS record.  Remember
that domain names are relative to the origin unless they end with a dot.

@end table
@end deftp

@deftp {Tipo de dados} zone-file
Data type representing the content of a zone file.  This type has the
following parameters:

@table @asis
@item @code{entries} (default: @code{'()})
The list of entries.  The SOA record is taken care of, so you don't need to
put it in the list of entries.  This list should probably contain an entry
for your primary authoritative DNS server.  Other than using a list of
entries directly, you can use @code{define-zone-entries} to define a object
containing the list of entries more easily, that you can later pass to the
@code{entries} field of the @code{zone-file}.

@item @code{origin} (default: @code{""})
The name of your zone.  This parameter cannot be empty.

@item @code{ns} (default: @code{"ns"})
The domain of your primary authoritative DNS server.  The name is relative
to the origin, unless it ends with a dot.  It is mandatory that this primary
DNS server corresponds to an NS record in the zone and that it is associated
to an IP address in the list of entries.

@item @code{mail} (default: @code{"hostmaster"})
An email address people can contact you at, as the owner of the zone.  This
is translated as @code{<mail>@@<origin>}.

@item @code{serial} (default: @code{1})
The serial number of the zone.  As this is used to keep track of changes by
both slaves and resolvers, it is mandatory that it @emph{never} decreases.
Always increment it when you make a change in your zone.

@item @code{refresh} (default: @code{(* 2 24 3600)})
The frequency at which slaves will do a zone transfer.  This value is a
number of seconds.  It can be computed by multiplications or with
@code{(string->duration)}.

@item @code{retry} (default: @code{(* 15 60)})
The period after which a slave will retry to contact its master when it
fails to do so a first time.

@item @code{expiry} (default: @code{(* 14 24 3600)})
Default TTL of records.  Existing records are considered correct for at most
this amount of time.  After this period, resolvers will invalidate their
cache and check again that it still exists.

@item @code{nx} (default: @code{3600})
Default TTL of inexistent records.  This delay is usually short because you
want your new domains to reach everyone quickly.

@end table
@end deftp

@deftp {Tipo de dados} knot-remote-configuration
Data type representing a remote configuration.  This type has the following
parameters:

@table @asis
@item @code{id} (default: @code{""})
An identifier for other configuration fields to refer to this remote.  IDs
must be unique and must not be empty.

@item @code{address} (default: @code{'()})
An ordered list of destination IP addresses.  Addresses are tried in
sequence.  An optional port can be given with the @@ separator.  For
instance: @code{(list "1.2.3.4" "2.3.4.5@@53")}.  Default port is 53.

@item @code{via} (default: @code{'()})
An ordered list of source IP addresses.  An empty list will have Knot choose
an appropriate source IP@.  An optional port can be given with the @@
separator.  The default is to choose at random.

@item @code{key} (padrão: @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 dados} knot-keystore-configuration
Data type representing a keystore to hold dnssec keys.  This type has the
following parameters:

@table @asis
@item @code{id} (default: @code{""})
The id of the keystore.  It must not be empty.

@item @code{backend} (default: @code{'pem})
The backend to store the keys in.  Can be @code{'pem} or @code{'pkcs11}.

@item @code{config} (default: @code{"/var/lib/knot/keys/keys"})
The configuration string of the backend.  An example for the PKCS#11 is:
@code{"pkcs11:token=knot;pin-value=1234
/gnu/store/.../lib/pkcs11/libsofthsm2.so"}.  For the pem backend, the string
represents a path in the file system.

@end table
@end deftp

@deftp {Tipo de dados} knot-policy-configuration
Data type representing a dnssec policy.  Knot DNS is able to automatically
sign your zones.  It can either generate and manage your keys automatically
or use keys that you generate.

Dnssec is usually implemented using two keys: a Key Signing Key (KSK) that
is used to sign the second, and a Zone Signing Key (ZSK) that is used to
sign the zone.  In order to be trusted, the KSK needs to be present in the
parent zone (usually a top-level domain).  If your registrar supports
dnssec, you will have to send them your KSK's hash so they can add a DS
record in their zone.  This is not automated and need to be done each time
you change your KSK.

The policy also defines the lifetime of keys.  Usually, ZSK can be changed
easily and use weaker cryptographic functions (they use lower parameters) in
order to sign records quickly, so they are changed often.  The KSK however
requires manual interaction with the registrar, so they are changed less
often and use stronger parameters because they sign only one record.

This type has the following parameters:

@table @asis
@item @code{id} (default: @code{""})
The id of the policy.  It must not be empty.

@item @code{keystore} (default: @code{"default"})
A reference to a keystore, that is a string containing the identifier of a
keystore defined in a @code{knot-keystore-configuration} field.  The
@code{"default"} identifier means the default keystore (a kasp database that
was setup by this service).

@item @code{manual?} (padrão: @code{#f})
Whether the key management is manual or automatic.

@item @code{single-type-signing?} (default: @code{#f})
When @code{#t}, use the Single-Type Signing Scheme.

@item @code{algorithm} (default: @code{"ecdsap256sha256"})
An algorithm of signing keys and issued signatures.

@item @code{ksk-size} (default: @code{256})
The length of the KSK@.  Note that this value is correct for the default
algorithm, but would be unsecure for other algorithms.

@item @code{zsk-size} (default: @code{256})
The length of the ZSK@.  Note that this value is correct for the default
algorithm, but would be unsecure for other algorithms.

@item @code{dnskey-ttl} (default: @code{'default})
The TTL value for DNSKEY records added into zone apex.  The special
@code{'default} value means same as the zone SOA TTL.

@item @code{zsk-lifetime} (default: @code{(* 30 24 3600)})
The period between ZSK publication and the next rollover initiation.

@item @code{propagation-delay} (default: @code{(* 24 3600)})
An extra delay added for each key rollover step.  This value should be high
enough to cover propagation of data from the master server to all slaves.

@item @code{rrsig-lifetime} (default: @code{(* 14 24 3600)})
A validity period of newly issued signatures.

@item @code{rrsig-refresh} (default: @code{(* 7 24 3600)})
A period how long before a signature expiration the signature will be
refreshed.

@item @code{nsec3?} (padrão: @code{#f})
When @code{#t}, NSEC3 will be used instead of NSEC.

@item @code{nsec3-iterations} (default: @code{5})
The number of additional times the hashing is performed.

@item @code{nsec3-salt-length} (default: @code{8})
The length of a salt field in octets, which is appended to the original
owner name before hashing.

@item @code{nsec3-salt-lifetime} (default: @code{(* 30 24 3600)})
The validity period of newly issued salt field.

@end table
@end deftp

@deftp {Tipo de dados} knot-zone-configuration
Data type representing a zone served by Knot.  This type has the following
parameters:

@table @asis
@item @code{domain} (default: @code{""})
The domain served by this configuration.  It must not be empty.

@item @code{file} (default: @code{""})
The file where this zone is saved.  This parameter is ignored by master
zones.  Empty means default location that depends on the domain name.

@item @code{zone} (default: @code{(zone-file)})
The content of the zone file.  This parameter is ignored by slave zones.  It
must contain a zone-file record.

@item @code{master} (default: @code{'()})
A list of master remotes.  When empty, this zone is a master.  When set,
this zone is a slave.  This is a list of remotes identifiers.

@item @code{ddns-master} (default: @code{#f})
The main master.  When empty, it defaults to the first master in the list of
masters.

@item @code{notify} (default: @code{'()})
A list of slave remote identifiers.

@item @code{acl} (default: @code{'()})
A list of acl identifiers.

@item @code{semantic-checks?} (default: @code{#f})
When set, this adds more semantic checks to the zone.

@item @code{zonefile-sync} (default: @code{0})
The delay between a modification in memory and on disk.  0 means immediate
synchronization.

@item @code{zonefile-load} (padrão: @code{#f})
The way the zone file contents are applied during zone load.  Possible
values are:

@itemize
@item @code{#f} for using the default value from Knot,
@item @code{'none} for not using the zone file at all,
@item @code{'difference} for computing the difference between already available
contents and zone contents and applying it to the current zone contents,
@item @code{'difference-no-serial} for the same as @code{'difference}, but
ignoring the SOA serial in the zone file, while the server takes care of it
automatically.
@item @code{'whole} for loading zone contents from the zone file.
@end itemize

@item @code{journal-content} (default: @code{#f})
The way the journal is used to store zone and its changes.  Possible values
are @code{'none} to not use it at all, @code{'changes} to store changes and
@code{'all} to store contents.  @code{#f} does not set this option, so the
default value from Knot is used.

@item @code{max-journal-usage} (padrão: @code{#f})
The maximum size for the journal on disk.  @code{#f} does not set this
option, so the default value from Knot is used.

@item @code{max-journal-depth} (padrão: @code{#f})
The maximum size of the history.  @code{#f} does not set this option, so the
default value from Knot is used.

@item @code{max-zone-size} (padrão: @code{#f})
The maximum size of the zone file.  This limit is enforced for incoming
transfer and updates.  @code{#f} does not set this option, so the default
value from Knot is used.

@item @code{dnssec-policy} (padrão: @code{#f})
A reference to a @code{knot-policy-configuration} record, or the special
name @code{"default"}.  If the value is @code{#f}, there is no dnssec
signing on this zone.

@item @code{serial-policy} (default: @code{'increment})
A policy between @code{'increment} and @code{'unixtime}.

@end table
@end deftp

@deftp {Tipo de dados} knot-configuration
Data type representing the Knot configuration.  This type has the following
parameters:

@table @asis
@item @code{knot} (default: @code{knot})
The Knot package.

@item @code{run-directory} (default: @code{"/var/run/knot"})
The run directory.  This directory will be used for pid file and sockets.

@item @code{includes} (default: @code{'()})
A list of strings or file-like objects denoting other files that must be
included at the top of the configuration file.

@cindex secrets, Knot service
This can be used to manage secrets out-of-band.  For example, secret keys
may be stored in an out-of-band file not managed by Guix, and thus not
visible in @file{/gnu/store}---e.g., you could store secret key
configuration in @file{/etc/knot/secrets.conf} and add this file to the
@code{includes} list.

One can generate a secret tsig key (for nsupdate and zone transfers with the
keymgr command from the knot package.  Note that the package is not
automatically installed by the service.  The following example shows how to
generate a new tsig key:

@example
keymgr -t mysecret > /etc/knot/secrets.conf
chmod 600 /etc/knot/secrets.conf
@end example

Also note that the generated key will be named @var{mysecret}, so it is the
name that needs to be used in the @var{key} field of the
@code{knot-acl-configuration} record and in other places that need to refer
to that key.

It can also be used to add configuration not supported by this interface.

@item @code{listen-v4} (default: @code{"0.0.0.0"})
An ip address on which to listen.

@item @code{listen-v6} (default: @code{"::"})
An ip address on which to listen.

@item @code{listen-port} (default: @code{53})
A port on which to listen.

@item @code{keys} (default: @code{'()})
The list of knot-key-configuration used by this configuration.

@item @code{acls} (default: @code{'()})
The list of knot-acl-configuration used by this configuration.

@item @code{remotes} (default: @code{'()})
The list of knot-remote-configuration used by this configuration.

@item @code{zones} (default: @code{'()})
The list of knot-zone-configuration used by this configuration.

@end table
@end deftp

@subsubheading Knot Resolver Service

@defvar knot-resolver-service-type
This is the type of the knot resolver service, whose value should be a
@code{knot-resolver-configuration} object as in this example:

@lisp
(service knot-resolver-service-type
         (knot-resolver-configuration
           (kresd-config-file (plain-file "kresd.conf" "
net.listen('192.168.0.1', 5353)
user('knot-resolver', 'knot-resolver')
modules = @{ 'hints > iterate', 'stats', 'predict' @}
cache.size = 100 * MB
"))))
@end lisp

For more information, refer its
@url{https://knot-resolver.readthedocs.io/en/stable/config-overview.html,
manual}.
@end defvar

@deftp {Tipo de dados} knot-resolver-configuration
Data type representing the configuration of knot-resolver.

@table @asis
@item @code{package} (default: @var{knot-resolver})
Package object of the knot DNS resolver.

@item @code{kresd-config-file} (default: %kresd.conf)
File-like object of the kresd configuration file to use, by default it will
listen on @code{127.0.0.1} and @code{::1}.

@item @code{garbage-collection-interval} (default: 1000)
Number of milliseconds for @code{kres-cache-gc} to periodically trim the
cache.

@end table
@end deftp


@subsubheading Dnsmasq Service

@defvar dnsmasq-service-type
This is the type of the dnsmasq service, whose value should be a
@code{dnsmasq-configuration} object as in this example:

@lisp
(service dnsmasq-service-type
         (dnsmasq-configuration
           (no-resolv? #t)
           (servers '("192.168.1.1"))))
@end lisp

@code{dnsmasq-service-type} provides two actions:

@table @code
@item reload
Send a @code{SIGHUP} signal to @command{dnsmasq} to clear cache and reload
hosts files which triggers the following actions:

@itemize @bullet
@item
Clear the DNS cache
@item
Reload @file{/etc/hosts} and @file{/etc/ethers}
@item
Reload files specified by @option{--dhcp-hostsfile},
@option{--dhcp-hostsdir}, @option{--dhcp-optsfile}, @option{--dhcp-optsdir},
@option{--addn-hosts}, or @option{--hostsdir}
@item
Execute DHCP lease change scripts for all existing leases
@item
Reread @file{/etc/resolv.conf} (only if @option{--no-poll} is configured).
@end itemize

@quotation Nota
The @code{SIGHUP} signal does not trigger a reload of the main configuration
file.
@end quotation

Example usage:
@example
herd reload dnsmasq
@end example

@item stats
When @command{dnsmasq} receives a @code{SIGUSR1} signal, it writes
statistics to the system log including:

@itemize @bullet
@item
Cache size and number of evicted entries
@item
Cache hits, misses, and authoritative queries answered
@item
For each upstream server: queries sent and errors received
@item
TCP connection fork statistics.
@end itemize

Example usage:
@example
herd stats dnsmasq
@end example
@end table

@end defvar

@deftp {Tipo de dados} dnsmasq-configuration
Data type representing the configuration of dnsmasq.

@table @asis
@item @code{package} (default: @var{dnsmasq})
Package object of the dnsmasq server.

@item @code{shepherd-provision} (default: @code{'(dnsmasq)})
@itemx @code{shepherd-requirement} (default: @code{'(user-processes networking)})
This option can be used to provide a list of Shepherd service names
(symbols) provided by this service.  You might want to change the default
value if you intend to run several @command{dnsmasq} instances.

Likewise, @code{shepherd-requirement} is a list of Shepherd service names
(symbols) that this service will depend on.

@item @code{pid-file} (default: @code{"/run/dnsmasq.pid"})
Specify an alternate path for dnsmasq to record its process-id in.

@item @code{no-hosts?} (padrão: @code{#f})
When true, don't read the hostnames in /etc/hosts.

@item @code{port} (padrão: @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?} (padrão: @code{#t})
Accept DNS queries only from hosts whose address is on a local subnet, ie a
subnet for which an interface exists on the server.

@item @code{listen-addresses} (default: @code{'()})
Listen on the given IP addresses.

@item @code{resolv-file} (default: @code{"/etc/resolv.conf"})
The file to read the IP address of the upstream nameservers from.

@item @code{no-resolv?} (padrão: @code{#f})
When true, don't read @var{resolv-file}.

@item @code{forward-private-reverse-lookup?} (default: @code{#t})
When false, all reverse lookups for private IP ranges are answered with "no
such domain" rather than being forwarded upstream.

@item @code{query-servers-in-order?} (default: @code{#f})
When true, dnsmasq queries the servers in the same order as they appear in
@var{servers}.

@item @code{servers} (default: @code{'()})
Specify IP address of upstream servers directly.

@item @code{servers-file} (default: @code{#f})
Specify file containing upstream servers. This file is re-read when dnsmasq
receives SIGHUP.  Could be either a string or a file-like object.

@item @code{addresses} (default: @code{'()})
For each entry, specify an IP address to return for any host in the given
domains.  Queries in the domains are never forwarded and always replied to
with the specified IP address.

This is useful for redirecting hosts locally, for example:

@lisp
(service dnsmasq-service-type
         (dnsmasq-configuration
           (addresses
             '(; Redirect to a local web-server.
               "/example.org/127.0.0.1"
               ; Redirect subdomain to a specific IP.
               "/subdomain.example.org/192.168.1.42"))))
@end lisp

Note that rules in @file{/etc/hosts} take precedence over this.

@item @code{cache-size} (padrão: @code{150})
Set the size of dnsmasq's cache.  Setting the cache size to zero disables
caching.

@item @code{negative-cache?} (padrão: @code{#t})
When false, disable negative caching.

@item @code{cpe-id} (default: @code{#f})
If set, add a CPE (Customer-Premises Equipment) identifier to DNS queries
which are forwarded upstream.

@item @code{tftp-enable?} (default: @code{#f})
Whether to enable the built-in TFTP server.

@item @code{tftp-no-fail?} (default: @code{#f})
If true, does not fail dnsmasq if the TFTP server could not start up.

@item @code{tftp-single-port?} (default: @code{#f})
Whether to use only one single port for TFTP.

@item @code{tftp-secure?} (default: @code{#f})
If true, only files owned by the user running the dnsmasq process are
accessible.

If dnsmasq is being run as root, different rules apply: @code{tftp-secure?}
has no effect, but only files which have the world-readable bit set are
accessible.

@item @code{tftp-max} (default: @code{#f})
If set, sets the maximal number of concurrent connections allowed.

@item @code{tftp-mtu} (default: @code{#f})
If set, sets the MTU for TFTP packets to that value.

@item @code{tftp-no-blocksize?} (default: @code{#f})
If true, stops the TFTP server from negotiating the blocksize with a client.

@item @code{tftp-lowercase?} (default: @code{#f})
Whether to convert all filenames in TFTP requests to lowercase.

@item @code{tftp-port-range} (default: @code{#f})
If set, fixes the dynamical ports (one per client) to the given range
(@code{"<start>,<end>"}).

@item @code{tftp-root} (default: @code{/var/empty,lo})
Look for files to transfer using TFTP relative to the given directory.  When
this is set, TFTP paths which include @samp{..} are rejected, to stop
clients getting outside the specified root.  Absolute paths (starting with
@samp{/}) are allowed, but they must be within the TFTP-root.  If the
optional interface argument is given, the directory is only used for TFTP
requests via that interface.

@item @code{tftp-unique-root} (default: @code{#f})
If set, add the IP or hardware address of the TFTP client as a path
component on the end of the TFTP-root.  Only valid if a TFTP root is set and
the directory exists.  Defaults to adding IP address (in standard
dotted-quad format).

For instance, if @option{--tftp-root} is @samp{/tftp} and client
@samp{1.2.3.4} requests file @file{myfile} then the effective path will be
@file{/tftp/1.2.3.4/myfile} if @file{/tftp/1.2.3.4} exists or
@file{/tftp/myfile} otherwise.  When @samp{=mac} is specified it will append
the MAC address instead, using lowercase zero padded digits separated by
dashes, e.g.: @samp{01-02-03-04-aa-bb}.  Note that resolving MAC addresses
is only possible if the client is in the local network or obtained a DHCP
lease from dnsmasq.

@item @code{conf-file} (default: @code{'()})
File names of configuration files to use.  Strings and file-like objects are
accepted.

@item @code{conf-dir} (default: @code{#f})
Read all the files in the given directory as configuration files.  Support
for @command{dnsmasq} field extensions is not implemented; users can use
@code{computed-file} to build a directory of files instead.  The
configuration files are loaded in alphabetical order of file name.

@item @code{extra-options} (default: @code{'()})
This option provides an ``escape hatch'' for the user to provide arbitrary
command-line arguments to @command{dnsmasq} as a list of strings.

@end table
@end deftp

@subsubheading Unbound Service

@defvar unbound-service-type
This is the type of the service to run @uref{https://www.unbound.net,
Unbound}, a validating, recursive, and caching DNS resolver.  Its value must
be a @code{unbound-configuration} object as in this example:

@lisp
(service unbound-service-type
         (unbound-configuration
          (forward-zone
           (list
            (unbound-zone
             (name ".")
             (forward-addr '("149.112.112.112#dns.quad9.net"
                             "2620:fe::9#dns.quad9.net"))
             (forward-tls-upstream #t))))))
@end lisp
@end defvar

@deftp {Data Type} unbound-configuration
Available @code{unbound-configuration} fields are:

@table @asis
@item @code{server} (type: unbound-server)
General options for the Unbound server.

@item @code{remote-control} (type: unbound-remote)
Remote control options for the daemon.

@item @code{forward-zone} (default: @code{()}) (type: list-of-unbound-zone)
A zone for which queries should be forwarded to another resolver.

@item @code{extra-content} (type: maybe-string)
Raw content to add to the configuration file.

@end table
@end deftp

@deftp {Data Type} unbound-server
Available @code{unbound-server} fields are:

@table @asis
@item @code{interface} (type: maybe-list-of-strings)
Interfaces listened on for queries from clients.

@item @code{hide-version} (type: maybe-boolean)
Refuse the version.server and version.bind queries.

@item @code{hide-identity} (type: maybe-boolean)
Refuse the id.server and hostname.bind queries.

@item @code{tls-cert-bundle} (type: maybe-string)
Certificate bundle file, used for DNS over TLS.

@item @code{extra-options} (default: @code{()}) (type: alist)
An association list of options to append.

@end table
@end deftp

@deftp {Data Type} unbound-remote
Available @code{unbound-remote} fields are:

@table @asis
@item @code{control-enable} (type: maybe-boolean)
Enable remote control.

@item @code{control-interface} (type: maybe-string)
IP address or local socket path to listen on for remote control.

@item @code{extra-options} (default: @code{()}) (type: alist)
An association list of options to append.

@end table
@end deftp

@deftp {Data Type} unbound-zone
Available @code{unbound-zone} fields are:

@table @asis
@item @code{name} (type: string)
Zone name.

@item @code{forward-addr} (type: maybe-list-of-strings)
IP address of server to forward to.

@item @code{forward-tls-upstream} (type: maybe-boolean)
Whether the queries to this forwarder use TLS for transport.

@item @code{extra-options} (default: @code{()}) (type: alist)
An association list of options to append.

@end table
@end deftp

@node VNC Services
@subsection VNC Services
@cindex VNC (virtual network computing)
@cindex XDMCP (x display manager control protocol)

The @code{(gnu services vnc)} module provides services related to
@dfn{Virtual Network Computing} (VNC), which makes it possible to locally
use graphical Xorg applications running on a remote machine.  Combined with
a graphical manager that supports the @dfn{X Display Manager Control
Protocol}, such as GDM (@pxref{gdm}) or LightDM (@pxref{lightdm}), it is
possible to remote an entire desktop for a multi-user environment.

@subsubheading Xvnc

Xvnc is a VNC server that spawns its own X window server; which means it can
run on headless servers.  The Xvnc implementations provided by the
@code{tigervnc-server} and @code{turbovnc} aim to be fast and efficient.

@defvar xvnc-service-type

The @code{xvnc-service-type} service can be configured via the
@code{xvnc-configuration} record, documented below.  A second virtual
display could be made available on a remote machine via the following
configuration:
@end defvar

@lisp
(service xvnc-service-type
         (xvnc-configuration (display-number 10)))
@end lisp

As a demonstration, the @command{xclock} command could then be started on
the remote machine on display number 10, and it could be displayed locally
via the @command{vncviewer} command:
@example
# Start xclock on the remote machine.
ssh -L5910:localhost:5910 @var{your-host} -- guix shell xclock \
    -- env DISPLAY=:10 xclock
# Access it via VNC.
guix shell tigervnc-client -- vncviewer localhost:5910
@end example

The following configuration combines XDMCP and Inetd to allow multiple users
to concurrently use the remote system and login graphically via the GDM
display manager:

@lisp
(operating-system
  [...]
  (services (cons*
             [...]
             (service xvnc-service-type (xvnc-configuration
                                         (display-number 5)
                                         (localhost? #f)
                                         (xdmcp? #t)
                                         (inetd? #t)))
             (modify-services %desktop-services
               (gdm-service-type config => (gdm-configuration
                                            (inherit config)
                                            (auto-suspend? #f)
                                            (xdmcp? #t)))))))
@end lisp

A remote user could then connect to it by using the @command{vncviewer}
command or a compatible VNC client and start a desktop session of their
choosing:
@example
vncviewer remote-host:5905
@end example

@quotation Aviso
Unless your machine is in a controlled environment, for security reasons,
the @code{localhost?} configuration of the @code{xvnc-configuration} record
should be left to its default @code{#t} value and exposed via a secure means
such as an SSH port forward.  The XDMCP port, UDP 177 should also be blocked
from the outside by a firewall, as it is not a secure protocol and can
expose login credentials in clear.
@end quotation

@c Use (configuration->documentation 'xvnc-configuration) to regenerate
@c the documentation.
@c %start of fragment
@deftp {Tipo de dados} xvnc-configuration
Available @code{xvnc-configuration} fields are:

@table @asis
@item @code{xvnc} (default: @code{tigervnc-server}) (type: file-like)
The package that provides the Xvnc binary.

@item @code{display-number} (default: @code{0}) (type: number)
The display number used by Xvnc.  You should set this to a number not
already used a Xorg server.

@item @code{geometry} (default: @code{"1024x768"}) (type: string)
The size of the desktop to be created.

@item @code{depth} (default: @code{24}) (type: color-depth)
The pixel depth in bits of the desktop to be created.  Accepted values are
16, 24 or 32.

@item @code{port} (type: maybe-port)
The port on which to listen for connections from viewers.  When left
unspecified, it defaults to 5900 plus the display number.

@item @code{ipv4?} (default: @code{#t}) (type: boolean)
Use IPv4 for incoming and outgoing connections.

@item @code{ipv6?} (default: @code{#t}) (type: boolean)
Use IPv6 for incoming and outgoing connections.

@item @code{password-file} (type: maybe-string)
The password file to use, if any.  Refer to vncpasswd(1) to learn how to
generate such a file.

@item @code{xdmcp?} (default: @code{#f}) (type: boolean)
Query the XDMCP server for a session.  This enables users to log in a
desktop session from the login manager screen.  For a multiple users
scenario, you'll want to enable the @code{inetd?} option as well, so that
each connection to the VNC server is handled separately rather than shared.

@item @code{inetd?} (default: @code{#f}) (type: boolean)
Use an Inetd-style service, which runs the Xvnc server on demand.

@item @code{frame-rate} (default: @code{60}) (type: number)
The maximum number of updates per second sent to each client.

@item @code{security-types} (default: @code{'("None")}) (type: security-types)
The allowed security schemes to use for incoming connections.  The default
is "None", which is safe given that Xvnc is configured to authenticate the
user via the display manager, and only for local connections.  Accepted
values are any of the following: ("None" "VncAuth" "Plain" "TLSNone"
"TLSVnc" "TLSPlain" "X509None" "X509Vnc")

@item @code{localhost?} (default: @code{#t}) (type: boolean)
Only allow connections from the same machine.  It is set to #true by default
for security, which means SSH or another secure means should be used to
expose the remote port.

@item @code{log-level} (default: @code{30}) (type: log-level)
The log level, a number between 0 and 100, 100 meaning most verbose output.
The log messages are output to syslog.

@item @code{extra-options} (default: @code{'()}) (type: strings)
This can be used to provide extra Xvnc options not exposed via this
<xvnc-configuration> record.

@end table

@end deftp
@c %end of fragment

@node Serviços VPN
@subsection Serviços VPN
@cindex VPN (virtual private network)
@cindex virtual private network (VPN)

The @code{(gnu services vpn)} module provides services related to
@dfn{virtual private networks} (VPNs).

@subsubheading Bitmask

@defvar bitmask-service-type
A service type for the @uref{https://bitmask.net, Bitmask} VPN client.  It
makes the client available in the system and loads its polkit policy.
Please note that the client expects an active polkit-agent, which is either
run by your desktop-environment or should be run manually.
@end defvar

@subsubheading OpenVPN

It provides a @emph{client} service for your machine to connect to a VPN,
and a @emph{server} service for your machine to host a VPN@.  Both
@code{openvpn-client-service-type} and @code{openvpn-server-service-type}
can be run simultaneously.

@defvar openvpn-client-service-type
Type of the service that runs @command{openvpn}, a VPN daemon, as a client.

The value for this service is a @code{<openvpn-client-configuration>}
object.
@end defvar

@defvar openvpn-server-service-type
Type of the service that runs @command{openvpn}, a VPN daemon, as a server.

The value for this service is a @code{<openvpn-server-configuration>}
object.
@end defvar

@c %automatically generated documentation

@deftp {Tipo de dados} openvpn-client-configuration
Available @code{openvpn-client-configuration} fields are:

@table @asis
@item @code{openvpn} (default: @code{openvpn}) (type: file-like)
The OpenVPN package.

@item @code{pid-file} (default: @code{"/var/run/openvpn/openvpn.pid"}) (type: string)
The OpenVPN pid file.

@item @code{proto} (default: @code{udp}) (type: proto)
The protocol (UDP or TCP) used to open a channel between clients and
servers.

@item @code{dev} (default: @code{tun}) (type: dev)
The device type used to represent the VPN connection.

@item @code{ca} (default: @code{"/etc/openvpn/ca.crt"}) (type: maybe-string)
The certificate authority to check connections against.

@item @code{cert} (default: @code{"/etc/openvpn/client.crt"}) (type: maybe-string)
The certificate of the machine the daemon is running on.  It should be
signed by the authority given in @code{ca}.

@item @code{key} (default: @code{"/etc/openvpn/client.key"}) (type: maybe-string)
The key of the machine the daemon is running on.  It must be the key whose
certificate is @code{cert}.

@item @code{comp-lzo?} (default: @code{#t}) (type: boolean)
Whether to use the lzo compression algorithm.

@item @code{persist-key?} (default: @code{#t}) (type: boolean)
Don't re-read key files across SIGUSR1 or --ping-restart.

@item @code{persist-tun?} (default: @code{#t}) (type: boolean)
Don't close and reopen TUN/TAP device or run up/down scripts across SIGUSR1
or --ping-restart restarts.

@item @code{fast-io?} (default: @code{#f}) (type: boolean)
(Experimental) Optimize TUN/TAP/UDP I/O writes by avoiding a call to
poll/epoll/select prior to the write operation.

@item @code{verbosity} (default: @code{3}) (type: number)
Verbosity level.

@item @code{tls-auth} (default: @code{#f}) (type: tls-auth-client)
Add an additional layer of HMAC authentication on top of the TLS control
channel to protect against DoS attacks.

@item @code{auth-user-pass} (type: maybe-string)
Authenticate with server using username/password.  The option is a file
containing username/password on 2 lines.  Do not use a file-like object as
it would be added to the store and readable by any user.

@item @code{verify-key-usage?} (default: @code{#t}) (type: key-usage)
Whether to check the server certificate has server usage extension.

@item @code{bind?} (default: @code{#f}) (type: bind)
Bind to a specific local port number.

@item @code{resolv-retry?} (default: @code{#t}) (type: resolv-retry)
Retry resolving server address.

@item @code{remote} (default: @code{'()}) (type: openvpn-remote-list)
A list of remote servers to connect to.

@deftp {Tipo de dados} openvpn-remote-configuration
Available @code{openvpn-remote-configuration} fields are:

@table @asis
@item @code{name} (default: @code{"my-server"}) (type: string)
Nome do servidor.

@item @code{port} (default: @code{1194}) (type: number)
Port number the server listens to.

@end table

@end deftp

@end table

@end deftp

@c %end of automatic openvpn-client documentation

@c %automatically generated documentation

@deftp {Tipo de dados} openvpn-server-configuration
Available @code{openvpn-server-configuration} fields are:

@table @asis
@item @code{openvpn} (default: @code{openvpn}) (type: file-like)
The OpenVPN package.

@item @code{pid-file} (default: @code{"/var/run/openvpn/openvpn.pid"}) (type: string)
The OpenVPN pid file.

@item @code{proto} (default: @code{udp}) (type: proto)
The protocol (UDP or TCP) used to open a channel between clients and
servers.

@item @code{dev} (default: @code{tun}) (type: dev)
The device type used to represent the VPN connection.

@item @code{ca} (default: @code{"/etc/openvpn/ca.crt"}) (type: maybe-string)
The certificate authority to check connections against.

@item @code{cert} (default: @code{"/etc/openvpn/client.crt"}) (type: maybe-string)
The certificate of the machine the daemon is running on.  It should be
signed by the authority given in @code{ca}.

@item @code{key} (default: @code{"/etc/openvpn/client.key"}) (type: maybe-string)
The key of the machine the daemon is running on.  It must be the key whose
certificate is @code{cert}.

@item @code{comp-lzo?} (default: @code{#t}) (type: boolean)
Whether to use the lzo compression algorithm.

@item @code{persist-key?} (default: @code{#t}) (type: boolean)
Don't re-read key files across SIGUSR1 or --ping-restart.

@item @code{persist-tun?} (default: @code{#t}) (type: boolean)
Don't close and reopen TUN/TAP device or run up/down scripts across SIGUSR1
or --ping-restart restarts.

@item @code{fast-io?} (default: @code{#f}) (type: boolean)
(Experimental) Optimize TUN/TAP/UDP I/O writes by avoiding a call to
poll/epoll/select prior to the write operation.

@item @code{verbosity} (default: @code{3}) (type: number)
Verbosity level.

@item @code{tls-auth} (default: @code{#f}) (type: tls-auth-server)
Add an additional layer of HMAC authentication on top of the TLS control
channel to protect against DoS attacks.

@item @code{port} (default: @code{1194}) (type: number)
Specifies the port number on which the server listens.

@item @code{server} (default: @code{"10.8.0.0 255.255.255.0"}) (type: ip-mask)
An ip and mask specifying the subnet inside the virtual network.

@item @code{server-ipv6} (default: @code{#f}) (type: cidr6)
A CIDR notation specifying the IPv6 subnet inside the virtual network.

@item @code{dh} (default: @code{"/etc/openvpn/dh2048.pem"}) (type: string)
The Diffie-Hellman parameters file.

@item @code{ifconfig-pool-persist} (default: @code{"/etc/openvpn/ipp.txt"}) (type: string)
The file that records client IPs.

@item @code{redirect-gateway?} (default: @code{#f}) (type: gateway)
When true, the server will act as a gateway for its clients.

@item @code{client-to-client?} (default: @code{#f}) (type: boolean)
When true, clients are allowed to talk to each other inside the VPN.

@item @code{keepalive} (default: @code{(10 120)}) (type: keepalive)
Causes ping-like messages to be sent back and forth over the link so that
each side knows when the other side has gone down.  @code{keepalive}
requires a pair.  The first element is the period of the ping sending, and
the second element is the timeout before considering the other side down.

@item @code{max-clients} (default: @code{100}) (type: number)
The maximum number of clients.

@item @code{status} (default: @code{"/var/run/openvpn/status"}) (type: string)
The status file.  This file shows a small report on current connection.  It
is truncated and rewritten every minute.

@item @code{client-config-dir} (default: @code{'()}) (type: openvpn-ccd-list)
The list of configuration for some clients.

@end table

@end deftp

@c %end of automatic openvpn-server documentation

@subheading strongSwan

Currently, the strongSwan service only provides legacy-style configuration
with @file{ipsec.conf} and @file{ipsec.secrets} files.

@defvar strongswan-service-type
A service type for configuring strongSwan for IPsec @acronym{VPN, Virtual
Private Networking}.  Its value must be a @code{strongswan-configuration}
record as in this example:

@lisp
(service strongswan-service-type
         (strongswan-configuration
          (ipsec-conf "/etc/ipsec.conf")
          (ipsec-secrets "/etc/ipsec.secrets")))
@end lisp

@end defvar

@deftp {Tipo de dados} strongswan-configuration
Data type representing the configuration of the StrongSwan service.

@table @asis
@item @code{strongswan}
The strongSwan package to use for this service.

@item @code{ipsec-conf} (default: @code{#f})
The file name of your @file{ipsec.conf}.  If not @code{#f}, then this and
@code{ipsec-secrets} must both be strings.

@item @code{ipsec-secrets} (default @code{#f})
The file name of your @file{ipsec.secrets}.  If not @code{#f}, then this and
@code{ipsec-conf} must both be strings.

@end table
@end deftp

@subsubheading Wireguard

@defvar wireguard-service-type
A service type for a Wireguard tunnel interface.  Its value must be a
@code{wireguard-configuration} record as in this example:

@lisp
(service wireguard-service-type
         (wireguard-configuration
          (peers
           (list
            (wireguard-peer
             (name "my-peer")
             (endpoint "my.wireguard.com:51820")
             (public-key "hzpKg9X1yqu1axN6iJp0mWf6BZGo8m1wteKwtTmDGF4=")
             (allowed-ips '("10.0.0.2/32")))))))
@end lisp

@end defvar

@deftp {Tipo de dados} wireguard-configuration
Data type representing the configuration of the Wireguard service.

@table @asis
@item @code{wireguard}
The wireguard package to use for this service.

@item @code{interface} (default: @code{"wg0"})
The interface name for the VPN.

@item @code{addresses} (default: @code{'("10.0.0.1/32")})
List of strings or G-expressions which represent the IP addresses to be
assigned to the above interface.

@item @code{port} (padrão: @code{51820})
The port on which to listen for incoming connections.

@item @code{dns} (default: @code{'())})
List of strings or G-expressions which represent the DNS server(s) to
announce to VPN clients via DHCP.

@item @code{monitor-ips?} (default: @code{#f})
@cindex Dynamic IP, with Wireguard
@cindex dyndns, usage with Wireguard
Whether to monitor the resolved Internet addresses (IPs) of the endpoints of
the configured peers, resetting the peer endpoints using an IP address that
no longer correspond to their freshly resolved host name.  Set this to
@code{#t} if one or more endpoints use host names provided by a dynamic DNS
service to keep the sessions alive.

@item @code{monitor-ips-interval} (default: @code{"*/5 * * * *"})
This is the monitoring schedule, expressed as a string in traditional cron
syntax or as a gexp evaluating to a Shepherd calendar event
(@pxref{Timers,,, shepherd, The GNU Shepherd Manual}).

@item @code{private-key} (default: @code{"/etc/wireguard/private.key"})
The private key file for the interface.  It is automatically generated if
the file does not exist.  If this field is @code{#f}, a private key is not
automatically created and the path is not serialized to the configuration
file.

@item @code{bootstrap-private-key?} (default: @code{#t})
Whether or not the private key should be generated automatically if it does
not exist.

Setting this to @code{#f} allows one to set the private key using command
substitution.  One example shown in the @code{wg-quick(8)} manual is
retrieving a private key using @code{password-store}.  This can be achieved
with the following code:

@lisp
(wireguard-configuration
 (private-key
  #~(string-append "<("
                   #$(file-append password-store "/bin/pass")
                   ;; Wireguard replaces %i with the interface name.
                   " WireGuard/private-keys/%i)")))
@end lisp


@item @code{peers} (default: @code{'()})
The authorized peers on this interface.  This is a list of
@var{wireguard-peer} records.

@item @code{pre-up} (default: @code{'()})
List of strings or G-expressions.  These are script snippets which will be
executed before setting up the interface.

@item @code{post-up} (default: @code{'()})
List of strings or G-expressions.  These are script snippets which will be
executed after setting up the interface.

@item @code{pre-down} (default: @code{'()})
List of strings or G-expressions.  These are script snippets which will be
executed before tearing down the interface.

@item @code{post-down} (default: @code{'()})
List of strings or G-expressions.  These are script snippets which will be
executed after tearing down the interface.

@item @code{shepherd-requirement} (default: @code{'()}) (type: list-of-symbols)
A list of symbols naming Shepherd services that this service will depend on.

@item @code{table} (default: @code{"auto"})
The routing table to which routes are added, as a string.  There are two
special values: @code{"off"} that disables the creation of routes
altogether, and @code{"auto"} (the default) that adds routes to the default
table and enables special handling of default routes.

@item @code{auto-start?} (default: @code{#t"})
Whether the Wireguard network should be started automatically by the
Shepherd.  If it is @code{#f} the service has to be started manually with
@code{herd start wireguard-$interface} (for example: @code{herd start
wireguard-wg0}).

@end table
@end deftp

@deftp {Tipo de dados} wireguard-peer
Data type representing a Wireguard peer attached to a given interface.

@table @asis
@item @code{name}
The peer name.

@item @code{endpoint} (default: @code{#f})
The optional endpoint for the peer, such as
@code{"demo.wireguard.com:51820"}.

@item @code{public-key}
The peer public-key represented as a base64 string.

@item @code{preshared-key} (default: @code{#f})
An optional pre-shared key file for this peer that can be either a string or
a G-expression.  The given file will not be autogenerated.

@item @code{allowed-ips}
A list of IP addresses from which incoming traffic for this peer is allowed
and to which incoming traffic for this peer is directed.

@item @code{keep-alive} (default: @code{#f})
An optional time interval in seconds.  A packet will be sent to the server
endpoint once per time interval.  This helps receiving incoming connections
from this peer when you are behind a NAT or a firewall.

@end table
@end deftp

@node Sistema de arquivos de rede
@subsection Sistema de arquivos de rede
@cindex NFS

The @code{(gnu services nfs)} module provides the following services, which
are most commonly used in relation to mounting or exporting directory trees
as @dfn{network file systems} (NFS).

While it is possible to use the individual components that together make up
a Network File System service, we recommended to configure an NFS server
with the @code{nfs-service-type}.

@subsubheading NFS Service
@cindex NFS, server

The NFS service takes care of setting up all NFS component services, kernel
configuration file systems, and installs configuration files in the
locations that NFS expects.

@defvar nfs-service-type
A service type for a complete NFS server.
@end defvar

@deftp {Tipo de dados} nfs-configuration
This data type represents the configuration of the NFS service and all of
its subsystems.

It has the following parameters:
@table @asis
@item @code{nfs-utils} (default: @code{nfs-utils})
The nfs-utils package to use.

@item @code{nfs-versions} (default: @code{'("4.2" "4.1" "4.0")})
If a list of string values is provided, the @command{rpc.nfsd} daemon will
be limited to supporting the given versions of the NFS protocol.

@item @code{exports} (default: @code{'()})
This is a list of directories the NFS server should export.  Each entry is a
list consisting of two elements: a directory name and a string containing
all options.  This is an example in which the directory @file{/export} is
served to all NFS clients as a read-only share:

@lisp
(nfs-configuration
 (exports
  '(("/export"
     "*(ro,insecure,no_subtree_check,crossmnt,fsid=0)"))))
@end lisp

@item @code{rpcmountd-port} (default: @code{#f})
The network port that the @command{rpc.mountd} daemon should use.

@item @code{rpcstatd-port} (default: @code{#f})
The network port that the @command{rpc.statd} daemon should use.

@item @code{rpcbind} (default: @code{rpcbind})
The rpcbind package to use.

@item @code{idmap-domain} (default: @code{"localdomain"})
The local NFSv4 domain name.

@item @code{nfsd-port} (default: @code{2049})
The network port that the @command{nfsd} daemon should use.

@item @code{nfsd-threads} (default: @code{8})
The number of threads used by the @command{nfsd} daemon.

@item @code{nfsd-tcp?} (default: @code{#t})
Whether the @command{nfsd} daemon should listen on a TCP socket.

@item @code{nfsd-udp?} (default: @code{#f})
Whether the @command{nfsd} daemon should listen on a UDP socket.

@item @code{pipefs-directory} (default: @code{"/var/lib/nfs/rpc_pipefs"})
The directory where the pipefs file system is mounted.

@item @code{debug} (default: @code{'()"})
A list of subsystems for which debugging output should be enabled.  This is
a list of symbols.  Any of these symbols are valid: @code{nfsd}, @code{nfs},
@code{rpc}, @code{idmap}, @code{statd}, or @code{mountd}.
@end table
@end deftp

If you don't need a complete NFS service or prefer to build it yourself you
can use the individual component services that are documented below.

@subsubheading RPC Bind Service
@cindex rpcbind

The RPC Bind service provides a facility to map program numbers into
universal addresses.  Many NFS related services use this facility.  Hence it
is automatically started when a dependent service starts.

@defvar rpcbind-service-type
A service type for the RPC portmapper daemon.
@end defvar


@deftp {Tipo de dados} rpcbind-configuration
Data type representing the configuration of the RPC Bind Service.  This type
has the following parameters:
@table @asis
@item @code{rpcbind} (default: @code{rpcbind})
The rpcbind package to use.

@item @code{warm-start?} (default: @code{#t})
If this parameter is @code{#t}, then the daemon will read a state file on
startup thus reloading state information saved by a previous instance.
@end table
@end deftp


@subsubheading Pipefs Pseudo File System
@cindex pipefs
@cindex rpc_pipefs

The pipefs file system is used to transfer NFS related data between the
kernel and user space programs.

@defvar pipefs-service-type
A service type for the pipefs pseudo file system.
@end defvar

@deftp {Tipo de dados} pipefs-configuration
Data type representing the configuration of the pipefs pseudo file system
service.  This type has the following parameters:
@table @asis
@item @code{mount-point} (default: @code{"/var/lib/nfs/rpc_pipefs"})
The directory to which the file system is to be attached.
@end table
@end deftp


@subsubheading GSS Daemon Service
@cindex GSSD
@cindex GSS
@cindex global security system

The @dfn{global security system} (GSS) daemon provides strong security for
RPC based protocols.  Before exchanging RPC requests an RPC client must
establish a security context.  Typically this is done using the Kerberos
command @command{kinit} or automatically at login time using PAM services
(@pxref{Serviços Kerberos}).

@defvar gss-service-type
A service type for the Global Security System (GSS) daemon.
@end defvar

@deftp {Tipo de dados} gss-configuration
Data type representing the configuration of the GSS daemon service.  This
type has the following parameters:
@table @asis
@item @code{nfs-utils} (default: @code{nfs-utils})
The package in which the @command{rpc.gssd} command is to be found.

@item @code{pipefs-directory} (default: @code{"/var/lib/nfs/rpc_pipefs"})
The directory where the pipefs file system is mounted.

@end table
@end deftp


@subsubheading IDMAP Daemon Service
@cindex idmapd
@cindex name mapper

The idmap daemon service provides mapping between user IDs and user names.
Typically it is required in order to access file systems mounted via NFSv4.

@defvar idmap-service-type
A service type for the Identity Mapper (IDMAP) daemon.
@end defvar

@deftp {Tipo de dados} idmap-configuration
Data type representing the configuration of the IDMAP daemon service.  This
type has the following parameters:
@table @asis
@item @code{nfs-utils} (default: @code{nfs-utils})
The package in which the @command{rpc.idmapd} command is to be found.

@item @code{pipefs-directory} (default: @code{"/var/lib/nfs/rpc_pipefs"})
The directory where the pipefs file system is mounted.

@item @code{domain} (padrão: @code{#f})
The local NFSv4 domain name.  This must be a string or @code{#f}.  If it is
@code{#f} then the daemon will use the host's fully qualified domain name.

@item @code{verbosity} (default: @code{0})
The verbosity level of the daemon.

@end table
@end deftp



@subsubheading Autofs Service
@cindex autofs
@cindex automount

The autofs service automatically mounts and unmounts filesystems.  It can
mount both network and local storage, but is most often used to manage NFS
mounts.

A typical configuration might look like:

@lisp
(operating-system
  (services
   (append
    (list
     (service nfs-service-type (nfs-configuration))
     (service autofs-service-type
              (autofs-configuration
               (mounts
                (list
                 (autofs-indirect-map
                  (mount-point "/net/home")
                  (entries
                   (list
                    ;; Accessing /net/home/foo will mount
                    ;; big.network.server:/home/foo.
                    (autofs-map-entry
                     (type "nfs")
                     (device "big.network.server:/home/&")
                     (mount-point "*"))))))))))
    %base-services)))
@end lisp

@deftp {Data Type} autofs-indirect-map
Available @code{autofs-indirect-map} fields are:

@table @asis
@item @code{mount-point} (type: string)
Where to mount the indirect map.

@item @code{entries} (default: @code{()}) (type: autofs-map-entries)
Entries in this map.

@end table
@end deftp

@deftp {Data Type} autofs-map-entry
Available @code{autofs-map-entry} fields are:

@table @asis
@item @code{type} (default: @code{"auto"}) (type: string)
The type of the filesystem.

@item @code{device} (type: string)
Device or remote host to mount.  May contain special character @code{&},
which can be referenced in the @var{mount-point} field.

@item @code{mount-point} (type: string)
Directory to mount this device on.  Map entries come in two flavors: direct
and indirect.  Direct entries map a single device to a single mountpoint,
while indirect entries can map multiple devices to multiple mountpoints.  A
direct entry has a @var{mount-point} beginning with @code{/}, representing
the absolute path of the directory to mount the device on.  For example:

@lisp
(autofs-map-entry
 (type "ext4")
 (device "/dev/sdb1")
 (mount-point "/mnt/external-disk"))
@end lisp

An indirect entry has a @var{mount-point} not beginning with @code{/},
representing the subdirectory within the parent indirect map for this
entry.  Indirect maps may also use the special character @code{*}, which
will be replaced with the value of special character @code{&} in the
@var{device} field of this entry.  For example:

@lisp
(autofs-indirect-map
 (mount-point "/devices")
 (entries
  (list
   ;; Automount any block device r/o by ID.
   (autofs-map-entry
    (type "auto")
    (mount-point "ro/uuid/*")
    (device "/dev/disk/by-id/&")
    (options '(ro)))
   ;; Automount any block device by UUID.
   (autofs-map-entry
    (type "auto")
    (mount-point "rw/uuid/*")
    (device "/dev/disk/by-uuid/&")))))
@end lisp

@item @code{options} (default: @code{()}) (type: file-system-options)
List of mount options.  Some options are simple flags, such as ro, noexec,
nosuid, etc.  These may be expressed as strings or symbols.  Other options
also accept a value.  These are expressed as pairs of @code{(option .
value)}.  @code{option} may be a string or symbol, as with flags.
@code{value} may be a string, symbol, or number.  Example: @code{(ro (errors
.  remount-ro) noexec)}

@end table
@end deftp

@deftp {Data Type} autofs-configuration
Available @code{autofs-configuration} fields are:

@table @asis
@item @code{autofs} (default: @code{autofs}) (type: package)
The autofs package to use.

@item @code{mounts} (default: @code{()}) (type: autofs-mount-maps)
Mount maps to manage.  This is a list of either direct map entries or
indirect mount maps.

@item @code{timeout} (default: @code{300}) (type: conf-integer)
Sets the default mount timeout in seconds.

@item @code{master-wait} (default: @code{10}) (type: conf-integer)
Sets the default maximum number of retries (actual iterations is half this,
each is delayed by 2 seconds before retrying) waiting for the master map to
become available if it cannot be read at program start.  This can be longer
if the map source itself waits for availability (such as sss).

@item @code{negative-timeout} (default: @code{60}) (type: conf-integer)
Set the default timeout for caching failed key lookups.

@item @code{mount-verbose?} (default: @code{#f}) (type: conf-boolean)
Use the verbose flag when spawning mount(8), and log some process info about
the requestor and its parent.

@item @code{mount-wait} (default: @code{-1}) (type: conf-integer)
Set the default time to wait for a response from a spawned mount(8)  before
sending it a SIGTERM.  Note that we still need to wait for the RPC layer to
timeout before the sub-process exits so this isn't ideal but it is the best
we can do.  The default is to wait until mount(8)  returns without
intervention.

@item @code{umount-wait} (default: @code{12}) (type: conf-integer)
Set the default time to wait for a response from a spawned umount(8)  before
sending it a SIGTERM.  Note that we still need to wait for the RPC layer to
timeout before the sub-process exits so this isn't ideal but it is the best
we can do.

@item @code{browse-mode?} (default: @code{#t}) (type: conf-boolean)
Should maps be browsable by default?

@item @code{mount-nfs-default-protocol} (default: @code{3}) (type: conf-integer)
Set the default protocol that mount.nfs(8) uses when performing a mount.
Autofs needs to know the default NFS protocol that mount.nfs(8) uses so it
can do special case handling for its availability probe for different NFS
protocols.  Since we can't identify this default automatically we need to
set it in the autofs configuration.

@item @code{append-options?} (default: @code{#t}) (type: conf-boolean)
When #t, global options are appended to map entry options.  When #f, map
entry options replace the global options.

@item @code{logging} (type: conf-log-level)
Default log level.  May be #:none, #:verbose, or #:debug.

@item @code{force-standard-program-map-env?} (default: @code{#f}) (type: conf-boolean)
Override the use of a prefix with standard environment variables when a
program map is executed.  Since program maps are run as the privileged user
setting these standard environment variables opens automount(8) to potential
user privilege escalation when the program map is written in a language that
can load components from, for example, a user home directory.

@item @code{map-hash-table-size} (default: @code{1024}) (type: conf-integer)
This configuration option may be used to change the number of hash table
slots.  This configuration option affects the overhead of searching the map
entry cache for map entries when there are a large number of entries.  It
affects the number of entries that must be looked at to locate a map entry
in the map entry cache.  For example, the default of 1024 and a direct map
with 8000 entries would result in each slot containing an average of 8
entries, which should be acceptable.  However, if excessive CPU usage is
observed during automount lookups increasing this option can reduce the CPU
overhead considerably because it reduces the length of the search chains.
Note that the number of entries in a map doesn't necessarily relate to the
number of entries used in the map entry cache.  There are two distinct cases
where the map hash table can make a significant difference, direct maps and
indirect maps that use the "browse" option.  For indirect maps that do not
use the "browse" option entries are added to the map entry cache at lookup
so the number of active cache entries, in this case, is usually much less
than the number of entries in the map.  In this last case it would be
unusual for the map entry cache to grow large enough to warrant increasing
the default before an event that cleans stale entries, a map re-read for
example.

@item @code{use-hostname-for-mounts?} (default: @code{#f}) (type: conf-boolean)
NFS mounts where the host name resolves to more than one IP address are
probed for availability and to establish the order in which mounts to them
should be tried.  To ensure that mount attempts are made only to hosts that
are responding and are tried in the order of hosts with the quickest
response the IP address of the host needs to be used for the mount.  If it
is necessary to use the hostname given in the map entry for the mount
regardless, then set this option to #t.  Be aware that if this is done there
is no defense against the host name resolving to one that isn't responding
and while the number of attempts at a successful mount will correspond to
the number of addresses the host name resolves to the order will also not
correspond to fastest responding hosts.

@item @code{disable-not-found-message?} (default: @code{#f}) (type: conf-boolean)
The original request to add this log message needed it to be unconditional.
That produces, IMHO, unnecessary noise in the log so a configuration option
has been added to provide the ability to turn it off.

@item @code{use-ignore-mount-option?} (default: @code{#f}) (type: conf-boolean)
An option to enable the use of autofs pseudo option "disable".  This option
is used as a hint to user space that the mount entry should be omitted from
mount table listings.  The default is #f to avoid unexpected changes in
behaviour and so is an opt-in setting.

@item @code{sss-master-map-wait} (default: @code{0}) (type: conf-integer)
Set the time to wait and retry if sssd is unable to read the master map at
program start.  Default is 0 (don't wait) or 10 if sss supports returning
EHSTDOWN when the provider isn't available.  If the sss library upports
returning EHOSTDOWN when the provider is down then this value is how long to
wait between re‐ tries reading the master map.  When reading dependent maps
or looking up a map key this value is multiplied by the number of retries
that would be used when reading the master map.

@item @code{use-mount-request-log-id?} (default: @code{#f}) (type: conf-boolean)
Set whether to use a mount request log id so that log entries for specific
mount requests can be easily identified in logs that have multiple
concurrent requests.

@end table

@end deftp


@c %end of fragment



@node Samba Services, Integração Contínua, Sistema de arquivos de rede, Serviços
@subsection Samba Services

@cindex Samba
@cindex SMB
The @code{(gnu services samba)} module provides service definitions for
Samba as well as additional helper services.  Currently it provides the
following services.

@subsubheading Samba

@uref{https://www.samba.org, Samba} provides network shares for folders and
printers using the SMB/CIFS protocol commonly used on Windows.  It can also
act as an Active Directory Domain Controller (AD DC) for other hosts in an
heterougenious network with different types of Computer systems.

@defvar samba-service-type

The service type to enable the samba services @code{samba}, @code{nmbd},
@code{smbd} and @code{winbindd}.  By default this service type does not run
any of the Samba daemons; they must be enabled individually.

Below is a basic example that configures a simple, anonymous
(unauthenticated) Samba file share exposing the @file{/public} directory.

@quotation Dica
The @file{/public} directory and its contents must be world
readable/writable, so you'll want to run @samp{chmod -R 777 /public} on it.
@end quotation

@quotation Caution
Such a Samba configuration should only be used in controlled environments,
and you should not share any private files using it, as anyone connecting to
your network would be able to access them.
@end quotation

@lisp
(service samba-service-type (samba-configuration
                             (enable-smbd? #t)
                             (config-file (plain-file "smb.conf" "\
[global]
map to guest = Bad User
logging = syslog@@1

[public]
browsable = yes
path = /public
read only = no
guest ok = yes
guest only = yes\n"))))
@end lisp

@end defvar

@deftp {Tipo de dados} samba-service-configuration
Configuration record for the Samba suite.

@table @asis
@item @code{package} (default: @code{samba})
The samba package to use.

@item @code{config-file} (default: @code{#f})
The config file to use.  To learn about its syntax, run @samp{man smb.conf}.

@item @code{enable-samba?} (default: @code{#f})
Enable the @code{samba} daemon.

@item @code{enable-smbd?} (default: @code{#f})
Enable the @code{smbd} daemon.

@item @code{enable-nmbd?} (default: @code{#f})
Enable the @code{nmbd} daemon.

@item @code{enable-winbindd?} (default: @code{#f})
Enable the @code{winbindd} daemon.

@end table
@end deftp

@cindex wsdd, Web service discovery daemon
@subsubheading Daemon de Descoberta de Serviço da Web

The @acronym{WSDD, Web Service Discovery daemon} implements the
@uref{http://docs.oasis-open.org/ws-dd/discovery/1.1/os/wsdd-discovery-1.1-spec-os.html,
Web Services Dynamic Discovery} protocol that enables host discovery over
Multicast DNS, similar to what Avahi does.  It is a drop-in replacement for
SMB hosts that have had SMBv1 disabled for security reasons.

@defvar wsdd-service-type
Service type for the WSD host daemon.  The value for this service type is a
@code{wsdd-configuration} record.  The details for the
@code{wsdd-configuration} record type are given below.
@end defvar

@deftp {Tipo de dados} wsdd-configuration
This data type represents the configuration for the wsdd service.

@table @asis

@item @code{package} (default: @code{wsdd})
The wsdd package to use.

@item @code{ipv4only?} (default: @code{#f})
Only listen to IPv4 addresses.

@item @code{ipv6only} (default: @code{#f})
Only listen to IPv6 addresses.  Please note: Activating both options is not
possible, since there would be no IP versions to listen to.

@item @code{chroot} (default: @code{#f})
Chroot into a separate directory to prevent access to other directories.
This is to increase security in case there is a vulnerability in
@command{wsdd}.

@item @code{hop-limit} (default: @code{1})
Limit to the level of hops for multicast packets.  The default is @var{1}
which should prevent packets from leaving the local network.

@item @code{interface} (default: @code{'()})
Limit to the given list of interfaces to listen to.  By default wsdd will
listen to all interfaces.  Except the loopback interface is never used.

@item @code{uuid-device} (default: @code{#f})
The WSD protocol requires a device to have a UUID.  Set this to manually
assign the service a UUID.

@item @code{domain} (padrão: @code{#f})
Notify this host is a member of an Active Directory.

@item @code{host-name} (padrão: @code{#f})
Manually set the hostname rather than letting @command{wsdd} inherit this
host's hostname.  Only the host name part of a possible FQDN will be used in
the default case.

@item @code{preserve-case?} (default: @code{#f})
By default @command{wsdd} will convert the hostname in workgroup to all
uppercase.  The opposite is true for hostnames in domains.  Setting this
parameter will preserve case.

@item @code{workgroup} (default: @var{"WORKGROUP"})
Change the name of the workgroup.  By default @command{wsdd} reports this
host being member of a workgroup.

@end table
@end deftp

@node Integração Contínua
@subsection Integração Contínua

@cindex integração contínua
@uref{https://guix.gnu.org/cuirass/, Cuirass} is a continuous integration
tool for Guix.  It can be used both for development and for providing
substitutes to others (@pxref{Substitutos}).

The @code{(gnu services cuirass)} module provides the following service.

@defvr {Procedure} cuirass-service-type
The type of the Cuirass service.  Its value must be a
@code{cuirass-configuration} object, as described below.
@end defvr

To add build jobs, you have to set the @code{specifications} field of the
configuration.  For instance, the following example will build all the
packages provided by the @code{my-channel} channel.

@lisp
(define %cuirass-specs
  #~(list (specification
           (name 'my-channel)
           (build '(channels my-channel))
           (channels
            (cons (channel
                   (name 'my-channel)
                   (url "https://my-channel.git"))
                  %default-channels)))))

(service cuirass-service-type
         (cuirass-configuration
          (specifications %cuirass-specs)))
@end lisp

To build the @code{linux-libre} package defined by the default Guix channel,
one can use the following configuration.

@lisp
(define %cuirass-specs
  #~(list (specification
           (name 'my-linux)
           (build '(packages "linux-libre")))))

(service cuirass-service-type
         (cuirass-configuration
          (specifications %cuirass-specs)))
@end lisp

The other configuration possibilities, as well as the specification record
itself are described in the Cuirass manual (@pxref{Specifications,,,
cuirass, Cuirass}).

While information related to build jobs is located directly in the
specifications, global settings for the @command{cuirass} process are
accessible in other @code{cuirass-configuration} fields.

@deftp {Tipo de dados} cuirass-configuration
Data type representing the configuration of Cuirass.

@table @asis
@item @code{cuirass} (default: @code{cuirass})
The Cuirass package to use.

@item @code{log-file} (default: @code{"/var/log/cuirass.log"})
Location of the log file.

@item @code{web-log-file} (default: @code{"/var/log/cuirass-web.log"})
Location of the log file used by the web interface.

@item @code{cache-directory} (default: @code{"/var/cache/cuirass"})
Location of the repository cache.

@item @code{user} (default: @code{"cuirass"})
Owner of the @code{cuirass} process.

@item @code{group} (default: @code{"cuirass"})
Owner's group of the @code{cuirass} process.

@item @code{interval} (default: @code{300})
Number of seconds between the poll of the repositories followed by the
Cuirass jobs, by default.

Note that individual jobset specifications may override this in their
@code{period} field; the value specified here is only used for
specifications that use the default @code{period} value, which is zero.

@item @code{parallel-evaluations} (default: @code{#f})
Maximum number of jobset evaluations that may run concurrently.  If
@code{#f}, that number is determined based on a number of CPU cores, with an
upper bound of 8.

@item @code{ttl} (default: @code{2592000})
Duration to keep build results' GC roots alive, in seconds.

@item @code{evaluation-ttl} (default: 24 months)
Number of seconds after which an evaluation may be deleted from the
database.

@item @code{build-expiry} (default: 4 months)
Duration in seconds after which pending builds are canceled.  This helps
ensure that the backlog does not grow indefinitely.

@item @code{threads} (default: @code{#f})
@itemx @code{web-threads} (default: @code{#f})
Number of kernel threads to use for Cuirass (main process) and for the web
interface (the @command{cuirass web} program).  The default value should be
appropriate for most cases.

@item @code{parameters} (default: @code{#f})
Read parameters from the given @var{parameters} file.  The supported
parameters are described here (@pxref{Parameters,,, cuirass, Cuirass}).

@item @code{remote-server} (default: @code{#f})
A @code{cuirass-remote-server-configuration} record to use the build remote
mechanism or @code{#f} to use the default build mechanism.

@item @code{database} (default: @code{"dbname=cuirass host=/var/run/postgresql"})
Use @var{database} as the database containing the jobs and the past build
results. Since Cuirass uses PostgreSQL as a database engine, @var{database}
must be a string such as @code{"dbname=cuirass host=localhost"}.

@item @code{port} (padrão: @code{8081})
Port number used by the HTTP server.

@item @code{host} (default: @code{"localhost"})
Listen on the network interface for @var{host}.  The default is to accept
connections from localhost.

@item @code{specifications} (default: @code{#~'()})
A gexp (@pxref{Expressões-G}) that evaluates to a list of specifications
records.  The specification record is described in the Cuirass manual
(@pxref{Specifications,,, cuirass, Cuirass}).

@item @code{one-shot?} (default: @code{#f})
Only evaluate specifications and build derivations once.

@item @code{fallback?} (padrão: @code{#f})
When substituting a pre-built binary fails, fall back to building packages
locally.

@item @code{extra-options} (default: @code{'()})
Extra options to pass when running the @code{cuirass register} process.

@item @code{web-extra-options} (default: @code{'()})
Extra options to pass when running the @code{cuirass web} process.

@end table
@end deftp

@cindex remote build
@subsubheading Cuirass remote building

Cuirass supports two mechanisms to build derivations.

@itemize
@item Using the local Guix daemon.
This is the default build mechanism.  Once the build jobs are evaluated,
they are sent to the local Guix daemon.  Cuirass then listens to the Guix
daemon output to detect the various build events.

@item Using the remote build mechanism.
The build jobs are not submitted to the local Guix daemon.  Instead, a
remote server dispatches build requests to the connect remote workers,
according to the build priorities.

@end itemize

To enable this build mode a @code{cuirass-remote-server-configuration}
record must be passed as @code{remote-server} argument of the
@code{cuirass-configuration} record.  The
@code{cuirass-remote-server-configuration} record is described below.

This build mode scales way better than the default build mode.  This is the
build mode that is used on the GNU Guix build farm at
@url{https://ci.guix.gnu.org}.  It should be preferred when using Cuirass to
build large amount of packages.

@deftp {Tipo de dados} cuirass-remote-server-configuration
Data type representing the configuration of the Cuirass remote-server.

@table @asis
@item @code{backend-port} (default: @code{5555})
The TCP port for communicating with @code{remote-worker} processes using
ZMQ.  It defaults to @code{5555}.

@item @code{log-port} (default: @code{5556})
The TCP port of the log server.  It defaults to @code{5556}.

@item @code{publish-port} (default: @code{5557})
The TCP port of the publish server.  It defaults to @code{5557}.

@item @code{log-file} (default: @code{"/var/log/cuirass-remote-server.log"})
Location of the log file.

@item @code{cache} (default: @code{"/var/cache/cuirass/remote"})
Use @var{cache} directory to cache build log files.

@item @code{log-expiry} (default: 6 months)
The duration in seconds after which build logs collected by @command{cuirass
remote-worker} may be deleted.

@item @code{trigger-url} (default: @code{#f})
Once a substitute is successfully fetched, trigger substitute baking at
@var{trigger-url}.

@item @code{publish?} (padrão: @code{#t})
If set to false, do not start a publish server and ignore the
@code{publish-port} argument.  This can be useful if there is already a
standalone publish server standing next to the remote server.

@item @code{public-key}
@item @code{private-key}
Use the specific @var{file}s as the public/private key pair used to sign the
store items being published.

@end table
@end deftp

At least one remote worker must also be started on any machine of the local
network to actually perform the builds and report their status.

@deftp {Tipo de dados} cuirass-remote-worker-configuration
Data type representing the configuration of the Cuirass remote-worker.

@table @asis
@item @code{cuirass} (default: @code{cuirass})
The Cuirass package to use.

@item @code{workers} (default: @code{1})
Start @var{workers} parallel workers.

@item @code{server} (default: @code{#f})
Do not use Avahi discovery and connect to the given @code{server} IP address
instead.

@item @code{systems} (default: @code{(list (%current-system))})
Only request builds for the given @var{systems}.

@item @code{log-file} (default: @code{"/var/log/cuirass-remote-worker.log"})
Location of the log file.

@item @code{publish-port} (default: @code{5558})
The TCP port of the publish server.  It defaults to @code{5558}.

@item @code{substitute-urls} (default: @code{%default-substitute-urls})
The list of URLs where to look for substitutes by default.

@item @code{public-key}
@item @code{private-key}
Use the specific @var{file}s as the public/private key pair used to sign the
store items being published.

@end table
@end deftp

@subsubheading Laminar

@uref{https://laminar.ohwg.net/, Laminar} is a lightweight and modular
Continuous Integration service.  It doesn't have a configuration web UI
instead uses version-controllable configuration files and scripts.

Laminar encourages the use of existing tools such as bash and cron instead
of reinventing them.

@defvar laminar-service-type
The type of the Laminar service.  Its value must be a
@code{laminar-configuration} object, as described below.

All configuration values have defaults, a minimal configuration to get
Laminar running is shown below. By default, the web interface is available
on port 8080.

@lisp
(service laminar-service-type)
@end lisp
@end defvar

@deftp {Tipo de dados} laminar-configuration
Data type representing the configuration of Laminar.

@table @asis
@item @code{laminar} (default: @code{laminar})
The Laminar package to use.

@item @code{home-directory} (default: @code{"/var/lib/laminar"})
The directory for job configurations and run directories.

@item @code{supplementary-groups} (default: @code{()})
Supplementary groups for the Laminar user account.

@item @code{bind-http} (default: @code{"*:8080"})
The interface/port or unix socket on which laminard should listen for
incoming connections to the web frontend.

@item @code{bind-rpc} (default: @code{"unix-abstract:laminar"})
The interface/port or unix socket on which laminard should listen for
incoming commands such as build triggers.

@item @code{title} (default: @code{"Laminar"})
The page title to show in the web frontend.

@item @code{keep-rundirs} (default: @code{0})
Set to an integer defining how many rundirs to keep per job.  The
lowest-numbered ones will be deleted.  The default is 0, meaning all run
dirs will be immediately deleted.

@item @code{archive-url} (default: @code{#f})
The web frontend served by laminard will use this URL to form links to
artefacts archived jobs.

@item @code{base-url} (default: @code{#f})
Base URL to use for links to laminar itself.

@end table
@end deftp

@subsubheading Forgejo Runner

@cindex continuous integration, Forgejo
@cindex Forgejo, continuous integration
The @code{(gnu services ci)} also provides a service for
@uref{https://code.forgejo.org/forgejo/runner, Forgejo Runner}, a daemon
that connects to an instance of the @uref{https://forgejo.org, Forgejo code
collaboration tool} and runs jobs for continuous integration.

A minimal configuration mostly with default values that can be added to the
@code{services} field of your operating system looks like this:

@lisp
(service forgejo-runner-service-type
         (forgejo-runner-configuration
          (name "my-runner")
          (labels '("guix" "linux"))))
@end lisp

This provides a @code{forgejo-runner} Shepherd service.  That service will
initially fail to start; you will have to manually @dfn{register} the runner
against the Forgejo server by running a command like:

@example
herd register forgejo-runner @var{url} @var{token}
@end example

@noindent
... where the arguments are as follows:

@table @var
@item url
the URL of the Forgejo server---e.g., @indicateurl{https://codeberg.org};
@item token
an access token
@uref{https://forgejo.org/docs/latest/admin/runner-installation/#standard-registration,
provided by the Forgejo server}.
@end table

Once registration has succeeded, you can start the runner:

@example
herd enable forgejo-runner
herd start forgejo-runner
@end example

The runner then receives orders from the Forgejo server to execute
@dfn{actions}.  Actions are commands and workflows specified by YAML files
in the @file{.forgejo/workflows} directory of source code repositories---see
@uref{https://forgejo.org/docs/v7.0/user/actions/, the Forgejo Action
documentation} for more info.

Note that at the moment @code{forgejo-runner-service-type} lets you run only
one runner.  Details about the configuration of this service follow.

@defvar forgejo-runner-service-type
This is the service type for Forgejo Runner.  Its value must be a
@code{forgejo-runner-configuration} record, documented below.
@end defvar

@deftp {Data Type} forgejo-runner-configuration
This data type represents the configuration of an instance of
@code{forgejo-runner-service-type}.  It contains the following fields:

@table @asis
@item @code{package} (default: @code{forgejo-runner})
The Forgejo Runner package to use.

@item @code{name} (default: @code{#~(gethostname)})
Name of the runner as will be shown in the runner management interface of
Forgejo.

@item @code{labels} (default: @code{'("guix")})
List of
@uref{https://forgejo.org/docs/latest/admin/actions/#choosing-labels,
labels} representing the type of environment the runner provides and that
actions may refer to.

@item @code{capacity} (default: @code{1})
Number of tasks to be executed concurrently.

@item @code{timeout} (default: @code{(* 3 3600)})
Maximum duration of a job, in seconds.

@item @code{fetch-timeout} (default: @code{5})
Maximum duration for fetching the job from the Forgejo server, in seconds.

@item @code{fetch-interval} (default: @code{2})
Interval (in seconds) for fetching the job from the Forgejo server.

@item @code{report-interval} (default: @code{1})
Interval (in seconds) for reporting the job status and log to the Forgejo
server.

@item @code{data-directory} (default: @code{"/var/lib/forgejo-runner"})
Directory where @command{forgejo-runner} will store persistent data such as
its configuration and access token.

@item @code{run-directory} (default: @code{"/var/run/forgejo-runner"})
Directory where @command{forgejo-runner} stores cached data.

@item @code{log-file} (default: @code{"/var/log/forgejo-runner.log"})
Name of the @command{forgejo-runner} log file.

@end table
@end deftp

@node Serviços de gerenciamento de energia
@subsection Serviços de gerenciamento de energia

@cindex power-profiles-daemon
@subsubheading Power Profiles Daemon

The @code{(gnu services pm)} module provides a Guix service definition for
the Linux Power Profiles Daemon, which makes power profiles handling
available over D-Bus.

The available profiles consist of the default @samp{balanced} mode, a
@samp{power-saver} mode and on supported systems a @samp{performance} mode.

@quotation Importante
The @code{power-profiles-daemon} conflicts with other power management tools
like @code{tlp}. Using both together is not recommended.
@end quotation

@defvar power-profiles-daemon-service-type
This is the service type for the
@uref{https://gitlab.freedesktop.org/upower/power-profiles-daemon/, Power
Profiles Daemon}.  The value for this service is a
@code{power-profiles-daemon-configuration}.

To enable the Power Profiles Daemon with default configuration add this line
to your services:

@lisp
(service power-profiles-daemon-service-type)
@end lisp
@end defvar

@deftp {Tipo de dados} power-profiles-daemon-configuration
Data type representing the configuration of
@code{power-profiles-daemon-service-type}.

@table @asis
@item @code{power-profiles-daemon} (default: @code{power-profiles-daemon}) (type: file-like)
Package object of power-profiles-daemon.

@end table
@end deftp


@cindex tlp
@cindex power management with TLP
@subsubheading TLP daemon

The @code{(gnu services pm)} module provides a Guix service definition for
the Linux power management tool TLP.

TLP enables various powersaving modes in userspace and kernel.  Contrary to
@code{upower-service}, it is not a passive, monitoring tool, as it will
apply custom settings each time a new power source is detected.  More
information can be found at @uref{https://linrunner.de/en/tlp/tlp.html, TLP
home page}.

@defvar tlp-service-type
The service type for the TLP tool.  The default settings are optimised for
battery life on most systems, but you can tweak them to your heart's content
by adding a valid @code{tlp-configuration}:
@lisp
(service tlp-service-type
         (tlp-configuration
          (cpu-scaling-governor-on-ac (list "performance"))
          (sched-powersave-on-bat? #t)))
@end lisp
@end defvar

Each parameter definition is preceded by its type; for example,
@samp{boolean foo} indicates that the @code{foo} parameter should be
specified as a boolean.  Types starting with @code{maybe-} denote parameters
that won't show up in TLP config file when their value is left unset, or is
explicitly set to the @code{%unset-value} value.

@c The following documentation was initially generated by
@c (generate-tlp-documentation) in (gnu services pm).  Manually maintained
@c documentation is better, so we shouldn't hesitate to edit below as
@c needed.  However if the change you want to make to this documentation
@c can be done in an automated way, it's probably easier to change
@c (generate-documentation) than to make it below and have to deal with
@c the churn as TLP updates.

Available @code{tlp-configuration} fields are:

@deftypevr {@code{tlp-configuration} parameter} package tlp
The TLP package.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} boolean tlp-enable?
Set to true if you wish to enable TLP.

Defaults to @samp{#t}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} string tlp-default-mode
Default mode when no power supply can be detected.  Alternatives are AC and
BAT.

Defaults to @samp{"AC"}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} non-negative-integer disk-idle-secs-on-ac
Number of seconds Linux kernel has to wait after the disk goes idle, before
syncing on AC.

Defaults to @samp{0}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} non-negative-integer disk-idle-secs-on-bat
Same as @code{disk-idle-ac} but on BAT mode.

Defaults to @samp{2}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} non-negative-integer max-lost-work-secs-on-ac
Dirty pages flushing periodicity, expressed in seconds.

Defaults to @samp{15}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} non-negative-integer max-lost-work-secs-on-bat
Same as @code{max-lost-work-secs-on-ac} but on BAT mode.

Defaults to @samp{60}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list cpu-scaling-governor-on-ac
CPU frequency scaling governor on AC mode.  With intel_pstate driver,
alternatives are powersave and performance.  With acpi-cpufreq driver,
alternatives are ondemand, powersave, performance and conservative.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list cpu-scaling-governor-on-bat
Same as @code{cpu-scaling-governor-on-ac} but on BAT mode.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-scaling-min-freq-on-ac
Set the min available frequency for the scaling governor on AC.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-scaling-max-freq-on-ac
Set the max available frequency for the scaling governor on AC.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-scaling-min-freq-on-bat
Set the min available frequency for the scaling governor on BAT.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-scaling-max-freq-on-bat
Set the max available frequency for the scaling governor on BAT.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-min-perf-on-ac
Limit the min P-state to control the power dissipation of the CPU, in AC
mode.  Values are stated as a percentage of the available performance.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-max-perf-on-ac
Limit the max P-state to control the power dissipation of the CPU, in AC
mode.  Values are stated as a percentage of the available performance.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-min-perf-on-bat
Same as @code{cpu-min-perf-on-ac} on BAT mode.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-max-perf-on-bat
Same as @code{cpu-max-perf-on-ac} on BAT mode.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} maybe-boolean cpu-boost-on-ac?
Enable CPU turbo boost feature on AC mode.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} maybe-boolean cpu-boost-on-bat?
Same as @code{cpu-boost-on-ac?} on BAT mode.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} boolean sched-powersave-on-ac?
Allow Linux kernel to minimize the number of CPU cores/hyper-threads used
under light load conditions.

Defaults to @samp{#f}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} boolean sched-powersave-on-bat?
Same as @code{sched-powersave-on-ac?} but on BAT mode.

Defaults to @samp{#t}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} boolean nmi-watchdog?
Enable Linux kernel NMI watchdog.

Defaults to @samp{#f}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} maybe-string phc-controls
For Linux kernels with PHC patch applied, change CPU voltages.  An example
value would be @samp{"F:V F:V F:V F:V"}.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} string energy-perf-policy-on-ac
Set CPU performance versus energy saving policy on AC@.  Alternatives are
performance, normal, powersave.

Defaults to @samp{"performance"}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} string energy-perf-policy-on-bat
Same as @code{energy-perf-policy-ac} but on BAT mode.

Defaults to @samp{"powersave"}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} space-separated-string-list disks-devices
Hard disk devices.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} space-separated-string-list disk-apm-level-on-ac
Hard disk advanced power management level.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} space-separated-string-list disk-apm-level-on-bat
Same as @code{disk-apm-bat} but on BAT mode.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list disk-spindown-timeout-on-ac
Hard disk spin down timeout.  One value has to be specified for each
declared hard disk.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list disk-spindown-timeout-on-bat
Same as @code{disk-spindown-timeout-on-ac} but on BAT mode.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list disk-iosched
Select IO scheduler for disk devices.  One value has to be specified for
each declared hard disk.  Example alternatives are cfq, deadline and noop.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} string sata-linkpwr-on-ac
SATA aggressive link power management (ALPM) level.  Alternatives are
min_power, medium_power, max_performance.

Defaults to @samp{"max_performance"}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} string sata-linkpwr-on-bat
Same as @code{sata-linkpwr-ac} but on BAT mode.

Defaults to @samp{"min_power"}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} maybe-string sata-linkpwr-blacklist
Exclude specified SATA host devices for link power management.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} maybe-on-off-boolean ahci-runtime-pm-on-ac?
Enable Runtime Power Management for AHCI controller and disks on AC mode.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} maybe-on-off-boolean ahci-runtime-pm-on-bat?
Same as @code{ahci-runtime-pm-on-ac} on BAT mode.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} non-negative-integer ahci-runtime-pm-timeout
Seconds of inactivity before disk is suspended.

Defaults to @samp{15}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} string pcie-aspm-on-ac
PCI Express Active State Power Management level.  Alternatives are default,
performance, powersave.

Defaults to @samp{"performance"}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} string pcie-aspm-on-bat
Same as @code{pcie-aspm-ac} but on BAT mode.

Defaults to @samp{"powersave"}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer start-charge-thresh-bat0
Percentage when battery 0 should begin charging.  Only supported on some
laptops.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer stop-charge-thresh-bat0
Percentage when battery 0 should stop charging.  Only supported on some
laptops.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer start-charge-thresh-bat1
Percentage when battery 1 should begin charging.  Only supported on some
laptops.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer stop-charge-thresh-bat1
Percentage when battery 1 should stop charging.  Only supported on some
laptops.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} string radeon-power-profile-on-ac
Radeon graphics clock speed level.  Alternatives are low, mid, high, auto,
default.

Defaults to @samp{"high"}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} string radeon-power-profile-on-bat
Same as @code{radeon-power-ac} but on BAT mode.

Defaults to @samp{"low"}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} string radeon-dpm-state-on-ac
Radeon dynamic power management method (DPM).  Alternatives are battery,
performance.

Defaults to @samp{"performance"}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} string radeon-dpm-state-on-bat
Same as @code{radeon-dpm-state-ac} but on BAT mode.

Defaults to @samp{"battery"}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} string radeon-dpm-perf-level-on-ac
Radeon DPM performance level.  Alternatives are auto, low, high.

Defaults to @samp{"auto"}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} string radeon-dpm-perf-level-on-bat
Same as @code{radeon-dpm-perf-ac} but on BAT mode.

Defaults to @samp{"auto"}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} on-off-boolean wifi-pwr-on-ac?
Wifi power saving mode.

Defaults to @samp{#f}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} on-off-boolean wifi-pwr-on-bat?
Same as @code{wifi-power-ac?} but on BAT mode.

Defaults to @samp{#t}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} y-n-boolean wol-disable?
Disable wake on LAN.

Defaults to @samp{#t}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} non-negative-integer sound-power-save-on-ac
Timeout duration in seconds before activating audio power saving on Intel
HDA and AC97 devices.  A value of 0 disables power saving.

Defaults to @samp{0}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} non-negative-integer sound-power-save-on-bat
Same as @code{sound-powersave-ac} but on BAT mode.

Defaults to @samp{1}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} y-n-boolean sound-power-save-controller?
Disable controller in powersaving mode on Intel HDA devices.

Defaults to @samp{#t}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} boolean bay-poweroff-on-bat?
Enable optical drive in UltraBay/MediaBay on BAT mode.  Drive can be powered
on again by releasing (and reinserting) the eject lever or by pressing the
disc eject button on newer models.

Defaults to @samp{#f}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} string bay-device
Name of the optical drive device to power off.

Defaults to @samp{"sr0"}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} string runtime-pm-on-ac
Runtime Power Management for PCI(e) bus devices.  Alternatives are on and
auto.

Defaults to @samp{"on"}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} string runtime-pm-on-bat
Same as @code{runtime-pm-ac} but on BAT mode.

Defaults to @samp{"auto"}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} boolean runtime-pm-all?
Runtime Power Management for all PCI(e) bus devices, except blacklisted
ones.

Defaults to @samp{#t}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list runtime-pm-blacklist
Exclude specified PCI(e) device addresses from Runtime Power Management.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} space-separated-string-list runtime-pm-driver-blacklist
Exclude PCI(e) devices assigned to the specified drivers from Runtime Power
Management.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} boolean usb-autosuspend?
Enable USB autosuspend feature.

Defaults to @samp{#t}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} maybe-string usb-blacklist
Exclude specified devices from USB autosuspend.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} boolean usb-blacklist-wwan?
Exclude WWAN devices from USB autosuspend.

Defaults to @samp{#t}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} maybe-string usb-whitelist
Include specified devices into USB autosuspend, even if they are already
excluded by the driver or via @code{usb-blacklist-wwan?}.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} maybe-boolean usb-autosuspend-disable-on-shutdown?
Enable USB autosuspend before shutdown.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} boolean restore-device-state-on-startup?
Restore radio device state (bluetooth, wifi, wwan) from previous shutdown on
system startup.

Defaults to @samp{#f}.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} string cpu-energy-perf-policy-on-ac
Set CPU energy/performance policy when on AC mode.  Possible values, in
order of increasing power saving, are performance, balance_performance,
default, balance_power and power.

@end deftypevr

@deftypevr {@code{tlp-configuration} parameter} string cpu-energy-perf-policy-on-bat
Set CPU energy/performance policy when on BAT mode.  Possible values, in
order of increasing power saving, are performance, balance_performance,
default, balance_power and power.

@end deftypevr

@cindex thermald
@cindex CPU frequency scaling with thermald
@subsubheading Thermald daemon

The @code{(gnu services pm)} module provides an interface to thermald, a CPU
frequency scaling service which helps prevent overheating.

@defvar thermald-service-type
This is the service type for @uref{https://01.org/linux-thermal-daemon/,
thermald}, the Linux Thermal Daemon, which is responsible for controlling
the thermal state of processors and preventing overheating.
@end defvar

@deftp {Tipo de dados} thermald-configuration
Data type representing the configuration of @code{thermald-service-type}.

@table @asis
@item @code{adaptive?} (default: @code{#f})
Use @acronym{DPTF, Dynamic Power and Thermal Framework} adaptive tables when
present.

@item @code{ignore-cpuid-check?} (default: @code{#f})
Ignore cpuid check for supported CPU models.

@item @code{thermald} (default: @var{thermald})
Package object of thermald.

@cindex PowerTOP
@cindex power consumption tuning with PowerTOP
@subsubheading PowerTOP

The @code{(gnu services pm)} module also provides a service definition for
@uref{https://01.org/powertop/, PowerTOP}, a power consumption analysis and
tuning tool.  When started, it tunes Linux kernel settings to reduce power
consumption.

@defvar powertop-service-type
The service type for PowerTOP.  No configuration is necessary.  When the
service starts, it executes @code{powertop --auto-tune}.

@lisp
(service powertop-service-type)
@end lisp
@end defvar

Available @code{powertop-configuration} fields are:

@deftypevr {@code{powertop-configuration} parameter} package powertop
The PowerTOP package.  Defaults to @code{powertop} in the @code{(gnu
packages linux)} module

@end deftypevr

@end table
@end deftp

The @code{(gnu services power)} module provides a service definition for
@uref{http://www.apcupsd.org/, apcupsd}, a utility to interact with
@acronym{APC, APC by Schneider Electric or formerly American Power
Conversion Corporation} @acronym{UPS, Uninterruptible Power Supply}
devices.  Apcupsd also works with some @acronym{OEM, Original Equipment
Manufacturer}-branded products manufactured by APC.

@defvar apcupsd-service-type
The service type for apcupsd.  For USB UPSes no configuration is necessary,
however tweaking some fields to better suit your needs might be desirable.
The defaults are taken from the upstream configuration and they are not very
conservative (for example, the default @code{battery-level} of 5% may be
considered too low by some).

The default event handlers do send emails, read more in
@ref{apcupsd-event-handlers}.

@lisp
(service apcupsd-service-type)
@end lisp
@end defvar

@deftp {Data Type} apcupsd-configuration

Available @code{apcupsd-configuration} fields are:

@table @asis
@item @code{apcupsd} (default: @code{apcupsd}) (type: package)
The @code{apcupsd} package to use.

@item @code{shepherd-service-name} (default: @code{apcupsd}) (type: symbol)
The name of the shepherd service.  You can add the service multiple times
with different names to manage multiple UPSes.

@item @code{auto-start?} (default: @code{#t}) (type: boolean)
Should the shepherd service auto-start?

@item @code{pid-file} (default: @code{"/var/run/apcupsd.pid"}) (type: string)
The file name of the pid file.

@item @code{debug-level} (default: @code{0}) (type: integer)
The logging verbosity.  Bigger number means more logs.  The source code uses
up to @code{300} as debug level value, so a value of @code{999} seems
reasonable to enable all the logs.

@item @code{run-dir} (default: @code{"/var/run/apcupsd"}) (type: string)
The directory containing runtime information.  You need to change this if
you desire to run multiple instances of the daemon.

@item @code{name} (type: maybe-string)
Use this to give your UPS a name in log files and such.  This is
particularly useful if you have multiple UPSes.  This does not set the
EEPROM.  It should be 8 characters or less.

@item @code{cable} (default: @code{usb}) (type: enum-cable)
The type of a cable connecting the UPS to your computer.  Possible generic
choices are @code{'simple}, @code{'smart}, @code{'ether} and @code{'usb}.

Alternatively, a specific cable model number may be used: @code{'940-0119A},
@code{'940-0127A}, @code{'940-0128A}, @code{'940-0020B}, @code{'940-0020C},
@code{'940-0023A}, @code{'940-0024B}, @code{'940-0024C}, @code{'940-1524C},
@code{'940-0024G}, @code{'940-0095A}, @code{'940-0095B}, @code{'940-0095C},
@code{'940-0625A}, @code{'M-04-02-2000}.

@item @code{type} (default: @code{usb}) (type: enum-type)
The type of the UPS you have.

@table @code
@item apcsmart
Newer serial character device, appropriate for SmartUPS models using a
serial cable (not an USB).

@item usb
Most new UPSes are an USB.

@item net
Network link to a master apcupsd through apcupsd's Network Information
Server.  This is used if the UPS powering your computer is connected to a
different computer for monitoring.

@item snmp
SNMP network link to an SNMP-enabled UPS device.

@item netsnmp
Same as the SNMP above but requires use of the net-snmp library.  Unless you
have a specific need for this old driver, you should use the @code{'snmp}
instead.

@item dumb
An old serial character device for use with simple-signaling UPSes.

@item pcnet
A PowerChute Network Shutdown protocol which can be used as an alternative
to an SNMP with the AP9617 family of smart slot cards.

@item modbus
A serial device for use with newest SmartUPS models supporting the MODBUS
protocol.

@end table

@item @code{device} (default: @code{""}) (type: string)
For USB UPSes, usually you want to set this to an empty string (the
default).  For other UPS types, you must specify an appropriate port or
address.

@table @code
@item apcsmart
Set to the appropriate @file{/dev/tty**} device.

@item usb
A null string setting enables auto-detection, which is the best choice for
most installations.

@item net
Set to @code{@var{hostname}:@var{port}}.

@item snmp
Set to @code{@var{hostname}:@var{port}:@var{vendor}:@var{community}}.  The
@var{hostname} is the ip address or hostname of the UPS on the network.  The
@var{vendor} can be can be "APC" or "APC_NOTRAP".  "APC_NOTRAP" will disable
SNMP trap catching; you usually want "APC".  The @var{port} is usually 161.
The @var{community} is usually "private".

@item netsnmp
Same as the @code{'snmp}.

@item dumb
Set to the appropriate @file{/dev/tty**} device.

@item pcnet
Set to @code{@var{ipaddr}:@var{username}:@var{passphrase}:@var{port}}.  The
@var{ipaddr} is the IP address of the UPS management card.  The
@var{username} and the @var{passphrase} are the credentials for which the
card has been configured.  The @var{port} is the port number on which to
listen for messages from the UPS, normally 3052.  If this parameter is empty
or missing, the default of 3052 will be used.

@item modbus
Set to the appropriate @file{/dev/tty**} device.  You can also leave it
empty for MODBUS over USB or set to the serial number of the UPS.

@end table

@item @code{poll-time} (default: @code{60}) (type: integer)
The interval (in seconds) at which apcupsd polls the UPS for status.  This
setting applies both to directly-attached UPSes (apcsmart, usb, dumb) and
networked UPSes (net, snmp).  Lowering this setting will improve the
apcupsd's responsiveness to certain events at the cost of higher CPU
utilization.

@item @code{on-batery-delay} (default: @code{6}) (type: integer)
The time in seconds from when a power failure is detected until we react to
it with an onbattery event.  The @code{'powerout} event will be triggered
immediately when a power failure is detected.  However, the
@code{'onbattery} event will be trigger only after this delay.

@item @code{battery-level} (default: @code{5}) (type: integer)
If during a power failure, the remaining battery percentage (as reported by
the UPS) is below or equal to this value, the apcupsd will initiate a system
shutdown.

@quotation Nota
@code{battery-level}, @code{remaining-minutes}, and @code{timeout} work in a
conjunction, so the first that occurs will cause the initiation of a
shutdown.
@end quotation

@item @code{remaining-minutes} (default: @code{3}) (type: integer)
If during a power failure, the remaining runtime in minutes (as calculated
internally by the UPS) is below or equal to this value, apcupsd will
initiate a system shutdown.

@quotation Nota
@code{battery-level}, @code{remaining-minutes}, and @code{timeout} work in a
conjunction, so the first that occurs will cause the initiation of a
shutdown.
@end quotation

@item @code{timeout} (default: @code{0}) (type: integer)
If during a power failure, the UPS has run on batteries for this many
seconds or longer, apcupsd will initiate a system shutdown.  The value of 0
disables this timer.

@quotation Nota
@code{battery-level}, @code{remaining-minutes}, and @code{timeout} work in a
conjunction, so the first that occurs will cause the initiation of a
shutdown.
@end quotation

@item @code{annoy-interval} (default: @code{300}) (type: integer)
The time in seconds between annoying users (via the @code{'annoyme} event)
to sign off prior to system shutdown.  0 disables.

@item @code{annoy-delay} (default: @code{60}) (type: integer)
The initial delay in seconds after a power failure before warning users to
get off the system.

@item @code{no-logon} (default: @code{disable}) (type: enum-no-logon)
The condition which determines when users are prevented from logging in
during a power failure.

@item @code{kill-delay} (default: @code{0}) (type: integer)
If this is non-zero, the apcupsd will continue running after a shutdown has
been requested, and after the specified time in seconds attempt to kill the
power.  This is for use on systems where apcupsd cannot regain control after
a shutdown.

@item @code{net-server} (default: @code{#f}) (type: boolean)
If enabled, a network information server process will be started.

@item @code{net-server-ip} (default: @code{"127.0.0.1"}) (type: string)
An IP address on which the NIS server will listen for incoming connections.

@item @code{net-server-port} (default: @code{3551}) (type: integer)
An IP port on which the NIS server will listen for incoming connections.

@item @code{net-server-events-file} (type: maybe-string)
If you want the last few EVENTS to be available over the network by the
network information server, you must set this to a file name.

@item @code{net-server-events-file-max-size} (default: @code{10}) (type: integer)
The maximum size of the events file in kilobytes.

@item @code{class} (default: @code{standalone}) (type: enum-class)
Normally standalone unless you share an UPS using an APC ShareUPS card.

@item @code{mode} (default: @code{disable}) (type: enum-mode)
Normally disable unless you share an UPS using an APC ShareUPS card.

@item @code{stat-time} (default: @code{0}) (type: integer)
The time interval in seconds between writing the status file, 0 disables.

@item @code{log-stats} (default: @code{#f}) (type: boolean)
Also write the stats as a logs.  This generates a lot of output.

@item @code{data-time} (default: @code{0}) (type: integer)
The time interval in seconds between writing the data records to the log
file, 0 disables.

@item @code{facility} (type: maybe-string)
The logging facility for the syslog.

@item @code{event-handlers} (type: apcupsd-event-handlers)
Handlers for events produced by apcupsd.

@end table
@end deftp

@anchor{apcupsd-event-handlers}
@deftp {Data Type} apcupsd-event-handlers

For a description of the events please refer to @samp{man 8 apccontrol}.

Each handler shall be a gexp.  It is spliced into the control script for the
daemon.  In addition to the standard Guile programming environment, the
following procedures and variables are also available:

@table @code
@item conf
Variable containing the file name of the configuration file.

@item powerfail-file
Variable containing the file name of the powerfail file.

@item cmd
The event currently being handled.

@item name
The name of the UPS as specified in the configuration file.

@item connected?
Is @code{#t} if @command{apcupsd} is connected to the UPS via a serial port
(or a USB port).  In most configurations, this will be the case.  In the
case of a Slave machine where apcupsd is not directly connected to the UPS,
this value will be @code{#f}.

@item powered?
Is @code{#t} if the computer on which @command{apcupsd} is running is
powered by the UPS and @code{#f} if not.  At the moment, this value is
unimplemented and always @code{#f}.

@item (err @var{fmt} @var{args...})
Wrapper around @code{format} outputting to @code{(current-error-port)}.

@item (wall @var{fmt} @var{args...})
Wrapper around @code{format} outputting via @command{wall}.

@item (apcupsd @var{args...})
Call @command{apcupsd} while passing the correct configuration file and all
the arguments.

@item (mail-to-root @var{subject} @var{body})
Send an email to the local administrator.  This procedure assumes the
@command{sendmail} is located at @command{/run/privileged/bin/sendmail} (as
would be the case with @code{opensmtpd-service-type}).

@end table

Available @code{apcupsd-event-handlers} fields are:

@table @asis
@item @code{modules} (type: gexp)
Additional modules to import into the generated handler script.

@item @code{killpower} (type: gexp)
The handler for the killpower event.

@item @code{commfailure} (type: gexp)
The handler for the commfailure event.

@item @code{commok} (type: gexp)
The handler for the commfailure event.

@item @code{powerout} (type: gexp)
The handler for the powerout event.

@item @code{onbattery} (type: gexp)
The handler for the onbattery event.

@item @code{offbattery} (type: gexp)
The handler for the offbattery event.

@item @code{mainsback} (type: gexp)
The handler for the mainsback event.

@item @code{failing} (type: gexp)
The handler for the failing event.

@item @code{timeout} (type: gexp)
The handler for the timeout event.

@item @code{loadlimit} (type: gexp)
The handler for the loadlimit event.

@item @code{runlimit} (type: gexp)
The handler for the runlimit event.

@item @code{doreboot} (type: gexp)
The handler for the doreboot event.

@item @code{doshutdown} (type: gexp)
The handler for the doshutdown event.

@item @code{annoyme} (type: gexp)
The handler for the annoyme event.

@item @code{emergency} (type: gexp)
The handler for the emergency event.

@item @code{changeme} (type: gexp)
The handler for the changeme event.

@item @code{remotedown} (type: gexp)
The handler for the remotedown event.

@item @code{startselftest} (type: gexp)
The handler for the startselftest event.

@item @code{endselftest} (type: gexp)
The handler for the endselftest event.

@item @code{battdetach} (type: gexp)
The handler for the battdetach event.

@item @code{battattach} (type: gexp)
The handler for the battattach event.

@end table
@end deftp

@node Serviços de áudio
@subsection Serviços de áudio

The @code{(gnu services audio)} module provides a service to start MPD (the
Music Player Daemon).

@cindex mpd
@subsubheading Daemon do reprodutor de música

The Music Player Daemon (MPD) is a service that can play music while being
controlled from the local machine or over the network by a variety of
clients.

The following example shows the simplest configuration to locally expose,
via PulseAudio, a music collection kept at @file{/srv/music}, with
@command{mpd} running as the default @samp{mpd} user.  This user will spawn
its own PulseAudio daemon, which may compete for the sound card access with
that of your own user.  In this configuration, you may have to stop the
playback of your user audio applications to hear MPD's output and
vice-versa.

@lisp
(service mpd-service-type
         (mpd-configuration
          (music-directory "/srv/music")))
@end lisp

@quotation Importante
The music directory must be readable to the MPD user, by default,
@samp{mpd}.  Permission problems will be reported via @samp{Permission
denied} errors in the MPD logs, which appear in @file{/var/log/messages} by
default.
@end quotation

Most MPD clients will trigger a database update upon connecting, but you can
also use the @code{update} action do to so:

@example
herd update mpd
@end example

All the MPD configuration fields are documented below, and a more complex
example follows.

@defvar mpd-service-type
The service type for @command{mpd}
@end defvar

@c %start of fragment
@deftp {Tipo de dados} mpd-configuration
Available @code{mpd-configuration} fields are:

@table @asis
@item @code{package} (default: @code{mpd}) (type: file-like)
The MPD package.

@item @code{user} (type: user-account)
The user to run mpd as.

@item @code{group} (type: user-group)
The group to run mpd as.

The default @code{%mpd-group} is a system group with name ``mpd''.

@item @code{shepherd-requirement} (default: @code{'()}) (type: list-of-symbols)
A list of symbols naming Shepherd services that this service will depend on.

@item @code{environment-variables} (default: @code{'("PULSE_CLIENTCONFIG=/etc/pulse/client.conf" "PULSE_CONFIG=/etc/pulse/daemon.conf")}) (type: list-of-strings)
A list of strings specifying environment variables.

@item @code{log-file} (type: maybe-string)
The location of the log file.  Unless specified, logs are sent to the local
syslog daemon.  Alternatively, a log file name can be specified, for example
@file{/var/log/mpd.log}.

@item @code{log-level} (type: maybe-string)
Suppress any messages below this threshold.  The available values, in
decreasing order of verbosity, are: @code{verbose}, @code{info},
@code{notice}, @code{warning} and @code{error}.

@item @code{music-directory} (type: maybe-string)
The directory to scan for music files.

@item @code{music-dir} (type: maybe-string)
The directory to scan for music files.

@item @code{playlist-directory} (type: maybe-string)
The directory to store playlists.

@item @code{playlist-dir} (type: maybe-string)
The directory to store playlists.

@item @code{db-file} (type: maybe-string)
The location of the music database.  When left unspecified,
@file{~/.cache/db} is used.

@item @code{state-file} (type: maybe-string)
The location of the file that stores current MPD's state.

@item @code{sticker-file} (type: maybe-string)
The location of the sticker database.

@item @code{default-port} (default: @code{6600}) (type: maybe-port)
The default port to run mpd on.

@item @code{endpoints} (type: maybe-list-of-strings)
The addresses that mpd will bind to.  A port different from
@var{default-port} may be specified, e.g.  @code{localhost:6602} and IPv6
addresses must be enclosed in square brackets when a different port is
used.  To use a Unix domain socket, an absolute path or a path starting with
@code{~} can be specified here.

@item @code{address} (type: maybe-string)
The address that mpd will bind to.  To use a Unix domain socket, an absolute
path can be specified here.

@item @code{database} (type: maybe-mpd-plugin)
MPD database plugin configuration.

@item @code{partitions} (default: @code{'()}) (type: list-of-mpd-partition)
List of MPD "partitions".

@item @code{neighbors} (default: @code{'()}) (type: list-of-mpd-plugin)
List of MPD neighbor plugin configurations.

@item @code{inputs} (default: @code{'()}) (type: list-of-mpd-plugin)
List of MPD input plugin configurations.

@item @code{archive-plugins} (default: @code{'()}) (type: list-of-mpd-plugin)
List of MPD archive plugin configurations.

@item @code{auto-update?} (type: maybe-boolean)
Whether to automatically update the music database when files are changed in
the @var{music-directory}.

@item @code{input-cache-size} (type: maybe-string)
MPD input cache size.

@item @code{decoders} (default: @code{'()}) (type: list-of-mpd-plugin)
List of MPD decoder plugin configurations.

@item @code{resampler} (type: maybe-mpd-plugin)
MPD resampler plugin configuration.

@item @code{filters} (default: @code{'()}) (type: list-of-mpd-plugin)
List of MPD filter plugin configurations.

@item @code{outputs} (type: list-of-mpd-plugin-or-output)
The audio outputs that MPD can use.  By default this is a single output
using pulseaudio.

@item @code{playlist-plugins} (default: @code{'()}) (type: list-of-mpd-plugin)
List of MPD playlist plugin configurations.

@item @code{extra-options} (default: @code{'()}) (type: alist)
An association list of option symbols/strings to string values to be
appended to the configuration.

@end table
@end deftp
@c %end of fragment

@deftp {Tipo de dados} mpd-plugin
Data type representing a @command{mpd} plugin.

@table @asis
@item @code{plugin} (type: maybe-string)
Plugin name.

@item @code{name} (type: maybe-string)
Nome.

@item @code{enabled?} (type: maybe-boolean)
Whether the plugin is enabled/disabled.

@item @code{extra-options} (default: @code{'()}) (type: alist)
An association list of option symbols/strings to string values to be
appended to the plugin configuration.  See
@uref{https://mpd.readthedocs.io/en/latest/plugins.html,MPD plugin
reference} for available options.

@end table
@end deftp

@deftp {Tipo de dados} mpd-partition
Data type representing a @command{mpd} partition.

@table @asis
@item @code{name} (type: string)
Partition name.

@item @code{extra-options} (default: @code{'()}) (type: alist)
An association list of option symbols/strings to string values to be
appended to the partition configuration.  See
@uref{https://mpd.readthedocs.io/en/latest/user.html#configuring-partitions,Configuring
Partitions} for available options.

@end table
@end deftp

@c %start of fragment
@deftp {Tipo de dados} mpd-output
Available @code{mpd-output} fields are:

@table @asis
@item @code{name} (default: @code{"MPD"}) (type: string)
The name of the audio output.

@item @code{type} (default: @code{"pulse"}) (type: string)
The type of audio output.

@item @code{enabled?} (default: @code{#t}) (type: boolean)
Specifies whether this audio output is enabled when MPD is started.  By
default, all audio outputs are enabled.  This is just the default setting
when there is no state file; with a state file, the previous state is
restored.

@item @code{format} (type: maybe-string)
Force a specific audio format on output.  See
@uref{https://mpd.readthedocs.io/en/latest/user.html#audio-output-format,Global
Audio Format} for a more detailed description.

@item @code{tags?} (default: @code{#t}) (type: boolean)
If set to @code{#f}, then MPD will not send tags to this output.  This is
only useful for output plugins that can receive tags, for example the
@code{httpd} output plugin.

@item @code{always-on?} (default: @code{#f}) (type: boolean)
If set to @code{#t}, then MPD attempts to keep this audio output always
open.  This may be useful for streaming servers, when you don’t want to
disconnect all listeners even when playback is accidentally stopped.

@item @code{mixer-type} (type: maybe-string)
This field accepts a string that specifies which mixer should be used for
this audio output: the @code{hardware} mixer, the @code{software} mixer, the
@code{null} mixer (allows setting the volume, but with no effect; this can
be used as a trick to implement an external mixer External Mixer) or no
mixer (@code{none}).  When left unspecified, a @code{hardware} mixer is used
for devices that support it.

@item @code{replay-gain-handler} (type: maybe-string)
This field accepts a string that specifies how
@uref{https://mpd.readthedocs.io/en/latest/user.html#replay-gain,Replay
Gain} is to be applied.  @code{software} uses an internal software volume
control, @code{mixer} uses the configured (hardware) mixer control and
@code{none} disables replay gain on this audio output.

@item @code{extra-options} (default: @code{'()}) (type: alist)
An association list of option symbols/strings to string values to be
appended to the audio output configuration.

@end table
@end deftp
@c %end of fragment

The following example shows a configuration of @command{mpd} that configures
some of its plugins and provides a HTTP audio streaming output.

@lisp
(service mpd-service-type
         (mpd-configuration
           (outputs
             (list (mpd-output
                     (name "streaming")
                     (type "httpd")
                     (mixer-type 'null)
                     (extra-options
                      `((encoder . "vorbis")
                        (port    . "8080"))))))
           (decoders
             (list (mpd-plugin
                     (plugin "mikmod")
                     (enabled? #f))
                   (mpd-plugin
                     (plugin "openmpt")
                     (enabled? #t)
                     (extra-options `((repeat-count . -1)
                                      (interpolation-filter . 1))))))
           (resampler (mpd-plugin
                        (plugin "libsamplerate")
                        (extra-options `((type . 0)))))))
@end lisp

@subsubheading myMPD

@cindex MPD, web interface
@cindex myMPD service

@uref{https://jcorporation.github.io/myMPD/, myMPD} is a web server frontend
for MPD that provides a mobile friendly web client for MPD.

The following example shows a myMPD instance listening on port 80, with
album cover caching disabled.

@lisp
(service mympd-service-type
         (mympd-configuration
          (port 80)
          (covercache-ttl 0)))
@end lisp

@defvar mympd-service-type
The service type for @command{mympd}.
@end defvar

@c %start of fragment
@deftp {Tipo de dados} mympd-configuration
Available @code{mympd-configuration} fields are:

@table @asis
@item @code{package} (default: @code{mympd}) (type: file-like)
The package object of the myMPD server.

@item @code{shepherd-requirement} (default: @code{'()}) (type: list-of-symbols)
This is a list of symbols naming Shepherd services that this service will
depend on.

@item @code{user} (default: @code{%mympd-user}) (type: user-account)
Owner of the @command{mympd} process.

The default @code{%mympd-user} is a system user with the name ``mympd'', who
is a part of the group @var{group} (see below).

@item @code{group} (default: @code{%mympd-group}) (type: user-group)
Owner group of the @command{mympd} process.

The default @code{%mympd-group} is a system group with name ``mympd''.
@item @code{work-directory} (default: @code{"/var/lib/mympd"}) (type: string)
Where myMPD will store its data.

@item @code{cache-directory} (default: @code{"/var/cache/mympd"}) (type: string)
Where myMPD will store its cache.

@item @code{acl} (type: maybe-mympd-ip-acl)
ACL to access the myMPD webserver.

@item @code{covercache-ttl} (default: @code{31}) (type: maybe-integer)
How long to keep cached covers, @code{0} disables cover caching.

@item @code{http?} (default: @code{#t}) (type: boolean)
HTTP support.

@item @code{host} (default: @code{"[::]"}) (type: string)
Host name to listen on.

@item @code{port} (default: @code{80}) (type: maybe-port)
HTTP port to listen on.

@item @code{log-level} (default: @code{5}) (type: integer)
How much detail to include in logs, possible values: @code{0} to @code{7}.

@item @code{log-to} (type: maybe-string)
Where to send logs.  Unless specified, the service logs to the local syslog
service under the @samp{daemon} facility.  Alternatively, a log file name
can be specified, for example @file{/var/log/mympd.log}.

@item @code{lualibs} (default: @code{"all"}) (type: maybe-string)
See
@uref{https://jcorporation.github.io/myMPD/scripting/#lua-standard-libraries}.

@item @code{uri} (type: maybe-string)
Override URI to myMPD.  See
@uref{https://github.com/jcorporation/myMPD/issues/950}.

@item @code{script-acl} (default: @code{(mympd-ip-acl (allow '("127.0.0.1")))}) (type: maybe-mympd-ip-acl)
ACL to access the myMPD script backend.

@item @code{ssl?} (default: @code{#f}) (type: boolean)
SSL/TLS support.

@item @code{ssl-port} (default: @code{443}) (type: maybe-port)
Port to listen for HTTPS.

@item @code{ssl-cert} (type: maybe-string)
Path to PEM encoded X.509 SSL/TLS certificate (public key).

@item @code{ssl-key} (type: maybe-string)
Path to PEM encoded SSL/TLS private key.

@item @code{pin-hash} (type: maybe-string)
SHA-256 hashed pin used by myMPD to control settings access by prompting a
pin from the user.

@item @code{save-caches?} (type: maybe-boolean)
Whether to preserve caches between service restarts.

@end table
@end deftp
@c %end of fragment

@c %start of fragment
@deftp {Tipo de dados} mympd-ip-acl
Available @code{mympd-ip-acl} fields are:

@table @asis
@item @code{allow} (default: @code{'()}) (type: list-of-strings)
Allowed IP addresses.

@item @code{deny} (default: @code{'()}) (type: list-of-strings)
Disallowed IP addresses.

@end table
@end deftp
@c %end of fragment

@node Serviços de virtualização
@subsection Serviços de virtualização

The @code{(gnu services virtualization)} module provides services for the
libvirt and virtlog daemons, as well as other virtualization-related
services.

@subsubheading Libvirt daemon

@code{libvirtd} is the server side daemon component of the libvirt
virtualization management system.  This daemon runs on host servers and
performs required management tasks for virtualized guests.  To connect to
the libvirt daemon as an unprivileged user, it must be added to the
@samp{libvirt} group, as shown in the example below.

@defvar libvirt-service-type
This is the type of the @uref{https://libvirt.org, libvirt daemon}.  Its
value must be a @code{libvirt-configuration}.

@lisp
(users (cons (user-account
              (name "user")
              (group "users")
              (supplementary-groups '("libvirt"
                                      "audio" "video" "wheel")))
             %base-user-accounts))
(service libvirt-service-type
         (libvirt-configuration
          (tls-port "16555")))
@end lisp
@end defvar

@c Auto-generated with (configuration->documentation 'libvirt-configuration)
@c %start of fragment

@deftp {Data Type} libvirt-configuration
Available @code{libvirt-configuration} fields are:

@table @asis
@item @code{libvirt} (default: @code{libvirt}) (type: file-like)
Libvirt package.

@item @code{qemu} (default: @code{qemu}) (type: file-like)
The QEMU package to use.

@item @code{dmidecode} (default: @code{dmidecode}) (type: file-like)
The Dmidecode package to use.

@item @code{requirement} (default: @code{'()}) (type: list-of-symbols)
Shepherd services dependencies to the provisioned Shepherd service.

@item @code{firmwares} (default: @code{(ovmf-x86-64)}) (type: list-of-file-likes)
List of UEFI/BIOS firmware packages to make available.  Each firmware
package should contain a @file{share/qemu/firmware/@var{NAME}.json} QEMU
firmware metadata file.

@item @code{listen-tls?} (default: @code{#t}) (type: boolean)
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.

@item @code{listen-tcp?} (default: @code{#f}) (type: boolean)
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).

@item @code{tls-port} (default: @code{"16514"}) (type: string)
Port for accepting secure TLS connections This can be a port number, or
service name.

@item @code{tcp-port} (default: @code{"16509"}) (type: string)
Port for accepting insecure TCP connections This can be a port number, or
service name.

@item @code{listen-addr} (default: @code{"0.0.0.0"}) (type: string)
IP address or hostname used for client connections.

@item @code{mdns-adv?} (default: @code{#f}) (type: boolean)
Flag toggling mDNS advertisement of the libvirt service.

@item @code{mdns-name} (default: @code{"Virtualization Host terra"}) (type: string)
Default mDNS advertisement name.  This must be unique on the immediate
broadcast network.

@item @code{unix-sock-group} (default: @code{"libvirt"}) (type: string)
UNIX domain socket group ownership.  This can be used to allow a trusted set
of users access to management capabilities without becoming root.

@item @code{unix-sock-ro-perms} (default: @code{"0777"}) (type: string)
UNIX socket permissions for the R/O socket.  This is used for monitoring VM
status only.

@item @code{unix-sock-rw-perms} (default: @code{"0770"}) (type: string)
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 (e.g., @code{"0777"}).

@item @code{unix-sock-admin-perms} (default: @code{"0777"}) (type: string)
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.

@item @code{unix-sock-dir} (default: @code{"/var/run/libvirt"}) (type: string)
The directory in which sockets will be found/created.

@item @code{auth-unix-ro} (default: @code{"polkit"}) (type: string)
Authentication scheme for UNIX read-only sockets.  By default socket
permissions allow anyone to connect.

@item @code{auth-unix-rw} (default: @code{"polkit"}) (type: string)
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.

@item @code{auth-tcp} (default: @code{"sasl"}) (type: string)
Authentication scheme for TCP sockets.  If you don't enable SASL, then all
TCP traffic is cleartext.  Don't do this outside of a development/test
scenario.

@item @code{auth-tls} (default: @code{"none"}) (type: string)
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 @code{"sasl"} for this option

@item @code{access-drivers} (default: @code{()}) (type: optional-list)
API access control scheme.  By default an authenticated user is allowed
access to all APIs.  Access drivers can place restrictions on this.

@item @code{key-file} (default: @code{""}) (type: string)
Server key file path.  If set to an empty string, then no private key is
loaded.

@item @code{cert-file} (default: @code{""}) (type: string)
Server key file path.  If set to an empty string, then no certificate is
loaded.

@item @code{ca-file} (default: @code{""}) (type: string)
Server key file path.  If set to an empty string, then no CA certificate is
loaded.

@item @code{crl-file} (default: @code{""}) (type: string)
Certificate revocation list path.  If set to an empty string, then no CRL is
loaded.

@item @code{tls-no-sanity-cert} (default: @code{#f}) (type: boolean)
Disable verification of our own server certificates.  When
@command{libvirtd} starts it performs some sanity checks against its own
certificates.

@item @code{tls-no-verify-cert} (default: @code{#f}) (type: boolean)
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.

@item @code{tls-allowed-dn-list} (default: @code{()}) (type: optional-list)
Whitelist of allowed x509 Distinguished Name.

@item @code{sasl-allowed-usernames} (default: @code{()}) (type: optional-list)
Whitelist of allowed SASL usernames.  The format for username depends on the
SASL authentication mechanism.

@item @code{tls-priority} (default: @code{"NORMAL"}) (type: string)
Override the compile time default TLS priority string.  The default is
usually "NORMAL" unless overridden at build time.  Only set this if it is
desired for libvirt to deviate from the global default settings.

@item @code{max-clients} (default: @code{5000}) (type: integer)
Maximum number of concurrent client connections to allow over all sockets
combined.

@item @code{max-queued-clients} (default: @code{1000}) (type: integer)
Maximum length of queue of connections waiting to be accepted by the
daemon.  Note, that some protocols supporting re-transmission may obey this
so that a later reattempt at connection succeeds.

@item @code{max-anonymous-clients} (default: @code{20}) (type: integer)
Maximum length of queue of accepted but not yet authenticated clients.  Set
this to zero to turn this feature off.

@item @code{min-workers} (default: @code{5}) (type: integer)
Number of workers to start up initially.

@item @code{max-workers} (default: @code{20}) (type: integer)
Maximum number of worker threads.  If the number of active clients exceeds
@code{min-workers}, then more threads are spawned, up to @code{max_workers}
limit.  Typically you'd want @code{max_workers} to equal maximum number of
clients allowed.

@item @code{prio-workers} (default: @code{5}) (type: integer)
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.

@item @code{max-requests} (default: @code{20}) (type: integer)
Total global limit on concurrent RPC calls.

@item @code{max-client-requests} (default: @code{5}) (type: integer)
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.

@item @code{admin-min-workers} (default: @code{1}) (type: integer)
Same as @code{min-workers} but for the admin interface.

@item @code{admin-max-workers} (default: @code{5}) (type: integer)
Same as @code{max-workers} but for the admin interface.

@item @code{admin-max-clients} (default: @code{5}) (type: integer)
Same as @code{max-clients} but for the admin interface.

@item @code{admin-max-queued-clients} (default: @code{5}) (type: integer)
Same as @code{max-queued-clients} but for the admin interface.

@item @code{admin-max-client-requests} (default: @code{5}) (type: integer)
Same as @code{max-client-requests} but for the admin interface.

@item @code{log-level} (default: @code{3}) (type: integer)
Semi-deprecated option for the logging level: using the @code{log-filters}
option instead is recommend, as it provides finer control.  The log level
can be set to @code{4} for errors, @code{3} for warnings, @code{2} for
information or @code{1} for debug.  Note that since @code{log-filters} and
@code{log-outputs} take precedence over this option, you will need to also
adjust their logging levels to avoid filtering out messages.

@item @code{log-filters} (default: @code{"3:remote 4:event"}) (type: string)
Logging filters.  A filter allows selecting a different logging level for a
given category of logs.  The format for a filter is either
@samp{@var{x}:@var{name}} or @samp{@var{x}:+@var{name}}, where name is a
string which is matched against the category given in the
@code{VIR_LOG_INIT()} at the top of each libvirt source file, e.g.,
@samp{"remote"}, @samp{"qemu"}, or @samp{"util.json"}.  @var{name} can be a
substring of the full category name, in order to match multiple similar
categories.  The optional @samp{+} prefix tells libvirt to log stack traces
for each message matching @var{name}.  @var{x} is the log level value used
to filter the associated message category.  @var{x} can be set to @samp{4}
for errors, @samp{3} for warnings, @samp{2} for information, or @samp{1} for
debug.  Multiple filters can be defined in a single filters statement, as
space-separated values.  Since @code{log-outputs} also include a level
filter, you may need to also adjust its value to see all the filtered
messages.

@item @code{log-outputs} (default: @code{"3:syslog:libvirtd"}) (type: string)
Logging outputs.  An output is one of the places to save logging
information.  The format for an output has the form
@code{"@var{x}:var@{output@}"}, where @var{output} can be @samp{stderr},
@samp{syslog:@var{name}}, where @var{name} is the syslog @code{ident} value
to use, or @samp{file:@var{file_name}}, where @var{file_name} is the file
name of the file to output to.  @var{x} is the minimal level, which acts as
a filter.  @var{x} can be set to @var{x} can be set to @samp{4} for errors,
@samp{3} for warnings, @samp{2} for information, or @samp{1} for debug.
Multiple filters can be defined in a single filters statement, as
space-separated values.

@item @code{audit-level} (default: @code{1}) (type: integer)
Modify the behavior of the auditing subsystem.  @samp{0} disables all
auditing, samp@{1@} enables auditing only if enabled on thehost and @samp{2}
enables auditing but exits if it is disabled on the host.

@item @code{audit-logging} (default: @code{#f}) (type: boolean)
Send audit messages via libvirt logging infrastructure.

@item @code{host-uuid} (default: @code{""}) (type: optional-string)
Host UUID.  UUID must not have all digits be the same.

@item @code{host-uuid-source} (default: @code{"smbios"}) (type: string)
Source to read host UUID.  Use @code{"smbios"} to fetch the UUID via
@code{dmidecode -s system-uuid}, or @code{"machine-id"} to fetch the UUID
from @code{/etc/machine-id}.  If @code{dmidecode} does not provide a valid
UUID a temporary UUID will be generated.

@item @code{keepalive-interval} (default: @code{5}) (type: integer)
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
@code{-1}, libvirtd won't send keepalive requests; however clients can still
send them and the daemon will send responses.

@item @code{keepalive-count} (default: @code{5}) (type: integer)
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 @samp{keepalive_interval * (keepalive_count + 1)}
seconds since the last message received from the client.  When
@code{keepalive-count} is set to @code{0}, connections will be automatically
closed after @code{keepalive-interval} seconds of inactivity without sending
any keepalive messages.

@item @code{admin-keepalive-interval} (default: @code{5}) (type: integer)
Same as above but for admin interface.

@item @code{admin-keepalive-count} (default: @code{5}) (type: integer)
Same as above but for admin interface.

@item @code{ovs-timeout} (default: @code{5}) (type: integer)
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.

@end table

@end deftp


@c %end of fragment

@subsubheading Virtlog daemon
The virtlogd service is a server side daemon component of libvirt that is
used to manage logs from virtual machine consoles.

This daemon is not used directly by libvirt client applications, rather it
is called on their behalf by @code{libvirtd}.  By maintaining the logs in a
standalone daemon, the main @code{libvirtd} daemon can be restarted without
risk of losing logs.  The @code{virtlogd} daemon has the ability to
re-exec()  itself upon receiving @code{SIGUSR1}, to allow live upgrades
without downtime.

@defvar virtlog-service-type
This is the type of the virtlog daemon.  Its value must be a
@code{virtlog-configuration}.

@lisp
(service virtlog-service-type
         (virtlog-configuration
          (max-clients 1000)))
@end lisp
@end defvar

@deftypevr {@code{libvirt} parameter} package libvirt
Libvirt package.
@end deftypevr

@deftypevr {@code{virtlog-configuration} parameter} integer log-level
Logging level.  4 errors, 3 warnings, 2 information, 1 debug.

Defaults to @samp{3}.

@end deftypevr

@deftypevr {@code{virtlog-configuration} parameter} string log-filters
Logging filters.

A filter allows to select a different logging level for a given category of
logs The format for a filter is one of:

@itemize @bullet
@item
x:name

@item
x:+name

@end itemize

where @code{name} is a string which is matched against the category given in
the @code{VIR_LOG_INIT()} at the top of each libvirt source file, e.g.,
"remote", "qemu", or "util.json" (the name in the filter can be a substring
of the full category name, in order to match multiple similar categories),
the optional "+" prefix tells libvirt to log stack trace for each message
matching name, and @code{x} is the minimal level where matching messages
should be logged:

@itemize @bullet
@item
1: DEBUG

@item
2: INFO

@item
3: WARNING

@item
4: ERROR

@end itemize

Multiple filters can be defined in a single filters statement, they just
need to be separated by spaces.

Defaults to @samp{"3:remote 4:event"}.

@end deftypevr

@deftypevr {@code{virtlog-configuration} parameter} string log-outputs
Logging outputs.

An output is one of the places to save logging information The format for an
output can be:

@table @code
@item x:stderr
output goes to stderr

@item x:syslog:name
use syslog for the output and use the given name as the ident

@item x:file:file_path
saída para um arquivo, com o caminho de arquivo dado

@item x:journald
output to journald logging system

@end table

In all case the x prefix is the minimal level, acting as a filter

@itemize @bullet
@item
1: DEBUG

@item
2: INFO

@item
3: WARNING

@item
4: ERROR

@end itemize

Multiple outputs can be defined, they just need to be separated by spaces.

Defaults to @samp{"3:stderr"}.

@end deftypevr

@deftypevr {@code{virtlog-configuration} parameter} integer max-clients
Maximum number of concurrent client connections to allow over all sockets
combined.

Defaults to @samp{1024}.

@end deftypevr

@deftypevr {@code{virtlog-configuration} parameter} integer max-size
Maximum file size before rolling over.

Defaults to @samp{2MB}

@end deftypevr

@deftypevr {@code{virtlog-configuration} parameter} integer max-backups
Maximum number of backup files to keep.

Defaults to @samp{3}

@end deftypevr

@anchor{transparent-emulation-qemu}
@subsubheading Transparent Emulation with QEMU

@cindex emulation
@cindex @code{binfmt_misc}
@code{qemu-binfmt-service-type} provides support for transparent emulation
of program binaries built for different architectures---e.g., it allows you
to transparently execute an ARMv7 program on an x86_64 machine.  It achieves
this by combining the @uref{https://www.qemu.org, QEMU} emulator and the
@code{binfmt_misc} feature of the kernel Linux.  This feature only allows
you to emulate GNU/Linux on a different architecture, but see below for
GNU/Hurd support.

@defvar qemu-binfmt-service-type
This is the type of the QEMU/binfmt service for transparent emulation.  Its
value must be a @code{qemu-binfmt-configuration} object, which specifies the
QEMU package to use as well as the architecture we want to emulated:

@lisp
(service qemu-binfmt-service-type
         (qemu-binfmt-configuration
           (platforms (lookup-qemu-platforms "arm" "aarch64"))))
@end lisp

In this example, we enable transparent emulation for the ARM and aarch64
platforms.  Running @code{herd stop qemu-binfmt} turns it off, and running
@code{herd start qemu-binfmt} turns it back on (@pxref{Invoking herd, the
@command{herd} command,, shepherd, The GNU Shepherd Manual}).
@end defvar

@deftp {Tipo de dados} qemu-binfmt-configuration
This is the configuration for the @code{qemu-binfmt} service.

@table @asis
@item @code{platforms} (default: @code{'()})
The list of emulated QEMU platforms.  Each item must be a @dfn{platform
object} as returned by @code{lookup-qemu-platforms} (see below).

For example, let's suppose you're on an x86_64 machine and you have this
service:

@lisp
(service qemu-binfmt-service-type
         (qemu-binfmt-configuration
           (platforms (lookup-qemu-platforms "arm"))))
@end lisp

You can run:

@example
guix build -s armhf-linux inkscape
@end example

@noindent
and it will build Inkscape for ARMv7 @emph{as if it were a native build},
transparently using QEMU to emulate the ARMv7 CPU@.  Pretty handy if you'd
like to test a package build for an architecture you don't have access to!

@item @code{qemu} (default: @code{qemu})
The QEMU package to use.
@end table
@end deftp

@deffn {Procedure} lookup-qemu-platforms platforms@dots{}
Return the list of QEMU platform objects corresponding to
@var{platforms}@dots{}.  @var{platforms} must be a list of strings
corresponding to platform names, such as @code{"arm"}, @code{"sparc"},
@code{"mips64el"}, and so on.
@end deffn

@deffn {Procedure} qemu-platform? obj
Return true if @var{obj} is a platform object.
@end deffn

@deffn {Procedure} qemu-platform-name platform
Return the name of @var{platform}---a string such as @code{"arm"}.
@end deffn


@subsubheading QEMU Guest Agent

@cindex emulation

The QEMU guest agent provides control over the emulated system to the host.
The @code{qemu-guest-agent} service runs the agent on Guix guests.  To
control the agent from the host, open a socket by invoking QEMU with the
following arguments:

@example
qemu-system-x86_64 \
	-chardev socket,path=/tmp/qga.sock,server=on,wait=off,id=qga0 \
	-device virtio-serial \
	-device virtserialport,chardev=qga0,name=org.qemu.guest_agent.0 \
	...
@end example

This creates a socket at @file{/tmp/qga.sock} on the host.  Once the guest
agent is running, you can issue commands with @code{socat}:

@example
$ guix shell socat -- socat unix-connect:/tmp/qga.sock stdio
@{"execute": "guest-get-host-name"@}
@{"return": @{"host-name": "guix"@}@}
@end example

See @url{https://wiki.qemu.org/Features/GuestAgent,QEMU guest agent
documentation} for more options and commands.

@defvar qemu-guest-agent-service-type
Tipo de serviço para o serviço de agente convidado QEMU.
@end defvar

@deftp {Tipo de dados} qemu-guest-agent-configuration
Configuration for the @code{qemu-guest-agent} service.

@table @asis
@item @code{qemu} (default: @code{qemu-minimal})
The QEMU package to use.

@item @code{device} (default: @code{""})
File name of the device or socket the agent uses to communicate with the
host.  If empty, QEMU uses a default file name.
@end table
@end deftp

@subsubheading Xen Guest Agent

@cindex Xen
@cindex Xen guest agent

The Xen guest agent allows a Xen host to control the emulated system.  The
@code{xe-guest-utilities} service runs the agent on Guix guests.

@url{https://github.com/xenserver/xe-guest-utilities, xe-guest-utilities}
collects information about the running virtualized guest. This includes:
@itemize
@item
static information
@itemize
@item
The operating system running
@item
The Linux kernel version
@end itemize

@item
dynamic information
@itemize
@item
Network interfaces (devices) being added/removed
@item
Network connections being unplugged/plugged-in
@item
CPUs being added or removed
@item
The guest migrating, being paused/resumed, etc.
@end itemize

@item
ephemeral information
@itemize
@item
The amount of memory currently in-use and free
@item
The amount of disk-space used
@end itemize
@end itemize

@quotation Nota
The default Linux-libre kernel that Guix ships already enables the necessary
paravirtualization features for a guest.  There is nothing you need to do
for the guest to support Xen's paravirtualization features.

The guest utilities are used to have the guest report information
@emph{back} to the virtualizing host and support tasks that require
cooperation between host and guest, like CPU hotplugging.
@end quotation

@defvar xe-guest-utilities-service-type
Service type for the Xen guest utilities service.
@end defvar

@deftp {Data Type} xe-guest-utilities-configuration
Configuration for the @code{xe-guest-utilities} service.

@table @asis
@item @code{package} (default: @code{xe-guest-utilities})
The Xen guest utilities package to use.

@item @code{pid-file} (default: @code{"/var/run/xe-daemon.pid"})
Name of the file holding the PID of @code{xe-deamon}.

@item @code{log-file} (default: @code{"/var/log/xe-guest-utilities.log"})
Name of the @code{xe-guest-utilities} log file.
@end table
@end deftp

@code{xe-guest-utilities} is the standard guest utilities used for Xen
guests.  More recently the Xen Project has been working to develop
@code{xen-guest-agent}, a modern drop-in replacement for
@code{xe-guest-utilities}.  While they nearly have feature-parity,
@code{xen-guest-agent} currently lacks some of the features of its
predecessor, namely disk metrics and ``PV drivers version''.

@defvar xen-guest-agent-service-type
Service type for the Xen guest agent service.
@end defvar

@deftp {Data Type} xen-guest-agent-configuration
Configuration for the @code{xen-guest-agent} service.

@table @asis
@item @code{package} (default: @code{xen-guest-agent})
The Xen guest agent package to use.
@end table
@end deftp

@quotation Aviso
@code{xe-guest-utilities} and @code{xen-guest-agent} are mutually exclusive.
@end quotation


@anchor{build-vm}
@subsubheading Virtual Build Machines

@cindex virtual build machines
@cindex build VMs
@cindex VMs, for offloading
@dfn{Virtual build machines} or ``build VMs'' let you offload builds to a
fully controlled environment.  ``How can it be more controlled than regular
builds? And why would it be useful?'', you ask.  Good questions.

Builds spawned by @code{guix-daemon} indeed run in a controlled environment;
specifically the daemon spawns build processes in separate namespaces and in
a chroot, such as that build processes only see their declared dependencies
and a well-defined subset of the file system tree (@pxref{Configuração do ambiente de compilação}, for details).  A few aspects of the environments are not controlled
though: the operating system kernel, the CPU model, and the date.  Most of
the time, these aspects have no impact on the build process: the level of
isolation @code{guix-daemon} provides is ``good enough''.

@cindex time traps
However, there are occasionally cases where those aspects @emph{do}
influence the build process.  A typical example is @dfn{time traps}: build
processes that stop working after a certain date@footnote{The most
widespread example of time traps is test suites that involve checking the
expiration date of a certificate.  Such tests exists in TLS implementations
such as OpenSSL and GnuTLS, but also in high-level software such as
Python.}.  Another one is software that optimizes for the CPU
microarchitecture it is built on or, worse, bugs that manifest only on
specific CPUs.

To address that, @code{virtual-build-machine-service-type} lets you add a
virtual build machine on your system, as in this example:

@lisp
(use-modules (gnu services virtualization))

(operating-system
  ;; @dots{}
  (services (append (list (service virtual-build-machine-service-type))
                    %base-services)))
@end lisp

By default, you have to explicitly start the build machine when you need it,
at which point builds may be offloaded to it (@pxref{Configuração de descarregamento de daemon}):

@example
herd start build-vm
@end example

With the default setting shown above, the build VM runs with its clock set
to a date several years in the past, and on a CPU model that corresponds to
that date---a model possibly older than that of your machine.  This lets you
rebuild today software from the past that would otherwise fail to build due
to a time trap or other issues in its build process.  You can view the VM's
config like this:

@example
herd configuration build-vm
@end example

You can configure the build VM, as in this example:

@lisp
(service virtual-build-machine-service-type
         (virtual-build-machine
          (cpu "Westmere")
          (cpu-count 8)
          (memory-size (* 1 1024))
          (auto-start? #t)))
@end lisp

The available options are shown below.

@defvar virtual-build-machine-service-type
This is the service type to run @dfn{virtual build machines}.  Virtual build
machines are configured so that builds are offloaded to them when they are
running.
@end defvar

@deftp {Tipo de dados} virtual-build-machine
This is the data type specifying the configuration of a build machine.  It
contains the fields below:

@table @asis
@item @code{name} (default: @code{'build-vm})
The name of this build VM.  It is used to construct the name of its Shepherd
service.

@item @code{image}
The image of the virtual machine (@pxref{Imagens do sistema}).  This notably
specifies the virtual disk size and the operating system running into it
(@pxref{Referência do operating-system}).  The default value is a minimal
operating system image.

@item @code{qemu} (default: @code{qemu-minimal})
The QEMU package to run the image.

@item @code{cpu}
The CPU model being emulated as a string denoting a model known to QEMU.

The default value is a model that matches @code{date} (see below).  To see
what CPU models are available, run, for example:

@example
qemu-system-x86_64 -cpu help
@end example

@item @code{cpu-count} (default: @code{4})
The number of CPUs emulated by the virtual machine.

@item @code{memory-size} (default: @code{2048})
Size in mebibytes (MiB) of the virtual machine's main memory (RAM).

@item @code{date} (default: a few years ago)
Date inside the virtual machine when it starts; this must be a SRFI-19 date
object (@pxref{SRFI-19 Date,,, guile, GNU Guile Reference Manual}).

@item @code{port-forwardings} (default: 11022 and 11004)
TCP ports of the virtual machine forwarded to the host.  By default, the SSH
and secrets ports are forwarded into the host.

@item @code{systems} (default: @code{(list (%current-system))})
List of system types supported by the build VM---e.g.,
@code{"x86_64-linux"}.

@item @code{auto-start?} (default: @code{#f})
Whether to start the virtual machine when the system boots.
@end table
@end deftp

In the next section, you'll find a variant on this theme: GNU/Hurd virtual
machines!

@anchor{hurd-vm}
@subsubheading The Hurd in a Virtual Machine

@cindex @code{hurd}
@cindex the Hurd
@cindex childhurd

Service @code{hurd-vm} provides support for running GNU/Hurd in a virtual
machine (VM), a so-called @dfn{childhurd}.  This service is meant to be used
on GNU/Linux and the given GNU/Hurd operating system configuration is
cross-compiled.  The virtual machine is a Shepherd service that can be
referred to by the names @code{hurd-vm} and @code{childhurd} and be
controlled with commands such as:

@example
herd start hurd-vm
herd stop childhurd
@end example

When the service is running, you can view its console by connecting to it
with a VNC client, for example with:

@example
guix shell tigervnc-client -- vncviewer localhost:5900
@end example

The default configuration (see @code{hurd-vm-configuration} below)  spawns a
secure shell (SSH) server in your GNU/Hurd system, which QEMU (the virtual
machine emulator) redirects to port 10022 on the host.  By default, the
service enables @dfn{offloading} such that the host @code{guix-daemon}
automatically offloads GNU/Hurd builds to the childhurd (@pxref{Configuração de descarregamento de daemon}).  This is what happens when running a command like the
following one, where @code{i586-gnu} is the system type of 32-bit GNU/Hurd:

@example
guix build emacs-minimal -s i586-gnu
@end example

The childhurd is volatile and stateless: it starts with a fresh root file
system every time you restart it.  By default though, all the files under
@file{/etc/childhurd} on the host are copied as is to the root file system
of the childhurd when it boots.  This allows you to initialize ``secrets''
inside the VM: SSH host keys, authorized substitute keys, and so on---see
the explanation of @code{secret-root} below.

You will probably find it useful to create an account for you in the
GNU/Hurd virtual machine and to authorize logins with your SSH key.  To do
that, you can define the GNU/Hurd system in the usual way (@pxref{Usando o sistema de configuração}), and then pass that operating system as the @code{os}
field of @code{hurd-vm-configuration}, as in this example:

@lisp
(define childhurd-os
  ;; Definition of my GNU/Hurd system, derived from the default one.
  (operating-system
    (inherit %hurd-vm-operating-system)

    ;; Add a user account.
    (users (cons (user-account
                  (name "charlie")
                  (comment "This is me!")
                  (group "users")
                  (supplementary-groups '("wheel"))) ;for 'sudo'
                 %base-user-accounts))

    (services
     ;; Modify the SSH configuration to allow login as "root"
     ;; and as "charlie" using public key authentication.
     (modify-services (operating-system-user-services
                       %hurd-vm-operating-system)
       (openssh-service-type
        config => (openssh-configuration
                   (inherit config)
                   (authorized-keys
                    `(("root"
                       ,(local-file
                         "/home/charlie/.ssh/id_rsa.pub"))
                      ("charlie"
                       ,(local-file
                         "/home/charlie/.ssh/id_rsa.pub"))))))))))

(operating-system
  ;; @dots{}
  (services
    ;; Add the 'hurd-vm' service, configured to use the
    ;; operating system configuration above.
    (append (list (service hurd-vm-service-type
                           (hurd-vm-configuration
                             (os %childhurd-os))))
            %base-services)))
@end lisp

That's it! The remainder of this section provides the reference of the
service configuration.

@defvar hurd-vm-service-type
This is the type of the Hurd in a Virtual Machine service.  Its value must
be a @code{hurd-vm-configuration} object, which specifies the operating
system (@pxref{Referência do operating-system}) and the disk size for the Hurd
Virtual Machine, the QEMU package to use as well as the options for running
it.

Por exemplo:

@lisp
(service hurd-vm-service-type
         (hurd-vm-configuration
          (disk-size (* 5000 (expt 2 20))) ;5G
          (memory-size 1024)))             ;1024MiB
@end lisp

would create a disk image big enough to build GNU@tie{}Hello, with some
extra memory.
@end defvar

@deftp {Tipo de dados} hurd-vm-configuration
The data type representing the configuration for
@code{hurd-vm-service-type}.

@table @asis
@item @code{os} (default: @var{%hurd-vm-operating-system})
The operating system to instantiate.  This default is bare-bones with a
permissive OpenSSH secure shell daemon listening on port 2222
(@pxref{Serviços de Rede, @code{openssh-service-type}}).

@item @code{qemu} (default: @code{qemu-minimal})
The QEMU package to use.

@item @code{type} (default: @code{'hurd-qcow2})
The image type name.  Use @code{'hurd-qcow2} for a 32-bit image or
@code{'hurd64-qcow2} for a 64-bit image.

@item @code{image} (default: @var{hurd-vm-disk-image})
The image object representing the disk image of this virtual machine
(@pxref{Imagens do sistema}).

Alternatively, this can be the file name (a string) of an image, which is
useful if you want the image to persist across service restarts---see
example below.

@item @code{disk-size} (default: @code{'guess})
The size of the disk image.

@item @code{memory-size} (default: @code{512})
The memory size of the Virtual Machine in mebibytes.

@item @code{options} (default: @code{'("--snapshot")})
The extra options for running QEMU.

@item @code{id} (default: @code{#f})
If set, a non-zero positive integer used to parameterize Childhurd
instances.  It is appended to the service's name, e.g. @code{childhurd1}.

@item @code{net-options} (default: @var{hurd-vm-net-options})
The procedure used to produce the list of QEMU networking options.

By default, it produces

@lisp
'("--device" "rtl8139,netdev=net0"
  "--netdev" (string-append
              "user,id=net0,"
              "hostfwd=tcp:127.0.0.1:@var{secrets-port}-:1004,"
              "hostfwd=tcp:127.0.0.1:@var{ssh-port}-:2222,"
              "hostfwd=tcp:127.0.0.1:@var{vnc-port}-:5900"))
@end lisp

with forwarded ports:

@example
@var{secrets-port}: @code{(+ 11004 (* 1000 @var{ID}))}
@var{ssh-port}: @code{(+ 10022 (* 1000 @var{ID}))}
@var{vnc-port}: @code{(+ 15900 (* 1000 @var{ID}))}
@end example

@cindex childhurd, offloading
@cindex Hurd, offloading
@item @code{offloading?} (default: @code{#t})
Whether to automatically set up offloading of builds to the childhurd.

When enabled, this lets you run GNU/Hurd builds on the host and have them
transparently offloaded to the VM, for instance when running a command like
this:

@example
guix build coreutils -s i586-gnu
@end example

This option automatically sets up offloading like so:

@enumerate
@item
Authorizing the childhurd's key on the host so that the host accepts build
results coming from the childhurd, which can be done like so
(@pxref{Invocando guix archive, @command{guix archive --authorize}}, for more
on that).

@item
Creating a user account called @code{offloading} dedicated to offloading in
the childhurd.

@item
Creating an SSH key pair on the host and making it an authorized key of the
@code{offloading} account in the childhurd.

@item
Adding the childhurd to @file{/etc/guix/machines.scm} (@pxref{Configuração de descarregamento de daemon}).
@end enumerate

@item @code{secret-root} (default: @file{/etc/childhurd})
The root directory with out-of-band secrets to be installed into the
childhurd once it runs.  Childhurds are volatile which means that on every
startup, secrets such as the SSH host keys and Guix signing key are
recreated.

If the @file{/etc/childhurd} directory does not exist, the
@code{secret-service} running in the Childhurd will be sent an empty list of
secrets.

By default, the service automatically populates @file{/etc/childhurd} with
the following non-volatile secrets, unless they already exist:

@example
/etc/childhurd/etc/guix/acl
/etc/childhurd/etc/guix/signing-key.pub
/etc/childhurd/etc/guix/signing-key.sec
/etc/childhurd/etc/ssh/authorized_keys.d/offloading
/etc/childhurd/etc/ssh/ssh_host_ed25519_key
/etc/childhurd/etc/ssh/ssh_host_ecdsa_key
/etc/childhurd/etc/ssh/ssh_host_ed25519_key.pub
/etc/childhurd/etc/ssh/ssh_host_ecdsa_key.pub
@end example

@end table
@end deftp

Note that by default the VM image is volatile---i.e., once the service is
stopped, the contents are lost.  If you want a persistent image instead,
override the configuration's @code{image} and @code{options} without the
@option{--snapshot} flag using something along these lines:

@lisp
(service hurd-vm-service-type
         (hurd-vm-configuration
          ;; Specify an out-of-store, persistent image.
          (image "/out/of/store/writable/hurd.img")
          (options '())))
@end lisp

@subsubheading Ganeti

@cindex ganeti

@quotation Nota
This service is considered experimental.  Configuration options may be
changed in a backwards-incompatible manner, and not all features have been
thorougly tested.  Users of this service are encouraged to share their
experience at @email{guix-devel@@gnu.org}.
@end quotation

Ganeti is a virtual machine management system.  It is designed to keep
virtual machines running on a cluster of servers even in the event of
hardware failures, and to make maintenance and recovery tasks easy.  It
consists of multiple services which are described later in this section.  In
addition to the Ganeti service, you will need the OpenSSH service
(@pxref{Serviços de Rede, @code{openssh-service-type}}), and update the
@file{/etc/hosts} file (@pxref{Referência de Service,
@code{hosts-service-type}}) with the cluster name and address (or use a DNS
server).

All nodes participating in a Ganeti cluster should have the same Ganeti and
@file{/etc/hosts} configuration.  Here is an example configuration for a
Ganeti cluster node that supports multiple storage backends, and installs
the @code{debootstrap} and @code{guix} @dfn{OS providers}:

@lisp
(use-package-modules virtualization)
(use-service-modules base ganeti networking ssh)
(operating-system
  ;; @dots{}
  (host-name "node1")

  ;; Install QEMU so we can use KVM-based instances, and LVM, DRBD and Ceph
  ;; in order to use the "plain", "drbd" and "rbd" storage backends.
  (packages (append (map specification->package
                         '("qemu" "lvm2" "drbd-utils" "ceph"
                           ;; Add the debootstrap and guix OS providers.
                           "ganeti-instance-guix" "ganeti-instance-debootstrap"))
                    %base-packages))
  (services
   (append (list (service static-networking-service-type
                          (list (static-networking
                                 (addresses
                                  (list (network-address
                                         (device "eth0")
                                         (value "192.168.1.201/24"))))
                                 (routes
                                  (list (network-route
                                         (destination "default")
                                         (gateway "192.168.1.254"))))
                                 (name-servers '("192.168.1.252"
                                                 "192.168.1.253")))))

                 ;; Ganeti uses SSH to communicate between nodes.
                 (service openssh-service-type
                          (openssh-configuration
                           (permit-root-login 'prohibit-password)))

                 (simple-service 'ganeti-hosts-entries hosts-service-type
                                 (list
                                   (host "192.168.1.200" "ganeti.example.com")
                                   (host "192.168.1.201" "node1.example.com"
                                         '("node1"))
                                   (host "192.168.1.202" "node2.example.com"
                                         '("node2"))))

                 (service ganeti-service-type
                          (ganeti-configuration
                           ;; This list specifies allowed file system paths
                           ;; for storing virtual machine images.
                           (file-storage-paths '("/srv/ganeti/file-storage"))
                           ;; This variable configures a single "variant" for
                           ;; both Debootstrap and Guix that works with KVM.
                           (os %default-ganeti-os))))
           %base-services)))
@end lisp

Users are advised to read the
@url{https://docs.ganeti.org/docs/ganeti/3.0/html/admin.html,Ganeti
administrators guide} to learn about the various cluster options and
day-to-day operations.  There is also a
@url{https://guix.gnu.org/blog/2020/running-a-ganeti-cluster-on-guix/,blog
post} describing how to configure and initialize a small cluster.

@defvar ganeti-service-type
This is a service type that includes all the various services that Ganeti
nodes should run.

Its value is a @code{ganeti-configuration} object that defines the package
to use for CLI operations, as well as configuration for the various
daemons.  Allowed file storage paths and available guest operating systems
are also configured through this data type.
@end defvar

@deftp {Tipo de dados} ganeti-configuration
The @code{ganeti} service takes the following configuration options:

@table @asis
@item @code{ganeti} (default: @code{ganeti})
The @code{ganeti} package to use.  It will be installed to the system
profile and make @command{gnt-cluster}, @command{gnt-instance}, etc
available.  Note that the value specified here does not affect the other
services as each refer to a specific @code{ganeti} package (see below).

@item @code{noded-configuration} (default: @code{(ganeti-noded-configuration)})
@itemx @code{confd-configuration} (default: @code{(ganeti-confd-configuration)})
@itemx @code{wconfd-configuration} (default: @code{(ganeti-wconfd-configuration)})
@itemx @code{luxid-configuration} (default: @code{(ganeti-luxid-configuration)})
@itemx @code{rapi-configuration} (default: @code{(ganeti-rapi-configuration)})
@itemx @code{kvmd-configuration} (default: @code{(ganeti-kvmd-configuration)})
@itemx @code{mond-configuration} (default: @code{(ganeti-mond-configuration)})
@itemx @code{metad-configuration} (default: @code{(ganeti-metad-configuration)})
@itemx @code{watcher-configuration} (default: @code{(ganeti-watcher-configuration)})
@itemx @code{cleaner-configuration} (default: @code{(ganeti-cleaner-configuration)})

These options control the various daemons and cron jobs that are distributed
with Ganeti.  The possible values for these are described in detail below.
To override a setting, you must use the configuration type for that service:

@lisp
(service ganeti-service-type
         (ganeti-configuration
          (rapi-configuration
           (ganeti-rapi-configuration
            (interface "eth1"))))
          (watcher-configuration
           (ganeti-watcher-configuration
            (rapi-ip "10.0.0.1"))))
@end lisp

@item @code{file-storage-paths} (default: @code{'()})
List of allowed directories for file storage backend.

@item @code{hooks} (default: @code{#f})
When set, this should be a file-like object containing a directory with
@url{https://docs.ganeti.org/docs/ganeti/3.0/html/hooks.html,cluster
execution hooks}.

@item @code{os} (default: @code{%default-ganeti-os})
List of @code{<ganeti-os>} records.
@end table

In essence @code{ganeti-service-type} is shorthand for declaring each
service individually:

@lisp
(service ganeti-noded-service-type)
(service ganeti-confd-service-type)
(service ganeti-wconfd-service-type)
(service ganeti-luxid-service-type)
(service ganeti-kvmd-service-type)
(service ganeti-mond-service-type)
(service ganeti-metad-service-type)
(service ganeti-watcher-service-type)
(service ganeti-cleaner-service-type)
@end lisp

Plus a service extension for @code{etc-service-type} that configures the
file storage backend and OS variants.

@end deftp

@deftp {Tipo de dados} ganeti-os
This data type is suitable for passing to the @code{os} parameter of
@code{ganeti-configuration}.  It takes the following parameters:

@table @asis
@item @code{name}
The name for this OS provider.  It is only used to specify where the
configuration ends up.  Setting it to ``debootstrap'' will create
@file{/etc/ganeti/instance-debootstrap}.

@item @code{extension} (default: @code{#f})
The file extension for variants of this OS type.  For example @file{.conf}
or @file{.scm}.  It will be appended to the variant file name if set.

@item @code{variants} (default: @code{'()})
This must be either a list of @code{ganeti-os-variant} objects for this OS,
or a ``file-like'' object (@pxref{Expressões-G, file-like objects})
representing the variants directory.

To use the Guix OS provider with variant definitions residing in a local
directory instead of declaring individual variants (see @var{guix-variants}
below), you can do:

@lisp
(ganeti-os
 (name "guix")
 (variants (local-file "ganeti-guix-variants"
                       #:recursive? #true)))
@end lisp

Note that you will need to maintain the @file{variants.list} file (see
@code{@url{https://docs.ganeti.org/docs/ganeti/3.0/man/ganeti-os-interface.html,
ganeti-os-interface(7)}})  manually in this case.

@end table
@end deftp

@deftp {Tipo de dados} ganeti-os-variant
This is the data type for a Ganeti OS variant.  It takes the following
parameters:

@table @asis
@item @code{name}
The name of this variant.

@item @code{configuration}
A configuration file for this variant.
@end table
@end deftp

@defvar %default-debootstrap-hooks
This variable contains hooks to configure networking and the GRUB
bootloader.
@end defvar

@defvar %default-debootstrap-extra-pkgs
This variable contains a list of packages suitable for a fully-virtualized
guest.
@end defvar

@deftp {Tipo de dados} debootstrap-configuration

This data type creates configuration files suitable for the debootstrap OS
provider.

@table @asis
@item @code{hooks} (default: @code{%default-debootstrap-hooks})
When not @code{#f}, this must be a G-expression that specifies a directory
with scripts that will run when the OS is installed.  It can also be a list
of @code{(name . file-like)} pairs.  For example:

@lisp
`((99-hello-world . ,(plain-file "#!/bin/sh\necho Hello, World")))
@end lisp

That will create a directory with one executable named @code{99-hello-world}
and run it every time this variant is installed.  If set to @code{#f}, hooks
in @file{/etc/ganeti/instance-debootstrap/hooks} will be used, if any.
@item @code{proxy} (default: @code{#f})
Optional HTTP proxy to use.
@item @code{mirror} (default: @code{#f})
The Debian mirror.  Typically something like
@code{http://ftp.no.debian.org/debian}.  The default varies depending on the
distribution.
@item @code{arch} (default: @code{#f})
The dpkg architecture.  Set to @code{armhf} to debootstrap an ARMv7 instance
on an AArch64 host.  Default is to use the current system architecture.
@item @code{suite} (default: @code{"stable"})
When set, this must be a Debian distribution ``suite'' such as @code{buster}
or @code{focal}.  If set to @code{#f}, the default for the OS provider is
used.
@item @code{extra-pkgs} (default: @code{%default-debootstrap-extra-pkgs})
List of extra packages that will get installed by dpkg in addition to the
minimal system.
@item @code{components} (default: @code{#f})
When set, must be a list of Debian repository ``components''.  For example
@code{'("main" "contrib")}.
@item @code{generate-cache?} (default: @code{#t})
Whether to automatically cache the generated debootstrap archive.
@item @code{clean-cache} (default: @code{14})
Discard the cache after this amount of days.  Use @code{#f} to never clear
the cache.
@item @code{partition-style} (default: @code{'msdos})
The type of partition to create.  When set, it must be one of @code{'msdos},
@code{'none} or a string.
@item @code{partition-alignment} (default: @code{2048})
Alignment of the partition in sectors.
@end table
@end deftp

@deffn {Procedure} debootstrap-variant name configuration
This is a helper procedure that creates a @code{ganeti-os-variant} record.
It takes two parameters: a name and a @code{debootstrap-configuration}
object.
@end deffn

@deffn {Procedure} debootstrap-os variants@dots{}
This is a helper procedure that creates a @code{ganeti-os} record.  It takes
a list of variants created with @code{debootstrap-variant}.
@end deffn

@deffn {Procedure} guix-variant name configuration
This is a helper procedure that creates a @code{ganeti-os-variant} record
for use with the Guix OS provider.  It takes a name and a G-expression that
returns a ``file-like'' (@pxref{Expressões-G, file-like objects}) object
containing a Guix System configuration.
@end deffn

@deffn {Procedure} guix-os variants@dots{}
This is a helper procedure that creates a @code{ganeti-os} record.  It takes
a list of variants produced by @code{guix-variant}.
@end deffn

@defvar %default-debootstrap-variants
This is a convenience variable to make the debootstrap provider work ``out
of the box'' without users having to declare variants manually.  It contains
a single debootstrap variant with the default configuration:

@lisp
(list (debootstrap-variant
       "default"
       (debootstrap-configuration)))
@end lisp
@end defvar

@defvar %default-guix-variants
This is a convenience variable to make the Guix OS provider work without
additional configuration.  It creates a virtual machine that has an SSH
server, a serial console, and authorizes the Ganeti hosts SSH keys.

@lisp
(list (guix-variant
       "default"
       (file-append ganeti-instance-guix
                    "/share/doc/ganeti-instance-guix/examples/dynamic.scm")))
@end lisp
@end defvar

Users can implement support for OS providers unbeknownst to Guix by
extending the @code{ganeti-os} and @code{ganeti-os-variant} records
appropriately.  For example:

@lisp
(ganeti-os
 (name "custom")
 (extension ".conf")
 (variants
  (list (ganeti-os-variant
         (name "foo")
         (configuration (plain-file "bar" "this is fine"))))))
@end lisp

That creates @file{/etc/ganeti/instance-custom/variants/foo.conf} which
points to a file in the store with contents @code{this is fine}.  It also
creates @file{/etc/ganeti/instance-custom/variants/variants.list} with
contents @code{foo}.

Obviously this may not work for all OS providers out there.  If you find the
interface limiting, please reach out to @email{guix-devel@@gnu.org}.

The rest of this section documents the various services that are included by
@code{ganeti-service-type}.

@defvar ganeti-noded-service-type
@command{ganeti-noded} is the daemon responsible for node-specific functions
within the Ganeti system.  The value of this service must be a
@code{ganeti-noded-configuration} object.
@end defvar

@deftp {Tipo de dados} ganeti-noded-configuration
This is the configuration for the @code{ganeti-noded} service.

@table @asis
@item @code{ganeti} (default: @code{ganeti})
The @code{ganeti} package to use for this service.

@item @code{port} (padrão: @code{1811})
The TCP port on which the node daemon listens for network requests.

@item @code{address} (default: @code{"0.0.0.0"})
The network address that the daemon will bind to.  The default address means
bind to all available addresses.

@item @code{interface} (default: @code{#f})
When this is set, it must be a specific network interface (e.g.@:
@code{eth0})  that the daemon will bind to.

@item @code{max-clients} (default: @code{20})
This sets a limit on the maximum number of simultaneous client connections
that the daemon will handle.  Connections above this count are accepted, but
no responses will be sent until enough connections have closed.

@item @code{ssl?} (default: @code{#t})
Whether to use SSL/TLS to encrypt network communications.  The certificate
is automatically provisioned by the cluster and can be rotated with
@command{gnt-cluster renew-crypto}.

@item @code{ssl-key} (default: @file{"/var/lib/ganeti/server.pem"})
This can be used to provide a specific encryption key for TLS
communications.

@item @code{ssl-cert} (default: @file{"/var/lib/ganeti/server.pem"})
This can be used to provide a specific certificate for TLS communications.

@item @code{debug?} (default: @code{#f})
When true, the daemon performs additional logging for debugging purposes.
Note that this will leak encryption details to the log files, use with
caution.

@end table
@end deftp

@defvar ganeti-confd-service-type
@command{ganeti-confd} answers queries related to the configuration of a
Ganeti cluster.  The purpose of this daemon is to have a highly available
and fast way to query cluster configuration values.  It is automatically
active on all @dfn{master candidates}.  The value of this service must be a
@code{ganeti-confd-configuration} object.

@end defvar

@deftp {Tipo de dados} ganeti-confd-configuration
This is the configuration for the @code{ganeti-confd} service.

@table @asis
@item @code{ganeti} (default: @code{ganeti})
The @code{ganeti} package to use for this service.

@item @code{port} (padrão: @code{1814})
The UDP port on which to listen for network requests.

@item @code{address} (default: @code{"0.0.0.0"})
Network address that the daemon will bind to.

@item @code{debug?} (default: @code{#f})
When true, the daemon performs additional logging for debugging purposes.

@end table
@end deftp

@defvar ganeti-wconfd-service-type
@command{ganeti-wconfd} is the daemon that has authoritative knowledge about
the cluster configuration and is the only entity that can accept changes to
it.  All jobs that need to modify the configuration will do so by sending
appropriate requests to this daemon.  It only runs on the @dfn{master node}
and will automatically disable itself on other nodes.

The value of this service must be a @code{ganeti-wconfd-configuration}
object.
@end defvar

@deftp {Tipo de dados} ganeti-wconfd-configuration
This is the configuration for the @code{ganeti-wconfd} service.

@table @asis
@item @code{ganeti} (default: @code{ganeti})
The @code{ganeti} package to use for this service.

@item @code{no-voting?} (default: @code{#f})
The daemon will refuse to start if the majority of cluster nodes does not
agree that it is running on the master node.  Set to @code{#t} to start even
if a quorum can not be reached (dangerous, use with caution).

@item @code{debug?} (default: @code{#f})
When true, the daemon performs additional logging for debugging purposes.

@end table
@end deftp

@defvar ganeti-luxid-service-type
@command{ganeti-luxid} is a daemon used to answer queries related to the
configuration and the current live state of a Ganeti cluster.  Additionally,
it is the authoritative daemon for the Ganeti job queue.  Jobs can be
submitted via this daemon and it schedules and starts them.

It takes a @code{ganeti-luxid-configuration} object.
@end defvar

@deftp {Tipo de dados} ganeti-luxid-configuration
This is the configuration for the @code{ganeti-luxid} service.

@table @asis
@item @code{ganeti} (default: @code{ganeti})
The @code{ganeti} package to use for this service.

@item @code{no-voting?} (default: @code{#f})
The daemon will refuse to start if it cannot verify that the majority of
cluster nodes believes that it is running on the master node.  Set to
@code{#t} to ignore such checks and start anyway (this can be dangerous).

@item @code{debug?} (default: @code{#f})
When true, the daemon performs additional logging for debugging purposes.

@end table
@end deftp

@defvar ganeti-rapi-service-type
@command{ganeti-rapi} provides a remote API for Ganeti clusters.  It runs on
the master node and can be used to perform cluster actions programmatically
via a JSON-based RPC protocol.

Most query operations are allowed without authentication (unless
@var{require-authentication?} is set), whereas write operations require
explicit authorization via the @file{/var/lib/ganeti/rapi/users} file.  See
the @url{https://docs.ganeti.org/docs/ganeti/3.0/html/rapi.html, Ganeti
Remote API documentation} for more information.

The value of this service must be a @code{ganeti-rapi-configuration} object.
@end defvar

@deftp {Tipo de dados} ganeti-rapi-configuration
This is the configuration for the @code{ganeti-rapi} service.

@table @asis
@item @code{ganeti} (default: @code{ganeti})
The @code{ganeti} package to use for this service.

@item @code{require-authentication?} (default: @code{#f})
Whether to require authentication even for read-only operations.

@item @code{port} (padrão: @code{5080})
The TCP port on which to listen to API requests.

@item @code{address} (default: @code{"0.0.0.0"})
The network address that the service will bind to.  By default it listens on
all configured addresses.

@item @code{interface} (default: @code{#f})
When set, it must specify a specific network interface such as @code{eth0}
that the daemon will bind to.

@item @code{max-clients} (default: @code{20})
The maximum number of simultaneous client requests to handle.  Further
connections are allowed, but no responses are sent until enough connections
have closed.

@item @code{ssl?} (default: @code{#t})
Whether to use SSL/TLS encryption on the RAPI port.

@item @code{ssl-key} (default: @file{"/var/lib/ganeti/server.pem"})
This can be used to provide a specific encryption key for TLS
communications.

@item @code{ssl-cert} (default: @file{"/var/lib/ganeti/server.pem"})
This can be used to provide a specific certificate for TLS communications.

@item @code{debug?} (default: @code{#f})
When true, the daemon performs additional logging for debugging purposes.
Note that this will leak encryption details to the log files, use with
caution.

@end table
@end deftp

@defvar ganeti-kvmd-service-type
@command{ganeti-kvmd} is responsible for determining whether a given KVM
instance was shut down by an administrator or a user.  Normally Ganeti will
restart an instance that was not stopped through Ganeti itself.  If the
cluster option @code{user_shutdown} is true, this daemon monitors the
@code{QMP} socket provided by QEMU and listens for shutdown events, and
marks the instance as @dfn{USER_down} instead of @dfn{ERROR_down} when it
shuts down gracefully by itself.

It takes a @code{ganeti-kvmd-configuration} object.
@end defvar

@deftp {Tipo de dados} ganeti-kvmd-configuration

@table @asis
@item @code{ganeti} (default: @code{ganeti})
The @code{ganeti} package to use for this service.

@item @code{debug?} (default: @code{#f})
When true, the daemon performs additional logging for debugging purposes.

@end table
@end deftp

@defvar ganeti-mond-service-type
@command{ganeti-mond} is an optional daemon that provides Ganeti monitoring
functionality.  It is responsible for running data collectors and publish
the collected information through a HTTP interface.

It takes a @code{ganeti-mond-configuration} object.
@end defvar

@deftp {Tipo de dados} ganeti-mond-configuration

@table @asis
@item @code{ganeti} (default: @code{ganeti})
The @code{ganeti} package to use for this service.

@item @code{port} (padrão: @code{1815})
The port on which the daemon will listen.

@item @code{address} (default: @code{"0.0.0.0"})
The network address that the daemon will bind to.  By default it binds to
all available interfaces.

@item @code{debug?} (default: @code{#f})
When true, the daemon performs additional logging for debugging purposes.

@end table
@end deftp

@defvar ganeti-metad-service-type
@command{ganeti-metad} is an optional daemon that can be used to provide
information about the cluster to instances or OS install scripts.

It takes a @code{ganeti-metad-configuration} object.
@end defvar

@deftp {Tipo de dados} ganeti-metad-configuration

@table @asis
@item @code{ganeti} (default: @code{ganeti})
The @code{ganeti} package to use for this service.

@item @code{port} (padrão: @code{80})
The port on which the daemon will listen.

@item @code{address} (default: @code{#f})
If set, the daemon will bind to this address only.  If left unset, the
behavior depends on the cluster configuration.

@item @code{debug?} (default: @code{#f})
When true, the daemon performs additional logging for debugging purposes.

@end table
@end deftp

@defvar ganeti-watcher-service-type
@command{ganeti-watcher} is a script designed to run periodically and ensure
the health of a cluster.  It will automatically restart instances that have
stopped without Ganeti's consent, and repairs DRBD links in case a node has
rebooted.  It also archives old cluster jobs and restarts Ganeti daemons
that are not running.  If the cluster parameter @code{ensure_node_health} is
set, the watcher will also shutdown instances and DRBD devices if the node
it is running on is declared offline by known master candidates.

It can be paused on all nodes with @command{gnt-cluster watcher pause}.

The service takes a @code{ganeti-watcher-configuration} object.
@end defvar

@deftp {Tipo de dados} ganeti-watcher-configuration

@table @asis
@item @code{ganeti} (default: @code{ganeti})
The @code{ganeti} package to use for this service.

@item @code{schedule} (default: @code{"*/5 * * * *"})
When to run the script, expressed either as a string in traditional cron
syntax or as a gexp representing a Shepherd calendar event (@pxref{Timers,,,
shepherd, The GNU Shepherd Manual}).  The default is every five minutes.

@item @code{rapi-ip} (default: @code{#f})
This option needs to be specified only if the RAPI daemon is configured to
use a particular interface or address.  By default the cluster address is
used.

@item @code{job-age} (default: @code{(* 6 3600)})
Archive cluster jobs older than this age, specified in seconds.  The default
is 6 hours.  This keeps @command{gnt-job list} manageable.

@item @code{verify-disks?} (default: @code{#t})
If this is @code{#f}, the watcher will not try to repair broken DRBD links
automatically.  Administrators will need to use @command{gnt-cluster
verify-disks} manually instead.

@item @code{debug?} (default: @code{#f})
When @code{#t}, the script performs additional logging for debugging
purposes.

@end table
@end deftp

@defvar ganeti-cleaner-service-type
@command{ganeti-cleaner} is a script designed to run periodically and remove
old files from the cluster.  This service type controls two @dfn{cron jobs}:
one intended for the master node that permanently purges old cluster jobs,
and one intended for every node that removes expired X509 certificates,
keys, and outdated @command{ganeti-watcher} information.  Like all Ganeti
services, it is safe to include even on non-master nodes as it will disable
itself as necessary.

It takes a @code{ganeti-cleaner-configuration} object.
@end defvar

@deftp {Tipo de dados} ganeti-cleaner-configuration

@table @asis
@item @code{ganeti} (default: @code{ganeti})
The @code{ganeti} package to use for the @command{gnt-cleaner} command.

@item @code{master-schedule} (default: @code{"45 1 * * *"})
How often to run the master cleaning job.  The default is once per day, at
01:45:00.

@item @code{node-schedule} (default: @code{"45 2 * * *"})
How often to run the node cleaning job.  The default is once per day, at
02:45:00.

@end table
@end deftp

@node Serviços de controlando versão
@subsection Serviços de controlando versão

The @code{(gnu services version-control)} module provides a service to allow
remote access to local Git repositories.  There are three options: the
@code{git-daemon-service-type}, which provides access to repositories via
the @code{git://} unsecured TCP-based protocol, extending the @code{nginx}
web server to proxy some requests to @code{git-http-backend}, or providing a
web interface with @code{cgit-service-type}.

@defvar git-daemon-service-type
Type for a service that runs @command{git daemon}, a simple TCP server to
expose repositories over the Git protocol for anonymous access.

The value for this service type is a @code{<git-daemon-configuration>}
record, by default it allows read-only access to exported@footnote{By
creating the magic file @file{git-daemon-export-ok} in the repository
directory.} repositories under @file{/srv/git}.
@end defvar

@deftp {Tipo de dados} git-daemon-configuration
Data type representing the configuration for @code{git-daemon-service-type}.

@table @asis
@item @code{package} (default: @code{git})
Package object of the Git distributed version control system.

@item @code{export-all?} (default: @code{#f})
Whether to allow access for all Git repositories, even if they do not have
the @file{git-daemon-export-ok} file.

@item @code{base-path} (default: @file{/srv/git})
Whether to remap all the path requests as relative to the given path.  If
you run @command{git daemon} with @code{(base-path "/srv/git")} on
@samp{example.com}, then if you later try to pull
@indicateurl{git://example.com/hello.git}, git daemon will interpret the
path as @file{/srv/git/hello.git}.

@item @code{user-path} (default: @code{#f})
Whether to allow @code{~user} notation to be used in requests.  When
specified with empty string, requests to @indicateurl{git://host/~alice/foo}
is taken as a request to access @code{foo} repository in the home directory
of user @code{alice}.  If @code{(user-path "@var{path}")} is specified, the
same request is taken as a request to access @file{@var{path}/foo}
repository in the home directory of user @code{alice}.

@item @code{listen} (default: @code{'()})
Whether to listen on specific IP addresses or hostnames, defaults to all.

@item @code{port} (padrão: @code{#f})
Whether to listen on an alternative port, which defaults to 9418.

@item @code{whitelist} (default: @code{'()})
If not empty, only allow access to this list of directories.

@item @code{extra-options} (default: @code{'()})
Extra options that will be passed to @command{git daemon}.@footnote{Run
@command{man git-daemon} for more information.}

@end table
@end deftp

The @code{git://} protocol lacks authentication.  When you pull from a
repository fetched via @code{git://}, you don't know whether the data you
receive was modified or is even coming from the specified host, and your
connection is subject to eavesdropping.  It's better to use an authenticated
and encrypted transport, such as @code{https}.  Although Git allows you to
serve repositories using unsophisticated file-based web servers, there is a
faster protocol implemented by the @code{git-http-backend} program.  This
program is the back-end of a proper Git web service.  It is designed to sit
behind a FastCGI proxy.  @xref{Serviços 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 dados} git-http-configuration
Data type representing the configuration for a future
@code{git-http-service-type}; can currently be used to configure Nginx
through @code{git-http-nginx-location-configuration}.

@table @asis
@item @code{package} (default: @var{git})
Package object of the Git distributed version control system.

@item @code{git-root} (default: @file{/srv/git})
Directory containing the Git repositories to expose to the world.

@item @code{export-all?} (default: @code{#f})
Whether to expose access for all Git repositories in @var{git-root}, even if
they do not have the @file{git-daemon-export-ok} file.

@item @code{uri-path} (default: @samp{/git/})
Path prefix for Git access.  With the default @samp{/git/} prefix, this will
map @indicateurl{http://@var{server}/git/@var{repo}.git} to
@file{/srv/git/@var{repo}.git}.  Requests whose URI paths do not begin with
this prefix are not passed on to this Git instance.

@item @code{fcgiwrap-socket} (default: @code{127.0.0.1:9000})
The socket on which the @code{fcgiwrap} daemon is listening.  @xref{Serviços 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 {Procedure} git-http-nginx-location-configuration @
       [config=(git-http-configuration)] Compute an
@code{nginx-location-configuration} that corresponds to the given Git http
configuration.  An example nginx service definition to serve the default
@file{/srv/git} over HTTPS might be:

@lisp
(service nginx-service-type
         (nginx-configuration
          (server-blocks
           (list
            (nginx-server-configuration
             (listen '("443 ssl"))
             (server-name "git.my-host.org")
             (ssl-certificate
              "/etc/certs/git.my-host.org/fullchain.pem")
             (ssl-certificate-key
              "/etc/certs/git.my-host.org/privkey.pem")
             (locations
              (list
               (git-http-nginx-location-configuration
                (git-http-configuration (uri-path "/"))))))))))
@end lisp

This example assumes that you are using Let's Encrypt to get your TLS
certificate.  @xref{Serviços de certificado}.  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{Serviços web}.
@end deffn

@subsubheading Cgit Service

@cindex Cgit service
@cindex Git, web interface
@uref{https://git.zx2c4.com/cgit/, Cgit} is a web frontend for Git
repositories written in C.

The following example will configure the service with default values.  By
default, Cgit can be accessed on port 80 (@code{http://localhost:80}).

@lisp
(service cgit-service-type)
@end lisp

The @code{file-object} type designates either a file-like object
(@pxref{Expressões-G, file-like objects}) or a string.

@c %start of fragment

Available @code{cgit-configuration} fields are:

@deftypevr {@code{cgit-configuration} parameter} package package
The CGIT package.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} nginx-server-configuration-list nginx
NGINX configuration.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} file-object about-filter
Specifies a command which will be invoked to format the content of about
pages (both top-level and for each repository).

Defaults to @samp{""}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} string agefile
Specifies a path, relative to each repository path, which can be used to
specify the date and time of the youngest commit in the repository.

Defaults to @samp{""}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} file-object auth-filter
Specifies a command that will be invoked for authenticating repository
access.

Defaults to @samp{""}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} string branch-sort
Flag which, when set to @samp{age}, enables date ordering in the branch ref
list, and when set @samp{name} enables ordering by branch name.

Defaults to @samp{"name"}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} string cache-root
Path used to store the cgit cache entries.

Defaults to @samp{"/var/cache/cgit"}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} integer cache-static-ttl
Number which specifies the time-to-live, in minutes, for the cached version
of repository pages accessed with a fixed SHA1.

Defaults to @samp{-1}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} integer cache-dynamic-ttl
Number which specifies the time-to-live, in minutes, for the cached version
of repository pages accessed without a fixed SHA1.

Defaults to @samp{5}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} integer cache-repo-ttl
Number which specifies the time-to-live, in minutes, for the cached version
of the repository summary page.

Defaults to @samp{5}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} integer cache-root-ttl
Number which specifies the time-to-live, in minutes, for the cached version
of the repository index page.

Defaults to @samp{5}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} integer cache-scanrc-ttl
Number which specifies the time-to-live, in minutes, for the result of
scanning a path for Git repositories.

Defaults to @samp{15}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} integer cache-about-ttl
Number which specifies the time-to-live, in minutes, for the cached version
of the repository about page.

Defaults to @samp{15}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} integer cache-snapshot-ttl
Number which specifies the time-to-live, in minutes, for the cached version
of snapshots.

Defaults to @samp{5}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} integer cache-size
The maximum number of entries in the cgit cache.  When set to @samp{0},
caching is disabled.

Defaults to @samp{0}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} boolean case-sensitive-sort?
Sort items in the repo list case sensitively.

Defaults to @samp{#t}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} list clone-prefix
List of common prefixes which, when combined with a repository URL,
generates valid clone URLs for the repository.

Defaults to @samp{'()}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} list clone-url
List of @code{clone-url} templates.

Defaults to @samp{'()}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} file-object commit-filter
Command which will be invoked to format commit messages.

Defaults to @samp{""}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} string commit-sort
Flag which, when set to @samp{date}, enables strict date ordering in the
commit log, and when set to @samp{topo} enables strict topological ordering.

Defaults to @samp{"git log"}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} file-object css
URL which specifies the css document to include in all cgit pages.

Defaults to @samp{"/share/cgit/cgit.css"}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} file-object email-filter
Specifies a command which will be invoked to format names and email address
of committers, authors, and taggers, as represented in various places
throughout the cgit interface.

Defaults to @samp{""}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} boolean embedded?
Flag which, when set to @samp{#t}, will make cgit generate a HTML fragment
suitable for embedding in other HTML pages.

Defaults to @samp{#f}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} boolean enable-commit-graph?
Flag which, when set to @samp{#t}, will make cgit print an ASCII-art commit
history graph to the left of the commit messages in the repository log page.

Defaults to @samp{#f}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} boolean enable-filter-overrides?
Flag which, when set to @samp{#t}, allows all filter settings to be
overridden in repository-specific cgitrc files.

Defaults to @samp{#f}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} boolean enable-follow-links?
Flag which, when set to @samp{#t}, allows users to follow a file in the log
view.

Defaults to @samp{#f}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} boolean enable-http-clone?
If set to @samp{#t}, cgit will act as an dumb HTTP endpoint for Git clones.

Defaults to @samp{#t}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} boolean enable-index-links?
Flag which, when set to @samp{#t}, will make cgit generate extra links
"summary", "commit", "tree" for each repo in the repository index.

Defaults to @samp{#f}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} boolean enable-index-owner?
Flag which, when set to @samp{#t}, will make cgit display the owner of each
repo in the repository index.

Defaults to @samp{#t}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} boolean enable-log-filecount?
Flag which, when set to @samp{#t}, will make cgit print the number of
modified files for each commit on the repository log page.

Defaults to @samp{#f}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} boolean enable-log-linecount?
Flag which, when set to @samp{#t}, will make cgit print the number of added
and removed lines for each commit on the repository log page.

Defaults to @samp{#f}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} boolean enable-remote-branches?
Flag which, when set to @code{#t}, will make cgit display remote branches in
the summary and refs views.

Defaults to @samp{#f}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} boolean enable-subject-links?
Flag which, when set to @code{1}, will make cgit use the subject of the
parent commit as link text when generating links to parent commits in commit
view.

Defaults to @samp{#f}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} boolean enable-html-serving?
Flag which, when set to @samp{#t}, will make cgit use the subject of the
parent commit as link text when generating links to parent commits in commit
view.

Defaults to @samp{#f}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} boolean enable-tree-linenumbers?
Flag which, when set to @samp{#t}, will make cgit generate linenumber links
for plaintext blobs printed in the tree view.

Defaults to @samp{#t}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} boolean enable-git-config?
Flag which, when set to @samp{#f}, will allow cgit to use Git config to set
any repo specific settings.

Defaults to @samp{#f}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} file-object favicon
URL used as link to a shortcut icon for cgit.

Defaults to @samp{"/favicon.ico"}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} string footer
The content of the file specified with this option will be included verbatim
at the bottom of all pages (i.e.@: it replaces the standard "generated
by..."@: message).

Defaults to @samp{""}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} string head-include
The content of the file specified with this option will be included verbatim
in the HTML HEAD section on all pages.

Defaults to @samp{""}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} string header
The content of the file specified with this option will be included verbatim
at the top of all pages.

Defaults to @samp{""}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} file-object include
Name of a configfile to include before the rest of the current config- file
is parsed.

Defaults to @samp{""}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} string index-header
The content of the file specified with this option will be included verbatim
above the repository index.

Defaults to @samp{""}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} string index-info
The content of the file specified with this option will be included verbatim
below the heading on the repository index page.

Defaults to @samp{""}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} boolean local-time?
Flag which, if set to @samp{#t}, makes cgit print commit and tag times in
the servers timezone.

Defaults to @samp{#f}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} file-object logo
URL which specifies the source of an image which will be used as a logo on
all cgit pages.

Defaults to @samp{"/share/cgit/cgit.png"}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} string logo-link
URL loaded when clicking on the cgit logo image.

Defaults to @samp{""}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} file-object owner-filter
Command which will be invoked to format the Owner column of the main page.

Defaults to @samp{""}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} integer max-atom-items
Number of items to display in atom feeds view.

Defaults to @samp{10}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} integer max-commit-count
Number of entries to list per page in "log" view.

Defaults to @samp{50}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} integer max-message-length
Number of commit message characters to display in "log" view.

Defaults to @samp{80}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} integer max-repo-count
Specifies the number of entries to list per page on the repository index
page.

Defaults to @samp{50}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} integer max-repodesc-length
Specifies the maximum number of repo description characters to display on
the repository index page.

Defaults to @samp{80}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} integer max-blob-size
Specifies the maximum size of a blob to display HTML for in KBytes.

Defaults to @samp{0}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} string max-stats
Maximum statistics period.  Valid values are @samp{week},@samp{month},
@samp{quarter} and @samp{year}.

Defaults to @samp{""}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} mimetype-alist mimetype
Mimetype for the specified filename extension.

Defaults to @samp{'((gif "image/gif") (html "text/html") (jpg "image/jpeg")
(jpeg "image/jpeg") (pdf "application/pdf") (png "image/png") (svg
"image/svg+xml"))}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} file-object mimetype-file
Specifies the file to use for automatic mimetype lookup.

Defaults to @samp{""}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} string module-link
Text which will be used as the formatstring for a hyperlink when a submodule
is printed in a directory listing.

Defaults to @samp{""}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} boolean nocache?
If set to the value @samp{#t} caching will be disabled.

Defaults to @samp{#f}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} boolean noplainemail?
If set to @samp{#t} showing full author email addresses will be disabled.

Defaults to @samp{#f}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} boolean noheader?
Flag which, when set to @samp{#t}, will make cgit omit the standard header
on all pages.

Defaults to @samp{#f}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} project-list project-list
A list of subdirectories inside of @code{repository-directory}, relative to
it, that should loaded as Git repositories.  An empty list means that all
subdirectories will be loaded.

Defaults to @samp{'()}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} file-object readme
Text which will be used as default @code{repository-cgit-configuration}
@code{readme}.

Defaults to @samp{""}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} boolean remove-suffix?
If set to @code{#t} and @code{repository-directory} is enabled, if any
repositories are found with a suffix of @code{.git}, this suffix will be
removed for the URL and name.

Defaults to @samp{#f}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} integer renamelimit
Maximum number of files to consider when detecting renames.

Defaults to @samp{-1}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} string repository-sort
The way in which repositories in each section are sorted.

Defaults to @samp{""}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} robots-list robots
Text used as content for the @code{robots} meta-tag.

Defaults to @samp{'("noindex" "nofollow")}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} string root-desc
Text printed below the heading on the repository index page.

Defaults to @samp{"a fast webinterface for the git dscm"}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} string root-readme
The content of the file specified with this option will be included verbatim
below the ``about'' link on the repository index page.

Defaults to @samp{""}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} string root-title
Text printed as heading on the repository index page.

Defaults to @samp{""}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} boolean scan-hidden-path
If set to @samp{#t} and repository-directory is enabled,
repository-directory will recurse into directories whose name starts with a
period.  Otherwise, repository-directory will stay away from such
directories, considered as ``hidden''.  Note that this does not apply to the
@file{.git} directory in non-bare repos.

Defaults to @samp{#f}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} list snapshots
Text which specifies the default set of snapshot formats that cgit generates
links for.

Defaults to @samp{'()}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} repository-directory repository-directory
Name of the directory to scan for repositories (represents
@code{scan-path}).

Defaults to @samp{"/srv/git"}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} string section
The name of the current repository section - all repositories defined after
this option will inherit the current section name.

Defaults to @samp{""}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} string section-sort
Flag which, when set to @samp{1}, will sort the sections on the repository
listing by name.

Defaults to @samp{""}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} integer section-from-path
A number which, if defined prior to repository-directory, specifies how many
path elements from each repo path to use as a default section name.

Defaults to @samp{0}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} boolean side-by-side-diffs?
If set to @samp{#t} shows side-by-side diffs instead of unidiffs per
default.

Defaults to @samp{#f}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} file-object source-filter
Specifies a command which will be invoked to format plaintext blobs in the
tree view.

Defaults to @samp{""}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} integer summary-branches
Specifies the number of branches to display in the repository ``summary''
view.

Defaults to @samp{10}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} integer summary-log
Specifies the number of log entries to display in the repository ``summary''
view.

Defaults to @samp{10}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} integer summary-tags
Specifies the number of tags to display in the repository ``summary'' view.

Defaults to @samp{10}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} string strict-export
Filename which, if specified, needs to be present within the repository for
cgit to allow access to that repository.

Defaults to @samp{""}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} string virtual-root
URL which, if specified, will be used as root for all cgit links.

Defaults to @samp{"/"}.

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} repository-cgit-configuration-list repositories
A list of @code{repository-cgit-configuration} records.

Defaults to @samp{'()}.

Available @code{repository-cgit-configuration} fields are:

@deftypevr {@code{repository-cgit-configuration} parameter} repo-list snapshots
A mask of snapshot formats for this repo that cgit generates links for,
restricted by the global @code{snapshots} setting.

Defaults to @samp{'()}.

@end deftypevr

@deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object source-filter
Override the default @code{source-filter}.

Defaults to @samp{""}.

@end deftypevr

@deftypevr {@code{repository-cgit-configuration} parameter} repo-string url
The relative URL used to access the repository.

Defaults to @samp{""}.

@end deftypevr

@deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object about-filter
Override the default @code{about-filter}.

Defaults to @samp{""}.

@end deftypevr

@deftypevr {@code{repository-cgit-configuration} parameter} repo-string branch-sort
Flag which, when set to @samp{age}, enables date ordering in the branch ref
list, and when set to @samp{name} enables ordering by branch name.

Defaults to @samp{""}.

@end deftypevr

@deftypevr {@code{repository-cgit-configuration} parameter} repo-list clone-url
A list of URLs which can be used to clone repo.

Defaults to @samp{'()}.

@end deftypevr

@deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object commit-filter
Override the default @code{commit-filter}.

Defaults to @samp{""}.

@end deftypevr

@deftypevr {@code{repository-cgit-configuration} parameter} repo-string commit-sort
Flag which, when set to @samp{date}, enables strict date ordering in the
commit log, and when set to @samp{topo} enables strict topological ordering.

Defaults to @samp{""}.

@end deftypevr

@deftypevr {@code{repository-cgit-configuration} parameter} repo-string defbranch
The name of the default branch for this repository.  If no such branch
exists in the repository, the first branch name (when sorted) is used as
default instead.  By default branch pointed to by HEAD, or ``master'' if
there is no suitable HEAD.

Defaults to @samp{""}.

@end deftypevr

@deftypevr {@code{repository-cgit-configuration} parameter} repo-string desc
The value to show as repository description.

Defaults to @samp{""}.

@end deftypevr

@deftypevr {@code{repository-cgit-configuration} parameter} repo-string homepage
The value to show as repository homepage.

Defaults to @samp{""}.

@end deftypevr

@deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object email-filter
Override the default @code{email-filter}.

Defaults to @samp{""}.

@end deftypevr

@deftypevr {@code{repository-cgit-configuration} parameter} maybe-repo-boolean enable-commit-graph?
A flag which can be used to disable the global setting
@code{enable-commit-graph?}.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{repository-cgit-configuration} parameter} maybe-repo-boolean enable-log-filecount?
A flag which can be used to disable the global setting
@code{enable-log-filecount?}.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{repository-cgit-configuration} parameter} maybe-repo-boolean enable-log-linecount?
A flag which can be used to disable the global setting
@code{enable-log-linecount?}.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{repository-cgit-configuration} parameter} maybe-repo-boolean enable-remote-branches?
Flag which, when set to @code{#t}, will make cgit display remote branches in
the summary and refs views.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{repository-cgit-configuration} parameter} maybe-repo-boolean enable-subject-links?
A flag which can be used to override the global setting
@code{enable-subject-links?}.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{repository-cgit-configuration} parameter} maybe-repo-boolean enable-html-serving?
A flag which can be used to override the global setting
@code{enable-html-serving?}.

Defaults to @samp{disabled}.

@end deftypevr

@deftypevr {@code{repository-cgit-configuration} parameter} repo-boolean hide?
Flag which, when set to @code{#t}, hides the repository from the repository
index.

Defaults to @samp{#f}.

@end deftypevr

@deftypevr {@code{repository-cgit-configuration} parameter} repo-boolean ignore?
Flag which, when set to @samp{#t}, ignores the repository.

Defaults to @samp{#f}.

@end deftypevr

@deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object logo
URL which specifies the source of an image which will be used as a logo on
this repo’s pages.

Defaults to @samp{""}.

@end deftypevr

@deftypevr {@code{repository-cgit-configuration} parameter} repo-string logo-link
URL loaded when clicking on the cgit logo image.

Defaults to @samp{""}.

@end deftypevr

@deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object owner-filter
Override the default @code{owner-filter}.

Defaults to @samp{""}.

@end deftypevr

@deftypevr {@code{repository-cgit-configuration} parameter} repo-string module-link
Text which will be used as the formatstring for a hyperlink when a submodule
is printed in a directory listing.  The arguments for the formatstring are
the path and SHA1 of the submodule commit.

Defaults to @samp{""}.

@end deftypevr

@deftypevr {@code{repository-cgit-configuration} parameter} module-link-path module-link-path
Text which will be used as the formatstring for a hyperlink when a submodule
with the specified subdirectory path is printed in a directory listing.

Defaults to @samp{'()}.

@end deftypevr

@deftypevr {@code{repository-cgit-configuration} parameter} repo-string max-stats
Override the default maximum statistics period.

Defaults to @samp{""}.

@end deftypevr

@deftypevr {@code{repository-cgit-configuration} parameter} repo-string name
The value to show as repository name.

Defaults to @samp{""}.

@end deftypevr

@deftypevr {@code{repository-cgit-configuration} parameter} repo-string owner
A value used to identify the owner of the repository.

Defaults to @samp{""}.

@end deftypevr

@deftypevr {@code{repository-cgit-configuration} parameter} repo-string path
An absolute path to the repository directory.

Defaults to @samp{""}.

@end deftypevr

@deftypevr {@code{repository-cgit-configuration} parameter} repo-string readme
A path (relative to repo) which specifies a file to include verbatim as the
``About'' page for this repo.

Defaults to @samp{""}.

@end deftypevr

@deftypevr {@code{repository-cgit-configuration} parameter} repo-string section
The name of the current repository section - all repositories defined after
this option will inherit the current section name.

Defaults to @samp{""}.

@end deftypevr

@deftypevr {@code{repository-cgit-configuration} parameter} repo-list extra-options
Extra options will be appended to cgitrc file.

Defaults to @samp{'()}.

@end deftypevr

@end deftypevr

@deftypevr {@code{cgit-configuration} parameter} list extra-options
Extra options will be appended to cgitrc file.

Defaults to @samp{'()}.

@end deftypevr


@c %end of fragment

However, it could be that you just want to get a @code{cgitrc} up and
running.  In that case, you can pass an @code{opaque-cgit-configuration} as
a record to @code{cgit-service-type}.  As its name indicates, an opaque
configuration does not have easy reflective capabilities.

Available @code{opaque-cgit-configuration} fields are:

@deftypevr {@code{opaque-cgit-configuration} parameter} package cgit
The cgit package.
@end deftypevr

@deftypevr {@code{opaque-cgit-configuration} parameter} string string
The contents of the @code{cgitrc}, as a string.
@end deftypevr

For example, if your @code{cgitrc} is just the empty string, you could
instantiate a cgit service like this:

@lisp
(service cgit-service-type
         (opaque-cgit-configuration
          (cgitrc "")))
@end lisp

@subsubheading Gitolite Service

@cindex Gitolite service
@cindex Git, hosting
@uref{https://gitolite.com/gitolite/, Gitolite} is a tool for hosting Git
repositories on a central server.

Gitolite can handle multiple repositories and users, and supports flexible
configuration of the permissions for the users on the repositories.

The following example will configure Gitolite using the default @code{git}
user, and the provided SSH public key.

@lisp
(service gitolite-service-type
         (gitolite-configuration
           (admin-pubkey (plain-file
                           "yourname.pub"
                           "ssh-rsa AAAA... guix@@example.com"))))
@end lisp

Gitolite is configured through a special admin repository which you can
clone, for example, if you setup Gitolite on @code{example.com}, you would
run the following command to clone the admin repository.

@example
git clone git@@example.com:gitolite-admin
@end example

When the Gitolite service is activated, the provided @code{admin-pubkey}
will be inserted in to the @file{keydir} directory in the gitolite-admin
repository.  If this results in a change in the repository, it will be
committed using the message ``gitolite setup by GNU Guix''.

@deftp {Tipo de dados} gitolite-configuration
Data type representing the configuration for @code{gitolite-service-type}.

@table @asis
@item @code{package} (default: @code{gitolite})
Gitolite package to use.  There are optional Gitolite dependencies that are
not included in the default package, such as Redis and git-annex.  These
features can be made available by using the @code{make-gitolite} procedure
in the @code{(gnu packages version-control}) module to produce a variant of
Gitolite with the desired additional dependencies.

The following code returns a package in which the Redis and git-annex
programs can be invoked by Gitolite's scripts:

@example
(use-modules (gnu packages databases)
             (gnu packages haskell-apps)
             (gnu packages version-control))
(make-gitolite (list redis git-annex))
@end example

@item @code{user} (default: @code{"git"})
User to use for Gitolite.  This will be user that you use when accessing
Gitolite over SSH.

@item @code{group} (default: @code{"git"})
Group to use for Gitolite.

@item @code{home-directory} (default: @code{"/var/lib/gitolite"})
Directory in which to store the Gitolite configuration and repositories.

@item @code{rc-file} (default: @code{(gitolite-rc-file)})
A ``file-like'' object (@pxref{Expressões-G, file-like objects}),
representing the configuration for Gitolite.

@item @code{git-config} (default: @code{(gitolite-git-configuration)})
A ``file-like'' object (@pxref{Expressões-G, file-like objects}),
representing the git configuration for Gitolite.

@item @code{admin-pubkey}
A ``file-like'' object (@pxref{Expressões-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.

@lisp
(plain-file "yourname.pub" "ssh-rsa AAAA... guix@@example.com")
@end lisp

The file has to have @file{.pub} extension.

@item @code{admin-name} (default: @code{#f})
Usually the key name is derived by taking a base name of the
@code{admin-pubkey}.  The resulting file name is the name of the gitolite
user.  You can use this field to override the automatic name.

@end table
@end deftp

@deftp {Tipo de dados} gitolite-rc-file
Data type representing the Gitolite RC file.

@table @asis
@item @code{umask} (padrão: @code{#o0077})
This controls the permissions Gitolite sets on the repositories and their
contents.

A value like @code{#o0027} will give read access to the group used by
Gitolite (by default: @code{git}).  This is necessary when using Gitolite
with software like cgit or gitweb.

@item @code{local-code} (default: @code{"$rc@{GL_ADMIN_BASE@}/local"})
Allows you to add your own non-core programs, or even override the shipped
ones with your own.

Please supply the FULL path to this variable. By default, directory called
"local" in your gitolite clone is used, providing the benefits of versioning
them as well as making changes to them without having to log on to the
server.

@item @code{unsafe-pattern} (default: @code{#f})
An optional Perl regular expression for catching unsafe configurations in
the configuration file.  See
@uref{https://gitolite.com/gitolite/git-config.html#compensating-for-unsafe_patt,
Gitolite's documentation} for more information.

When the value is not @code{#f}, it should be a string containing a Perl
regular expression, such as @samp{"[`~#\$\&()|;<>]"}, which is the default
value used by gitolite.  It rejects any special character in configuration
that might be interpreted by a shell, which is useful when sharing the
administration burden with other people that do not otherwise have shell
access on the server.

@item @code{git-config-keys} (default: @code{""})
Gitolite allows you to set git config values using the @samp{config}
keyword.  This setting allows control over the config keys to accept.

@item @code{log-extra} (default: @code{#f})
Whether gitolite should log extra details.

For historical reasons, this field defaults to @code{#f}.  The default value
from gitolite however is @code{1} (written as @code{#t} in this
configuration).

@item @code{host-name} (padrão: @code{#f})
The host name of this gitolite instance.  It is used by the mirroring
feature.

@item @code{roles} (default: @code{'(("READERS" . 1) ("WRITERS" . ))})
Set the role names allowed to be used by users running the perms command.

@item @code{enable} (default: @code{'("help" "desc" "info" "perms" "writable" "ssh-authkeys" "git-config" "daemon" "gitweb")})
This setting controls the commands and features to enable within Gitolite.

@item @code{extra-content} (default: @code{""})
Extra content to add verbatim into the @code{%RC} hash.

@end table
@end deftp

@deftp {Data Type} gitolite-git-configuration
Data type representing the git configuration file for gitolite.

@table @asis
@item @code{name} (default: @code{"GNU GNU"})
User name used for commits (e.g. during setting up the admin repository).

@item @code{email} (default: @code{"guix@@localhost"})
Email used for commits (e.g. during setting up the admin repository).

@item @code{default-branch} (default: @code{#f})
If true, set the @code{init.defaultBranch} option to that value.  Common
values are @code{"master"} and @code{"main"}.

@item @code{receive-fsck-objects} (default: @code{#f})
If it is set to true, git-receive-pack will check all received objects.

@item @code{extra-content} (default: @code{""})
Extra content to add verbatim into the git configuration file.

@end table
@end deftp

@subsubheading Gitile Service

@cindex Serviço Gitile
@cindex Git, forge
@uref{https://git.lepiller.eu/gitile, Gitile} is a Git forge for viewing
public git repository contents from a web browser.

Gitile works best in collaboration with Gitolite, and will serve the public
repositories from Gitolite by default.  The service should listen only on a
local port, and a webserver should be configured to serve static resources.
The gitile service provides an easy way to extend the Nginx service for that
purpose (@pxref{NGINX}).

The following example will configure Gitile to serve repositories from a
custom location, with some default messages for the home page and the
footers.

@lisp
(service gitile-service-type
         (gitile-configuration
           (repositories "/srv/git")
           (base-git-url "https://myweb.site/git")
           (index-title "My git repositories")
           (intro '((p "This is all my public work!")))
           (footer '((p "This is the end")))
           (nginx
             (nginx-server-configuration
               (ssl-certificate
                 "/etc/certs/myweb.site/fullchain.pem")
               (ssl-certificate-key
                 "/etc/certs/myweb.site/privkey.pem")
               (listen '("443 ssl http2" "[::]:443 ssl http2"))
               (locations
                 (list
                   ;; Allow for https anonymous fetch on /git/ urls.
                   (git-http-nginx-location-configuration
                     (git-http-configuration
                       (uri-path "/git/")
                       (git-root "/var/lib/gitolite/repositories")))))))))
@end lisp

In addition to the configuration record, you should configure your git
repositories to contain some optional information.  First, your public
repositories need to contain the @file{git-daemon-export-ok} magic file that
allows Git to export the repository.  Gitile uses the presence of this file
to detect public repositories it should make accessible.  To do so with
Gitolite for instance, modify your @file{conf/gitolite.conf} to include this
in the repositories you want to make public:

@example
repo foo
    R = daemon
@end example

In addition, Gitile can read the repository configuration to display more
information on the repository.  Gitile uses the gitweb namespace for its
configuration.  As an example, you can use the following in your
@file{conf/gitolite.conf}:

@example
repo foo
    R = daemon
    desc = A long description, optionally with <i>HTML</i>, shown on the index page
    config gitweb.name = The Foo Project
    config gitweb.synopsis = A short description, shown on the main page of the project
@end example

Do not forget to commit and push these changes once you are satisfied.  You
may need to change your gitolite configuration to allow the previous
configuration options to be set.  One way to do that is to add the following
service definition:

@lisp
(service gitolite-service-type
          (gitolite-configuration
            (admin-pubkey (local-file "key.pub"))
            (rc-file
              (gitolite-rc-file
                (umask #o0027)
                ;; Allow to set any configuration key
                (git-config-keys ".*")
                ;; Allow any text as a valid configuration value
                (unsafe-patt "^$")))))
@end lisp

@deftp {Tipo de dados} gitile-configuration
Data type representing the configuration for @code{gitile-service-type}.

@table @asis
@item @code{package} (default: @var{gitile})
Gitile package to use.

@item @code{host} (default: @code{"localhost"})
The host on which gitile is listening.

@item @code{port} (padrão: @code{8080})
The port on which gitile is listening.

@item @code{database} (default: @code{"/var/lib/gitile/gitile-db.sql"})
The location of the database.

@item @code{repositories} (default: @code{"/var/lib/gitolite/repositories"})
The location of the repositories.  Note that only public repositories will
be shown by Gitile.  To make a repository public, add an empty
@file{git-daemon-export-ok} file at the root of that repository.

@item @code{git-owner-validation?} (default: @code{#t})
Whether to check for the service user's ownership of repositories.  By
default, Git will refuse to process a repository owned by another user.

@item @code{base-git-url}
The base git url that will be used to show clone commands.

@item @code{index-title} (default: @code{"Index"})
The page title for the index page that lists all the available repositories.

@item @code{intro} (default: @code{'()})
The intro content, as a list of sxml expressions.  This is shown above the
list of repositories, on the index page.

@item @code{footer} (default: @code{'()})
The footer content, as a list of sxml expressions.  This is shown on every
page served by Gitile.

@item @code{nginx}
An nginx server block that will be extended and used as a reverse proxy by
Gitile to serve its pages, and as a normal web server to serve its assets.

You can use this block to add more custom URLs to your domain, such as a
@code{/git/} URL for anonymous clones, or serving any other files you would
like to serve.
@end table
@end deftp


@node Serviços de jogos
@subsection Serviços de jogos

@subsubheading Joycond service
@cindex joycond
@cindex nintendo controllers
The joycond service allows the pairing of Nintendo joycon game controllers
over Bluetooth. (@pxref{Serviços de desktop} for setting up Bluetooth.)

@deftp {Tipo de dados} joycond-configuration
Data type representing the configuration of @command{joycond}.

@table @asis
@item @code{package} (default: @code{joycond})
The joycond package to use.
@end table
@end deftp

@defvar joycond-service-type
Service type for the joycond service.  It also extends the
@code{udev-service-type} with the @code{joycond} package (provided via the
@code{joycond-configuration} configuration), so that joycond controllers can
be detected and used by an unprivileged user.
@end defvar

@subsubheading The Battle for Wesnoth Service
@cindex wesnothd
@uref{https://wesnoth.org, The Battle for Wesnoth} is a fantasy, turn based
tactical strategy game, with several single player campaigns, and
multiplayer games (both networked and local).

@defvar wesnothd-service-type
Service type for the wesnothd service.  Its value must be a
@code{wesnothd-configuration} object.  To run wesnothd in the default
configuration, instantiate it as:

@lisp
(service wesnothd-service-type)
@end lisp
@end defvar

@deftp {Tipo de dados} wesnothd-configuration
Data type representing the configuration of @command{wesnothd}.

@table @asis
@item @code{package} (default: @code{wesnoth-server})
The wesnoth server package to use.

@item @code{port} (padrão: @code{15000})
The port to bind the server to.
@end table
@end deftp


@node Serviço de montagem PAM
@subsection Serviço de montagem PAM
@cindex pam-mount

The @code{(gnu services pam-mount)} module provides a service allowing users
to mount volumes when they log in.  It should be able to mount any volume
format supported by the system.

@defvar pam-mount-service-type
Service type for PAM Mount support.
@end defvar

@deftp {Tipo de dados} pam-mount-configuration
Data type representing the configuration of PAM Mount.

It takes the following parameters:

@table @asis
@item @code{rules}
The configuration rules that will be used to generate
@file{/etc/security/pam_mount.conf.xml}.

The configuration rules are SXML elements (@pxref{SXML,,, guile, GNU Guile
Reference Manual}), and the default ones don't mount anything for anyone at
login:

@lisp
`((debug (@@ (enable "0")))
  (mntoptions (@@ (allow ,(string-join
                          '("nosuid" "nodev" "loop"
                            "encryption" "fsck" "nonempty"
                            "allow_root" "allow_other")
                          ","))))
  (mntoptions (@@ (require "nosuid,nodev")))
  (logout (@@ (wait "0")
             (hup "0")
             (term "no")
             (kill "no")))
  (mkmountpoint (@@ (enable "1")
                   (remove "true"))))
@end lisp

Some @code{volume} elements must be added to automatically mount volumes at
login.  Here's an example allowing the user @code{alice} to mount her
encrypted @env{HOME} directory and allowing the user @code{bob} to mount the
partition where he stores his data:

@lisp
(define pam-mount-rules
`((debug (@@ (enable "0")))
            (volume (@@ (user "alice")
                       (fstype "crypt")
                       (path "/dev/sda2")
                       (mountpoint "/home/alice")))
            (volume (@@ (user "bob")
                       (fstype "auto")
                       (path "/dev/sdb3")
                       (mountpoint "/home/bob/data")
                       (options "defaults,autodefrag,compress")))
            (mntoptions (@@ (allow ,(string-join
                                    '("nosuid" "nodev" "loop"
                                      "encryption" "fsck" "nonempty"
                                      "allow_root" "allow_other")
                                    ","))))
            (mntoptions (@@ (require "nosuid,nodev")))
            (logout (@@ (wait "0")
                       (hup "0")
                       (term "no")
                       (kill "no")))
            (mkmountpoint (@@ (enable "1")
                             (remove "true")))))

(service pam-mount-service-type
         (pam-mount-configuration
           (rules pam-mount-rules)))
@end lisp

The complete list of possible options can be found in the man page for
@uref{http://pam-mount.sourceforge.net/pam_mount.conf.5.html,
pam_mount.conf}.
@end table
@end deftp

@subheading PAM Mount Volume Service
@cindex pam volume mounting

PAM mount volumes are automatically mounted at login by the PAM login
service according to a set of per-volume rules.  Because they are mounted by
PAM the password entered during login may be used directly to mount
authenticated volumes, such as @code{cifs}, using the same credentials.

These volumes will be added in addition to any volumes directly specified in
@code{pam-mount-rules}.

Here is an example of a rule which will mount a remote CIFS share from
@file{//remote-server/share} into a sub-directory of @file{/shares} named
after the user logging in:

@lisp
(simple-service 'pam-mount-remote-share pam-mount-volume-service-type
                (list (pam-mount-volume
                       (secondary-group "users")
                       (file-system-type "cifs")
                       (server "remote-server")
                       (file-name "share")
                       (mount-point "/shares/%(USER)")
                       (options "nosuid,nodev,seal,cifsacl"))))
@end lisp

@deftp {Tipo de dados} pam-mount-volume-service-type
Configuration for a single volume to be mounted.  Any fields not specified
will be omitted from the run-time PAM configuration.  See
@uref{http://pam-mount.sourceforge.net/pam_mount.conf.5.html, the man page}
for the default values when unspecified.

@table @asis
@item @code{user-name} (type: maybe-string)
Mount the volume for the given user.

@item @code{user-id} (type: maybe-integer-or-range)
Mount the volume for the user with this ID.  This field may also be
specified as a pair of @code{(start . end)} indicating a range of user IDs
for whom to mount the volume.

@item @code{primary-group} (type: maybe-string)
Mount the volume for users with this primary group name.

@item @code{group-id} (type: maybe-integer-or-range)
Mount the volume for the users with this primary group ID.  This field may
also be specified as a cons cell of @code{(start . end)} indicating a range
of group ids for whom to mount the volume.

@item @code{secondary-group} (type: maybe-string)
Mount the volume for users who are members of this group as either a primary
or secondary group.

@item @code{file-system-type} (type: maybe-string)
The file system type for the volume being mounted (e.g., @code{cifs})

@item @code{no-mount-as-root?} (type: maybe-boolean)
Whether or not to mount the volume with root privileges.  This is normally
disabled, but may be enabled for mounts of type @code{fuse}, or other
user-level mounts.

@item @code{server} (type: maybe-string)
The name of the remote server to mount the volume from, when necessary.

@item @code{file-name} (type: maybe-string)
The location of the volume, either local or remote, depending on the
@code{file-system-type}.

@item @code{mount-point} (type: maybe-string)
Where to mount the volume in the local file-system.  This may be set to
@file{~} to indicate the home directory of the user logging in.  If this
field is omitted then @file{/etc/fstab} is consulted for the mount
destination.

@item @code{options} (type: maybe-string)
The options to be passed as-is to the underlying mount program.

@item @code{ssh?} (type: maybe-boolean)
Enable this option to pass the login password to SSH for use with mounts
involving SSH (e.g., @code{sshfs}).

@item @code{cipher} (type: maybe-string)
Cryptsetup cipher name for the volume.  To be used with the @code{crypt}
@code{file-system-type}.

@item @code{file-system-key-cipher} (type: maybe-string)
Cipher name used by the target volume.

@item @code{file-system-key-hash} (type: maybe-string)
SSL hash name used by the target volume.

@item @code{file-system-key-file-name} (type: maybe-string)
File name of the file system key for the target volume.

@end table
@end deftp


@node Serviços Guix
@subsection Serviços Guix

@subsubheading Shared Cache Service
@cindex shared cache
@cindex cache, sharing

Running @command{guix pull}, @command{guix time-machine}, @command{guix
system reconfigure}, and @command{guix home reconfigure} pulls the complete
Git version control history of your channels in
@file{$HOME/.cache/guix/checkouts}.  If you have multiple user accounts
(typically @code{root} and a main user account for your personal computer),
or if multiple users are using the system (typically on a shared server),
then this can quickly waste a lot of space.

The @code{shared-cache} service lets you prevent this waste by either
sharing or exposing a specific user's cache to the other users.

In the context of this service, @emph{sharing} and @emph{exposing} have the
same meaning as with @command{guix shell}: making the shared cache directory
read-only if you use mode @option{'expose} (the default), and writable if
you use mode @option{'share}, (@pxref{Invocando guix shell, @option{--expose}
and @option{--share}}).

Whatever mode you choose, from the point of view of the user, the cache
appears writable.  With @option{'expose}, any write will be stored in a
user-owned overlay directory next to mountpoint, whereas with
@option{'share}, writes will be propagated back to the sharing user's cache.

@quotation Aviso
Use the @option{'share} option @emph{if and only if} users on the machine
trust each other.  This is a hard requirement since, with this option, any
user could ``poison'' the shared cache to indirectly gain access to other
user's data and privileges.
@end quotation

@quotation Aviso
Using @option{'share} is meant for a single-seat computer where the single
user has unprivileged user accounts---e.g. one for work and one for gaming.
Even then, channels from one will leak into the other's cache.  Use with
caution.
@end quotation

@quotation Aviso
@option{'share} will not work for multiple concurrent invocation of
@command{guix}, e.g. if two user accounts run @command{guix time machine} at
the same time, the results will be fun but not useful.
@end quotation

Here is an example configuration that exposes @code{root}'s guix checkout
cache to @code{alice} and @code{bob}:

@lisp
(operating-system
  ;; @dots{}
     (services
      (cons*
       (service shared-cache-service-type
             (shared-cache-configuration
               (users (list (user-cache (user "alice"))
                            (user-cache (user "bob"))))))
                    %desktop-services)))
@end lisp

The service can also be extended by providing a list of @code{user-cache},
allowing for easier splitting of configuration.

@lisp
(operating-system
  ;; @dots{}
  (services
   (cons*
    (simple-service 'bob-shared-guix-cache shared-cache-service-type
                    (list (user-cache (user "bob"))))
    %desktop-services)))
@end lisp

@defvar shared-cache-service-type
Service type for sharing a subdirectory of @file{~/.cache/} between multiple
users.

This service allows different system users to share the contents of the user
cache, avoiding duplication and saving disk space.  It can be configured in
either ``share'' mode, where all users write to the same cache, or
``expose'' mode, where users get a read-only view with a writable overlay.
Its value must be a @code{shared-cache-configuration} object.
@end defvar

@deftp {Data Type} shared-cache-configuration
Data type representing the configuration of the shared cache.

@table @asis
@item @code{mode} (default: @code{'expose})
Either @code{'share} (read-write, dangerous) or @code{'expose} (read-only
with per-user overlay, the default).  In share mode, all writes go to the
shared directory.  In expose mode, only reads use the shared directory;
writes go to a user-owned overlay.

@item @code{shared-directory} (default: @code{"/root/.cache"})
The source cache directory that is shared between users.  Each user will see
some or all of its subdirectories mounted into their own @file{~/.cache}.

@item @code{users} (default: @code{'()})
The list of users that will benefit from the shared directory.  This must be
a list of @code{user-info} records.

@end table
@end deftp

@deftp {Data Type} user-info
Data type representing the configuration for a single user benefitting from
a shared cache.

@table @asis
@item @code{user}
The username of the user.

@item @code{location} (default: @code{"/home/@var{user}/.cache"})
The cache directory of the user.

@item @code{group} (default: @code{"users"})
The primary group of the user.

@item @code{directories} (default: @code{'("guix/checkouts")})
List of subdirectories of the @code{shared-cache-configuration}'s
@code{shared-directory} (whose default is @file{/root/.cache}) to mount
under @var{location} (whose default is @file{~/.cache/}) for the user.
@end table
@end deftp

@subsubheading Build Farm Front-End (BFFE)
The @uref{https://git.cbaines.net/guix/bffe/,Build Farm Front-End} assists
with building Guix packages in bulk.  It's responsible for submitting builds
and displaying the status of the build farm.

@defvar bffe-service-type
Service type for the Build Farm Front-End.  Its value must be a
@code{bffe-configuration} object.
@end defvar

@deftp {Tipo de dados} bffe-configuration
Data type representing the configuration of the Build Farm Front-End.

@table @asis
@item @code{package} (default: @code{bffe})
The Build Farm Front-End package to use.

@item @code{user} (default: @code{"bffe"})
The system user to run the service as.

@item @code{group} (default: @code{"bffe"})
The system group to run the service as.

@item @code{arguments}
A list of arguments to the Build Farm Front-End.  These are passed to the
@code{run-bffe-service} procedure when starting the service.

For example, the following value directs the Build Farm Front-End to submit
builds for derivations available from @code{data.guix.gnu.org} to the Build
Coordinator instance assumed to be running on the same machine.

@example
(list
 #:build
 (list
  (build-from-guix-data-service
   (data-service-url "https://data.guix.gnu.org")
   (build-coordinator-url "http://127.0.0.1:8746")
   (branches '("master"))
   (systems '("x86_64-linux" "i686-linux"))
   (systems-and-targets
    (map (lambda (target)
           (cons "x86_64-linux" target))
         '("aarch64-linux-gnu"
           "i586-pc-gnu")))))
 #:web-server-args
 '(#:event-source "https://example.com"
   #:controller-args
   (#:title "example.com build farm")))
@end example

@item @code{extra-environment-variables} (default: @var{'()})
Extra environment variables to set via the shepherd service.

@end table
@end deftp

@subsubheading Guix Build Coordinator
The @uref{https://git.cbaines.net/guix/build-coordinator/,Guix Build
Coordinator} aids in distributing derivation builds among machines running
an @dfn{agent}.  The build daemon is still used to build the derivations,
but the Guix Build Coordinator manages allocating builds and working with
the results.

The Guix Build Coordinator consists of one @dfn{coordinator}, and one or
more connected @dfn{agent} processes.  The coordinator process handles
clients submitting builds, and allocating builds to agents.  The agent
processes talk to a build daemon to actually perform the builds, then send
the results back to the coordinator.

There is a script to run the coordinator component of the Guix Build
Coordinator, but the Guix service uses a custom Guile script instead, to
provide better integration with G-expressions used in the configuration.

@defvar guix-build-coordinator-service-type
Service type for the Guix Build Coordinator.  Its value must be a
@code{guix-build-coordinator-configuration} object.
@end defvar

@deftp {Tipo de dados} guix-build-coordinator-configuration
Data type representing the configuration of the Guix Build Coordinator.

@table @asis
@item @code{package} (default: @code{guix-build-coordinator})
The Guix Build Coordinator package to use.

@item @code{user} (default: @code{"guix-build-coordinator"})
The system user to run the service as.

@item @code{group} (default: @code{"guix-build-coordinator"})
The system group to run the service as.

@item @code{database-uri-string} (default: @code{"sqlite:///var/lib/guix-build-coordinator/guix_build_coordinator.db"})
The URI to use for the database.

@item @code{agent-communication-uri} (default: @code{"http://0.0.0.0:8745"})
The URI describing how to listen to requests from agent processes.

@item @code{client-communication-uri} (default: @code{"http://127.0.0.1:8746"})
The URI describing how to listen to requests from clients.  The client API
allows submitting builds and currently isn't authenticated, so take care
when configuring this value.

@item @code{allocation-strategy} (default: @code{#~basic-build-allocation-strategy})
A G-expression for the allocation strategy to be used.  This is a procedure
that takes the datastore as an argument and populates the allocation plan in
the database.

@item @code{hooks} (default: @var{'()})
An association list of hooks.  These provide a way to execute arbitrary code
upon certain events, like a build result being processed.

@item @code{parallel-hooks} (default: @var{'()})
Hooks can be configured to run in parallel.  This parameter is an
association list of hooks to do in parallel, where the key is the symbol for
the hook and the value is the number of threads to run.

@item @code{listen-repl} (default: @var{#f})
Port or filename to spawn a REPL listening on, pass @code{#t} to listen on
the default port or @code{#f} to disable.

@item @code{guile} (default: @code{guile-3.0-latest})
The Guile package with which to run the Guix Build Coordinator.

@item @code{extra-environment-variables} (default: @var{'()})
Extra environment variables to set via the shepherd service.

@end table
@end deftp

@defvar guix-build-coordinator-agent-service-type
Service type for a Guix Build Coordinator agent.  Its value must be a
@code{guix-build-coordinator-agent-configuration} object.
@end defvar

@deftp {Tipo de dados} guix-build-coordinator-agent-configuration
Data type representing the configuration a Guix Build Coordinator agent.

@table @asis
@item @code{package} (default: @code{guix-build-coordinator/agent-only})
The Guix Build Coordinator package to use.

@item @code{user} (default: @code{"guix-build-coordinator-agent"})
The system user to run the service as.

@item @code{coordinator} (default: @code{"http://localhost:8745"})
The URI to use when connecting to the coordinator.

@item @code{authentication}
Record describing how this agent should authenticate with the coordinator.
Possible record types are described below.

@item @code{systems} (default: @code{#f})
The systems for which this agent should fetch builds.  The agent process
will use the current system it's running on as the default.

@item @code{max-parallel-builds} (default: @code{#f})
The number of builds to perform in parallel.

@item @code{max-parallel-uploads} (default: @code{#f})
The number of uploads to perform in parallel.

@item @code{max-allocated-builds} (default: @code{#f})
The maximum number of builds this agent can be allocated.

@item @code{max-1min-load-average} (default: @code{#f})
Load average value to look at when considering starting new builds, if the 1
minute load average exceeds this value, the agent will wait before starting
new builds.

This will be unspecified if the value is @code{#f}, and the agent will use
the number of cores reported by the system as the max 1 minute load average.

@item @code{derivation-substitute-urls} (default: @code{#f})
URLs from which to attempt to fetch substitutes for derivations, if the
derivations aren't already available.

@item @code{non-derivation-substitute-urls} (default: @code{#f})
URLs from which to attempt to fetch substitutes for build inputs, if the
input store items aren't already available.

@item @code{extra-options} (default: @var{'()})
Extra command line options for @code{guix-build-coordinator-agent}.
@end table
@end deftp

@deftp {Tipo de dados} guix-build-coordinator-agent-password-auth
Data type representing an agent authenticating with a coordinator via a UUID
and password.

@table @asis
@item @code{uuid}
The UUID of the agent.  This should be generated by the coordinator process,
stored in the coordinator database, and used by the intended agent.

@item @code{password}
The password to use when connecting to the coordinator.

@end table
@end deftp

@deftp {Tipo de dados} guix-build-coordinator-agent-password-file-auth
Data type representing an agent authenticating with a coordinator via a UUID
and password read from a file.

@table @asis
@item @code{uuid}
The UUID of the agent.  This should be generated by the coordinator process,
stored in the coordinator database, and used by the intended agent.

@item @code{password-file}
A file containing the password to use when connecting to the coordinator.

@end table
@end deftp

@deftp {Tipo de dados} guix-build-coordinator-agent-dynamic-auth
Data type representing an agent authenticating with a coordinator via a
dynamic auth token and agent name.

@table @asis
@item @code{agent-name}
Name of an agent, this is used to match up to an existing entry in the
database if there is one.  When no existing entry is found, a new entry is
automatically added.

@item @code{token}
Dynamic auth token, this is created and stored in the coordinator database,
and is used by the agent to authenticate.

@end table
@end deftp

@deftp {Tipo de dados} guix-build-coordinator-agent-dynamic-auth-with-file
Data type representing an agent authenticating with a coordinator via a
dynamic auth token read from a file and agent name.

@table @asis
@item @code{agent-name}
Name of an agent, this is used to match up to an existing entry in the
database if there is one.  When no existing entry is found, a new entry is
automatically added.

@item @code{token-file}
File containing the dynamic auth token, this is created and stored in the
coordinator database, and is used by the agent to authenticate.

@end table
@end deftp

@subsubheading Guix Data Service
The @uref{http://data.guix.gnu.org,Guix Data Service} processes, stores and
provides data about GNU Guix.  This includes information about packages,
derivations and lint warnings.

The data is stored in a PostgreSQL database, and available through a web
interface.

@defvar guix-data-service-type
Service type for the Guix Data Service.  Its value must be a
@code{guix-data-service-configuration} object.  The service optionally
extends the getmail service, as the guix-commits mailing list is used to
find out about changes in the Guix git repository.
@end defvar

@deftp {Tipo de dados} guix-data-service-configuration
Data type representing the configuration of the Guix Data Service.

@table @asis
@item @code{package} (default: @code{guix-data-service})
The Guix Data Service package to use.

@item @code{user} (default: @code{"guix-data-service"})
The system user to run the service as.

@item @code{group} (default: @code{"guix-data-service"})
The system group to run the service as.

@item @code{port} (padrão: @code{8765})
The port to bind the web service to.

@item @code{host} (default: @code{"127.0.0.1"})
The host to bind the web service to.

@item @code{getmail-idle-mailboxes} (default: @code{#f})
If set, this is the list of mailboxes that the getmail service will be
configured to listen to.

@item @code{commits-getmail-retriever-configuration} (default: @code{#f})
If set, this is the @code{getmail-retriever-configuration} object with which
to configure getmail to fetch mail from the guix-commits mailing list.

@item @code{extra-options} (default: @var{'()})
Extra command line options for @code{guix-data-service}.

@item @code{extra-process-jobs-options} (default: @var{'()})
Extra command line options for @code{guix-data-service-process-jobs}.

@item @code{git-repositories} (default: @var{#f})
List of git-repository information to insert into the database.

@item @code{build-servers} (default: @var{#f})
List of build-server information to insert into the database.

@end table
@end deftp

@anchor{guix-home-service-type}
@subsubheading Guix Home Service

The Guix Home service is a way to let Guix System deploy the home
environment of one or more users (@pxref{Home Configuration}, for more on
Guix Home).  That way, the system configuration embeds declarations of the
home environment of those users and can be used to deploy everything
consistently at once, saving users the need to run @command{guix home
reconfigure} independently.

@command{guix home} can operate on the home environment configured for
current user via this service, but its effect won't last beyond the next
system activation.  This can be used for quick testing and may avoid the
need of keeping a separate home configuration.

@defvar guix-home-service-type
Service type for the Guix Home service.  Its value must be a list of lists
containing user and home environment pairs.  The key of each pair is a
string representing the user to deploy the configuration under and the value
is a home-environment configuration.

@lisp
(use-modules (gnu services guix))

(define my-home
  (home-environment
    @dots{}))

(operating-system
  (services (append (list (service guix-home-service-type
                                   `(("alice" ,my-home))))
                    %base-services)))
@end lisp

This service can be extended by other services to add additional home
environments, as in this example:

@lisp
(simple-service 'my-extra-home guix-home-service-type
                `(("bob" ,my-extra-home)))
@end lisp
@end defvar

@subsubheading Nar Herder
The @uref{https://git.cbaines.net/guix/nar-herder/about/,Nar Herder} is a
utility for managing a collection of nars.

@defvar nar-herder-type
Service type for the Guix Data Service.  Its value must be a
@code{nar-herder-configuration} object.  The service optionally extends the
getmail service, as the guix-commits mailing list is used to find out about
changes in the Guix git repository.
@end defvar

@deftp {Tipo de dados} nar-herder-configuration
Data type representing the configuration of the Guix Data Service.

@table @asis
@item @code{package} (default: @code{nar-herder})
The Nar Herder package to use.

@item @code{user} (default: @code{"nar-herder"})
The system user to run the service as.

@item @code{group} (default: @code{"nar-herder"})
The system group to run the service as.

@item @code{port} (padrão: @code{8734})
The port to bind the server to.

@item @code{host} (default: @code{"127.0.0.1"})
The host to bind the server to.

@item @code{control-port} (default: @code{8734})
The port to bind the control server to.

@item @code{control-host} (default: @code{"127.0.0.1"})
The host to bind the control server to.

@item @code{mirror} (default: @code{#f})
Optional URL of the other Nar Herder instance which should be mirrored.
This means that this Nar Herder instance will download it's database, and
keep it up to date.

@item @code{database} (default: @code{"/var/lib/nar-herder/nar_herder.db"})
Location for the database.  If this Nar Herder instance is mirroring
another, the database will be downloaded if it doesn't exist.  If this Nar
Herder instance isn't mirroring another, an empty database will be created.

@item @code{database-dump} (default: @code{"/var/lib/nar-herder/nar_herder_dump.db"})
Location of the database dump.  This is created and regularly updated by
taking a copy of the database.  This is the version of the database that is
available to download.

@item @code{storage} (default: @code{#f})
Optional location in which to store nars.

@item @code{storage-limit} (default: @code{"none"})
Limit in bytes for the nars stored in the storage location.  This can also
be set to ``none'' so that there is no limit.

When the storage location exceeds this size, nars are removed according to
the nar removal criteria.

@item @code{storage-nar-removal-criteria} (default: @code{'()})
Criteria used to remove nars from the storage location.  These are used in
conjunction with the storage limit.

When the storage location exceeds the storage limit size, nars will be
checked against the nar removal criteria and if any of the criteria match,
they will be removed.  This will continue until the storage location is
below the storage limit size.

Each criteria is specified by a string, then an equals sign, then another
string. Currently, only one criteria is supported, checking if a nar is
stored on another Nar Herder instance.

@item @code{ttl} (default: @code{#f})
Produce @code{Cache-Control} HTTP headers that advertise a time-to-live
(TTL) of @var{ttl}.  @var{ttl} must denote a duration: @code{5d} means 5
days, @code{1m} means 1 month, and so on.

This allows the user's Guix to keep substitute information in cache for
@var{ttl}.

@item @code{new-ttl} (default: @code{#f})
If specified, this will override the @code{ttl} setting when used for the
@code{Cache-Control} headers, but this value will be used when scheduling
the removal of nars.

Use this setting when the TTL is being reduced to avoid removing nars while
clients still have cached narinfos.

@item @code{negative-ttl} (default: @code{#f})
Similarly produce @code{Cache-Control} HTTP headers to advertise the
time-to-live (TTL) of @emph{negative} lookups---missing store items, for
which the HTTP 404 code is returned.  By default, no negative TTL is
advertised.

@item @code{log-level} (default: @code{'DEBUG})
Log level to use, specify a log level like @code{'INFO} to stop logging
individual requests.

@item @code{cached-compressions} (default: @code{'()})
Activate generating cached nars with different compression details from the
stored nars.  This is a list of nar-herder-cached-compression-configuration
records.

@item @code{min-uses} (default: @code{3})
When cached-compressions are enabled, generate cached nars when at least
this number of requests are made for a nar.

@item @code{workers} (default: @code{2})
Number of cached nars to generate at a time.

@item @code{nar-source} (default: @code{#f})
Location to fetch nars from when computing cached compressions.  By default,
the storage location will be used.

@item @code{extra-environment-variables} (default: @code{'()})
Extra environment variables to set via the shepherd service.

@end table
@end deftp

@deftp {Tipo de dados} nar-herder-cached-compression-configuration
Data type representing the cached compression configuration.

@table @asis
@item @code{tipo}
Type of compression to use, e.g. @code{'zstd}.

@item @code{workers} (default: @code{#f})
Level of the compression to use.

@item @code{directory} (default: @code{#f})
Location to store the cached nars.  If unspecified, they will be stored in
/var/cache/nar-herder/nar/TYPE.

@item @code{directory-max-size} (default: @code{#f})
Maximum size in bytes of the directory.

@item @code{unused-removal-duration} (default: @code{#f})
If a cached nar isn't used for @code{unused-removal-duration}, it will be
scheduled for removal.

@var{unused-removal-duration} must denote a duration: @code{5d} means 5
days, @code{1m} means 1 month, and so on.

@item @code{ttl} (default: @code{#f})
If specified this overrides the @code{ttl} used for narinfos when this
cached compression is available.

@item @code{new-ttl} (default: @code{#f})
As with the @code{new-ttl} option for @code{nar-herder-configuration}, this
value will override the @code{ttl} when used for narinfo requests.

@end table
@end deftp

@node Serviços Linux
@subsection Serviços Linux

@subsubheading VFS Mapping Service
@cindex VFS mapping
@cindex Virtual File System mapping
@cindex bind mounts, service
@cindex overlay mounts, service

The VFS (Virtual File System) Mapping service allows you to bind a file name
under a different name in the global namespace.  For example, this is used
by the Shared Cache Service (@pxref{Serviços Guix}) to bind the @samp{root}
user's cache over another user's cache.  Another use case may be to expose
game data from the store over your home directory, and apply modifications
there.

The service has three @emph{policies} to choose from with respect to access
rights on the bound over path:

@table @code
@item 'bind
Use a bind mount; the ownership and file permissions of the destination are
the same as the source.

@item 'translate
Use bindfs to make the destination appear as owned by the target user and
group.  Writes will be propagated back to the source as if made by the
original owner.

@item 'overlay
Use an overlay to make the destination appear as owned by the target user
and group. Writes will not appear in the source, but will be stored in a
target-user-owned @samp{-overlay} suffixed directory near the destination.
@end table

Here is an example configuration that exposes the default data directory of
@command{tuxpaint} under the home directory of @code{alice}.  Any
modification made by Alice to the brushes or stamps will not propagate back
to the store (which is read-only anyway).

@lisp
(operating-system
  ;; @dots{}
  (services
   (cons*
    (service vfs-mapping-service-type
             (vfs-mapping-configuration
              (bindings (list (vfs-mapping
                               (source      #~(string-append #$tuxpaint
                                                             "/share/tuxpaint"))
                               (destination "/home/alice/.tuxpaint")
                               (user        "alice")
                               (policy      'overlay)
                               (name        "alice-tuxpaint-overlay"))))))
    %desktop-services)))
@end lisp

The service can also be extended by providing a list of @code{vfs-mapping},
allowing for easier splitting of configuration.

@lisp
(operating-system
  ;; @dots{}
  (services
   (cons*
    (simple-service 'bob-too-wants-to-hack-on-tuxpaint
                    vfs-mapping-service-type
                    (list (vfs-mapping
                           (source      #~(string-append #$tuxpaint "/share/tuxpaint"))
                           (destination "/home/bob/.tuxpaint")
                           (user        "bob")
                           (policy      'overlay)
                           (name        "bob-tuxpaint-overlay"))))
    %desktop-services)))
@end lisp

The @code{source} file name must exist for the service to start.  The
@code{destination} directory will be created if it does not exist.

@defvar vfs-mapping-service-type
Service type for binding a directory in multiple places on the file system.

The access rights are either the same in source and destination
(@code{'bind}), or writes are translated back to the source as if made by
the source's owner (@code{'translate}), or kept in an overlay directory near
the destination (@code{'overlay}).  The service's value must be a
@code{vfs-mapping-configuration} object.
@end defvar

@deftp {Data Type} vfs-mapping-configuration
Data type representing the configuration of the vfs-mapping service.

@table @asis
@item @code{bindfs} (default: @code{#~(string-append #$bindfs "/bin/bindfs")})
The @command{bindfs} command to use for mounting.

@item @code{fusermount} (default: @code{#~(string-append #$fuse-2 "/bin/fusermount")})
The @command{fusermount} command to use.

@item @code{umount} (default: @code{#~(string-append #$util-linux+udev "/bin/umount")})
The @command{umount} command to use.

@item @code{bindings} (default: @code{'()})
A list of @code{vfs-mapping} records.

@end table
@end deftp

@deftp {Data Type} vfs-mapping
Data type representing the configuration for a single shared directory.

@table @asis
@item @code{source}
The source file name to be shared.

@item @code{destination}
The destination at which the contents of @code{source} will be exposed.

@item @code{policy} (default: @code{'translate})
Either @code{'bind} (same ownership and access rights for @code{source} and
@code{destination}), @code{'translate} (read-write, with writes translated
as if made by @code{source}'s owner), or @code{'overlay} (read-only with
@code{user}-owned writable overlay).

@item @code{user} (default: @code{#f})
The user that will own the @code{destination} directory, and appear to own
its content.  It must be kept at its default @code{#f} value when using the
@code{'bind} policy.

@item @code{group} (default: @code{"users"})
The group that will own the @code{destination} directory, and appear to own
its content.

@item @code{name} (default: @code{"<src>-[<policy>]-><dst>"})
The name of the shepherd service to mount and unmount the binding.

@item @code{requirement} (default: @code{'(file-systems user-homes)})
The list of services that Shepherd ought to provision before trying to
mount.

@end table
@end deftp

@cindex oom
@cindex out of memory killer
@cindex earlyoom
@cindex early out of memory daemon
@subsubheading Early OOM Service

@uref{https://github.com/rfjakob/earlyoom,Early OOM}, also known as
Earlyoom, is a minimalist out of memory (OOM) daemon that runs in user space
and provides a more responsive and configurable alternative to the in-kernel
OOM killer.  It is useful to prevent the system from becoming unresponsive
when it runs out of memory.

@defvar earlyoom-service-type
The service type for running @command{earlyoom}, the Early OOM daemon.  Its
value must be a @code{earlyoom-configuration} object, described below.  The
service can be instantiated in its default configuration with:

@lisp
(service earlyoom-service-type)
@end lisp
@end defvar

@deftp {Tipo de dados} earlyoom-configuration
This is the configuration record for the @code{earlyoom-service-type}.

@table @asis
@item @code{earlyoom} (default: @var{earlyoom})
The Earlyoom package to use.

@item @code{minimum-available-memory} (default: @code{10})
The threshold for the minimum @emph{available} memory, in percentages.

@item @code{minimum-free-swap} (default: @code{10})
The threshold for the minimum free swap memory, in percentages.

@item @code{prefer-regexp} (default: @code{#f})
A regular expression (as a string) to match the names of the processes that
should be preferably killed.

@item @code{avoid-regexp} (default: @code{#f})
A regular expression (as a string) to match the names of the processes that
should @emph{not} be killed.

@item @code{memory-report-interval} (default: @code{0})
The interval in seconds at which a memory report is printed.  It is disabled
by default.

@item @code{ignore-positive-oom-score-adj?} (default: @code{#f})
A boolean indicating whether the positive adjustments set in
@file{/proc/*/oom_score_adj} should be ignored.

@item @code{show-debug-messages?} (default: @code{#f})
A boolean indicating whether debug messages should be printed.  The logs are
saved at @file{/var/log/earlyoom.log}.

@item @code{send-notification-command} (default: @code{#f})
This can be used to provide a custom command used for sending notifications.
@end table
@end deftp

@subsubheading fstrim Service
@cindex fstrim service
@cindex solid state drives, periodic trim
@cindex solid state drives, trim

The command @command{fstrim} can be used to discard (or @dfn{trim})  unused
blocks on a mounted file system.

@c This was copied from the fstrim manpage, with some Texinfo touch-ups.
@quotation Aviso
Running @command{fstrim} frequently, or even using @command{mount -o
discard}, might negatively affect the lifetime of poor-quality SSD devices.
For most desktop and server systems a sufficient trimming frequency is once
a week.  Note that not all devices support a queued trim, so each trim
command incurs a performance penalty on whatever else might be trying to use
the disk at the time.
@end quotation

@defvar fstrim-service-type
Type for a service that periodically runs @command{fstrim}, whose value must
be an @code{<fstrim-configuration>} object.  The service can be instantiated
in its default configuration with:

@lisp
(service fstrim-service-type)
@end lisp
@end defvar

@c %start of fragment

@deftp {Tipo de dados} fstrim-configuration
Available @code{fstrim-configuration} fields are:

@table @asis
@item @code{package} (default: @code{util-linux}) (type: file-like)
The package providing the @command{fstrim} command.

@item @code{schedule} (default: @code{"0 0 * * 0"}) (type: Shepherd calendar event)
Schedule for launching @command{fstrim}, expressed as a string in
traditional cron syntax or as a gexp evaluating to a Shepherd calendar event
(@pxref{Timers,,, shepherd,The GNU Shepherd Manual}).  By default this is
set to run weekly on Sunday at 00:00.

@item @code{listed-in} (default: @code{'("/etc/fstab" "/proc/self/mountinfo")}) (type: maybe-list-of-strings)
List of files in fstab or kernel mountinfo format.  All missing or empty
files are silently ignored.  The evaluation of the list @emph{stops} after
the first non-empty file.  File systems with @code{X-fstrim.notrim} mount
option in fstab are skipped.

@item @code{verbose?} (default: @code{#t}) (type: boolean)
Verbose execution.

@item @code{quiet-unsupported?} (default: @code{#t}) (type: boolean)
Suppress error messages if trim operation (ioctl) is unsupported.

@item @code{extra-arguments} (type: maybe-list-of-strings)
Extra options to append to @command{fstrim} (run @samp{man fstrim} for more
information).

@end table

@end deftp


@c %end of fragment

@cindex modprobe
@cindex kernel module loader
@subsubheading Kernel Module Loader Service

The kernel module loader service allows one to load loadable kernel modules
at boot.  This is especially useful for modules that don't autoload and need
to be manually loaded, as is the case with @code{ddcci}.

@defvar kernel-module-loader-service-type
The service type for loading loadable kernel modules at boot with
@command{modprobe}.  Its value must be a list of strings representing module
names.  For example loading the drivers provided by
@code{ddcci-driver-linux}, in debugging mode by passing some module
parameters, can be done as follow:

@lisp
(use-modules (gnu) (gnu services))
(use-package-modules linux)
(use-service-modules linux)

(define ddcci-config
  (plain-file "ddcci.conf"
              "options ddcci dyndbg delay=120"))

(operating-system
  ...
  (services (cons* (service kernel-module-loader-service-type
                            '("ddcci" "ddcci_backlight"))
                   (simple-service 'ddcci-config etc-service-type
                                   (list `("modprobe.d/ddcci.conf"
                                           ,ddcci-config)))
                   %base-services))
  (kernel-loadable-modules (list ddcci-driver-linux)))
@end lisp
@end defvar

@subsubheading Cachefilesd Service

@cindex cachefilesd
@cindex fscache, file system caching (Linux)
The Cachefilesd service starts a daemon that caches network file system data
locally.  It is especially useful for NFS and AFS shares, where it reduces
latencies for repeated access when reading files.

The daemon can be configured as follows:

@lisp
(service cachefilesd-service-type
         (cachefilesd-configuration
           (cache-directory "/var/cache/fscache")))
@end lisp

@defvar cachefilesd-service-type
The service type for starting @command{cachefilesd}.  The value for this
service type is a @code{cachefilesd-configuration}, whose only required
field is @var{cache-directory}.

@end defvar

@c %start of fragment
@deftp {Tipo de dados} cachefilesd-configuration
Available @code{cachefilesd-configuration} fields are:

@table @asis
@item @code{cachefilesd} (default: @code{cachefilesd}) (type: file-like)
The cachefilesd package to use.

@item @code{debug-output?} (default: @code{#f}) (type: boolean)
Print debugging output to stderr.

@item @code{use-syslog?} (default: @code{#t}) (type: boolean)
Log to syslog facility instead of stdout.

@item @code{scan?} (default: @code{#t}) (type: boolean)
Scan for cacheable objects.

@item @code{cache-directory} (type: maybe-string)
Location of the cache directory.

@item @code{cache-name} (default: @code{"CacheFiles"}) (type: maybe-string)
Name of cache (keep unique).

@item @code{security-context} (type: maybe-string)
SELinux security context.

@item @code{pause-culling-for-block-percentage} (default: @code{7}) (type: maybe-non-negative-integer)
Pause culling when available blocks exceed this percentage.

@item @code{pause-culling-for-file-percentage} (default: @code{7}) (type: maybe-non-negative-integer)
Pause culling when available files exceed this percentage.

@item @code{resume-culling-for-block-percentage} (default: @code{5}) (type: maybe-non-negative-integer)
Start culling when available blocks drop below this percentage.

@item @code{resume-culling-for-file-percentage} (default: @code{5}) (type: maybe-non-negative-integer)
Start culling when available files drop below this percentage.

@item @code{pause-caching-for-block-percentage} (default: @code{1}) (type: maybe-non-negative-integer)
Pause further allocations when available blocks drop below this percentage.

@item @code{pause-caching-for-file-percentage} (default: @code{1}) (type: maybe-non-negative-integer)
Pause further allocations when available files drop below this percentage.

@item @code{log2-table-size} (default: @code{12}) (type: maybe-non-negative-integer)
Size of tables holding cullable objects in logarithm of base 2.

@item @code{cull?} (default: @code{#t}) (type: boolean)
Create free space by culling (consumes system load).

@item @code{trace-function-entry-in-kernel-module?} (default: @code{#f}) (type: boolean)
Trace function entry in the kernel module (for debugging).

@item @code{trace-function-exit-in-kernel-module?} (default: @code{#f}) (type: boolean)
Trace function exit in the kernel module (for debugging).

@item @code{trace-internal-checkpoints-in-kernel-module?} (default: @code{#f}) (type: boolean)
Trace internal checkpoints in the kernel module (for debugging).

@end table
@end deftp
@c %end of fragment

@cindex rasdaemon
@cindex Platform Reliability, Availability and Serviceability daemon
@subsubheading Rasdaemon Service

The Rasdaemon service provides a daemon which monitors platform
@acronym{RAS, Reliability@comma{} Availability@comma{} and Serviceability}
reports from Linux kernel trace events, logging them to syslogd.

Reliability, Availability and Serviceability is a concept used on servers
meant to measure their robustness.

@strong{Relability} is the probability that a system will produce correct
outputs:

@itemize @bullet
@item Generally measured as Mean Time Between Failures (MTBF), and
@item Enhanced by features that help to avoid, detect and repair hardware
faults
@end itemize

@strong{Availability} is the probability that a system is operational at a
given time:

@itemize @bullet
@item Generally measured as a percentage of downtime per a period of time, and
@item Often uses mechanisms to detect and correct hardware faults in runtime.
@end itemize

@strong{Serviceability} is the simplicity and speed with which a system can
be repaired or maintained:

@itemize @bullet
@item Generally measured on Mean Time Between Repair (MTBR).
@end itemize


Among the monitoring measures, the most usual ones include:

@itemize @bullet
@item CPU – detect errors at instruction execution and at L1/L2/L3 caches;
@item Memory – add error correction logic (ECC) to detect and correct errors;
@item I/O – add CRC checksums for transferred data;
@item Storage – RAID, journal file systems, checksums, Self-Monitoring,
Analysis and Reporting Technology (SMART).
@end itemize

By monitoring the number of occurrences of error detections, it is possible
to identify if the probability of hardware errors is increasing, and, on
such case, do a preventive maintenance to replace a degraded component while
those errors are correctable.

For detailed information about the types of error events gathered and how to
make sense of them, see the kernel administrator's guide at
@url{https://www.kernel.org/doc/html/latest/admin-guide/ras.html}.

@defvar rasdaemon-service-type
Service type for the @command{rasdaemon} service.  It accepts a
@code{rasdaemon-configuration} object.  Instantiating like

@lisp
(service rasdaemon-service-type)
@end lisp

will load with a default configuration, which monitors all events and logs
to syslogd.
@end defvar

@deftp {Tipo de dados} rasdaemon-configuration
The data type representing the configuration of @command{rasdaemon}.

@table @asis
@item @code{record?} (default: @code{#f})

A boolean indicating whether to record the events in an SQLite database.
This provides a more structured access to the information contained in the
log file.  The database location is hard-coded to
@file{/var/lib/rasdaemon/ras-mc_event.db}.

@end table
@end deftp

@cindex zram
@cindex compressed swap
@cindex Compressed RAM-based block devices
@subsubheading Zram Device Service

The Zram device service provides a compressed swap device in system memory.
The Linux Kernel documentation has more information about
@uref{https://www.kernel.org/doc/html/latest/admin-guide/blockdev/zram.html,zram}
devices.

@defvar zram-device-service-type
This service creates the zram block device, formats it as swap and enables
it as a swap device.  The service's value is a
@code{zram-device-configuration} record.

@deftp {Tipo de dados} zram-device-configuration
This is the data type representing the configuration for the zram-device
service.

@table @asis
@item @code{size} (default @code{"1G"})
This is the amount of space you wish to provide for the zram device.  It
accepts a string and can be a number of bytes or use a suffix, eg.:
@code{"512M"} or @code{1024000}.
@item @code{compression-algorithm} (default @code{'lzo})
This is the compression algorithm you wish to use.  It is difficult to list
all the possible compression options, but common ones supported by Guix's
Linux Libre Kernel include @code{'lzo}, @code{'lz4} and @code{'zstd}.
@item @code{memory-limit} (default @code{0})
This is the maximum amount of memory which the zram device can use.  Setting
it to '0' disables the limit.  While it is generally expected that
compression will be 2:1, it is possible that uncompressable data can be
written to swap and this is a method to limit how much memory can be used.
It accepts a string and can be a number of bytes or use a suffix, eg.:
@code{"2G"}.
@item @code{priority} (default @code{#f})
This is the priority of the swap device created from the zram device.
@xref{Espaço de troca (swap)} for a description of swap priorities.  You might want to
set a specific priority for the zram device, otherwise it could end up not
being used much for the reasons described there.
@end table

@end deftp
@end defvar

@node Serviços Hurd
@subsection Serviços Hurd

@defvar hurd-console-service-type
This service starts the fancy @code{VGA} console client on the Hurd.

The service's value is a @code{hurd-console-configuration} record.
@end defvar

@deftp {Tipo de dados} hurd-console-configuration
This is the data type representing the configuration for the
hurd-console-service.

@table @asis
@item @code{hurd} (default: @var{hurd})
The Hurd package to use.
@end table
@end deftp

@defvar hurd-getty-service-type
This service starts a tty using the Hurd @code{getty} program.

The service's value is a @code{hurd-getty-configuration} record.
@end defvar

@deftp {Tipo de dados} hurd-getty-configuration
This is the data type representing the configuration for the
hurd-getty-service.

@table @asis
@item @code{hurd} (default: @var{hurd})
The Hurd package to use.

@item @code{tty}
The name of the console this Getty runs on---e.g., @code{"tty1"}.

@item @code{baud-rate} (default: @code{38400})
An integer specifying the baud rate of the tty.

@end table
@end deftp

@node Serviços diversos
@subsection Serviços diversos

@cindex fingerprint
@subsubheading Fingerprint Service

The @code{(gnu services authentication)} module provides a DBus service to
read and identify fingerprints via a fingerprint sensor.

@defvar fprintd-service-type
The service type for @command{fprintd}, which provides the fingerprint
reading capability.

@lisp
(service fprintd-service-type)
@end lisp
@end defvar

@cindex sysctl
@subsubheading System Control Service

The @code{(gnu services sysctl)} provides a service to configure kernel
parameters at boot.

@defvar sysctl-service-type
The service type for @command{sysctl}, which modifies kernel parameters
under @file{/proc/sys/}.  To enable IPv4 forwarding, it can be instantiated
as:

@lisp
(service sysctl-service-type
         (sysctl-configuration
           (settings '(("net.ipv4.ip_forward" . "1")))))
@end lisp

Since @code{sysctl-service-type} is used in the default lists of services,
@code{%base-services} and @code{%desktop-services}, you can use
@code{modify-services} to change its configuration and add the kernel
parameters that you want (@pxref{Referência de Service,
@code{modify-services}}).

@lisp
(modify-services %base-services
  (sysctl-service-type config =>
                       (sysctl-configuration
                         (settings (append '(("net.ipv4.ip_forward" . "1"))
                                           %default-sysctl-settings)))))
@end lisp

@end defvar

@deftp {Tipo de dados} sysctl-configuration
The data type representing the configuration of @command{sysctl}.

@table @asis
@item @code{sysctl} (default: @code{(file-append procps "/sbin/sysctl"})
The @command{sysctl} executable to use.

@item @code{settings} (default: @code{%default-sysctl-settings})
An association list specifies kernel parameters and their values.
@end table
@end deftp

@defvar %default-sysctl-settings
An association list specifying the default @command{sysctl} parameters on
Guix System.
@end defvar

@cindex pcscd
@subsubheading PC/SC Smart Card Daemon Service

The @code{(gnu services security-token)} module provides the following
service to run @command{pcscd}, the PC/SC Smart Card Daemon.
@command{pcscd} is the daemon program for pcsc-lite and the MuscleCard
framework.  It is a resource manager that coordinates communications with
smart card readers, smart cards and cryptographic tokens that are connected
to the system.

@defvar pcscd-service-type
Service type for the @command{pcscd} service.  Its value must be a
@code{pcscd-configuration} object.  To run pcscd in the default
configuration, instantiate it as:

@lisp
(service pcscd-service-type)
@end lisp
@end defvar

@deftp {Tipo de dados} pcscd-configuration
The data type representing the configuration of @command{pcscd}.

@table @asis
@item @code{pcsc-lite} (default: @code{pcsc-lite})
The pcsc-lite package that provides pcscd.
@item @code{usb-drivers} (default: @code{(list ccid)})
List of packages that provide USB drivers to pcscd.  Drivers are expected to
be under @file{pcsc/drivers} in the store directory of the package.
@end table
@end deftp

@cindex LIRC
@subsubheading LIRC Service

The @code{(gnu services lirc)} module provides the following service.

@defvar lirc-service-type
Type for a service that runs @url{http://www.lirc.org, LIRC}, a daemon that
decodes infrared signals from remote controls.

The value for this service is a @code{<lirc-configuration>} object.
@end defvar

@deftp {Tipo de dados} lirc-configuration
Data type representing the configuration of @command{lircd}.

@table @asis
@item @code{lirc} (default: @code{lirc}) (type: file-like)
Package object for @command{lirc}.

@item @code{device} (default: @code{#f}) (type: string)
@itemx @code{driver} (default: @code{#f}) (type: string)
@itemx @code{config-file} (default: @code{#f}) (type: string-or-file-like)
TODO.  See @command{lircd} manual for details.

@item @code{extra-options} (default: @code{'()}) (type: list-of-string)
Additional command-line options to pass to @command{lircd}.

@end table
@end deftp

@c TODO: Document <lirc-configuration>, preferably by refactoring this to use
@c       define-configuration and generating documentation from it.

@cindex SPICE
@subsubheading SPICE Service

The @code{(gnu services spice)} module provides the following service.

@defvar spice-vdagent-service-type
Type of the service that runs @url{https://www.spice-space.org, VDAGENT}, a
daemon that enables sharing the clipboard with a vm and setting the guest
display resolution when the graphical console window resizes.
@end defvar

@deftp {Tipo de dados} spice-vdagent-configuration
Data type representing the configuration of
@code{spice-vdagent-service-type}.

@table @asis
@item @code{spice-vdagent} (default: @code{spice-vdagent}) (type: file-like)
Package object for VDAGENT.

@end table
@end deftp

@cindex inputattach
@subsubheading inputattach Service

@cindex tablet input, for Xorg
@cindex touchscreen input, for Xorg
The @uref{https://linuxwacom.github.io/, inputattach} service allows you to
use input devices such as Wacom tablets, touchscreens, or joysticks with the
Xorg display server.

@defvar inputattach-service-type
Type of a service that runs @command{inputattach} on a device and dispatches
events from it.
@end defvar

@deftp {Tipo de dados} 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} (padrão: @code{"/dev/ttyS0"})
The device file to connect to the device.

@item @code{baud-rate} (default: @code{#f})
Baud rate to use for the serial connection.  Should be a number or
@code{#f}.

@item @code{log-file} (default: @code{#f})
If true, this must be the name of a file to log messages to.
@end table
@end deftp

@subsubheading Dictionary Service
@cindex dicionário

The @code{(gnu services dict)} module provides the following service:

@defvar dicod-service-type
This is the type of the service that runs the @command{dicod} daemon, an
implementation of DICT server (@pxref{Dicod,,, dico, GNU Dico Manual}).

You can add @command{open localhost} to your @file{~/.dico} file to make
@code{localhost} the default server for @command{dico} client
(@pxref{Initialization File,,, dico, GNU Dico Manual}).

@quotation Nota
This service is also available for Guix Home, where it runs directly with
your user privileges (@pxref{Miscellaneous Home Services,
@code{home-dicod-service-type}}).
@end quotation
@end defvar

@deftp {Tipo de dados} dicod-configuration
Data type representing the configuration of dicod.

@table @asis
@item @code{dico} (default: @var{dico})
Package object of the GNU Dico dictionary server.

@item @code{interfaces} (default: @var{'("localhost")})
This is the list of IP addresses and ports and possibly socket file names to
listen to (@pxref{Server Settings, @code{listen} directive,, dico, GNU Dico
Manual}).

@item @code{handlers} (default: @var{'()})
List of @code{<dicod-handler>} objects denoting handlers (module instances).

@item @code{databases} (default: @var{(list %dicod-database:gcide)})
List of @code{<dicod-database>} objects denoting dictionaries to be served.
@end table
@end deftp

@deftp {Tipo de dados} dicod-handler
Data type representing a dictionary handler (module instance).

@table @asis
@item @code{name}
Name of the handler (module instance).

@item @code{module} (default: @var{#f})
Name of the dicod module of the handler (instance).  If it is @code{#f}, the
module has the same name as the handler.  (@pxref{Modules,,, dico, GNU Dico
Manual}).

@item @code{options}
List of strings or gexps representing the arguments for the module handler
@end table
@end deftp

@deftp {Tipo de dados} dicod-database
Data type representing a dictionary database.

@table @asis
@item @code{name}
Name of the database, will be used in DICT commands.

@item @code{handler}
Name of the dicod handler (module instance) used by this database
(@pxref{Handlers,,, dico, GNU Dico Manual}).

@item @code{complex?} (default: @var{#f})
Whether the database configuration complex.  The complex configuration will
need a corresponding @code{<dicod-handler>} object, otherwise not.

@item @code{options}
List of strings or gexps representing the arguments for the database
(@pxref{Databases,,, dico, GNU Dico Manual}).
@end table
@end deftp

@defvar %dicod-database:gcide
A @code{<dicod-database>} object serving the GNU Collaborative International
Dictionary of English using the @code{gcide} package.
@end defvar

@deffn {Procedure} dicod-freedict-database dictionary-name
Returns a record of type @code{dicod-database} for purpose of configuring a
database for the FreeDict multilingual dictionary named by
@var{dictionary-name}, a string such as @code{"kur-eng"} for the
Kurdish-to-English dictionary, into a service of type
@code{dicod-service-type}.
@end deffn

@defvar %dicod-databases:freedict
A relatively large list of records of type @code{dicod-database}, made
available for users who wish to configure all the FreeDict multilingual
dictionaries provided by the @code{freedict-dictionaries} package into a
service of type @code{dicod-service-type}.
@end defvar

The following is an example @code{dicod-service-type} configuration,
extending a @command{dicod} daemon serving databases for the wordnet and
gcide dictionaries, as well as a selection of FreeDict multilingual
dictionaries.

@lisp
(service dicod-service-type
         (dicod-configuration
          (handlers (list
                     (dicod-handler
                      (name "wordnet")
                      (module "wordnet")
                      (options
                       (list #~(string-append "wnhome=" #$wordnet))))))
          (databases (cons*
                      (dicod-database
                       (name "wordnet")
                       (complex? #t)
                       (handler "wordnet"))
                      %dicod-database:gcide
                      (map
                       dicod-freedict-database
                       '("fra-eng" "eng-fra" "eng-spa" "spa-eng"))))))
@end lisp

@cindex Docker
@subsubheading Docker Service

The @code{(gnu services docker)} module provides the following services.

@cindex containerd, container runtime
@defvar containerd-service-type

This service type operates containerd
@url{https://containerd.io,containerd}, a daemon responsible for overseeing
the entire container lifecycle on its host system. This includes image
handling, storage management, container execution, supervision, low-level
storage operations, network connections, and more.

@end defvar

@deftp {Tipo de dados} containerd-configuration
This is the data type representing the configuration of containerd.

@table @asis

@item @code{containerd} (default: @code{containerd})
The containerd daemon package to use.

@item @code{debug?} (default @code{#f})
Enable or disable debug output.

@item @code{environment-variables} (default: @code{'()})
List of environment variables to set for @command{containerd}.

This must be a list of strings where each string has the form
@samp{@var{key}=@var{value}} as in this example:

@lisp
(list "HTTP_PROXY=socks5://127.0.0.1:9150"
      "HTTPS_PROXY=socks5://127.0.0.1:9150")
@end lisp

@end table
@end deftp

@defvar docker-service-type

This is the type of the service that runs
@url{https://www.docker.com,Docker}, a daemon that can execute application
bundles (sometimes referred to as ``containers'') in isolated environments.

The @code{containerd-service-type} service need to be added to a system
configuration, otherwise a message about not any service provides
@code{containerd} will be displayed during @code{guix system reconfigure}.

@end defvar

@deftp {Tipo de dados} docker-configuration
This is the data type representing the configuration of Docker and
Containerd.

@table @asis

@item @code{docker} (default: @code{docker})
The Docker daemon package to use.

@item @code{docker-cli} (default: @code{docker-cli})
The Docker client package to use.

@item @code{containerd} (default: @var{containerd})
This field is deprecated in favor of @code{containerd-service-type} service.

@item @code{proxy} (default @var{docker-libnetwork-cmd-proxy})
The Docker user-land networking proxy package to use.

@item @code{enable-proxy?} (default @code{#t})
Enable or disable the use of the Docker user-land networking proxy.

@item @code{debug?} (default @code{#f})
Enable or disable debug output.

@item @code{enable-iptables?} (default @code{#t})
Enable or disable the addition of iptables rules.

@item @code{environment-variables} (default: @code{'()})
List of environment variables to set for @command{dockerd}.

This must be a list of strings where each string has the form
@samp{@var{key}=@var{value}} as in this example:

@lisp
(list "LANGUAGE=eo:ca:eu"
      "TMPDIR=/tmp/dockerd")
@end lisp

@item @code{config-file} (type: maybe-file-like)
JSON configuration file pass to @command{dockerd}.

@end table
@end deftp

@cindex Singularity, container service
@defvar singularity-service-type
This is the type of the service that allows you to run
@url{https://www.sylabs.io/singularity/, Singularity}, a Docker-style tool
to create and run application bundles (aka. ``containers'').  The value for
this service is the Singularity package to use.

The service does not install a daemon; instead, it installs helper programs
as setuid-root (@pxref{Privileged Programs}) such that unprivileged users
can invoke @command{singularity run} and similar commands.
@end defvar

@cindex Rootless Podman
@subsubheading Rootless Podman Service

@cindex rootless podman, container management tool
@cindex podman, rootless
@cindex container management, podman
The @code{(gnu services containers)} module provides the following service.


@defvar rootless-podman-service-type
This is the service type for @url{https://podman.io, Podman} is a container
management tool.

In addition to providing a drop-in replacement for Docker, Podman offers the
ability to run containers in ``root-less'' mode, meaning that regular users
can deploy containers without elevated privileges.  It does so mainly by
leveraging two Linux kernel features: unprivileged user namespaces, and
subordinate user and group IDs (@pxref{subordinate-user-group-ids, the
subordinate user and group ID service}).

The @code{rootless-podman-service-type} sets up the system to allow
unprivileged users to run @command{podman} commands:

@lisp
(use-service-modules containers dbus desktop networking @dots{})
(use-modules (gnu system accounts))  ;for 'subid-range'

(operating-system
  ;; @dots{}
  (users (cons (user-account
                (name "alice")
                (comment "Bob's sister")
                (group "users")

                ;; Adding the account to the "cgroup" group
                ;; makes it possible to run podman commands.
                (supplementary-groups '("cgroup" "wheel"
                                        "audio" "video")))
               %base-user-accounts))
  (services
    (cons* (service dbus-root-service-type)
           (service dhcpcd-service-type)
           (service elogind-service-type)
           (service iptables-service-type)
           (service rootless-podman-service-type
                    (rootless-podman-configuration
                      (subgids
                       (list (subid-range (name "alice"))))
                      (subuids
                       (list (subid-range (name "alice"))))))
           %base-services)))
@end lisp

The @code{iptables-service-type} is required for Podman to be able to setup
its own networks.  Due to the change in user groups and file systems it is
recommended to reboot (or at least logout), before trying to run Podman
commands.

To test your installation you can run:

@example
$ podman run -it --rm docker.io/alpine cat /etc/*release*
NAME="Alpine Linux"
ID=alpine
VERSION_ID=3.20.2
PRETTY_NAME="Alpine Linux v3.20"
HOME_URL="https://alpinelinux.org/"
BUG_REPORT_URL="https://gitlab.alpinelinux.org/alpine/aports/-/issues"
@end example

@end defvar

@c %start of fragment

@deftp {Data Type} rootless-podman-configuration
Available @code{rootless-podman-configuration} fields are:

@table @asis
@item @code{podman} (default: @code{podman}) (type: package-or-#f)
The Podman package that will be installed in the system profile.  Pass
@code{#f} to not install Podman.

@item @code{group-name} (default: @code{"cgroup"}) (type: string)
The name of the group that will own /sys/fs/cgroup resources.  Users that
want to use rootless Podman have to be in this group.

@item @code{containers-registries} (type: lowerable)
A string or a gexp evaluating to the path of Podman's
@code{containers/registries.conf} configuration file.

@item @code{containers-storage} (type: lowerable)
A string or a gexp evaluating to the path of Podman's
@code{containers/storage.conf} configuration file.

@item @code{containers-policy} (type: lowerable)
A string or a gexp evaluating to the path of Podman's
@code{containers/policy.json} configuration file.

@item @code{pam-limits} (type: list-of-pam-limits-entries)
The PAM limits to be set for rootless Podman.

@item @code{subgids} (default: @code{()}) (type: list-of-subid-ranges)
A list of subid ranges representing the subgids that will be available for
each configured user.

@item @code{subuids} (default: @code{()}) (type: list-of-subid-ranges)
A list of subid ranges representing the subuids that will be available for
each configured user.

@end table

@end deftp


@c %end of fragment

@cindex OCI-backed, Shepherd services
@subsubheading OCI backed services

Should you wish to manage your @acronym{Open Container Initiative, OCI}
containers with the same consistent interface you use for your other
Shepherd services, @var{oci-service-type} is the tool to use: given an OCI
container image, it will run it in a Shepherd service.  One example where
this is useful: it lets you run services that are available as OCI images
but not yet packaged for Guix.

@defvar oci-service-type

This is a thin wrapper around Docker's or Podman's CLI that executes OCI
images backed processes as Shepherd Services.

@lisp
(simple-service 'oci-provisioning
                oci-service-type
                (oci-extension
                  (networks
                    (list
                      (oci-network-configuration (name "monitoring"))))
                  (containers
                   (list
                    (oci-container-configuration
                     (network "monitoring")
                     (image
                      (oci-image
                        (repository "guile")
                        (tag "3")
                        (value (specifications->manifest '("guile")))
                        (pack-options '(#:symlinks (("/bin/guile" -> "bin/guile"))
                                        #:max-layers 2))))
                     (entrypoint "/bin/guile")
                     (command
                      '("-c" "(display \"hello!\n\")")))
                    (oci-container-configuration
                      (image "prom/prometheus")
                      (network "host")
                      (ports
                       '(("9000" . "9000")
                         ("9090" . "9090"))))
                    (oci-container-configuration
                      (image "grafana/grafana:10.0.1")
                      (network "host")
                      (volumes
                       '("/var/lib/grafana:/var/lib/grafana")))))))
@end lisp

In this example three different Shepherd services are going to be added to
the system.  Each @code{oci-container-configuration} record translates to a
@samp{docker run} or @samp{podman run} invocation and its fields directly
map to options.  You can refer to the
@url{https://docs.docker.com/engine/reference/commandline/run,Docker} or
@url{https://docs.podman.io/en/stable/markdown/podman-run.1.html,Podman}
upstream documentation for semantics of each value.  If the images are not
found, they will be pulled.  You can refer to the
@url{https://docs.docker.com/engine/reference/commandline/pull/,Docker} or
@url{https://docs.podman.io/en/stable/markdown/podman-pull.1.html,Podman}
upstream documentation for semantics.  The services with @code{(network
"host")} are going to be attached to the host network and are supposed to
behave like native processes with regard to networking.

@end defvar

@c %start of fragment

@deftp {Data Type} oci-configuration
Available @code{oci-configuration} fields are:

@table @asis
@item @code{runtime} (default: @code{'docker}) (type: symbol)
The OCI runtime to use to run commands.  It can be either @code{'docker} or
@code{'podman}.

@item @code{runtime-cli} (type: maybe-package-or-string)
The OCI runtime command line to be installed in the system profile and used
to provision OCI resources, it can be either a package or a string
representing an absolute file name to the runtime binary entrypoint.  When
unset it will default to @code{docker-cli} package for the @code{'docker}
runtime or to @code{podman} package for the @code{'podman} runtime.

@item @code{runtime-extra-arguments} (default: @code{'()}) (type: list)
A list of strings, gexps or file-like objects that will be placed after each
@command{docker} or @command{podman} invokation.

@item @code{user} (type: maybe-string)
The user name under whose authority OCI commands will be run.  This field
will override the @code{user} field of @code{oci-configuration}.

@item @code{group} (type: maybe-string)
The group name under whose authority OCI commands will be run.  When using
the @code{'podman} OCI runtime, this field will be ignored and the default
group of the user configured in the @code{user} field will be used.  This
field will override the @code{group} field of @code{oci-configuration}.

@item @code{subuids-range} (type: maybe-subid-range)
An optional @code{subid-range} record allocating subuids for the user from
the @code{user} field.  When unset, with the rootless Podman OCI runtime, it
defaults to @code{(subid-range (name "oci-container"))}.

@item @code{subgids-range} (type: maybe-subid-range)
An optional @code{subid-range} record allocating subgids for the user from
the @code{user} field.  When unset, with the rootless Podman OCI runtime, it
defaults to @code{(subid-range (name "oci-container"))}.

@item @code{containers} (default: @code{'()}) (type: list-of-oci-containers)
The list of @code{oci-container-configuration} records representing the
containers to provision.  The use of the @code{oci-extension} record should
be preferred for most cases.

@item @code{networks} (default: @code{'()}) (type: list-of-oci-networks)
The list of @code{oci-network-configuration} records representing the
containers to provision.  The use of the @code{oci-extension} record should
be preferred for most cases.

@item @code{volumes} (default: @code{'()}) (type: list-of-oci-volumes)
The list of @code{oci-volumes-configuration} records representing the
containers to provision.  The use of the @code{oci-extension} record should
be preferred for most cases.

@item @code{verbose?} (default: @code{#f}) (type: boolean)
When true, additional output will be printed, allowing to better follow the
flow of execution.

@end table

@end deftp


@c %end of fragment

@c %start of fragment

@deftp {Data Type} oci-extension
Available @code{oci-extension} fields are:

@table @asis
@item @code{containers} (default: @code{'()}) (type: list-of-oci-containers)
The list of @code{oci-container-configuration} records representing the
containers to provision.

@item @code{networks} (default: @code{'()}) (type: list-of-oci-networks)
The list of @code{oci-network-configuration} records representing the
containers to provision.

@item @code{volumes} (default: @code{'()}) (type: list-of-oci-volumes)
The list of @code{oci-volumes-configuration} records representing the
containers to provision.

@end table

@end deftp


@c %end of fragment


@c %start of fragment

@deftp {Tipo de dados} oci-container-configuration
Available @code{oci-container-configuration} fields are:

@table @asis
@item @code{user} (default: @code{"oci-container"}) (type: string)
The user under whose authority docker commands will be run.

@item @code{group} (default: @code{"docker"}) (type: string)
The group under whose authority docker commands will be run.

@item @code{command} (default: @code{'()}) (type: list-of-strings)
Overwrite the default command (@code{CMD}) of the image.

@item @code{entrypoint} (default: @code{""}) (type: string)
Overwrite the default entrypoint (@code{ENTRYPOINT}) of the image.

@item @code{host-environment} (default: @code{'()}) (type: list)
Set environment variables in the host environment where @samp{docker run} or
@samp{podman run} are invoked.  This is especially useful to pass secrets
from the host to the container without having them on the OCI runtime
command line, for example: by setting the @code{MYSQL_PASSWORD} on the host
and by passing @code{--env MYSQL_PASSWORD} through the
@code{extra-arguments} field, it is possible to securely set values in the
container environment.  This field's value can be a list of pairs or
strings, even mixed:

@lisp
(list '("LANGUAGE" . "eo:ca:eu")
      "JAVA_HOME=/opt/java")
@end lisp

Pair members can be strings, gexps or file-like objects. Strings are passed
directly to @code{make-forkexec-constructor}.

@item @code{environment} (default: @code{'()}) (type: list)
Set environment variables inside the container.  This can be a list of pairs
or strings, even mixed:

@lisp
(list '("LANGUAGE" . "eo:ca:eu")
      "JAVA_HOME=/opt/java")
@end lisp

Pair members can be strings, gexps or file-like objects. Strings are passed
directly to the OCI runtime CLI.  You can refer to the
@url{https://docs.docker.com/engine/reference/commandline/run/#env,Docker}
or
@url{https://docs.podman.io/en/stable/markdown/podman-run.1.html#env-e-env,Podman}
upstream documentation for semantics.

@item @code{image} (type: string-or-oci-image)
The image used to build the container.  It can be a string or an
@code{oci-image} record.  Strings are resolved by the OCI runtime, and
follow the usual format @code{myregistry.local:5000/testing/test-image:tag}.

@item @code{provision} (default: @code{""}) (type: string)
Set the name of the provisioned Shepherd service.

@item @code{requirement} (default: @code{'()}) (type: list-of-symbols)
Set additional Shepherd services dependencies to the provisioned Shepherd
service.

@item @code{log-file} (type: maybe-string)
When @code{log-file} is set, it names the file to which the service's
standard output and standard error are redirected.  @code{log-file} is
created if it does not exist, otherwise it is appended to.

@item @code{auto-start?} (default: @code{#t}) (type: boolean)
Whether this service should be started automatically by the Shepherd.  If it
is @code{#f}, the service has to be started manually with @command{herd
start}.

@item @code{respawn?} (default: @code{#f}) (type: boolean)
Whether to have Shepherd restart the service when it stops, for instance
when the underlying process dies.

@item @code{shepherd-actions} (default: @code{'()}) (type: list-of-shepherd-actions)
This is a list of @code{shepherd-action} records defining actions supported
by the service.

@item @code{network} (default: @code{""}) (type: string)
Set an OCI network for the spawned container.

@item @code{ports} (default: @code{'()}) (type: list)
Set the port or port ranges to expose from the spawned container.  This can
be a list of pairs or strings, even mixed:

@lisp
(list '("8080" . "80")
      "10443:443")
@end lisp

Pair members can be strings, gexps or file-like objects. Strings are passed
directly to the OCI runtime CLI.  You can refer to the
@url{https://docs.docker.com/engine/reference/commandline/run/#publish,Docker}
or
@url{https://docs.podman.io/en/stable/markdown/podman-run.1.html#publish-p-ip-hostport-containerport-protocol,Podman}
upstream documentation for semantics.

@item @code{volumes} (default: @code{'()}) (type: list)
Set volume mappings for the spawned container.  This can be a list of pairs
or strings, even mixed:

@lisp
(list '("/root/data/grafana" . "/var/lib/grafana")
      "/gnu/store:/gnu/store")
@end lisp

Pair members can be strings, gexps or file-like objects. Strings are passed
directly to the OCI runtime CLI.  You can refer to the
@url{https://docs.docker.com/engine/reference/commandline/run/#volume,Docker}
or
@url{https://docs.podman.io/en/stable/markdown/podman-run.1.html#volume-v-source-volume-host-dir-container-dir-options,Podman}
upstream documentation for semantics.

@item @code{container-user} (default: @code{""}) (type: string)
Set the current user inside the spawned container.  You can refer to the
@url{https://docs.docker.com/engine/reference/run/#user,Docker} or
@url{https://docs.podman.io/en/stable/markdown/podman-run.1.html#user-u-user-group,Podman}
upstream documentation for semantics.

@item @code{workdir} (default: @code{""}) (type: string)
Set the current working directory for the spawned Shepherd service.  You can
refer to the
@url{https://docs.docker.com/engine/reference/run/#workdir,Docker} or
@url{https://docs.podman.io/en/stable/markdown/podman-run.1.html#workdir-w-dir,Podman}
upstream documentation for semantics.

@item @code{extra-arguments} (default: @code{'()}) (type: list)
A list of strings, gexps or file-like objects that will be directly passed
to the @samp{docker run} or @samp{podman run} invokation.

@end table

@end deftp


@c %end of fragment

@c %start of fragment

@deftp {Data Type} oci-network-configuration
Available @code{oci-network-configuration} fields are:

@table @asis
@item @code{name} (type: string)
The name of the OCI network to provision.

@item @code{driver} (type: maybe-string)
The driver to manage the network.

@item @code{gateway} (type: maybe-string)
IPv4 or IPv6 gateway for the subnet.

@item @code{internal?} (default: @code{#f}) (type: boolean)
Restrict external access to the network

@item @code{ip-range} (type: maybe-string)
Allocate container ip from a sub-range in CIDR format.

@item @code{ipam-driver} (type: maybe-string)
IP Address Management Driver.

@item @code{ipv6?} (default: @code{#f}) (type: boolean)
Enable IPv6 networking.

@item @code{subnet} (type: maybe-string)
Subnet in CIDR format that represents a network segment.

@item @code{labels} (default: @code{'()}) (type: list)
The list of labels that will be used to tag the current volume.

@item @code{extra-arguments} (default: @code{'()}) (type: list)
A list of strings, gexps or file-like objects that will be directly passed
to the @samp{docker network create} or @samp{podman network create}
invokation.

@end table

@end deftp


@c %end of fragment

@c %start of fragment

@deftp {Data Type} oci-volume-configuration
Available @code{oci-volume-configuration} fields are:

@table @asis
@item @code{name} (type: string)
The name of the OCI volume to provision.

@item @code{labels} (default: @code{'()}) (type: list)
The list of labels that will be used to tag the current volume.

@item @code{extra-arguments} (default: @code{'()}) (type: list)
A list of strings, gexps or file-like objects that will be directly passed
to the @samp{docker volume create} or @samp{podman volume create}
invokation.

@end table

@end deftp


@c %end of fragment

@c %start of fragment

@deftp {Tipo de dados} oci-image
Available @code{oci-image} fields are:

@table @asis
@item @code{repository} (type: string)
A string like @code{myregistry.local:5000/testing/test-image} that names the
OCI image.

@item @code{tag} (default: @code{"latest"}) (type: string)
A string representing the OCI image tag.  Defaults to @code{latest}.

@item @code{value} (type: oci-lowerable-image)
A @code{manifest} or @code{operating-system} record that will be lowered
into an OCI compatible tarball.  Otherwise this field's value can be a
file-like object that evaluates to an OCI compatible tarball.

@item @code{pack-options} (default: @code{'()}) (type: list)
An optional set of keyword arguments that will be passed to the
@code{docker-image} procedure from @code{guix scripts pack}.  They can be
used to replicate @command{guix pack} behavior:

@lisp
(oci-image
  (repository "guile")
  (tag "3")
  (value
    (specifications->manifest '("guile")))
  (pack-options '(#:symlinks (("/bin/guile" -> "bin/guile"))
                  #:max-layers 2)))
@end lisp

If the @code{value} field is an @code{operating-system} record, this field's
value will be ignored.

@item @code{system} (default: @code{""}) (type: string)
Attempt to build for a given system, e.g.@: "i686-linux"

@item @code{target} (default: @code{""}) (type: string)
Attempt to cross-build for a given triple, e.g.@: "aarch64-linux-gnu"

@item @code{grafts?} (default: @code{#f}) (type: boolean)
Whether to allow grafting or not in the pack build.

@end table

@end deftp


@c %end of fragment

@anchor{subordinate-user-group-ids}
@cindex subordinate user and group IDs
@cindex subid, subordinate user and group IDs
@subsubheading Subordinate User and Group ID Service

Among the virtualization facilities implemented by the Linux kernel is the
concept of @dfn{subordinate IDs}.  Subordinate IDs allow for mapping user
and group IDs inside process namespaces to user and group IDs of the host
system.  Subordinate user ID ranges (subuids) allow users to map virtual
user IDs inside containers to the user ID of an unprivileged user of the
host system.  Subordinate group ID ranges (subgids), instead map virtual
group IDs to the group ID of an unprivileged user on the host system.  You
can access @code{subuid(5)} and @code{subgid(5)} Linux man pages for more
details.

The @code{(gnu system shadow)} module exposes the
@code{subids-service-type}, its configuration record
@code{subids-configuration} and its extension record
@code{subids-extension}.

With @code{subids-service-type}, subuids and subgids ranges can be reserved
for users that desire so:

@lisp
(use-modules (gnu system shadow)     ;for 'subids-service-type'
             (gnu system accounts)   ;for 'subid-range'
             @dots{})

(operating-system
  ;; @dots{}
  (services
    (list
      (simple-service 'alice-bob-subids
                      subids-service-type
                      (subids-extension
                        (subgids
                         (list
                          (subid-range (name "alice"))))
                        (subuids
                         (list
                          (subid-range (name "alice"))
                          (subid-range (name "bob")
                                       (start 100700)))))))))
@end lisp

Users (definitely other services), usually, are supposed to extend the
service instead of adding subids directly to @code{subids-configuration},
unless the want to change the default behavior for root.  With default
settings the @code{subids-service-type} adds, if it's not already there, a
configuration for the root account to both @file{/etc/subuid} and
@file{/etc/subgid}, possibly starting at the minimum possible subid.
Otherwise the root subuids and subgids ranges are fitted wherever possible.

The above configuration will yield the following:

@example
# cat /etc/subgid
root:100000:65536
alice:165536:65536
# cat /etc/subuid
root:100000:700
bob:100700:65536
alice:166236:65536
@end example

@c %start of fragment

@deftp {Data Type} subids-configuration

With default settings the @code{subids-service-type} adds, if it's not
already there, a configuration for the root account to both
@file{/etc/subuid} and @file{/etc/subgid}, possibly starting at the minimum
possible subid.  To disable the default behavior and provide your own
definition for the root subid ranges you can set to @code{#f} the
@code{add-root?} field:

@lisp
(use-modules (gnu system shadow)     ;for 'subids-service-type'
             (gnu system accounts)   ;for 'subid-range'
             @dots{})

(operating-system
  ;; @dots{}
  (services
    (list
      (service subids-service-type
               (subids-configuration
                (add-root? #f)
                (subgids
                  (subid-range (name "root")
                               (start 120000)
                               (count 100)))
                (subuids
                  (subid-range (name "root")
                               (start 120000)
                               (count 100)))))
      (simple-service 'alice-bob-subids
                      subids-service-type
                      (subids-extension
                        (subgids
                         (list
                          (subid-range (name "alice"))))
                        (subuids
                         (list
                          (subid-range (name "alice"))
                          (subid-range (name "bob")
                                       (start 100700)))))))))
@end lisp

Available @code{subids-configuration} fields are:

@table @asis
@item @code{add-root?} (default: @code{#t}) (type: boolean)
Whether to automatically configure subuids and subgids for root.

@item @code{subgids} (default: @code{'()}) (type: list-of-subid-ranges)
The list of @code{subid-range}s that will be serialized to
@code{/etc/subgid}.  If a range doesn't specify a start it will be fitted
based on its number of requested subids.  If a range doesn't specify a count
the default size of 65536 will be assumed.

@item @code{subuids} (default: @code{'()}) (type: list-of-subid-ranges)
The list of @code{subid-range}s that will be serialized to
@code{/etc/subuid}.  If a range doesn't specify a start it will be fitted
based on its number of requested subids.  If a range doesn't specify a count
the default size of 65536 will be assumed.

@end table

@end deftp

@c %end of fragment

@c %start of fragment

@deftp {Data Type} subids-extension

Available @code{subids-extension} fields are:

@table @asis

@item @code{subgids} (default: @code{'()}) (type: list-of-subid-ranges)
The list of @code{subid-range}s that will be appended to
@code{subids-configuration-subgids}.  Entries with the same name are
deduplicated upon merging.

@item @code{subuids} (default: @code{'()}) (type: list-of-subid-ranges)
The list of @code{subid-range}s that will be appended to
@code{subids-configuration-subuids}.  Entries with the same name are
deduplicated upon merging.

@end table

@end deftp

@c %end of fragment

@c %start of fragment

@deftp {Data Type} subid-range

The @code{subid-range} record is defined at @code{(gnu system accounts)}.
Available fields are:

@table @asis

@item @code{name} (type: string)
The name of the user or group that will own this range.

@item @code{start} (default: @code{#f}) (type: integer)
The first requested subid.  When false the first available subid with enough
contiguous subids will be assigned.

@item @code{count} (default: @code{#f}) (type: integer)
The number of total allocated subids.  When #f the default of 65536 will be
assumed .

@end table

@end deftp

@c %end of fragment

@cindex Audit
@subsubheading Auditd Service

The @code{(gnu services auditd)} module provides the following service.

@defvar auditd-service-type

This is the type of the service that runs
@url{https://people.redhat.com/sgrubb/audit/,auditd}, a daemon that tracks
security-relevant information on your system.

Examples of things that can be tracked:

@enumerate
@item
File accesses
@item
System calls
@item
Invoked commands
@item
Failed login attempts
@item
Firewall filtering
@item
Network access
@end enumerate

@command{auditctl} do pacote @code{audit} pode ser usado para adicionar ou
remover eventos a serem rastreaddos (até o próximo reinício). A fim de
rastrear permanentemente eventos, ponha os argumentos de linha de comando do
auditctl num arquivo chamado @code{audit.rules} no diretório de
configurações (veja abaixo). @command{aureport} do pacote @code{audit} pode
ser usado para visualizar um relatório de todos os eventos gravados. O
daemon audit por padrão, produz logs no arquivo @file{/var/log/audit.log}.

@end defvar

@deftp {Tipo de dados} auditd-configuration
This is the data type representing the configuration of auditd.

@table @asis

@item @code{audit} (default: @code{audit})
The audit package to use.

@item @code{configuration-directory} (default: @code{%default-auditd-configuration-directory})
The directory containing the configuration file for the audit package, which
must be named @code{auditd.conf}, and optionally some audit rules to
instantiate on startup.

@end table
@end deftp

@cindex rshiny
@subsubheading R-Shiny service

The @code{(gnu services science)} module provides the following service.

@defvar rshiny-service-type

This is a type of service which is used to run a webapp created with
@code{r-shiny}.  This service sets the @env{R_LIBS_USER} environment
variable and runs the provided script to call @code{runApp}.

@deftp {Tipo de dados} rshiny-configuration
This is the data type representing the configuration of rshiny.

@table @asis

@item @code{package} (default: @code{r-shiny})
The package to use.

@item @code{binary} (default @code{"rshiny"})
The name of the binary or shell script located at @code{package/bin/} to run
when the service is run.

The common way to create this file is as follows:

@lisp
@dots{}
(let* ((out       (assoc-ref %outputs "out"))
       (targetdir (string-append out "/share/" ,name))
       (app       (string-append out "/bin/" ,name))
       (Rbin      (search-input-file %build-inputs "/bin/Rscript")))
  ;; @dots{}
  (mkdir-p (string-append out "/bin"))
  (call-with-output-file app
    (lambda (port)
      (format port
"#!~a
library(shiny)
setwd(\"~a\")
runApp(launch.browser=0, port=4202)~%\n"
      Rbin targetdir))))
@end lisp

@end table
@end deftp
@end defvar

@cindex Nix
@subsubheading Nix service

The @code{(gnu services nix)} module provides the following service.

@defvar nix-service-type

This is the type of the service that runs build daemon of the
@url{https://nixos.org/nix/, Nix} package manager.  Here is an example
showing how to use it:

@lisp
(use-modules (gnu))
(use-service-modules nix)
(use-package-modules package-management)

(operating-system
  ;; @dots{}
  (packages (append (list nix)
                    %base-packages))

  (services (append (list (service nix-service-type))
                    %base-services)))
@end lisp

After @command{guix system reconfigure} configure Nix for your user:

@itemize
@item Add a Nix channel and update it.  See
@url{https://wiki.nixos.org/wiki/Nix_channels, Nix channels} for more
information about the available channels.  If you would like to use the
unstable Nix channel you can do this by running:

@example
$ nix-channel --add https://nixos.org/channels/nixpkgs-unstable
$ nix-channel --update
@end example

@item Create your Nix profile directory:

@example
$ sudo mkdir -p /nix/var/nix/profiles/per-user/$USER
$ sudo chown $USER:root /nix/var/nix/profiles/per-user/$USER
@end example

@item Create a symlink to your profile and activate Nix profile:

@example
$ ln -s "/nix/var/nix/profiles/per-user/$USER/profile" ~/.nix-profile
$ source /run/current-system/profile/etc/profile.d/nix.sh
@end example

@end itemize

@end defvar

@deftp {Tipo de dados} nix-configuration
This data type represents the configuration of the Nix daemon.

@table @asis
@item @code{nix} (default: @code{nix})
The Nix package to use.

@item @code{sandbox} (default: @code{#t})
Specifies whether builds are sandboxed by default.

@item @code{build-directory} (default: @code{"/tmp"})
The directory where build directory are stored during builds.  This is
useful to change if, for example, the default location does not have enough
space to hold build trees for big packages.

This is similar to setting the @env{TMPDIR} environment variable for
@command{guix-daemon}.  @ref{Configuração do ambiente de compilação, @env{TMPDIR}}, for
more info.

@item @code{build-sandbox-items} (default: @code{'()})
This is a list of strings or objects appended to the
@code{build-sandbox-items} field of the configuration file.

@item @code{extra-config} (default: @code{'()})
This is a list of strings or objects appended to the configuration file.  It
is used to pass extra text to be added verbatim to the configuration file.

@item @code{extra-options} (default: @code{'()})
Extra command line options for @code{nix-service-type}.
@end table
@end deftp

@cindex Fail2Ban
@subsubheading Fail2Ban service

@uref{http://www.fail2ban.org/, @code{fail2ban}} scans log files
(e.g. @code{/var/log/apache/error_log}) and bans IP addresses that show
malicious signs -- repeated password failures, attempts to make use of
exploits, etc.

@code{fail2ban-service-type} service type is provided by the @code{(gnu
services security)} module.

This service type runs the @code{fail2ban} daemon.  It can be configured in
various ways, which are:

@table @asis
@item Basic configuration
The basic parameters of the Fail2Ban service can be configured via its
@code{fail2ban} configuration, which is documented below.

@item User-specified jail extensions
The @code{fail2ban-jail-service} function can be used to add new Fail2Ban
jails.

@item Shepherd extension mechanism
Service developers can extend the @code{fail2ban-service-type} service type
itself via the usual service extension mechanism.
@end table

@defvar fail2ban-service-type

This is the type of the service that runs @code{fail2ban} daemon.  Below is
an example of a basic, explicit configuration:

@lisp
(append
 (list
  (service fail2ban-service-type
           (fail2ban-configuration
            (extra-jails
             (list
              (fail2ban-jail-configuration
               (name "sshd")
               (enabled? #t))))))
  ;; There is no implicit dependency on an actual SSH
  ;; service, so you need to provide one.
  (service openssh-service-type))
 %base-services)
@end lisp
@end defvar

@deffn {Procedure} fail2ban-jail-service svc-type jail
Extend @var{svc-type}, a @code{<service-type>} object with @var{jail}, a
@code{fail2ban-jail-configuration} object.

Por exemplo:

@lisp
(append
 (list
  (service
   ;; The 'fail2ban-jail-service' procedure can extend any service type
   ;; with a fail2ban jail.  This removes the requirement to explicitly
   ;; extend services with fail2ban-service-type.
   (fail2ban-jail-service
    openssh-service-type
    (fail2ban-jail-configuration
     (name "sshd")
     (enabled? #t)))
   (openssh-configuration ...))))
@end lisp
@end deffn

Below is the reference for the different @code{jail-service-type}
configuration records.

@c The documentation is to be auto-generated via
@c 'generate-documentation'.  See at the bottom of (gnu services
@c security).

@deftp {Tipo de dados} fail2ban-configuration
Available @code{fail2ban-configuration} fields are:

@table @asis
@item @code{fail2ban} (default: @code{fail2ban}) (type: package)
The @code{fail2ban} package to use.  It is used for both binaries and as
base default configuration that is to be extended with
@code{<fail2ban-jail-configuration>} objects.

@item @code{run-directory} (default: @code{"/var/run/fail2ban"}) (type: string)
The state directory for the @code{fail2ban} daemon.

@item @code{jails} (default: @code{'()}) (type: list-of-fail2ban-jail-configurations)
Instances of @code{<fail2ban-jail-configuration>} collected from extensions.

@item @code{extra-jails} (default: @code{'()}) (type: list-of-fail2ban-jail-configurations)
Instances of @code{<fail2ban-jail-configuration>} explicitly provided.

@item @code{extra-content} (default: @code{'()}) (type: text-config)
Extra raw content to add to the end of the @file{jail.local} file, provided
as a list of file-like objects.

@end table

@end deftp

@deftp {Tipo de dados} fail2ban-ignore-cache-configuration
Available @code{fail2ban-ignore-cache-configuration} fields are:

@table @asis
@item @code{key} (type: string)
Cache key.

@item @code{max-count} (type: integer)
Cache size.

@item @code{max-time} (type: integer)
Cache time.

@end table

@end deftp

@deftp {Tipo de dados} fail2ban-jail-action-configuration
Available @code{fail2ban-jail-action-configuration} fields are:

@table @asis
@item @code{name} (type: string)
Action name.

@item @code{arguments} (default: @code{'()}) (type: list-of-arguments)
Action arguments.

@end table

@end deftp

@deftp {Tipo de dados} fail2ban-jail-configuration
Available @code{fail2ban-jail-configuration} fields are:

@table @asis
@item @code{name} (type: string)
Required name of this jail configuration.

@item @code{enabled?} (default: @code{#t}) (type: boolean)
Whether this jail is enabled.

@item @code{backend} (type: maybe-symbol)
Backend to use to detect changes in the @code{log-path}.  The default is
'auto.  To consult the defaults of the jail configuration, refer to the
@file{/etc/fail2ban/jail.conf} file of the @code{fail2ban} package.

@item @code{max-retry} (type: maybe-integer)
The number of failures before a host gets banned (e.g.  @code{(max-retry
5)}).

@item @code{max-matches} (type: maybe-integer)
The number of matches stored in ticket (resolvable via tag @code{<matches>})
in action.

@item @code{find-time} (type: maybe-string)
The time window during which the maximum retry count must be reached for an
IP address to be banned.  A host is banned if it has generated
@code{max-retry} during the last @code{find-time} seconds (e.g.
@code{(find-time "10m")}).  It can be provided in seconds or using
Fail2Ban's "time abbreviation format", as described in @command{man 5
jail.conf}.

@item @code{ban-time} (type: maybe-string)
The duration, in seconds or time abbreviated format, that a ban should
last.  (e.g.  @code{(ban-time "10m")}).

@item @code{ban-time-increment?} (type: maybe-boolean)
Whether to consider past bans to compute increases to the default ban time
of a specific IP address.

@item @code{ban-time-factor} (type: maybe-string)
The coefficient to use to compute an exponentially growing ban time.

@item @code{ban-time-formula} (type: maybe-string)
This is the formula used to calculate the next value of a ban time.

@item @code{ban-time-multipliers} (type: maybe-string)
Used to calculate next value of ban time instead of formula.

@item @code{ban-time-max-time} (type: maybe-string)
The maximum number of seconds a ban should last.

@item @code{ban-time-rnd-time} (type: maybe-string)
The maximum number of seconds a randomized ban time should last.  This can
be useful to stop ``clever'' botnets calculating the exact time an IP
address can be unbanned again.

@item @code{ban-time-overall-jails?} (type: maybe-boolean)
When true, it specifies the search of an IP address in the database should
be made across all jails.  Otherwise, only the current jail of the ban IP
address is considered.

@item @code{ignore-self?} (type: maybe-boolean)
Never ban the local machine's own IP address.

@item @code{ignore-ip} (default: @code{'()}) (type: list-of-strings)
A list of IP addresses, CIDR masks or DNS hosts to ignore.  @code{fail2ban}
will not ban a host which matches an address in this list.

@item @code{ignore-cache} (type: maybe-fail2ban-ignore-cache-configuration)
Provide cache parameters for the ignore failure check.

@item @code{filter} (type: maybe-fail2ban-jail-filter-configuration)
The filter to use by the jail, specified via a
@code{<fail2ban-jail-filter-configuration>} object.  By default, jails have
names matching their filter name.

@item @code{log-time-zone} (type: maybe-string)
The default time zone for log lines that do not have one.

@item @code{log-encoding} (type: maybe-symbol)
The encoding of the log files handled by the jail.  Possible values are:
@code{'ascii}, @code{'utf-8} and @code{'auto}.

@item @code{log-path} (default: @code{'()}) (type: list-of-strings)
The file names of the log files to be monitored.

@item @code{action} (default: @code{'()}) (type: list-of-fail2ban-jail-actions)
A list of @code{<fail2ban-jail-action-configuration>}.

@item @code{extra-content} (default: @code{'()}) (type: text-config)
Extra content for the jail configuration, provided as a list of file-like
objects.

@end table

@end deftp

@deftp {Tipo de dados} fail2ban-jail-filter-configuration
Available @code{fail2ban-jail-filter-configuration} fields are:

@table @asis
@item @code{name} (type: string)
Filter to use.

@item @code{mode} (type: maybe-string)
Mode for filter.

@end table

@end deftp

@c End of auto-generated fail2ban documentation.

@cindex resize-file-system
@subsubheading Resize File System Service

This service type lets you resize a live file system during boot, which can
be convenient if a Guix image is flashed on an SD Card (e.g. for an embedded
device) or uploaded to a VPS.  In both cases the medium the image will
reside upon may be larger than the image you want to produce.

For an embedded device booting from an SD card you may use something like:
@lisp
(service resize-file-system-service-type
         (resize-file-system-configuration
          (file-system
           (file-system (device (file-system-label "root"))
                        (type "ext4")))))
@end lisp

@quotation Aviso
Be extra cautious to use the correct device and type.  The service has
little error handling of its own and relies on the underlying tools.  Wrong
use could end in loss of data or the corruption of the operating system.
@end quotation

Partitions and file systems are grown to the maximum size available.  File
systems can only grow when they are on the last partition on a device and
have empty space available.

This service supports the ext2, ext3, ext4, btrfs, and bcachefs file
systems.

@table @asis

@item @code{file-system} (type: file-system)
The file-system object to resize (@pxref{Sistemas de arquivos}).  This object must
have the @code{device} and @code{type} fields set.  Other fields are
ignored.

@item @code{cloud-utils} (default: @code{cloud-utils}) (type: file-like)
The cloud-utils package to use.  This package is used for the
@code{growpart} command.

@item @code{e2fsprogs} (default: @code{e2fsprogs}) (type: file-like)
The e2fsprogs package to use, used for resizing ext2, ext3, and ext4 file
systems.

@item @code{btrfs-progs} (default: @code{btrfs-progs}) (type: file-like)
The btrfs-progs package to use, used for resizing the btrfs file system.

@item @code{bcachefs-tools} (default: @code{bcachefs-tools}) (type: file-like)
The bcachefs-tools package to use, used for resizing the bcachefs file
system.

@end table

@cindex Backup
@subsubheading Backup Services

The @code{(gnu services backup)} module offers services for backing up file
system trees.  For now, it provides the @code{restic-backup-service-type}.

With @code{restic-backup-service-type}, you can periodically back up
directories and files with @uref{https://restic.net/, Restic}, which
supports end-to-end encryption and deduplication.  Consider the following
configuration:

@lisp
(use-service-modules backup @dots{}) ;for 'restic-backup-service-type'
(use-package-modules sync @dots{})   ;for 'rclone'

(operating-system
  ;; @dots{}
  (packages (append (list rclone)    ;for use by restic
                    %base-packages))
  (services
    (list
      (service restic-backup-service-type
               (restic-backup-configuration
                 (jobs
                   (list (restic-backup-job
                           (name "remote-ftp")
                           (repository "rclone:remote-ftp:backup/restic")
                           (password-file "/root/.restic")
                           ;; Every day at 23.
                           (schedule "0 23 * * *")
                           (files '("/root/.restic"
                                    "/root/.config/rclone"
                                    "/etc/ssh/ssh_host_rsa_key"
                                    "/etc/ssh/ssh_host_rsa_key.pub"
                                    "/etc/guix/signing-key.pub"
                                    "/etc/guix/signing-key.sec"))))))))))
@end lisp

Each @code{restic-backup-job} translates to a Shepherd timer which sets the
@env{RESTIC_PASSWORD} environment variable by reading the first line of
@code{password-file} and runs @command{restic backup}, creating backups
using rclone of all the files listed in the @code{files} field.

The @code{restic-backup-service-type} provides the ability to
instantaneously trigger a backup with the @code{trigger} Shepherd action:

@example
sudo herd trigger remote-ftp
@end example

@c %start of fragment

@deftp {Tipo de dados} restic-backup-configuration
Available @code{restic-backup-configuration} fields are:

@table @asis
@item @code{jobs} (default: @code{'()}) (type: list-of-restic-backup-jobs)
The list of backup jobs for the current system.

@end table

@end deftp


@c %end of fragment

@c %start of fragment

@deftp {Tipo de dados} restic-backup-job
Available @code{restic-backup-job} fields are:

@table @asis
@item @code{restic} (default: @code{restic}) (type: package)
The restic package to be used for the current job.

@item @code{user} (default: @code{"root"}) (type: string)
The user used for running the current job.

@item @code{group} (default: @code{"root"}) (type: string)
The group used for running the current job.

@item @code{log-file} (type: maybe-string)
The file system path to the log file for this job.  By default the file will
have be @file{/var/log/restic-backup/@var{job-name}.log}, where
@var{job-name} is the name defined in the @code{name} field.  For Guix Home
services it defaults to
@file{$XDG_STATE_HOME/shepherd/restic-backup/@var{job-name}.log}.

@item @code{max-duration} (type: maybe-number)
The maximum duration in seconds that a job may last.  Past
@code{max-duration} seconds, the job is forcefully terminated.

@item @code{wait-for-termination?} (default: @code{#f}) (type: boolean)
Wait until the job has finished before considering executing it again;
otherwise, perform it strictly on every occurrence of event, at the risk of
having multiple instances running concurrently.

@item @code{repository} (type: string)
The restic repository target of this job.

@item @code{name} (type: string)
A string denoting a name for this job.

@item @code{password-file} (type: string)
Name of the password file, readable by the configured @code{user}, that will
be used to set the @env{RESTIC_PASSWORD} environment variable for the
current job.

@item @code{schedule} (type: gexp-or-string)
A string or a gexp representing the frequency of the backup.  Gexp must
evaluate to @code{calendar-event} records or to strings.  Strings must
contain Vixie cron date lines.

@item @code{requirement} (type: maybe-list-of-symbols)
The list of Shepherd services that this backup job depends upon.  When unset
it defaults to @code{'()}, for Guix Home.  Otherwise to
@code{'(user-processes file-systems)}.

@item @code{files} (default: @code{'()}) (type: list-of-lowerables)
The list of files or directories to be backed up.  It must be a list of
values that can be lowered to strings.

@item @code{verbose?} (default: @code{#f}) (type: boolean)
Whether to enable verbose output for the current backup job.

@item @code{extra-flags} (default: @code{'()}) (type: list-of-lowerables)
A list of values that are lowered to strings.  These will be passed as
command-line arguments to the current job @command{restic backup}
invocation.

@end table

@end deftp

@c %end of fragment

@cindex DLNA/UPnP
@subsubheading DLNA/UPnP Services

The @code{(gnu services upnp)} module offers services related to
@acronym{UPnP, Universal Plug and Play} and @acronym{DLNA, Digital Living
Network Alliance}, networking protocols that can be used for media streaming
and device interoperability within a local network.  For now, this module
provides the @code{readymedia-service-type}.

@uref{https://minidlna.sourceforge.net/, ReadyMedia} (formerly known as
MiniDLNA) is a DLNA/UPnP-AV media server.  The project's daemon,
@code{minidlnad}, can serve media files (audio, pictures, and video) to
DLNA/UPnP-AV clients available on the network.
@code{readymedia-service-type} is a Guix service that wraps around
ReadyMedia's @code{minidlnad}.

Consider the following configuration:
@lisp
(use-service-modules upnp @dots{})

(operating-system
  @dots{}
  (services
   (list (service readymedia-service-type
                  (readymedia-configuration
                   (media-directories
                    (list (readymedia-media-directory
                           (path "/media/audio")
                           (types '(A)))
                          (readymedia-media-directory
                           (path "/media/video")
                           (types '(V)))
                          (readymedia-media-directory
                           (path "/media/misc"))))
                   (extra-config '(("notify_interval" . "60")))))
         @dots{})))
@end lisp

This sets up the ReadyMedia daemon to serve files from the media folders
specified in @code{media-directories}.  The @code{media-directories} field
is mandatory.  All other fields (such as network ports and the server name)
come with a predefined default and can be omitted.

@quotation Nota
This service is also available for Guix Home, where it runs directly with
your user privileges (@pxref{Miscellaneous Home Services,
@code{home-readymedia-service-type}}).
@end quotation

@c %start of fragment

@deftp {Tipo de dados} readymedia-configuration
Available @code{readymedia-configuration} fields are:

@table @asis
@item @code{readymedia} (default: @code{readymedia}) (type: package)
The ReadyMedia package to be used for the service.

@item @code{friendly-name} (default: @code{#f}) (type: maybe-string)
A custom name that will be displayed on connected clients.

@item @code{media-directories} (type: list)
The list of media folders to serve content from.  Each item is a
@code{readymedia-media-directory}.

@item @code{cache-directory} (default: @code{"/var/cache/readymedia"}) (type: string)
A folder for ReadyMedia's cache files.  If not existing already, the folder
will be created as part of the service activation and the ReadyMedia user
will be assigned ownership.

@item @code{log-directory} (default: @code{"/var/log/readymedia"}) (type: string)
A folder for ReadyMedia's log files.  If not existing already, the folder
will be created as part of the service activation and the ReadyMedia user
will be assigned ownership.

@item @code{port} (default: @code{#f}) (type: maybe-integer)
A custom port that the service will be listening on.

@item @code{extra-config} (default: @code{'()}) (type: alist)
An association list of further options, as accepted by ReadyMedia.
@end table

@end deftp

@c %end of fragment

@c %start of fragment

@deftp {Tipo de dados} readymedia-media-directory
A @code{media-directories} entry includes a folder @code{path} and,
optionally, the @code{types} of media files included within the folder.

@table @asis
@item @code{path} (type: string)
The media folder location.

@item @code{types} (default: @code{'()}) (type: list)
A list indicating the types of file included in the media folder.  Valid
values are combinations of individual media types, i.e. symbol @code{A} for
audio, @code{P} for pictures, @code{V} for video.  An empty list means that
no type is specified.
@end table

@end deftp

@c %end of fragment

@node Privileged Programs
@section Privileged Programs

@cindex privileged programs
@cindex setuid programs
@cindex setgid programs
@cindex capabilities, POSIX
@cindex setcap
Some programs need to run with elevated privileges, even when they are
launched by unprivileged users.  A notorious example is the @command{passwd}
program, which users can run to change their password, and which needs to
access the @file{/etc/passwd} and @file{/etc/shadow} files---something
normally restricted to root, for obvious security reasons.  To address that,
@command{passwd} should be @dfn{setuid-root}, meaning that it always runs
with root privileges (@pxref{How Change Persona,,, libc, The GNU C Library
Reference Manual}, for more info about the setuid mechanism).

The store itself @emph{cannot} contain privileged programs: that would be a
security issue since any user on the system can write derivations that
populate the store (@pxref{O armazém}).  Thus, a different mechanism is
used: instead of directly granting permissions to files that are in the
store, we let the system administrator @emph{declare} which programs should
be entrusted with these additional privileges.

The @code{privileged-programs} field of an @code{operating-system}
declaration contains a list of @code{<privileged-program>} denoting the
names of programs to have a setuid or setgid bit set (@pxref{Usando o sistema de configuração}).  For instance, the @command{mount.nfs} program,
which is part of the nfs-utils package, with a setuid root can be designated
like this:

@lisp
(privileged-program
  (program (file-append nfs-utils "/sbin/mount.nfs"))
  (setuid? #t))
@end lisp

And then, to make @command{mount.nfs} setuid on your system, add the
previous example to your operating system declaration by appending it to
@code{%default-privileged-programs} like this:

@lisp
(operating-system
  ;; Some fields omitted...
  (privileged-programs
    (append (list (privileged-program
                    (program (file-append nfs-utils "/sbin/mount.nfs"))
                    (setuid? #t)))
            %default-privileged-programs)))
@end lisp

@deftp {Tipo de dados} privileged-program
This data type represents a program with special privileges, such as setuid

@table @asis
@item @code{program}
A file-like object to which all given privileges should apply.

@item @code{setuid?} (default: @code{#f})
Whether to set user setuid bit.

@item @code{setgid?} (default: @code{#f})
Whether to set group setgid bit.

@item @code{user} (default: @code{0})
UID (integer) or user name (string) for the user owner of the program,
defaults to root.

@item @code{group} (default: @code{0})
GID (integer) group name (string) for the group owner of the program,
defaults to root.

@item @code{capabilities} (default: @code{#f})
A string representing the program's POSIX capabilities, as described by the
@code{cap_to_text(3)} man page from the libcap package, or @code{#f} to make
no changes.

@end table
@end deftp

A default set of privileged programs is defined by the
@code{%default-privileged-programs} variable of the @code{(gnu system)}
module.

@defvar {Scheme Variable} %default-privileged-programs
A list of @code{<privileged-program>} denoting common programs with elevated
privileges.

The list includes commands such as @command{passwd}, @command{ping},
@command{su}, and @command{sudo}.
@end defvar

Under the hood, the actual privileged programs are created in the
@file{/run/privileged/bin} directory at system activation time.  The files
in this directory refer to the ``real'' binaries, which are in the store.

@node Certificados X.509
@section Certificados X.509

@cindex HTTPS, certificates
@cindex Certificados X.509
@cindex TLS
Web servers available over HTTPS (that is, HTTP over the transport-layer
security mechanism, TLS) send client programs an @dfn{X.509 certificate}
that the client can then use to @emph{authenticate} the server.  To do that,
clients verify that the server's certificate is signed by a so-called
@dfn{certificate authority} (CA).  But to verify the CA's signature, clients
must have first acquired the CA's certificate.

Web browsers such as GNU@tie{}IceCat include their own set of CA
certificates, such that they are able to verify CA signatures
out-of-the-box.

However, most other programs that can talk HTTPS---@command{wget},
@command{git}, @command{w3m}, etc.---need to be told where CA certificates
can be found.

@cindex @code{nss-certs}
For users of Guix System, this is done by adding a package that provides
certificates to the @code{packages} field of the @code{operating-system}
declaration (@pxref{Referência do 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.

This package is part of @code{%base-packages}, so there is no need to
explicitly add it.  The @file{/etc/ssl/certs} directory, which is where most
applications and libraries look for certificates by default, points to the
certificates installed globally.

Unprivileged users, including users of Guix on a foreign distro, can also
install their own certificate package in their profile.  A number of
environment variables need to be defined so that applications and libraries
know where to find them.  Namely, the OpenSSL library honors the
@env{SSL_CERT_DIR} and @env{SSL_CERT_FILE} variables.  Some applications add
their own environment variables; for instance, the Git version control
system honors the certificate bundle pointed to by the @env{GIT_SSL_CAINFO}
environment variable.  Thus, you would typically run something like:

@example
guix install nss-certs
export SSL_CERT_DIR="$HOME/.guix-profile/etc/ssl/certs"
export SSL_CERT_FILE="$HOME/.guix-profile/etc/ssl/certs/ca-certificates.crt"
export GIT_SSL_CAINFO="$SSL_CERT_FILE"
@end example

As another example, R requires the @env{CURL_CA_BUNDLE} environment variable
to point to a certificate bundle, so you would have to run something like
this:

@example
guix install nss-certs
export CURL_CA_BUNDLE="$HOME/.guix-profile/etc/ssl/certs/ca-certificates.crt"
@end example

For other applications you may want to look up the required environment
variable in the relevant documentation.


@node Name Service Switch
@section Name Service Switch

@cindex name service switch
@cindex NSS
The @code{(gnu system nss)} module provides bindings to the configuration
file of the libc @dfn{name service switch} or @dfn{NSS} (@pxref{NSS
Configuration File,,, libc, The GNU C Library Reference Manual}).  In a
nutshell, the NSS is a mechanism that allows libc to be extended with new
``name'' lookup methods for system databases, which includes host names,
service names, user accounts, and more (@pxref{Name Service Switch, System
Databases and Name Service Switch,, libc, The GNU C Library Reference
Manual}).

The NSS configuration specifies, for each system database, which lookup
method is to be used, and how the various methods are chained together---for
instance, under which circumstances NSS should try the next method in the
list.  The NSS configuration is given in the @code{name-service-switch}
field of @code{operating-system} declarations (@pxref{Referência do operating-system, @code{name-service-switch}}).

@cindex nss-mdns
@cindex .local, host name lookup
As an example, the declaration below configures the NSS to use the
@uref{https://0pointer.de/lennart/projects/nss-mdns/, @code{nss-mdns}
back-end}, which supports host name lookups over multicast DNS (mDNS)  for
host names ending in @code{.local}:

@lisp
(name-service-switch
   (hosts (list %files    ;first, check /etc/hosts

                ;; If the above did not succeed, try
                ;; with 'mdns_minimal'.
                (name-service
                  (name "mdns_minimal")

                  ;; 'mdns_minimal' is authoritative for
                  ;; '.local'.  When it returns "not found",
                  ;; no need to try the next methods.
                  (reaction (lookup-specification
                             (not-found => return))))

                ;; Then fall back to DNS.
                (name-service
                  (name "dns"))

                ;; Finally, try with the "full" 'mdns'.
                (name-service
                  (name "mdns")))))
@end lisp

Do not worry: the @code{%mdns-host-lookup-nss} variable (see below)
contains this configuration, so you will not have to type it if all you want
is to have @code{.local} host lookup working.

Note that, in this case, in addition to setting the
@code{name-service-switch} of the @code{operating-system} declaration, you
also need to use @code{avahi-service-type} (@pxref{Serviços de Rede,
@code{avahi-service-type}}), or @code{%desktop-services}, which includes it
(@pxref{Serviços de desktop}).  Doing this makes @code{nss-mdns} accessible to
the name service cache daemon (@pxref{Serviços básicos, @code{nscd-service}}).

For convenience, the following variables provide typical NSS configurations.

@defvar %default-nss
This is the default name service switch configuration, a
@code{name-service-switch} object.
@end defvar

@defvar %mdns-host-lookup-nss
This is the name service switch configuration with support for host name
lookup over multicast DNS (mDNS) for host names ending in @code{.local}.
@end defvar

Furthermore, mDNS lookups could be restricted to IPv4 or IPv6 protocols
using the procedure @code{mdns-host-lookup-nss}.

@deffn {Procedure} mdns-host-lookup-nss @
       [#:ipv6? #t] [#:ipv4? #t] Return a @code{name-service-switch} object with
mDNS lookup restricted to specified protocols.
@end deffn

The reference for name service switch configuration is given below.  It is a
direct mapping of the configuration file format of the C library , so please
refer to the C library manual for more information (@pxref{NSS Configuration
File,,, libc, The GNU C Library Reference Manual}).  Compared to the
configuration file format of libc NSS, it has the advantage not only of
adding this warm parenthetic feel that we like, but also static checks: you
will know about syntax errors and typos as soon as you run @command{guix
system}.

@deftp {Tipo de dados} name-service-switch

This is the data type representation the configuration of libc's name
service switch (NSS).  Each field below represents one of the supported
system databases.

@table @code
@item aliases
@itemx ethers
@itemx group
@itemx gshadow
@itemx hosts
@itemx initgroups
@itemx netgroup
@itemx networks
@itemx password
@itemx public-key
@itemx rpc
@itemx services
@itemx shadow
The system databases handled by the NSS@.  Each of these fields must be a
list of @code{<name-service>} objects (see below).
@end table
@end deftp

@deftp {Tipo de dados} name-service

This is the data type representing an actual name service and the associated
lookup action.

@table @code
@item name
A string denoting the name service (@pxref{Services in the NSS
configuration,,, libc, The GNU C Library Reference Manual}).

Note that name services listed here must be visible to nscd.  This is
achieved by passing the @code{#:name-services} argument to
@code{nscd-service} the list of packages providing the needed name services
(@pxref{Serviços básicos, @code{nscd-service}}).

@item reaction
An action specified using the @code{lookup-specification} macro
(@pxref{Actions in the NSS configuration,,, libc, The GNU C Library
Reference Manual}).  For example:

@lisp
(lookup-specification (unavailable => continue)
                      (success => return))
@end lisp
@end table
@end deftp

@node Disco de RAM inicial
@section Disco de RAM inicial

@cindex initrd
@cindex initial RAM disk
For bootstrapping purposes, the Linux-Libre kernel is passed an @dfn{initial
RAM disk}, or @dfn{initrd}.  An initrd contains a temporary root file system
as well as an initialization script.  The latter is responsible for mounting
the real root file system, and for loading any kernel modules that may be
needed to achieve that.

The @code{initrd-modules} field of an @code{operating-system} declaration
allows you to specify Linux-libre kernel modules that must be available in
the initrd.  In particular, this is where you would list modules needed to
actually drive the hard disk where your root partition is---although the
default value of @code{initrd-modules} should cover most use cases.  For
example, assuming you need the @code{megaraid_sas} module in addition to the
default modules to be able to access your root file system, you would write:

@lisp
(operating-system
  ;; @dots{}
  (initrd-modules (cons "megaraid_sas" %base-initrd-modules)))
@end lisp

@defvar %base-initrd-modules
This is the list of kernel modules included in the initrd by default.
@end defvar

Furthermore, if you need lower-level customization, the @code{initrd} field
of an @code{operating-system} declaration allows you to specify which initrd
you would like to use.  The @code{(gnu system linux-initrd)} module provides
three ways to build an initrd: the high-level @code{base-initrd} procedure
and the low-level @code{raw-initrd} and @code{expression->initrd}
procedures.

The @code{base-initrd} procedure is intended to cover most common uses.  For
example, if you want to add a bunch of kernel modules to be loaded at boot
time, you can define the @code{initrd} field of the operating system
declaration like this:

@lisp
(initrd (lambda (file-systems . rest)
          ;; Create a standard initrd but set up networking
          ;; with the parameters QEMU expects by default.
          (apply base-initrd file-systems
                 #:qemu-networking? #t
                 rest)))
@end lisp

The @code{base-initrd} procedure also handles common use cases that involves
using the system as a QEMU guest, or as a ``live'' system with volatile root
file system.

The @code{base-initrd} procedure is built from @code{raw-initrd} procedure.
Unlike @code{base-initrd}, @code{raw-initrd} doesn't do anything high-level,
such as trying to guess which kernel modules and packages should be included
to the initrd.  An example use of @code{raw-initrd} is when a user has a
custom Linux kernel configuration and default kernel modules included by
@code{base-initrd} are not available.

The initial RAM disk produced by @code{base-initrd} or @code{raw-initrd}
honors several options passed on the Linux kernel command line (that is,
arguments passed @i{via} the @code{linux} command of GRUB, or the
@code{-append} option of QEMU), notably:

@table @code
@item gnu.load=@var{boot}
Tell the initial RAM disk to load @var{boot}, a file containing a Scheme
program, once it has mounted the root file system.

Guix uses this option to yield control to a boot program that runs the
service activation programs and then spawns the GNU@tie{}Shepherd, the
initialization system.

@item root=@var{root}
Mount @var{root} as the root file system.  @var{root} can be a device name
like @code{/dev/sda1}, a file system label, or a file system UUID.  When
unspecified, the device name from the root file system of the operating
system declaration is used.

@item rootfstype=@var{type}
Set the type of the root file system.  It overrides the @code{type} field of
the root file system specified via the @code{operating-system} declaration,
if any.

@item rootflags=@var{options}
Set the mount @emph{options} of the root file system.  It overrides the
@code{options} field of the root file system specified via the
@code{operating-system} declaration, if any.

@item fsck.mode=@var{mode}
Whether to check the @var{root} file system for errors before mounting it.
@var{mode} is one of @code{skip} (never check), @code{force} (always check),
or @code{auto} to respect the root @code{<file-system>} object's
@code{check?} setting (@pxref{Sistemas de arquivos}) and run a full scan only if the
file system was not cleanly shut down.

@code{auto} is the default if this option is not present or if @var{mode} is
not one of the above.

@item fsck.repair=@var{level}
The level of repairs to perform automatically if errors are found in the
@var{root} file system.  @var{level} is one of @code{no} (do not write to
@var{root} at all if possible), @code{yes} (repair as much as possible), or
@code{preen} to repair problems considered safe to repair automatically.

@code{preen} is the default if this option is not present or if @var{level}
is not one of the above.

@item gnu.system=@var{system}
Have @file{/run/booted-system} and @file{/run/current-system} point to
@var{system}.

@item modprobe.blacklist=@var{modules}@dots{}
@cindex module, black-listing
@cindex black list, of kernel modules
Instruct the initial RAM disk as well as the @command{modprobe} command
(from the kmod package) to refuse to load @var{modules}.  @var{modules} must
be a comma-separated list of module names---e.g., @code{usbkbd,9pnet}.

@item gnu.repl
Start a read-eval-print loop (REPL) from the initial RAM disk before it
tries to load kernel modules and to mount the root file system.  Our
marketing team calls it @dfn{boot-to-Guile}.  The Schemer in you will love
it.  @xref{Using Guile Interactively,,, guile, GNU Guile Reference Manual},
for more information on Guile's REPL.

@end table

Now that you know all the features that initial RAM disks produced by
@code{base-initrd} and @code{raw-initrd} provide, here is how to use it and
customize it further.

@cindex initrd
@cindex initial RAM disk
@deffn {Procedure} raw-initrd file-systems @
       [#:linux-modules '()] [#:pre-mount #t] [#:mapped-devices '()] @
[#:keyboard-layout #f] [#:helper-packages '()] @ [#:qemu-networking? #f]
[#:volatile-root? #f] Return a derivation that builds a raw initrd.
@var{file-systems} is a list of file systems to be mounted by the initrd,
possibly in addition to the root file system specified on the kernel command
line via @option{root}.  @var{linux-modules} is a list of kernel modules to
be loaded at boot time.  @var{mapped-devices} is a list of device mappings
to realize before @var{file-systems} are mounted (@pxref{Dispositivos mapeados}).
@var{pre-mount} is a G-expression to evaluate before realizing
@var{mapped-devices}.  @var{helper-packages} is a list of packages to be
copied in the initrd.  It may include @code{e2fsck/static} or other packages
needed by the initrd to check the root file system.

When true, @var{keyboard-layout} is a @code{<keyboard-layout>} record
denoting the desired console keyboard layout.  This is done before
@var{mapped-devices} are set up and before @var{file-systems} are mounted
such that, should the user need to enter a passphrase or use the REPL, this
happens using the intended keyboard layout.

When @var{qemu-networking?} is true, set up networking with the standard
QEMU parameters.

When @var{volatile-root?} is true, the root file system is writable but any
changes to it are lost.
@end deffn

@deffn {Procedure} base-initrd file-systems @
       [#:mapped-devices '()] [#:keyboard-layout #f] @ [#:qemu-networking? #f]
[#:volatile-root? #f] @ [#:linux-modules '()] Return as a file-like object a
generic initrd, with kernel modules taken from @var{linux}.
@var{file-systems} is a list of file-systems to be mounted by the initrd,
possibly in addition to the root file system specified on the kernel command
line via @option{root}.  @var{mapped-devices} is a list of device mappings
to realize before @var{file-systems} are mounted.

When true, @var{keyboard-layout} is a @code{<keyboard-layout>} record
denoting the desired console keyboard layout.  This is done before
@var{mapped-devices} are set up and before @var{file-systems} are mounted
such that, should the user need to enter a passphrase or use the REPL, this
happens using the intended keyboard layout.

@var{qemu-networking?} and @var{volatile-root?} behaves as in
@code{raw-initrd}.

The initrd is automatically populated with all the kernel modules necessary
for @var{file-systems} and for the given options.  Additional kernel modules
can be listed in @var{linux-modules}.  They will be added to the initrd, and
loaded at boot time in the order in which they appear.
@end deffn

Needless to say, the initrds we produce and use embed a statically-linked
Guile, and the initialization program is a Guile program.  That gives a lot
of flexibility.  The @code{expression->initrd} procedure builds such an
initrd, given the program to run in that initrd.

@deffn {Procedure} expression->initrd exp @
       [#:guile %guile-static-initrd] [#:name "guile-initrd"] Return as a file-like
object a Linux initrd (a gzipped cpio archive)  containing @var{guile} and
that evaluates @var{exp}, a G-expression, upon booting.  All the derivations
referenced by @var{exp} are automatically copied to the initrd.
@end deffn

@node Configuração do carregador de inicialização
@section Configuração do carregador de inicialização

@cindex bootloader
@cindex boot loader

The operating system supports multiple bootloaders.  The bootloader is
configured using @code{bootloader-configuration} declaration.  All the
fields of this structure are bootloader agnostic except for one field,
@code{bootloader} that indicates the bootloader to be configured and
installed.

Some of the bootloaders do not honor every field of
@code{bootloader-configuration}.  For instance, the extlinux bootloader does
not support themes and thus ignores the @code{theme} field.

@deftp {Tipo de dados} bootloader-configuration
The type of a bootloader configuration declaration.

@table @asis

@item @code{bootloader}
@cindex EFI, bootloader
@cindex UEFI, bootloader
@cindex BIOS, bootloader
The bootloader to use, as a @code{bootloader} object.  For now
@code{grub-bootloader}, @code{grub-efi-bootloader},
@code{grub-efi-removable-bootloader}, @code{grub-efi-netboot-bootloader},
@code{grub-efi-netboot-removable-bootloader}, @code{extlinux-bootloader} and
@code{u-boot-bootloader} are supported.

@cindex ARM, bootloaders
@cindex AArch64, bootloaders
Available bootloaders are described in @code{(gnu bootloader @dots{})}
modules.  In particular, @code{(gnu bootloader u-boot)} contains definitions
of bootloaders for a wide range of ARM and AArch64 systems, using the
@uref{https://www.denx.de/wiki/U-Boot/, U-Boot bootloader}.

@vindex grub-bootloader
@code{grub-bootloader} allows you to boot in particular Intel-based machines
in ``legacy'' BIOS mode.

@vindex grub-efi-bootloader
@code{grub-efi-bootloader} allows to boot on modern systems using the
@dfn{Unified Extensible Firmware Interface} (UEFI).  This is what you should
use if the installation image contains a @file{/sys/firmware/efi} directory
when you boot it on your system.

@vindex grub-efi-removable-bootloader
@code{grub-efi-removable-bootloader} allows you to boot your system from
removable media by writing the GRUB file to the UEFI-specification location
of @file{/EFI/BOOT/BOOTX64.efi} of the boot directory, usually
@file{/boot/efi}.  This is also useful for some UEFI firmwares that
``forget'' their configuration from their non-volatile storage. Like
@code{grub-efi-bootloader}, this can only be used if the
@file{/sys/firmware/efi} directory is available.

@quotation Nota
This @emph{will} overwrite the GRUB file from any other operating systems
that also place their GRUB file in the UEFI-specification location; making
them unbootable.
@end quotation

@vindex grub-efi-netboot-bootloader
@code{grub-efi-netboot-bootloader} allows you to boot your system over
network through TFTP@.  In combination with an NFS root file system this
allows you to build a diskless Guix system.

The installation of the @code{grub-efi-netboot-bootloader} generates the
content of the TFTP root directory at @code{targets} (@pxref{Configuração do carregador de inicialização, @code{targets}}) below the sub-directory @file{efi/Guix}, to
be served by a TFTP server.  You may want to mount your TFTP server
directories onto the @code{targets} to move the required files to the TFTP
server automatically during installation.

If you plan to use an NFS root file system as well (actually if you mount
the store from an NFS share), then the TFTP server needs to serve the file
@file{/boot/grub/grub.cfg} and other files from the store (like GRUBs
background image, the kernel (@pxref{Referência do operating-system,
@code{kernel}}) and the initrd (@pxref{Referência do operating-system,
@code{initrd}})), too.  All these files from the store will be accessed by
GRUB through TFTP with their normal store path, for example as
@file{tftp://tftp-server/gnu/store/…-initrd/initrd.cpio.gz}.

Two symlinks are created to make this possible.  For each target in the
@code{targets} field, the first symlink is
@samp{target}@file{/efi/Guix/boot/grub/grub.cfg} pointing to
@file{../../../boot/grub/grub.cfg}, where @samp{target} may be
@file{/boot}.  In this case the link is not leaving the served TFTP root
directory, but otherwise it does.  The second link is
@samp{target}@file{/gnu/store} and points to @file{../gnu/store}.  This link
is leaving the served TFTP root directory.

The assumption behind all this is that you have an NFS server exporting the
root file system for your Guix system, and additionally a TFTP server
exporting your @code{targets} directories—usually a single @file{/boot}—from
that same root file system for your Guix system.  In this constellation the
symlinks will work.

For other constellations you will have to program your own bootloader
installer, which then takes care to make necessary files from the store
accessible through TFTP, for example by copying them into the TFTP root
directory for your @code{targets}.

It is important to note that symlinks pointing outside the TFTP root
directory may need to be allowed in the configuration of your TFTP server.
Further the store link exposes the whole store through TFTP@.  Both points
need to be considered carefully for security aspects.  It is advised to
disable any TFTP write access!

Please note, that this bootloader will not modify the ‘UEFI Boot Manager’ of
the system.

Beside the @code{grub-efi-netboot-bootloader}, the already mentioned TFTP
and NFS servers, you also need a properly configured DHCP server to make the
booting over netboot possible.  For all this we can currently only recommend
you to look for instructions about @acronym{PXE, Preboot eXecution
Environment}.

If a local EFI System Partition (ESP) or a similar partition with a FAT file
system is mounted in @code{targets}, then symlinks cannot be created.  In
this case everything will be prepared for booting from local storage,
matching the behavior of @code{grub-efi-bootloader}, with the difference
that all GRUB binaries are copied to @code{targets}, necessary for booting
over the network.

@vindex grub-efi-netboot-removable-bootloader
@code{grub-efi-netboot-removable-bootloader} is identical to
@code{grub-efi-netboot-bootloader} with the exception that the sub-directory
@file{efi/boot} will be used instead of @file{efi/Guix} to comply with the
UEFI specification for removable media.

@quotation Nota
This @emph{will} overwrite the GRUB file from any other operating systems
that also place their GRUB file in the UEFI-specification location; making
them unbootable.
@end quotation

@item @code{targets}
This is a list of strings denoting the targets onto which to install the
bootloader.

The interpretation of targets depends on the bootloader in question.  For
@code{grub-bootloader}, for example, they should be device names understood
by the bootloader @command{installer} command, such as @code{/dev/sda} or
@code{(hd0)} (@pxref{Invoking grub-install,,, grub, GNU GRUB Manual}).  For
@code{grub-efi-bootloader} and @code{grub-efi-removable-bootloader} they
should be mount points of the EFI file system, usually @file{/boot/efi}.
For @code{grub-efi-netboot-bootloader}, @code{targets} should be the mount
points corresponding to TFTP root directories served by your TFTP server.

@item @code{menu-entries} (default: @code{'()})
A possibly empty list of @code{menu-entry} objects (see below), denoting
entries to appear in the bootloader menu, in addition to the current system
entry and the entry pointing to previous system generations.

@item @code{default-entry} (default: @code{0})
The index of the default boot menu entry.  Index 0 is for the entry of the
current system.

@item @code{timeout} (default: @code{5})
The number of seconds to wait for keyboard input before booting.  Set to 0
to boot immediately, and to -1 to wait indefinitely.

@cindex disposição do teclado, para o carregador de inicialização
@item @code{keyboard-layout} (padrão: @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{Disposição do teclado}).

@quotation Nota
This option is currently ignored by bootloaders other than @code{grub} and
@code{grub-efi}.
@end quotation

@item @code{theme} (default: @var{#f})
The bootloader theme object describing the theme to use.  If no theme is
provided, some bootloaders might use a default theme, that's true for GRUB.

@item @code{terminal-outputs} (default: @code{'(gfxterm)})
The output terminals used for the bootloader boot menu, as a list of
symbols.  GRUB accepts the values: @code{console}, @code{serial},
@code{serial_@{0-3@}}, @code{gfxterm}, @code{vga_text}, @code{mda_text},
@code{morse}, and @code{pkmodem}.  This field corresponds to the GRUB
variable @code{GRUB_TERMINAL_OUTPUT} (@pxref{Simple configuration,,,
grub,GNU GRUB manual}).

@item @code{terminal-inputs} (default: @code{'()})
The input terminals used for the bootloader boot menu, as a list of
symbols.  For GRUB, the default is the native platform terminal as
determined at run-time.  GRUB accepts the values: @code{console},
@code{serial}, @code{serial_@{0-3@}}, @code{at_keyboard}, and
@code{usb_keyboard}.  This field corresponds to the GRUB variable
@code{GRUB_TERMINAL_INPUT} (@pxref{Simple configuration,,, grub,GNU GRUB
manual}).

@item @code{serial-unit} (default: @code{#f})
The serial unit used by the bootloader, as an integer from 0 to 3.  For
GRUB, it is chosen at run-time; currently GRUB chooses 0, which corresponds
to COM1 (@pxref{Serial terminal,,, grub,GNU GRUB manual}).

@item @code{serial-speed} (default: @code{#f})
The speed of the serial interface, as an integer.  For GRUB, the default
value is chosen at run-time; currently GRUB chooses 9600@tie{}bps
(@pxref{Serial terminal,,, grub,GNU GRUB manual}).

@item @code{device-tree-support?} (default: @code{#t})
Whether to support Linux @uref{https://en.wikipedia.org/wiki/Devicetree,
device tree} files loading.

This option in enabled by default.  In some cases involving the
@code{u-boot} bootloader, where the device tree has already been loaded in
RAM, it can be handy to disable the option by setting it to @code{#f}.

@item @code{extra-initrd} (default: @code{#f})
File name of an additional initrd to load during the boot.  It may or may
not point to a file in the store, but the main use case is for out-of-store
files containing secrets.

In order to be able to provide decryption keys for LUKS devices, they need
to be available in the initial RAM disk.  However they cannot be stored
inside the usual initrd, since it is stored in the store and being
world-readable (as files in the store are) is not a desired property for an
initrd containing decryption keys.  You can therefore use this field to
instruct GRUB to also load a manually created initrd not stored in the
store.

For any use case not involving secrets, you should use regular initrd
(@pxref{Referência do operating-system, @code{initrd}}) instead.

Suitable image can be created for example like this:

@example
echo /key-file.bin | cpio -oH newc >/key-file.cpio
chmod 0000 /key-file.cpio
@end example

After it is created, you can use it in this manner:

@lisp
;; Operating system with encrypted boot partition
(operating-system
  @dots{}
  (bootloader (bootloader-configuration
               (bootloader grub-efi-bootloader)
               (targets '("/boot/efi"))
               ;; Load the initrd with a key file...
               (extra-initrd "/key-file.cpio")))
  (mapped-devices
   (list (mapped-device
          (source (uuid "12345678-1234-1234-1234-123456789abc"))
          (target "my-root")
          (type luks-device-mapping)
          ;; ... and use it to unlock the root device.
          (arguments '(#:key-file "/key-file.bin"))))))
@end lisp

Be careful when using this option, since pointing to a file that is not
readable by the grub while booting will cause the boot to fail and require a
manual edit of the initrd line in the grub menu.

Currently only supported by GRUB.
@end table

@end deftp

@cindex dual boot
@cindex boot menu
Should you want to list additional boot menu entries @i{via} the
@code{menu-entries} field above, you will need to create them with the
@code{menu-entry} form.  For example, imagine you want to be able to boot
another distro (hard to imagine!), you can define a menu entry along these
lines:

@lisp
(menu-entry
  (label "The Other Distro")
  (linux "/boot/old/vmlinux-2.6.32")
  (linux-arguments '("root=/dev/sda2"))
  (initrd "/boot/old/initrd"))
@end lisp

Details below.

@deftp {Tipo de dados} menu-entry
The type of an entry in the bootloader menu.

@table @asis

@item @code{label}
The label to show in the menu---e.g., @code{"GNU"}.

@item @code{linux} (default: @code{#f})
The Linux kernel image to boot, for example:

@lisp
(file-append linux-libre "/bzImage")
@end lisp

For GRUB, it is also possible to specify a device explicitly in the file
path using GRUB's device naming convention (@pxref{Naming convention,,,
grub, GNU GRUB manual}), for example:

@example
"(hd0,msdos1)/boot/vmlinuz"
@end example

If the device is specified explicitly as above, then the @code{device} field
is ignored entirely.

@item @code{linux-arguments} (default: @code{'()})
The list of extra Linux kernel command-line arguments---e.g.,
@code{'("console=ttyS0")}.

@item @code{initrd} (default: @code{#f})
A G-Expression or string denoting the file name of the initial RAM disk to
use (@pxref{Expressões-G}).

@item @code{device} (default: @code{#f})
The device where the kernel and initrd are to be found---i.e., for GRUB,
@dfn{root} for this menu entry (@pxref{root,,, grub, GNU GRUB manual}).

This may be a file system label (a string), a file system UUID (a
bytevector, @pxref{Sistemas de arquivos}), or @code{#f}, in which case the
bootloader will search the device containing the file specified by the
@code{linux} field (@pxref{search,,, grub, GNU GRUB manual}).  It must
@emph{not} be an OS device name such as @file{/dev/sda1}.

@item @code{multiboot-kernel} (default: @code{#f})
The kernel to boot in Multiboot-mode (@pxref{multiboot,,, grub, GNU GRUB
manual}).  When this field is set, a Multiboot menu-entry is generated.  For
example:

@lisp
(file-append mach "/boot/gnumach")
@end lisp

@item @code{multiboot-arguments} (default: @code{'()})
The list of extra command-line arguments for the multiboot-kernel.

For example, when running in QEMU it can be useful to use a text-based
console (use options @option{--nographic} @option{--serial mon:stdio}):

@lisp
'("console=com0")
@end lisp

To use the new and still experimental
@uref{https://darnassus.sceen.net/~hurd-web/rump_kernel/, rumpdisk
user-level disk driver} instead of GNU@tie{}Mach's in-kernel IDE driver, set
@code{kernel-arguments} to:

@lisp
'("noide")
@end lisp

Of course, these options can be combined:

@lisp
'("console=com0" "noide")
@end lisp

@item @code{multiboot-modules} (default: @code{'()})
The list of commands for loading Multiboot modules.  For example:

@lisp
(list (list (file-append hurd "/hurd/ext2fs.static") "ext2fs"
             @dots{})
      (list (file-append libc "/lib/ld.so.1") "exec"
             @dots{}))
@end lisp

@item @code{chain-loader} (default: @code{#f})
A string that can be accepted by @code{grub}'s @code{chainloader}
directive. This has no effect if either @code{linux} or
@code{multiboot-kernel} fields are specified. The following is an example of
chainloading a different GNU/Linux system.

@lisp
(bootloader
 (bootloader-configuration
  ;; @dots{}
  (menu-entries
   (list
    (menu-entry
     (label "GNU/Linux")
     (device (uuid "1C31-A17C" 'fat))
     (chain-loader "/EFI/GNULinux/grubx64.efi"))))))
@end lisp

@end table
@end deftp

@cindex HDPI
@cindex HiDPI
@cindex resolution
@c FIXME: Write documentation once it's stable.
For now only GRUB has theme support.  GRUB themes are created using the
@code{grub-theme} form, which is not fully documented yet.

@deftp {Tipo de dados} grub-theme
Data type representing the configuration of the GRUB theme.

@table @asis
@item @code{gfxmode} (default: @code{'("auto")})
The GRUB @code{gfxmode} to set (a list of screen resolution strings,
@pxref{gfxmode,,, grub, GNU GRUB manual}).
@end table
@end deftp

@deffn {Procedure} grub-theme
Return the default GRUB theme used by the operating system if no
@code{theme} field is specified in @code{bootloader-configuration} record.

It comes with a fancy background image displaying the GNU and Guix logos.
@end deffn

For example, to override the default resolution, you may use something like

@lisp
(bootloader
 (bootloader-configuration
 ;; @dots{}
 (theme (grub-theme
         (inherit (grub-theme))
         (gfxmode '("1024x786x32" "auto"))))))
@end lisp

@node Invocando guix system
@section Invoking @command{guix system}

@cindex @command{guix system}
Once you have written an operating system declaration as seen in the
previous section, it can be @dfn{instantiated} using the @command{guix
system} command.  The synopsis is:

@example
guix system @var{options}@dots{} @var{action} @var{file}
@end example

@var{file} must be the name of a file containing an @code{operating-system}
declaration.  @var{action} specifies how the operating system is
instantiated.  Currently the following values are supported:

@table @code
@item search
Display available service type definitions that match the given regular
expressions, sorted by relevance:

@cindex HDPI
@cindex HiDPI
@cindex resolution
@example
$ guix system search console
name: console-fonts
location: gnu/services/base.scm:806:2
extends: shepherd-root
description: Install the given fonts on the specified ttys (fonts are per
+ virtual console on GNU/Linux).  The value of this service is a list of
+ tty/font pairs.  The font can be the name of a font provided by the `kbd'
+ package or any valid argument to `setfont', as in this example:
+
+      '(("tty1" . "LatGrkCyr-8x16")
+        ("tty2" . (file-append
+                      font-tamzen
+                      "/share/kbd/consolefonts/TamzenForPowerline10x20.psf"))
+        ("tty3" . (file-append
+                      font-terminus
+                      "/share/consolefonts/ter-132n"))) ; for HDPI
relevance: 9

name: mingetty
location: gnu/services/base.scm:1190:2
extends: shepherd-root
description: Provide console login using the `mingetty' program.
relevance: 2

name: login
location: gnu/services/base.scm:860:2
extends: pam
description: Provide a console log-in service as specified by its
+ configuration value, a `login-configuration' object.
relevance: 2

@dots{}
@end example

As for @command{guix package --search}, the result is written in
@code{recutils} format, which makes it easy to filter the output
(@pxref{Top, GNU recutils databases,, recutils, GNU recutils manual}).

@cindex service type definition, editing
@cindex editing, service type definition
@item edit
Edit or view the definition of the given service types.

For example, the command below opens your editor, as specified by the
@env{EDITOR} environment variable, on the definition of the @code{openssh}
service type:

@example
guix system edit openssh
@end example

@item reconfigure
Build the operating system described in @var{file}, activate it, and switch
to it@footnote{This action (and the related actions @code{switch-generation}
and @code{roll-back}) are usable only on systems already running Guix
System.}.

@quotation Nota
@c The paragraph below refers to the problem discussed at
@c <https://lists.gnu.org/archive/html/guix-devel/2014-08/msg00057.html>.
It is highly recommended to run @command{guix pull} once before you run
@command{guix system reconfigure} for the first time (@pxref{Invocando guix pull}).  Failing to do that you would see an older version of Guix once
@command{reconfigure} has completed.
@end quotation

This effects all the configuration specified in @var{file}: user accounts,
system services, global package list, privileged programs, etc.  The command
starts system services specified in @var{file} that are not currently
running; if a service is currently running this command will arrange for it
to be upgraded the next time it is stopped (e.g.@: by @code{herd stop X} or
@code{herd restart X}).

This command creates a new generation whose number is one greater than the
current generation (as reported by @command{guix system list-generations}).
If that generation already exists, it will be overwritten.  This behavior
mirrors that of @command{guix package} (@pxref{Invocando guix package}).

It adds a bootloader menu entry for the new OS configuration, ---unless
@option{--no-bootloader} is passed.  For GRUB, it moves entries for older
configurations to a submenu, allowing you to choose an older system
generation at boot time should you need it.

@cindex kexec, for fast reboots
@cindex rebooting @i{via} Linux kexec
On Linux, @command{guix system reconfigure} also loads the new system for
fast reboot @i{via} kexec: running @command{reboot --kexec} will boot the
new system by directly executing its kernel, thus bypassing the BIOS
initialization phase and bootloader (@pxref{Invoking reboot,,, shepherd, The
GNU Shepherd Manual}).  You can avoid this behavior by passing the
@option{--no-kexec} option.

@cindex provenance tracking, of the operating system
Upon completion, the new system is deployed under
@file{/run/current-system}.  This directory contains @dfn{provenance
meta-data}: the list of channels in use (@pxref{Canais}) and @var{file}
itself, when available.  You can view it by running:

@example
guix system describe
@end example

This information is useful should you later want to inspect how this
particular generation was built.  In fact, assuming @var{file} is
self-contained, you can later rebuild generation @var{n} of your operating
system with:

@example
guix time-machine \
  -C /var/guix/profiles/system-@var{n}-link/channels.scm -- \
  system reconfigure \
  /var/guix/profiles/system-@var{n}-link/configuration.scm
@end example

You can think of it as some sort of built-in version control! Your system is
not just a binary artifact: @emph{it carries its own source}.  @xref{Referência de Service, @code{provenance-service-type}}, for more information on
provenance tracking.

By default, @command{reconfigure} @emph{prevents you from downgrading your
system}, which could (re)introduce security vulnerabilities and also cause
problems with ``stateful'' services such as database management systems.
You can override that behavior by passing @option{--allow-downgrades}.

@item switch-generation
@cindex gerações
Switch to an existing system generation.  This action atomically switches
the system profile to the specified system generation.  It also rearranges
the system's existing bootloader menu entries.  It makes the menu entry for
the specified system generation the default, and it moves the entries for
the other generations to a submenu, if supported by the bootloader being
used.  The next time the system boots, it will use the specified system
generation.

The bootloader itself is not being reinstalled when using this command.
Thus, the installed bootloader is used with an updated configuration file.

The target generation can be specified explicitly by its generation number.
For example, the following invocation would switch to system generation 7:

@example
guix system switch-generation 7
@end example

The target generation can also be specified relative to the current
generation with the form @code{+N} or @code{-N}, where @code{+3} means ``3
generations ahead of the current generation,'' and @code{-1} means ``1
generation prior to the current generation.'' When specifying a negative
value such as @code{-1}, you must precede it with @code{--} to prevent it
from being parsed as an option.  For example:

@example
guix system switch-generation -- -1
@end example

Currently, the effect of invoking this action is @emph{only} to switch the
system profile to an existing generation and rearrange the bootloader menu
entries.  To actually start using the target system generation, you must
reboot after running this action.  In the future, it will be updated to do
the same things as @command{reconfigure}, like activating and deactivating
services.

This action will fail if the specified generation does not exist.

@item roll-back
@cindex revertendo
Switch to the preceding system generation.  The next time the system boots,
it will use the preceding system generation.  This is the inverse of
@command{reconfigure}, and it is exactly the same as invoking
@command{switch-generation} with an argument of @code{-1}.

Currently, as with @command{switch-generation}, you must reboot after
running this action to actually start using the preceding system generation.

@item delete-generations
@cindex deleting system generations
@cindex saving space
Delete system generations, making them candidates for garbage collection
(@pxref{Invocando guix gc}, for information on how to run the ``garbage
collector'').

This works in the same way as @samp{guix package --delete-generations}
(@pxref{Invocando guix package, @option{--delete-generations}}).  With no
arguments, all system generations but the current one are deleted:

@example
guix system delete-generations
@end example

You can also select the generations you want to delete.  The example below
deletes all the system generations that are more than two months old:

@example
guix system delete-generations 2m
@end example

Running this command automatically reinstalls the bootloader with an updated
list of menu entries---e.g., the ``old generations'' sub-menu in GRUB no
longer lists the generations that have been deleted.

@item build
Build the derivation of the operating system, which includes all the
configuration files and programs needed to boot and run the system.  This
action does not actually install anything.

@item init
Populate the given directory with all the files necessary to run the
operating system specified in @var{file}.  This is useful for first-time
installations of Guix System.  For instance:

@example
guix system init my-os-config.scm /mnt
@end example

copies to @file{/mnt} all the store items required by the configuration
specified in @file{my-os-config.scm}.  This includes configuration files,
packages, and so on.  It also creates other essential files needed for the
system to operate correctly---e.g., the @file{/etc}, @file{/var}, and
@file{/run} directories, and the @file{/bin/sh} file.

This command also installs bootloader on the targets specified in
@file{my-os-config}, unless the @option{--no-bootloader} option was passed.

@item installer
Run the installer.  Usually the installer is built as an @file{iso} image,
copied to a USB Stick or DVD, and booted from (@ref{Instalação em um pendrive e em DVD}).  If your machine already runs Guix and you still want to run
the installer, e.g., for testing purposes, you can skip the step of creating
an @file{iso} and run for instance:

@example
guix system installer --dry-run
@end example

@quotation Nota
If you do not use @option{--dry-run} then you need to run as root.  Be
@emph{very careful} when running the installer as root, it can cause data
loss or render your system unbootable!
@end quotation

@item vm
@cindex virtual machine
@cindex VM
@anchor{guix system vm}
Build a virtual machine (VM) that contains the operating system declared in
@var{file}, and return a script to run that VM.

@quotation 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{Configuração do ambiente de compilação}).
@end quotation

Arguments given to the script are passed to QEMU as in the example below,
which enables networking and requests 1@tie{}GiB of RAM for the emulated
machine:

@example
$ /gnu/store/@dots{}-run-vm.sh -m 1024 -smp 2 -nic user,model=virtio-net-pci
@end example

It's possible to combine the two steps into one:

@example
$ $(guix system vm my-config.scm) -m 1024 -smp 2 -nic user,model=virtio-net-pci
@end example

The VM shares its store with the host system.

By default, the root file system of the VM is mounted volatile; the
@option{--persistent} option can be provided to make it persistent instead.
In that case, the VM disk-image file will be copied from the store to the
@env{TMPDIR} directory to make it writable.

Additional file systems can be shared between the host and the VM using the
@option{--share} and @option{--expose} command-line options: the former
specifies a directory to be shared with write access, while the latter
provides read-only access to the shared directory.

The example below creates a VM in which the user's home directory is
accessible read-only, and where the @file{/exchange} directory is a
read-write mapping of @file{$HOME/tmp} on the host:

@example
guix system vm my-config.scm \
   --expose=$HOME --share=$HOME/tmp=/exchange
@end example

On GNU/Linux, the default is to boot directly to the kernel; this has the
advantage of requiring only a very tiny root disk image since the store of
the host can then be mounted.

The @option{--full-boot} option forces a complete boot sequence, starting
with the bootloader.  This requires more disk space since a root image
containing at least the kernel, initrd, and bootloader data files must be
created.

The @option{--image-size} option can be used to specify the size of the
image.

The @option{--no-graphic} option will instruct @command{guix system} to
spawn a headless VM that will use the invoking tty for IO.  Among other
things, this enables copy-pasting, and scrollback.  Use the @kbd{ctrl-a}
prefix to issue QEMU commands; e.g.@: @kbd{ctrl-a h} prints a help,
@kbd{ctrl-a x} quits the VM, and @kbd{ctrl-a c} switches between the QEMU
monitor and the VM.

@cindex System images, creation in various formats
@cindex Creating system images in various formats
@item image
@cindex image, creating disk images
The @code{image} command can produce various image types.  The image type
can be selected using the @option{--image-type} option.  It defaults to
@code{mbr-hybrid-raw}.  When its value is @code{iso9660}, the
@option{--label} option can be used to specify a volume ID with
@code{image}.  By default, the root file system of a disk image is mounted
non-volatile; the @option{--volatile} option can be provided to make it
volatile instead.  When using @code{image}, the bootloader installed on the
generated image is taken from the provided @code{operating-system}
definition.  The following example demonstrates how to generate an image
that uses the @code{grub-efi-bootloader} bootloader and boot it with QEMU:

@example
image=$(guix system image --image-type=qcow2 \
        gnu/system/examples/lightweight-desktop.tmpl)
cp $image /tmp/my-image.qcow2
chmod +w /tmp/my-image.qcow2
qemu-system-x86_64 -enable-kvm -hda /tmp/my-image.qcow2 -m 1000 \
                   -bios $(guix build ovmf-x86-64)/share/firmware/ovmf_x64.bin
@end example

When using the @code{mbr-hybrid-raw} image type, a raw disk image is
produced; it can be copied as is to a USB stick, for instance.  Assuming
@code{/dev/sdc} is the device corresponding to a USB stick, one can copy the
image to it using the following command:

@example
# dd if=$(guix system image my-os.scm) of=/dev/sdc status=progress
@end example

The @code{--list-image-types} command lists all the available image types.

@cindex creating virtual machine images
When using the @code{qcow2} image type, the returned image is in qcow2
format, which the QEMU emulator can efficiently use. @xref{Executando Guix em uma VM}, for more information on how to run the image in a virtual machine.  The
@code{grub-bootloader} bootloader is always used independently of what is
declared in the @code{operating-system} file passed as argument.  This is to
make it easier to work with QEMU, which uses the SeaBIOS BIOS by default,
expecting a bootloader to be installed in the Master Boot Record (MBR).  In
case the virtual machine is going to be AArch64, you might want to take a
look at @code{qcow2-gpt} image type that installs bootloader only in EFI.

@cindex docker-image, creating docker images
When using the @code{docker} image type, a Docker image is produced.  Guix
builds the image from scratch, not from a pre-existing Docker base image.
As a result, it contains @emph{exactly} what you define in the operating
system configuration file.  You can then load the image and launch a Docker
container using commands like the following:

@example
image_id="$(docker load < guix-system-docker-image.tar.gz)"
container_id="$(docker create $image_id)"
docker start $container_id
@end example

This command starts a new Docker container from the specified image.  It
will boot the Guix system in the usual manner, which means it will start any
services you have defined in the operating system configuration.  You can
get an interactive shell running in the container using @command{docker
exec}:

@example
docker exec -ti $container_id /run/current-system/profile/bin/bash --login
@end example

Depending on what you run in the Docker container, it may be necessary to
give the container additional permissions.  For example, if you intend to
build software using Guix inside of the Docker container, you may need to
pass the @option{--privileged} option to @code{docker create}.

Last, the @option{--network} option applies to @command{guix system
docker-image}: it produces an image where network is supposedly shared with
the host, and thus without services like nscd or NetworkManager.

@item container
Return a script to run the operating system declared in @var{file} within a
container.  Containers are a set of lightweight isolation mechanisms
provided by the kernel Linux-libre.  Containers are substantially less
resource-demanding than full virtual machines since the kernel, shared
objects, and other resources can be shared with the host system; this also
means they provide thinner isolation.

Currently, the script must be run as root in order to support more than a
single user and group.  The container shares its store with the host system.

As with the @code{vm} action (@pxref{guix system vm}), additional file
systems to be shared between the host and container can be specified using
the @option{--share} and @option{--expose} options:

@example
guix system container my-config.scm \
   --expose=$HOME --share=$HOME/tmp=/exchange
@end example

The @option{--share} and @option{--expose} options can also be passed to the
generated script to bind-mount additional directories into the container.

The generated script also supports the @option{--pid-file} option to write
the container process ID to a file. This can be used, along with
@command{guix container exec} to execute scripts within the container
(@pxref{Invocando guix container}).

@quotation Nota
The @code{container} action requires Linux-libre 3.19 or newer.
@end quotation

@end table

@var{options} can contain any of the common build options (@pxref{Opções de compilação comuns}).  In addition, @var{options} can contain one of the
following:

@table @option
@item --expression=@var{expr}
@itemx -e @var{expr}
Consider the operating-system @var{expr} evaluates to.  This is an
alternative to specifying a file which evaluates to an operating system.
This is used to generate the Guix system installer @pxref{Compilando a imagem de instalação}).

@item --system=@var{sistema}
@itemx -s @var{sistema}
Attempt to build for @var{system} instead of the host system type.  This
works as per @command{guix build} (@pxref{Invocando guix build}).

@item --target=@var{tripleto}
Construção cruzada para @var{tripleto}, que deve ser um tripleto GNU válido,
como @code{"aarch64-linux-gnu"} (@pxref{Specifying target triplets,
tripletos de configuração GNU, autoconf, Autoconf}).

@item --derivation
@itemx -d
Return the derivation file name of the given operating system without
building anything.

@cindex provenance tracking, of the operating system
@item --save-provenance
As discussed above, @command{guix system init} and @command{guix system
reconfigure} always save provenance information @i{via} a dedicated service
(@pxref{Referência de Service, @code{provenance-service-type}}).  However, other
commands don't do that by default.  If you wish to, say, create a virtual
machine image that contains provenance information, you can run:

@example
guix system image -t qcow2 --save-provenance config.scm
@end example

That way, the resulting image will effectively ``embed its own source'' in
the form of meta-data in @file{/run/current-system}.  With that information,
one can rebuild the image to make sure it really contains what it pretends
to contain; or they could use that to derive a variant of the image.

@item --image-type=@var{type}
@itemx -t @var{tipo}
For the @code{image} action, create an image with given @var{type}.

When this option is omitted, @command{guix system} uses the
@code{mbr-hybrid-raw} image type.

@cindex ISO-9660 format
@cindex CD image format
@cindex DVD image format
@option{--image-type=iso9660} produces an ISO-9660 image, suitable for
burning on CDs and DVDs.

@item --image-size=@var{size}
For the @code{image} action, create an image of the given @var{size}.
@var{size} may be a number of bytes, or it may include a unit as a suffix
(@pxref{Block size, size specifications,, coreutils, GNU Coreutils}).

When this option is omitted, @command{guix system} computes an estimate of
the image size as a function of the size of the system declared in
@var{file}.

@item --network
@itemx -N
For the @code{container} action, allow containers to access the host
network, that is, do not create a network namespace.

@item --root=@var{arquivo}
@itemx -r @var{arquivo}
Make @var{file} a symlink to the result, and register it as a garbage
collector root.

@item --skip-checks
Skip pre-installation safety checks.

By default, @command{guix system init} and @command{guix system reconfigure}
perform safety checks: they make sure the file systems that appear in the
@code{operating-system} declaration actually exist (@pxref{Sistemas de arquivos}),
and that any Linux kernel modules that may be needed at boot time are listed
in @code{initrd-modules} (@pxref{Disco de RAM inicial}).  Passing this option
skips these tests altogether.

@item --allow-downgrades
Instruct @command{guix system reconfigure} to allow system downgrades.

By default, @command{reconfigure} prevents you from downgrading your
system.  It achieves that by comparing the provenance info of your system
(shown by @command{guix system describe}) with that of your @command{guix}
command (shown by @command{guix describe}).  If the commits for
@command{guix} are not descendants of those used for your system,
@command{guix system reconfigure} errors out.  Passing
@option{--allow-downgrades} allows you to bypass these checks.

@quotation Nota
Certifique-se de entender as implicações de segurança antes de usar
@option{--allow-downgrades}.
@end quotation

@cindex on-error
@cindex on-error strategy
@cindex error strategy
@item --on-error=@var{strategy}
Apply @var{strategy} when an error occurs when reading @var{file}.
@var{strategy} may be one of the following:

@table @code
@item nothing-special
Report the error concisely and exit.  This is the default strategy.

@item backtrace
Likewise, but also display a backtrace.

@item debug
Report the error and enter Guile's debugger.  From there, you can run
commands such as @code{,bt} to get a backtrace, @code{,locals} to display
local variable values, and more generally inspect the state of the program.
@xref{Debug Commands,,, guile, GNU Guile Reference Manual}, for a list of
available debugging commands.
@end table
@end table

Once you have built, configured, re-configured, and re-re-configured your
Guix installation, you may find it useful to list the operating system
generations available on disk---and that you can choose from the bootloader
boot menu:

@table @code

@item describe
Describe the running system generation: its file name, the kernel and
bootloader used, etc., as well as provenance information when available.

The @code{--list-installed} flag is available, with the same syntax that is
used in @command{guix package --list-installed} (@pxref{Invocando guix package}).  When the flag is used, the description will include a list of
packages that are currently installed in the system profile, with optional
filtering based on a regular expression.

@quotation Nota
The @emph{running} system generation---referred to by
@file{/run/current-system}---is not necessarily the @emph{current} system
generation---referred to by @file{/var/guix/profiles/system}: it differs
when, for instance, you chose from the bootloader menu to boot an older
generation.

It can also differ from the @emph{booted} system generation---referred to by
@file{/run/booted-system}---for instance because you reconfigured the system
in the meantime.
@end quotation

@item list-generations
List a summary of each generation of the operating system available on disk,
in a human-readable way.  This is similar to the @option{--list-generations}
option of @command{guix package} (@pxref{Invocando guix package}).

Optionally, one can specify a pattern, with the same syntax that is used in
@command{guix package --list-generations}, to restrict the list of
generations displayed.  For instance, the following command displays
generations that are up to 10 days old:

@example
$ guix system list-generations 10d
@end example

The @code{--list-installed} flag may also be specified, with the same syntax
that is used in @command{guix package --list-installed}.  This may be
helpful if trying to determine when a package was added to the system.

@end table

The @command{guix system} command has even more to offer! The following
sub-commands allow you to visualize how your system services relate to each
other:

@anchor{system-extension-graph}
@table @code

@item extension-graph
Emit to standard output the @dfn{service extension graph} of the operating
system defined in @var{file} (@pxref{Composição de serviço}, for more
information on service extensions).  By default the output is in
Dot/Graphviz format, but you can choose a different format with
@option{--graph-backend}, as with @command{guix graph} (@pxref{Invocando guix graph, @option{--backend}}):

O comando:

@example
$ guix system extension-graph @var{file} | xdot -
@end example

shows the extension relations among services.

@quotation Nota
The @command{dot} program is provided by the @code{graphviz} package.
@end quotation

@anchor{system-shepherd-graph}
@item shepherd-graph
Emit to standard output the @dfn{dependency graph} of shepherd services of
the operating system defined in @var{file}.  @xref{Serviços de Shepherd}, for
more information and for an example graph.

Again, the default output format is Dot/Graphviz, but you can pass
@option{--graph-backend} to select a different one.

@end table

@node Invocando guix deploy
@section Invoking @command{guix deploy}

@cindex @command{guix deploy}
We've already seen @code{operating-system} declarations used to manage a
machine's configuration locally.  Suppose you need to configure multiple
machines, though---perhaps you're managing a service on the web that's
comprised of several servers.  @command{guix deploy} enables you to use
those same @code{operating-system} declarations to manage multiple remote
hosts at once as a logical ``deployment''.

@quotation Nota
The functionality described in this section is still under development and
is subject to change.  Get in touch with us on @email{guix-devel@@gnu.org}!
@end quotation

@example
guix deploy @var{file}
@end example

Such an invocation will deploy the machines that the code within @var{file}
evaluates to.  As an example, @var{file} might contain a definition like
this:

@lisp
;; This is a Guix deployment of a "bare bones" setup, with
;; no X11 display server, to a machine with an SSH daemon
;; listening on localhost:2222. A configuration such as this
;; may be appropriate for virtual machine with ports
;; forwarded to the host's loopback interface.

(use-service-modules networking ssh)
(use-package-modules bootloaders)

(define %system
  (operating-system
   (host-name "gnu-deployed")
   (timezone "Etc/UTC")
   (bootloader (bootloader-configuration
                (bootloader grub-bootloader)
                (targets '("/dev/vda"))
                (terminal-outputs '(console))))
   (file-systems (cons (file-system
                        (mount-point "/")
                        (device "/dev/vda1")
                        (type "ext4"))
                       %base-file-systems))
   (services
    (append (list (service dhcp-client-service-type)
                  (service openssh-service-type
                           (openssh-configuration
                            (permit-root-login #t)
                            (allow-empty-passwords? #t))))
            %base-services))))

(list (machine
       (operating-system %system)
       (environment managed-host-environment-type)
       (configuration (machine-ssh-configuration
                       (host-name "localhost")
                       (system "x86_64-linux")
                       (user "alice")
                       (identity "./id_rsa")
                       (port 2222)))))
@end lisp

The file should evaluate to a list of @var{machine} objects.  This example,
upon being deployed, will create a new generation on the remote system
realizing the @code{operating-system} declaration @code{%system}.
@code{environment} and @code{configuration} specify how the machine should
be provisioned---that is, how the computing resources should be created and
managed.  The above example does not create any resources, as a
@code{'managed-host} is a machine that is already running the Guix system
and available over the network.  This is a particularly simple case; a more
complex deployment may involve, for example, starting virtual machines
through a Virtual Private Server (VPS) provider.  In such a case, a
different @var{environment} type would be used.

Do note that you first need to generate a key pair on the coordinator
machine to allow the daemon to export signed archives of files from the
store (@pxref{Invocando guix archive}), though this step is automatic on Guix
System:

@example
# guix archive --generate-key
@end example

@noindent
Each target machine must authorize the key of the master machine so that it
accepts store items it receives from the coordinator:

@example
# guix archive --authorize < coordinator-public-key.txt
@end example

@code{user}, in this example, specifies the name of the user account to log
in as to perform the deployment.  Its default value is @code{root}, but root
login over SSH may be forbidden in some cases.  To work around this,
@command{guix deploy} can log in as an unprivileged user and employ
@code{sudo} to escalate privileges.  This will only work if @code{sudo} is
currently installed on the remote and can be invoked non-interactively as
@code{user}.  That is, the line in @code{sudoers} granting @code{user} the
ability to use @code{sudo} must contain the @code{NOPASSWD} tag.  This can
be accomplished with the following operating system configuration snippet:

@lisp
(use-modules ...
             (gnu system))               ;for %sudoers-specification

(define %user "username")

(operating-system
  ...
  (sudoers-file
     (plain-file "sudoers"
                 (string-append (plain-file-content %sudoers-specification)
                                (format #f "~a ALL = NOPASSWD: ALL~%"
                                        %user)))))

@end lisp

For more information regarding the format of the @file{sudoers} file,
consult @command{man sudoers}.

Once you've deployed a system on a set of machines, you may find it useful
to run a command on all of them.  The @option{--execute} or @option{-x}
option lets you do that; the example below runs @command{uname -a} on all
the machines listed in the deployment file:

@example
guix deploy @var{file} -x -- uname -a
@end example

One thing you may often need to do after deployment is restart specific
services on all the machines, which you can do like so:

@example
guix deploy @var{file} -x -- herd restart @var{service}
@end example

The @command{guix deploy -x} command returns zero if and only if the command
succeeded on all the machines.

You may also wish to roll back configurations on machines to a previous
generation.  You can do that using the @option{--roll-back} or @option{-r}
option like so:

@example
guix deploy --roll-back @var{file}
@end example

@c FIXME/TODO: Separate the API doc from the CLI doc.

Below are the data types you need to know about when writing a deployment
file.

@deftp {Tipo de dados} machine
This is the data type representing a single machine in a heterogeneous Guix
deployment.

@table @asis
@item @code{operating-system}
The object of the operating system configuration to deploy.

@item @code{environment}
An @code{environment-type} describing how the machine should be provisioned.

@item @code{configuration} (default: @code{#f})
An object describing the configuration for the machine's
@code{environment}.  If the @code{environment} has a default configuration,
@code{#f} may be used.  If @code{#f} is used for an environment with no
default configuration, however, an error will be thrown.
@end table
@end deftp

@deftp {Tipo de dados} machine-ssh-configuration
This is the data type representing the SSH client parameters for a machine
with an @code{environment} of @code{managed-host-environment-type}.

@table @asis
@item @code{host-name}
@item @code{build-locally?} (default: @code{#t})
If false, system derivations will be built on the machine being deployed to.
@item @code{system}
The system type describing the architecture of the machine being deployed
to---e.g., @code{"x86_64-linux"}.
@item @code{authorize?} (default: @code{#t})
If true, the coordinator's signing key will be added to the remote's ACL
keyring.
@item @code{port} (padrão: @code{22})
@item @code{user} (default: @code{"root"})
@item @code{identity} (default: @code{#f})
If specified, the path to the SSH private key to use to authenticate with
the remote host.

@item @code{host-key} (default: @code{#f})
This should be the SSH host key of the machine, which looks like this:

@example
ssh-ed25519 AAAAC3Nz@dots{} root@@example.org
@end example

When @code{host-key} is @code{#f}, the server is authenticated against the
@file{~/.ssh/known_hosts} file, just like the OpenSSH @command{ssh} client
does.

@item @code{allow-downgrades?} (default: @code{#f})
Whether to allow potential downgrades.

Like @command{guix system reconfigure}, @command{guix deploy} compares the
channel commits currently deployed on the remote host (as returned by
@command{guix system describe}) to those currently in use (as returned by
@command{guix describe}) to determine whether commits currently in use are
descendants of those deployed.  When this is not the case and
@code{allow-downgrades?} is false, it raises an error.  This ensures you do
not accidentally downgrade remote machines.

@item @code{safety-checks?} (default: @code{#t})
Whether to perform ``safety checks'' before deployment.  This includes
verifying that devices and file systems referred to in the operating system
configuration actually exist on the target machine, and making sure that
Linux modules required to access storage devices at boot time are listed in
the @code{initrd-modules} field of the operating system.

These safety checks ensure that you do not inadvertently deploy a system
that would fail to boot.  Be careful before turning them off!
@end table
@end deftp

@deftp {Tipo de dados} digital-ocean-configuration
This is the data type describing the Droplet that should be created for a
machine with an @code{environment} of @code{digital-ocean-environment-type}.

@table @asis
@item @code{ssh-key}
The path to the SSH private key to use to authenticate with the remote
host.  In the future, this field may not exist.
@item @code{tags}
A list of string ``tags'' that uniquely identify the machine.  Must be given
such that no two machines in the deployment have the same set of tags.
@item @code{region}
A Digital Ocean region slug, such as @code{"nyc3"}.
@item @code{size}
A Digital Ocean size slug, such as @code{"s-1vcpu-1gb"}
@item @code{enable-ipv6?}
Whether or not the droplet should be created with IPv6 networking.
@end table
@end deftp

@deftp {Data Type} hetzner-configuration
This is the data type describing the server that should be created for a
machine with an @code{environment} of @code{hetzner-environment-type}. It
allows you to configure deployment to a @acronym{VPS, virtual private
server} hosted by @uref{https://www.hetzner.com, Hetzner}.

@table @asis

@item @code{allow-downgrades?} (default: @code{#f})
Whether to allow potential downgrades.

@item @code{authorize?} (default: @code{#t})
If true, the public signing key @code{"/etc/guix/signing-key.pub"} of the
machine that invokes @command{guix deploy} will be added to the operating
system ACL keyring of the target machine.

@item @code{build-locally?} (default: @code{#t})
If true, system derivations will be built on the machine that invokes
@command{guix deploy}, otherwise derivations are build on the target
machine.  Set this to @code{#f} if the machine you are deploying from has a
different architecture than the target machine and you can't build
derivations for the target architecture by other means, like offloading
(@pxref{Configuração de descarregamento de daemon}) or emulation
(@pxref{transparent-emulation-qemu, Transparent Emulation with QEMU}).

@item @code{delete?} (default: @code{#t})
If true, the server will be deleted when an error happens in the
provisioning phase. If false, the server will be kept in order to debug any
issues.

@item @code{ipv4} (default: @code{#t})
@itemx @code{ipv6} (default: @code{#t})
When false, no public IP address is attached.  Specify the name of an
existing primary ip to attach it to the machine.  Other values would create
a new address automatically.

@item @code{labels} (default: @code{'()})
A user defined alist of key/value pairs attached to the SSH key and the
server on the Hetzner API.  Keys and values must be strings,
e.g. @code{'(("environment" . "development"))}.  For more information, see
@uref{https://docs.hetzner.cloud/#labels, Labels}.

@item @code{location} (default: @code{"fsn1"})
The name of a @uref{https://docs.hetzner.com/cloud/general/locations,
location} to create the server in.  For example, @code{"fsn1"} corresponds
to the Hetzner site in Falkenstein, Germany, while @code{"sin"} corresponds
to its site in Singapore.

@item @code{server-type} (default: @code{"cx42"})
The name of the
@uref{https://docs.hetzner.com/cloud/servers/overview#server-types, server
type} this virtual server should be created with.  For example,
@code{"cx42"} corresponds to a x86_64 server that has 8 VCPUs, 16 GB of
memory and 160 GB of storage, while @code{"cax31"} to the AArch64
equivalent.  Other server types and their current prices can be found
@uref{https://www.hetzner.com/cloud/#pricing, here}.  The @code{"cpx11"}
server type is currently not supported, since its rescue system is too small
to bootstrap a Guix system from.

@item @code{ssh-key} (default: @code{#f})
If specified, the file name of the SSH private key to use to authenticate
with the remote host.

@item @code{ssh-public-key} (default: extracted from @code{ssh-key})
If specified, either a public key as returned by @code{string->public-key}
or the path to the SSH public key to use to authenticate with the remote
host.

@end table

When deploying a machine for the first time, the following steps are taken
to provision a server for the machine on the
@uref{https://www.hetzner.com/cloud, Hetzner Cloud} service:

@itemize

@item
Create the SSH key of the machine on the Hetzner API.

@item
Create a server for the machine on the Hetzner API.

@item
Format the root partition of the disk using the file system of the machine's
operating system.  Supported file systems are btrfs and ext4.

@item
Install a minimal Guix operating system on the server using the
@uref{https://docs.hetzner.com/cloud/servers/getting-started/rescue-system,
rescue mode}.  This minimal system is used to install the machine's
operating system, after rebooting.

@item
Reboot the server and apply the machine's operating system on the server.

@end itemize

Once the server has been provisioned and SSH is available, deployment
continues by delegating it to the @code{managed-host-environment-type}.

Servers on the Hetzner Cloud service can be provisioned on the AArch64
architecture using UEFI boot mode, or on the x86_64 architecture using BIOS
boot mode.  The @code{(gnu machine hetzner)} module exports the
@code{%hetzner-os-arm} and @code{%hetzner-os-x86} operating systems that are
compatible with those two architectures, and can be used as a base for
defining your custom operating system.

The following example shows the definition of two machines that are deployed
on the Hetzner Cloud service.  The first one uses the @code{%hetzner-os-arm}
operating system to run a server with 16 shared vCPUs and 32 GB of RAM on
the @code{aarch64} architecture, the second one uses the
@code{%hetzner-os-x86} operating system on a server with 16 shared vCPUs and
32 GB of RAM on the @code{x86_64} architecture.

@lisp
(use-modules (gnu machine)
             (gnu machine hetzner))

(list (machine
       (operating-system %hetzner-os-arm)
       (environment hetzner-environment-type)
       (configuration (hetzner-configuration
                       (server-type "cax41")
                       (ssh-key "/home/charlie/.ssh/id_rsa"))))
      (machine
       (operating-system %hetzner-os-x86)
       (environment hetzner-environment-type)
       (configuration (hetzner-configuration
                       (server-type "cpx51")
                       (ssh-public-key "/home/charlie/.ssh/id_rsa.pub")))))
@end lisp

@vindex GUIX_HETZNER_API_TOKEN
Passing this file to @command{guix deploy} with the environment variable
@env{GUIX_HETZNER_API_TOKEN} set to a valid Hetzner
@uref{https://docs.hetzner.com/cloud/api/getting-started/generating-api-token,
API key} should provision two machines for you.

@end deftp

@node Executando Guix em uma VM
@section Usando o Guix em uma Máquina Virtual

@cindex virtual machine
To run Guix in a virtual machine (VM), one can use the pre-built Guix VM
image distributed at
@url{@value{BASE-URL}/guix-system-vm-image-@value{VERSION}.x86_64-linux.qcow2}.
This image is a compressed image in QCOW format.  You can pass it to an
emulator such as @uref{https://qemu.org/, QEMU} (see below for details).

This image boots the Xfce graphical environment and it contains some
commonly used tools.  You can install more software in the image by running
@command{guix package} in a terminal (@pxref{Invocando guix package}).  You
can also reconfigure the system based on its initial configuration file
available as @file{/run/current-system/configuration.scm} (@pxref{Usando o sistema de configuração}).

Instead of using this pre-built image, one can also build their own image
using @command{guix system image} (@pxref{Invocando guix system}).

@cindex QEMU
If you built your own image, you must copy it out of the store (@pxref{O armazém}) and give yourself permission to write to the copy before you can use
it.  When invoking QEMU, you must choose a system emulator that is suitable
for your hardware platform.  Here is a minimal QEMU invocation that will
boot the result of @command{guix system image -t qcow2} on x86_64 hardware:

@example
$ qemu-system-x86_64 \
   -nic user,model=virtio-net-pci \
   -enable-kvm -m 2048 \
   -device virtio-blk,drive=myhd \
   -drive if=none,file=guix-system-vm-image-@value{VERSION}.x86_64-linux.qcow2,id=myhd
@end example

Here is what each of these options means:

@table @code
@item qemu-system-x86_64
This specifies the hardware platform to emulate.  This should match the
host.

@item -nic user,model=virtio-net-pci
Enable the unprivileged user-mode network stack.  The guest OS can access
the host but not vice versa.  This is the simplest way to get the guest OS
online.  @code{model} specifies which network device to emulate:
@code{virtio-net-pci} is a special device made for virtualized operating
systems and recommended for most uses.  Assuming your hardware platform is
x86_64, you can get a list of available NIC models by running
@command{qemu-system-x86_64 -nic model=help}.

@item -enable-kvm
If your system has hardware virtualization extensions, enabling the virtual
machine support (KVM) of the Linux kernel will make things run faster.

@c To run Xfce + 'guix pull', we need at least 1G of RAM.
@item -m 2048
RAM available to the guest OS, in mebibytes.  Defaults to 128@tie{}MiB,
which may be insufficient for some operations.

@item -device virtio-blk,drive=myhd
Create a @code{virtio-blk} drive called ``myhd''.  @code{virtio-blk} is a
``paravirtualization'' mechanism for block devices that allows QEMU to
achieve better performance than if it were emulating a complete disk drive.
See the QEMU and KVM documentation for more info.

@item -drive if=none,file=/tmp/qemu-image,id=myhd
Use our QCOW image, the
@file{guix-system-vm-image-@value{VERSION}.x86_64-linux.qcow2} file, as the
backing store of the ``myhd'' drive.
@end table

The default @command{run-vm.sh} script that is returned by an invocation of
@command{guix system vm} does not add a @command{-nic user} flag by
default.  To get network access from within the vm add the
@code{(dhcp-client-service)} to your system definition and start the VM
using @command{$(guix system vm config.scm) -nic user}.  An important caveat
of using @command{-nic user} for networking is that @command{ping} will not
work, because it uses the ICMP protocol.  You'll have to use a different
command to check for network connectivity, for example @command{guix
download}.

@subsection Connecting Through SSH

@cindex SSH
@cindex SSH server
To enable SSH inside a VM you need to add an SSH server like
@code{openssh-service-type} to your VM (@pxref{Serviços de Rede,
@code{openssh-service-type}}).  In addition you need to forward the SSH
port, 22 by default, to the host.  You can do this with

@example
$(guix system vm config.scm) -nic user,model=virtio-net-pci,hostfwd=tcp::10022-:22
@end example

To connect to the VM you can run

@example
ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -p 10022 localhost
@end example

The @command{-p} tells @command{ssh} the port you want to connect to.
@command{-o UserKnownHostsFile=/dev/null} prevents @command{ssh} from
complaining every time you modify your @command{config.scm} file and the
@command{-o StrictHostKeyChecking=no} prevents you from having to allow a
connection to an unknown host every time you connect.

@quotation Nota
If you find the above @samp{hostfwd} example not to be working (e.g., your
SSH client hangs attempting to connect to the mapped port of your VM), make
sure that your Guix System VM has networking support, such as by using the
@code{dhcp-client-service-type} service type.
@end quotation

@subsection Using @command{virt-viewer} with Spice

As an alternative to the default @command{qemu} graphical client you can use
the @command{remote-viewer} from the @command{virt-viewer} package.  To
connect pass the @command{-spice port=5930,disable-ticketing} flag to
@command{qemu}.  See previous section for further information on how to do
this.

Spice also allows you to do some nice stuff like share your clipboard with
your VM@.  To enable that you'll also have to pass the following flags to
@command{qemu}:

@example
-device virtio-serial-pci,id=virtio-serial0,max_ports=16,bus=pci.0,addr=0x5
-chardev spicevmc,name=vdagent,id=vdagent
-device virtserialport,nr=1,bus=virtio-serial0.0,chardev=vdagent,\
name=com.redhat.spice.0
@end example

You'll also need to add the @code{(spice-vdagent-service)} to your system
definition (@pxref{Serviços diversos, Spice service}).

@node Definindo serviços
@section Definindo serviços

The previous sections show the available services and how one can combine
them in an @code{operating-system} declaration.  But how do we define them
in the first place? And what is a service anyway?

@menu
* Composição de serviço::    O modelo para serviços de composição.
* Tipos de Service e Serviços::  Tipos e serviços.
* Referência de Service::    Referência de API.
* Serviços de Shepherd::     Um tipo em particular de serviço.
* Complex Configurations::   Defining bindings for complex configurations.
@end menu

@node Composição de serviço
@subsection Composição de serviço

@cindex services
@cindex daemons
Here we define a @dfn{service} as, broadly, something that extends the
functionality of the operating system.  Often a service is a process---a
@dfn{daemon}---started when the system boots: a secure shell server, a Web
server, the Guix build daemon, etc.  Sometimes a service is a daemon whose
execution can be triggered by another daemon---e.g., an FTP server started
by @command{inetd} or a D-Bus service activated by @command{dbus-daemon}.
Occasionally, a service does not map to a daemon.  For instance, the
``account'' service collects user accounts and makes sure they exist when
the system runs; the ``udev'' service collects device management rules and
makes them available to the eudev daemon; the @file{/etc} service populates
the @file{/etc} directory of the system.

@cindex service extensions
Guix system services are connected by @dfn{extensions}.  For instance, the
secure shell service @emph{extends} the Shepherd---the initialization
system, running as PID@tie{}1---by giving it the command lines to start and
stop the secure shell daemon (@pxref{Serviços de Rede,
@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{Serviços de desktop,
@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{Serviços básicos}).

All in all, services and their ``extends'' relations form a directed acyclic
graph (DAG).  If we represent services as boxes and extensions as arrows, a
typical system might provide something like this:

@image{images/service-graph,,5in,Typical service extension graph.}

@cindex system service
At the bottom, we see the @dfn{system service}, which produces the directory
containing everything to run and boot the system, as returned by the
@command{guix system build} command.  @xref{Referência de Service}, to learn
about the other service types shown here.  @xref{system-extension-graph, the
@command{guix system extension-graph} command}, for information on how to
generate this representation for a particular operating system definition.

@cindex service types
Technically, developers can define @dfn{service types} to express these
relations.  There can be any number of services of a given type on the
system, for instance when running two instances with different parameters.

The following section describes the programming interface for service types
and services.

@node Tipos de Service e Serviços
@subsection Tipos de Service e Serviços

A @dfn{service type} is a node in the DAG described above.  Let us start
with a simple example, the service type for the Guix build daemon
(@pxref{Invocando guix-daemon}):

@lisp
(define guix-service-type
  (service-type
   (name 'guix)
   (extensions
    (list (service-extension shepherd-root-service-type guix-shepherd-service)
          (service-extension account-service-type guix-accounts)
          (service-extension activation-service-type guix-activation)))
   (default-value (guix-configuration))))
@end lisp

@noindent
It defines three things:

@enumerate
@item
A name, whose sole purpose is to make inspection and debugging easier.

@item
A list of @dfn{service extensions}, where each extension designates the
target service type and a procedure that, given the parameters of the
service, returns a list of objects to extend the service of that type.

Every service type has at least one service extension.  The only exception
is the @dfn{boot service type}, which is the ultimate service.

@item
Optionally, a default value for instances of this type.
@end enumerate

In this example, @code{guix-service-type} extends three services:

@table @code
@item shepherd-root-service-type
The @code{guix-shepherd-service} procedure defines how the Shepherd service
is extended.  Namely, it returns a @code{<shepherd-service>} object that
defines how @command{guix-daemon} is started and stopped (@pxref{Serviços 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{Invocando guix-daemon}).

@item activation-service-type
Here @code{guix-activation} is a procedure that returns a gexp, which is a
code snippet to run at ``activation time''---e.g., when the service is
booted.
@end table

A service of this type is instantiated like this:

@lisp
(service guix-service-type
         (guix-configuration
           (build-accounts 5)
           (extra-options '("--gc-keep-derivations"))))
@end lisp

The second argument to the @code{service} form is a value representing the
parameters of this specific service instance.
@xref{guix-configuration-type, @code{guix-configuration}}, for information
about the @code{guix-configuration} data type.  When the value is omitted,
the default value specified by @code{guix-service-type} is used:

@lisp
(service guix-service-type)
@end lisp

@code{guix-service-type} is quite simple because it extends other services
but is not extensible itself.

@c @subsubsubsection Extensible Service Types

The service type for an @emph{extensible} service looks like this:

@lisp
(define udev-service-type
  (service-type (name 'udev)
                (extensions
                 (list (service-extension shepherd-root-service-type
                                          udev-shepherd-service)))

                (compose concatenate)       ;concatenate the list of rules
                (extend (lambda (config rules)
                          (udev-configuration
                           (inherit config)
                           (rules (append (udev-configuration-rules config)
                                          rules)))))))
@end lisp

This is the service type for the
@uref{https://github.com/eudev-project/eudev, eudev device management
daemon}.  Compared to the previous example, in addition to an extension of
@code{shepherd-root-service-type}, we see two new fields:

@table @code
@item compose
This is the procedure to @dfn{compose} the list of extensions to services of
this type.

Services can extend the udev service by passing it lists of rules; we
compose those extensions simply by concatenating them.

@item extend
This procedure defines how the value of the service is @dfn{extended} with
the composition of the extensions.

Udev extensions are composed into a list of rules, but the udev service
value is itself a @code{<udev-configuration>} record.  So here, we extend
that record by appending the list of rules it contains to the list of
contributed rules.

@item description
This is a string giving an overview of the service type.  The string can
contain Texinfo markup (@pxref{Overview,,, texinfo, GNU Texinfo}).  The
@command{guix system search} command searches these strings and displays
them (@pxref{Invocando guix system}).
@end table

There can be only one instance of an extensible service type such as
@code{udev-service-type}.  If there were more, the @code{service-extension}
specifications would be ambiguous.

Still here? The next section provides a reference of the programming
interface for services.

@node Referência de Service
@subsection Referência de Service

We have seen an overview of service types (@pxref{Tipos de Service e Serviços}).  This section provides a reference on how to manipulate services
and service types.  This interface is provided by the @code{(gnu services)}
module.

@deffn {Procedure} service type [value]
Return a new service of @var{type}, a @code{<service-type>} object (see
below).  @var{value} can be any object; it represents the parameters of this
particular service instance.

When @var{value} is omitted, the default value specified by @var{type} is
used; if @var{type} does not specify a default value, an error is raised.

For instance, this:

@lisp
(service openssh-service-type)
@end lisp

@noindent
is equivalent to this:

@lisp
(service openssh-service-type
         (openssh-configuration))
@end lisp

In both cases the result is an instance of @code{openssh-service-type} with
the default configuration.
@end deffn

@deffn {Procedure} service? obj
Return true if @var{obj} is a service.
@end deffn

@deffn {Procedure} service-kind service
Return the type of @var{service}---i.e., a @code{<service-type>} object.
@end deffn

@deffn {Procedure} service-value service
Return the value associated with @var{service}.  It represents its
parameters.
@end deffn

Here is an example of how a service is created and manipulated:

@lisp
(define s
  (service nginx-service-type
           (nginx-configuration
            (nginx nginx)
            (log-directory log-directory)
            (run-directory run-directory)
            (file config-file))))

(service? s)
@result{} #t

(eq? (service-kind s) nginx-service-type)
@result{} #t
@end lisp

The @code{modify-services} form provides a handy way to change the
parameters of some of the services of a list such as @code{%base-services}
(@pxref{Serviços básicos, @code{%base-services}}).  It evaluates to a list of
services.  Of course, you could always use standard list combinators such as
@code{map} and @code{fold} to do that (@pxref{SRFI-1, List Library,, guile,
GNU Guile Reference Manual}); @code{modify-services} simply provides a more
concise form for this common pattern.

@defspec modify-services services @
  (type variable => body) @dots{}

Modify the services listed in @var{services} according to the given
clauses.  Each clause has the form:

@example
(@var{type} @var{variable} => @var{body})
@end example

where @var{type} is a service type---e.g., @code{guix-service-type}---and
@var{variable} is an identifier that is bound within the @var{body} to the
service parameters---e.g., a @code{guix-configuration} instance---of the
original service of that @var{type}.

The @var{body} should evaluate to the new service parameters, which will be
used to configure the new service.  This new service will replace the
original in the resulting list.  Because a service's service parameters are
created using @code{define-record-type*}, you can write a succinct
@var{body} that evaluates to the new service parameters by using the
@code{inherit} feature that @code{define-record-type*} provides.

Clauses can also have the following form:

@lisp
(delete @var{type})
@end lisp

Such a clause removes all services of the given @var{type} from
@var{services}.

@xref{Usando o sistema de configuração}, for example usage.

@end defspec

Next comes the programming interface for service types.  This is something
you want to know when writing new service definitions, but not necessarily
when simply looking for ways to customize your @code{operating-system}
declaration.

@deftp {Tipo de dados} service-type
@cindex tipo de serviço
This is the representation of a @dfn{service type} (@pxref{Tipos de Service e Serviços}).

@table @asis
@item @code{name}
This is a symbol, used only to simplify inspection and debugging.

@item @code{extensions}
A non-empty list of @code{<service-extension>} objects (see below).

@item @code{compose} (padrão: @code{#f})
If this is @code{#f}, then the service type denotes services that cannot be
extended---i.e., services that do not receive ``values'' from other
services.

Otherwise, it must be a one-argument procedure.  The procedure is called by
@code{fold-services} and is passed a list of values collected from
extensions.  It may return any single value.

@item @code{extend} (padrão: @code{#f})
If this is @code{#f}, services of this type cannot be extended.

Otherwise, it must be a two-argument procedure: @code{fold-services} calls
it, passing it the initial value of the service as the first argument and
the result of applying @code{compose} to the extension values as the second
argument.  It must return a value that is a valid parameter value for the
service instance.

@item @code{description}
This is a string, possibly using Texinfo markup, describing in a couple of
sentences what the service is about.  This string allows users to find about
the service through @command{guix system search} (@pxref{Invocando guix system}).

@item @code{default-value} (default: @code{&no-default-value})
The default value associated for instances of this service type.  This
allows users to use the @code{service} form without its second argument:

@lisp
(service @var{type})
@end lisp

The returned service in this case has the default value specified by
@var{type}.
@end table

@xref{Tipos de Service e Serviços}, for examples.
@end deftp

@deffn {Procedure} service-extension target-type compute
Return a new extension for services of type @var{target-type}.
@var{compute} must be a one-argument procedure: @code{fold-services} calls
it, passing it the value associated with the service that provides the
extension; it must return a valid value for the target service.
@end deffn

@deffn {Procedure} service-extension? obj
Return true if @var{obj} is a service extension.
@end deffn

Occasionally, you might want to simply extend an existing service.  This
involves creating a new service type and specifying the extension of
interest, which can be verbose; the @code{simple-service} procedure provides
a shorthand for this.

@deffn {Procedure} simple-service name target value
Return a service that extends @var{target} with @var{value}.  This works by
creating a singleton service type @var{name}, of which the returned service
is an instance.

For example, this extends mcron (@pxref{Execução de trabalho agendado}) with an
additional job:

@lisp
(simple-service 'my-mcron-job mcron-service-type
                #~(job '(next-hour (3)) "guix gc -F 2G"))
@end lisp
@end deffn

At the core of the service abstraction lies the @code{fold-services}
procedure, which is responsible for ``compiling'' a list of services down to
a single directory that contains everything needed to boot and run the
system---the directory shown by the @command{guix system build} command
(@pxref{Invocando guix system}).  In essence, it propagates service
extensions down the service graph, updating each node parameters on the way,
until it reaches the root node.

@deffn {Procedure} fold-services services [#:target-type system-service-type]
Fold @var{services} by propagating their extensions down to the root of type
@var{target-type}; return the root service adjusted accordingly.
@end deffn

Lastly, the @code{(gnu services)} module also defines several essential
service types, some of which are listed below.

@defvar system-service-type
This is the root of the service graph.  It produces the system directory as
returned by the @command{guix system build} command.
@end defvar

@defvar boot-service-type
The type of the ``boot service'', which produces the @dfn{boot script}.  The
boot script is what the initial RAM disk runs when booting.
@end defvar

@defvar etc-service-type
The type of the @file{/etc} service.  This service is used to create files
under @file{/etc} and can be extended by passing it name/file tuples such
as:

@lisp
(list `("issue" ,(plain-file "issue" "Welcome!\n")))
@end lisp

In this example, the effect would be to add an @file{/etc/issue} file
pointing to the given file.
@end defvar

@defvar etc-profile-d-service-type
The type of the @file{/etc/profile.d} service.  This service is used to
create files under @file{/etc/profile.d}.  It takes as value a list of
file-like objects, as can be produced with @code{local-file},
@code{plain-file}, etc.  Note that provided files whose file names do not
end with @file{.sh} are @emph{not} added to @file{/etc/profile.d/} and are
silently dropped.  Package objects can also be provided directly to have
their @file{etc/profile.d/*.sh} prefixed files added.  A simple usage may
look like:

@example
(simple-service 'my-important-profile-file etc-profile-d-service-type
                (list (plain-file "youppi.sh" "HOW_IMPORTANT=very")))
@end example
@end defvar

@defvar etc-bashrc-d-service-type
The type of the @file{/etc/bashrc.d} service.  This service is used to
create files under @file{/etc/bashrc.d}.  It takes as value a list of
file-like objects, as can be produced with @code{local-file},
@code{plain-file}, etc.  Note that provided files whose file names do not
end with @file{.sh} are @emph{not} added to @file{/etc/profile.d/} and are
silently dropped.  The default value is made available via the
@var{%default-etc-bashrc-d-files} variable for users to extended.  Package
objects can also be provided directly to have their @file{etc/bashrc.d/*.sh}
prefixed files added.  Since the service is part @code{%base-services}, it
can be extended via @code{simple-service} like so:

@example
(use-package-modules gnome)     ;for the `vte' package

(simple-service 'vte-integration etc-bashrc-d-service-type
                (list (file-append vte "/etc/profile.d/vte.sh")))
@end example
@end defvar

@defvar vte-integration-service-type
This services adds the @file{/etc/bashrc.d/vte.sh} to your system, which
improves the Bash and Zsh experience when using VTE-powered terminal
emulators.  This causes for example the current directory to be displayed in
the terminal emulator's tab title, and the current directory to be preserved
when creating a new tab, among other features.  The value of the service is
the @code{vte} package to use.

@example
(use-package-modules gnome)     ;for the `vte' package

(service vte-integration-service-type vte)
@end example
@end defvar

@defvar privileged-program-service-type
Type for the ``privileged-program service''.  This service collects lists of
executable file names, passed as gexps, and adds them to the set of
privileged programs on the system (@pxref{Privileged Programs}).
@end defvar

@defvar profile-service-type
Type of the service that populates the @dfn{system profile}---i.e., the
programs under @file{/run/current-system/profile}.  Other services can
extend it by passing it lists of packages to add to the system profile.
@end defvar

@cindex provenance tracking, of the operating system
@anchor{provenance-service-type}
@defvar provenance-service-type
This is the type of the service that records @dfn{provenance meta-data} in
the system itself.  It creates several files under
@file{/run/current-system}:

@table @file
@item channels.scm
This is a ``channel file'' that can be passed to @command{guix pull -C} or
@command{guix time-machine -C}, and which describes the channels used to
build the system, if that information was available (@pxref{Canais}).

@item configuration.scm
This is the file that was passed as the value for this
@code{provenance-service-type} service.  By default, @command{guix system
reconfigure} automatically passes the OS configuration file it received on
the command line.

@item provenance
This contains the same information as the two other files but in a format
that is more readily processable.
@end table

In general, these two pieces of information (channels and configuration
file) are enough to reproduce the operating system ``from source''.

@quotation Caveats
This information is necessary to rebuild your operating system, but it is
not always sufficient.  In particular, @file{configuration.scm} itself is
insufficient if it is not self-contained---if it refers to external Guile
modules or to extra files.  If you want @file{configuration.scm} to be
self-contained, we recommend that modules or files it refers to be part of a
channel.

Besides, provenance meta-data is ``silent'' in the sense that it does not
change the bits contained in your system, @emph{except for the meta-data
bits themselves}.  Two different OS configurations or sets of channels can
lead to the same system, bit-for-bit; when @code{provenance-service-type} is
used, these two systems will have different meta-data and thus different
store file names, which makes comparison less trivial.
@end quotation

This service is automatically added to your operating system configuration
when you use @command{guix system reconfigure}, @command{guix system init},
or @command{guix deploy}.
@end defvar

@defvar linux-loadable-module-service-type
Type of the service that collects lists of packages containing
kernel-loadable modules, and adds them to the set of kernel-loadable
modules.

This service type is intended to be extended by other service types, such as
below:

@lisp
(simple-service 'installing-module
                linux-loadable-module-service-type
                (list module-to-install-1
                      module-to-install-2))
@end lisp

This does not actually load modules at bootup, only adds it to the kernel
profile so that it @emph{can} be loaded by other means.
@end defvar

@node Serviços de Shepherd
@subsection Serviços de Shepherd

@cindex shepherd services
@cindex PID 1
@cindex init system
The @code{(gnu services shepherd)} module provides a way to define services
managed by the GNU@tie{}Shepherd, which is the initialization system---the
first process that is started when the system boots, also known as
PID@tie{}1 (@pxref{Introduction,,, shepherd, The GNU Shepherd Manual}).

Services in the Shepherd can depend on each other.  For instance, the SSH
daemon may need to be started after the syslog daemon has been started,
which in turn can only happen once all the file systems have been mounted.
The simple operating system defined earlier (@pxref{Usando o sistema de configuração}) results in a service graph like this:

@image{images/shepherd-graph,,5in,Typical shepherd service graph.}

You can actually generate such a graph for any operating system definition
using the @command{guix system shepherd-graph} command
(@pxref{system-shepherd-graph, @command{guix system shepherd-graph}}).

The @code{%shepherd-root-service} is a service object representing
PID@tie{}1, of type @code{shepherd-root-service-type}; it can be extended by
passing it lists of @code{<shepherd-service>} objects.

@deftp {Tipo de dados} shepherd-service
The data type representing a service managed by the Shepherd.

@table @asis
@item @code{provision}
This is a list of symbols denoting what the service provides.

These are the names that may be passed to @command{herd start},
@command{herd status}, and similar commands (@pxref{Invoking herd,,,
shepherd, The GNU Shepherd Manual}).  @xref{Defining Services,,, shepherd,
The GNU Shepherd Manual}, for details.

@item @code{requirement} (default: @code{'()})
List of symbols denoting the Shepherd services this one depends on.

@cindex @code{user-processes} Shepherd service
With very few exceptions, services that start a daemon must depend at least
on the @code{user-processes} service; this ensures that these daemons are
started after all the file systems have been mounted and that, during
shutdown, they are stopped before attempting to terminate remaining user
processes.

Similarly, services that do make mounts during their startup or operation,
should have @code{user-file-systems} as a requirement. @code{user-processes}
does depend on @code{user-file-systems} as well.  So direct requirement only
on @code{user-processes} is sufficient.

@cindex one-shot services, for the Shepherd
@item @code{one-shot?} (default: @code{#f})
Whether this service is @dfn{one-shot}.  One-shot services stop immediately
after their @code{start} action has completed.  @xref{Slots of services,,,
shepherd, The GNU Shepherd Manual}, for more info.

@item @code{respawn?} (padrão: @code{#t})
Whether to restart the service when it stops, for instance when the
underlying process dies.

@item @code{respawn-limit} (default: @code{#f})
Set a limit on how many times and how frequently a service may be restarted
by Shepherd before it is disabled.  @xref{Defining Services,,, shepherd, The
GNU Shepherd Manual}, for details.

@item @code{respawn-delay} (default: @code{#f})
When true, this is the delay in seconds before restarting a failed service.

@item @code{start} (default: @code{#~(const #t)})
@itemx @code{stop} (default: @code{#~(const #f)})
The @code{start} and @code{stop} fields refer to the Shepherd's facilities
to start and stop processes (@pxref{Service De- and Constructors,,,
shepherd, The GNU Shepherd Manual}).  They are given as G-expressions that
get expanded in the Shepherd configuration file (@pxref{Expressões-G}).

@item @code{actions} (default: @code{'()})
@cindex actions, of Shepherd services
This is a list of @code{shepherd-action} objects (see below) defining
@dfn{actions} supported by the service, in addition to the standard
@code{start} and @code{stop} actions.  Actions listed here become available
as @command{herd} sub-commands:

@example
herd @var{action} @var{service} [@var{arguments}@dots{}]
@end example

@item @code{free-form} (default: @code{#f})
When set, this field replaces the @code{start}, @code{stop}, and
@code{actions} fields.  It is meant to be used when the service definition
comes from some other source, typically the service collection provided by
the Shepherd proper (@pxref{Service Collection,,, shepherd, The GNU Shepherd
Manual}).

@cindex REPL service, for shepherd
For example, the snippet below defines a service for the Shepherd's built-in
@acronym{REPL, read-eval-print loop} service (@pxref{REPL Service,,,
shepherd, The GNU Shepherd Manual}):

@lisp
(shepherd-service
  (provision '(repl))
  (modules '((shepherd service repl)))
  (free-form #~(repl-service)))
@end lisp

In this case, the service object is returned by the @code{repl-service}
procedure of the Shepherd, so all the @code{free-form} G-expression does is
call that procedure.  Note that the @code{provision} field must be
consistent with the actual service provision.

@item @code{auto-start?} (default: @code{#t})
Whether this service should be started automatically by the Shepherd.  If it
is @code{#f} the service has to be started manually with @code{herd start}.

@item @code{documentation}
A documentation string, as shown when running:

@example
herd doc @var{service-name}
@end example

where @var{service-name} is one of the symbols in @code{provision}
(@pxref{Invoking herd,,, shepherd, The GNU Shepherd Manual}).

@item @code{modules} (default: @code{%default-modules})
This is the list of modules that must be in scope when @code{start} and
@code{stop} are evaluated.

@end table
@end deftp

The example below defines a Shepherd service that spawns @command{syslogd},
the system logger from the GNU Networking Utilities (@pxref{syslogd invocation, @command{syslogd},, inetutils, GNU Inetutils}):

@example
(let ((config (plain-file "syslogd.conf" "@dots{}")))
  (shepherd-service
    (documentation "Run the syslog daemon (syslogd).")
    (provision '(syslogd))
    (requirement '(user-processes))
    (start #~(make-forkexec-constructor
               (list #$(file-append inetutils "/libexec/syslogd")
                     "--rcfile" #$config)
               #:pid-file "/var/run/syslog.pid"))
    (stop #~(make-kill-destructor))))
@end example

Key elements in this example are the @code{start} and @code{stop} fields:
they are @dfn{staged} code snippets that use the
@code{make-forkexec-constructor} procedure provided by the Shepherd and its
dual, @code{make-kill-destructor} (@pxref{Service De- and Constructors,,,
shepherd, The GNU Shepherd Manual}).  The @code{start} field will have
@command{shepherd} spawn @command{syslogd} with the given option; note that
we pass @code{config} after @option{--rcfile}, which is a configuration file
declared above (contents of this file are omitted).  Likewise, the
@code{stop} field tells how this service is to be stopped; in this case, it
is stopped by making the @code{kill} system call on its PID@.  Code staging
is achieved using G-expressions: @code{#~} stages code, while @code{#$}
``escapes'' back to host code (@pxref{Expressões-G}).

@deftp {Tipo de dados} shepherd-action
This is the data type that defines additional actions implemented by a
Shepherd service (see above).

@table @code
@item name
Symbol naming the action.

@item documentation
This is a documentation string for the action.  It can be viewed by running:

@example
herd doc @var{service} action @var{action}
@end example

@item procedure
This should be a gexp that evaluates to a procedure of at least one
argument, which is the ``running value'' of the service (@pxref{Slots of
services,,, shepherd, The GNU Shepherd Manual}).
@end table

The following example defines an action called @code{say-hello} that kindly
greets the user:

@lisp
(shepherd-action
  (name 'say-hello)
  (documentation "Say hi!")
  (procedure #~(lambda (running . args)
                 (format #t "Hello, friend! arguments: ~s\n"
                         args)
                 #t)))
@end lisp

Assuming this action is added to the @code{example} service, then you can
do:

@example
# herd say-hello example
Hello, friend! arguments: ()
# herd say-hello example a b c
Hello, friend! arguments: ("a" "b" "c")
@end example

This, as you can see, is a fairly sophisticated way to say hello.
@xref{Defining Services,,, shepherd, The GNU Shepherd Manual}, for more info
on actions.
@end deftp

@cindex configuration file, of Shepherd services
@deffn {Procedure} shepherd-configuration-action
Return a @code{configuration} action to display @var{file}, which should be
the name of the service's configuration file.

It can be useful to equip services with that action.  For example, the
service for the Tor anonymous router (@pxref{Serviços de Rede,
@code{tor-service-type}}) is defined roughly like this:

@lisp
(let ((torrc (plain-file "torrc" @dots{})))
  (shepherd-service
    (provision '(tor))
    (requirement '(user-processes loopback syslogd))

    (start #~(make-forkexec-constructor
              (list #$(file-append tor "/bin/tor") "-f" #$torrc)
              #:user "tor" #:group "tor"))
    (stop #~(make-kill-destructor))
    (actions (list (shepherd-configuration-action torrc)))
    (documentation "Run the Tor anonymous network overlay.")))
@end lisp

Thanks to this action, administrators can inspect the configuration file
passed to @command{tor} with this shell command:

@example
cat $(herd configuration tor)
@end example

This can come in as a handy debugging tool!
@end deffn

@defvar shepherd-root-service-type
The service type for the Shepherd ``root service''---i.e., PID@tie{}1.

This is the service type that extensions target when they want to create
shepherd services (@pxref{Tipos de Service e Serviços}, for an example).
Each extension must pass a list of @code{<shepherd-service>}.  Its value
must be a @code{shepherd-configuration}, as described below.
@end defvar

@deftp {Tipo de dados} shepherd-configuration
This data type represents the Shepherd's configuration.

@table @code
@item shepherd (default: @code{shepherd})
The Shepherd package to use.

@item services (default: @code{'()})
A list of @code{<shepherd-service>} to start.  You should probably use the
service extension mechanism instead (@pxref{Serviços de Shepherd}).
@end table
@end deftp

The following example specifies the Shepherd package for the operating
system:

@lisp
(operating-system
  ;; ...
  (services (append (list openssh-service-type))
            ;; ...
            %desktop-services)
  ;; ...
  ;; Use own Shepherd package.
  (essential-services
   (modify-services (operating-system-default-essential-services
                     this-operating-system)
     (shepherd-root-service-type config => (shepherd-configuration
                                            (inherit config)
                                            (shepherd my-shepherd))))))
@end lisp

@anchor{shepherd-transient-timer-services}
@cindex @code{transient} service, Shepherd
@defvar shepherd-transient-service-type
This service type represents the Shepherd's @code{transient} service, which
lets you spawn commands in the background and interact with them as regular
Shepherd services; it is similar to @command{systemd-run}.

For example, the command below spawns @command{rsync} in the background, in
an environment where the @env{SSH_AUTH_SOCK} environment variable has the
given value:

@example
herd spawn transient -E SSH_AUTH_SOCK=$SSH_AUTH_SOCK -- \
  rsync -e ssh -vur . backup.example.org:
@end example

@xref{Transient Service Maker,,, shepherd, The GNU Shepherd Manual}, for
more info on the @code{transient} service.
@end defvar

@cindex @code{timer} service, Shepherd
@defvar shepherd-timer-service-type
This is the service type representing the Shepherd's @code{timer} service,
which lets you schedule the execution of commands, similar to the venerable
@command{at} command.  Here is an example:

@example
herd schedule timer at 07:00 -- mpg123 Music/alarm.mp3
@end example

@xref{Timer Service,,, shepherd, The GNU Shepherd Manual}, for more info on
the @code{timer} service.
@end defvar

@anchor{shepherd-system-log}
@cindex system log service, from Shepherd
@cindex syslogd, Shepherd system log service
@defvar shepherd-system-log-service-type
This service implements a @dfn{system log}, reading messages applications
send to @file{/dev/log} and writing them to files or terminals according to
user-defined rules.  It provides functionality traditionally implemented by
@command{syslogd} programs.

The value of services of this type must be a @code{system-log-configuration}
record, as described below.

This service is part of @code{%base-services} (@pxref{Serviços básicos}).
@end defvar

@c %start of fragment

@deftp {Data Type} system-log-configuration
Available @code{system-log-configuration} fields are:

@table @asis
@item @code{provision} (default: @code{(system-log syslogd)}) (type: list-of-symbols)
The name(s) of the system log service.

@item @code{requirement} (default: @code{(root-file-system)}) (type: list-of-symbols)
Dependencies of the system log service.

@item @code{kernel-log-file} (type: gexp-or-string-or-false)
File from which kernel messages are read, @file{/dev/kmsg} by default.

@item @code{message-destination} (default: @code{#f}) (type: gexp-or-false)
This gexp must evaluate to a procedure that, when passed a log message,
returns the list of files to write it to; @code{#f} is equivalent to using
@code{(default-message-destination-procedure)}.  @xref{System Log
Service,,,shepherd,The GNU Shepherd Manual}, for information on how to write
that procedure.

@item @code{date-format} (type: gexp-or-string)
String or string-valued gexp specifying how to format timestamps in log
files.  It must be a valid string for @code{strftime} (@pxref{Time,,,
guile,GNU Guile Reference Manual}), including delimiting space---e.g.,
@code{"%c "} for a format identical to that of traditional syslogd
implementations.

@item @code{history-size} (type: gexp-or-integer)
Number of logging messages kept in memory for the purposes of making them
available to @command{herd status system-log}.

@item @code{max-silent-time} (type: gexp-or-integer-or-false)
Time after which a mark is written to log files if nothing was logged during
that time frame.  When set to @code{#f}, this feature is disabled.

@end table

@end deftp


@c %end of fragment

@defvar %shepherd-root-service
This service represents PID@tie{}1.
@end defvar

@node Complex Configurations
@subsection Complex Configurations
@cindex complex configurations
Some programs might have rather complex configuration files or formats, and
to make it easier to create Scheme bindings for these configuration files,
you can use the utilities defined in the @code{(gnu services configuration)}
module.

The main utility is the @code{define-configuration} macro, a helper used to
define a Scheme record type (@pxref{Record Overview,,, guile, GNU Guile
Reference Manual}).  The fields from this Scheme record can be serialized
using @dfn{serializers}, which are procedures that take some kind of Scheme
value and translates them into another Scheme value or @ref{Expressões-G}.

@defmac define-configuration name clause1 clause2 @dots{}
Create a record type named @code{@var{name}} that contains the fields found
in the clauses.

A clause has the following form:

@example
(@var{field-name}
 @var{type-decl}
 @var{documentation}
 @var{option*}
 @dots{})
@end example

@var{field-name} is an identifier that denotes the name of the field in the
generated record.

@var{type-decl} is either @code{@var{type}} for fields that require a value
to be set or @code{(@var{type} @var{default-value})} otherwise.

@var{type} is the type of the value corresponding to @var{field-name}; since
Guile is untyped, a predicate procedure---@code{@var{type}?}---will be
called on the value corresponding to the field to ensure that the value is
of the correct type.  This means that if say, @var{type} is @code{package},
then a procedure named @code{package?} will be applied on the value to make
sure that it is indeed a @code{<package>} object.

@var{default-value} is the default value corresponding to the field; if none
is specified, the user is forced to provide a value when creating an object
of the record type.

@c XXX: Should these be full sentences or are they allow to be very
@c short like package synopses?
@var{documentation} is a string formatted with Texinfo syntax which should
provide a description of what setting this field does.

@var{option*} is one of the following subclauses:

@table @asis
@item @code{empty-serializer}
Exclude this field from serialization.

@item @code{(serializer @var{serializer})}
@var{serializer} is the name of a procedure which takes two arguments, the
first is the name of the field, and the second is the value corresponding to
the field.  The procedure should return a string or @ref{Expressões-G} that
represents the content that will be serialized to the configuration file.
If none is specified, a procedure of the name @code{serialize-@var{type}}
will be used.

An example of a simple serializer procedure:
@lisp
(define (serialize-boolean field-name value)
  (let ((value (if value "true" "false")))
    #~(string-append '#$field-name " = " #$value)))
@end lisp

@item @code{(sanitizer @var{sanitizer})}
@var{sanitizer} is a procedure which takes one argument, a user-supplied
value, and returns a ``sanitized'' value for the field.  If no sanitizer is
specified, a default sanitizer is used, which raises an error if the value
is not of type @var{type}.

An example of a sanitizer for a field that accepts both strings and symbols
looks like this:
@lisp
(define (sanitize-foo value)
  (cond ((string? value) value)
        ((symbol? value) (symbol->string value))
        (else (error "bad value"))))
@end lisp
@end table

In some cases multiple different configuration records might be defined in
the same file, but their serializers for the same type might have to be
different, because they have different configuration formats.  For example,
the @code{serialize-boolean} procedure for the Getmail service would have to
be different from the one for the Transmission service.  To make it easier
to deal with this situation, one can specify a serializer prefix by using
the @code{prefix} literal in the @code{define-configuration} form.  This
means that one doesn't have to manually specify a custom @var{serializer}
for every field.

@lisp
(define (foo-serialize-string field-name value)
  @dots{})

(define (bar-serialize-string field-name value)
  @dots{})

(define-configuration foo-configuration
  (label
   string
   "The name of label.")
  (prefix foo-))

(define-configuration bar-configuration
  (ip-address
   string
   "The IPv4 address for this device.")
  (prefix bar-))
@end lisp

However, in some cases you might not want to serialize any of the values of
the record, to do this, you can use the @code{no-serialization} literal.
There is also the @code{define-configuration/no-serialization} macro which
is a shorthand of this.

@lisp
;; Nothing will be serialized to disk.
(define-configuration foo-configuration
  (field
   (string "test")
   "Some documentation.")
  (no-serialization))

;; The same thing as above.
(define-configuration/no-serialization bar-configuration
  (field
   (string "test")
   "Some documentation."))
@end lisp
@end defmac

@defmac define-maybe type
Sometimes a field should not be serialized if the user doesn’t specify a
value.  To achieve this, you can use the @code{define-maybe} macro to define
a ``maybe type''; if the value of a maybe type is left unset, or is set to
the @code{%unset-value} value, then it will not be serialized.

When defining a ``maybe type'', the corresponding serializer for the regular
type will be used by default.  For example, a field of type
@code{maybe-string} will be serialized using the @code{serialize-string}
procedure by default, you can of course change this by specifying a custom
serializer procedure.  Likewise, the type of the value would have to be a
string, or left unspecified.

@lisp
(define-maybe string)

(define (serialize-string field-name value)
  @dots{})

(define-configuration baz-configuration
  (name
   ;; If set to a string, the `serialize-string' procedure will be used
   ;; to serialize the string.  Otherwise this field is not serialized.
   maybe-string
   "The name of this module."))
@end lisp

Like with @code{define-configuration}, one can set a prefix for the
serializer name by using the @code{prefix} literal.

@lisp
(define-maybe integer
  (prefix baz-))

(define (baz-serialize-integer field-name value)
  @dots{})
@end lisp

There is also the @code{no-serialization} literal, which when set means that
no serializer will be defined for the ``maybe type'', regardless of whether
its value is set or not.  @code{define-maybe/no-serialization} is a
shorthand for specifying the @code{no-serialization} literal.

@lisp
(define-maybe/no-serialization symbol)

(define-configuration/no-serialization test-configuration
  (mode
   maybe-symbol
   "Docstring."))
@end lisp
@end defmac

@deffn {Procedure} maybe-value-set? value
Predicate to check whether a user explicitly specified the value of a maybe
field.
@end deffn

@deffn {Procedure} serialize-configuration configuration fields
Return a G-expression that contains the values corresponding to the
@var{fields} of @var{configuration}, a record that has been generated by
@code{define-configuration}.  The G-expression can then be serialized to
disk by using something like @code{mixed-text-file}.
@end deffn

Once you have defined a configuration record, you will most likely also want
to document it so that other people know to use it.  To help with that,
there are two procedures, both of which are documented below.

@deffn {Procedure} generate-documentation documentation documentation-name
Generate a Texinfo fragment from the docstrings in @var{documentation}, a
list of @code{(@var{label} @var{fields} @var{sub-documentation} ...)}.
@var{label} should be a symbol and should be the name of the configuration
record.  @var{fields} should be a list of all the fields available for the
configuration record.

@var{sub-documentation} is a @code{(@var{field-name}
@var{configuration-name})} tuple.  @var{field-name} is the name of the field
which takes another configuration record as its value, and
@var{configuration-name} is the name of that configuration record.  The same
value may be used for multiple @var{field-name}s, in case a field accepts
different types of configurations.

@var{sub-documentation} is only needed if there are nested configuration
records.  For example, the @code{getmail-configuration} record (@pxref{Serviços de correio}) accepts a @code{getmail-configuration-file} record in one of its
@code{rcfile} field, therefore documentation for
@code{getmail-configuration-file} is nested in @code{getmail-configuration}.

@lisp
(generate-documentation
  `((getmail-configuration ,getmail-configuration-fields
     (rcfile getmail-configuration-file))
    @dots{})
  'getmail-configuration)
@end lisp

@var{documentation-name} should be a symbol and should be the name of the
configuration record.

@end deffn

@deffn {Procedure} configuration->documentation configuration-symbol
Take @var{configuration-symbol}, the symbol corresponding to the name used
when defining a configuration record with @code{define-configuration}, and
print the Texinfo documentation of its fields.  This is useful if there
aren’t any nested configuration records since it only prints the
documentation for the top-level fields.
@end deffn

As of right now, there is no automated way to generate documentation for
configuration records and put them in the manual.  Instead, every time you
make a change to the docstrings of a configuration record, you have to
manually call @code{generate-documentation} or
@code{configuration->documentation}, and paste the output into the
@file{doc/guix.texi} file.

@c TODO: Actually test this
Below is an example of a record type created using
@code{define-configuration} and friends.

@lisp
(use-modules (gnu services)
             (guix gexp)
             (gnu services configuration)
             (srfi srfi-26)
             (srfi srfi-1))

;; Turn field names, which are Scheme symbols into strings
(define (uglify-field-name field-name)
  (let ((str (symbol->string field-name)))
    ;; field? -> is-field
    (if (string-suffix? "?" str)
        (string-append "is-" (string-drop-right str 1))
        str)))

(define (serialize-string field-name value)
  #~(string-append #$(uglify-field-name field-name) " = " #$value "\n"))

(define (serialize-integer field-name value)
  (serialize-string field-name (number->string value)))

(define (serialize-boolean field-name value)
  (serialize-string field-name (if value "true" "false")))

(define (serialize-contact-name field-name value)
  #~(string-append "\n[" #$value "]\n"))

(define (list-of-contact-configurations? lst)
  (every contact-configuration? lst))

(define (serialize-list-of-contact-configurations field-name value)
  #~(string-append #$@@(map (cut serialize-configuration <>
                                contact-configuration-fields)
                           value)))

(define (serialize-contacts-list-configuration configuration)
  (mixed-text-file
   "contactrc"
   #~(string-append "[Owner]\n"
                    #$(serialize-configuration
                       configuration contacts-list-configuration-fields))))

(define-maybe integer)
(define-maybe string)

(define-configuration contact-configuration
  (name
   string
   "The name of the contact."
   serialize-contact-name)
  (phone-number
   maybe-integer
   "The person's phone number.")
  (email
   maybe-string
   "The person's email address.")
  (married?
   boolean
   "Whether the person is married."))

(define-configuration contacts-list-configuration
  (name
   string
   "The name of the owner of this contact list.")
  (email
   string
   "The owner's email address.")
  (contacts
   (list-of-contact-configurations '())
   "A list of @@code@{contact-configuration@} records which contain
information about all your contacts."))
@end lisp

A contacts list configuration could then be created like this:

@lisp
(define my-contacts
  (contacts-list-configuration
   (name "Alice")
   (email "alice@@example.org")
   (contacts
    (list (contact-configuration
           (name "Bob")
           (phone-number 1234)
           (email "bob@@gnu.org")
           (married? #f))
          (contact-configuration
           (name "Charlie")
           (phone-number 0000)
           (married? #t))))))
@end lisp

After serializing the configuration to disk, the resulting file would look
like this:

@example
[owner]
name = Alice
email = alice@@example.org

[Bob]
phone-number = 1234
email = bob@@gnu.org
is-married = false

[Charlie]
phone-number = 0
is-married = true
@end example


@c *********************************************************************
@cindex troubleshooting, Guix System
@cindex guix system troubleshooting
@node Dicas para solução de problemas do sistema
@chapter Dicas para solução de problemas do sistema

Guix System allows rebooting into a previous generation should the last one
be malfunctioning, which makes it quite robust against being broken
irreversibly.  This feature depends on GRUB being correctly functioning
though, which means that if for whatever reasons your GRUB installation
becomes corrupted during a system reconfiguration, you may not be able to
easily boot into a previous generation.  A technique that can be used in
this case is to @i{chroot} into your broken system and reconfigure it from
there.  Such technique is explained below.

@cindex chroot, guix system
@cindex chrooting, guix system
@cindex repairing GRUB, via chroot
@menu
* Acessando um sistema existente via chroot::  Acessando um sistema 
                                                 existente via chroot
@end menu

@node Acessando um sistema existente via chroot
@section Acessando um sistema existente via chroot

This section details how to @i{chroot} to an already installed Guix System
with the aim of reconfiguring it, for example to fix a broken GRUB
installation.  The process is similar to how it would be done on other
GNU/Linux systems, but there are some Guix System particularities such as
the daemon and profiles that make it worthy of explaining here.

@enumerate
@item
Obtain a bootable image of Guix System.  It is recommended the latest
development snapshot so the kernel and the tools used are at least as as new
as those of your installed system; it can be retrieved from the
@url{https://ci.guix.gnu.org/search/latest/ISO-9660?query=spec:images+status:success+system:x86_64-linux+image.iso,
https://ci.guix.gnu.org} URL.  Follow the @pxref{Instalação em um pendrive e em DVD} section for copying it to a bootable media.

@item
Boot the image, and proceed with the graphical text-based installer until
your network is configured.  Alternatively, you could configure the network
manually by following the @ref{manual-installation-networking} section.  If
you get the error @samp{RTNETLINK answers: Operation not possible due to
RF-kill}, try @samp{rfkill list} followed by @samp{rfkill unblock 0}, where
@samp{0} is your device identifier (ID).

@item
Switch to a virtual console (tty) if you haven't already by pressing
simultaneously the @kbd{Control + Alt + F4} keys.  Mount your file system at
@file{/mnt}.  Assuming your root partition is @file{/dev/sda2}, you would
do:

@example sh
mount /dev/sda2 /mnt
@end example

@item
Mount special block devices and Linux-specific directories:

@example sh
mount --rbind /proc /mnt/proc
mount --rbind /sys /mnt/sys
mount --rbind /dev /mnt/dev
@end example

If your system is EFI-based, you must also mount the ESP partition.
Assuming it is @file{/dev/sda1}, you can do so with:

@example sh
mount /dev/sda1 /mnt/boot/efi
@end example

@item
Enter your system via chroot:

@example sh
chroot /mnt /bin/sh
@end example

@item
Source the system profile as well as your @var{user} profile to setup the
environment, where @var{user} is the user name used for the Guix System you
are attempting to repair:

@example sh
source /var/guix/profiles/system/profile/etc/profile
source /home/@var{user}/.guix-profile/etc/profile
@end example

To ensure you are working with the Guix revision you normally would as your
normal user, also source your current Guix profile:

@example sh
source /home/@var{user}/.config/guix/current/etc/profile
@end example

@item
Start a minimal @command{guix-daemon} in the background:

@example sh
guix-daemon --build-users-group=guixbuild --disable-chroot &
@end example

@item
Edit your Guix System configuration if needed, then reconfigure with:

@example sh
guix system reconfigure your-config.scm
@end example

@item
Finally, you should be good to reboot the system to test your fix.

@end enumerate

@node Home Configuration
@chapter Home Configuration
@cindex Configuração pessoal
@c Maybe later, it will be possible to make home configuration a part of
@c system configuration to make everything managed by guix system.
Guix supports declarative configuration of @dfn{home environments} by
utilizing the configuration mechanism described in the previous chapter
(@pxref{Definindo serviços}), but for user's dotfiles and packages.  It works
both on Guix System and foreign distros and allows users to declare all the
packages and services that should be installed and configured for the user.
Once a user has written a file containing a @code{home-environment} record,
such a configuration can be @dfn{instantiated} by an unprivileged user with
the @command{guix home} command (@pxref{Invocando guix home}).

The user's home environment usually consists of three basic parts: software,
configuration, and state.  Software in mainstream distros are usually
installed system-wide, but with GNU Guix most software packages can be
installed on a per-user basis without needing root privileges, and are thus
considered part of the user’s @dfn{home environment}.  Packages on their own
are not very useful in many cases, because often they require some
additional configuration, usually config files that reside in
@env{XDG_CONFIG_HOME} (@file{~/.config} by default) or other directories.
Everything else can be considered state, like media files, application
databases, and logs.

Usar o Guix para gerenciar seu ambiente pessoal traz várias vantagens.

@itemize

@item All software can be configured in one language (Guile Scheme),
this gives users the ability to share values between configurations of
different programs.

@item A well-defined home environment is self-contained and can be
created in a declarative and reproducible way---there is no need to grab
external binaries or manually edit some configuration file.

@item After every @command{guix home reconfigure} invocation, a new home
environment generation will be created.  This means that users can rollback
to a previous home environment generation so they don’t have to worry about
breaking their configuration.

@item It is possible to manage stateful data with Guix Home, this
includes the ability to automatically clone Git repositories on the initial
setup of the machine, and periodically running commands like @command{rsync}
to sync data with another host.  This functionality is still in an
experimental stage, though.

@end itemize

@menu
* Declarando o ambiente pessoal::  Personalizando seu ambiente pessoal.
* Configurando o "Shell"::   Habilitando o ambiente pessoal.
* Serviços pessoais::        Especificando serviços pessoais.
* Invocando guix home::      Inicializando uma configuração pessoal.
@end menu

@node Declarando o ambiente pessoal
@section Declarando o ambiente pessoal
The home environment is configured by providing a @code{home-environment}
declaration in a file that can be passed to the @command{guix home} command
(@pxref{Invocando guix home}).  The easiest way to get started is by
generating an initial configuration with @command{guix home import}:

@example
guix home import ~/src/guix-config
@end example

The @command{guix home import} command reads some of the ``dot files'' such
as @file{~/.bashrc} found in your home directory and copies them to the
given directory, @file{~/src/guix-config} in this case; it also reads the
contents of your profile, @file{~/.guix-profile}, and, based on that, it
populates @file{~/src/guix-config/home-configuration.scm} with a Home
configuration that resembles your current configuration.

A simple setup can include Bash and a custom text configuration, like in the
example below.  Don't be afraid to declare home environment parts, which
overlaps with your current dot files: before installing any configuration
files, Guix Home will back up existing config files to a separate place in
the home directory.

@quotation Nota
It is highly recommended that you manage your shell or shells with Guix
Home, because it will make sure that all the necessary scripts are sourced
by the shell configuration file.  Otherwise you will need to do it
manually. (@pxref{Configurando o "Shell"}).
@end quotation

@findex home-environment
@vindex %base-home-services
@lisp
@include he-config-bare-bones.scm
@end lisp

The @code{packages} field should be self-explanatory, it will install the
list of packages into the user's profile.  The most important field is
@code{services}, it contains a list of @dfn{home services}, which are the
basic building blocks of a home environment.

There is no daemon (at least not necessarily) related to a home service, a
home service is just an element that is used to declare part of home
environment and extend other parts of it.  The extension mechanism discussed
in the previous chapter (@pxref{Definindo serviços}) should not be confused
with Shepherd services (@pxref{Serviços de Shepherd}).  Using this extension
mechanism and some Scheme code that glues things together gives the user the
freedom to declare their own, very custom, home environments.

@cindex container, for @command{guix home}
Once the configuration looks good, you can first test it in a throw-away
``container'':

@example
guix home container config.scm
@end example

The command above spawns a shell where your home environment is running.
The shell runs in a container, meaning it's isolated from the rest of the
system, so it's a good way to try out your configuration---you can see if
configuration bits are missing or misbehaving, if daemons get started, and
so on.  Once you exit that shell, you're back to the prompt of your original
shell ``in the real world''.

Once you have a configuration file that suits your needs, you can
reconfigure your home by running:

@example
guix home reconfigure config.scm
@end example

This ``builds'' your home environment and creates @file{~/.guix-home}
pointing to it.  Voilà!

@quotation Nota
Make sure the operating system has elogind, systemd, or a similar mechanism
to create the XDG run-time directory and has the @env{XDG_RUNTIME_DIR}
variable set.  Failing that, the @file{on-first-login} script will not
execute anything, and processes like user Shepherd and its descendants will
not start.
@end quotation

If you're using Guix System, you can embed your home configuration in your
system configuration such that @command{guix system reconfigure} will deploy
both the system @emph{and} your home at once! @xref{guix-home-service-type,
@code{guix-home-service-type}}, for how to do that.

@node Configurando o "Shell"
@section Configurando o "Shell"
This section is safe to skip if your shell or shells are managed by Guix
Home.  Otherwise, read it carefully.

There are a few scripts that must be evaluated by a login shell to activate
the home environment.  The shell startup files only read by login shells
often have @code{profile} suffix.  For more information about login shells
see @ref{Invoking Bash,,, bash, The GNU Bash Reference Manual} and see
@ref{Bash Startup Files,,, bash, The GNU Bash Reference Manual}.

The first script that needs to be sourced is @file{setup-environment}, which
sets all the necessary environment variables (including variables declared
by the user) and the second one is @file{on-first-login}, which starts
Shepherd for the current user and performs actions declared by other home
services that extends @code{home-run-on-first-login-service-type}.

Guix Home will always create @file{~/.profile}, which contains the following
lines:

@example
HOME_ENVIRONMENT=$HOME/.guix-home
. $HOME_ENVIRONMENT/setup-environment
$HOME_ENVIRONMENT/on-first-login
@end example

This makes POSIX compliant login shells activate the home environment.
However, in most cases this file won't be read by most modern shells,
because they are run in non POSIX mode by default and have their own
@file{*profile} startup files.  For example Bash will prefer
@file{~/.bash_profile} in case it exists and only if it doesn't will it
fallback to @file{~/.profile}.  Zsh (if no additional options are specified)
will ignore @file{~/.profile}, even if @file{~/.zprofile} doesn't exist.

To make your shell respect @file{~/.profile}, add @code{. ~/.profile} or
@code{source ~/.profile} to the startup file for the login shell.  In case
of Bash, it is @file{~/.bash_profile}, and in case of Zsh, it is
@file{~/.zprofile}.

@quotation Nota
This step is only required if your shell is @emph{not} managed by Guix
Home.  Otherwise, everything will be done automatically.
@end quotation

@node Serviços pessoais
@section Serviços pessoais
@cindex serviços pessoais

A @dfn{home service} is not necessarily something that has a daemon and is
managed by Shepherd (@pxref{Jump Start,,, shepherd, The GNU Shepherd
Manual}), in most cases it doesn't.  It's a simple building block of the
home environment, often declaring a set of packages to be installed in the
home environment profile, a set of config files to be symlinked into
@env{XDG_CONFIG_HOME} (@file{~/.config} by default), and environment
variables to be set by a login shell.

There is a service extension mechanism (@pxref{Composição de serviço})  which
allows home services to extend other home services and utilize capabilities
they provide; for example: declare mcron jobs (@pxref{Top,,, mcron,
GNU@tie{}Mcron}) by extending @ref{Mcron Home Service}; declare daemons by
extending @ref{Shepherd Home Service}; add commands, which will be invoked
on by the Bash by extending @ref{Shells Home Services,
@code{home-bash-service-type}}.

A good way to discover available home services is using the @command{guix
home search} command (@pxref{Invocando guix home}).  After the required home
services are found, include its module with the @code{use-modules} form
(@pxref{use-modules,, Using Guile Modules, guile, The GNU Guile Reference
Manual}), or the @code{#:use-modules} directive (@pxref{define-module,,
Creating Guile Modules, guile, The GNU Guile Reference Manual}) and declare
a home service using the @code{service} function, or extend a service type
by declaring a new service with the @code{simple-service} procedure from
@code{(gnu services)}.

@menu
* Serviços essenciais pessoais::  Variáveis de ambiente, pacotes, scripts 
                                    on-*.
* Shells: Shells Home Services.  POSIX shells, Bash, Zsh.
* Mcron: Mcron Home Service.  Execução de trabalho do Usuário agendado.
* Power Management: Power Management Home Services.  Services for battery 
                                                       power.
* Shepherd: Shepherd Home Service.  Managing User's Daemons.
* SSH: Secure Shell.         Configurando o cliente de shell seguro.
* GPG: GNU Privacy Guard.    Configurando GPG e ferramentas relacionadas.
* Desktop: Desktop Home Services.  Serviços para ambientes gráficos.
* Guix: Guix Home Services.  Services for Guix.
* Backup: Backup Home Services.  Services for backing up User's files.
* Fonts: Fonts Home Services.  Services for managing User's fonts.
* Sound: Sound Home Services.  Lidando com áudio.
* Mail: Mail Home Services.  Services for managing mail.
* Messaging: Messaging Home Services.  Services for managing messaging.
* Media: Media Home Services.  Services for managing media.
* Niri: Niri window manager.  Setting up the Niri.
* Sway: Gerenciador de janelas Sway.  Setting up the Sway configuration.
* Networking: Networking Home Services.  Networking services.
* Secrets: Secrets Home Services.  Services for storing secrets.
* Miscellaneous: Miscellaneous Home Services.  More services.
@end menu
@c In addition to that Home Services can provide

@node Serviços essenciais pessoais
@subsection Serviços essenciais pessoais
There are a few essential home services defined in @code{(gnu home
services)}, they are mostly for internal use and are required to build a
home environment, but some of them will be useful for the end user.

@cindex environment variables

@defvar home-environment-variables-service-type
The service of this type will be instantiated by every home environment
automatically by default, there is no need to define it, but someone may
want to extend it with a list of pairs to set some environment variables.

@lisp
(list ("ENV_VAR1" . "value1")
      ("ENV_VAR2" . "value2"))
@end lisp

The easiest way to extend a service type, without defining a new service
type is to use the @code{simple-service} helper from @code{(gnu services)}.

@findex literal-string
@lisp
(simple-service 'some-useful-env-vars-service
		home-environment-variables-service-type
		`(("LESSHISTFILE" . "$XDG_CACHE_HOME/.lesshst")
                  ("SHELL" . ,(file-append zsh "/bin/zsh"))
                  ("USELESS_VAR" . #f)
                  ("_JAVA_AWT_WM_NONREPARENTING" . #t)
                  ("LITERAL_VALUE" . ,(literal-string "$@{abc@}"))))
@end lisp

If you include such a service in you home environment definition, it will
add the following content to the @file{setup-environment} script (which is
expected to be sourced by the login shell):

@example
export LESSHISTFILE="$XDG_CACHE_HOME/.lesshst"
export SHELL="/gnu/store/2hsg15n644f0glrcbkb1kqknmmqdar03-zsh-5.8/bin/zsh"
export _JAVA_AWT_WM_NONREPARENTING
export LITERAL_VALUE='$@{abc@}'
@end example

Notice that @code{literal-string} above lets us declare that a value is to
be interpreted as a @dfn{literal string}, meaning that ``special
characters'' such as the dollar sign will not be interpreted by the shell.

@quotation Nota
Make sure that module @code{(gnu packages shells)} is imported with
@code{use-modules} or any other way, this namespace contains the definition
of the @code{zsh} package, which is used in the example above.
@end quotation

The association list (@pxref{Association Lists, alists, Association Lists,
guile, The GNU Guile Reference manual}) is a data structure containing
key-value pairs, for @code{home-environment-variables-service-type} the key
is always a string, the value can be a string, string-valued gexp
(@pxref{Expressões-G}), file-like object (@pxref{Expressões-G, file-like
object}) or boolean.  For gexps, the variable will be set to the value of
the gexp; for file-like objects, it will be set to the path of the file in
the store (@pxref{O armazém}); for @code{#t}, it will export the variable
without any value; and for @code{#f}, it will omit variable.

@end defvar

@defvar home-profile-service-type
The service of this type will be instantiated by every home environment
automatically, there is no need to define it, but you may want to extend it
with a list of packages if you want to install additional packages into your
profile.  Other services, which need to make some programs available to the
user will also extend this service type.

The extension value is just a list of packages:

@lisp
(list htop vim emacs)
@end lisp

The same approach as @code{simple-service} (@pxref{Referência de Service,
simple-service}) for @code{home-environment-variables-service-type} can be
used here, too.  Make sure that modules containing the specified packages
are imported with @code{use-modules}.  To find a package or information
about its module use @command{guix search} (@pxref{Invocando guix package}).
Alternatively, @code{specification->package} can be used to get the package
record from a string without importing its related module.
@end defvar

There are few more essential services, but users are not expected to extend
them.

@defvar home-service-type
The root of home services DAG, it generates a folder, which later will be
symlinked to @file{~/.guix-home}, it contains configurations, profile with
binaries and libraries, and some necessary scripts to glue things together.
@end defvar

@defvar home-run-on-first-login-service-type
The service of this type generates a Guile script, which is expected to be
executed by the login shell.  It is only executed if the special flag file
inside @env{XDG_RUNTIME_DIR} hasn't been created, this prevents redundant
executions of the script if multiple login shells are spawned.

It can be extended with a gexp.  However, to autostart an application, users
@emph{should not} use this service, in most cases it's better to extend
@code{home-shepherd-service-type} with a Shepherd service (@pxref{Serviços de Shepherd}), or extend the shell's startup file with the required command
using the appropriate service type.
@end defvar

@defvar home-files-service-type
The service of this type allows to specify a list of files, which will go to
@file{~/.guix-home/files}, usually this directory contains configuration
files (to be more precise it contains symlinks to files in
@file{/gnu/store}), which should be placed in @file{$XDG_CONFIG_HOME} or in
rare cases in @file{$HOME}.  It accepts extension values in the following
format:

@lisp
`((".sway/config" ,sway-file-like-object)
  (".tmux.conf" ,(local-file "./tmux.conf")))
@end lisp

Each nested list contains two values: a subdirectory and file-like object.
After building a home environment @file{~/.guix-home/files} will be
populated with appropriate content and all nested directories will be
created accordingly, however, those files won't go any further until some
other service will do it.  By default a
@code{home-symlink-manager-service-type}, which creates necessary symlinks
in home folder to files from @file{~/.guix-home/files} and backs up already
existing, but clashing configs and other things, is a part of essential home
services (enabled by default), but it's possible to use alternative services
to implement more advanced use cases like read-only home.  Feel free to
experiment and share your results.
@end defvar

@cindex dot files in Guix Home
It is often the case that Guix Home users already have a setup for
versioning their user configuration files (also known as @emph{dot files})
in a single directory, and some way of automatically deploy changes to their
user home.

@cindex Stow-like dot file management
The @code{home-dotfiles-service-type} from @code{(gnu home services
dotfiles)} is designed to ease the way into using Guix Home for this kind of
users, allowing them to point the service to their dotfiles directory
without migrating them to Guix native configurations.

Please keep in mind that it is advisable to keep your dotfiles directories
under version control, for example in the same repository where you'd track
your Guix Home configuration.

There are two supported dotfiles directory layouts, for now. The
@code{'plain} layout, which is structured as follows:

@example
~$ tree -a ./dotfiles/
dotfiles/
├── .gitconfig
├── .gnupg
│   ├── gpg-agent.conf
│   └── gpg.conf
├── .guile
├── .config
│   ├── guix
│   │   └── channels.scm
│   └── nixpkgs
│       └── config.nix
├── .nix-channels
├── .tmux.conf
└── .vimrc
@end example

This tree structure is installed as is to the home directory upon
@command{guix home reconfigure}.

The @code{'stow} layout, which must follow the layout suggested by
@uref{https://www.gnu.org/software/stow/, GNU Stow} presents an additional
application specific directory layer, just like:

@example
~$ tree -a ./dotfiles/
dotfiles/
├── git
│   └── .gitconfig
├── gpg
│   └── .gnupg
│       ├── gpg-agent.conf
│       └── gpg.conf
├── guile
│   └── .guile
├── guix
│   └── .config
│       └── guix
│           └── channels.scm
├── nix
│   ├── .config
│   │   └── nixpkgs
│   │       └── config.nix
│   └── .nix-channels
├── tmux
│   └── .tmux.conf
└── vim
    └── .vimrc

13 directories, 10 files
@end example

For an informal specification please refer to the Stow manual
(@pxref{Introduction,,, stow, The GNU Stow Manual}). This tree structure is
installed following GNU Stow's logic to the home directory upon
@command{guix home reconfigure}.

A suitable configuration with a @code{'plain} layout could be:

@lisp
(home-environment
  ;; @dots{}
  (services
    (service home-dotfiles-service-type
             (home-dotfiles-configuration
               (directories '("./dotfiles"))))))
@end lisp

The expected home directory state would then be:

@example
.
├── .config
│   ├── guix
│   │   └── channels.scm
│   └── nixpkgs
│       └── config.nix
├── .gitconfig
├── .gnupg
│   ├── gpg-agent.conf
│   └── gpg.conf
├── .guile
├── .nix-channels
├── .tmux.conf
└── .vimrc
@end example

@defvar home-dotfiles-service-type
Return a service which is very similar to @code{home-files-service-type}
(and actually extends it), but designed to ease the way into using Guix Home
for users that already track their dotfiles under some kind of version
control.  This service allows users to point Guix Home to their dotfiles
directory and have their files automatically provisioned to their home
directory, without migrating all of their dotfiles to Guix native
configurations.
@end defvar

@c %start of fragment

@deftp {Tipo de dados} home-dotfiles-configuration
Available @code{home-dotfiles-configuration} fields are:

@table @asis
@item @code{source-directory} (default: @code{(current-source-directory)}) (type: string)
The path where dotfile directories are resolved.  By default dotfile
directories are resolved relative the source location where
@code{home-dotfiles-configuration} appears.

@item @code{layout} (default: @code{'plain}) (type: symbol)
The intended layout of the specified @code{directory}.  It can be either
@code{'stow} or @code{'plain}.

@item @code{directories} (default: @code{'()}) (type: list-of-strings)
The list of dotfiles directories where @code{home-dotfiles-service-type}
will look for application dotfiles.

@item @code{packages} (type: maybe-list-of-strings)
The names of a subset of the GNU Stow package layer directories.  When
provided the @code{home-dotfiles-service-type} will only provision dotfiles
from this subset of applications.  This field will be ignored if
@code{layout} is set to @code{'plain}.

@item @code{excluded} (default: @code{'(".*~" ".*\\.swp" "\\.git" "\\.gitignore")}) (type: list-of-strings)
The list of file patterns @code{home-dotfiles-service-type} will exclude
while visiting each one of the @code{directories}.

@end table

@end deftp


@c %end of fragment

@defvar home-xdg-configuration-files-service-type
The service is very similar to @code{home-files-service-type} (and actually
extends it), but used for defining files, which will go to
@file{~/.guix-home/files/.config}, which will be symlinked to
@file{$XDG_CONFIG_HOME} by @code{home-symlink-manager-service-type} (for
example) during activation.  It accepts extension values in the following
format:

@lisp
`(("sway/config" ,sway-file-like-object)
  ;; -> ~/.guix-home/files/.config/sway/config
  ;; -> $XDG_CONFIG_HOME/sway/config (by symlink-manager)
  ("tmux/tmux.conf" ,(local-file "./tmux.conf")))
@end lisp
@end defvar

@defvar home-activation-service-type
The service of this type generates a guile script, which runs on every
@command{guix home reconfigure} invocation or any other action, which leads
to the activation of the home environment.
@end defvar

@defvar home-symlink-manager-service-type
The service of this type generates a guile script, which will be executed
during activation of home environment, and do a few following steps:

@enumerate
@item
Reads the content of @file{files/} directory of current and pending home
environments.

@item
Cleans up all symlinks created by symlink-manager on previous activation.
Also, sub-directories, which become empty also will be cleaned up.

@item
Creates new symlinks the following way: It looks @file{files/} directory
(usually defined with @code{home-files-service-type},
@code{home-xdg-configuration-files-service-type} and maybe some others),
takes the files from @file{files/.config/} subdirectory and put respective
links in @env{XDG_CONFIG_HOME}.  For example symlink for
@file{files/.config/sway/config} will end up in
@file{$XDG_CONFIG_HOME/sway/config}.  The rest files in @file{files/}
outside of @file{files/.config/} subdirectory will be treated slightly
different: symlink will just go to @file{$HOME}.
@file{files/.some-program/config} will end up in
@file{$HOME/.some-program/config}.

@item
If some sub-directories are missing, they will be created.

@item
If there is a clashing files on the way, they will be backed up.

@end enumerate

symlink-manager is a part of essential home services and is enabled and used
by default.
@end defvar


@node Shells Home Services
@subsection Shells

@cindex shell
@cindex login shell
@cindex interactive shell
@cindex bash
@cindex zsh

Shells play a quite important role in the environment initialization
process, you can configure them manually as described in section
@ref{Configurando o "Shell"}, but the recommended way is to use home services
listed below.  It's both easier and more reliable.

Each home environment instantiates @code{home-shell-profile-service-type},
which creates a @file{~/.profile} startup file for all POSIX-compatible
shells.  This file contains all the necessary steps to properly initialize
the environment, but many modern shells like Bash or Zsh prefer their own
startup files, that's why the respective home services
(@code{home-bash-service-type} and @code{home-zsh-service-type}) ensure that
@file{~/.profile} is sourced by @file{~/.bash_profile} and
@file{~/.zprofile}, respectively.

@subsubheading Shell Profile Service

@deftp {Tipo de dados} home-shell-profile-configuration
Available @code{home-shell-profile-configuration} fields are:

@table @asis
@item @code{profile} (default: @code{'()}) (type: text-config)
@code{home-shell-profile} is instantiated automatically by
@code{home-environment}, DO NOT create this service manually, it can only be
extended.  @code{profile} is a list of file-like objects, which will go to
@file{~/.profile}.  By default @file{~/.profile} contains the initialization
code which must be evaluated by the login shell to make home-environment's
profile available to the user, but other commands can be added to the file
if it is really necessary.  In most cases shell's configuration files are
preferred places for user's customizations.  Extend home-shell-profile
service only if you really know what you do.

@end table

@end deftp

@subsubheading Bash Home Service

@c %start of fragment
@anchor{home-bash-configuration}

@deftp {Tipo de dados} home-bash-configuration
Available @code{home-bash-configuration} fields are:

@table @asis
@item @code{package} (default: @code{bash}) (type: package)
The Bash package to use.

@item @code{guix-defaults?} (default: @code{#t}) (type: boolean)
Add sane defaults like setting @env{PS1}, @env{SHELL}, and ensuring
@file{/etc/profile} is sourced for non-interactive SSH shells.  If you use
Guix System, is it safe to set this to @code{#f}, as in this case this is
already taken care of by the globally installed @file{/etc/bashrc}.

@item @code{environment-variables} (default: @code{()}) (type: alist)
Association list of environment variables to set for the Bash session.  The
rules for the @code{home-environment-variables-service-type} apply here
(@pxref{Serviços essenciais pessoais}).  The contents of this field will be added
after the contents of the @code{bash-profile} field.

@item @code{variables} (default: @code{()}) (type: alist)
Bash variables (not to be confused with environment variables) to be set in
@file{.bashrc} for use by interactive shells.  A typical example of such
variables is @code{HISTSIZE} and related history variables (@pxref{Bash
Variables,,, bash,Bash Reference Manual}).

@item @code{aliases} (type: alist)
Association list of aliases to set for the Bash session.  The aliases will
be defined after the contents of the @code{bashrc} field has been put in the
@file{.bashrc} file.  The alias will automatically be quoted, so something
like this:

@lisp
'(("ls" . "ls -alF"))
@end lisp

turns into

@example
alias ls="ls -alF"
@end example

@item @code{bash-profile} (default: @code{()}) (type: text-config)
List of file-like objects, which will be added to @file{.bash_profile}.
Used for executing user's commands at start of login shell (In most cases
the shell started on tty just after login).  @file{.bash_login} won't be
ever read, because @file{.bash_profile} always present.

@item @code{bashrc} (default: @code{()}) (type: text-config)
List of file-like objects, which will be added to @file{.bashrc}.  Used for
executing user's commands at start of interactive shell (The shell for
interactive usage started by typing @code{bash} or by terminal app or any
other program).

@item @code{bash-logout} (default: @code{()}) (type: text-config)
List of file-like objects, which will be added to @file{.bash_logout}.  Used
for executing user's commands at the exit of login shell.  It won't be read
in some cases (if the shell terminates by exec'ing another process for
example).

@end table

@end deftp


@c %end of fragment

You can extend the Bash service by using the @code{home-bash-extension}
configuration record, whose fields must mirror that of
@code{home-bash-configuration} (@pxref{home-bash-configuration}).  The
contents of the extensions will be added to the end of the corresponding
Bash configuration files (@pxref{Bash Startup Files,,, bash, The GNU Bash
Reference Manual}.

For example, here is how you would define a service that extends the Bash
service such that @file{~/.bash_profile} defines an additional shell
variable, @env{PS1}:

@lisp
(define bash-fancy-prompt-service
  (simple-service 'bash-fancy-prompt
                  home-bash-service-type
                  (home-bash-extension
                   (variables
                    '(("PS1" . "\\u \\wλ "))))))
@end lisp

You would then add @code{bash-fancy-prompt-service} to the list in the
@code{services} field of your @code{home-environment}.  The reference of
@code{home-bash-extension} follows.

@c %start of fragment

@deftp {Tipo de dados} home-bash-extension
Available @code{home-bash-extension} fields are:

@table @asis
@item @code{environment-variables} (default: @code{()}) (type: alist)
Additional environment variables to set.  These will be combined with the
environment variables from other extensions and the base service to form one
coherent block of environment variables.

@item @code{variables} (default: @code{()}) (type: alist)
Extra Bash variables (not to be confused with environment variables) to be
set in @file{.bashrc} for use by interactive shells.

@item @code{aliases} (default: @code{()}) (type: alist)
Additional aliases to set.  These will be combined with the aliases from
other extensions and the base service.

@item @code{bash-profile} (default: @code{()}) (type: text-config)
Additional text blocks to add to @file{.bash_profile}, which will be
combined with text blocks from other extensions and the base service.

@item @code{bashrc} (default: @code{()}) (type: text-config)
Additional text blocks to add to @file{.bashrc}, which will be combined with
text blocks from other extensions and the base service.

@item @code{bash-logout} (default: @code{()}) (type: text-config)
Additional text blocks to add to @file{.bash_logout}, which will be combined
with text blocks from other extensions and the base service.

@end table

@end deftp

@c %end of fragment

@subsubheading Zsh Home Service

@deftp {Tipo de dados} home-zsh-configuration
Available @code{home-zsh-configuration} fields are:

@table @asis
@item @code{package} (default: @code{zsh}) (type: package)
The Zsh package to use.

@item @code{xdg-flavor?} (default: @code{#t}) (type: boolean)
Place all the configs to @file{$XDG_CONFIG_HOME/zsh}.  Makes
@file{~/.zshenv} to set @env{ZDOTDIR} to @file{$XDG_CONFIG_HOME/zsh}.  Shell
startup process will continue with @file{$XDG_CONFIG_HOME/zsh/.zshenv}.

@item @code{environment-variables} (default: @code{'()}) (type: alist)
Association list of environment variables to set for the Zsh session.

@item @code{zshenv} (default: @code{'()}) (type: text-config)
List of file-like objects, which will be added to @file{.zshenv}.  Used for
setting user's shell environment variables.  Must not contain commands
assuming the presence of tty or producing output.  Will be read always.
Will be read before any other file in @env{ZDOTDIR}.

@item @code{zprofile} (default: @code{'()}) (type: text-config)
List of file-like objects, which will be added to @file{.zprofile}.  Used
for executing user's commands at start of login shell (In most cases the
shell started on tty just after login).  Will be read before @file{.zlogin}.

@item @code{zshrc} (default: @code{'()}) (type: text-config)
List of file-like objects, which will be added to @file{.zshrc}.  Used for
executing user's commands at start of interactive shell (The shell for
interactive usage started by typing @code{zsh} or by terminal app or any
other program).

@item @code{zlogin} (default: @code{'()}) (type: text-config)
List of file-like objects, which will be added to @file{.zlogin}.  Used for
executing user's commands at the end of starting process of login shell.

@item @code{zlogout} (default: @code{'()}) (type: text-config)
List of file-like objects, which will be added to @file{.zlogout}.  Used for
executing user's commands at the exit of login shell.  It won't be read in
some cases (if the shell terminates by exec'ing another process for
example).

@end table

@end deftp

@subsubheading Inputrc Profile Service
@cindex inputrc
@cindex readline

The @uref{https://tiswww.cwru.edu/php/chet/readline/rltop.html, GNU Readline
package} includes Emacs and vi editing modes, with the ability to customize
the configuration with settings in the @file{~/.inputrc} file.  With the
@code{gnu home services shells} module, you can setup your readline
configuration in a predictable manner, as shown below.  For more information
about configuring an @file{~/.inputrc} file, @pxref{Readline Init File,,,
readline, GNU Readline}.

@defvar home-inputrc-service-type

This is the service to setup various @file{.inputrc} configurations. The
settings in @file{.inputrc} are read by all programs which are linked with
GNU Readline.

Here is an example of a service and its configuration that you could add to
the @code{services} field of your @code{home-environment}:

@lisp
(service home-inputrc-service-type
         (home-inputrc-configuration
           (key-bindings
            `(("Control-l" . "clear-screen")))
           (variables
            `(("bell-style" . "visible")
              ("colored-completion-prefix" . #t)
              ("editing-mode" . "vi")
              ("show-mode-in-prompt" . #t)))
           (conditional-constructs
            `(("$if mode=vi" .
               ,(home-inputrc-configuration
                  (variables
                   `(("colored-stats" . #t)
                     ("enable-bracketed-paste" . #t)))))
              ("$else" .
               ,(home-inputrc-configuration
                  (variables
                   `(("show-all-if-ambiguous" . #t)))))
              ("endif" . #t)
              ("$include" . "/etc/inputrc")
              ("$include" . ,(file-append
                               (specification->package "readline")
                               "/etc/inputrc"))))))
@end lisp

The example above starts with a combination of @code{key-bindings} and
@code{variables}.  The @code{conditional-constructs} show how it is possible
to add conditionals and includes.  In the example above @code{colored-stats}
is only enabled if the editing mode is @code{vi} style, and it also reads
any additional configuration located in @file{/etc/inputrc} or in
@file{/gnu/store/@dots{}-readline/etc/inputrc}.

The value associated with a @code{home-inputrc-service-type} instance must
be a @code{home-inputrc-configuration} record, as described below.

@end defvar

@anchor{home-inputrc-configuration}
@deftp {Tipo de dados} home-inputrc-configuration
Available @code{home-inputrc-configuration} fields are:

@table @asis
@item @code{key-bindings} (default: @code{'()}) (type: alist)
Association list of readline key bindings to be added to the
@file{~/.inputrc} file.

@lisp
'((\"Control-l\" . \"clear-screen\"))
@end lisp

turns into

@example
Control-l: clear-screen
@end example

@item @code{variables} (default: @code{'()}) (type: alist)
Association list of readline variables to set.

@lisp
'((\"bell-style\" . \"visible\")
  (\"colored-completion-prefix\" . #t))
@end lisp

turns into

@example
set bell-style visible
set colored-completion-prefix on
@end example

@item @code{conditional-constructs} (default: @code{'()}) (type: alist)
Association list of conditionals to add to the initialization file.  This
includes @command{$if}, @command{else}, @command{endif} and
@command{include} and they receive a value of another
@command{home-inputrc-configuration}.

@lisp
(conditional-constructs
 `((\"$if mode=vi\" .
     ,(home-inputrc-configuration
        (variables
         `((\"show-mode-in-prompt\" . #t)))))
   (\"$else\" .
     ,(home-inputrc-configuration
        (key-bindings
         `((\"Control-l\" . \"clear-screen\")))))
   (\"$endif\" . #t)))
@end lisp

turns into

@example
$if mode=vi
set show-mode-in-prompt on
$else
Control-l: clear-screen
$endif
@end example

@item @code{extra-content} (default: @code{""}) (type: text-config)
Extra content appended as-is to the configuration file.  Run @command{man
readline} for more information about all the configuration options.

@end table
@end deftp

@node Mcron Home Service
@subsection Execução de trabalho agendado pessoal

@cindex cron, per-user
@cindex mcron, per-user
@cindex scheduling jobs per-user
The @code{(gnu home services mcron)} module provides an interface to
GNU@tie{}mcron, a daemon to run jobs at scheduled times (@pxref{Top,,,
mcron, GNU@tie{}mcron}).  The information about system's mcron is applicable
here (@pxref{mcron-service, mcron reference}), the only difference for home
services is that they have to be declared in a @code{home-environment}
record instead of an @code{operating-system} record.

@quotation Nota
We recommend defining periodic tasks as Shepherd timers, which provide more
flexibility than mcron.  @xref{Shepherd Home Service}, for more info.
@end quotation

@defvar home-mcron-service-type
This is the type of the @code{mcron} home service, whose value is a
@code{home-mcron-configuration} object.  It allows to manage scheduled
tasks.

This service type can be the target of a service extension that provides
additional job specifications (@pxref{Composição de serviço}).  In other
words, it is possible to define services that provide additional mcron jobs
to run.
@end defvar

@deftp {Tipo de dados} home-mcron-configuration
Available @code{home-mcron-configuration} fields are:

@c Auto-generated with (gnu home services mcron)'s
@c generate-documentation procedure.
@c %start of fragment
@table @asis
@item @code{mcron} (default: @code{mcron}) (type: file-like)
The mcron package to use.

@item @code{jobs} (default: @code{'()}) (type: list-of-gexps)
This is a list of gexps (@pxref{Expressões-G}), where each gexp corresponds
to an mcron job specification (@pxref{Syntax, mcron job specifications,,
mcron,GNU@tie{}mcron}).

@item @code{log?} (default: @code{#t}) (type: boolean)
Log messages to standard output.

@item @code{log-format} (default: @code{"~1@@*~a ~a: ~a~%"}) (type: string)
@code{(ice-9 format)} format string for log messages.  The default value
produces messages like "@samp{@var{pid} @var{name}: @var{message}"}
(@pxref{Invoking mcron, Invoking,, mcron,GNU@tie{}mcron}).  Each message is
also prefixed by a timestamp by GNU Shepherd.

@end table
@end deftp
@c %end of fragment

@node Power Management Home Services
@subsection Power Management Home Services

@cindex power management
The @code{(gnu home services pm)} module provides home services pertaining
to battery power.

@defvar home-batsignal-service-type
Service for @code{batsignal}, a program that monitors battery levels and
warns the user through desktop notifications when their battery is getting
low.  You can also configure a command to be run when the battery level
passes a point deemed ``dangerous''.  This service is configured with the
@code{home-batsignal-configuration} record.
@end defvar

@deftp {Tipo de dados} home-batsignal-configuration
Data type representing the configuration for batsignal.

@table @asis
@item @code{warning-level} (default: @code{15})
The battery level to send a warning message at.

@item @code{warning-message} (default: @code{#f})
The message to send as a notification when the battery level reaches the
@code{warning-level}.  Setting to @code{#f} uses the default message.

@item @code{critical-level} (default: @code{5})
The battery level to send a critical message at.

@item @code{critical-message} (default: @code{#f})
The message to send as a notification when the battery level reaches the
@code{critical-level}.  Setting to @code{#f} uses the default message.

@item @code{danger-level} (default: @code{2})
The battery level to run the @code{danger-command} at.

@item @code{danger-command} (default: @code{#f})
The command to run when the battery level reaches the @code{danger-level}.
Setting to @code{#f} disables running the command entirely.

@item @code{full-level} (default: @code{#f})
The battery level to send a full message at.  Setting to @code{#f} disables
sending the full message entirely.

@item @code{full-message} (default: @code{#f})
The message to send as a notification when the battery level reaches the
@code{full-level}.  Setting to @code{#f} uses the default message.

@item @code{batteries} (default: @code{'()})
The batteries to monitor.  Setting to @code{'()} tries to find batteries
automatically.

@item @code{poll-delay} (default: @code{60})
The time in seconds to wait before checking the batteries again.

@item @code{icon} (default: @code{#f})
A file-like object to use as the icon for battery notifications.  Setting to
@code{#f} disables notification icons entirely.

@item @code{notifications?} (default: @code{#t})
Whether to send any notifications.

@item @code{notifications-expire?} (default: @code{#f})
Whether notifications sent expire after a time.

@item @code{notification-command} (default: @code{#f})
Command to use to send messages.  Setting to @code{#f} sends a notification
through @code{libnotify}.

@item @code{ignore-missing?} (default: @code{#f})
Whether to ignore missing battery errors.
@end table
@end deftp

@node Shepherd Home Service
@subsection Managing User Daemons

@cindex shepherd services, for users
The @code{(gnu home services shepherd)} module supports the definitions of
per-user Shepherd services (@pxref{Introduction,,, shepherd, The GNU
Shepherd Manual}).  You extend @code{home-shepherd-service-type} with new
services; Guix Home then takes care of starting the @code{shepherd} daemon
for you when you log in, which in turns starts the services you asked for.

@defvar home-shepherd-service-type
The service type for the userland Shepherd, which allows one to manage
long-running processes or one-shot tasks.  User's Shepherd is not an init
process (PID 1), but almost all other information described in
(@pxref{Serviços de Shepherd}) is applicable here too.

This is the service type that extensions target when they want to create
shepherd services (@pxref{Tipos de Service e Serviços}, for an example).
Each extension must pass a list of @code{<shepherd-service>}.  Its value
must be a @code{home-shepherd-configuration}, as described below.
@end defvar

@deftp {Tipo de dados} home-shepherd-configuration
This data type represents the Shepherd's configuration.

@table @code
@item shepherd (default: @code{shepherd})
The Shepherd package to use.

@item auto-start? (default: @code{#t})
Whether or not to start Shepherd on first login.

@item daemonize? (default: @code{#t})
Whether or not to run Shepherd in the background.

@item silent? (default: @code{#t})
When true, the @command{shepherd} process does not write anything to
standard output when started automatically.

@item services (default: @code{'()})
A list of @code{<shepherd-service>} to start.  You should probably use the
service extension mechanism instead (@pxref{Serviços de Shepherd}).
@end table
@end deftp

@cindex timers, per-user
The Shepherd allows you to define @dfn{timers}, a special type of service
that performs a given task periodically.  Just like you can define timers at
the system level (@pxref{Execução de trabalho agendado}), you can do so in your
home environment.

The example below defines a home environment where a Shepherd timer runs the
@command{mkid} command twice per day (@pxref{mkid invocation,,, idutils, ID
Database Utilities}).  It does so by extending
@code{home-shepherd-service-type} with @code{simple-service}; the Shepherd
timer itself is produced by the @code{shepherd-timer} procedure
(@pxref{shepherd-timer-procedure, @code{shepherd-timer}}), which is given
the service name, a gexp specifying its schedule, and a gexp specifying the
command to run.

@lisp
(use-modules (gnu) (guix)
             (gnu home services shepherd)
             (gnu packages idutils))

(define idutils-service
  ;; Index my 'doc' directory everyday at 12:15PM and 7:15PM.
  (simple-service
   'update-idutils-database home-shepherd-service-type
   (list (shepherd-timer '(update-idutils-database)
                         #~(calendar-event #:hours '(12 19)
                                           #:minutes '(15))
                         #~(#$(file-append idutils "/bin/mkid")
                            "doc")))))

(home-environment
  ;; @dots{}
  (services (append (list idutils-service)
                    %base-home-services)))
@end lisp

@xref{Timers,,, shepherd, The GNU Shepherd Manual} for more information on
Shepherd timers.

@cindex log rotation, for user services
The Shepherd also comes with a @dfn{log rotation service}, which compresses
and then deletes old log files produced by services and daemons that it
runs.  This service is made available through
@code{home-log-rotation-service-type} as described below.

@defvar home-log-rotation-service-type
This is the service type for the user Shepherd log rotation service
(@pxref{Log Rotation Service,,, shepherd, The GNU Shepherd Manual}).  Its
value must be a @code{log-rotation-configuration} record, exactly as for its
system-wide counterpart.  @xref{log-rotation-configuration}, for its
reference.

This service is part of @code{%base-home-services}.
@end defvar

@defvar home-shepherd-transient-service-type
@defvarx home-shepherd-timer-service-type
These are the @code{timer} and @code{transient} Shepherd services.  The
former lets you schedule command execution for later, while the latter can
run commands in the background as a regular service.

@xref{shepherd-transient-timer-services, the system @code{timer} and
@code{transient} services}, which are their Guix System counterparts, for
more info.
@end defvar

@node Secure Shell
@subsection Secure Shell

@cindex secure shell client, configuration
@cindex SSH client, configuration
The @uref{https://www.openssh.com, OpenSSH package} includes a client, the
@command{ssh} command, that allows you to connect to remote machines using
the @acronym{SSH, secure shell} protocol.  With the @code{(gnu home services
ssh)} module, you can set up OpenSSH so that it works in a predictable
fashion, almost independently of state on the local machine.  To do that,
you instantiate @code{home-openssh-service-type} in your Home configuration,
as explained below.

@defvar home-openssh-service-type
This is the type of the service to set up the OpenSSH client.  It takes care
of several things:

@itemize
@item
providing a @file{~/.ssh/config} file based on your configuration so that
@command{ssh} knows about hosts you regularly connect to and their
associated parameters;

@item
providing a @file{~/.ssh/authorized_keys}, which lists public keys that the
local SSH server, @command{sshd}, may accept to connect to this user
account;

@item
optionally providing a @file{~/.ssh/known_hosts} file so that @file{ssh} can
authenticate hosts you connect to.
@end itemize

Here is an example of a service and its configuration that you could add to
the @code{services} field of your @code{home-environment}:

@lisp
(service home-openssh-service-type
         (home-openssh-configuration
          (hosts
           (list (openssh-host (name "ci.guix.gnu.org")
                               (user "charlie"))
                 (openssh-host (name "chbouib")
                               (host-name "chbouib.example.org")
                               (user "supercharlie")
                               (port 10022))))
          (authorized-keys (list (local-file "alice.pub")))))
@end lisp

The example above lists two hosts and their parameters.  For instance,
running @command{ssh chbouib} will automatically connect to
@code{chbouib.example.org} on port 10022, logging in as user
@samp{supercharlie}.  Further, it marks the public key in @file{alice.pub}
as authorized for incoming connections.

The value associated with a @code{home-openssh-service-type} instance must
be a @code{home-openssh-configuration} record, as describe below.
@end defvar

@deftp {Tipo de dados} home-openssh-configuration
This is the datatype representing the OpenSSH client and server
configuration in one's home environment.  It contains the following fields:

@table @asis
@item @code{hosts} (default: @code{'()})
A list of @code{openssh-host} records specifying host names and associated
connection parameters (see below).  This host list goes into
@file{~/.ssh/config}, which @command{ssh} reads at startup.

@item @code{known-hosts} (default: @code{*unspecified*})
This must be either:

@itemize
@item
@code{*unspecified*}, in which case @code{home-openssh-service-type} leaves
it up to @command{ssh} and to the user to maintain the list of known hosts
at @file{~/.ssh/known_hosts}, or

@item
a list of file-like objects, in which case those are concatenated and
emitted as @file{~/.ssh/known_hosts}.
@end itemize

The @file{~/.ssh/known_hosts} contains a list of host name/host key pairs
that allow @command{ssh} to authenticate hosts you connect to and to detect
possible impersonation attacks.  By default, @command{ssh} updates it in a
@dfn{TOFU, trust-on-first-use} fashion, meaning that it records the host's
key in that file the first time you connect to it.  This behavior is
preserved when @code{known-hosts} is set to @code{*unspecified*}.

If you instead provide a list of host keys upfront in the @code{known-hosts}
field, your configuration becomes self-contained and stateless: it can be
replicated elsewhere or at another point in time.  Preparing this list can
be relatively tedious though, which is why @code{*unspecified*} is kept as a
default.

@item @code{authorized-keys} (default: @code{#false})
The default @code{#false} value means: Leave any
@file{~/.ssh/authorized_keys} file alone.  Otherwise, this must be a list of
file-like objects, each of which containing an SSH public key that should be
authorized to connect to this machine.

Concretely, these files are concatenated and made available as
@file{~/.ssh/authorized_keys}.  If an OpenSSH server, @command{sshd}, is
running on this machine, then it @emph{may} take this file into account:
this is what @command{sshd} does by default, but be aware that it can also
be configured to ignore it.

@item @code{add-keys-to-agent} (default: @code{no})
This string specifies whether keys should be automatically added to a
running ssh-agent.  If this option is set to @code{yes} and a key is loaded
from a file, the key and its passphrase are added to the agent with the
default lifetime, as if by @code{ssh-add}.  If this option is set to
@code{ask}, @code{ssh} will require confirmation.  If this option is set to
@code{confirm}, each use of the key must be confirmed.  If this option is
set to @code{no}, no keys are added to the agent.  Alternately, this option
may be specified as a time interval to specify the key's lifetime in
@code{ssh-agent}, after which it will automatically be removed.  The
argument must be @code{no}, @code{yes}, @code{confirm} (optionally followed
by a time interval), @code{ask} or a time interval.
@end table
@end deftp

@c %start of fragment

@deftp {Tipo de dados} openssh-host
Available @code{openssh-host} fields are:

@table @asis
@item @code{name} (type: string)
Name of this host declaration.  A @code{openssh-host} must define only
@code{name} or @code{match-criteria}.  Use host-name @code{\"*\"} for
top-level options.

@item @code{host-name} (type: maybe-string)
Host name---e.g., @code{"foo.example.org"} or @code{"192.168.1.2"}.

@item @code{match-criteria} (type: maybe-match-criteria)
When specified, this string denotes the set of hosts to which the entry
applies, superseding the @code{host-name} field.  Its first element must be
all or one of @code{ssh-match-keywords}.  The rest of the elements are
arguments for the keyword, or other criteria.  A @code{openssh-host} must
define only @code{name} or @code{match-criteria}.  Other host configuration
options will apply to all hosts matching @code{match-criteria}.

@item @code{address-family} (type: maybe-address-family)
Address family to use when connecting to this host: one of @code{AF_INET}
(for IPv4 only), @code{AF_INET6} (for IPv6 only).  Additionally, the field
can be left unset to allow any address family.

@item @code{identity-file} (type: maybe-string)
The identity file to use---e.g., @code{"/home/charlie/.ssh/id_ed25519"}.

@item @code{port} (type: maybe-natural-number)
TCP port number to connect to.

@item @code{user} (type: maybe-string)
User name on the remote host.

@item @code{forward-x11?} (type: maybe-boolean)
Whether to forward remote client connections to the local X11 graphical
display.

@item @code{forward-x11-trusted?} (type: maybe-boolean)
Whether remote X11 clients have full access to the original X11 graphical
display.

@item @code{forward-agent?} (type: maybe-boolean)
Whether the authentication agent (if any) is forwarded to the remote
machine.

@item @code{compression?} (type: maybe-boolean)
Whether to compress data in transit.

@item @code{proxy} (type: maybe-proxy-command-or-jump-list)
The command to use to connect to the server or a list of SSH hosts to jump
through before connecting to the server.  The field may be set to either a
@code{proxy-command} or a list of @code{proxy-jump} records.

As an example, a @code{proxy-command} to connect via an HTTP proxy at
192.0.2.0 would be constructed with: @code{(proxy-command "nc -X connect -x
192.0.2.0:8080 %h %p")}.

@deftp {Tipo de dados} proxy-jump
Available @code{proxy-jump} fields are:

@table @asis
@item @code{user} (type: maybe-string)
User name on the remote host.

@item @code{host-name} (type: string)
Host name---e.g., @code{foo.example.org} or @code{192.168.1.2}.

@item @code{port} (type: maybe-natural-number)
TCP port number to connect to.

@end table

@end deftp

@item @code{host-key-algorithms} (type: maybe-string-list)
The list of accepted host key algorithms---e.g., @code{'("ssh-ed25519")}.

@item @code{accepted-key-types} (type: maybe-string-list)
The list of accepted user public key types.

@item @code{extra-content} (default: @code{""}) (type: raw-configuration-string)
Extra content appended as-is to this @code{Host} block in
@file{~/.ssh/config}.

@end table

@end deftp

@cindex Parcimonie, Home service
The @code{parcimonie} service runs a daemon that slowly refreshes a GnuPG
public key from a keyserver.  It refreshes one key at a time; between every
key update parcimonie sleeps a random amount of time, long enough for the
previously used Tor circuit to expire.  This process is meant to make it
hard for an attacker to correlate the multiple key update.

As an example, here is how you would configure @code{parcimonie} to refresh
the keys in your GnuPG keyring, as well as those keyrings created by Guix,
such as when running @code{guix import}:

@lisp
(service home-parcimonie-service-type
         (home-parcimonie-configuration
           (refresh-guix-keyrings? #t)))
@end lisp

This assumes that the Tor anonymous routing daemon is already running on
your system.  On Guix System, this can be achieved by setting up
@code{tor-service-type} (@pxref{Serviços de Rede,
@code{tor-service-type}}).

The service reference is given below.

@defvar parcimonie-service-type
This is the service type for @command{parcimonie}
(@uref{https://salsa.debian.org/intrigeri/parcimonie, Parcimonie's web
site}).  Its value must be a @code{home-parcimonie-configuration}, as shown
below.
@end defvar

@c %start of fragment

@deftp {Tipo de dados} home-parcimonie-configuration
Available @code{home-parcimonie-configuration} fields are:

@table @asis
@item @code{parcimonie} (default: @code{parcimonie}) (type: file-like)
The parcimonie package to use.

@item @code{verbose?} (default: @code{#f}) (type: boolean)
Whether to have more verbose logging from the service.

@item @code{gnupg-already-torified?} (default: @code{#f}) (type: boolean)
Whether GnuPG is already configured to pass all traffic through
@uref{https://torproject.org, Tor}.

@item @code{refresh-guix-keyrings?} (default: @code{#f}) (type: boolean)
Guix creates a few keyrings in the @var{$XDG_CONFIG_HOME}, such as when
running @code{guix import} (@pxref{Invocando guix import}).  Setting this to
@code{#t} will also refresh any keyrings which Guix has created.

@item @code{extra-content} (default: @code{#f}) (type: raw-configuration-string)
Raw content to add to the parcimonie command.

@end table

@end deftp

@c %end of fragment

@cindex ssh-agent
The @uref{https://www.openssh.com, OpenSSH package} includes a daemon, the
@command{ssh-agent} command, that manages keys to connect to remote machines
using the @acronym{SSH, secure shell} protocol.  With the @code{(gnu home
services ssh)} service, you can configure the OpenSSH ssh-agent to run upon
login.  @xref{GNU Privacy Guard, @code{home-gpg-agent-service-type}}, for an
alternative to OpenSSH's @command{ssh-agent}.


Here is an example of a service and its configuration that you could add to
the @code{services} field of your @code{home-environment}:

@lisp
(service home-ssh-agent-service-type
         (home-ssh-agent-configuration
          (extra-options '("-t" "1h30m"))))
@end lisp

@defvar home-ssh-agent-service-type
This is the type of the @code{ssh-agent} home service, whose value is a
@code{home-ssh-agent-configuration} object.
@end defvar

@deftp {Tipo de dados} home-ssh-agent-configuration
Available @code{home-ssh-agent-configuration} fields are:

@table @asis
@item @code{openssh} (default: @code{openssh}) (type: file-like)
The OpenSSH package to use.

@item @code{socket-directory} (default: @code{@env{XDG_RUNTIME_DIR}/ssh-agent"}) (type: gexp)
The directory to write the ssh-agent's @file{socket} file.

@item @code{extra-options} (default: @code{'()})
Extra options will be passed to @command{ssh-agent}, please run @command{man
ssh-agent} for more information.

@end table
@end deftp

@node GNU Privacy Guard
@subsection GNU Privacy Guard

@cindex GNU Privacy Guard, Home service
@cindex GPG, Home service
The @code{(gnu home services gnupg)} module provides services that help you
set up the GNU Privacy Guard, also known as GnuPG or GPG, in your home
environment.

@cindex gpg-agent, Home service
@cindex SSH agent, with gpg-agent
The @code{gpg-agent} service configures and sets up GPG's agent, the program
that is responsible for managing OpenPGP private keys and, optionally,
OpenSSH (secure shell) private keys (@pxref{Invoking GPG-AGENT,,, gnupg,
Using the GNU Privacy Guard}).

As an example, here is how you would configure @code{gpg-agent} with SSH
support such that it uses the Emacs-based Pinentry interface when prompting
for a passphrase:

@lisp
(service home-gpg-agent-service-type
         (home-gpg-agent-configuration
          (pinentry-program
           (file-append pinentry-emacs "/bin/pinentry-emacs"))
          (ssh-support? #t)))
@end lisp

The service reference is given below.

@defvar home-gpg-agent-service-type
This is the service type for @command{gpg-agent} (@pxref{Invoking
GPG-AGENT,,, gnupg, Using the GNU Privacy Guard}).  Its value must be a
@code{home-gpg-agent-configuration}, as shown below.
@end defvar

@c %start of fragment

@deftp {Tipo de dados} home-gpg-agent-configuration
Available @code{home-gpg-agent-configuration} fields are:

@table @asis
@item @code{gnupg} (default: @code{gnupg}) (type: file-like)
The GnuPG package to use.

@item @code{pinentry-program} (type: file-like)
Pinentry program to use.  Pinentry is a small user interface that
@command{gpg-agent} delegates to anytime it needs user input for a
passphrase or @acronym{PIN,personal identification number} (@pxref{Top,,,
pinentry,Using the PIN-Entry}).

@item @code{ssh-support?} (default: @code{#f}) (type: boolean)
Whether to enable @acronym{SSH,secure shell} support.  When true,
@command{gpg-agent} acts as a drop-in replacement for OpenSSH's
@command{ssh-agent} program, taking care of OpenSSH secret keys and
directing passphrase requests to the chosen Pinentry program.

@item @code{default-cache-ttl} (default: @code{600}) (type: integer)
Time a cache entry is valid, in seconds.

@item @code{max-cache-ttl} (default: @code{7200}) (type: integer)
Maximum time a cache entry is valid, in seconds.  After this time a cache
entry will be expired even if it has been accessed recently.

@item @code{default-cache-ttl-ssh} (default: @code{1800}) (type: integer)
Time a cache entry for SSH keys is valid, in seconds.

@item @code{max-cache-ttl-ssh} (default: @code{7200}) (type: integer)
Maximum time a cache entry for SSH keys is valid, in seconds.

@item @code{extra-content} (default: @code{""}) (type: raw-configuration-string)
Raw content to add to the end of @file{~/.gnupg/gpg-agent.conf}.

@end table

@end deftp


@c %end of fragment


@node Desktop Home Services
@subsection Desktop Home Services

The @code{(gnu home services desktop)} module provides services that you may
find useful on ``desktop'' systems running a graphical user environment such
as Xorg.

@cindex X Window, for Guix Home services
@cindex X11, in Guix Home
@defvar home-x11-service-type
This is the service type representing the X Window graphical display server
(also referred to as ``X11'').

X Window is necessarily started by a system service; on Guix System,
starting it is the responsibility of @code{gdm-service-type} and similar
services (@pxref{X Window}).  At the level of Guix Home, as an unprivileged
user, we cannot start X Window; all we can do is check whether it is
running.  This is what this service does.

As a user, you probably don't need to worry or explicitly instantiate
@code{home-x11-service-type}.  Services that require an X Window graphical
display, such as @code{home-redshift-service-type} below, instantiate it and
depend on its corresponding @code{x11-display} Shepherd service
(@pxref{Shepherd Home Service}).

When X Window is running, the @code{x11-display} Shepherd service starts and
sets the @env{DISPLAY} environment variable of the @command{shepherd}
process, using its original value if it was already set; otherwise, it fails
to start.

The service can also be forced to use a given value for @env{DISPLAY}, like
so:

@example
herd start x11-display :3
@end example

In the example above, @code{x11-display} is instructed to set @env{DISPLAY}
to @code{:3}.
@end defvar

@defvar home-redshift-service-type
This is the service type for @uref{https://github.com/jonls/redshift,
Redshift}, a program that adjusts the display color temperature according to
the time of day.  Its associated value must be a
@code{home-redshift-configuration} record, as shown below.

A typical configuration, where we manually specify the latitude and
longitude, might look like this:

@lisp
(service home-redshift-service-type
         (home-redshift-configuration
          (location-provider 'manual)
          (latitude 35.81)    ;northern hemisphere
          (longitude -0.80))) ;west of Greenwich
@end lisp
@end defvar

@deftp {Tipo de dados} home-redshift-configuration
Available @code{home-redshift-configuration} fields are:

@table @asis
@item @code{redshift} (default: @code{redshift}) (type: file-like)
Redshift package to use.

@item @code{location-provider} (default: @code{geoclue2}) (type: symbol)
Geolocation provider---@code{'manual} or @code{'geoclue2}.  In the former
case, you must also specify the @code{latitude} and @code{longitude} fields
so Redshift can determine daytime at your place.  In the latter case, the
Geoclue system service must be running; it will be queried for location
information.

@item @code{adjustment-method} (default: @code{randr}) (type: symbol)
Color adjustment method.

@item @code{daytime-temperature} (default: @code{6500}) (type: integer)
Daytime color temperature (kelvins).

@item @code{nighttime-temperature} (default: @code{4500}) (type: integer)
Nighttime color temperature (kelvins).

@item @code{daytime-brightness} (type: maybe-inexact-number)
Daytime screen brightness, between 0.1 and 1.0, or left unspecified.

@item @code{nighttime-brightness} (type: maybe-inexact-number)
Nighttime screen brightness, between 0.1 and 1.0, or left unspecified.

@item @code{latitude} (type: maybe-inexact-number)
Latitude, when @code{location-provider} is @code{'manual}.

@item @code{longitude} (type: maybe-inexact-number)
Longitude, when @code{location-provider} is @code{'manual}.

@item @code{dawn-time} (type: maybe-string)
Custom time for the transition from night to day in the
morning---@code{"HH:MM"} format.  When specified, solar elevation is not
used to determine the daytime/nighttime period.

@item @code{dusk-time} (type: maybe-string)
Likewise, custom time for the transition from day to night in the evening.

@item @code{extra-content} (default: @code{""}) (type: raw-configuration-string)
Extra content appended as-is to the Redshift configuration file.  Run
@command{man redshift} for more information about the configuration file
format.

@end table

@end deftp

@defvar home-dbus-service-type
This is the service type for running a session-specific D-Bus, for
unprivileged applications that require D-Bus to be running.
@end defvar

@deftp {Tipo de dados} home-dbus-configuration
The configuration record for @code{home-dbus-service-type}.

@table @asis
@item @code{dbus} (default: @code{dbus})
The package providing the @code{/bin/dbus-daemon} command.
@end table
@end deftp

@defvar home-unclutter-service-type
This is the service type for Unclutter, a program that runs on the
background of an X11 session and detects when the X pointer hasn't moved for
a specified idle timeout, after which it hides the cursor so that you can
focus on the text underneath.  Its associated value must be a
@code{home-unclutter-configuration} record, as shown below.

A typical configuration, where we manually specify the idle timeout (in
seconds), might look like this:

@lisp
(service home-unclutter-service-type
         (home-unclutter-configuration
          (idle-timeout 2)))
@end lisp
@end defvar

@deftp {Tipo de dados} home-unclutter-configuration
The configuration record for @code{home-unclutter-service-type}.

@table @asis
@item @code{unclutter} (default: @code{unclutter}) (type: file-like)
Unclutter package to use.

@item @code{idle-timeout} (default: @code{5}) (type: integer)
A timeout in seconds after which to hide cursor.
@end table

@end deftp

@defvar home-xmodmap-service-type
This is the service type for the
@uref{https://gitlab.freedesktop.org/xorg/app/xmodmap,xmodmap} utility to
modify keymaps and pointer button mappings under the Xorg display server.
Its associated value must be a @code{home-xmodmap-configuration} record, as
shown below.

The @code{key-map} field takes a list of objects, each of which is either a
@dfn{statement} (a string) or an @dfn{assignment} (a pair of strings).  As
an example, the snippet below swaps around the @kbd{Caps_Lock} and the
@kbd{Control_L} keys, by first removing the keysyms (on the right-hand side)
from the corresponding modifier maps (on the left-hand side), re-assigning
them by swapping each other out, and finally adding back the keysyms to the
modifier maps.

@lisp
(service home-xmodmap-service-type
         (home-xmodmap-configuration
          (key-map '(("remove Lock" . "Caps_Lock")
                     ("remove Control" . "Control_L")
                     ("keysym Control_L" . "Caps_Lock")
                     ("keysym Caps_Lock" . "Control_L")
                     ("add Lock" . "Caps_Lock")
                     ("add Control" . "Control_L")))))
@end lisp
@end defvar

@deftp {Tipo de dados} home-xmodmap-configuration
The configuration record for @code{home-xmodmap-service-type}.  Its
available fields are:

@table @asis
@item @code{xmodmap} (default: @code{xmodmap}) (type: file-like)
The @code{xmodmap} package to use.

@item @code{key-map} (default: @code{'()}) (type: list)
The list of expressions to be read by @code{xmodmap} on service startup.

@end table
@end deftp

@defvar home-startx-command-service-type
Add @command{startx} to the home profile putting it onto @env{PATH}.

The value for this service is a @code{<xorg-configuration>} object which is
passed to the @code{xorg-start-command-xinit} procedure producing the
@command{startx} used.  Default value is @code{(xorg-configuration)}.
@end defvar

@defvar home-darkman-service-type
This is the service type for the
@uref{https://gitlab.com/WhyNotHugo/darkman, Darkman}, a program for
dark-mode and light-mode transitions on Unix-like desktops.  It invokes
scripts in @code{$XDG_DATA_DIRS/dark-mode.d} at sundown, and invokes scripts
in @code{$XDG_DATA_DIRS/light-mode.d} at sunrise.  Darkman tries to
determine the user's current location from:
@itemize
@item The config file.
@item The cache file from last time it ran.
@item Using the system geoclue.
@end itemize
@end defvar

@deftp {Data Type} home-darkman-configuration
The configuration record for @code{home-darkman-service-type}.  Its
available fields are:

@table @asis
@item @code{darkman} (default: @code{darkman}) (type: file-like)
The @code{darkman} package to use.

@item @code{latitude} (type: maybe-number)
Latitude, used at startup or when @code{use-geoclue} is @code{#f}.  More
than one decimal point is generally not needed.

@item @code{longitude} (type: maybe-number)
Longitude, used at startup or when @code{use-geoclue} is @code{#f}.  More
than one decimal point is generally not needed.

@item @code{use-geoclue} (default: @code{#f}) (type: boolean)
Whether to use a local geoclue instance to determine the current location.
Setting this to false without explicitly setting latitude and longtitude
disables automatic transitions entirely.

@item @code{dbus-server} (default: @code{#t}) (type: boolean)
Whether to expose the current mode via darkman's own D-Bus API.

@item @code{portal} (default: @code{#t}) (type: boolean)
Whether to expose the current mode via the XDG settings portal D-Bus API.

@end table
@end deftp

@defvar home-gcr-ssh-agent-service-type

GNOME Keyring used to be able to act as a wrapper over @command{ssh-agent}.
It would display a graphical password entry dialog, including a checkbox to
remember the password, which, if selected, would allow fully passwordless
use of that key.

The SSH functionality is disabled by default in
@command{gnome-keyring-daemon} builds since version
@uref{https://gitlab.gnome.org/GNOME/gnome-keyring/-/commit25c5a1982467802fa12c6852b03c57924553ba73,
1.46}.  It has been
@uref{https://gitlab.gnome.org/GNOME/gcr/-/merge_requests/67, moved} into
@command{gcr-ssh-agent}, which is part of the @code{gcr} package.

To enable the SSH agent functionality it is sufficient to add the following
to your Home configuration.

@lisp
(use-modules (gnu home services gnome) ;for 'home-gcr-ssh-agent-service-type'
             @dots{})

(home-environment
  (services
    (list
      @dots{}
      (service home-gcr-ssh-agent-service-type))))
@end lisp
@end defvar

@deftp {Data Type} gcr-ssh-agent-configuration
The configuration record for @code{home-gcr-ssh-agent-service-type}.  Its
available fields are:

@table @asis
@item @code{package} (default: @code{gcr}) (type: package)
The @code{gcr} package to use.

@item @code{log-file} (type: maybe-string)
Where the service will write its logs.  If unset, it defaults to
@file{$HOME/.local/state/shepherd/gcr-ssh-agent.log}.

@end table
@end deftp

@node Guix Home Services
@subsection Guix Home Services

The @code{(gnu home services guix)} module provides services for
user-specific Guix configuration.

@defvar home-channels-service-type
This is the service type for managing
@file{$XDG_CONFIG_HOME/guix/channels.scm}, the file that controls the
channels received on @command{guix pull} (@pxref{Canais}).  Its associated
value is a list of @code{channel} records, defined in the @code{(guix
channels)} module.

Generally, it is better to extend this service than to directly configure
it, as its default value is the default guix channel(s)  defined by
@code{%default-channels}.  If you configure this service directly, be sure
to include a guix channel.  @xref{Especificando canais adicionais} and
@ref{Usando um canal Guix personalizado} for more details.

A typical extension for adding a channel might look like this:

@lisp
(simple-service 'variant-packages-service
                home-channels-service-type
                (list
                 (channel
                  (name 'variant-packages)
                  (url "https://example.org/variant-packages.git"))))
@end lisp
@end defvar

@node Backup Home Services
@subsection Backup Services

The @code{(gnu home services backup)} module offers services for backing up
file system trees.  For now, it provides the
@code{home-restic-backup-service-type}.

With @code{home-restic-backup-service-type}, you can periodically back up
directories and files with @uref{https://restic.net/, Restic}, which
supports end-to-end encryption and deduplication.  Consider the following
configuration:

@lisp
(use-modules (gnu home services backup) ;for 'restic-backup-job', 'home-restic-backup-service-type'
             (gnu packages sync)        ;for 'rclone'
             @dots{})

(home-environment

  (packages (list rclone    ;for use by restic
                  @dots{}))
  (services
    (list
      @dots{}
      (simple-service 'backup-jobs
                      home-restic-backup-service-type
                      (list (restic-backup-job
                              (name "remote-ftp")
                              (repository "rclone:remote-ftp:backup/restic")
                              (password-file "/home/alice/.restic")
                              ;; Every day at 23.
                              (schedule "0 23 * * *")
                              (files '("/home/alice/.restic"
                                       "/home/alice/.config/rclone"
                                       "/home/alice/Pictures"))))))))
@end lisp

In general it is preferable to extend the
@code{home-restic-backup-service-type}, as shown in the example above.  This
is because it takes care of wrapping everything with @code{for-home}, which
enables the @code{home-restic-backup-service-type} and
@code{restic-backup-service-type} to share the same codebase.

For a custom configuration, wrap your @code{restic-backup-configuration} in
@code{for-home}, as in this example:

@lisp
(use-modules (gnu services)             ;for 'for-home'
             (gnu services backup)      ;for 'restic-backup-job' and 'restic-backup-configuration'
             (gnu home services backup) ;for 'home-restic-backup-service-type'
             (gnu packages sync)        ;for 'rclone'
             @dots{})

(home-environment

  (packages (list rclone    ;for use by restic
                  @dots{}))
  (services
    (list
      @dots{}
      (service home-restic-backup-service-type
               (for-home
                (restic-backup-configuration
                 (jobs (list @dots{}))))))))
@end lisp

You can refer to @pxref{Serviços diversos,
@code{restic-backup-service-type}} for details about
@code{restic-backup-configuration} and @code{restic-backup-job}.  The only
difference is that the @code{home-restic-backup-service-type} will ignore
the @code{user} and @code{group} field of @code{restic-backup-job}.

@node Fonts Home Services
@subsection Fonts Home Services

The @code{(gnu home services fontutils)} module provides services for
user-specific Fontconfig setup.  The
@uref{https://www.freedesktop.org/wiki/Software/fontconfig,Fontconfig}
library is used by many applications to access fonts on the system.

@defvar home-fontconfig-service-type
This is the service type for generating configurations for Fontconfig.  Its
associated value is a list of either strings (or gexps) pointing to fonts
locations, or SXML (@pxref{SXML,,, guile, GNU Guile Reference Manual})
fragments to be converted into XML and put inside the main @code{fontconfig}
node.

Generally, it is better to extend this service than to directly configure
it, as its default value is the default Guix Home's profile font
installation path (@file{~/.guix-home/profile/share/fonts}).  If you
configure this service directly, be sure to include the above directory.

Here's how you'd extend it to include fonts installed with the Nix package
manager, and to prefer your favourite monospace font:

@lisp
(simple-service 'additional-fonts-service
                home-fontconfig-service-type
                (list "~/.nix-profile/share/fonts"
                      '(alias
                        (family "monospace")
                        (prefer
                         (family "Liberation Mono")))))
@end lisp
@end defvar

@node Sound Home Services
@subsection Sound Home Services

The @code{(gnu home services sound)} module provides services related to
sound support.

@cindex PulseAudio, serviço pessoal
@cindex RTP, for PulseAudio
@subsubheading PulseAudio RTP Streaming Services

The following services dynamically reconfigure the
@uref{https://pulseaudio.org,PulseAudio sound server}: they let you toggle
broadcast of audio output over the network using the @acronym{RTP, real-time
transport protocol} and, correspondingly, playback of sound received over
RTP.  Once @code{home-pulseaudio-rtp-sink-service-type} is among your home
services, you can start broadcasting audio output by running this command:

@example
herd start pulseaudio-rtp-sink
@end example

You can then run a PulseAudio-capable mixer, such as @code{pavucontrol} or
@code{pulsemixer} (both from the same-named package) to control which audio
stream(s) should be sent to the RTP ``sink''.

By default, audio is broadcasted to a multicast address: any device on the
@acronym{LAN, local area network} receives it and may play it.  Using
multicast in this way puts a lot of pressure on the network and degrades its
performance, so you may instead prefer sending to specifically one device.
The first way to do that is by specifying the IP address of the target
device when starting the service:

@example
herd start pulseaudio-rtp-sink 192.168.1.42
@end example

The other option is to specify this IP address as the one to use by default
in your home environment configuration:

@lisp
(service home-pulseaudio-rtp-sink-service-type
         "192.168.1.42")
@end lisp

On the device where you intend to receive and play the RTP stream, you can
use @code{home-pulseaudio-rtp-source-service-type}, like so:

@lisp
(service home-pulseaudio-rtp-source-service-type)
@end lisp

This will then let you start the receiving module for PulseAudio:

@example
herd start pulseaudio-rtp-source
@end example

Again, by default it will listen on the multicast address.  If, instead,
you'd like it to listen for direct incoming connections, you can do that by
running:

@lisp
(service home-pulseaudio-rtp-source-service-type
         "0.0.0.0")
@end lisp

The reference of these services is given below.

@defvar home-pulseaudio-rtp-sink-service-type
@defvarx home-pulseaudio-rtp-source-service-type
This is the type of the service to send, respectively receive, audio streams
over @acronym{RTP, real-time transport protocol}.

The value associated with this service is the IP address (a string)  where
to send, respectively receive, the audio stream.  By default, audio is
sent/received on multicast address @code{%pulseaudio-rtp-multicast-address}.

This service defines one Shepherd service: @code{pulseaudio-rtp-sink},
respectively @code{pulseaudio-rtp-source}.  The service is not started by
default, so you have to explicitly start it when you want to turn it on, as
in this example:

@example
herd start pulseaudio-rtp-sink
@end example

Stopping the Shepherd service turns off broadcasting.
@end defvar

@defvar %pulseaudio-rtp-multicast-address
This is the multicast address used by default by the two services above.
@end defvar

@cindex PipeWire, serviço pessoal
@subsubheading PipeWire Home Service

@uref{https://pipewire.org, PipeWire} provides a low-latency, graph-based
audio and video processing service.  In addition to its native protocol, it
can also be used as a replacement for both JACK and PulseAudio.

While PipeWire provides the media processing and API, it does not, directly,
know about devices such as sound cards, nor how you might want to connect
applications, hardware, and media processing filters.  Instead, PipeWire
relies on a @dfn{session manager} to specify all these relationships.  While
you may use any session manager you wish, for most people the
@url{https://pipewire.pages.freedesktop.org/wireplumber/, WirePlumber}
session manager, a reference implementation provided by the PipeWire project
itself, suffices, and that is the one @code{home-pipewire-service-type}
uses.

PipeWire can be used as a replacement for PulseAudio by setting
@code{enable-pulseaudio?} to @code{#t} in
@code{home-pipewire-configuration}, so that existing PulseAudio clients may
use it without any further configuration.

In addition, JACK clients may connect to PipeWire by using the
@command{pw-jack} program, which comes with PipeWire.  Simply prefix the
command with @command{pw-jack} when you run it, and audio data should go
through PipeWire:

@example
pw-jack mpv -ao=jack sound-file.wav
@end example

For more information on PulseAudio emulation, see
@uref{https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/Config-PulseAudio},
for JACK, see
@uref{https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/Config-JACK}.

As PipeWire does not use @code{dbus} to start its services on demand (as
PulseAudio does), @code{home-pipewire-service-type} uses Shepherd to start
services when logged in, provisioning the @code{pipewire},
@code{wireplumber}, and, if configured, @code{pipewire-pulseaudio}
services.  @xref{Shepherd Home Service}.

@defvar home-pipewire-service-type
This provides the service definition for @command{pipewire}, which will run
on login.  Its value is a @code{home-pipewire-configuration} object.

To start the service, add it to the @code{service} field of your
@code{home-environment}, such as:

@lisp
(service home-pipewire-service-type)
@end lisp
@end defvar

@deftp {Tipo de dados} home-pipewire-configuration
Available @code{home-pipewire-configuration} fields are:

@table @asis
@item @code{pipewire} (default: @code{pipewire}) (type: file-like)
The PipeWire package to use.

@item @code{wireplumber} (default: @code{wireplumber}) (type: file-like)
The WirePlumber package to use.

@item @code{enable-pulseaudio?} (default: @code{#t}) (type: boolean)
When true, enable PipeWire's PulseAudio emulation support, allowing
PulseAudio clients to use PipeWire transparently.

@item @code{extra-content} (default: @code{""}) (type: string)
Extra content to add to the end of @file{~/.config/alsa/asoundrc}.
@end table
@end deftp

@node Mail Home Services
@subsection Mail Home Services

The @code{(gnu home services mail)} module provides services that help you
set up the tools to work with emails in your home environment.

@cindex msmtp
@uref{https://marlam.de/msmtp, MSMTP} is a @acronym{SMTP, Simple Mail
Transfer Protocol} client.  It sends mail to a predefined SMTP server that
takes care of proper delivery.

The service reference is given below.

@defvar home-msmtp-service-type
This is the service type for @command{msmtp}.  Its value must be a
@code{home-msmtp-configuration}, as shown below.  It provides the
@file{~/.config/msmtp/config} file.

As an example, here is how you would configure @code{msmtp} for a single
account:

@lisp
(service home-msmtp-service-type
         (home-msmtp-configuration
          (accounts
           (list
            (msmtp-account
             (name "alice")
             (configuration
              (msmtp-configuration
               (host "mail.example.org")
               (port 587)
               (user "alice")
               (password-eval "pass Mail/alice"))))))))
@end lisp
@end defvar

@c %start of fragment

@deftp {Tipo de dados} home-msmtp-configuration
Available @code{home-msmtp-configuration} fields are:

@table @asis
@item @code{defaults} (type: msmtp-configuration)
The configuration that will be set as default for all accounts.

@item @code{accounts} (default: @code{'()}) (type: list-of-msmtp-accounts)
A list of @code{msmtp-account} records which contain information about all
your accounts.

@item @code{default-account} (type: maybe-string)
Set the default account.

@item @code{extra-content} (default: @code{""}) (type: string)
Extra content appended as-is to the configuration file.  Run @command{man
msmtp} for more information about the configuration file format.

@end table

@end deftp

@c %end of fragment

@c %start of fragment

@deftp {Tipo de dados} msmtp-account
Available @code{msmtp-account} fields are:

@table @asis
@item @code{name} (type: string)
The unique name of the account.

@item @code{configuration} (type: msmtp-configuration)
The configuration for this given account.

@end table

@end deftp

@c %end of fragment

@c %start of fragment

@deftp {Tipo de dados} msmtp-configuration
Available @code{msmtp-configuration} fields are:

@table @asis
@item @code{auth?} (type: maybe-boolean)
Enable or disable authentication.

@item @code{tls?} (type: maybe-boolean)
Enable or disable TLS (also known as SSL) for secured connections.

@item @code{tls-starttls?} (type: maybe-boolean)
Choose the TLS variant: start TLS from within the session (‘on’, default),
or tunnel the session through TLS (‘off’).

@item @code{tls-trust-file} (type: maybe-string)
Activate server certificate verification using a list of trusted
Certification Authorities (CAs).

@item @code{log-file} (type: maybe-string)
Enable logging to the specified file.  An empty argument disables logging.
The file name ‘-’ directs the log information to standard output.

@item @code{host} (type: maybe-string)
The SMTP server to send the mail to.

@item @code{port} (type: maybe-integer)
The port that the SMTP server listens on.  The default is 25 ("smtp"),
unless TLS without STARTTLS is used, in which case it is 465 ("smtps").

@item @code{user} (type: maybe-string)
Set the user name for authentication.

@item @code{from} (type: maybe-string)
Set the envelope-from address.

@item @code{password-eval} (type: maybe-string)
Set the password for authentication to the output (stdout) of the command
cmd.

@item @code{extra-content} (default: @code{""}) (type: string)
Extra content appended as-is to the configuration block.  Run @command{man
msmtp} for more information about the configuration file format.

@end table

@end deftp

@c %end of fragment

@node Messaging Home Services
@subsection Messaging Home Services

@cindex znc
The @uref{https://znc.in, ZNC bouncer} can be run as a daemon to manage your
IRC presence.  With the @code{(gnu home services messaging)} service, you
can configure ZNC to run upon login.

You will have to provide a @file{~/.znc/configs/znc.conf} separately.

Here is an example of a service and its configuration that you could add to
the @code{services} field of your @code{home-environment}:

@lisp
(service home-znc-service-type)
@end lisp

@defvar home-znc-service-type
This is the type of the ZNC home service, whose value is a
@code{home-znc-configuration} object.
@end defvar

@deftp {Tipo de dados} home-znc-configuration
Available @code{home-znc-configuration} fields are:

@table @asis
@item @code{znc} (default: @code{znc}) (type: file-like)
The ZNC package to use.

@item @code{extra-options} (default: @code{'()})
Extra options will be passed to @command{znc}, please run @command{man znc}
for more information.

@end table
@end deftp

@cindex irc-bot
@cindex snuik
The @uref{https://gitlab.com/janneke/snuik, Snuik IRC bot} can be run as a
daemon to aid talking to users that are currently offline.  With the
@code{(gnu home services messaging)} service, you can configure Snuik to run
upon login.

@defvar home-snuik-service-type
This is the type of the Snuik home service, whose value is a
@code{home-snuik-configuration} object.
@end defvar

You may specify a custom configuration by providing a
@code{snuik-configuration} record, exactly like for
@code{snuik-service-type} and wrapping it in @code{for-home}.  Here is an
example of a service and its configuration that you could add to the
@code{services} field of your @code{home-environment}:

@lisp
(service home-snuik-service-type
         (for-home
          (snuik-configuration
           (server "irc.oftc.net")
           (nick "sneek")
           (password "snuik is sneeky")
           (channels '("#reproducible-builds")))))
@end lisp

@node Media Home Services
@subsection Media Home Services

@cindex kodi
The @uref{https://kodi.tv, Kodi media center} can be run as a daemon on a
media server.  With the @code{(gnu home services kodi)} service, you can
configure Kodi to run upon login.

Here is an example of a service and its configuration that you could add to
the @code{services} field of your @code{home-environment}:

@lisp
(service home-kodi-service-type
  (home-kodi-configuration
   (extra-options '("--settings="<settings-file>"))))
@end lisp

@defvar home-kodi-service-type
This is the type of the Kodi home service, whose value is a
@code{home-kodi-configuration} object.
@end defvar

@deftp {Tipo de dados} home-kodi-configuration
Available @code{home-kodi-configuration} fields are:

@table @asis
@item @code{kodi} (default: @code{kodi}) (type: file-like)
The Kodi package to use.

@item @code{extra-options} (default: @code{'()})
Extra options will be passed to @command{kodi}, please run @command{man
kodi} for more information.

@end table
@end deftp

@c This is ugly, but upstream does *not* capitalize the ``m'' even when
@c at the beginning of a sentence.  So let us follow the branding.
@node mpv Media Player
@subsection mpv Media Player

@cindex mpv, Home Service
@cindex mpv, configuration
Configuring the @uref{https://mpv.io/, mpv media player} can be somewhat
daunting task, due to the sheer amount of options available, especially if
one wants to be able to inherit the configuration in their code.  The
@code{home-mpv-service-type} is provided to help with that problem.  When
the service is added to your home environment, file based on the passed
configuration is generated and placed into the correct location.

Due to the bug #74748, it does not use Guix Records to represent the
configuration, but uses keyword arguments to achieve similar result.
Example follows:

@lisp
(service home-mpv-service-type
         (make-home-mpv-configuration
          #:global (make-mpv-profile-configuration
                    #:fullscreen? #t
                    #:alang '("jpn" "eng"))))
@end lisp

@defvar home-mpv-service-type
This is the type of the mpv home service, whose value is a
@code{home-mpv-configuration} object.
@end defvar

@deffn {Procedure} make-home-mpv-configuration
Return a new instance of @code{home-mpv-configuration}.  Available keyword
arguments are:

@table @asis
@item @code{inherit} (default: @code{#t})
Inherit fields from an another instance.

@item @code{global} (default: @code{(make-mpv-profile-configuration)})
The global configuration preceding all profiles.

@item @code{profiles} (default: @code{()})
An alist containing configuration for any additional profiles to include in
the configuration file.

@lisp
(make-home-mpv-configuration
 #:profiles `((fullscreen . ,(make-mpv-profile-configuration
                              #:fullscreen? #t))))
@end lisp

@item @code{extra-config} (default: @code{#f})
Additional content to include in the configuration file.  It is placed at
the end of the file.

@end table
@end deffn

@deffn {Procedure} make-mpv-profile-configuration
Return a new instance of @code{mpv-profile-configuration}.  As above, it
also supports the @code{#:inherit} argument.  Additionally it supports
keyword arguments named after the options of @command{mpv}.  Hence
@option{--fullscreen} (or @code{fullscreen} in the configuration file)
becomes @code{#:fullscreen?}.

Few options are using their aliases instead.  @option{audio} instead of
@option{aid}, @option{video} instead of @option{vid}, @option{sub} instead
of @option{sid}, @option{screenshot-directory} instead of
@option{screenshot-dir} and @option{watch-later-directory} instead of
@option{watch-later-dir}.

Valid values for the fields depend on their type.

@table @asis
@item Flags
The value should be @code{#f} or @code{#t}.

@item Numerical fields
Integer and integer64 fields are validated by @code{integer?}, float and
double fields by @code{real?}.  Ranges are checked when applicable.

@item Aspect
Same as integer.

@item ByteSize
Same as integer64.

@item Choice
The value should be a symbol representing member of the enumeration.  If the
choice has @samp{or ...} part, it can also be value of that alternative
type.

@item @var{type} list
The value should be a list of the @var{type}.

@end table

Other types accept strings, with validation of the values where possible
(e.g. type @samp{Color} is validated, but type @samp{Audio channels or
channel map} is not).  If an option is marked as taking a file, values
satisfying @code{file-like?} can also be used.

The full list of currently supported keyword arguments is below.  For the
types, allowed values and full description please refer to the @command{mpv
--list-options} and @uref{https://mpv.io/manual/stable/#options, mpv
manual}.

Only set fields are output to the configuration file.  Accessors are
provided for every field, returning either their value or a sentinel object
@code{%unset-value} (from @code{(gnu services configuration)}).

@code{ab-loop-a}, @code{ab-loop-b}, @code{ab-loop-count},
@code{access-references?}, @code{ad}, @code{ad-lavc-ac3drc},
@code{ad-lavc-downmix?}, @code{ad-lavc-o}, @code{ad-lavc-threads},
@code{ad-queue-enable?}, @code{ad-queue-max-bytes},
@code{ad-queue-max-samples}, @code{ad-queue-max-secs}, @code{af},
@code{audio}, @code{alang}, @code{allow-delayed-peak-detect?},
@code{alsa-buffer-time}, @code{alsa-ignore-chmap?},
@code{alsa-mixer-device}, @code{alsa-mixer-index}, @code{alsa-mixer-name},
@code{alsa-non-interleaved?}, @code{alsa-periods}, @code{alsa-resample?},
@code{ao}, @code{ao-null-broken-delay?}, @code{ao-null-broken-eof?},
@code{ao-null-buffer}, @code{ao-null-channel-layouts},
@code{ao-null-format}, @code{ao-null-latency}, @code{ao-null-outburst},
@code{ao-null-speed}, @code{ao-null-untimed?}, @code{ao-pcm-append?},
@code{ao-pcm-file}, @code{ao-pcm-waveheader?}, @code{archive-exts},
@code{audio-backward-batch}, @code{audio-backward-overlap},
@code{audio-buffer}, @code{audio-channels}, @code{audio-client-name},
@code{audio-delay}, @code{audio-demuxer}, @code{audio-device},
@code{audio-display}, @code{audio-exclusive?}, @code{audio-exts},
@code{audio-fallback-to-null?}, @code{audio-file-auto},
@code{audio-file-paths}, @code{audio-files}, @code{audio-format},
@code{audio-normalize-downmix?}, @code{audio-pitch-correction?},
@code{audio-resample-cutoff}, @code{audio-resample-filter-size},
@code{audio-resample-linear?}, @code{audio-resample-max-output-size},
@code{audio-resample-phase-shift}, @code{audio-reversal-buffer},
@code{audio-samplerate}, @code{audio-spdif}, @code{audio-stream-silence?},
@code{audio-swresample-o}, @code{audio-wait-open},
@code{auto-window-resize?}, @code{autocreate-playlist}, @code{autofit},
@code{autofit-larger}, @code{autofit-smaller}, @code{autoload-files?},
@code{autosync}, @code{background}, @code{background-color},
@code{blend-subtitles}, @code{bluray-device}, @code{border?},
@code{border-background}, @code{brightness}, @code{cache},
@code{cache-on-disk?}, @code{cache-pause?}, @code{cache-pause-initial?},
@code{cache-pause-wait}, @code{cache-secs}, @code{cdda-cdtext?},
@code{cdda-device}, @code{cdda-overlap}, @code{cdda-paranoia},
@code{cdda-sector-size}, @code{cdda-skip?}, @code{cdda-span-a},
@code{cdda-span-b}, @code{cdda-speed}, @code{cdda-toc-offset},
@code{chapter-merge-threshold}, @code{chapter-seek-threshold},
@code{chapters-file}, @code{clipboard-backends}, @code{clipboard-monitor?},
@code{config?}, @code{container-fps-override}, @code{contrast},
@code{cookies?}, @code{cookies-file}, @code{corner-rounding},
@code{correct-downscaling?}, @code{correct-pts?}, @code{cover-art-auto},
@code{cover-art-files}, @code{cover-art-whitelist}, @code{cscale},
@code{cscale-antiring}, @code{cscale-blur}, @code{cscale-clamp},
@code{cscale-param1}, @code{cscale-param2}, @code{cscale-radius},
@code{cscale-taper}, @code{cscale-window}, @code{cscale-wparam},
@code{cscale-wtaper}, @code{cursor-autohide},
@code{cursor-autohide-fs-only?}, @code{deband?}, @code{deband-grain},
@code{deband-iterations}, @code{deband-range}, @code{deband-threshold},
@code{deinterlace}, @code{deinterlace-field-parity}, @code{demuxer},
@code{demuxer-backward-playback-step}, @code{demuxer-cache-dir},
@code{demuxer-cache-unlink-files}, @code{demuxer-cache-wait?},
@code{demuxer-donate-buffer?}, @code{demuxer-hysteresis-secs},
@code{demuxer-lavf-allow-mimetype?}, @code{demuxer-lavf-analyzeduration},
@code{demuxer-lavf-buffersize}, @code{demuxer-lavf-format},
@code{demuxer-lavf-hacks?}, @code{demuxer-lavf-linearize-timestamps},
@code{demuxer-lavf-o}, @code{demuxer-lavf-probe-info},
@code{demuxer-lavf-probescore}, @code{demuxer-lavf-probesize},
@code{demuxer-lavf-propagate-opts?}, @code{demuxer-max-back-bytes},
@code{demuxer-max-bytes}, @code{demuxer-mkv-crop-compat?},
@code{demuxer-mkv-probe-start-time?},
@code{demuxer-mkv-probe-video-duration},
@code{demuxer-mkv-subtitle-preroll},
@code{demuxer-mkv-subtitle-preroll-secs},
@code{demuxer-mkv-subtitle-preroll-secs-index},
@code{demuxer-rawaudio-channels}, @code{demuxer-rawaudio-format},
@code{demuxer-rawaudio-rate}, @code{demuxer-rawvideo-codec},
@code{demuxer-rawvideo-format}, @code{demuxer-rawvideo-fps},
@code{demuxer-rawvideo-h}, @code{demuxer-rawvideo-mp-format},
@code{demuxer-rawvideo-size}, @code{demuxer-rawvideo-w},
@code{demuxer-readahead-secs}, @code{demuxer-seekable-cache},
@code{demuxer-termination-timeout}, @code{demuxer-thread?},
@code{directory-filter-types}, @code{directory-mode},
@code{display-fps-override}, @code{display-tags}, @code{dither},
@code{dither-depth}, @code{dither-size-fruit}, @code{drag-and-drop},
@code{dscale}, @code{dscale-antiring}, @code{dscale-blur},
@code{dscale-clamp}, @code{dscale-param1}, @code{dscale-param2},
@code{dscale-radius}, @code{dscale-taper}, @code{dscale-window},
@code{dscale-wparam}, @code{dscale-wtaper}, @code{dump-stats},
@code{dvbin-card}, @code{dvbin-channel-switch-offset}, @code{dvbin-file},
@code{dvbin-full-transponder?}, @code{dvbin-prog}, @code{dvbin-timeout},
@code{dvd-angle}, @code{dvd-device}, @code{dvd-speed}, @code{edition},
@code{egl-config-id}, @code{egl-output-format}, @code{embeddedfonts?},
@code{end}, @code{error-diffusion}, @code{external-files},
@code{fbo-format}, @code{focus-on}, @code{force-media-title},
@code{force-render?}, @code{force-rgba-osd-rendering?},
@code{force-seekable?}, @code{force-window}, @code{force-window-position?},
@code{framedrop}, @code{frames}, @code{fs-screen}, @code{fs-screen-name},
@code{fullscreen?}, @code{gamma}, @code{gamma-auto?}, @code{gamma-factor},
@code{gamut-mapping-mode}, @code{gapless-audio}, @code{geometry},
@code{glsl-shader-opts}, @code{glsl-shaders}, @code{gpu-api},
@code{gpu-context}, @code{gpu-debug?}, @code{gpu-dumb-mode},
@code{gpu-hwdec-interop}, @code{gpu-shader-cache?},
@code{gpu-shader-cache-dir}, @code{gpu-sw?}, @code{gpu-tex-pad-x},
@code{gpu-tex-pad-y}, @code{hdr-compute-peak}, @code{hdr-contrast-recovery},
@code{hdr-contrast-smoothness}, @code{hdr-peak-decay-rate},
@code{hdr-peak-percentile}, @code{hdr-scene-threshold-high},
@code{hdr-scene-threshold-low}, @code{hidpi-window-scale?},
@code{hls-bitrate}, @code{hr-seek}, @code{hr-seek-demuxer-offset},
@code{hr-seek-framedrop?}, @code{http-header-fields}, @code{http-proxy},
@code{hue}, @code{hwdec}, @code{hwdec-codecs}, @code{hwdec-extra-frames},
@code{hwdec-image-format}, @code{hwdec-software-fallback},
@code{icc-3dlut-size}, @code{icc-cache?}, @code{icc-cache-dir},
@code{icc-force-contrast}, @code{icc-intent}, @code{icc-profile},
@code{icc-profile-auto?}, @code{icc-use-luma?}, @code{idle},
@code{ignore-path-in-watch-later-config?}, @code{image-display-duration},
@code{image-exts}, @code{image-lut}, @code{image-lut-type},
@code{image-subs-video-resolution?}, @code{include}, @code{index},
@code{initial-audio-sync?}, @code{input-ar-delay}, @code{input-ar-rate},
@code{input-builtin-bindings?}, @code{input-builtin-dragging?},
@code{input-commands}, @code{input-conf}, @code{input-cursor?},
@code{input-cursor-passthrough?}, @code{input-default-bindings?},
@code{input-doubleclick-time}, @code{input-dragging-deadzone},
@code{input-ime?}, @code{input-ipc-client}, @code{input-ipc-server},
@code{input-key-fifo-size}, @code{input-media-keys?},
@code{input-preprocess-wheel?}, @code{input-right-alt-gr?},
@code{input-terminal?}, @code{input-test?},
@code{input-touch-emulate-mouse?}, @code{input-vo-keyboard?},
@code{interpolation?}, @code{interpolation-preserve?},
@code{interpolation-threshold}, @code{inverse-tone-mapping?},
@code{jack-autostart?}, @code{jack-connect?}, @code{jack-name},
@code{jack-port}, @code{jack-std-channel-layout}, @code{keep-open},
@code{keep-open-pause?}, @code{keepaspect?}, @code{keepaspect-window?},
@code{lavfi-complex}, @code{length}, @code{libplacebo-opts},
@code{linear-downscaling?}, @code{linear-upscaling?},
@code{load-auto-profiles}, @code{load-commands?}, @code{load-console?},
@code{load-positioning?}, @code{load-scripts?}, @code{load-select?},
@code{load-stats-overlay?}, @code{load-unsafe-playlists?}, @code{log-file},
@code{loop-file}, @code{loop-playlist}, @code{lut}, @code{lut-type},
@code{mc}, @code{media-controls?}, @code{merge-files?},
@code{metadata-codepage}, @code{mf-fps}, @code{mf-type},
@code{monitoraspect}, @code{monitorpixelaspect}, @code{msg-color?},
@code{msg-level}, @code{msg-module?}, @code{msg-time?}, @code{mute?},
@code{native-fs?}, @code{native-keyrepeat?}, @code{native-touch?},
@code{network-timeout}, @code{oac}, @code{oacopts}, @code{ocopy-metadata?},
@code{of}, @code{ofopts}, @code{on-all-workspaces?}, @code{ontop?},
@code{ontop-level}, @code{opengl-check-pattern-a},
@code{opengl-check-pattern-b}, @code{opengl-early-flush}, @code{opengl-es},
@code{opengl-glfinish?}, @code{opengl-pbo?},
@code{opengl-rectangle-textures?}, @code{opengl-swapinterval},
@code{opengl-waitvsync?}, @code{orawts?}, @code{ordered-chapters?},
@code{ordered-chapters-files}, @code{oremove-metadata}, @code{osc?},
@code{osd-align-x}, @code{osd-align-y}, @code{osd-back-color},
@code{osd-bar?}, @code{osd-bar-align-x}, @code{osd-bar-align-y},
@code{osd-bar-h}, @code{osd-bar-marker-min-size},
@code{osd-bar-marker-scale}, @code{osd-bar-marker-style},
@code{osd-bar-outline-size}, @code{osd-bar-w}, @code{osd-blur},
@code{osd-bold?}, @code{osd-border-style}, @code{osd-color},
@code{osd-duration}, @code{osd-font}, @code{osd-font-provider},
@code{osd-font-size}, @code{osd-fonts-dir}, @code{osd-fractions?},
@code{osd-italic?}, @code{osd-justify}, @code{osd-level},
@code{osd-margin-x}, @code{osd-margin-y}, @code{osd-msg1}, @code{osd-msg2},
@code{osd-msg3}, @code{osd-on-seek}, @code{osd-outline-color},
@code{osd-outline-size}, @code{osd-playing-msg},
@code{osd-playing-msg-duration}, @code{osd-playlist-entry},
@code{osd-scale}, @code{osd-scale-by-window?}, @code{osd-selected-color},
@code{osd-selected-outline-color}, @code{osd-shadow-offset},
@code{osd-spacing}, @code{osd-status-msg}, @code{oset-metadata}, @code{ovc},
@code{ovcopts}, @code{panscan}, @code{pause?}, @code{pipewire-buffer},
@code{pipewire-remote}, @code{pipewire-volume-mode}, @code{pitch},
@code{play-direction}, @code{player-operation-mode}, @code{playlist-exts},
@code{playlist-start}, @code{prefetch-playlist?}, @code{profile},
@code{pulse-allow-suspended?}, @code{pulse-buffer}, @code{pulse-host},
@code{pulse-latency-hacks?}, @code{quiet?}, @code{really-quiet?},
@code{rebase-start-time?}, @code{referrer}, @code{replaygain},
@code{replaygain-clip?}, @code{replaygain-fallback},
@code{replaygain-preamp}, @code{reset-on-next-file},
@code{resume-playback?}, @code{resume-playback-check-mtime?},
@code{rtsp-transport}, @code{saturation}, @code{save-position-on-quit?},
@code{save-watch-history?}, @code{scale}, @code{scale-antiring},
@code{scale-blur}, @code{scale-clamp}, @code{scale-param1},
@code{scale-param2}, @code{scale-radius}, @code{scale-taper},
@code{scale-window}, @code{scale-wparam}, @code{scale-wtaper},
@code{scaler-resizes-only?}, @code{screen}, @code{screen-name},
@code{screenshot-avif-encoder}, @code{screenshot-avif-opts},
@code{screenshot-avif-pixfmt}, @code{screenshot-directory},
@code{screenshot-format}, @code{screenshot-high-bit-depth?},
@code{screenshot-jpeg-quality}, @code{screenshot-jpeg-source-chroma?},
@code{screenshot-jxl-distance}, @code{screenshot-jxl-effort},
@code{screenshot-png-compression}, @code{screenshot-png-filter},
@code{screenshot-sw?}, @code{screenshot-tag-colorspace?},
@code{screenshot-template}, @code{screenshot-webp-compression},
@code{screenshot-webp-lossless?}, @code{screenshot-webp-quality},
@code{script-opts}, @code{scripts}, @code{secondary-sid},
@code{secondary-sub-ass-override}, @code{secondary-sub-delay},
@code{secondary-sub-pos}, @code{secondary-sub-visibility?}, @code{sharpen},
@code{show-in-taskbar?}, @code{shuffle?}, @code{sub}, @code{sigmoid-center},
@code{sigmoid-slope}, @code{sigmoid-upscaling?}, @code{slang},
@code{snap-window?}, @code{speed}, @code{spirv-compiler}, @code{sstep},
@code{start}, @code{stop-playback-on-init-failure?},
@code{stop-screensaver}, @code{stream-buffer-size}, @code{stream-dump},
@code{stream-lavf-o}, @code{stream-record}, @code{stretch-dvd-subs?},
@code{stretch-image-subs-to-screen?}, @code{sub-align-x},
@code{sub-align-y}, @code{sub-ass?}, @code{sub-ass-force-margins?},
@code{sub-ass-justify?}, @code{sub-ass-override},
@code{sub-ass-prune-delay}, @code{sub-ass-scale-with-window?},
@code{sub-ass-style-overrides}, @code{sub-ass-styles},
@code{sub-ass-use-video-data}, @code{sub-ass-video-aspect-override},
@code{sub-ass-vsfilter-color-compat}, @code{sub-auto}, @code{sub-auto-exts},
@code{sub-back-color}, @code{sub-blur}, @code{sub-bold?},
@code{sub-border-style}, @code{sub-clear-on-seek?}, @code{sub-codepage},
@code{sub-color}, @code{sub-create-cc-track?}, @code{sub-delay},
@code{sub-demuxer}, @code{sub-file-paths}, @code{sub-files},
@code{sub-filter-jsre}, @code{sub-filter-regex},
@code{sub-filter-regex-enable?}, @code{sub-filter-regex-plain?},
@code{sub-filter-regex-warn?}, @code{sub-filter-sdh?},
@code{sub-filter-sdh-enclosures}, @code{sub-filter-sdh-harder?},
@code{sub-fix-timing?}, @code{sub-font}, @code{sub-font-provider},
@code{sub-font-size}, @code{sub-fonts-dir}, @code{sub-forced-events-only?},
@code{sub-fps}, @code{sub-gauss}, @code{sub-gray?}, @code{sub-hinting},
@code{sub-italic?}, @code{sub-justify}, @code{sub-lavc-o},
@code{sub-line-spacing}, @code{sub-margin-x}, @code{sub-margin-y},
@code{sub-outline-color}, @code{sub-outline-size},
@code{sub-past-video-end?}, @code{sub-pos}, @code{sub-scale},
@code{sub-scale-by-window?}, @code{sub-scale-signs?},
@code{sub-scale-with-window?}, @code{sub-shadow-offset}, @code{sub-shaper},
@code{sub-spacing}, @code{sub-speed}, @code{sub-stretch-durations?},
@code{sub-use-margins?}, @code{sub-visibility?},
@code{sub-vsfilter-bidi-compat?}, @code{subs-fallback},
@code{subs-fallback-forced}, @code{subs-match-os-language?},
@code{subs-with-matching-audio}, @code{swapchain-depth},
@code{sws-allow-zimg?}, @code{sws-bitexact?}, @code{sws-cgb},
@code{sws-chs}, @code{sws-cs}, @code{sws-cvs}, @code{sws-fast?},
@code{sws-lgb}, @code{sws-ls}, @code{sws-scaler},
@code{target-colorspace-hint}, @code{target-contrast}, @code{target-gamut},
@code{target-lut}, @code{target-peak}, @code{target-prim},
@code{target-trc}, @code{taskbar-progress?}, @code{teletext-page},
@code{temporal-dither?}, @code{temporal-dither-period}, @code{term-osd},
@code{term-osd-bar?}, @code{term-osd-bar-chars}, @code{term-playing-msg},
@code{term-status-msg}, @code{term-title}, @code{terminal?}, @code{title},
@code{title-bar?}, @code{tls-ca-file}, @code{tls-cert-file},
@code{tls-key-file}, @code{tls-verify?}, @code{tone-mapping},
@code{tone-mapping-max-boost}, @code{tone-mapping-param},
@code{tone-mapping-visualize?}, @code{track-auto-selection?}, @code{tscale},
@code{tscale-antiring}, @code{tscale-blur}, @code{tscale-clamp},
@code{tscale-param1}, @code{tscale-param2}, @code{tscale-radius},
@code{tscale-taper}, @code{tscale-window}, @code{tscale-wparam},
@code{tscale-wtaper}, @code{untimed?}, @code{use-embedded-icc-profile?},
@code{use-filedir-conf?}, @code{user-agent}, @code{vaapi-device}, @code{vd},
@code{vd-apply-cropping?}, @code{vd-lavc-assume-old-x264?},
@code{vd-lavc-bitexact?}, @code{vd-lavc-check-hw-profile?},
@code{vd-lavc-dr}, @code{vd-lavc-fast?}, @code{vd-lavc-film-grain},
@code{vd-lavc-framedrop}, @code{vd-lavc-o}, @code{vd-lavc-show-all?},
@code{vd-lavc-skipframe}, @code{vd-lavc-skipidct},
@code{vd-lavc-skiploopfilter}, @code{vd-lavc-threads},
@code{vd-queue-enable?}, @code{vd-queue-max-bytes},
@code{vd-queue-max-samples}, @code{vd-queue-max-secs}, @code{vf},
@code{video}, @code{video-align-x}, @code{video-align-y},
@code{video-aspect-method}, @code{video-aspect-override},
@code{video-backward-batch}, @code{video-backward-overlap},
@code{video-crop}, @code{video-exts}, @code{video-latency-hacks?},
@code{video-margin-ratio-bottom}, @code{video-margin-ratio-left},
@code{video-margin-ratio-right}, @code{video-margin-ratio-top},
@code{video-osd?}, @code{video-output-levels}, @code{video-pan-x},
@code{video-pan-y}, @code{video-recenter?}, @code{video-reversal-buffer},
@code{video-rotate}, @code{video-scale-x}, @code{video-scale-y},
@code{video-sync}, @code{video-sync-max-audio-change},
@code{video-sync-max-factor}, @code{video-sync-max-video-change},
@code{video-timing-offset}, @code{video-unscaled}, @code{video-zoom},
@code{vlang}, @code{vo}, @code{vo-image-avif-encoder},
@code{vo-image-avif-opts}, @code{vo-image-avif-pixfmt},
@code{vo-image-format}, @code{vo-image-high-bit-depth?},
@code{vo-image-jpeg-quality}, @code{vo-image-jpeg-source-chroma?},
@code{vo-image-jxl-distance}, @code{vo-image-jxl-effort},
@code{vo-image-outdir}, @code{vo-image-png-compression},
@code{vo-image-png-filter}, @code{vo-image-tag-colorspace?},
@code{vo-image-webp-compression}, @code{vo-image-webp-lossless?},
@code{vo-image-webp-quality}, @code{vo-kitty-alt-screen?},
@code{vo-kitty-cols}, @code{vo-kitty-config-clear?}, @code{vo-kitty-height},
@code{vo-kitty-left}, @code{vo-kitty-rows}, @code{vo-kitty-top},
@code{vo-kitty-use-shm?}, @code{vo-kitty-width}, @code{vo-null-fps},
@code{vo-sixel-alt-screen?}, @code{vo-sixel-buffered?},
@code{vo-sixel-cols}, @code{vo-sixel-config-clear?}, @code{vo-sixel-dither},
@code{vo-sixel-fixedpalette?}, @code{vo-sixel-height}, @code{vo-sixel-left},
@code{vo-sixel-pad-x}, @code{vo-sixel-pad-y}, @code{vo-sixel-reqcolors},
@code{vo-sixel-rows}, @code{vo-sixel-threshold}, @code{vo-sixel-top},
@code{vo-sixel-width}, @code{vo-tct-256?}, @code{vo-tct-algo},
@code{vo-tct-buffering}, @code{vo-tct-height}, @code{vo-tct-width},
@code{vo-vaapi-scaled-osd?}, @code{vo-vaapi-scaling},
@code{vo-vdpau-chroma-deint?}, @code{vo-vdpau-colorkey},
@code{vo-vdpau-composite-detect?}, @code{vo-vdpau-denoise},
@code{vo-vdpau-force-yuv?}, @code{vo-vdpau-fps}, @code{vo-vdpau-hqscaling},
@code{vo-vdpau-output-surfaces}, @code{vo-vdpau-pullup?},
@code{vo-vdpau-queuetime-fs}, @code{vo-vdpau-queuetime-windowed},
@code{vo-vdpau-sharpen}, @code{volume}, @code{volume-gain},
@code{volume-gain-max}, @code{volume-gain-min}, @code{volume-max},
@code{vulkan-async-compute?}, @code{vulkan-async-transfer?},
@code{vulkan-device}, @code{vulkan-display-display},
@code{vulkan-display-mode}, @code{vulkan-display-plane},
@code{vulkan-queue-count}, @code{vulkan-swap-mode},
@code{watch-history-path}, @code{watch-later-directory},
@code{watch-later-options}, @code{wayland-app-id},
@code{wayland-configure-bounds}, @code{wayland-content-type},
@code{wayland-disable-vsync?}, @code{wayland-edge-pixels-pointer},
@code{wayland-edge-pixels-touch}, @code{wayland-internal-vsync},
@code{wayland-present?}, @code{wid}, @code{window-dragging?},
@code{window-maximized?}, @code{window-minimized?}, @code{window-scale},
@code{write-filename-in-watch-later-config?}, @code{x11-bypass-compositor},
@code{x11-name}, @code{x11-netwm}, @code{x11-present},
@code{x11-wid-title?}, @code{xv-adaptor}, @code{xv-buffers}, @code{xv-ck},
@code{xv-ck-method}, @code{xv-colorkey}, @code{xv-port}, @code{ytdl?},
@code{ytdl-format}, @code{ytdl-raw-options}, @code{zimg-dither},
@code{zimg-fast?}, @code{zimg-scaler}, @code{zimg-scaler-chroma},
@code{zimg-scaler-chroma-param-a}, @code{zimg-scaler-chroma-param-b},
@code{zimg-scaler-param-a}, @code{zimg-scaler-param-b}, and
@code{zimg-threads}.

@end deffn

@node Niri window manager
@subsection Niri window manager

@cindex niri, Home Service
@cindex niri, configuration
@cindex Wayland compositor
@cindex scrollable tiling window manager
The @code{(gnu home services niri)} module provides the
@code{home-niri-service-type} service, which installs and configures
@uref{https://github.com/YaLTeR/niri, Niri}, a scrollable tiling Wayland
compositor. Niri combines traditional tiling window management with smooth
scrolling between workspaces.

This service starts Niri as a user-level desktop session with proper
environment variables configured for Wayland compatibility, including
@code{XDG_CURRENT_DESKTOP}, @code{XDG_SESSION_DESKTOP}, and
@code{DESKTOP_SESSION}.

Here is a minimal example service declaration for your
@code{home-environment} configuration:

@example
(service home-niri-service-type)
@end example

For more advanced configurations, you can customize the service with a
@code{niri-configuration} record to specify additional environment
variables.

@node Gerenciador de janelas Sway
@subsection Gerenciador de janelas Sway

@cindex sway, Home Service
@cindex sway, configuration
The @code{(gnu home services sway)} module provides
@code{home-sway-service-type}, a home service to configure the
@uref{https://github.com/swaywm/sway,Sway window manager for Wayland} in a
declarative way.

Here is an example of a service and its configuration that you could add to
the @code{services} field of your @code{home-environment}:

@lisp
(service home-sway-service-type
         (sway-configuration
          (gestures
           '((swipe:3:down . "move to scratchpad")
             (swipe:3:up   . "scratchpad show")))
          (outputs
           (list (sway-output
                  (identifier '*)
                  (background (file-append sway
                                           "\
/share/backgrounds/sway/Sway_Wallpaper_Blue_1920x1080.png")))))))
@end lisp

The above example describes a Sway configuration in which
@itemize
@item
all monitors use a particular wallpaper whose @file{.png} is provided by the
@code{sway} package;
@item
swiping down (resp.@: up) with three fingers moves the active window to the
scratchpad (resp.@: shows/hides the scratchpad).
@end itemize

@quotation Nota
This home service only sets up the configuration file and profile packages
for Sway.  It does @emph{not} start Sway in any way.  If you want to do so,
you might be interested in using @code{greetd-wlgreet-sway-session} instead.

The procedure @code{sway-configuration->file} defined below can be used to
provide the value for the @emph{optional} @code{sway-configuration} field of
@code{greetd-wlgreet-sway-session}.
@end quotation

@deffn {Procedure} sway-configuration->file config
This procedure takes one argument @code{config}, which must be a
@code{sway-configuration} record (defined below), and returns a file-like
object representing the serialized configuration.
@end deffn

@defvar home-sway-service-type
This is a home service type to set up Sway.  It takes care of:
@itemize
@item
providing a @file{~/.config/sway/config} file,
@item
adding Sway-related packages to your profile.
@end itemize

It is possible to extend this service (@pxref{Composição de serviço}).  The
resulting configuration file contains the concatenation of keybindings,
modes, @i{etc.}@: found in all extensions.

@quotation Nota
At the moment, only one bar configuration is allowed.  If more are found, an
error will be raised.
@end quotation
@end defvar

@defvar %empty-sway-configuration
The variable @code{%empty-sway-configuration} contains an empty
@code{sway-configuration} record.  This value can help users write simple
service extensions.
@end defvar

@deftp {Tipo de dados} sway-configuration
This configuration record describes the Sway configuration (see@
@cite{sway(5)}).  Available fields are:

@table @asis
@item @code{variables} (default: @code{%sway-default-variables})
The value of this field is an association list in which keys are symbols and
values are either strings, G-expressions or file-like objects
(@pxref{Expressões-G}).

Exemplo:
@lisp
(variables `((mod . "Mod4") ; string
             (term ; file-append
              . ,(file-append foot "/bin/foot"))
             (Term ; G-expression
              . ,#~(string-append #$foot "/bin/foot"))))
@end lisp

@quotation Nota
Default keybindings assume the existence of variables named @code{$mod},
@code{$left}, @code{$right}, @code{$up} and @code{$down}.  If you choose not
to define these variables, make sure to remove keybindings referring to
them.
@end quotation

@item @code{keybindings} (default: @code{%sway-default-keybindings})
This field describes keybindings for the @emph{default} mode.  The value is
an association list in which keys are symbols.  Values can either be:
@itemize
@item
strings or G-expressions,
@item
a cons-cell of a string or G-expression and a list of options.  Options must
be a string starting with ``input-device='' or strings among ``no-warn'',
``whole-window'', ``border'', ``exclude-titlebar'', ``release'', ``locked'',
``to-code'', ``inhibited'' and ``no-repeat''.
@end itemize

The following snippet launches the terminal when pressing @kbd{$mod+t} and
@kbd{$mod+Shift+t} (assuming that a variable @code{$term} is defined):
@lisp
`(($mod+t . ,#~(string-append "exec " #$foot "/bin/foot"))
  ($mod+Shift+t . "exec $term")
  ($mod+q "exec $term" . ("to-code"))) ;; passes the --to-code option.
@end lisp

@item @code{gestures} (default: @code{%sway-default-gestures})
Similar to the previous field, but for finger-gestures.  Options must start
with ``input-device='' or be among ``exact'' and ``no-warn''.

The following snippet allows to navigate through workspaces by swiping right
and left with three fingers:
@lisp
'((swipe:3:right . "workspace next_on_output")
  (swipe:3:left    "workspace prev_on_output" . ("exact")))
@end lisp

@item @code{packages} (default: @code{%sway-default-packages})
This field describes a list of packages to add to the user profile.  At the
moment, the default value only adds @code{sway} to the profile.

@item @code{inputs} (padrão: @code{'()})
List of @code{sway-input} configuration records (described below).

@item @code{outputs} (default: @code{'()})
List of @code{sway-output} configuration records (described below).

@item @code{bar} (optional @code{sway-bar} record)
Optional @code{sway-bar} record (described below) to configure a Sway bar.

@item @code{modes} (default: @code{%sway-default-modes})
List of @code{sway-mode} records (described below) to add modes to the Sway
configuration.  The default value @code{%sway-default-modes} adds the
``resize'' mode of the default Sway configuration (as described below).

@item @code{startup+reload-programs} (default: @code{'()})
Programs to execute at startup time @emph{and} after every configuration
reload.  The value of this field is a list of strings, G-expressions or
file-like objects (@pxref{Expressões-G}).

@item @code{startup-programs} (default: @code{%sway-default-startup-programs})
Programs to execute at startup time.  As above, values of this field are a
list of strings, G-expressions or file-like objects.

The default value, @code{%sway-default-startup-programs}, executes
@code{swayidle} in order to lock the screen after 5@ minutes of inactivity
(displaying a background distributed with Sway) and turn the screen off
after 10@ minutes of inactivity.

@item @code{extra-content} (default: @code{'()})
Lines to add to the configuration file.  The value of this field is a list
of strings or G-expressions.
@end table
@end deftp

@deftp {Tipo de dados} sway-input
@code{sway-input} records describe input blocks (see@
@cite{sway-input(5)}).  For example, the following snippet makes all
keyboards use a French layout, in which @kbd{capslock} has been remapped to
@kbd{ctrl}:
@lisp
(sway-input (identifier "type:keyboard")
            (layout
              (keyboard-layout "fr" #:options '("ctrl:nocaps"))))
@end lisp

Available fields for @code{sway-input} configuration records are:

@table @asis
@item @code{identifier} (default: @code{'*})
Identifier of the input.  The field accepts symbols and strings.  If the
@code{identifier} is a symbol, it is inserted as is; if it is a string, it
will be quoted in the configuration file.

@item @code{layout} (optional @code{<keyboard-layout>} record)
Keyboard specific option.  Field specifying the layout to use for the
input.  The value must be a @code{<keyboard-layout>} record (@pxref{Disposição do teclado}).

@quotation Nota
@code{(gnu home services sway)} does not re-export the
@code{keyboard-layout} procedure.
@end quotation

@item @code{disable-while-typing} (optional boolean)
If @code{#t} (resp.@: @code{#f}) enables (resp.@: disables) the ``disable
while typing'' option for this input.

@item @code{disable-while-trackpointing} (optional boolean)
If @code{#t} (resp.@: @code{#f}), enables (resp.@: disables) the ``disable
while track-pointing'' option for this input.

@item @code{tap} (optional boolean)
Enables or disables the ``tap'' option, which allows clicking by tapping on
a touchpad.

@item @code{extra-content} (default: @code{'()})
Lines to add to the input block.  The value of this field must a list whose
elements are either strings or G-expressions.
@end table
@end deftp

@deftp {Tipo de dados} sway-output
@code{sway-output} records describe Sway outputs (see@
@cite{sway-output(5)}).  Available fields are:

@table @asis
@item @code{identifier} (default: @code{'*})
Identifier of the monitor.  The field accepts symbols and strings.  If the
@code{identifier} is a symbol, it is inserted as is; if it is a string, it
will be quoted in the configuration file.

@item @code{resolution} (optional string)
This string defines the resolution of the monitor.

@item @code{position} (optional)
The (optional) value of this field must be a @code{point}.  Example:
@lisp
(position
 (point (x 1920)
        (y 0)))
@end lisp

@item @code{background} (optional)
The value of this field describes what wallpaper to use on this output.  The
field accepts the following types of values:
@itemize
@item
a string,
@item
a G-expression,
@item
a file-like object,
@item
a pair.  The first argument of this pair must be a string, a G-expression or
a file-like object.  The second element describes how the wallpaper will be
displayed.  It must be a symbol among @code{stretch}, @code{fill},
@code{fit}, @code{center} and @code{tile}.

If the second element is not specified (@i{i.e.}@: when the value is not a
pair), the @code{fill} mode will be used.
@end itemize

@quotation Nota
In order to use an SVG file, you must have @code{librsvg} in your profile
(@i{e.g.}@: by adding it in the @code{packages} field of
@code{sway-configuration}).
@end quotation

@item @code{extra-content} (default: @code{'()})
List defining additional lines to add to the output configuration block.
Elements of the list must be either strings or G-expressions.
@end table
@end deftp

@deftp {Tipo de dados} sway-border-color
@table @code
@item border
Color of the border.
@item background
Color of the background.
@item text
Color of the text.
@end table
@end deftp

@deftp {Tipo de dados} sway-color
@table @asis
@item @code{background} (optional string)
Background color of the bar.

@item @code{statusline} (optional string)
Text color of the status line.

@item @code{focused-background} (optional string)
Background color of the bar on the currently focused monitor.

@item @code{focused-statusline} (optional string)
Text color of the statusline on the currently focused monitor.

@item @code{focused-workspace} (optional @code{sway-border-color})
Color scheme for focused workspaces.

@item @code{active-workspace} (optional @code{sway-border-color})
Color scheme for active workspaces.

@item @code{inactive-workspace} (optional @code{sway-border-color})
Color scheme for inactive workspaces.

@item @code{urgent-workspace} (optional @code{sway-border-color})
Color scheme for workspaces containing ``urgent windows''.

@item @code{binding-mode} (optional @code{sway-border-color})
Color scheme for the binding mode indicator.
@end table
@end deftp

@deftp {Tipo de dados} sway-bar
Describes the Sway bar (see@ @cite{sway-bar(5)}).

@table @asis
@item @code{identifier} (default: @code{'bar0})
Identifier of the bar.  The value must be a symbol.

@item @code{position} (optional)
Specify the position of the bar.  Accepted values are @code{'top} or
@code{'bottom}.

@item @code{hidden-state} (optional)
Specify the appearance of the bar when it is hidden.  Accepted values are
@code{'hide} or @code{'show}.

@item @code{binding-mode-indicator} (optional)
Boolean enabling or disabling the binding mode indicator.

@item @code{colors} (optional)
An optional @code{sway-color} configuration record.

@item @code{status-command} (optional)
This field accept strings, G-expressions and executable file-like values.
The default value is a command (string) that prints the date and time every
second.

Each line printed on @code{stdout} by this command (or script) will be
displayed on the status area of the bar.

Below are a few examples using:
@itemize
@item
a string: @code{"while date +'%Y-%m-%d %X'; do sleep 1; done"},
@item
a G-exp:
@lisp
#~(string-append "while "
                 #$coreutils "/bin/date"
                 " +'%Y-%m-%d %X'; do sleep 1; done")
@end lisp
@item
an executable file:
@lisp
(program-file
 "sway-bar-status"
 #~(begin
     (use-modules (ice-9 format)
                  (srfi srfi-19))
     (let loop ()
       (let* ((date (date->string
                     (current-date)
                     "~d/~m/~Y (~a) • ~H:~M:~S")))
         (format #t "~a~%~!" date)
         (sleep 1)
         (loop)))))
@end lisp
@end itemize

@item @code{mouse-bindings} (default: @code{'()})
This field accepts an associative list.  Keys are integers describing mouse
events.  Values are similar to that of key-bindings (except that ``to-code''
is not a valid option for mouse-bindings).

The module @code{(gnu home services sway)} exports constants
@code{%ev-code-mouse-left}, @code{%ev-code-mouse-right} and
@code{%ev-code-mouse-scroll-click} whose values are integers corresponding
to left, right and scroll click respectively.  For example, with
@code{(mouse-bindings `((,%ev-code-mouse-left . "exec $term")))}, left
clicks in the status bar open the terminal (assuming that the variable
@code{$term} is bound to a terminal).
@end table
@end deftp

@deftp {Tipo de dados} sway-mode
Describes a Sway mode (see@ @cite{sway(5)}).  For example, the following
snippet defines the resize mode of the default Sway configuration:
@example
(sway-mode
 (mode-name "resize")
 (keybindings
  '(($left  . "resize shrink width 10px")
    ($right . "resize grow width 10px")
    ($down  . "resize grow height 10px")
    ($up    . "resize shrink height 10px")
    (Left   . "resize shrink width 10px")
    (Right  . "resize grow width 10px")
    (Down   . "resize grow height 10px")
    (Up     . "resize shrink height 10px")
    (Return . "mode \"default\"")
    (Escape . "mode \"default\""))))
@end example

@table @asis
@item @code{mode-name} (default: @code{"default"})
Name of the mode.  This field accepts strings.

@item @code{keybindings} (default: @code{'()})
This field describes keybindings.  The value is an association list.  As
above, keys are symbols and values are either strings, G-expressions or
cons-cells.

@item @code{mouse-bindings} (default: @code{'()})
Ditto, but keys are mouse events (integers).  Constants
@code{%ev-code-mouse-*} described above can be used as helpers to define
mouse bindings.
@end table
@end deftp

@node Networking Home Services
@subsection Networking Home Services

This section lists services somewhat networking-related that you may use
with Guix Home.

@subheading Syncthing Service

@cindex Syncthing, file synchronization service
@cindex backup service, Syncthing
The @code{(gnu home services syncthing)} module provides a service to set up
the @uref{Syncthing, https://syncthing.net} continuous file backup service.

@defvar home-syncthing-service-type
This is the service type for the @command{syncthing} daemon; it is the Home
counterpart of the @code{syncthing-service-type} system service
(@pxref{Serviços de Rede, @code{syncthing-service-type}}).  The value for
this service type is a @command{syncthing-configuration}.

Here is how you would set it up with the default configuration:

@lisp
(service home-syncthing-service-type)
@end lisp

For a custom configuration, wrap you @code{syncthing-configuration} in
@code{for-home}, as in this example:

@lisp
(service home-syncthing-service-type
         (for-home
          (syncthing-configuration (logflags 5))))
@end lisp

For details about @code{syncthing-configuration}, check out the
documentation of the system service (@pxref{Serviços de Rede,
@code{syncthing-service-type}}).
@end defvar

@node Secrets Home Services
@subsection Secrets Home Services

The @code{(gnu home services secrets)} module provides services pertaining
to storing secrets, notably including password managers.

@subsubheading Himitsu Services

@uref{https://himitsustore.org/, Himitsu} is a daemon for storing arbitrary
secrets encrypted by a single password.  The daemon operates alongside a
prompter, which asks the user for permission when an application requests a
secret, and for the store password on first use in a session.  Neither
Himitsu nor its underlying cryptography library have been indepednently
audited.

@defvar home-himitsu-service-type
This service provides the main Himitsu store daemon.  It will not launch
unless you have a store set up - run @code{himitsu-store -i} after the
service is added to your profile to create it, and then @code{herd start
himitsud} to restart the service. Configuration is as follows:
@end defvar

@deftp {Data Type} home-himitsu-configuration
@table @asis
@item @code{package} (default: @code{himitsu})
Package to find @code{himitsud} in.

@item @code{notify-reuse} (optional)
Interpreted shell command to run on application access to an
already-approved secret.

@item @code{prompter} (default: @code{(wrap-himitsu-prompter (file-append hiprompt-gtk "/bin/hiprompt-gtk"))})
Path to a prompter binary.  Defaults to @code{hiprompt-gtk}, the reference
implementation.  If your prompter is graphical, you should pass it through
the provided @code{wrap-himitsu-prompter} procedure, which will autodetect a
running display to prompt on, due to the Himitsu daemon starting before the
display server is online.

@item @code{extra-options} (optional)
List of extra strings or G-expressions to insert verbatim into the Himitsu
configuration file.  Each list element gets its own line.

@end table
@end deftp

Himitsu can be used through its command-line tool @code{hiq} or through any
number of supporting services, providing compatability to other
applications.  Git credential support may be provided simply by adding the
@code{himitsu-git} package to your profile, but other such supporting
services are listed below:

@defvar home-himitsu-ssh-service-type
This service provides an @code{ssh-agent} implementation that stores keys
through Himitsu.  You may interact with a running daemon through
@code{hissh-import} and @code{hissh-export}.
@end defvar

@deftp {Data Type} home-himitsu-ssh-configuration
@table @asis
@item @code{package} (default: @code{himitsu-ssh})
Package to find @code{hissh-agent} in.

@item @code{persist} (default: @code{'(session 300 refuse)})
List of options given when prompting to allow this service access to your
list of keys.  The option chosen decides how long @code{himitsu-ssh} has
this access.  Options can be either @code{'session} (access is retained
until the daemon closes), @code{'refuse} (access is declined and the
prompter will not ask again), @code{'skip} (ask again next use), or a
numerical access timeout in seconds.

@item @code{disclose} (default: @code{'(skip session 300)})
List of options given when prompting to allow this service use of your
secret keys.  Has the same format as @code{persist}.

@end table
@end deftp

@defvar home-himitsu-secret-service-type
This service provides a
@uref{https://specifications.freedesktop.org/secret-service/latest/,
freedesktop Secret Service} implementation, allowing Himitsu to replace
@pxref{Serviços de desktop, gnome-keyring-service-type} and @pxref{Serviços de desktop, kwallet-service-type}.
@end defvar

@deftp {Data Type} home-himitsu-secret-service-configuration
@table @asis
@item @code{package} (default: @code{himitsu-secret-service})
Package to find @code{hisecrets-agent} in.

@end table
@end deftp

@node Miscellaneous Home Services
@subsection Miscellaneous Home Services

This section lists Home services that lack a better place.

@subsubheading Beets Service

@cindex Beets service, for Home
The @code{(gnu home services music)} module provides the following service:

@defvar home-beets-service-type
@uref{https://beets.io, Beets} is a music file and metadata manager that can
be used via its command-line interface, @command{beet}. Beets requires a
YAML configuration file and this Guix Home service is to create such file.
@end defvar

The service can be used as follows:

@lisp
(service home-beets-service-type
         (home-beets-configuration (directory "/home/alice/music")))
@end lisp

Additional options can be specified via the service wild-card field
@code{extra-options}:

@lisp
(service home-beets-service-type
         (home-beets-configuration
          (directory "/home/alice/music")
          (extra-options '("
import:
  move: yes"))))
@end lisp

@subsubheading Dictionary Service

@cindex dictionary service, for Home
The @code{(gnu home services dict)} module provides the following service:

@defvar home-dicod-service-type
This is the type of the service that runs the @command{dicod} daemon, an
implementation of DICT server (@pxref{Dicod,,, dico, GNU Dico Manual}).

You can add @command{open localhost} to your @file{~/.dico} file to make
@code{localhost} the default server for @command{dico} client
(@pxref{Initialization File,,, dico, GNU Dico Manual}).
@end defvar

This service is a direct mapping of the @code{dicod-service-type} system
service (@pxref{Serviços diversos, Dictionary Service}).  You can use
it like this:

@lisp
(service home-dicod-service-type)
@end lisp

You may specify a custom configuration by providing a
@code{dicod-configuration} record, exactly like for
@code{dicod-service-type}, but wrapping it in @code{for-home}:

@lisp
(service home-dicod-service-type
         (for-home
          (dicod-configuration @dots{})))
@end lisp

@subheading ReadyMedia Service

@cindex ReadyMedia, DLNA/UPnP Service
The @code{(gnu home services upnp)} module provides a service to set up the
@uref{https://minidlna.sourceforge.net/, ReadyMedia} @acronym{DLNA, Digital
Living Network Alliance} @acronym{UPnP, Universal Plug and Play} media
server.

@defvar home-readymedia-service-type
This is the service type for the @command{minidlnad} daemon; it is the Home
counterpart of the @code{readymedia-service-type} system service
(@pxref{Serviços diversos, @code{readymedia-service-type}}).  The value
for this service type is a @code{readymedia-configuration}.
@end defvar

The service can be used with a @code{readymedia-configuration} wrapped in
@code{for-home} like this:

@lisp
(service home-readymedia-service-type
         (for-home
          (readymedia-configuration
            (media-directories
             (list (readymedia-directory
                     (path "/path/to/media/audio")
                     (types '(A)))
                   (readymedia-directory
                     (path "/path/to/media/video")
                     (types '(V)))
                   (readymedia-directory
                     (path "/path/to/media/misc")))))))
@end lisp

For details about @code{readymedia-configuration}, check out the
documentation of the system service (@pxref{Serviços diversos,
@code{readymedia-service-type}}).

@subsubheading OCI backed services

@cindex OCI-backed, for Home
The @code{(gnu home services containers)} module provides the following
service:

@defvar home-oci-service-type
This is the type of the service that allows to manage your OCI containers
with the same consistent interface you use for your other Home Shepherd
services.
@end defvar

This service is a direct mapping of the @code{oci-service-type} system
service (@pxref{Serviços diversos, OCI backed services}).  You can use
it like this:

@lisp
(use-modules (gnu services containers)
             (gnu home services containers))

(simple-service 'home-oci-provisioning
                home-oci-service-type
                (oci-extension
                  (volumes
                    (list
                      (oci-volume-configuration (name "prometheus"))
                      (oci-volume-configuration (name "grafana"))))
                  (networks
                    (list
                      (oci-network-configuration (name "monitoring"))))
                  (containers
                   (list
                    (oci-container-configuration
                     (network "monitoring")
                     (image
                      (oci-image
                        (repository "guile")
                        (tag "3")
                        (value (specifications->manifest '("guile")))
                        (pack-options '(#:symlinks (("/bin/guile" -> "bin/guile"))
                                        #:max-layers 2))))
                     (entrypoint "/bin/guile")
                     (command
                      '("-c" "(display \"hello!\n\")")))
                    (oci-container-configuration
                      (image "prom/prometheus")
                      (network "monitoring")
                      (ports
                       '(("9000" . "9000")
                         ("9090" . "9090")))
                      (volumes
                       (list
                        '(("prometheus" . "/var/lib/prometheus")))))
                    (oci-container-configuration
                      (image "grafana/grafana:10.0.1")
                      (network "monitoring")
                      (volumes
                       '(("grafana:/var/lib/grafana"))))))))

@end lisp

You may specify a custom configuration by providing a
@code{oci-configuration} record, exactly like for @code{oci-service-type},
but wrapping it in @code{for-home}:

@lisp
(use-modules (gnu services)
             (gnu services containers)
             (gnu home services containers))

(service home-oci-service-type
         (for-home
          (oci-configuration
           (runtime 'podman)
           (verbose? #t))))

(simple-service 'home-oci-provisioning
                home-oci-service-type
                (oci-extension
                  (volumes
                    (list
                      (oci-volume-configuration (name "prometheus"))
                      (oci-volume-configuration (name "grafana"))))
                  (networks
                    (list
                      (oci-network-configuration (name "monitoring"))))
                  (containers
                   (list
                    (oci-container-configuration
                     (network "monitoring")
                     (image
                      (oci-image
                        (repository "guile")
                        (tag "3")
                        (value (specifications->manifest '("guile")))
                        (pack-options '(#:symlinks (("/bin/guile" -> "bin/guile"))
                                        #:max-layers 2))))
                     (entrypoint "/bin/guile")
                     (command
                      '("-c" "(display \"hello!\n\")")))
                    (oci-container-configuration
                      (image "prom/prometheus")
                      (network "monitoring")
                      (ports
                       '(("9000" . "9000")
                         ("9090" . "9090")))
                      (volumes
                       (list
                        '(("prometheus" . "/var/lib/prometheus")))))
                    (oci-container-configuration
                      (image "grafana/grafana:10.0.1")
                      (network "monitoring")
                      (volumes
                       '(("grafana:/var/lib/grafana"))))))))
@end lisp

@node Invocando guix home
@section Invoking @command{guix home}

@cindex @command{guix home}

Once you have written a home environment declaration (@pxref{Declarando o ambiente pessoal,,,,}, it can be @dfn{instantiated} using the @command{guix
home} command.  The synopsis is:

@example
guix home @var{options}@dots{} @var{action} @var{file}
@end example

@var{file} must be the name of a file containing a @code{home-environment}
declaration.  @var{action} specifies how the home environment is
instantiated, but there are few auxiliary actions which don't instantiate
it.  Currently the following values are supported:

@table @code
@item search
Display available home service type definitions that match the given regular
expressions, sorted by relevance:

@cindex shell
@cindex shell-profile
@cindex bash
@cindex zsh
@example
$ guix home search shell
name: home-shell-profile
location: gnu/home/services/shells.scm:100:2
extends: home-files
description: Create `~/.profile', which is used for environment initialization of POSIX compliant login shells.
+ This service type can be extended with a list of file-like objects.
relevance: 6

name: home-fish
location: gnu/home/services/shells.scm:640:2
extends: home-files home-profile
description: Install and configure Fish, the friendly interactive shell.
relevance: 3

name: home-zsh
location: gnu/home/services/shells.scm:290:2
extends: home-files home-profile
description: Install and configure Zsh.
relevance: 1

name: home-bash
location: gnu/home/services/shells.scm:508:2
extends: home-files home-profile
description: Install and configure GNU Bash.
relevance: 1

@dots{}
@end example

As for @command{guix search}, the result is written in @code{recutils}
format, which makes it easy to filter the output (@pxref{Top, GNU recutils
databases,, recutils, GNU recutils manual}).

@cindex container, for @command{guix home}
@item container
Spawn a shell in an isolated environment---a @dfn{container}---containing
your home as specified by @var{file}.

For example, this is how you would start an interactive shell in a container
with your home:

@example
guix home container config.scm
@end example

This is a throw-away container where you can lightheartedly fiddle with
files; any changes made within the container, any process started---all this
disappears as soon as you exit that shell.

As with @command{guix shell}, several options control that container:

@table @option
@item --network
@itemx -N
Enable networking within the container (it is disabled by default).

@item --expose=@var{fonte}[=@var{alvo}]
@itemx --share=@var{fonte}[=@var{alvo}]
As with @command{guix shell}, make directory @var{source} of the host system
available as @var{target} inside the container---read-only if you pass
@option{--expose}, and writable if you pass @option{--share}
(@pxref{Invocando guix shell, @option{--expose} and @option{--share}}).
@end table

Additionally, you can run a command in that container, instead of spawning
an interactive shell.  For instance, here is how you would check which
Shepherd services are started in a throw-away home container:

@example
guix home container config.scm -- herd status
@end example

The command to run in the container must come after @code{--} (double
hyphen).

@cindex service type definition, editing
@cindex editing, service type definition
@item edit
Edit or view the definition of the given Home service types.

For example, the command below opens your editor, as specified by the
@env{EDITOR} environment variable, on the definition of the
@code{home-mcron} service type:

@example
guix home edit home-mcron
@end example

@item reconfigure
Build the home environment described in @var{file}, and switch to it.
Switching means that the activation script will be evaluated and (in basic
scenario) symlinks to configuration files generated from
@code{home-environment} declaration will be created in @file{~}.  If the
file with the same path already exists in home folder it will be moved to
@file{~/@var{timestamp}-guix-home-legacy-configs-backup}, where
@var{timestamp} is a current UNIX epoch time.

@quotation Nota
It is highly recommended to run @command{guix pull} once before you run
@command{guix home reconfigure} for the first time (@pxref{Invocando guix pull}).
@end quotation

This effects all the configuration specified in @var{file}.  The command
starts Shepherd services specified in @var{file} that are not currently
running; if a service is currently running, this command will arrange for it
to be upgraded the next time it is stopped (e.g.@: by @code{herd stop
@var{service}} or @code{herd restart @var{service}}).

This command creates a new generation whose number is one greater than the
current generation (as reported by @command{guix home list-generations}).
If that generation already exists, it will be overwritten.  This behavior
mirrors that of @command{guix package} (@pxref{Invocando guix package}).

@cindex rastreamento de proveniência, do ambiente pessoal
Upon completion, the new home is deployed under @file{~/.guix-home}.  This
directory contains @dfn{provenance meta-data}: the list of channels in use
(@pxref{Canais}) and @var{file} itself, when available.  You can view the
provenance information by running:

@example
guix home describe
@end example

This information is useful should you later want to inspect how this
particular generation was built.  In fact, assuming @var{file} is
self-contained, you can later rebuild generation @var{n} of your home
environment with:

@example
guix time-machine \
  -C /var/guix/profiles/per-user/@var{USER}/guix-home-@var{n}-link/channels.scm -- \
  home reconfigure \
  /var/guix/profiles/per-user/@var{USER}/guix-home-@var{n}-link/configuration.scm

@end example

You can think of it as some sort of built-in version control! Your home is
not just a binary artifact: @emph{it carries its own source}.

@quotation Nota
If you're using Guix System, @ref{guix-home-service-type,
@code{guix-home-service-type}}, on how to embed your home configuration in
your system configuration such that @command{guix system reconfigure}
deploys both your system and your home.
@end quotation

@item switch-generation
@cindex home generations
Switch to an existing home generation.  This action atomically switches the
home profile to the specified home generation.

The target generation can be specified explicitly by its generation number.
For example, the following invocation would switch to home generation 7:

@example
guix home switch-generation 7
@end example

The target generation can also be specified relative to the current
generation with the form @code{+N} or @code{-N}, where @code{+3} means ``3
generations ahead of the current generation,'' and @code{-1} means ``1
generation prior to the current generation.'' When specifying a negative
value such as @code{-1}, you must precede it with @code{--} to prevent it
from being parsed as an option.  For example:

@example
guix home switch-generation -- -1
@end example

This action will fail if the specified generation does not exist.

@item roll-back
@cindex revertendo
Switch to the preceding home generation.  This is the inverse of
@command{reconfigure}, and it is exactly the same as invoking
@command{switch-generation} with an argument of @code{-1}.

@item delete-generations
@cindex deleting home generations
@cindex saving space
Delete home generations, making them candidates for garbage collection
(@pxref{Invocando guix gc}, for information on how to run the ``garbage
collector'').

This works in the same way as @samp{guix package --delete-generations}
(@pxref{Invocando guix package, @option{--delete-generations}}).  With no
arguments, all home generations but the current one are deleted:

@example
guix home delete-generations
@end example

You can also select the generations you want to delete.  The example below
deletes all the home generations that are more than two months old:

@example
guix home delete-generations 2m
@end example

@item build
Build the derivation of the home environment, which includes all the
configuration files and programs needed.  This action does not actually
install anything.

@item describe
Describe the current home generation: its file name, as well as provenance
information when available.

To show installed packages in the current home generation's profile, the
@code{--list-installed} flag is provided, with the same syntax that is used
in @command{guix package --list-installed} (@pxref{Invocando guix package}).
For instance, the following command shows a table of all the packages with
``emacs'' in their name that are installed in the current home generation's
profile:

@example
guix home describe --list-installed=emacs
@end example

@item list-generations
List a summary of each generation of the home environment available on disk,
in a human-readable way.  This is similar to the @option{--list-generations}
option of @command{guix package} (@pxref{Invocando guix package}).

Optionally, one can specify a pattern, with the same syntax that is used in
@command{guix package --list-generations}, to restrict the list of
generations displayed.  For instance, the following command displays
generations that are up to 10 days old:

@example
guix home list-generations 10d
@end example

The @code{--list-installed} flag may also be specified, with the same syntax
that is used in @command{guix home describe}.  This may be helpful if trying
to determine when a package was added to the home profile.

@item import
Generate a @dfn{home environment} from the packages in the default profile
and configuration files found in the user's home directory.  The
configuration files will be copied to the specified directory, and a
@file{home-configuration.scm} will be populated with the home environment.
Note that not every home service that exists is supported (@pxref{Serviços pessoais}).

@example
$ guix home import ~/guix-config
guix home: '/home/alice/guix-config' populated with all the Home configuration files
@end example
@end table

And there's more! @command{guix home} also provides the following
sub-commands to visualize how the services of your home environment relate
to one another:

@table @code
@cindex service extension graph, of a home environment
@item extension-graph
Emit to standard output the @dfn{service extension graph} of the home
environment defined in @var{file} (@pxref{Composição de serviço}, for more
information on service extensions).  By default the output is in
Dot/Graphviz format, but you can choose a different format with
@option{--graph-backend}, as with @command{guix graph} (@pxref{Invocando guix graph, @option{--backend}}):

O comando:

@example
guix home extension-graph @var{file} | xdot -
@end example

shows the extension relations among services.

@cindex Shepherd dependency graph, for a home environment
@item shepherd-graph
Emit to standard output the @dfn{dependency graph} of shepherd services of
the home environment defined in @var{file}.  @xref{Serviços de Shepherd}, for
more information and for an example graph.

Again, the default output format is Dot/Graphviz, but you can pass
@option{--graph-backend} to select a different one.
@end table

@var{options} can contain any of the common build options (@pxref{Opções de compilação comuns}).  In addition, @var{options} can contain one of the
following:

@table @option

@item --expression=@var{expr}
@itemx -e @var{expr}
Consider the home-environment @var{expr} evaluates to.  This is an
alternative to specifying a file which evaluates to a home environment.

@item --allow-downgrades
Instruct @command{guix home reconfigure} to allow system downgrades.

Just like @command{guix system}, @command{guix home reconfigure}, by
default, prevents you from downgrading your home to older or unrelated
revisions compared to the channel revisions that were used to deploy
it---those shown by @command{guix home describe}.  Using
@option{--allow-downgrades} allows you to bypass that check, at the risk of
downgrading your home---be careful!

@end table

@node Documentação
@chapter Documentação

@cindex documentation, searching for
@cindex searching for documentation
@cindex Info, documentation format
@cindex man pages
@cindex manual pages
In most cases packages installed with Guix come with documentation.  There
are two main documentation formats: ``Info'', a browsable hypertext format
used for GNU software, and ``manual pages'' (or ``man pages''), the linear
documentation format traditionally found on Unix.  Info manuals are accessed
with the @command{info} command or with Emacs, and man pages are accessed
using @command{man}.

You can look for documentation of software installed on your system by
keyword.  For example, the following command searches for information about
``TLS'' in Info manuals:

@example
$ info -k TLS
"(emacs)Network Security" -- STARTTLS
"(emacs)Network Security" -- TLS
"(gnutls)Core TLS API" -- gnutls_certificate_set_verify_flags
"(gnutls)Core TLS API" -- gnutls_certificate_set_verify_function
@dots{}
@end example

@noindent
The command below searches for the same keyword in man pages@footnote{The
database searched by @command{man -k} is only created in profiles that
contain the @code{man-db} package.}:

@example
$ man -k TLS
SSL (7)              - OpenSSL SSL/TLS library
certtool (1)         - GnuTLS certificate tool
@dots {}
@end example

These searches are purely local to your computer so you have the guarantee
that documentation you find corresponds to what you have actually installed,
you can access it off-line, and your privacy is respected.

Once you have these results, you can view the relevant documentation by
running, say:

@example
$ info "(gnutls)Core TLS API"
@end example

@noindent
or:

@example
$ man certtool
@end example

Info manuals contain sections and indices as well as hyperlinks like those
found in Web pages.  The @command{info} reader (@pxref{Top, Info reader,,
info-stnd, Stand-alone GNU Info}) and its Emacs counterpart (@pxref{Misc
Help,,, emacs, The GNU Emacs Manual}) provide intuitive key bindings to
navigate manuals.  @xref{Getting Started,,, info, Info: An Introduction},
for an introduction to Info navigation.

@node Plataformas
@chapter Plataformas

The packages and systems built by Guix are intended, like most computer
programs, to run on a CPU with a specific instruction set, and under a
specific operating system.  Those programs are often also targeting a
specific kernel and system library.  Those constraints are captured by Guix
in @code{platform} records.

@menu
* Referência do platform::   Detail of platform declarations.
* Supported Platforms::      Description of the supported platforms.
@end menu

@node Referência do platform
@section @code{platform} Reference

The @code{platform} data type describes a @dfn{platform}: an @acronym{ISA,
instruction set architecture}, combined with an operating system and
possibly additional system-wide settings such as the @acronym{ABI,
application binary interface}.

@deftp {Tipo de dados} platform
This is the data type representing a platform.

@table @asis
@item @code{target}
This field specifies the platform's GNU triplet as a string
(@pxref{Specifying Target Triplets, GNU configuration triplets,, autoconf,
Autoconf}).

@item @code{system}
This string is the system type as it is known to Guix and passed, for
instance, to the @option{--system} option of most commands.

It usually has the form @code{"@var{cpu}-@var{kernel}"}, where @var{cpu} is
the target CPU and @var{kernel} the target operating system kernel.

It can be for instance @code{"aarch64-linux"} or @code{"armhf-linux"}.  You
will encounter system types when you perform native builds (@pxref{Construções nativas}).

@item @code{linux-architecture} (default: @code{#false})
This optional string field is only relevant if the kernel is Linux.  In that
case, it corresponds to the ARCH variable used when building Linux,
@code{"mips"} for instance.

@item @code{rust-target} (default: @code{#false})
This optional string field is used to determine which rust target is best
supported by this platform.  For example, the base level system targeted by
@code{armhf-linux} system is closest to
@code{armv7-unknown-linux-gnueabihf}.

@item @code{glibc-dynamic-linker}
This field is the name of the GNU C Library dynamic linker for the
corresponding system, as a string.  It can be
@code{"/lib/ld-linux-armhf.so.3"}.

@end table
@end deftp

@node Supported Platforms
@section Supported Platforms

The @code{(guix platforms @dots{})} modules export the following variables,
each of which is bound to a @code{platform} record.

@defvar armv7-linux
Platform targeting ARM v7 CPU running GNU/Linux.
@end defvar

@defvar aarch64-linux
Platform targeting ARM v8 CPU running GNU/Linux.
@end defvar

@defvar loongarch64-linux
Platform targeting loongarch 64-bit CPU running GNU/Linux.
@end defvar

@defvar mips64-linux
Platform targeting MIPS little-endian 64-bit CPU running GNU/Linux.
@end defvar

@defvar powerpc-linux
Platform targeting PowerPC big-endian 32-bit CPU running GNU/Linux.
@end defvar

@defvar powerpc64le-linux
Platform targeting PowerPC little-endian 64-bit CPU running GNU/Linux.
@end defvar

@defvar riscv64-linux
Platform targeting RISC-V 64-bit CPU running GNU/Linux.
@end defvar

@defvar i686-linux
Platform targeting x86 CPU running GNU/Linux.
@end defvar

@defvar x86_64-linux
Platform targeting x86 64-bit CPU running GNU/Linux.
@end defvar

@defvar x86_64-linux-x32
Platform targeting x86 64-bit CPU running GNU/Linux with the run-time using
the X32 ABI.
@end defvar

@defvar i686-mingw
Platform targeting x86 CPU running Windows, with run-time support from
MinGW.
@end defvar

@defvar x86_64-mingw
Platform targeting x86 64-bit CPU running Windows, with run-time support
from MinGW.
@end defvar

@defvar i586-gnu
Platform targeting x86 CPU running GNU/Hurd (also referred to as ``GNU'').
@end defvar

@defvar avr
Platform targeting AVR CPUs without an operating system, with run-time
support from AVR Libc.
@end defvar

@defvar or1k-elf
Platform targeting OpenRISC 1000 CPU without an operating system and without
a C standard library.
@end defvar

@defvar xtensa-ath9k-elf
Platform targeting Xtensa CPU used in the Qualcomm Atheros AR7010 and AR9271
USB 802.11n @acronym{NICs, Network Interface Controllers}.
@end defvar

@node Imagens do sistema
@chapter Criando imagens do sistema

@cindex imagens de sistema
When it comes to installing Guix System for the first time on a new machine,
you can basically proceed in three different ways.  The first one is to use
an existing operating system on the machine to run the @command{guix system
init} command (@pxref{Invocando guix system}).  The second one, is to produce
an installation image (@pxref{Compilando a imagem de instalação}). This is a
bootable system which role is to eventually run @command{guix system init}.
Finally, the third option would be to produce an image that is a direct
instantiation of the system you wish to run.  That image can then be copied
on a bootable device such as an USB drive or a memory card.  The target
machine would then directly boot from it, without any kind of installation
procedure.

The @command{guix system image} command is able to turn an operating system
definition into a bootable image.  This command supports different image
types, such as @code{mbr-hybrid-raw}, @code{iso9660} and @code{docker}.  Any
modern @code{x86_64} machine will probably be able to boot from an
@code{iso9660} image.  However, there are a few machines out there that
require specific image types.  Those machines, in general using @code{ARM}
processors, may expect specific partitions at specific offsets.

This chapter explains how to define customized system images and how to turn
them into actual bootable images.

@menu
* image Reference::          Detail of image declarations.
* Instanciar uma imagem::    Como instanciar um registro de imagem.
* image-type Reference::     Detail of image types declaration.
* Módulos de imagem::        Definição de módulos de imagem.
@end menu

@node image Reference
@section @code{image} Reference

The @code{image} record, described right after, allows you to define a
customized bootable system image.

@deftp {Tipo de dados} image
This is the data type representing a system image.

@table @asis
@item @code{name} (default: @code{#false})
The image name as a symbol, @code{'my-iso9660} for instance.  The name is
optional and it defaults to @code{#false}.

@item @code{format}
The image format as a symbol.  The following formats are supported:

@itemize
@item @code{disk-image}, a raw disk image composed of one or multiple
partitions.

@item @code{compressed-qcow2}, a compressed qcow2 image composed of
one or multiple partitions.

@item @code{docker}, a Docker image.

@item @code{iso9660}, an ISO-9660 image.

@item @code{tarball}, a tar.gz image archive.

@item @code{wsl2}, a WSL2 image.

@end itemize

@item @code{platform} (default: @code{#false})
The @code{platform} record the image is targeting (@pxref{Plataformas}),
@code{aarch64-linux} for instance.  By default, this field is set to
@code{#false} and the image will target the host platform.

@item @code{size} (default: @code{'guess})
The image size in bytes or @code{'guess}.  The @code{'guess} symbol, which
is the default, means that the image size will be inferred based on the
image content.

@item @code{operating-system}
The image's @code{operating-system} record that is instantiated.

@item @code{partition-table-type} (default: @code{'mbr})
The image partition table type as a symbol.  Possible values are @code{'mbr}
and @code{'gpt}.  It default to @code{'mbr}.

@item @code{partitions} (default: @code{'()})
The image partitions as a list of @code{partition} records (@pxref{Referência do partition}).

@item @code{compression?} (default: @code{#true})
Whether the image content should be compressed, as a boolean.  It defaults
to @code{#true} and only applies to @code{'iso9660} image formats.

@item @code{volatile-root?} (default: @code{#true})
Whether the image root partition should be made volatile, as a boolean.

This is achieved by using a RAM backed file system (overlayfs) that is
mounted on top of the root partition by the initrd.  It defaults to
@code{#true}.  When set to @code{#false}, the image root partition is
mounted as read-write partition by the initrd.

@item @code{shared-store?} (default: @code{#false})
Whether the image's store should be shared with the host system, as a
boolean.  This can be useful when creating images dedicated to virtual
machines.  When set to @code{#false}, which is the default, the image's
@code{operating-system} closure is copied to the image.  Otherwise, when set
to @code{#true}, it is assumed that the host store will be made available at
boot, using a @code{9p} mount for instance.

@item @code{shared-network?} (default: @code{#false})
Se deve usar as interfaces de rede do host dentro da imagem, como um
booleano. Isso é usado apenas para o formato de imagem @code{'docker}. O
padrão é @code{#false}.

@item @code{substitutable?} (default: @code{#true})
Whether the image derivation should be substitutable, as a boolean.  It
defaults to @code{true}.

@end table
@end deftp

@menu
* Referência do partition::  Referência do partition
@end menu

@node Referência do partition
@subsection Referência do @code{partition}

In @code{image} record may contain some partitions.

@deftp {Tipo de dados} partition
This is the data type representing an image partition.

@table @asis
@item @code{size} (default: @code{'guess})
The partition size in bytes or @code{'guess}.  The @code{'guess} symbol,
which is the default, means that the partition size will be inferred based
on the partition content.

@item @code{offset} (default: @code{0})
The partition's start offset in bytes, relative to the image start or the
previous partition end.  It defaults to @code{0} which means that there is
no offset applied.

@item @code{file-system} (default: @code{"ext4"})
The partition file system as a string, defaulting to @code{"ext4"}.

The supported values are @code{"btrfs"}, @code{"ext4"}, @code{"fat16"},
@code{"f2fs"}, @code{"fat32"}, @code{"vfat"}, and @code{"swap"}.

@code{"vfat"}, @code{"fat16"}, and @code{"fat32"} partitions without the
@code{'esp} flag are by default LBA compatible.

@item @code{file-system-options} (default: @code{'()})
As opções de criação do sistema de arquivos de partição que devem ser
passadas para a ferramenta de criação de partição, como uma lista de
strings. Isso só é suportado ao criar partições @code{"vfat"},
@code{"fat16"}, @code{"fat32"} ou @code{"ext4"}.

See the @code{"extended-options"} man page section of the @code{"mke2fs"}
tool for a more complete reference.

@item @code{label}
The partition label as a mandatory string, @code{"my-root"} for instance.

@item @code{uuid} (default: @code{#false})
The partition UUID as an @code{uuid} record (@pxref{Sistemas de arquivos}).  By
default it is @code{#false}, which means that the partition creation tool
will attribute a random UUID to the partition.

@item @code{flags} (default: @code{'()})
The partition flags as a list of symbols.  Possible values are @code{'boot}
and @code{'esp}.  The @code{'boot} flags should be set if you want to boot
from this partition.  Exactly one partition should have this flag set,
usually the root one. The @code{'esp} flag identifies a UEFI System
Partition.

@item @code{initializer} (default: @code{#false})
The partition initializer procedure as a gexp.  This procedure is called to
populate a partition.  If no initializer is passed, the
@code{initialize-root-partition} procedure from the @code{(gnu build image)}
module is used.

@end table
@end deftp

@node Instanciar uma imagem
@section Instanciar uma imagem

Let's say you would like to create an MBR image with three distinct
partitions:

@itemize
@item The @acronym{ESP, EFI System Partition}, a partition of
40@tie{}MiB at offset 1024@tie{}KiB with a vfat file system.

@item an ext4 partition of 50@tie{}MiB data file, and labeled ``data''.

@item an ext4 bootable partition containing the @code{%simple-os}
operating-system.
@end itemize

You would then write the following image definition in a @code{my-image.scm}
file for instance.

@lisp
(use-modules (gnu)
             (gnu image)
             (gnu tests)
             (gnu system image)
             (guix gexp))

(define MiB (expt 2 20))

(image
 (format 'disk-image)
 (operating-system %simple-os)
 (partitions
  (list
   (partition
    (size (* 40 MiB))
    (offset (* 1024 1024))
    (label "GNU-ESP")
    (file-system "vfat")
    (flags '(esp))
    (initializer (gexp initialize-efi-partition)))
   (partition
    (size (* 50 MiB))
    (label "DATA")
    (file-system "ext4")
    (initializer #~(lambda* (root . rest)
                     (mkdir root)
                     (call-with-output-file
                         (string-append root "/data")
                       (lambda (port)
                         (format port "my-data"))))))
   (partition
    (size 'guess)
    (label root-label)
    (file-system "ext4")
    (flags '(boot))
    (initializer (gexp initialize-root-partition))))))
@end lisp

Note que a primeira e a terceira partições usam procedimentos de
inicializadores genéricos, initialize-efi-partition e
initialize-root-partition, respectivamente. O initialize-efi-partition
instala um carregador EFI GRUB que está carregando o carregador de
inicialização GRUB localizado na partição raiz. O initialize-root-partition
instancia um sistema completo conforme definido pelo sistema operacional
@code{%simple-os}.

Agora você pode executar:

@example
guix system image my-image.scm
@end example

para instanciar a definição @code{image}. Isso produz uma imagem de disco
que tem a estrutura esperada:

@example
$ parted $(guix system image my-image.scm) print
@dots{}
Model:  (file)
Disk /gnu/store/yhylv1bp5b2ypb97pd3bbhz6jk5nbhxw-disk-image: 1714MB
Sector size (logical/physical): 512B/512B
Partition Table: msdos
Disk Flags:

Number  Start   End     Size    Type     File system  Flags
 1      1049kB  43.0MB  41.9MB  primary  fat16        esp
 2      43.0MB  95.4MB  52.4MB  primary  ext4
 3      95.4MB  1714MB  1619MB  primary  ext4         boot
@end example

The size of the @code{boot} partition has been inferred to @code{1619MB} so
that it is large enough to host the @code{%simple-os} operating-system.

You can also use existing @code{image} record definitions and inherit from
them to simplify the @code{image} definition.  The @code{(gnu system image)}
module provides the following @code{image} definition variables.

@defvar mbr-disk-image
An MBR disk-image composed of a single ROOT partition.  The ROOT partition
starts at a 1@tie{}MiB offset so that the bootloader can install itself in
the post-MBR gap.
@end defvar

@defvar mbr-hybrid-disk-image
An MBR disk-image composed of two partitions: a 64 bits ESP partition and a
ROOT boot partition.  The ESP partition starts at a 1@tie{}MiB offset so
that a BIOS compatible bootloader can install itself in the post-MBR gap.
The image can be used by @code{x86_64} and @code{i686} machines supporting
only legacy BIOS booting.  The ESP partition ensures that it can also be
used by newer machines relying on UEFI booting, hence the @emph{hybrid}
denomination.
@end defvar

@defvar efi-disk-image
A GPT disk-image composed of two partitions: a 64 bits ESP partition and a
ROOT boot partition.  This image can be used on most @code{x86_64} and
@code{i686} machines, supporting BIOS or UEFI booting.
@end defvar

@defvar efi32-disk-image
Same as @code{efi-disk-image} but with a 32 bits EFI partition.
@end defvar

@defvar iso9660-image
An ISO-9660 image composed of a single bootable partition.  This image can
also be used on most @code{x86_64} and @code{i686} machines.
@end defvar

@defvar docker-image
Uma imagem do Docker que pode ser usada para gerar um contêiner do Docker.
@end defvar

Using the @code{efi-disk-image} we can simplify our previous @code{image}
declaration this way:

@lisp
(use-modules (gnu)
             (gnu image)
             (gnu tests)
             (gnu system image)
             (guix gexp)
             (ice-9 match))

(define MiB (expt 2 20))

(define data
  (partition
   (size (* 50 MiB))
   (label "DATA")
   (file-system "ext4")
   (initializer #~(lambda* (root . rest)
                    (mkdir root)
                    (call-with-output-file
                        (string-append root "/data")
                      (lambda (port)
                        (format port "my-data")))))))

(image
 (inherit efi-disk-image)
 (operating-system %simple-os)
 (partitions
  (match (image-partitions efi-disk-image)
    ((esp root)
     (list esp data root)))))
@end lisp

This will give the exact same @code{image} instantiation but the
@code{image} declaration is simpler.

@node image-type Reference
@section image-type Reference

The @command{guix system image} command can, as we saw above, take a file
containing an @code{image} declaration as argument and produce an actual
disk image from it.  The same command can also handle a file containing an
@code{operating-system} declaration as argument.  In that case, how is the
@code{operating-system} turned into an image?

That's where the @code{image-type} record intervenes.  This record defines
how to transform an @code{operating-system} record into an @code{image}
record.

@deftp {Tipo de dados} image-type
This is the data type representing an image-type.

@table @asis
@item @code{name}
The image-type name as a mandatory symbol, @code{'efi32-raw} for instance.

@item @code{constructor}
The image-type constructor, as a mandatory procedure that takes an
@code{operating-system} record as argument and returns an @code{image}
record.

@end table
@end deftp

There are several @code{image-type} records provided by the @code{(gnu
system image)} and the @code{(gnu system images @dots{})} modules.

@defvar mbr-raw-image-type
Crie uma imagem baseada na imagem @code{mbr-disk-image}.
@end defvar

@defvar mbr-hybrid-raw-image-type
Build an image based on the @code{mbr-hybrid-disk-image} image.
@end defvar

@defvar efi-raw-image-type
Build an image based on the @code{efi-disk-image} image.
@end defvar

@defvar efi32-raw-image-type
Build an image based on the @code{efi32-disk-image} image.
@end defvar

@defvar qcow2-image-type
Build an image based on the @code{mbr-disk-image} image but with the
@code{compressed-qcow2} image format. The resulting image will have an MBR
embedded bootloader as well as an EFI bootloader. This image is not suitable
for architectures that do not support `grub-pc`, such as AArch64. See
@code{qcow2-gpt-image-type} for an alternative.
@end defvar

@defvar qcow2-gpt-image-type
Build an image based on the @code{efi-disk-image} image but with the
@code{compressed-qcow2} image format. The resulting image will have only EFI
bootloader, unlike @code{qcow2-image-type}. This image is suitable for
architectures that do not support `grub-pc`, such as AArch64.
@end defvar

@defvar iso-image-type
Build a compressed image based on the @code{iso9660-image} image.
@end defvar

@defvar uncompressed-iso-image-type
Build an image based on the @code{iso9660-image} image but with the
@code{compression?} field set to @code{#false}.
@end defvar

@defvar docker-image-type
Build an image based on the @code{docker-image} image.
@end defvar

@defvar raw-with-offset-image-type
Crie uma imagem MBR com uma única partição começando em um deslocamento
@code{1024KiB}. Isso é útil para deixar algum espaço para instalar um
bootloader na lacuna pós-MBR.
@end defvar

@defvar pinebook-pro-image-type
Build an image that is targeting the Pinebook Pro machine.  The MBR image
contains a single partition starting at a @code{9MiB} offset.  The
@code{u-boot-pinebook-pro-rk3399-bootloader} bootloader will be installed in
this gap.
@end defvar

@defvar rock64-image-type
Build an image that is targeting the Rock64 machine.  The MBR image contains
a single partition starting at a @code{16MiB} offset.  The
@code{u-boot-rock64-rk3328-bootloader} bootloader will be installed in this
gap.
@end defvar

@defvar novena-image-type
Build an image that is targeting the Novena machine.  It has the same
characteristics as @code{raw-with-offset-image-type}.
@end defvar

@defvar pine64-image-type
Build an image that is targeting the Pine64 machine.  It has the same
characteristics as @code{raw-with-offset-image-type}.
@end defvar

@defvar hurd-image-type
Build an image that is targeting a @code{i386} machine running the Hurd
kernel.  The MBR image contains a single ext2 partitions with specific
@code{file-system-options} flags.
@end defvar

@defvar hurd-qcow2-image-type
Build an image similar to the one built by the @code{hurd-image-type} but
with the @code{format} set to @code{'compressed-qcow2}.
@end defvar

@defvar wsl2-image-type
Build an image for the @acronym{WSL2, Windows Subsystem for Linux 2}.  It
can be imported by running:

@example
wsl --import Guix ./guix ./wsl2-image.tar.gz
wsl -d Guix
@end example

@end defvar

Então, se voltarmos ao comando @code{guix system image} tomando uma
declaração @code{operating-system} como argumento. Por padrão, o
@code{mbr-raw-image-type} é usado para transformar o @code{operating-system}
fornecido em uma imagem inicializável real.

Para usar um @code{image-type} diferente, a opção @code{--image-type} pode
ser usada. A opção @code{--list-image-types} listará todos os tipos de
imagem suportados. Acontece que é uma listagem textual de todas as variáveis
@code{image-types} descritas logo acima (@pxref{Invocando guix system}).

@node Módulos de imagem
@section Módulos de imagem

Vamos pegar o exemplo do Pine64, uma máquina baseada em ARM. Para poder
produzir uma imagem direcionada a essa placa, precisamos dos seguintes
elementos:

@itemize
@item Um registro @code{operating-system} contendo pelo menos
um kernel apropriado (@code{linux-libre-arm64-generic}) e bootloader
@code{u-boot-pine64-lts-bootloader}) para o Pine64.

@item Possibly, an @code{image-type} record providing a way to
turn an @code{operating-system} record to an @code{image} record suitable
for the Pine64.

@item An actual @code{image} that can be instantiated with the
@command{guix system image} command.

@end itemize

The @code{(gnu system images pine64)} module provides all those elements:
@code{pine64-barebones-os}, @code{pine64-image-type} and
@code{pine64-barebones-raw-image} respectively.

The module returns the @code{pine64-barebones-raw-image} in order for users
to be able to run:

@example
guix system image gnu/system/images/pine64.scm
@end example

Now, thanks to the @code{pine64-image-type} record declaring the
@code{'pine64-raw} @code{image-type}, one could also prepare a
@code{my-pine.scm} file with the following content:

@lisp
(use-modules (gnu system images pine64))
(operating-system
  (inherit pine64-barebones-os)
  (timezone "Europe/Athens"))
@end lisp

to customize the @code{pine64-barebones-os}, and run:

@example
$ guix system image --image-type=pine64-raw my-pine.scm
@end example

Note that there are other modules in the @code{gnu/system/images} directory
targeting @code{Novena}, @code{Pine64}, @code{PinebookPro} and @code{Rock64}
machines.

@node Instalando arquivos de depuração
@chapter Instalando arquivos de depuração

@cindex debugging files
Program binaries, as produced by the GCC compilers for instance, are
typically written in the ELF format, with a section containing
@dfn{debugging information}.  Debugging information is what allows the
debugger, GDB, to map binary code to source code; it is required to debug a
compiled program in good conditions.

This chapter explains how to use separate debug info when packages provide
it, and how to rebuild packages with debug info when it's missing.

@menu
* Informações de depuração separadas::  Instalando saídas de 'depuração'.
* Reconstruindo informações de depuração::  Informações de depuração 
                                              ausentes no edifício.
@end menu

@node Informações de depuração separadas
@section Informações de depuração separadas

O problema com informações de depuração é que elas ocupam uma quantidade
considerável de espaço em disco. Por exemplo, informações de depuração para
a GNU C Library pesam mais de 60 MiB@. Assim, como usuário, manter todas as
informações de depuração de todos os programas instalados geralmente não é
uma opção. No entanto, a economia de espaço não deve vir ao custo de um
impedimento à depuração --- especialmente no sistema GNU, o que deve tornar
mais fácil para os usuários exercerem sua liberdade de computação
(@pxref{Distribuição GNU}).

Thankfully, the GNU Binary Utilities (Binutils) and GDB provide a mechanism
that allows users to get the best of both worlds: debugging information can
be stripped from the binaries and stored in separate files.  GDB is then
able to load debugging information from those files, when they are available
(@pxref{Separate Debug Files,,, gdb, Debugging with GDB}).

The GNU distribution takes advantage of this by storing debugging
information in the @code{lib/debug} sub-directory of a separate package
output unimaginatively called @code{debug} (@pxref{Pacotes com múltiplas saídas}).  Users can choose to install the @code{debug} output of a package
when they need it.  For instance, the following command installs the
debugging information for the GNU C Library and for GNU Guile:

@example
guix install glibc:debug guile:debug
@end example

GDB must then be told to look for debug files in the user's profile, by
setting the @code{debug-file-directory} variable (consider setting it from
the @file{~/.gdbinit} file, @pxref{Startup,,, gdb, Debugging with GDB}):

@example
(gdb) set debug-file-directory ~/.guix-profile/lib/debug
@end example

From there on, GDB will pick up debugging information from the @file{.debug}
files under @file{~/.guix-profile/lib/debug}.

Below is an alternative GDB script which is useful when working with other
profiles.  It takes advantage of the optional Guile integration in GDB.
This snippet is included by default on Guix System in the @file{~/.gdbinit}
file.

@example
guile
(use-modules (gdb))
(execute (string-append "set debug-file-directory "
                        (or (getenv "GDB_DEBUG_FILE_DIRECTORY")
                            "~/.guix-profile/lib/debug")))
end
@end example

In addition, you will most likely want GDB to be able to show the source
code being debugged.  To do that, you will have to unpack the source code of
the package of interest (obtained with @code{guix build --source},
@pxref{Invocando guix build}), and to point GDB to that source directory
using the @code{directory} command (@pxref{Source Path, @code{directory},,
gdb, Debugging with GDB}).

@c XXX: keep me up-to-date
The @code{debug} output mechanism in Guix is implemented by the
@code{gnu-build-system} (@pxref{Sistemas de compilação}).  Currently, it is
opt-in---debugging information is available only for the packages with
definitions explicitly declaring a @code{debug} output.  To check whether a
package has a @code{debug} output, use @command{guix package
--list-available} (@pxref{Invocando guix package}).

Read on for how to deal with packages lacking a @code{debug} output.

@node Reconstruindo informações de depuração
@section Reconstruindo informações de depuração

@cindex debugging info, rebuilding
Como vimos acima, alguns pacotres, mas não todos, provêem informação de
depuração numa saída @code{debug}.  O que podemos fazer quando informação de
depuração está faltando? A opção @option{--with-debug-info} provê uma
solução para isso: ela te permite reconstruir os pacotes para os quais a
informação está faltando --- e nomente estes --- e exertá-los no aplicativo
que você está deupurando.  Portanto, enquanto isso não é tão rápido quanto a
instalação de uma saída do @code{debug}, isso é relativamente menos custoso.

Let's illustrate that.  Suppose you're experiencing a bug in Inkscape and
would like to see what's going on in GLib, a library that's deep down in its
dependency graph.  As it turns out, GLib does not have a @code{debug} output
and the backtrace GDB shows is all sadness:

@example
(gdb) bt
#0  0x00007ffff5f92190 in g_getenv ()
   from /gnu/store/@dots{}-glib-2.62.6/lib/libglib-2.0.so.0
#1  0x00007ffff608a7d6 in gobject_init_ctor ()
   from /gnu/store/@dots{}-glib-2.62.6/lib/libgobject-2.0.so.0
#2  0x00007ffff7fe275a in call_init (l=<optimized out>, argc=argc@@entry=1, argv=argv@@entry=0x7fffffffcfd8,
    env=env@@entry=0x7fffffffcfe8) at dl-init.c:72
#3  0x00007ffff7fe2866 in call_init (env=0x7fffffffcfe8, argv=0x7fffffffcfd8, argc=1, l=<optimized out>)
    at dl-init.c:118
@end example

To address that, you install Inkscape linked against a variant GLib that
contains debug info:

@example
guix install inkscape --with-debug-info=glib
@end example

This time, debugging will be a whole lot nicer:

@example
$ gdb --args sh -c 'exec inkscape'
@dots{}
(gdb) b g_getenv
Function "g_getenv" not defined.
Make breakpoint pending on future shared library load? (y or [n]) y
Breakpoint 1 (g_getenv) pending.
(gdb) r
Starting program: /gnu/store/@dots{}-profile/bin/sh -c exec\ inkscape
@dots{}
(gdb) bt
#0  g_getenv (variable=variable@@entry=0x7ffff60c7a2e "GOBJECT_DEBUG") at ../glib-2.62.6/glib/genviron.c:252
#1  0x00007ffff608a7d6 in gobject_init () at ../glib-2.62.6/gobject/gtype.c:4380
#2  gobject_init_ctor () at ../glib-2.62.6/gobject/gtype.c:4493
#3  0x00007ffff7fe275a in call_init (l=<optimized out>, argc=argc@@entry=3, argv=argv@@entry=0x7fffffffd088,
    env=env@@entry=0x7fffffffd0a8) at dl-init.c:72
@dots{}
@end example

Much better!

Note that there can be packages for which @option{--with-debug-info} will
not have the desired effect.  @xref{Opções de transformação de pacote,
@option{--with-debug-info}}, for more information.

@node Usando TeX e LaTeX
@chapter Usando @TeX{} e @LaTeX{}

@cindex pacotes @TeX{}
@cindex pacotes @LaTeX{}
Guix provê pacotes para os @TeX{}, @LaTeX{}, ConTeXt, LuaTeX e sistemas de
tipografia afins, retirados da @uref{https://www.tug.org/texlive/,
distribuição @TeX{} Live}.  Por conta da @TeX{} Live ser tão grande e
encontrar um método neste labirinto é complicado, essa seção providenciará
um guia de como implantar os pacotes relevantes para compilar documentos
@TeX{} e @LaTeX{}.

@TeX{} Live atualmente vem em dois sabores mutualmente excluisvos no Guix:

@itemize
@item
O pacote ``monolítico'' @code{texlive}: vem com @emph{todo pacote único da
@TeX{} Live} (rigorosamente 4.200), mas isso é enorme --- mais que
4@tie{}GiB para um único pacote!

@item
Uma distribuição ``modular'' da @TeX{} Live, na qual você instala os pacotes
que você necessita, cujo nome é sempre prefixado com @samp{texlive-}.
@end itemize

To insist, these two flavors cannot be combined@footnote{No rule without
exception! As the monolithic @TeX{} Live does not contain the
@command{biber} executable, it is okay to combine it with
@code{texlive-biber}, which does.}.  If in the modular setting your document
does not compile, the solution is not to add the monolithic @code{texlive}
package, but to add the set of missing packages from the modular
distribution.

Building a coherent system that provides all the essential tools and, at the
same time, satisfies all of its internal dependencies can be a difficult
task.  It is therefore recommended to start with sets of packages, called
@dfn{collections}, and @dfn{schemes}, the name for collections of
collections.  The following command lists available schemes and collections
(@pxref{guix-search,, Invoking guix package}):

@example
guix search texlive-\(scheme\|collection\) | recsel -p name,description
@end example

Se necessário, você pode completar seu sistema com pacotes individuais,
principalmente quando eles pertencem a uma coleção grande na qual você não
tem interesse.

Por exemplo. o seguinte manifesto e algo razoável, e ainda um ponto de
partidal frugal para um usuário francês de @LaTeX{}:

@lisp
(specifications->manifest
 '("rubber"

   "texlive-scheme-basic"
   "texlive-collection-latexrecommended"
   "texlive-collection-fontsrecommended"
   "texlive-babel-french"

   ;; From "latexextra" collection.
   "texlive-tabularray"
   ;; From "binextra" collection.
   "texlive-texdoc"))
@end lisp

If you come across a document that does not compile in such a basic setting,
the main difficulty is finding the missing packages.  In this case,
@command{pdflatex} and similar commands tend to fail with obscure error
messages along the lines of:

@example
doc.tex: File `tikz.sty' not found.
doc.tex:7: Emergency stop.
@end example

@noindent
or, for a missing font:

@example
kpathsea: Running mktexmf phvr7t
! I can't find file `phvr7t'.
@end example

Como determinar qual é o pacote que falta? No primeiro caso, encontrará a
resposta executando:

@example
$ guix search texlive tikz
name: texlive-pgf
version: 59745
@dots{}
@end example

No segundo caso, @command{guix search} não fornece nada.  Ao invés disso,
você pode buscar na base de dados de pacotes do @TeX{} Live usando o comando
@command{tlmgr}:

@example
$ tlmgr info phvr7t
tlmgr: cannot find package phvr7t, searching for other matches:

Packages containing `phvr7t' in their title/description:

Packages containing files matching `phvr7t':
helvetic:
        texmf-dist/fonts/tfm/adobe/helvetic/phvr7t.tfm
        texmf-dist/fonts/tfm/adobe/helvetic/phvr7tn.tfm
        texmf-dist/fonts/vf/adobe/helvetic/phvr7t.vf
        texmf-dist/fonts/vf/adobe/helvetic/phvr7tn.vf
tex4ht:
        texmf-dist/tex4ht/ht-fonts/alias/adobe/helvetic/phvr7t.htf
@end example

@noindent
O arquivo está disponível no pacote @TeX{} Live @code{helvetic}, que é
conhecido no Guix como @code{texlive-helvetic}. Uma viagem e tanto, mas você
encontrou!

@node Atualizações de segurança
@chapter Atualizações de segurança

@cindex atualizações de segurança
@cindex security vulnerabilities
Ocasionalmente, vulnerabilidades de segurança importantes são descobertas em
pacotes de software e devem ser corrigidas. Os desenvolvedores do Guix se
esforçam para manter o controle das vulnerabilidades conhecidas e aplicar
correções o mais rápido possível no branch @code{master} do Guix (ainda não
fornecemos um branch ``stable'' contendo apenas atualizações de
segurança). A ferramenta @command{guix lint} ajuda os desenvolvedores a
descobrirem sobre versões vulneráveis de pacotes de software na
distribuição:

@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{Invocando guix lint}, para mais informações.

Guix segue uma disciplina de gerenciamento de pacotes funcional
(@pxref{Introdução}), o que implica que, quando um pacote é alterado,
@emph{todo pacote que depende dele} deve ser reconstruído. Isso pode
desacelerar significativamente a implantação de correções em pacotes
principais, como libc ou Bash, já que basicamente toda a distribuição
precisaria ser reconstruída. Usar binários pré-construídos ajuda
(@pxref{Substitutos}), mas a implantação ainda pode levar mais tempo do que
o desejado.

@cindex grafts
To address this, Guix implements @dfn{grafts}, a mechanism that allows for
fast deployment of critical updates without the costs associated with a
whole-distribution rebuild.  The idea is to rebuild only the package that
needs to be patched, and then to ``graft'' it onto packages explicitly
installed by the user and that were previously referring to the original
package.  The cost of grafting is typically very low, and order of
magnitudes lower than a full rebuild of the dependency chain.

@cindex replacements of packages, for grafts
For instance, suppose a security update needs to be applied to Bash.  Guix
developers will provide a package definition for the ``fixed'' Bash, say
@code{bash-fixed}, in the usual way (@pxref{Definindo pacotes}).  Then, the
original package definition is augmented with a @code{replacement} field
pointing to the package containing the bug fix:

@lisp
(define bash
  (package
    (name "bash")
    ;; @dots{}
    (replacement bash-fixed)))
@end lisp

From there on, any package depending directly or indirectly on Bash---as
reported by @command{guix gc --requisites} (@pxref{Invocando guix gc})---that
is installed is automatically ``rewritten'' to refer to @code{bash-fixed}
instead of @code{bash}.  This grafting process takes time proportional to
the size of the package, usually less than a minute for an ``average''
package on a recent machine.  Grafting is recursive: when an indirect
dependency requires grafting, then grafting ``propagates'' up to the package
that the user is installing.

Currently, the length of the name and version of the graft and that of the
package it replaces (@code{bash-fixed} and @code{bash} in the example above)
must be equal.  This restriction mostly comes from the fact that grafting
works by patching files, including binary files, directly.  Other
restrictions may apply: for instance, when adding a graft to a package
providing a shared library, the original shared library and its replacement
must have the same @code{SONAME} and be binary-compatible.

The @option{--no-grafts} command-line option allows you to forcefully avoid
grafting (@pxref{Opções de compilação comuns, @option{--no-grafts}}).  Thus, the
command:

@example
guix build bash --no-grafts
@end example

@noindent
returns the store file name of the original Bash, whereas:

@example
guix build bash
@end example

@noindent
returns the store file name of the ``fixed'', replacement Bash.  This allows
you to distinguish between the two variants of Bash.

To verify which Bash your whole profile refers to, you can run
(@pxref{Invocando guix gc}):

@example
guix gc -R $(readlink -f ~/.guix-profile) | grep bash
@end example

@noindent
@dots{} e compare os nomes dos arquivos de armazém que você obtém com os
acima. Da mesma forma para uma geração completa do sistema Guix:

@example
guix gc -R $(guix system build my-config.scm) | grep bash
@end example

Por fim, para verificar quais processos Bash estão em execução, você pode
usar o comando @command{lsof}:

@example
lsof | grep /gnu/store/.*bash
@end example


@node Inicializando
@chapter Inicializando

@c Adapted from the ELS 2013 paper.

@cindex inicialização

Bootstrapping em nosso contexto se refere a como a distribuição é construída
``do nada''. Lembre-se de que o ambiente de construção de uma derivação não
contém nada além de suas entradas declaradas (@pxref{Introdução}). Então há
um problema óbvio de galinha e ovo: como o primeiro pacote é construído?
Como o primeiro compilador é compilado?

É tentador pensar nessa questão como algo com que apenas hackers obstinados
podem se importar. No entanto, embora a resposta a essa questão seja de
natureza técnica, suas implicações são abrangentes. Como a distribuição é
bootstrapped define até que ponto nós, como indivíduos e como um coletivo de
usuários e hackers, podemos confiar no software que executamos. É uma
preocupação central do ponto de vista da @emph{segurança} e do ponto de
vista da @emph{liberdade do usuário}.

@cindex binários bootstrap
O sistema GNU é feito principalmente de código C, com libc em seu núcleo. O
próprio sistema de construção GNU assume a disponibilidade de um Bourne
shell e ferramentas de linha de comando fornecidas pelo GNU Coreutils, Awk,
Findutils, `sed' e `grep'. Além disso, programas de construção --- programas
que executam @code{./configure}, @code{make}, etc. --- são escritos em Guile
Scheme (@pxref{Derivações}). Consequentemente, para ser capaz de construir
qualquer coisa, do zero, Guix depende de binários pré-construídos de Guile,
GCC, Binutils, libc e os outros pacotes mencionados acima --- os
@dfn{binários bootstrap}.

Esses binários bootstrap são ``considerados garantidos'', embora também
possamos recriá-los se necessário (@pxref{Preparando para usar os binários do Bootstrap}).

@menu
* Bootstrap de código fonte completo::  Um Bootstrap digno do GNU.
* Preparando para usar os binários do Bootstrap::  Construindo o que mais 
                                                     importa.
@end menu

@node Bootstrap de código fonte completo
@section O Bootstrap de código fonte completo

Guix---como outras distribuições GNU/Linux---é tradicionalmente bootstrapado
a partir de um conjunto de binários bootstrap: Bourne shell, ferramentas de
linha de comando fornecidas pelo GNU Coreutils, Awk, Findutils, ``sed' e
`grep' e Guile, GCC, Binutils e a GNU C Library
(@pxref{Inicializando}). Normalmente, esses binários bootstrap são
``considerados garantidos.''

Tomar os binários bootstrap como garantidos significa que os consideramos
uma ``semente'' correta e confiável para construir o sistema completo. Aí
está um problema: o tamanho combinado desses binários bootstrap é de cerca
de 250 MB (@pxref{Bootstrappable Builds,,, mes, GNU Mes}). Auditar ou mesmo
inspecionar isso é quase impossível.

@c XXX TODO: update to savannah url, once accepted there
Para @code{i686-linux} e @code{x86_64-linux}, o Guix agora apresenta um
@dfn{full-source bootstrap}. Este bootstrap está enraizado em
@file{hex0-seed} do pacote @url{https://savannah.gnu.org/projects/stage0,
Stage0}. O programa hex0 é um assembler minimalista: ele lê dígitos
hexadecimais separados por espaços (nibbles) de um arquivo, possivelmente
incluindo comentários, e emite na saída padrão os bytes correspondentes a
esses números hexadecimais. O código-fonte deste programa hex0 inicial é um
arquivo chamado
@url{https://github.com/oriansj/bootstrap-seeds/blob/master/POSIX/x86/hex0_x86.hex0,@file{hex0_x86.hex0}}
e é escrito na linguagem @code{hex0}.

O Hex0 é auto-hospedado, o que significa que ele pode se construir:

@example
./hex0-seed hex0_x86.hex0 hex0
@end example

Hex0 é o equivalente ASCII do programa binário e pode ser produzido fazendo
algo muito parecido com:

@example
sed 's/[;#].*$//g' hex0_x86.hex0 | xxd -r -p > hex0
chmod +x hex0
@end example

É por causa dessa equivalência ASCII-binário que podemos abençoar esse
binário inicial de 357 bytes como fonte e, portanto, `bootstrap de fonte
completa''.

O bootstrap então continua: @code{hex0} constrói @code{hex1} e então para
@code{M0}, @code{hex2}, @code{M1}, @code{mescc-tools} e finalmente
@code{M2-Planet}. Então, usando @code{mescc-tools}, @code{M2-Planet} nós
construímos Mes (@pxref{Top, GNU Mes Reference Manual,, mes, GNU Mes}, um
interpretador Scheme e compilador C em Scheme). A partir daqui começa o
bootstrap mais tradicional baseado em @code{C} do Sistema GNU.

Outro passo que o Guix tomou foi substituir o shell e todos os seus
utilitários por implementações no Guile Scheme, o @emph{Scheme-only
bootstrap}. O Gash (@pxref{Gash,,, gash, The Gash manual}) é um shell
compatível com POSIX que substitui o Bash, e vem com o Gash Utils, que tem
substituições minimalistas para o Awk, o GNU Core Utilities, Grep, Gzip, Sed
e Tar.

Atualmente, construir o Sistema GNU a partir do código-fonte só é possível
adicionando alguns pacotes históricos do GNU como etapas
intermediárias@footnote{Pacotes como @code{gcc-2.95.3},
@code{binutils-2.14}, @code{glibc-2.2.5}, @code{gzip-1.2.4}, @code{tar-1.22}
e alguns outros. Para detalhes, veja
@file{gnu/packages/commencement.scm}.}. Conforme o Gash e o Gash Utils
amadurecem, e os pacotes GNU se tornam mais inicializáveis novamente (por
exemplo, novos lançamentos do GNU Sed também serão enviados como tarballs
compactados novamente, como alternativa à compressão @code{xz} difícil de
inicializar), esse conjunto de pacotes adicionados pode ser reduzido
novamente.

O grafo abaixo mostra o grafo de dependência resultante para
@code{gcc-core-mesboot0}, o compilador bootstrap usado para o bootstrap
tradicional do restante do Sistema Guix.

@c ./pre-inst-env guix graph \
@c   -e '(@@ (gnu packages commencement) gcc-core-mesboot0)' \
@c   | sed -r \
@c     -e 's,((bootstrap-seeds|guile-bootstrap).*shape =) box,\1 ellipse,' \
@c     -e 's,fontname = sans,fontname = "dejavu sans",' \
@c   > doc/images/gcc-core-mesboot0-graph.dot
@image{images/gcc-core-mesboot0-graph,6in,,Dependency graph of
gcc-core-mesboot0}

O trabalho está em andamento para levar esses bootstraps às arquiteturas
@code{arm-linux} e @code{aarch64-linux} e ao Hurd.

Se você estiver interessado, junte-se a nós em @samp{#bootstrappable} na
rede IRC Libera.Chat ou discuta em @email{bug-mes@@gnu.org} ou
@email{gash-devel@@nongnu.org}.

@node Preparando para usar os binários do Bootstrap
@section Preparando para usar os binários do Bootstrap

@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 dependência das primeiras
derivações do bootstrap}

A figura acima mostra o início do grafo de dependência da distribuição,
correspondendo às definições de pacote do módulo @code{(gnu packages
bootstrap)}. Uma figura similar pode ser gerada com @command{guix graph}
(@pxref{Invocando guix graph}), ao longo das linhas de:

@example
guix graph -t derivation \
  -e '(@@@@ (gnu packages bootstrap) %bootstrap-gcc)' \
  | dot -Tps > gcc.ps
@end example

ou, para o bootstrap de semente binária reduzida

@example
guix graph -t derivation  \
-e '(@@@@ (pacotes gnu bootstrap) %bootstrap-mes)' \
| ponto -Tps > mes.ps
@end example

Neste nível de detalhe, as coisas são um pouco complexas. Primeiro, o
próprio Guile consiste em um executável ELF, junto com muitas fontes e
arquivos de Scheme compilados que são carregados dinamicamente quando ele é
executado. Isso é armazenado no tarball @file{guile-2.0.7.tar.xz} mostrado
neste grafo. Este tarball é parte da distribuição de ``fontes'' do Guix e é
inserido no armazém com @code{add-to-store} (@pxref{O armazém}).

Mas como escrevemos uma derivação que descompacta esse tarball e o adiciona
ao armazém? Para resolver esse problema, a derivação
@code{guile-bootstrap-2.0.drv} --- a primeira que é construída --- usa
@code{bash} como seu construtor, que executa
@code{build-bootstrap-guile.sh}, que por sua vez chama @code{tar} para
descompactar o tarball. Assim, @file{bash}, @file{tar}, @file{xz} e
@file{mkdir} são binários estaticamente vinculados, também parte da
distribuição de fontes do Guix, cujo único propósito é permitir que o
tarball do Guile seja descompactado.

Uma vez que @code{guile-bootstrap-2.0.drv} é construído, temos um Guile
funcional que pode ser usado para executar programas de construção
subsequentes. Sua primeira tarefa é baixar tarballs contendo os outros
binários pré-construídos --- é isso que as derivações @file{.tar.xz.drv}
fazem. Módulos Guix como @code{ftp-client.scm} são usados para esse
propósito. As derivações @code{module-import.drv} importam esses módulos em
um diretório no armazém, usando o layout original. As derivações
@code{module-import-compiled.drv} compilam esses módulos e os escrevem em um
diretório de saída com o layout correto. Isso corresponde ao argumento
@code{#:modules} de @code{build-expression->derivation}
(@pxref{Derivações}).

Por fim, os vários tarballs são descompactados pelas derivações
@code{gcc-bootstrap-0.drv}, @code{glibc-bootstrap-0.drv} ou
@code{bootstrap-mes-0.drv} e @code{bootstrap-mescc-tools-0.drv}, ponto em
que temos uma cadeia de ferramentas C funcional.

@unnumberedsec Construindo as ferramentas de construção

O bootstrapping está completo quando temos uma cadeia de ferramentas
completa que não depende das ferramentas bootstrap pré-construídas
discutidas acima. Esse requisito de não dependência é verificado verificando
se os arquivos da cadeia de ferramentas final contêm referências aos
diretórios @file{/gnu/store} das entradas bootstrap. O processo que leva a
essa cadeia de ferramentas ``final'' é descrito pelas definições de pacote
encontradas no módulo @code{(gnu packages commencement)}.

O comando @command{guix graph} nos permite ``diminuir o zoom'' em comparação
ao grafo acima, observando o nível de objetos do pacote em vez de derivações
individuais --- lembre-se de que um pacote pode ser traduzido para várias
derivações, normalmente uma derivação para baixar sua fonte, uma para
construir os módulos Guile de que ele precisa e uma para realmente construir
o pacote a partir da fonte. O comando:

@example
guix graph -t bag \
  -e '(@@@@ (gnu packages commencement)
          glibc-final-with-bootstrap-bash)' | xdot -
@end example

@noindent
exibe o grafo de dependência que leva à biblioteca C ``final''@footnote{Você
pode notar o rótulo @code{glibc-intermediate}, sugerindo que ela não é
@emph{completamente} final, mas como uma boa aproximação, a consideraremos
final.}, descrita abaixo.

@image{images/bootstrap-packages,6in,,Grafo de dependência dos primeiros
pacotes}

@c See <https://lists.gnu.org/archive/html/gnu-system-discuss/2012-10/msg00000.html>.
A primeira ferramenta que é construída com os binários bootstrap é o
GNU@tie{}Make---observado @code{make-boot0} acima---que é um pré-requisito
para todos os pacotes seguintes. A partir daí, Findutils e Diffutils são
construídos.

Então vêm os Binutils e GCC de primeiro estágio, construídos como pseudo
cross tools---i.e., com @option{--target} igual a @option{--host}. Eles são
usados para construir a libc. Graças a esse truque de cross-build, essa libc
tem a garantia de não manter nenhuma referência à cadeia de ferramentas
inicial.

A partir daí, os Binutils finais e o GCC (não mostrados acima) são
construídos. O GCC usa @command{ld} dos Binutils finais e vincula programas
à libc recém-construída. Essa cadeia de ferramentas é usada para construir
os outros pacotes usados pelo Guix e pelo GNU Build System: Guile, Bash,
Coreutils, etc.

E voilà! Neste ponto, temos o conjunto completo de ferramentas de construção
que o GNU Build System espera. Elas estão na variável @code{%final-inputs}
do módulo @code{(gnu packages commencement)} e são implicitamente usadas por
qualquer pacote que use @code{gnu-build-system} (@pxref{Sistemas de compilação,
@code{gnu-build-system}}).


@unnumberedsec Construindo os binários Bootstrap

@cindex binários bootstrap
Because the final tool chain does not depend on the bootstrap binaries,
those rarely need to be updated.  Nevertheless, it is useful to have an
automated way to produce them, should an update occur, and this is what the
@code{(gnu packages make-bootstrap)} module provides.

The following command builds the tarballs containing the bootstrap binaries
(Binutils, GCC, glibc, for the traditional bootstrap and
linux-libre-headers, bootstrap-mescc-tools, bootstrap-mes for the Reduced
Binary Seed bootstrap, and Guile, and a tarball containing a mixture of
Coreutils and other basic command-line tools):

@example
guix build bootstrap-tarballs
@end example

The generated tarballs are those that should be referred to in the
@code{(gnu packages bootstrap)} module mentioned at the beginning of this
section.

Still here? Then perhaps by now you've started to wonder: when do we reach a
fixed point? That is an interesting question! The answer is unknown, but if
you would like to investigate further (and have significant computational
and storage resources to do so), then let us know.

@unnumberedsec Reducing the Set of Bootstrap Binaries

Our traditional bootstrap includes GCC, GNU Libc, Guile, etc.  That's a lot
of binary code! Why is that a problem? It's a problem because these big
chunks of binary code are practically non-auditable, which makes it hard to
establish what source code produced them.  Every unauditable binary also
leaves us vulnerable to compiler backdoors as described by Ken Thompson in
the 1984 paper @emph{Reflections on Trusting Trust}.

This is mitigated by the fact that our bootstrap binaries were generated
from an earlier Guix revision.  Nevertheless it lacks the level of
transparency that we get in the rest of the package dependency graph, where
Guix always gives us a source-to-binary mapping.  Thus, our goal is to
reduce the set of bootstrap binaries to the bare minimum.

The @uref{https://bootstrappable.org, Bootstrappable.org web site} lists
on-going projects to do that.  One of these is about replacing the bootstrap
GCC with a sequence of assemblers, interpreters, and compilers of increasing
complexity, which could be built from source starting from a simple and
auditable assembler.

Our first major achievement is the replacement of GCC, the GNU C Library and
Binutils by MesCC-Tools (a simple hex linker and macro assembler) and Mes
(@pxref{Top, GNU Mes Reference Manual,, mes, GNU Mes}, a Scheme interpreter
and C compiler in Scheme).  Neither MesCC-Tools nor Mes can be fully
bootstrapped yet and thus we inject them as binary seeds.  We call this the
Reduced Binary Seed bootstrap, as it has halved the size of our bootstrap
binaries! Also, it has eliminated the C compiler binary; i686-linux and
x86_64-linux Guix packages are now bootstrapped without any binary C
compiler.

Work is ongoing to make MesCC-Tools and Mes fully bootstrappable and we are
also looking at any other bootstrap binaries.  Your help is welcome!

@node Portando
@chapter Portando para uma nova plataforma

As discussed above, the GNU distribution is self-contained, and
self-containment is achieved by relying on pre-built ``bootstrap binaries''
(@pxref{Inicializando}).  These binaries are specific to an operating system
kernel, CPU architecture, and application binary interface (ABI).  Thus, to
port the distribution to a platform that is not yet supported, one must
build those bootstrap binaries, and update the @code{(gnu packages
bootstrap)} module to use them on that platform.

Fortunately, Guix can @emph{cross compile} those bootstrap binaries.  When
everything goes well, and assuming the GNU tool chain supports the target
platform, this can be as simple as running a command like this one:

@example
guix build --target=armv5tel-linux-gnueabi bootstrap-tarballs
@end example

For this to work, it is first required to register a new platform as defined
in the @code{(guix platform)} module.  A platform is making the connection
between a GNU triplet (@pxref{Specifying Target Triplets, GNU configuration
triplets,, autoconf, Autoconf}), the equivalent @var{system} in Nix
notation, the name of the @var{glibc-dynamic-linker}, and the corresponding
Linux architecture name if applicable (@pxref{Plataformas}).

Once the bootstrap tarball are built, the @code{(gnu packages bootstrap)}
module needs to be updated to refer to these binaries on the target
platform.  That is, the hashes and URLs of the bootstrap tarballs for the
new platform must be added alongside those of the currently supported
platforms.  The bootstrap Guile tarball is treated specially: it is expected
to be available locally, and @file{gnu/local.mk} has rules to download it
for the supported architectures; a rule for the new platform must be added
as well.

In practice, there may be some complications.  First, it may be that the
extended GNU triplet that specifies an ABI (like the @code{eabi} suffix
above) is not recognized by all the GNU tools.  Typically, glibc recognizes
some of these, whereas GCC uses an extra @option{--with-abi} configure flag
(see @code{gcc.scm} for examples of how to handle this).  Second, some of
the required packages could fail to build for that platform.  Lastly, the
generated binaries could be broken for some reason.

@c *********************************************************************
@include contributing.pt_BR.texi

@c *********************************************************************
@node Agradecimentos
@chapter Agradecimentos

Guix é baseado no @uref{https://nixos.org/nix/, gerenciador de pacotes Nix},
que foi projetado e implementado por Eelco Dolstra, com contribuições de
outras pessoas (veja o arquivo @file{nix/AUTHORS} no Guix.) O Nix foi
pioneiro no gerenciamento funcional de pacotes e promoveu recursos sem
precedentes, como atualizações e reversões de pacotes transacionais, perfis
por usuário e processos de construção referencialmente transparentes. Sem
esse trabalho, o Guix não existiria.

As distribuições de software baseadas em Nix, Nixpkgs e NixOS, também foram
uma inspiração para o Guix.

O GNU@tie{}Guix em si é um trabalho coletivo com contribuições de várias
pessoas. Veja o arquivo @file{AUTHORS} no Guix para obter mais informações
sobre essas pessoas legais. O arquivo @file{THANKS} lista as pessoas que
ajudaram a relatar erros, cuidar da infraestrutura, fornecer ilustrações e
temas, fazer sugestões e muito mais -- obrigado!


@c *********************************************************************
@node Licença de Documentação Livre GNU
@appendix Licença de Documentação Livre GNU
@cindex licença, Licença de Documentação Livre GNU
@include fdl-1.3.texi

@c *********************************************************************
@node Índice de conceitos
@unnumbered Índice de conceitos
@printindex cp

@node Índice de programação
@unnumbered Índice de programação
@syncodeindex tp fn
@syncodeindex vr fn
@printindex fn

@bye

@c Local Variables:
@c ispell-local-dictionary: "american";
@c End:
