Re: Auto-start service

[excalamus]

> I had to activate the user-level Shepherd by hand in any file that is 
> executed when the system is started. In my case I have it in my i3 config. 
> You can put it in .xsession like the thread you shared suggests.
>
*expletives*  Call 'shepherd'.  That's it.  Call 'shepherd'.  Goodness 
gracious...thank you.

I see now the docs mention this.  Yet, because user error (pun intended) is 
never my fault (sarcasm), I wonder if the docs might express it more clearly.

The information I overlooked is that Shepherd may (and likely will) be run 
concurrently by two or more users (e.g. 'root' and 'Joe Shmoe'). 

The relevant docs are:

1.  The  (shepherd) Introduction says, 

"""The Shepherd is the “init system” of the GNU operating system—it is the 
first user process that gets started, typically with PID 1, and runs as 
‘root’."""

I believe the phrase "the first user process" might be better as "the first 
process".

Are there processes which are not "user processes" within userland?  The kernel 
starts the init process (i.e. Shepherd).  However, because users can access it 
as 'root', it can be considered a userland process.  Therefore, the edit could 
happen without loss of meaning.  

When reading the phrase "the first user process", the word "user" stuck with 
me.  Maybe I read too much Hacker News, but when developers speak of "users", I 
interpret it as "a non-developer or someone without access to controls, such as 
admin privileges".  I read "user" and thought of "unprivileged", despite the 
sentence literally saying Shepherd runs as 'root'! 

2.  The (shepherd) Jump Start says,

"""When ‘shepherd’ gets started, it reads and evaluates a configuration file.  
When it is started with superuser privileges, it tries to use 
‘/etc/shepherd.scm’.  When started as normal user, it looks for a file called 
‘$XDG_CONFIG_HOME/shepherd/init.scm’.  If the ‘XDG_CONFIG_HOME’ environment 
variable is not defined, ‘$HOME/.config/shepherd/init.scm’ is used instead.  
With the option ‘--config’ (or, for short, ‘-c’), you can specify where to look 
instead.  So if you want to start ‘shepherd’ with an alternative file, use one 
of the following commands:


     shepherd --config=/etc/shepherd.scm.old
     shepherd -c /etc/shepherd.scm.old
"""

I followed the first and second paragraphs well enough.  I placed my init.scm 
in the 'normal user' location.  I expressly didn't put it in /etc/shepherd.scm 
because I knew I was non-root.  Although Shepherd starts on init, I overlooked 
that it's *not* started for unprivileged users.

Expecting Shepherd to auto-start for unprivileged users comes, in part, from my 
experience with systemd.  On Debian, I recall being able to run `systemctl 
--user restart emacsd` without sudo.  There's the --user option, sure.  
However, I could manage a service as a non-privileged user and didn't 
explicitly need to start systemd. Is there a reason why Shepherd must be 
explicitly started as a non-privileged user?

This expectation, and the confusion, was reinforced by the paragraph 
immediately following in the docs,

"""As the final “d” suggests, ‘shepherd’ is just a daemon that (usually) runs 
in the background, so you will not interact with it directly.  After it is 
started, ‘shepherd’ will listen on a socket special file, usually 
‘/var/run/shepherd/socket’, for further commands.  You use the tool “herd” to 
send these commands to ‘shepherd’."""

The important fact that Shepherd must be 1) started by an unprivileged user 2) 
using the 'shepherd' command is hidden in the conjunction(?) "After it is 
started".  The manual emphasizes to use 'herd' and that interacting with 
Shepherd through the 'shepherd' command is unusual.  Yet, isn't starting 
Shepherd as a regular user with 'shepherd' the usual approach?

This again begs the question, why isn't Shepherd started for non-privileged 
users?

3. Section (shepherd) herd and shepherd says,

"""Thus, you start ‘shepherd’ once, and then always use herd whenever
you want to do something service-related."""
Looking at it now, I see this describes a procedure:

1. Run 'shepherd'
2. Always use 'herd'

It's not mentioned that 'shepherd' isn't automatically started for 
non-privileged users.  The sentence is also buried in Section 3.  Section 2 
explicitly says, "It [Section 2] is enough if
you just need the basic features of it [Shepherd]".  Is it enough?

I'm happy to provide language suggestions for improving the docs.  I feel I 
need to understand things a little better first.  Maybe the manual needs to 
clarify that 'shepherd' must be run by non-privileged users before they can use 
services and 'herd'?  Maybe 'shepherd' should be setup to automatically run for 
non-privileged users so that 'herd' is available immediately?

Thoughts?