From 84133320b8fb70f093831203a028ed2ffb6082ce Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ludovic=20Court=C3=A8s?= Date: Sat, 2 May 2020 23:46:10 +0200 Subject: doc: Document committer authorization. * doc/contributing.texi (Commit Access): Add instructions for authorizing committers. --- doc/contributing.texi | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) (limited to 'doc') diff --git a/doc/contributing.texi b/doc/contributing.texi index 31b875f817..0ec7a48b96 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -1192,13 +1192,23 @@ Maintainers ultimately decide whether to grant you commit access, usually following your referrals' recommendation. @item +@cindex OpenPGP, signed commits If and once you've been given access, please send a message to @email{guix-devel@@gnu.org} to say so, again signed with the OpenPGP key you will use to sign commits (do that before pushing your first commit). That way, everyone can notice and ensure you control that OpenPGP key. -@c TODO: Add note about adding the fingerprint to the list of authorized -@c keys once that has stabilized. +@quotation Important +Before you can push for the first time, maintainers must: + +@enumerate +@item +add your OpenPGP key to the @code{keyring} branch; +@item +add your OpenPGP fingerprint to the @file{.guix-authorizations} file of +the branch(es) you will commit to. +@end enumerate +@end quotation @item Make sure to read the rest of this section and... profit! -- cgit v1.2.3 From 4a84deda7489f668cd833b59daeb504cbd87fa2b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ludovic=20Court=C3=A8s?= Date: Sat, 2 May 2020 23:53:25 +0200 Subject: doc: Recommend against SHA1 OpenPGP signatures. * doc/contributing.texi (Commit Access): Recommend against SHA1 signatures. --- doc/contributing.texi | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'doc') diff --git a/doc/contributing.texi b/doc/contributing.texi index 0ec7a48b96..9583120742 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -1187,6 +1187,16 @@ the OpenPGP key you will use to sign commits, and giving its fingerprint (see below). See @uref{https://emailselfdefense.fsf.org/en/}, for an introduction to public-key cryptography with GnuPG. +@c See . +Set up GnuPG such that it never uses the SHA1 hash algorithm for digital +signatures, which is known to be unsafe since 2019, for instance by +adding the following line to @file{~/.gnupg/gpg.conf} (@pxref{GPG +Esoteric Options,,, gnupg, The GNU Privacy Guard Manual}): + +@example +digest-algo sha512 +@end example + @item Maintainers ultimately decide whether to grant you commit access, usually following your referrals' recommendation. -- cgit v1.2.3 From 1f14e25c1969a93908288cb302a572f3cbbaa478 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ludovic=20Court=C3=A8s?= Date: Mon, 4 May 2020 10:50:18 +0200 Subject: doc: Add "Packages for C Development" section. Suggested by Bruno Haible in . * doc/guix.texi (Packages for C Development): New node. (Application Setup)[The GCC toolchain]: Empty and refer to it. --- doc/guix.texi | 43 +++++++++++++++++++++++++++---------------- 1 file changed, 27 insertions(+), 16 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index d5d8662937..64e3c01a50 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -1768,22 +1768,11 @@ can do so by running Emacs with the @code{--no-site-file} option @subsection The GCC toolchain -@cindex GCC -@cindex ld-wrapper - -Guix offers individual compiler packages such as @code{gcc} but if you -are in need of a complete toolchain for compiling and linking source -code what you really want is the @code{gcc-toolchain} package. This -package provides a complete GCC toolchain for C/C++ development, -including GCC itself, the GNU C Library (headers and binaries, plus -debugging symbols in the @code{debug} output), Binutils, and a linker -wrapper. - -The wrapper's purpose is to inspect the @code{-L} and @code{-l} switches -passed to the linker, add corresponding @code{-rpath} arguments, and -invoke the actual linker with this new set of arguments. You can instruct the -wrapper to refuse to link against libraries not in the store by setting the -@code{GUIX_LD_WRAPPER_ALLOW_IMPURITIES} environment variable to @code{no}. +@c XXX: The contents of this section were moved under +@c ``Development'', since it makes more sense there and is not specific +@c foreign distros. Remove it from here eventually? +@xref{Packages for C Development}, for information on packages for C/C++ +development. @node Upgrading Guix @section Upgrading Guix @@ -4681,6 +4670,7 @@ easily distributed to users who do not run Guix. @menu * Invoking guix environment:: Setting up development environments. * Invoking guix pack:: Creating software bundles. +* Packages for C Development:: Working with C code with Guix. @end menu @node Invoking guix environment @@ -5344,6 +5334,27 @@ In addition, @command{guix pack} supports all the common build options (@pxref{Common Build Options}) and all the package transformation options (@pxref{Package Transformation Options}). +@node Packages for C Development +@section Packages for C Development + +@cindex GCC +@cindex ld-wrapper +@cindex linker wrapper +@cindex toolchain, for C development + +If you need a complete toolchain for compiling and linking C or C++ +source code, use the @code{gcc-toolchain} package. This package +provides a complete GCC toolchain for C/C++ development, including GCC +itself, the GNU C Library (headers and binaries, plus debugging symbols +in the @code{debug} output), Binutils, and a linker wrapper. + +The wrapper's purpose is to inspect the @code{-L} and @code{-l} switches +passed to the linker, add corresponding @code{-rpath} arguments, and +invoke the actual linker with this new set of arguments. You can instruct the +wrapper to refuse to link against libraries not in the store by setting the +@code{GUIX_LD_WRAPPER_ALLOW_IMPURITIES} environment variable to @code{no}. + + @c ********************************************************************* @node Programming Interface -- cgit v1.2.3 From 9dbc7f50ab698e952b19e4f12476956be2fa43c4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ludovic=20Court=C3=A8s?= Date: Mon, 4 May 2020 14:58:26 +0200 Subject: doc: Remove prompt from X.509 examples. * doc/guix.texi (X.509 Certificates): Remove leading "$". --- doc/guix.texi | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index 64e3c01a50..0020739aec 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -26085,10 +26085,10 @@ pointed to by the @code{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" +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 @code{CURL_CA_BUNDLE} environment @@ -26096,8 +26096,8 @@ 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" +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 -- cgit v1.2.3 From 051f3254cd56aa8f3cb65a7e35ef8578af2cd3c5 Mon Sep 17 00:00:00 2001 From: pinoaffe Date: Tue, 5 May 2020 09:31:11 +0200 Subject: gnu: Add AutoSSH service. * gnu/services/ssh.scm (): New record type. (autossh-service-type): New variable. (autossh-service-activation, autossh-file-name): New procedures. * doc/guix.texi (Networking Services): Document this. Signed-off-by: Oleg Pykhalov --- doc/guix.texi | 75 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 75 insertions(+) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index 0020739aec..812d08a8ef 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -79,6 +79,7 @@ Copyright @copyright{} 2020 Naga Malleswari@* Copyright @copyright{} 2020 Brice Waegeneire@* Copyright @copyright{} 2020 R Veera Kumar@* Copyright @copyright{} 2020 Pierre Langlois@* +Copyright @copyright{} 2020 pinoaffe@* Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or @@ -14390,6 +14391,80 @@ Whether to enable password-based authentication. @end table @end deftp +@cindex AutoSSH +@deffn {Scheme Variable} autossh-service-type +This is the type for the @uref{https://www.harding.motd.ca/autossh, +AutoSSH} program that runs a copy of @code{ssh} and monitors it, +restarting it as necessary should it die or stop passing traffic. +AutoSSH can be run manually from the commandline by passing arguments to +the binary @code{autossh} from the package @code{autossh}, but it can +also be run as a guix service. This latter usecase is documented here. + +AutoSSH can be used to forward local traffic to a remote machine using an SSH tunnel, +and it respects the @file{~/.ssh/config} of the user it is run as. + +For example, to specify a service running autossh as the user @code{pino} +and forwarding all local connections to port @code{8081} to @code{remote:8081} +using an SSH tunnel, add this call to the operating system's @code{services} field: + +@lisp +(service autossh-service-type + (autossh-configuration + (user "pino") + (ssh-options (list "-T" "-N" "-L" "8081:localhost:8081" "remote.net")))) +@end lisp +@end deffn + +@deftp {Data Type} autossh-configuration +This data type represents the configuration of an AutoSSH service. + +@table @asis + +@item @code{user} (default @code{"autossh"}) +The user as which the AutoSSH service is to be run. +This assumes that the specified user exists. + +@item @code{poll} (default @code{600}) +Specifies the connection poll time in seconds. + +@item @code{first-poll} (default @code{#f}) +Specifies how long autossh waits before the first connection test in seconds. +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 (in seconds) how long an SSH connection must be active +before it is considered successful. + +@item @code{log-level} (default @code{1}) +The log level, corresponding to the levels used by syslog +(so @code{0} is the most silent while @code{7} is the chattiest.) + +@item @code{max-start} (default @code{#f}) +The maximum number of times SSH may be (re)started before AutoSSH exits. +When set to @code{#f}, no maximum is configured and AutoSSH may restart indefinitely. + +@item @code{message} (default @code{""}) +The message to append to the echo message sent when testing connections. + +@item @code{port} (default @code{"0"}) +The ports used for monitoring the connection. When set to @code{"0"}, +monitoring is disabled. When set to @code{"n"} where @code{n} is a positive integer, +ports @code{n} and @code{n+1} are used for monitoring the connection, such that +port @code{n} is the base monitoring port and @code{n+1} is the echo port. +When set to @code{"n:m"} where @code{n} and @code{m} are positive integers, +the ports @code{n} and @code{n+1} are used for monitoring the connection, such +that port @code{n} is the base monitoring port and @code{m} is the echo port. + +@item @code{ssh-options} (default @code{'()}) +The list of commandline arguments to pass to ssh when it is run. +Options @code{-f} and @code{-M ....} are reserved for AutoSSH +and may cause undefined behaviour. + +@end table +@end deftp + @defvr {Scheme Variable} %facebook-host-aliases This variable contains a string for use in @file{/etc/hosts} (@pxref{Host Names,,, libc, The GNU C Library Reference Manual}). Each -- cgit v1.2.3 From 826c2eecbe59daf338e4c19b1e42c725fefeef2e Mon Sep 17 00:00:00 2001 From: Nicolas Goaziou Date: Tue, 5 May 2020 16:38:29 +0200 Subject: doc: Typographic improvements. * doc/guix.texi (Networking Services): Use @var, @option, and @command when appropriate. Add two spaces after sentences. --- doc/guix.texi | 60 ++++++++++++++++++++++++++++++++--------------------------- 1 file changed, 33 insertions(+), 27 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index 812d08a8ef..6b5b8bf6f8 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -14394,18 +14394,21 @@ Whether to enable password-based authentication. @cindex AutoSSH @deffn {Scheme Variable} autossh-service-type This is the type for the @uref{https://www.harding.motd.ca/autossh, -AutoSSH} program that runs a copy of @code{ssh} and monitors it, +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 commandline by passing arguments to -the binary @code{autossh} from the package @code{autossh}, but it can -also be run as a guix service. This latter usecase is documented here. +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. +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: +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 @@ -14428,18 +14431,19 @@ This assumes that the specified user exists. Specifies the connection poll time in seconds. @item @code{first-poll} (default @code{#f}) -Specifies how long autossh waits before the first connection test in seconds. -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} +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 (in seconds) how long an SSH connection must be active -before it is considered successful. +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.) +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. @@ -14449,18 +14453,20 @@ When set to @code{#f}, no maximum is configured and AutoSSH may restart indefini The message to append to the echo message sent when testing connections. @item @code{port} (default @code{"0"}) -The ports used for monitoring the connection. When set to @code{"0"}, -monitoring is disabled. When set to @code{"n"} where @code{n} is a positive integer, -ports @code{n} and @code{n+1} are used for monitoring the connection, such that -port @code{n} is the base monitoring port and @code{n+1} is the echo port. -When set to @code{"n:m"} where @code{n} and @code{m} are positive integers, -the ports @code{n} and @code{n+1} are used for monitoring the connection, such -that port @code{n} is the base monitoring port and @code{m} is the echo port. +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{n}+1 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 commandline arguments to pass to ssh when it is run. -Options @code{-f} and @code{-M ....} are reserved for AutoSSH -and may cause undefined behaviour. +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 -- cgit v1.2.3 From 751d1f01e4f0607d41e4c859d944753b18466652 Mon Sep 17 00:00:00 2001 From: Jean-Baptiste Note Date: Mon, 4 May 2020 20:01:10 +0000 Subject: doc: cookbook: Fix sbcl-ttf-fonts package name. * doc/guix-cookbook.texi (StumpWM): Adjust sbcl-ttf-fonts package name. Signed-off-by: Marius Bakke --- doc/guix-cookbook.texi | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'doc') diff --git a/doc/guix-cookbook.texi b/doc/guix-cookbook.texi index f58d18d47c..2a605276e6 100644 --- a/doc/guix-cookbook.texi +++ b/doc/guix-cookbook.texi @@ -1594,7 +1594,7 @@ An example configuration can look like this: @cindex stumpwm fonts By default StumpWM uses X11 fonts, which could be small or pixelated on your system. You could fix this by installing StumpWM contrib Lisp -module @code{sbcl-stumpwm-ttf-fonts}, adding it to Guix system packages: +module @code{sbcl-ttf-fonts}, adding it to Guix system packages: @lisp (use-modules (gnu)) @@ -1603,7 +1603,7 @@ module @code{sbcl-stumpwm-ttf-fonts}, adding it to Guix system packages: (operating-system ;; … (packages (append (list sbcl stumpwm `(,stumpwm "lib")) - sbcl-stumpwm-ttf-fonts font-dejavu %base-packages))) + sbcl-ttf-fonts font-dejavu %base-packages))) @end lisp Then you need to add the following code to a StumpWM configuration file -- cgit v1.2.3