From 1f14e25c1969a93908288cb302a572f3cbbaa478 Mon Sep 17 00:00:00 2001 From: Ludovic Courtès 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/guix.texi') 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: Ludovic Courtès 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/guix.texi') 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 ++++++++++++++++++++++++++++++++++++ gnu/services/ssh.scm | 106 ++++++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 180 insertions(+), 1 deletion(-) (limited to 'doc/guix.texi') 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 diff --git a/gnu/services/ssh.scm b/gnu/services/ssh.scm index d2dbb8f80d..ced21c0742 100644 --- a/gnu/services/ssh.scm +++ b/gnu/services/ssh.scm @@ -4,6 +4,7 @@ ;;; Copyright © 2016 Julien Lepiller ;;; Copyright © 2017 Clément Lassieur ;;; Copyright © 2019 Ricardo Wurmus +;;; Copyright © 2020 pinoaffe ;;; ;;; This file is part of GNU Guix. ;;; @@ -45,7 +46,11 @@ (define-module (gnu services ssh) dropbear-configuration dropbear-configuration? dropbear-service-type - dropbear-service)) + dropbear-service + + autossh-configuration + autossh-configuration? + autossh-service-type)) ;;; Commentary: ;;; @@ -628,4 +633,103 @@ (define* (dropbear-service #:optional (config (dropbear-configuration))) object." (service dropbear-service-type config)) + +;;; +;;; AutoSSH. +;;; + + +(define-record-type* + autossh-configuration make-autossh-configuration + autossh-configuration? + (user autossh-configuration-user + (default "autossh")) + (poll autossh-configuration-poll + (default 600)) + (first-poll autossh-configuration-first-poll + (default #f)) + (gate-time autossh-configuration-gate-time + (default 30)) + (log-level autossh-configuration-log-level + (default 1)) + (max-start autossh-configuration-max-start + (default #f)) + (message autossh-configuration-message + (default "")) + (port autossh-configuration-port + (default "0")) + (ssh-options autossh-configuration-ssh-options + (default '()))) + +(define (autossh-file-name config file) + "Return a path in /var/run/autossh/ that is writable + by @code{user} from @code{config}." + (string-append "/var/run/autossh/" + (autossh-configuration-user config) + "/" file)) + +(define (autossh-shepherd-service config) + (shepherd-service + (documentation "Automatically set up ssh connections (and keep them alive).") + (provision '(autossh)) + (start #~(make-forkexec-constructor + (list #$(file-append autossh "/bin/autossh") + #$@(autossh-configuration-ssh-options config)) + #:user #$(autossh-configuration-user config) + #:group (passwd:gid (getpw #$(autossh-configuration-user config))) + #:pid-file #$(autossh-file-name config "pid") + #:log-file #$(autossh-file-name config "log") + #:environment-variables + '(#$(string-append "AUTOSSH_PIDFILE=" + (autossh-file-name config "pid")) + #$(string-append "AUTOSSH_LOGFILE=" + (autossh-file-name config "log")) + #$(string-append "AUTOSSH_POLL=" + (number->string + (autossh-configuration-poll config))) + #$(string-append "AUTOSSH_FIRST_POLL=" + (number->string + (or + (autossh-configuration-first-poll config) + (autossh-configuration-poll config)))) + #$(string-append "AUTOSSH_GATETIME=" + (number->string + (autossh-configuration-gate-time config))) + #$(string-append "AUTOSSH_LOGLEVEL=" + (number->string + (autossh-configuration-log-level config))) + #$(string-append "AUTOSSH_MAXSTART=" + (number->string + (or (autossh-configuration-max-start config) + -1))) + #$(string-append "AUTOSSH_MESSAGE=" + (autossh-configuration-message config)) + #$(string-append "AUTOSSH_PORT=" + (autossh-configuration-port config))))) + (stop #~(make-kill-destructor)))) + +(define (autossh-service-activation config) + (with-imported-modules '((guix build utils)) + #~(begin + (use-modules (guix build utils)) + (define %user + (getpw #$(autossh-configuration-user config))) + (let* ((directory #$(autossh-file-name config "")) + (log (string-append directory "/log"))) + (mkdir-p directory) + (chown directory (passwd:uid %user) (passwd:gid %user)) + (call-with-output-file log (const #t)) + (chown log (passwd:uid %user) (passwd:gid %user)))))) + +(define autossh-service-type + (service-type + (name 'autossh) + (description "Automatically set up ssh connections (and keep them alive).") + (extensions + (list (service-extension shepherd-root-service-type + (compose list autossh-shepherd-service)) + (service-extension activation-service-type + autossh-service-activation))) + (default-value (autossh-configuration)))) + ;;; ssh.scm ends here -- 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/guix.texi') 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