guardctrl.md

@@ -6,12 +6,16 @@ Each guardian node is handled by a systemd templated service unit, `guardian@.se
 
 ## host setup
 
+### install
+
 The `guardctrl` package is available through the [LIGO Debian apt archives](http://apt.ligo-wa.caltech.edu/debian/), so once that archive is enabled it can be installed directly:
 ```shell
 # apt install guardctrl
 ```
 The `guardctrl` package depends on `guardian` package, so you'll automatically get them both.
 
+### setup user
+
 `guardctrl` uses a `systemd --user` instance.  This means that `guardctrl` should always be invoked as the same user so that processes are managed in a unified way.  The `guardctrl` interface knows that it's running as the correct user by the presence of a `~/.guardctrl-home` file.
 
 For the LIGO site installations we therefore create a `guardian` user:
@@ -30,6 +34,8 @@ We need to inform the system systemd that the `guardctrl` user is "persistent",
 # loginctl enable-linger guardian
 ```
 
+### configure journald for persistent logs
+
 For the LIGO sites, we want to store logs from all guardian processes in perpetuity.  To do this, the journald system logger needs to be configured to store all logs indefinitely.  This is done by setting `Storage=persistent` in `/etc/systemd/journald.conf`:
 ```
 [Journal]
@@ -39,6 +45,8 @@ Storage=persistent
 # systemctl force-reload systemd-journald
 ```
 
+### setup local environment
+
 The `guardian@.service` expects an `/etc/guardian/local-env` environment file to exist, for providing any needed environment variables to the supervised guardian processes.  Here's an example of the file for H1 at LHO:
 ```shell
 # cat /etc/guardian/local-env
@@ -51,23 +59,36 @@ NDSSERVER=h1nds0:8088,h1nds1:8088
 
 ### passwordless SSH interface
 
-For accessing the guardctrl interface via passwordless SSH, we add a "Match" stanza to the sshd_config:
+The best way to allow remote control of guardctrl is via ssh.
+For a site install on a protected network, where you want to allow "remote" users (users on the same network but on hosts other than the guardctrl host) to be able to control the nodes without entering a password, you can setup a passwordless ssh "ForceCommand" for the guardctrl user.
+
+First, we need to modify the system PAM stack to allow passwordless login via ssh.  Usually PAM is configured to not allow passwordless login on anything except for special TTYs.  To loosen that restriction, on Debian systems, we modify `/etc/pam.d/common-auth` to change the following line:
 ```
+auth	[success=1 default=ignore]	pam_unix.so nullok_secure
+```
+to:
+```
+auth	[success=1 default=ignore]	pam_unix.so nullok
+```
+
+We then need to add to the sshd_config a special "Match" stanza for the guardctrl user which specifies that it may login without a password, but is forced to execute only a single command (`guardctrl`).  On most systems this would go in `/etc/ssh/sshd_config`:
+```/etc/ssh/sshd_config
 Match User guardian
-  # PermitEmptyPasswords yes
+  PermitEmptyPasswords yes
   PermitTTY yes
   X11Forwarding no
   AllowTcpForwarding no
-  ForceCommand /etc/guardian/guardctrl-ssh-bridge
+  ForceCommand /usr/bin/guardctrl
 ```
 After adding the Match stanza, reload sshd:
 ```shell
 # systemctl force-reload sshd
 ```
+If for some reason you need to pass special environment variables to `guardctrl`, you can point the ForceCommand to someething like `/etc/guardian/guardctrl-ssh-bridge` which can be a shell script that sets the needed environment and then execs `/usr/bin/guardctrl` (without arguments).  Be sure to set your wrapper script to be executable.
 
 #### local guardian user access
 
-Occasionally it might be necessary to access the guardian user directly.  If passwordless SSH access has been enabled, this will need to be done with something like su.  However, su and sudo do not provide access to the user dbus needed to interact with systemctl --user.  However the systemd-container package includes the `machinectl` interface whose `shell` command allows for a clean user environment with all dbus interfaces available:
+Occasionally it might be necessary to access the guardian user directly.  If passwordless SSH access has been enabled, this will need to be done with something like su.  However, su and sudo do not provide access to the user dbus session needed to interact with `systemctl --user`.  The systemd-container package includes the `machinectl` interface whose `shell` command allows for a clean user environment with all dbus interfaces available:
 ```shell
 root@h1guardian1:~# machinectl shell guardian@ /bin/bash
 guardian@h1guardian1:~$ systemctl --user status