Manage censhare services with systemd

RPMs will transition the service startup from rccss startup scripts to systemd-based scripts, since systemd is the new standard for service handling on Linux.

Which services exist

censhare.server

This service is to start the censhare-Server with the default user "corpus". After startup it will check for the pidfile at /opt/corpus/work/run/censhare.pid.

[Unit]
Description=censhare server
Documentation=https://ecosphere.censhare.com/en/Search?s.text=censhare-server
After=network.target

[Service]
User=corpus
EnvironmentFile=/etc/sysconfig/censhare
LimitNOFILE=65536
ExecStart=/opt/corpus/bin/censhare.rc start
ExecStop=/opt/corpus/bin/censhare.rc stop
Restart=on-failure
Type=forking
RestartSec=15s
PIDFile=/opt/corpus/work/run/censhare.pid
TimeoutStartSec=600

[Install]
WantedBy=default.target
Alias=css.service

censhare.serviceclient

This service is to start up the Service-Client in order to connect to a censhare-Server and to do the image previews.

[Unit]
Description=censhare ServiceClient
Documentation=https://ecosphere.censhare.com/en/Search?s.text=censhare-server
After=censhare.server.service

[Service]
User=corpus
EnvironmentFile=/etc/sysconfig/css_serviceclient
ExecStart=/opt/corpus/service-client/serviceclient.sh start
ExecStop=/opt/corpus/service-client/serviceclient.sh stop
Restart=on-failure
Type=forking
PIDFile=/opt/corpus/service-client/run/serviceclient.pid
TimeoutStartSec=600

[Install]
WantedBy=default.target
Alias=serviceclient.service

censhare.office

The office services starts LibreOffice on a given port to get previews of office documents like Excel.

[Unit]
Description=office services for censhare
Documentation=https://ecosphere.censhare.com/en/documentation/system-administration/article/2377965
Before=censhare.serviceclient.service

[Service]
EnvironmentFile=/etc/sysconfig/office
ExecStart=/opt/corpus/localbin/office.sh start
ExecStop=/opt/corpus/localbin/office.sh stop
Restart=on-failure
Type=forking
PIDFile=/opt/corpus/office/run/office.pid
TimeoutStartSec=60

[Install]
WantedBy=default.target
Alias=office.service

Vendor preset

If the censhare systemd services are available, we recommend to have them enabled, so the services come up after system restart. Therefore the vendor preset for all systemd services by censhare is to be enabled. This preset can be found at /usr/lib/systemd/system-preset/99-censhare.preset.

# Have all available censhare related service enabled by default. 
# In order to change this default, just create a file with lower ID 
   in order to overwrite this one enable censhare.*

systemd services for censhare

Enable/disable

If you don't want a service to come up at system startup, you can deactivate it.

systemctl disable censhare.server

Removed symlink /etc/systemd/system/default.target.wants/censhare.server.service. 
Removed symlink /etc/systemd/system/css.service.

Re-enabling works in the same way: 

systemctl enable censhare.server

Created symlink from /etc/systemd/system/css.service to /usr/lib/systemd/system/censhare.server.service.
Created symlink from /etc/systemd/system/default.target.wants/censhare.server.service 
to /usr/lib/systemd/system/censhare.server.service.

Start/stop/status

You can simply stop a service:

systemctl stop censhare.server

Or start the service:

systemctl start censhare.server

Status of the censhare installed services:

systemctl status censhare.*

Status during start:

systemctl status censhare.server

censhare.server.service - censhare server
   Loaded: loaded (/usr/lib/systemd/system/censhare.server.service; enabled; 
           vendor preset: enabled)
   Active: activating (start) since Tue 2018-03-20 08:51:38 UTC; 19s ago
     Docs: https://ecosphere.censhare.com/en/Search?s.text=censhare=server
  Control: 3085 (censhare.rc)
   CGroup: /docker-ce/docker/f9979d0a28218d082782faa9e365135fe121f8f70b556c647c9ab408a4f9059f/
system.slice/
censhare.server.service
           ├─3085 /bin/bash /opt/corpus/bin/censhare.rc start
           ├─3186 tail -0f /opt/corpus/work/logs/server-0.0.log
           ├─3206 java -server -ea:com.censhare... -ea:source... -ea:modules... 
                  -verbose:gc -Xloggc:work/logs/gc.lo...
           └─3525 sleep 2

Mar 20 08:51:38 f9979d0a2821 systemd[1]: Starting censhare server...

Status when the service is running:

systemctl status censhare.server

censhare.server.service - censhare server
   Loaded: loaded (/usr/lib/systemd/system/censhare.server.service; enabled; 
           vendor preset: enabled)
   Active: active (running) since Tue 2018-03-20 08:52:06 UTC; 25s ago
     Docs: https://ecosphere.censhare.com/en/Search?s.text=censhare=server
  Process: 3085 ExecStart=/opt/corpus/bin/censhare.rc start (code=exited, status=0/SUCCESS)
 Main PID: 3206 (java)
   CGroup: /dockerce/docker/f9979d0a28218d082782faa9e365135fe121f8f70b556c647c9ab408a4f9059f/
system.slice/
censhare.server.service
           └─3206 java -server -ea:com.censhare... -ea:source... -ea:modules... 
                  -verbose:gc -Xloggc:work/logs/gc.lo...

Mar 20 08:51:38 f9979d0a2821 systemd[1]: Starting censhare server...
Mar 20 08:52:06 f9979d0a2821 systemd[1]: Started censhare server.

systemd for non-privileged user "corpus"

With the censhare-Common 1.5 RPM there are two solutions implemented.

systemd policy kit

This solution will work from systemd 226, many Linux distributions are still just on systemd 219.
There is a policy file that defines if the username "corpus" runs any "systemctl status|stop|restart censhare.*" command, it will be allowed without any further prompt.
The policy is defined at /etc/polkit-1/rules.d/99-user-corpus-handles-censhare-services.rules.

/* allow user corpus to handle censhare.* services */

polkit.addRule(function(action, subject) {
  if ( action.id == "org.freedesktop.systemd1.manage-units") {
      var unit = action.lookup("unit");
    if ( /^censhare\.*/.test(unit) && subject.user == "corpus") {
      var verb = action.lookup("verb");
      if (verb == "start" || verb == "stop" || verb == "restart") {
        polkit.log("ResultYes");
        return polkit.Result.YES;
      }
    }
  }
  polkit.log("action=" + action);
  polkit.log("subject=" + subject);
});

To override this rule, just create your own file with a lower ID and it will be read first. For example, if you want user corpus to enter their password first, you can copy the file to /etc/polkit-1/rules.d/90-user-corpus-handles-censhare-services-with-password.rules.

/* allow user corpus to handle censhare.* services */

polkit.addRule(function(action, subject) {
  if ( action.id == "org.freedesktop.systemd1.manage-units") {
      var unit = action.lookup("unit");
    if ( /^censhare\.*/.test(unit) && subject.user == "corpus") {
      var verb = action.lookup("verb");
      if (verb == "start" || verb == "stop" || verb == "restart") {
        polkit.log("ResultYes");
        return polkit.Result.AUTH_SELF;
      }
    }
  }
  polkit.log("action=" + action);
  polkit.log("subject=" + subject);
});

For more information refer to the Policy Kit documentation.

sudoers

Since the Policy Kit solution only works from systemd 226 onwards, as alternative a sudoers rule will be provided at /etc/sudoers.d/censhare-services that provides the following rule:

Cmnd_Alias CENSHARE = /bin/systemctl start censhare.*, /bin/systemctl 
stop censhare.*, /bin/systemctl restart censhare.* 
corpus ALL=(ALL) NOPASSWD: CENSHARE

In order to apply your own changes here, you can just edit the file, it won't be overwritten by an RPM update.

Transition from init scripts

systemd services will be available from the following censhare RPM packages.

If rccss service is enabled

In this case, rccss will be disabled, systemd service will be set to vendor preset, which should be enabled by default.

If rccss service is disabled

Then also systemd will not be enabled.

If the replaced service was started

If the old RPM had no systemd, it will try to startup the service again via init service while the old RPM gets removed. The new RPM will then run a transition scriptlet to stop the service again and start it via systemd service

If the old RPM had systemd already, but the service was still running with an init script, it will be also started again via init script.

If the replaced service was stopped

If the old RPM had no systemd, it will try to startup the service again via init service while the old RPM gets removed, even when the service was stopped before. This is just a problem with the old RPM.

Customizing systemd services

vendor preset

If the administrator wants to disable a preset file supplied by the vendor, the recommended way is to place a symlink to /dev/null in /etc/systemd/system-preset/ bearing the same filename.

ln -s /dev/null /etc/systemd/system-preset/99-censhare.preset

You can also put your own preset file in /etc/systemd/ in order to maintain your own settings

cp /usr/lib/systemd/system-preset/99-censhare.preset /etc/systemd/
            system-preset/99-censhare.preset
enable censhare.server
disable censhare.serviceclient
disable censhare.office

services

If you create service units in /etc/systemd/system, they will override the defaults which are installed to /usr/lib/systemd/system
So this way you can completely define your own censhare.server.service and it will be used instead of the original one.

I don't want to use systemd, how can I stay with init scripts?

Since systemd is used by default on all major Linux distributions we support, we don't recommend to stay with init scripts.
If you don't want to enable systemd by default, you could deactivate the vendor preset we provide as described above.

ln -s /dev/null /etc/systemd/system-preset/99-censhare.preset

This way it won't be enabled on update at all. If there was no systemd in the old RPM, it will disable the rccss service. You can re-enabled it after the update and for the next update rccss service will stay enabled.

rccss enable censhare

I want systemd now and don't want to wait for RPMs to deliver, how can I install it manually?

It is recommended to first update censhare-Common to the latest version, so you already have presets and settings for non-privileged user corpus. Also, a bug in rccss is solved that did not disable services correctly.

censhare.office

• remove old init.d service

  rccss stop office
  rccss disable office 
  
  

• create new systemd unit:

  cat <<EOF >> /usr/lib/systemd/system/censhare.office.service
  [Unit]
  Description=office services for censhare
  Documentation=https://ecosphere.censhare.com/en/documentation/system-administration/article/2377965
  Before=censhare.serviceclient.service
  
  [Service]
  EnvironmentFile=/etc/sysconfig/office
  ExecStart=/opt/corpus/localbin/office.sh start
  ExecStop=/opt/corpus/localbin/office.sh stop
  Restart=on-failure
  Type=forking
  PIDFile=/opt/corpus/office/run/office.pid
  TimeoutStartSec=60
  
  [Install]
  WantedBy=default.target
  Alias=office.service
  EOF

  CODE

• Enable and start systemd service:

  systemctl enable censhare.office
  systemctl start censhare.office

censhare.serviceclient

• Remove old init.d service:

  rccss stop css_serviceclient
  rccss disable css_serviceclient
              

• Create new systemd unit:

  cat <<EOF >> /usr/lib/systemd/system/censhare.serviceclient.service
  [Unit]
  Description=censhare ServiceClient
  Documentation=https://ecosphere.censhare.com/en/Search?s.text=censhare=server
  After=censhare.server.service
  
  [Service]
  User=corpus
  EnvironmentFile=/etc/sysconfig/css_serviceclient
  ExecStart=/opt/corpus/service-client/serviceclient.sh start
  ExecStop=/opt/corpus/service-client/serviceclient.sh stop
  Restart=on-failure
  Type=forking
  PIDFile=/opt/corpus/service-client/run/serviceclient.pid
  TimeoutStartSec=600
  
  [Install]
  WantedBy=default.target
  Alias=serviceclient.service
  EOF

  CODE

• Enable and start systemd service:

  systemctl enable censhare.serviceclient
  systemctl start censhare.serviceclient

censhare.server

• Remove old init.d service:

  rccss stop censhare
  rccss disable censhare
              

• Create new systemd unit:

  # source sysconfig in order to have $CSS_ID
  source /etc/sysconfig/censhare
  
  cat <<EOF >> /usr/lib/systemd/system/censhare.server.service
  [Unit]
  Description=censhare server
  Documentation=https://ecosphere.censhare.com/en/Search?s.text=censhare-server
  After=network.target
  
  [Service]
  User=corpus
  EnvironmentFile=/etc/sysconfig/censhare
  LimitNOFILE=65536
  ExecStart=/opt/corpus/bin/censhare.rc start
  ExecStop=/opt/corpus/bin/censhare.rc stop
  Restart=on-failure
  Type=forking
  RestartSec=15s
  PIDFile=/opt/corpus/work/run/$CSS_ID
  TimeoutStartSec=600
  
  [Install]
  WantedBy=default.target
  Alias=css.service
  EOF

  CODE

• Enable and start systemd service:

  systemctl enable censhare.server
  systemctl start censhare.server