[bug#43921] [PATCH v3 2/2] Add User Service example.

[Jan Nieuwenhuizen]

Ludovic Courtès writes:

Hello,

> "Jan (janneke) Nieuwenhuizen" <janneke@gnu.org> skribis:
>
>> * modules/shepherd/support.scm: Export %user-cache-dir, %user-config-dir,
>> %user-runtime-dir.
>> * doc/shepherd.texi (User Service examples): Use them in new subsection with
>> example.
>>
>> Co-authored-by: Efraim Flashner <efraim@flashner.co.il>
>
> Good idea!
>
>> +@menu
>> +* User Service examples::
>> +@end menu
>> +
>> +@node User Service examples
>> +@subsection User Service examples
>
> The subsection looks lonely.  :-)  How about making it a section, at the
> same level as “Service Examples”?

Sure.

> Also, since “user services” are no different than “non-user” services,
> perhaps the focus should be on using the Shepherd as an unprivileged
> user.  Thus, I’d suggest calling the section “Managing User Services”,
> or “Running the Shepherd as a User”, which do not imply that “user
> services” are a new concept.
>
> WDYT?

Yes, nice.  I changed the opening to

The Shepherd can be used to manage services for an unprivileged user.
First, you may want to ensure it is up and running every time you log
in.  One way to accomplish that is by adding the following lines to
@file{~/.bash_profile} (@pxref{Bash Startup Files,,, bash, The GNU Bash
Reference Manual}):

>> +For starters, use a toplevel @code{$XDG_CONFIG_HOME/shepherd/init.scm}
>> +that looks like this:
>
> Maybe: “… we suggest the following top-level
> @file{$XDG_CONFIG_HOME/shepherd/init.scm} file, which will automatically
> load individual service definitions from
> @file{~/.config/shepherd/init.d}:”

Nice.

>> +Then, individual user services can be put in
>> +@code{$XDG_CONFIG_HOME/shepherd/init.d/}, e.g., for ssh-agent
>
> @command{ssh-agent} and period.  :-)

>> +@lisp
[..]
>> +    #:start (let ((socket-dir (string-append %user-runtime-dir 
>> "/ssh-agent")))
>> +              (unless (file-exists? socket-dir)
>> +                (mkdir-p socket-dir)
>> +                (chmod socket-dir #o700))
>> +              (make-forkexec-constructor
>> +               `("ssh-agent" "-D" "-a" ,(string-append socket-dir 
>> "/socket"))
>> +               #:log-file (string-append %user-cache-dir "/ssh-agent.log")))
>
> This is misleading because the code to create the socket directory runs
> from the top-level, i.e., when shepherd starts.

Oops; that's probably $HOME for me, because it worked...

> I’d write:
>
>   #:start (lambda ()
>             ;; make socket dir
>             (fork+exec-command … #:log-file …))

Great; changed that too.

> (BTW, I use ‘gnupg-agent’, which I think is pretty nice because it’s
> integrated with pinentry and all.

Interesting...makes me wonder: maybe we could ship init.scm together
with a couple of popular user service descriptions like ssh-agent.scm,
znc.scm, ...gpg-agent.scm (?) in an examples directory?  That would make
it even easier for people to migrate away from the old

> I run it as:
>   eval `gpg-agent --daemon --enable-ssh-support`
>
> … from ~/.xsession.)

It would have helped me to move away from my `eval ssh-agent` thingy ;-)

New version attached (included 0001 patch for completeness but which
can probably be merged into / obsoleted by #43920).

Greetings,
Janneke

>From f0deaa24ad57d2db921bf1b092350988c50558a7 Mon Sep 17 00:00:00 2001
From: "Jan (janneke) Nieuwenhuizen" <janneke@gnu.org>
Date: Sun, 11 Oct 2020 10:54:26 +0200
Subject: [PATCH v3 1/2] Use XDG_CACHE_HOME/shepherd for unprivileged users'
 log directory.
Content-Transfer-Encoding: 8bit
Content-Type: text/plain; charset=UTF-8

* modules/shepherd/support.scm (%user-cache-dir): New variable.
(user-default-log-file): Use it.
* doc/shepherd.texi (Invoking shepherd): Document it.
---
 doc/shepherd.texi            |  4 +++-
 modules/shepherd/support.scm | 11 +++++++++--
 2 files changed, 12 insertions(+), 3 deletions(-)

diff --git a/doc/shepherd.texi b/doc/shepherd.texi
index 696477e..7c9a739 100644
--- a/doc/shepherd.texi
+++ b/doc/shepherd.texi
@@ -417,7 +417,9 @@ permissions are not as expected.
 Log output into @var{file}.
 
 For unprivileged users, the default log file is
-@file{$XDG_CONFIG_HOME/shepherd/shepherd.log}.
+@file{$XDG_CACHE_HOME/shepherd/shepherd.log}.  If the
+@code{XDG_CACHE_HOME} environment variable is not defined,
+@code{$HOME/.cache/shepherd/shepherd.log} is used instead.
 
 @cindex syslog
 When running as root, the default behavior is to connect to
diff --git a/modules/shepherd/support.scm b/modules/shepherd/support.scm
index cdb7b35..fe64a05 100644
--- a/modules/shepherd/support.scm
+++ b/modules/shepherd/support.scm
@@ -4,6 +4,7 @@
 ;; Copyright (C) 2002, 2003 Wolfgang Jährling <wolfgang@pro-linux.de>
 ;; Copyright (C) 2016 Mathieu Lirzin <mthl@gnu.org>
 ;; Copyright (C) 2018 Danny Milosavljevic <dannym@scratchpost.org>
+;; Copyright (C) 2020 Jan (janneke) Nieuwenhuizen <janneke@gnu.org>
 ;;
 ;; This file is part of the GNU Shepherd.
 ;;
@@ -265,6 +266,12 @@ There is NO WARRANTY, to the extent permitted by law.")))
       (false-if-exception (passwd:dir (getpwuid (getuid))))
       "/"))
 
+(define %user-cache-dir
+  ;; Default cache directory if shepherd is run as a normal user.
+  (string-append (or (getenv "XDG_CACHE_HOME")
+                     (string-append user-homedir "/.cache"))
+                 "/shepherd"))
+
 (define %user-config-dir
   ;; Default config directory if shepherd is run as a normal user.
   (string-append (or (getenv "XDG_CONFIG_HOME")
@@ -302,8 +309,8 @@ TARGET should be a string representing a filepath + name."
 ;; Logging.
 (define (user-default-log-file)
   "Return the file name of the user's default log file."
-  (mkdir-p %user-config-dir #o700)
-  (string-append %user-config-dir "/shepherd.log"))
+  (mkdir-p %user-cache-dir #o700)
+  (string-append %user-cache-dir "/shepherd.log"))
 
 (define default-logfile-date-format
   ;; 'strftime' format string to prefix each entry in the log.
-- 
Jan Nieuwenhuizen <janneke@gnu.org> | GNU LilyPond http://lilypond.org
Freelance IT http://JoyofSource.com | Avatar® http://AvatarAcademy.com

>From ae64ec3bfa7a0e4e877f06161f2d6aacb5804960 Mon Sep 17 00:00:00 2001
From: "Jan (janneke) Nieuwenhuizen" <janneke@gnu.org>
Date: Sun, 11 Oct 2020 10:59:04 +0200
Subject: [PATCH v3 2/2] doc: Add "Managing User Services".
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Content-Transfer-Encoding: 8bit
Content-Type: text/plain; charset=UTF-8

* modules/shepherd/support.scm: Export %user-cache-dir, %user-config-dir,
%user-runtime-dir.
* doc/shepherd.texi (Managing User Services): Use them in new section with
example.

Co-authored-by: Efraim Flashner <efraim@flashner.co.il>
Co-authored-by: Ludovic Courtès <ludo@gnu.org>
---
 doc/shepherd.texi            | 81 ++++++++++++++++++++++++++++++++++--
 modules/shepherd/support.scm |  4 ++
 2 files changed, 81 insertions(+), 4 deletions(-)

diff --git a/doc/shepherd.texi b/doc/shepherd.texi
index 7c9a739..ea3edf0 100644
--- a/doc/shepherd.texi
+++ b/doc/shepherd.texi
@@ -13,6 +13,7 @@ Copyright @copyright{} @value{OLD-YEARS} Wolfgang J@"ahrling@*
 Copyright @copyright{} @value{NEW-YEARS} Ludovic Courtès@*
 Copyright @copyright{} 2020 Brice Waegeneire@*
 Copyright @copyright{} 2020 Oleg Pykhalov
+Copyright @copyright{} 2020 Jan (janneke) Nieuwenhuizen@*
 
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.3 or
@@ -146,10 +147,11 @@ configuration file.  When it is started with superuser 
privileges, it
 tries to use @code{/etc/shepherd.scm}.  When started as normal user, it
 looks for a file called @code{$XDG_CONFIG_HOME/shepherd/init.scm}.  If
 the @code{XDG_CONFIG_HOME} environment variable is not defined,
-@code{$HOME/.config/shepherd/init.scm} is used instead.  With the option
-@code{--config} (or, for short, @code{-c}), you can specify where to
-look instead.  So if you want to start @command{shepherd} with an
-alternative file, use one of the following commands:
+@code{$HOME/.config/shepherd/init.scm} is used instead (@pxref{Managing
+User Services }).  With the option @code{--config} (or, for short,
+@code{-c}), you can specify where to look instead.  So if you want to
+start @command{shepherd} with an alternative file, use one of the
+following commands:
 
 @example
 shepherd --config=/etc/shepherd.scm.old
@@ -591,6 +593,7 @@ defined in the @code{(shepherd service)} module.
 * Service De- and Constructors:: Commonly used ways of starting and
                                    stopping services.
 * Service Examples::             Examples that show how services are used.
+* Managing User Services::       Running the Shepherd as a user.
 * The root and unknown services:: Special services in the Shepherd.
 @end menu
 
@@ -1025,6 +1028,76 @@ also specifies some more initial values for the slots:
                    (restart (...)))))
 @end lisp
 
+@node Managing User Services
+@section Managing User Services
+
+The Shepherd can be used to manage services for an unprivileged user.
+First, you may want to ensure it is up and running every time you log
+in.  One way to accomplish that is by adding the following lines to
+@file{~/.bash_profile} (@pxref{Bash Startup Files,,, bash, The GNU Bash
+Reference Manual}):
+
+@verbatim
+if [[ ! -S ${XDG_RUNTIME_DIR-$HOME/.cache}/shepherd/socket ]]; then
+    shepherd
+fi
+@end verbatim
+
+Then, we suggest the following top-level
+@file{$XDG_CONFIG_HOME/shepherd/init.scm} file, which will automatically
+load individual service definitions from
+@file{~/.config/shepherd/init.d}:
+
+@lisp
+(use-modules (shepherd service)
+             ((ice-9 ftw) #:select (scandir)))
+
+;; Load all the files in the directory 'init.d' with a suffix '.scm'.
+(for-each
+  (lambda (file)
+    (load (string-append "init.d/" file)))
+  (scandir (string-append (dirname (current-filename)) "/init.d")
+           (lambda (file)
+             (string-suffix? ".scm" file))))
+
+;; Send shepherd into the background
+(action 'shepherd 'daemonize)
+@end lisp
+
+Then, individual user services can be put in
+@code{$XDG_CONFIG_HOME/shepherd/init.d/}, e.g., for @command{ssh-agent}.
+
+@lisp
+;;; Commentary:
+;;;
+;;; Add to your ~/.bash_profile:
+;;;
+;;; SSH_AUTH_SOCK=$@{XDG_RUNTIME_DIR-$HOME/.cache@}/ssh-agent/socket
+;;; export SSH_AUTH_SOCK
+;;;
+;;; Code:
+
+(use-modules (shepherd support))
+
+(define ssh-agent
+  (make <service>
+    #:provides '(ssh-agent)
+    #:docstring "Run `ssh-agent'"
+    #:start (lambda ()
+              (let ((socket-dir (string-append %user-runtime-dir 
"/ssh-agent")))
+                (unless (file-exists? socket-dir)
+                  (mkdir-p socket-dir)
+                  (chmod socket-dir #o700))
+                (fork+exec-command
+                 `("ssh-agent" "-D" "-a" ,(string-append socket-dir "/socket"))
+                 #:log-file (string-append %user-cache-dir "/ssh-agent.log"))))
+    #:stop (make-kill-destructor)
+    #:respawn? #t))
+
+(register-services ssh-agent)
+(start ssh-agent)
+@end lisp
+
 @c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
 
 @node The root and unknown services
diff --git a/modules/shepherd/support.scm b/modules/shepherd/support.scm
index fe64a05..bf34ada 100644
--- a/modules/shepherd/support.scm
+++ b/modules/shepherd/support.scm
@@ -61,6 +61,10 @@
             persistency
             persistency-state-file
 
+            %user-cache-dir
+            %user-config-dir
+            %user-runtime-dir
+
             verify-dir))
 
 (define-syntax-rule (if-2.0 subsequent alternate)
-- 
Jan Nieuwenhuizen <janneke@gnu.org> | GNU LilyPond http://lilypond.org
Freelance IT http://JoyofSource.com | Avatar® http://AvatarAcademy.com

-- 
Jan Nieuwenhuizen <janneke@gnu.org> | GNU LilyPond http://lilypond.org
Freelance IT http://JoyofSource.com | Avatar® http://AvatarAcademy.com