HowTo: Installation on Solaris

1. Coherence (Open)Solaris Installation Guide
   1. Dependencies and Installation
2. Service Configuration
3. Troubleshooting
4. Feedback

Coherence (Open)Solaris Installation Guide

This document gives a brief overview on how to install Coherence on (Open)Solaris.

Dependencies and Installation

There is a mimimum set of dependencies that Coherence needs to be able to run. Thanks to the built-in package manager this is very easy. Either use the Package Manager GUI tool in Gnome or a root shell like this:

  Mike@Sisyphos:~$ pkg install <package-name>

These package must be installed if not already done (the links to the packages are only given for reference and are not needed for installation, except the easy_install application):

• Python: SUNWPython (which is python 2.4 per default at the time of this writing) or SUNWPython25
• Twisted: SUNWpython-twisted (for Python 2.4) or SUNWpython25-twisted
• Easy Install: download the latest installer (not the eggs) for Python 2.4 or 2.5, not a direct dependency for Coherence but helps later with other python stuff

The next step depends on what version of Coherence you want to use. If you want the latest stable build then use

Variant 1:

  Mike@Sisyphos:~$ su
  Mike@Sisyphos:~$ password:
  Mike@Sisyphos:~$ whoami
  root
  Mike@Sisyphos:~$ easy_install Coherence

However if you rather want the latest and greatest cutting edge code then go use a Subversion checkout (if you don't know what Subversion, Bazaar or similar is, don't even bother and go with variant 1)

Variant 2:

  Mike@Sisyphos:/$ cd ~
  Mike@Sisyphos:~$ mkdir Development
  Mike@Sisyphos:~$ cd Development
  Mike@Sisyphos:~$ svn co https://coherence.beebits.net/svn/trunk/Coherence
  Mike@Sisyphos:~$ cd Coherence
  Mike@Sisyphos:~$ su
  Mike@Sisyphos:~$ password:
  Mike@Sisyphos:~$ python setup.py install

Both variants will leave you with an executable in /usr/bin which can be run from any location by just typing

  Mike@Sisyphos:~$ coherence

Running the application like this will look in your home dir for the file .coherence and use this as config file if it exists. Any output goes to stdout. You can stop the process simply by pressing Ctrl+C. However while it runs you should already be able to see the server in your DLNA client. Easy, hu?

Service Configuration

Without telling Coherence what to serve as content you won't have much fun with it. So this is what needs to be done next. However, there is another point to consider: you probably don't want to log into your OpenSolaris box just to run Coherence, but rather prefer it to run as a service. Since setting up Coherence as service which runs automatically after each boot and configuring it are closely related, we do both together.

Some general notes:

• We use the new style for the configuration file, which is an xml format.
• If you change any of the values (paths, user name etc.) given below you might need to adjust the files too.
• Do installation as root. Much easier than prefixing each command with pfexec.

Follow these steps now:

1) Create user and group for the server (we assume upnp/nas here), if you don't want to reuse an existing user. The group should be allowed to access your media files. If you have setup your box as a file server then you probably have already a dedicated group for accessing it, which would be a good candidate. If not do

  Mike@Sisyphos:~$ groupadd nas
  Mike@Sisyphos:~$ useradd -g nas -d /var/coherence upnp

2) Create a private folder for Coherence. There we store the config file, the log file and a lock file which prevents more than one instance to start (if started via start script).

  Mike@Sisyphos:~$ mkdir /var/coherence
  Mike@Sisyphos:~$ chown upnp:nas /var/coherence
  Mike@Sisyphos:~$ chmod g+rwx /var/coherence

3) Copy the [config file] into that folder and give proper permissions.

  Mike@Sisyphos:~$ cd /var/coherence
  Mike@Sisyphos:/var/coherence$ chown upnp:nas coherence.conf

Edit the config file for your own situation!

4) Copy the socalled [method script] (a script to control the server) to /lib/svc/method/coherence (no extension) and set permissions. This file is used by the Service Management Facility (SMF) to control the service.

  Mike@Sisyphos:~$ chmod 555 /lib/svc/method/coherence

5) Copy the [service description] file to /var/svc/manifest/application/

6) Import the service description to add the new service.

  Mike@Sisyphos:~$ svccfg import /var/svc/manifest/application/coherence.xml

The service is now ready and only needs to be started. Check that it is really there:

  Mike@Sisyphos:~$ svcs coherence
  STATE          STIME    FMRI
  offline        18:18:10 svc:/application/upnp/coherence:default

Enable the service and you are done.

  Mike@Sisyphos:~$ svcadmin enable coherence
  Mike@Sisyphos:~$ svcs coherence
  STATE          STIME    FMRI
  online         18:19:24 svc:/application/upnp/coherence:default

Check with your DNLA client that you can access your media files and keep an eye on the log file for eventual problems.

Troubleshooting

In case something goes wrong you have several means to look for a reason.

1) If your service doesn't want to go online and stays offline or in maintenance mode check if all dependencies (of the service, not coherence itself) are met:

  Mike@Sisyphos:~$ svcs -l coherence
  fmri         svc:/application/upnp/coherence:default
  name         Coherence UPNP/DLNA media server
  enabled      true
  state        online
  next_state   none
  state_time   28. März 2009 18:19:24 CET
  logfile      /var/svc/log/application-upnp-coherence:default.log
  restarter    svc:/system/svc/restarter:default
  contract_id  112 
  dependency   require_all/none svc:/milestone/network:default (online)
  dependency   require_all/restart file://localhost/var/coherence/coherence.conf (online)
  dependency   require_all/none file://localhost/lib/svc/method/coherence (online)
  dependency   require_all/none svc:/system/filesystem/local:default (online)

Spend special attention to the dependencies. All four must be "online". Use the next command to find other info (only useful if the service makes trouble).

  Mike@Sisyphos:~$ svcs -x coherence
  svc:/application/upnp/coherence:default (Coherence UPNP/DLNA media server)
   State: online since 28. März 2009 18:19:24 CET
     See: coherence(1)
     See: http://coherence.beebits.net/wiki/DocumentationDepartment
     See: /var/svc/log/application-upnp-coherence:default.log
  Impact: None.

Watch out: make sure there is no lock file located in /var/coherence if the server is down or it won't start up next time SMF tries to get it online. This file does not get removed if the server went offline for some other reason than the stop method or if pkill did not return 0 in this stop method.

A good pool of information is also the set of properties assigned to the service. You get them via:

  Mike@Sisyphos:~$ svcprop coherence
  coherence/config astring /var/coherence/coherence.conf
  coherence/data astring /var/coherence
  coherence/action_authorization astring solaris.smf.manage.coherence
  coherence/value_authorization astring solaris.smf.value.coherence
  method_context/limit_privileges astring :default
  method_context/privileges astring :default
  method_context/project astring :default
  method_context/resource_pool astring :default
  method_context/supp_groups astring :default
  method_context/use_profile boolean false
  method_context/working_directory astring :default
  method_context/group astring nas
  method_context/user astring upnp
  general/enabled boolean true
  general/action_authorization astring solaris.smf.manage.coherence
  general/value_authorization astring solaris.smf.value.coherence
  general/entity_stability astring Evolving
  system/grouping astring require_all
  system/restart_on astring none
  system/type astring service
  system/entities fmri svc:/milestone/network:default
  config_data/grouping astring require_all
  config_data/restart_on astring restart
  config_data/type astring path
  config_data/entities fmri file://localhost/var/coherence/coherence.conf
  init_script/grouping astring require_all
  init_script/restart_on astring none
  init_script/type astring path
  init_script/entities fmri file://localhost/lib/svc/method/coherence
  filesystem-local/entities fmri svc:/system/filesystem/local:default
  filesystem-local/grouping astring require_all
  filesystem-local/restart_on astring none
  filesystem-local/type astring service
  start/type astring method
  start/exec astring /lib/svc/method/coherence\ start
  start/timeout_seconds count 30
  stop/timeout_seconds count 2
  stop/type astring method
  stop/exec astring /lib/svc/method/coherence\ stop
  restart/type astring method
  restart/timeout_seconds count 30
  restart/exec astring /lib/svc/method/coherence\ restart
  tm_common_name/C ustring Coherence\ UPNP/DLNA\ media\ server
  tm_man_coherence/manpath astring :default
  tm_man_coherence/section astring 1
  tm_man_coherence/title astring coherence
  tm_doc_Coherence_Documentation/name astring Coherence\ Documentation
  tm_doc_Coherence_Documentation/uri astring http://coherence.beebits.net/wiki/DocumentationDepartment
  restarter/transient_contract count 
  restarter/auxiliary_state astring none
  restarter/contract count 112
  restarter/start_pid count 2027
  restarter/start_method_timestamp time 1238257605.483494000
  restarter/start_method_waitstatus integer 0
  restarter/logfile astring /var/svc/log/application-upnp-coherence:default.log
  restarter/next_state astring none
  restarter/state astring online
  restarter/state_timestamp time 1238260764.231741000
  restarter_actions/restart integer 
  restarter_actions/auxiliary_tty boolean true
  restarter_actions/auxiliary_fmri astring svc:/application/graphical-login/gdm:default
  restarter_actions/refresh integer

2) Check the log file of the coherence server in /var/coherence. It gives you good hints about plugins and other trouble which either keeps it from starting at all or at least why certain backends don't work.

3) If the service enters the maintenance state and you receive a "could not set context for method" error in the service log, make sure the service account has a home directory set. Note the attempt to change directories.

  [ Apr 28 21:55:26 Executing start method ("/lib/svc/method/coherence start"). ]
  svc.startd could not set context for method: chdir: No such file or directory
  [ Apr 28 21:55:26 Method "start" exited with status 96. ]

The solution is to add a sensible home directory to the service account:

  [jmccune@rain ~]$ pfexec usermod -d /var/coherence upnp

Feedback

I'd be glad for any feedback you have. If you see any error in this document or changes which are needed contact me at public@soft-gems.net.